@sanity-labs/slides 0.0.0

package/src/core/runtime.ts

@@ -0,0 +1,150 @@
+/**
+ * The seam between the reconciler and the slide runtime backend.
+ *
+ * Production wires `PptxSlidesRuntime` into the reconciler. Tests wire
+ * `FakeSlidesRuntime` which records every operation and builds an in-memory
+ * deck model.
+ *
+ * See `docs/testing-strategy.md` for the rationale.
+ */
+
+import type { Emu } from './geometry.js';
+import type { GenerationManifest } from './manifest.js';
+
+/**
+ * A typed Slides API operation the reconciler emits.
+ *
+ * This is intentionally NOT a 1:1 mapping of any specific slide API — it's
+ * the *intent* the reconciler emits, with EMU and IDs already resolved. The
+ * runtime adapter turns these into backend-specific operations.
+ *
+ * Keeping ops at this layer (vs raw API requests) means:
+ * 1. Goldens read clearly. `{ type: "createShape", ... }` beats a 50-line nested object.
+ * 2. The API can evolve underneath without churning every test snapshot.
+ * 3. Template-agnostic; nothing here is Sanity-specific.
+ */
+export type SlideOp =
+  | { type: 'createSlide'; slideId: string; insertAt?: number }
+  | { type: 'createShape'; slideId: string; shapeId: string; shape: ShapeKind; rect: EmuRect }
+  | { type: 'insertText'; objectId: string; text: string }
+  | { type: 'updateTextStyle'; objectId: string; range: TextRange; style: TextStyle }
+  | { type: 'updateParagraphStyle'; objectId: string; range: TextRange; style: ParagraphStyle }
+  | {
+      type: 'createImage';
+      slideId: string;
+      imageId: string;
+      url: string;
+      rect: EmuRect;
+      altText?: string;
+    }
+  | { type: 'updateShapeProperties'; objectId: string; properties: ShapeProperties };
+
+/** A rectangle in EMU — the reconciler converts pt → EMU before emitting. */
+export interface EmuRect {
+  x: Emu;
+  y: Emu;
+  w: Emu;
+  h: Emu;
+}
+
+/**
+ * Shape kinds the reconciler emits. Names mirror the Office Open XML /
+ * Google Slides API enum so translators on either side can pass through
+ * without a lookup table.
+ */
+export type ShapeKind = 'TEXT_BOX' | 'RECTANGLE' | 'ELLIPSE' | 'LINE';
+
+/** Inclusive-exclusive index range over a string of text. */
+export interface TextRange {
+  start: number;
+  end: number;
+}
+
+/**
+ * A font role keyword. Resolved against `Template.fonts[role][0]` at the
+ * reconciler boundary; the role keywords (`'display'` / `'body'` / `'mono'`)
+ * are reserved — a brand cannot have a literal font family named "display."
+ *
+ * See `reconciler.ts` for resolution semantics; the role keywords mirror
+ * `FontStack` keys so adding a role to one ripples to the other.
+ */
+export type FontRole = 'display' | 'body' | 'mono';
+
+/** Text-style properties supported at the reconciler boundary. */
+export interface TextStyle {
+  /**
+   * Font family. Either:
+   * - A role keyword (`'display'` / `'body'` / `'mono'`), resolved against
+   *   `Template.fonts[role][0]` at the reconciler boundary before the op is
+   *   emitted. This is what brand components and `<Text/>` consumers
+   *   should pass — it keeps the brand's font choice load-bearing.
+   * - A literal family name (e.g., `'Geist'`, `'Inter'`), passed through
+   *   verbatim. Template authors with a specific family in mind use this.
+   *
+   * The role keywords are reserved — they shadow any literal family of the
+   * same name. If a future brand needed a literal `'display'` family, the
+   * shape would need to migrate to a discriminated union.
+   *
+   * Why a string union (vs. discriminated): the role keywords are vanishingly
+   * unlikely to ever be a real family; a discriminated union would force every
+   * literal-family consumer to write `{ kind: 'family', family: ... }` for no
+   * win. `flatten-for-brand.ts:inferFontRole` returns role strings directly,
+   * which compose cleanly into this shape.
+   */
+  fontFamily?: FontRole | string;
+  fontSize?: number; // pt — passes straight through, NOT converted to EMU
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  foregroundColor?: HexColor;
+  backgroundColor?: HexColor;
+}
+
+/** Paragraph-style properties supported at the reconciler boundary. */
+export interface ParagraphStyle {
+  alignment?: 'START' | 'CENTER' | 'END' | 'JUSTIFIED';
+  lineSpacing?: number; // multiplier (e.g., 1.2)
+  spaceAbove?: number; // pt
+  spaceBelow?: number; // pt
+}
+
+/** Shape-level visual properties. */
+export interface ShapeProperties {
+  fillColor?: HexColor;
+  outlineColor?: HexColor;
+  outlineWeight?: number; // pt
+}
+
+/** A 24-bit hex color, e.g., "#FF5500". The reconciler converts to RGB at emit. */
+export type HexColor = `#${string}`;
+
+/**
+ * The runtime contract every slide backend satisfies. This is the seam that
+ * makes layered testing work — see `docs/testing-strategy.md`.
+ */
+export interface SlidesRuntime {
+  /** Apply a sequence of slide operations to a deck. */
+  applyOps(deckId: string, ops: readonly SlideOp[]): Promise<ApplyOpsResult>;
+
+  /**
+   * Create a new deck, optionally seeded from a template reference.
+   *
+   * `masterRef` is opaque to the substrate; runtimes that don't have a
+   * master-template concept ignore it and initialize a blank deck.
+   */
+  createDeckFromMaster(masterRef: string, title: string): Promise<{ deckId: string }>;
+
+  /** Write the deck to a file on disk. Returns the absolute path. */
+  write(deckId: string): Promise<{ filePath: string }>;
+
+  /** Attach a manifest to a deck (for later retrieval). */
+  attachManifest(deckId: string, manifest: GenerationManifest): void;
+}
+
+/** What the runtime returns after applying a batch of ops. */
+export interface ApplyOpsResult {
+  /** IDs of objects created during this batch, keyed by the requested ID. */
+  createdObjectIds: Readonly<Record<string, string>>;
+  /** Revision token for optimistic-concurrency on the next call. */
+  revisionId?: string;
+}

