@sanity-labs/slides 0.0.0

package/src/core/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Public surface of `react-pptx`. The high-frequency symbols a template
+ * author or MCP framework needs.
+ *
+ * Specialized internals (PPTX op-translator, fake-runtime model types, etc.)
+ * live behind sub-path imports (`react-pptx/op-translator-pptx`,
+ * `react-pptx/fake-runtime`, …) so tree-shaking stays clean.
+ */
+
+// Canvas + units
+export {
+  CANVAS_16_9,
+  CANVAS_4_3,
+  type Canvas,
+  type Emu,
+  type Pt,
+  type Rect,
+  ptToEmu,
+  inToEmu,
+} from './geometry.js';
+
+// Template contract
+export type { Template, TypographyToken } from './template.js';
+export { defineTemplate, defineTemplateComponent, type TemplateComponent } from './template.js';
+export { type FontStack } from './font-resolver.js';
+
+// Runtime op types
+export type {
+  ApplyOpsResult,
+  EmuRect,
+  HexColor,
+  ShapeKind,
+  ShapeProperties,
+  SlideOp,
+  SlidesRuntime,
+  TextRange,
+  TextStyle,
+  ParagraphStyle,
+} from './runtime.js';
+
+// JSX primitives a template's components build on
+export {
+  Slide,
+  Box,
+  Text,
+  Color,
+  Image,
+  type SlideProps,
+  type BoxProps,
+  type BoxFill,
+  type TextProps,
+  type ColorProps,
+  type ImageProps,
+  type ImageRef,
+} from './components.js';
+
+// Reconciler entry point
+export { renderToOps, ReconcilerError, type RenderToOpsInput } from './reconciler.js';
+
+// Manifest types
+export type { ArtifactRef, GenerationManifest, ReconcileResult, SlotId } from './manifest.js';
+
+// Runtimes
+export { FakeSlidesRuntime, type FakeDeck } from './fake-runtime.js';
+export {
+  PptxSlidesRuntime,
+  DEFAULT_PPTX_FONT_SUBSTITUTION,
+  type PptxSlidesRuntimeOptions,
+} from './pptx-runtime.js';

package/src/core/manifest.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'vitest';
+import { decodeAltText, encodeAltText, type SlotId } from './manifest.js';
+
+describe('encodeAltText / decodeAltText', () => {
+  test('round-trips a slot ID through the alt-text encoding', () => {
+    const slotId: SlotId = 'cover:title';
+    const encoded = encodeAltText(slotId);
+    expect(encoded).toBe('rgs-slot:cover:title');
+    expect(decodeAltText(encoded)).toBe(slotId);
+  });
+
+  test('returns undefined for an unmanaged alt-text caption', () => {
+    expect(decodeAltText('Picture of a sunrise')).toBeUndefined();
+    expect(decodeAltText('')).toBeUndefined();
+    expect(decodeAltText(null)).toBeUndefined();
+    expect(decodeAltText(undefined)).toBeUndefined();
+  });
+
+  test('rejects malformed payloads after the prefix', () => {
+    // Missing colon between component and slot.
+    expect(decodeAltText('rgs-slot:invalid')).toBeUndefined();
+    // Disallowed characters (spaces, capitals).
+    expect(decodeAltText('rgs-slot:Cover:Title')).toBeUndefined();
+    expect(decodeAltText('rgs-slot:cover :title')).toBeUndefined();
+    // Empty halves.
+    expect(decodeAltText('rgs-slot::title')).toBeUndefined();
+    expect(decodeAltText('rgs-slot:cover:')).toBeUndefined();
+  });
+
+  test('accepts hyphenated identifiers in both halves', () => {
+    expect(decodeAltText('rgs-slot:two-column:left-body')).toBe('two-column:left-body');
+  });
+});

package/src/core/manifest.ts