package/src/core/template.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from 'vitest';
+import { z } from 'zod';
+import type { Template, TemplateComponent } from './template.js';
+import { defineTemplateComponent } from './template.js';
+import { CANVAS_16_9 } from './geometry.js';
+
+// A minimal valid brand for typing-level smoke tests. Real brands live downstream.
+const TestBrand: Template = {
+  name: 'test',
+  canvas: CANVAS_16_9,
+  fonts: {
+    display: ['Inter', 'Arial'],
+    body: ['Inter', 'Arial'],
+    mono: ['Courier New'],
+  },
+  colors: {
+    'fg.base': '#0b0b0b',
+    'bg.surface': '#ffffff',
+  },
+  typography: {
+    'body-md': { fontFamily: 'body', fontSize: 18, lineHeight: 1.5 },
+  },
+  spacing: {
+    sm: 8,
+    md: 12,
+    lg: 24,
+  },
+  components: {
+    Cover: {
+      component: () => null,
+      schema: z.object({ title: z.string() }).strict(),
+      description: 'Use as the first slide. Sets title and stance for the deck.',
+    } satisfies TemplateComponent<{ title: string }>,
+  },
+};
+
+describe('Template interface', () => {
+  test('a minimal brand satisfies the type', () => {
+    expect(TestBrand.name).toBe('test');
+    expect(TestBrand.canvas.w).toBe(960);
+    expect(Object.keys(TestBrand.components)).toEqual(['Cover']);
+  });
+
+  test('component schemas are strict', () => {
+    const cover = TestBrand.components['Cover'];
+    expect(cover).toBeDefined();
+    if (!cover) return;
+    expect(() => cover.schema.parse({ title: 'Hello' })).not.toThrow();
+    // .strict() rejects unknown keys
+    expect(() => cover.schema.parse({ title: 'Hello', extra: true })).toThrow();
+  });
+
+  test('token surfaces are populated and queryable', () => {
+    expect(TestBrand.colors['fg.base']).toBe('#0b0b0b');
+    expect(TestBrand.typography['body-md']?.fontSize).toBe(18);
+    expect(TestBrand.spacing['md']).toBe(12);
+  });
+
+  test('typography tokens reference font roles, not concrete font names', () => {
+    // The brand's typography references font *roles* (display/body/mono) which
+    // are resolved against `fonts` at runtime — see font-resolver. This means
+    // a token like body-md doesn't bake "Inter" into typography; it says
+    // "whatever the body font resolves to."
+    const token = TestBrand.typography['body-md'];
+    expect(token).toBeDefined();
+    if (!token) return;
+    expect(['display', 'body', 'mono']).toContain(token.fontFamily);
+  });
+});
+
+describe('defineTemplateComponent', () => {
+  const CoverSchema = z.object({ title: z.string() }).strict();
+  const TwoColumnSchema = z.object({ left: z.string(), right: z.string() }).strict();
+
+  const CoverComponent = (_props: { title: string }) => null;
+  const TwoColumnComponent = (_props: { left: string; right: string }) => null;
+
+  test('returns its input unchanged at runtime (identity)', () => {
+    const spec: TemplateComponent<{ title: string }> = {
+      component: CoverComponent,
+      schema: CoverSchema,
+      description: 'Use as the first slide. Sets title and stance.',
+    };
+    const result = defineTemplateComponent(spec);
+    expect(result).toBe(spec);
+  });
+
+  test('preserves component and schema fields', () => {
+    const spec = defineTemplateComponent({
+      component: CoverComponent,
+      schema: CoverSchema,
+      description: 'Use as the first slide.',
+    });
+    expect(spec.component).toBe(CoverComponent);
+    expect(spec.schema).toBe(CoverSchema);
+    expect(spec.description).toBe('Use as the first slide.');
+  });
+
+  test('schema validation still works on the returned component', () => {
+    const spec = defineTemplateComponent({
+      component: CoverComponent,
+      schema: CoverSchema,
+      description: 'Use as the first slide.',
+    });
+    expect(() => spec.schema.parse({ title: 'Hello' })).not.toThrow();
+    expect(() => spec.schema.parse({ title: 'Hello', extra: true })).toThrow();
+  });
+
+  test('two helper-returned components compose into Template.components without casts', () => {
+    // Compile-time test: if TypeScript accepts this without `as` casts,
+    // the variance erasure is working correctly.
+    const Cover = defineTemplateComponent({
+      component: CoverComponent,
+      schema: CoverSchema,
+      description: 'Use as the first slide. Sets title and stance.',
+    });
+    const TwoColumn = defineTemplateComponent({
+      component: TwoColumnComponent,
+      schema: TwoColumnSchema,
+      description: 'Use to compare two parallel ideas of equal weight.',
+    });
+
+    // No `as unknown as TemplateComponent` casts needed — this is the fix.
+    const brand: Template = {
+      name: 'test-brand',
+      canvas: CANVAS_16_9,
+      fonts: { display: ['Inter'], body: ['Inter'], mono: ['Courier New'] },
+      colors: { 'fg.base': '#0b0b0b' },
+      typography: {},
+      spacing: {},
+      components: { Cover, TwoColumn },
+    };
+
+    expect(Object.keys(brand.components)).toEqual(['Cover', 'TwoColumn']);
+  });
+});

package/src/core/template.ts

@@ -0,0 +1,37 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { z } from 'zod';
+import type { FontStack } from './font-resolver.js';
+import type { Canvas, Pt } from './geometry.js';
+import type { HexColor } from './runtime.js';
+
+export interface TemplateComponent<P = unknown> {
+  component: ComponentType<P>;
+  schema: z.ZodObject<z.ZodRawShape>;
+  masterRef?: string;
+  description: string;
+}
+
+export const defineTemplateComponent = <P>(spec: TemplateComponent<P>): TemplateComponent =>
+  spec as TemplateComponent;
+
+export interface TypographyToken {
+  fontFamily: 'display' | 'body' | 'mono';
+  fontSize: Pt;
+  lineHeight: number;
+  letterSpacing?: number;
+  fontWeight?: number;
+  textTransform?: 'none' | 'uppercase' | 'lowercase';
+}
+
+export interface Template {
+  readonly name: string;
+  readonly canvas: Canvas;
+  readonly fonts: FontStack;
+  readonly colors: Readonly<Record<string, HexColor>>;
+  readonly typography: Readonly<Record<string, TypographyToken>>;
+  readonly spacing: Readonly<Record<string, Pt>>;
+  readonly components: Readonly<Record<string, TemplateComponent>>;
+  readonly preview?: () => ReactNode;
+}
+
+export const defineTemplate = (template: Template): Template => template;