@@ -0,0 +1,150 @@
+/**
+ * The generation manifest — what the reconciler emits *alongside* the SlideOps.
+ *
+ * The manifest captures everything needed to:
+ *
+ * 1. Re-fill the deck later (`replaceAllText` against named slots, preserving
+ *    manual polish on the rest of the deck).
+ * 2. Audit which decks were AI-generated and from which template version.
+ * 3. Detect drift between resolved-at-generation-time brand artifacts
+ *    (textures, logos, master templates) and their current upstream state.
+ *
+ * Template-agnostic: any brand package reads it the same way; the substrate
+ * doesn't encode brand-specific slot keys.
+ */
+
+import type { SlideOp } from './runtime.js';
+
+/**
+ * A stable identity for a slot in a generated deck.
+ *
+ * Slot IDs are encoded into the Slides shape's *alt text* at generation time —
+ * the alt-text-as-ID pattern documented in `generation-model.md`. This is what
+ * makes in-place re-fill robust: when re-running with new data, we look up
+ * shapes by the alt-text token rather than by index/position (which can drift
+ * if the marketer moved or duplicated a shape).
+ *
+ * Format: `<componentName>:<slotName>` (colon-separated, both segments are
+ * `[a-z0-9-]+`). E.g., `cover:title`, `two-column:left-body`.
+ *
+ * Restricting the character set keeps the alt-text round-trippable across
+ * backends, some of which are picky about non-ASCII content.
+ */
+export type SlotId = `${string}:${string}`;
+
+/** The token we wrap a SlotId in when storing it as alt-text on a Slides shape. */
+const ALT_TEXT_PREFIX = 'rgs-slot:';
+
+/**
+ * Encode a SlotId into the alt-text representation written on a Slides shape.
+ *
+ * The wrapper prefix `rgs-slot:` is what `decodeAltText` keys off when reading
+ * an existing deck back. Anything else in the alt-text field — a marketer's
+ * accessibility caption, an empty string — is treated as "not a managed slot."
+ */
+export const encodeAltText = (slotId: SlotId): string => `${ALT_TEXT_PREFIX}${slotId}`;
+
+/**
+ * Decode a Slides shape's alt-text field back into a SlotId, or return
+ * `undefined` if the alt-text isn't a managed slot tag.
+ *
+ * Mirror of `encodeAltText`. Used at re-fill time to identify which shapes
+ * the system owns.
+ */
+export const decodeAltText = (altText: string | undefined | null): SlotId | undefined => {
+  if (typeof altText !== 'string') return undefined;
+  if (!altText.startsWith(ALT_TEXT_PREFIX)) return undefined;
+  const candidate = altText.slice(ALT_TEXT_PREFIX.length);
+  // Must look like `a:b` with both halves non-empty and matching the safe charset.
+  if (!/^[a-z0-9-]+:[a-z0-9-]+$/.test(candidate)) return undefined;
+  return candidate as SlotId;
+};
+
+/**
+ * The reconciler's record of where each slot landed in the emitted ops.
+ *
+ * Keys are SlotIds. Values reference the Slides object IDs (`shapeId` /
+ * `imageId`) the reconciler assigned at op-emission time. Re-fill resolves a
+ * SlotId → object ID via this map, then issues a `replaceAllText` op against
+ * that object.
+ */
+export type SlotRegistry = Readonly<Record<SlotId, string>>;
+
+/**
+ * A reference to a brand artifact (texture, logo, font, master template, image)
+ * the deck depends on at generation time.
+ *
+ * Recorded in the manifest so re-fill can detect 404s and (optionally)
+ * verify content integrity via `contentHash`. The substrate type doesn't
+ * fetch or validate — it just records what the brand resolver produced.
+ */
+export interface ArtifactRef {
+  /** What kind of artifact this is. Drives any artifact-type-specific re-fill behavior. */
+  readonly type: 'texture' | 'logo' | 'font' | 'master-template' | 'image';
+
+  /**
+   * Template-meaningful identifier, e.g., `"dots-grid-base-medium-dark"`. Stable
+   * across generations; the brand's resolver maps this to a current URL.
+   */
+  readonly identifier: string;
+
+  /** The URL the resolver produced for this artifact at generation time. */
+  readonly resolvedUrl: string;
+
+  /** ISO-8601 timestamp the resolution occurred. */
+  readonly resolvedAt: string;
+
+  /**
+   * Optional SHA-256 (or other) of the artifact bytes, hex-encoded.
+   *
+   * The reconciler does not compute or verify this; it's a forward-compat
+   * slot brands can populate when they want stricter integrity checks at
+   * re-fill time.
+   */
+  readonly contentHash?: string;
+}
+
+/**
+ * The full record the reconciler emits alongside its SlideOp stream.
+ *
+ * Persisted somewhere accessible at re-fill time. The persistence strategy
+ * is a runtime concern (each backend picks its own — file metadata, a
+ * sidecar JSON, embedded XML, etc.); this type just defines the shape.
+ */
+export interface GenerationManifest {
+  /** Schema version of the manifest itself. Bump on breaking changes to this shape. */
+  readonly manifestVersion: '1';
+
+  /** The substrate that produced this manifest. Locked literal for forward compat. */
+  readonly generatedBy: 'react-pptx';
+
+  /** ISO-8601 timestamp of generation. */
+  readonly generatedAt: string;
+
+  /** Name of the template whose components produced this deck (`template.name`). */
+  readonly templateName: string;
+
+  /** ID of the deck this manifest applies to. `null` if the deck wasn't created yet. */
+  readonly deckId: string | null;
+
+  /** Map of SlotId → Slides object ID, for re-fill lookups. */
+  readonly slots: SlotRegistry;
+
+  /** Template artifacts the deck depends on. See `ArtifactRef`. */
+  readonly artifacts: readonly ArtifactRef[];
+}
+
+/**
+ * The full output of a single `renderToOps` call.
+ *
+ * Carries both the op stream (what to send to the runtime) and the manifest
+ * (what to persist). They're emitted together because they're computed
+ * together — the slot map can't exist without the ops that created the
+ * shapes it points at.
+ */
+export interface ReconcileResult {
+  /** The op stream, in the order the reconciler emitted them. */
+  readonly ops: readonly SlideOp[];
+  /** The generation manifest. */
+  readonly manifest: GenerationManifest;
+}

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