package/src/dev/auto-examples.ts

@@ -0,0 +1,89 @@
+import { Fragment, createElement, type ReactNode } from 'react';
+import type { z } from 'zod';
+import type { Template, TemplateComponent } from '../core/template.js';
+
+export const deriveAutoPreview = (template: Template): ReactNode => {
+  const entries = Object.entries(template.components);
+  if (entries.length === 0) return null;
+  return createElement(
+    Fragment,
+    null,
+    ...entries.map(([name, tc]) => createElement(Fragment, { key: name }, renderSample(tc, name))),
+  );
+};
+
+const renderSample = (tc: TemplateComponent, name: string): ReactNode => {
+  const props = sampleProps(tc.schema, name);
+  return createElement(tc.component as (p: unknown) => ReactNode, props);
+};
+export const sampleProps = (schema: z.ZodTypeAny, contextName: string): Record<string, unknown> => {
+  const value = sample(schema, contextName);
+  return (value && typeof value === 'object' ? (value as Record<string, unknown>) : {}) ?? {};
+};
+
+const sample = (schema: z.ZodTypeAny, ctx: string): unknown => {
+  const def = (schema as unknown as { _def: { typeName: string } })._def;
+  switch (def.typeName) {
+    case 'ZodObject':
+      return sampleObject(schema as z.ZodObject<z.ZodRawShape>, ctx);
+    case 'ZodString':
+      return sampleString(schema, ctx);
+    case 'ZodNumber':
+      return 1;
+    case 'ZodBoolean':
+      return false;
+    case 'ZodEnum':
+    case 'ZodNativeEnum': {
+      const values = (def as unknown as { values: unknown }).values;
+      const arr = Array.isArray(values) ? values : Object.values(values as object);
+      return arr[0];
+    }
+    case 'ZodLiteral':
+      return (def as unknown as { value: unknown }).value;
+    case 'ZodUnion':
+    case 'ZodDiscriminatedUnion': {
+      const options = (def as unknown as { options: z.ZodTypeAny[] }).options;
+      return options.length > 0 && options[0] ? sample(options[0], ctx) : undefined;
+    }
+    case 'ZodArray': {
+      const item = (def as unknown as { type: z.ZodTypeAny }).type;
+      return [sample(item, ctx), sample(item, ctx)];
+    }
+    case 'ZodOptional':
+    case 'ZodNullable':
+    case 'ZodDefault': {
+      const inner = (def as unknown as { innerType: z.ZodTypeAny }).innerType;
+      return sample(inner, ctx);
+    }
+    case 'ZodEffects': {
+      const inner = (def as unknown as { schema: z.ZodTypeAny }).schema;
+      return sample(inner, ctx);
+    }
+    default:
+      return undefined;
+  }
+};
+
+const sampleObject = (schema: z.ZodObject<z.ZodRawShape>, ctx: string): Record<string, unknown> => {
+  const shape = schema.shape;
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(shape)) {
+    if (isOptional(child)) continue;
+    out[key] = sample(child, `${ctx}.${key}`);
+  }
+  return out;
+};
+
+const isOptional = (schema: z.ZodTypeAny): boolean => {
+  const name = (schema as unknown as { _def: { typeName: string } })._def.typeName;
+  return name === 'ZodOptional' || name === 'ZodDefault' || name === 'ZodNullable';
+};
+
+const sampleString = (schema: z.ZodTypeAny, ctx: string): string => {
+  const checks =
+    (schema as unknown as { _def: { checks?: Array<{ kind: string; value?: number }> } })._def
+      .checks ?? [];
+  const min = checks.find((c) => c.kind === 'min')?.value ?? 0;
+  const sample = `Sample ${ctx.split('.').pop() ?? 'value'}`;
+  return sample.length >= min ? sample : sample.padEnd(min, '.');
+};