@@ -0,0 +1,204 @@
+import { describe, expect, it, vi } from 'vitest';
+import { translateOpsToPptx, hexToPptxColor } from './op-translator-pptx.js';
+import { ptToEmu, EMU_PER_INCH } from './geometry.js';
+import type { SlideOp } from './runtime.js';
+
+describe('translateOpsToPptx', () => {
+  it('createSlide produces a slide entry; insertAt is preserved', () => {
+    const ops: SlideOp[] = [{ type: 'createSlide', slideId: 'slide_1', insertAt: 0 }];
+    const batch = translateOpsToPptx(ops);
+    expect(batch.slides).toEqual([{ slideId: 'slide_1', insertAt: 0 }]);
+    expect(batch.objects).toEqual([]);
+    expect(batch.createdObjectIds).toContain('slide_1');
+  });
+
+  it('createShape TEXT_BOX produces a text object with EMU rect converted to inches', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 'slide_1' },
+      {
+        type: 'createShape',
+        slideId: 'slide_1',
+        shapeId: 'shape_1',
+        shape: 'TEXT_BOX',
+        // 1 inch = 914400 EMU
+        rect: { x: EMU_PER_INCH, y: 2 * EMU_PER_INCH, w: 3 * EMU_PER_INCH, h: 4 * EMU_PER_INCH },
+      },
+    ];
+    const batch = translateOpsToPptx(ops);
+    expect(batch.objects).toHaveLength(1);
+    const obj = batch.objects[0];
+    expect(obj?.kind).toBe('text');
+    expect(obj?.position).toEqual({ x: 1, y: 2, w: 3, h: 4 });
+  });
+
+  it('createShape RECTANGLE produces a rectangle object', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'r1',
+        shape: 'RECTANGLE',
+        rect: { x: 0, y: 0, w: EMU_PER_INCH, h: EMU_PER_INCH },
+      },
+    ];
+    const batch = translateOpsToPptx(ops);
+    expect(batch.objects[0]?.kind).toBe('rectangle');
+  });
+
+  it('insertText sets text content on the matching object', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'shape_1',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: EMU_PER_INCH, h: EMU_PER_INCH },
+      },
+      { type: 'insertText', objectId: 'shape_1', text: 'hello world' },
+    ];
+    const batch = translateOpsToPptx(ops);
+    const obj = batch.objects[0];
+    expect(obj?.kind).toBe('text');
+    if (obj?.kind === 'text') {
+      expect(obj.text).toBe('hello world');
+    }
+  });
+
+  it('updateShapeProperties merges fillColor (strips leading #)', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'shape_1',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: EMU_PER_INCH, h: EMU_PER_INCH },
+      },
+      { type: 'updateShapeProperties', objectId: 'shape_1', properties: { fillColor: '#0b0b0b' } },
+    ];
+    const batch = translateOpsToPptx(ops);
+    const obj = batch.objects[0];
+    if (obj?.kind === 'text') {
+      expect(obj.fill).toBe('0B0B0B');
+    } else {
+      throw new Error('expected text object');
+    }
+  });
+
+  it('updateTextStyle applies font substitution (Waldenburg → Inter)', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'shape_1',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: ptToEmu(100), h: ptToEmu(50) },
+      },
+      { type: 'insertText', objectId: 'shape_1', text: 'hi' },
+      {
+        type: 'updateTextStyle',
+        objectId: 'shape_1',
+        range: { start: 0, end: 2 },
+        style: { fontFamily: 'Waldenburg', fontSize: 24 },
+      },
+    ];
+    const batch = translateOpsToPptx(ops, {
+      fontSubstitution: { Waldenburg: 'Inter' },
+      onUnknownFont: null,
+    });
+    const obj = batch.objects[0];
+    if (obj?.kind !== 'text') throw new Error('expected text object');
+    expect(obj.textSpans[0]?.style.fontFamily).toBe('Inter');
+    // Identity passthrough doesn't substitute and doesn't warn.
+    expect(obj.textSpans[0]?.style.fontSize).toBe(24);
+  });
+
+  it('updateTextStyle warns once per unknown font', () => {
+    const warn = vi.fn();
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'a',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: ptToEmu(10), h: ptToEmu(10) },
+      },
+      { type: 'insertText', objectId: 'a', text: 'x' },
+      {
+        type: 'updateTextStyle',
+        objectId: 'a',
+        range: { start: 0, end: 1 },
+        style: { fontFamily: 'Comic Sans' },
+      },
+      {
+        type: 'updateTextStyle',
+        objectId: 'a',
+        range: { start: 0, end: 1 },
+        style: { fontFamily: 'Comic Sans' },
+      },
+    ];
+    translateOpsToPptx(ops, { fontSubstitution: {}, onUnknownFont: warn });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith('Comic Sans');
+  });
+
+  it('createImage with altText emits an image object with both fields populated', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createImage',
+        slideId: 's',
+        imageId: 'img_1',
+        url: 'https://example.com/x.png',
+        rect: { x: 0, y: 0, w: EMU_PER_INCH, h: EMU_PER_INCH },
+        altText: 'rgs-slot:cover:hero',
+      },
+    ];
+    const batch = translateOpsToPptx(ops);
+    const obj = batch.objects[0];
+    expect(obj?.kind).toBe('image');
+    if (obj?.kind === 'image') {
+      expect(obj.url).toBe('https://example.com/x.png');
+      expect(obj.altText).toBe('rgs-slot:cover:hero');
+    }
+  });
+
+  it('updateParagraphStyle merges paragraph style on text object', () => {
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'a',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: EMU_PER_INCH, h: EMU_PER_INCH },
+      },
+      { type: 'insertText', objectId: 'a', text: 'x' },
+      {
+        type: 'updateParagraphStyle',
+        objectId: 'a',
+        range: { start: 0, end: 1 },
+        style: { alignment: 'CENTER', lineSpacing: 1.4 },
+      },
+    ];
+    const batch = translateOpsToPptx(ops);
+    const obj = batch.objects[0];
+    if (obj?.kind !== 'text') throw new Error('expected text');
+    expect(obj.paragraphStyle).toEqual({ alignment: 'CENTER', lineSpacing: 1.4 });
+  });
+});
+
+describe('hexToPptxColor', () => {
+  it('strips leading # and uppercases', () => {
+    expect(hexToPptxColor('#ff5500')).toBe('FF5500');
+    expect(hexToPptxColor('#0b0b0b')).toBe('0B0B0B');
+  });
+
+  it('passes through bare hex', () => {
+    expect(hexToPptxColor('FF5500' as `#${string}`)).toBe('FF5500');
+  });
+});