package/src/dev/bin/slides-dev.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const tsxLoader = require.resolve('tsx/esm');
+const entry = resolve(here, 'slides-dev.ts');
+
+const child = spawn(
+  process.execPath,
+  ['--import', `file://${tsxLoader}`, entry, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+
+child.on('exit', (code) => process.exit(code ?? 1));
+child.on('error', (err) => {
+  process.stderr.write(`slides-dev shim failed: ${err.message}\n`);
+  process.exit(1);
+});

package/src/dev/bin/slides-dev.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import { realpathSync } from 'node:fs';
+import { basename } from 'node:path';
+import pc from 'picocolors';
+import { startDevServer } from '../dev-server/start.js';
+import { formatBanner, formatReady, formatStartupError } from '../dev-server/output.js';
+
+const USAGE = `${pc.bold('Usage:')} slides-dev [options]
+
+${pc.bold('Options:')}
+  --port <n>       Dev server port. Default: 5173.
+  --host <h>       Dev server host. Default: localhost.
+                   Pass --host with no value to expose on the network.
+  -h, --help       Show this help.
+
+Run from your template package directory.
+`;
+
+type ParsedFlags = {
+  port?: number;
+  host?: string;
+  exposed: boolean;
+};
+
+const parseFlags = (argv: readonly string[]): ParsedFlags => {
+  const out: ParsedFlags = { exposed: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    if (arg === '--port') {
+      const v = argv[++i];
+      if (!v) throw new Error('Missing value for --port');
+      out.port = Number.parseInt(v, 10);
+      continue;
+    }
+    if (arg === '--host') {
+      const v = argv[i + 1];
+      if (v && !v.startsWith('--')) {
+        out.host = v;
+        i++;
+      } else {
+        out.host = '0.0.0.0';
+      }
+      out.exposed = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return out;
+};
+
+const main = async (): Promise<void> => {
+  const flags = parseFlags(process.argv.slice(2));
+  const handle = await startDevServer({
+    cwd: process.cwd(),
+    ...(flags.port !== undefined ? { port: flags.port } : {}),
+    ...(flags.host !== undefined ? { host: flags.host } : {}),
+  });
+
+  const templateName = inferTemplateName(handle.templatePath);
+  process.stdout.write(formatBanner(templateName, handle.startedInMs));
+  process.stdout.write(
+    formatReady({
+      url: handle.url,
+      templatePath: handle.templatePath,
+      host: flags.exposed,
+    }),
+  );
+  process.stdout.write('\n');
+
+  const shutdown = async () => {
+    await handle.server.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+};
+
+const findPackageDirName = (templatePath: string): string | undefined => {
+  const parts = templatePath.split('/').filter(Boolean);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (parts[i] === 'src' && i > 0) return parts[i - 1];
+  }
+  return undefined;
+};
+
+const inferTemplateName = (templatePath: string): string =>
+  findPackageDirName(templatePath) ?? basename(templatePath, '.ts');
+
+const argvPath = process.argv[1];
+const isEntrypoint = argvPath !== undefined && import.meta.filename === realpathSync(argvPath);
+if (isEntrypoint) {
+  main().catch((err: unknown) => {
+    process.stderr.write(formatStartupError(err));
+    process.exit(1);
+  });
+}

package/src/dev/compose-deck.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'vitest';
+import { createElement, Fragment, type ReactElement } from 'react';
+import { Slide, Box, Text } from '../core/components.js';
+import { CANVAS_16_9 } from '../core/geometry.js';
+import type { Template } from '../core/template.js';
+import { composeDeck } from './compose-deck.js';
+
+const STUB_TEMPLATE: Template = {
+  name: 'stub',
+  canvas: CANVAS_16_9,
+  fonts: { display: ['Inter'], body: ['Inter'], mono: ['Courier'] },
+  colors: {},
+  typography: {},
+  spacing: {},
+  components: {},
+};
+
+const TwoSlideDeck = (): ReactElement =>
+  createElement(
+    Fragment,
+    null,
+    createElement(
+      Slide,
+      { key: 'a' },
+      createElement(
+        Box,
+        { rect: { x: 0, y: 0, w: 200, h: 50 } },
+        createElement(Text, null, 'Hello'),
+      ),
+    ),
+    createElement(
+      Slide,
+      { key: 'b' },
+      createElement(
+        Box,
+        { rect: { x: 0, y: 0, w: 200, h: 50 } },
+        createElement(Text, null, 'World'),
+      ),
+    ),
+  );
+
+describe('composeDeck', () => {
+  test('compiles a multi-slide JSX tree into a FakeDeck the viewer can render', async () => {
+    const result = await composeDeck({
+      tree: createElement(TwoSlideDeck),
+      template: STUB_TEMPLATE,
+    });
+
+    expect(result.deck.slideOrder).toHaveLength(2);
+
+    const shapeTexts = [...result.deck.shapes.values()]
+      .map((s) => s.text)
+      .filter((t) => t.length > 0);
+    expect(shapeTexts).toEqual(['Hello', 'World']);
+
+    expect(result.manifest.deckId).toBe('dev-deck');
+    expect(result.manifest.templateName).toBe('stub');
+  });
+
+  test('honours the pinned timestamp for deterministic manifests', async () => {
+    const result = await composeDeck({
+      tree: createElement(Slide),
+      template: STUB_TEMPLATE,
+      now: () => '2026-01-01T00:00:00.000Z',
+    });
+    expect(result.manifest.generatedAt).toBe('2026-01-01T00:00:00.000Z');
+  });
+});

package/src/dev/compose-deck.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+import { renderToOps } from '../core/reconciler.js';
+import { FakeSlidesRuntime, type FakeDeck } from '../core/fake-runtime.js';
+import type { GenerationManifest } from '../core/manifest.js';
+import type { SlideOp } from '../core/runtime.js';
+import type { Template } from '../core/template.js';
+
+export type ComposeDeckInput = {
+  readonly tree: ReactNode;
+  readonly template: Template;
+  readonly title?: string;
+  readonly now?: () => string;
+};
+
+export type ComposedDeck = {
+  readonly deck: FakeDeck;
+  readonly ops: readonly SlideOp[];
+  readonly manifest: GenerationManifest;
+};
+
+const DECK_ID = 'dev-deck';
+
+export const composeDeck = async (input: ComposeDeckInput): Promise<ComposedDeck> => {
+  const runtime = new FakeSlidesRuntime({ fixedDeckId: DECK_ID });
+  await runtime.createDeckFromMaster(input.template.name, input.title ?? 'Dev deck');
+
+  const reconciled = renderToOps({
+    tree: input.tree,
+    template: input.template,
+    deckId: DECK_ID,
+    ...(input.now ? { now: input.now } : {}),
+  });
+
+  await runtime.applyOps(DECK_ID, reconciled.ops);
+
+  const deck = runtime.getDeck(DECK_ID);
+  if (!deck) throw new Error('composeDeck: FakeSlidesRuntime lost track of the dev deck.');
+
+  return { deck, ops: reconciled.ops, manifest: reconciled.manifest };
+};