@pep/term-deck 1.0.10

package/src/schemas/__tests__/validation.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect } from 'bun:test'
+import { z, ZodError } from 'zod'
+import { ValidationError, formatZodError, safeParse } from '../validation'
+
+describe('ValidationError', () => {
+  it('extends Error', () => {
+    const error = new ValidationError('test message')
+    expect(error).toBeInstanceOf(Error)
+  })
+
+  it('has name "ValidationError"', () => {
+    const error = new ValidationError('test message')
+    expect(error.name).toBe('ValidationError')
+  })
+
+  it('stores the message', () => {
+    const error = new ValidationError('Something went wrong')
+    expect(error.message).toBe('Something went wrong')
+  })
+
+  it('can be caught as Error', () => {
+    let caught: Error | null = null
+    try {
+      throw new ValidationError('test')
+    } catch (e) {
+      if (e instanceof Error) {
+        caught = e
+      }
+    }
+    expect(caught).not.toBeNull()
+    expect(caught?.name).toBe('ValidationError')
+  })
+
+  it('can be identified by instanceof', () => {
+    const error = new ValidationError('test')
+    expect(error instanceof ValidationError).toBe(true)
+    expect(error instanceof Error).toBe(true)
+  })
+})
+
+describe('formatZodError', () => {
+  it('formats single field error with path', () => {
+    const schema = z.object({
+      name: z.string().min(1, { message: 'Name is required' }),
+    })
+    const result = schema.safeParse({ name: '' })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'config')
+      expect(formatted).toBe('Invalid config:\n  - name: Name is required')
+    }
+  })
+
+  it('formats nested field error with dotted path', () => {
+    const schema = z.object({
+      colors: z.object({
+        primary: z.string().regex(/^#[0-9a-fA-F]{6}$/, {
+          message: 'Must be a valid hex color',
+        }),
+      }),
+    })
+    const result = schema.safeParse({ colors: { primary: 'red' } })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'theme')
+      expect(formatted).toBe('Invalid theme:\n  - colors.primary: Must be a valid hex color')
+    }
+  })
+
+  it('formats multiple errors', () => {
+    const schema = z.object({
+      name: z.string().min(1, { message: 'Name is required' }),
+      age: z.number().min(0, { message: 'Age must be positive' }),
+    })
+    const result = schema.safeParse({ name: '', age: -1 })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'person')
+      expect(formatted).toContain('Invalid person:')
+      expect(formatted).toContain('name: Name is required')
+      expect(formatted).toContain('age: Age must be positive')
+    }
+  })
+
+  it('formats error without path (root level)', () => {
+    const schema = z.string().min(1, { message: 'Value is required' })
+    const result = schema.safeParse('')
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'input')
+      expect(formatted).toBe('Invalid input:\n  - Value is required')
+    }
+  })
+
+  it('formats deeply nested paths', () => {
+    const schema = z.object({
+      settings: z.object({
+        display: z.object({
+          theme: z.object({
+            color: z.string().min(1, { message: 'Color is required' }),
+          }),
+        }),
+      }),
+    })
+    const result = schema.safeParse({
+      settings: { display: { theme: { color: '' } } },
+    })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'config')
+      expect(formatted).toContain('settings.display.theme.color: Color is required')
+    }
+  })
+
+  it('formats array index in path', () => {
+    const schema = z.object({
+      items: z.array(z.string().min(1, { message: 'Item cannot be empty' })),
+    })
+    const result = schema.safeParse({ items: ['valid', ''] })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'list')
+      expect(formatted).toContain('items.1: Item cannot be empty')
+    }
+  })
+
+  it('includes context in error message', () => {
+    const schema = z.object({ name: z.string() })
+    const result = schema.safeParse({ name: 123 })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      const formatted = formatZodError(result.error, 'slide frontmatter')
+      expect(formatted).toStartWith('Invalid slide frontmatter:')
+    }
+  })
+})
+
+describe('safeParse', () => {
+  it('returns parsed data for valid input', () => {
+    const schema = z.object({
+      name: z.string(),
+      count: z.number().default(0),
+    })
+    const result = safeParse(schema, { name: 'test' }, 'config')
+    expect(result).toEqual({ name: 'test', count: 0 })
+  })
+
+  it('applies schema defaults', () => {
+    const schema = z.object({
+      enabled: z.boolean().default(true),
+      value: z.number().default(42),
+    })
+    const result = safeParse(schema, {}, 'settings')
+    expect(result).toEqual({ enabled: true, value: 42 })
+  })
+
+  it('throws ValidationError for invalid input', () => {
+    const schema = z.object({
+      name: z.string().min(1),
+    })
+    expect(() => safeParse(schema, { name: '' }, 'config')).toThrow(ValidationError)
+  })
+
+  it('thrown error contains formatted message', () => {
+    const schema = z.object({
+      email: z.string().email({ message: 'Invalid email format' }),
+    })
+    try {
+      safeParse(schema, { email: 'not-an-email' }, 'user')
+      expect(true).toBe(false) // Should not reach here
+    } catch (e) {
+      expect(e).toBeInstanceOf(ValidationError)
+      if (e instanceof ValidationError) {
+        expect(e.message).toContain('Invalid user:')
+        expect(e.message).toContain('email: Invalid email format')
+      }
+    }
+  })
+
+  it('thrown error has name ValidationError', () => {
+    const schema = z.number()
+    try {
+      safeParse(schema, 'not a number', 'value')
+      expect(true).toBe(false) // Should not reach here
+    } catch (e) {
+      expect(e).toBeInstanceOf(ValidationError)
+      if (e instanceof ValidationError) {
+        expect(e.name).toBe('ValidationError')
+      }
+    }
+  })
+
+  it('works with complex schemas', () => {
+    const schema = z.object({
+      name: z.string().min(1),
+      colors: z.object({
+        primary: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+        accent: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+      }),
+      settings: z.object({
+        enabled: z.boolean().default(false),
+      }).optional(),
+    })
+
+    const validData = {
+      name: 'test',
+      colors: {
+        primary: '#ff0066',
+        accent: '#00ff66',
+      },
+    }
+
+    const result = safeParse(schema, validData, 'theme')
+    expect(result.name).toBe('test')
+    expect(result.colors.primary).toBe('#ff0066')
+    expect(result.settings).toBeUndefined()
+  })
+
+  it('preserves type inference', () => {
+    const schema = z.object({
+      count: z.number(),
+      name: z.string(),
+      items: z.array(z.string()),
+    })
+    const result = safeParse(schema, { count: 5, name: 'test', items: ['a', 'b'] }, 'data')
+
+    // Type inference test - these should compile without errors
+    const count: number = result.count
+    const name: string = result.name
+    const items: string[] = result.items
+
+    expect(count).toBe(5)
+    expect(name).toBe('test')
+    expect(items).toEqual(['a', 'b'])
+  })
+
+  it('handles union types', () => {
+    const schema = z.object({
+      value: z.union([z.string(), z.array(z.string())]),
+    })
+
+    const stringResult = safeParse(schema, { value: 'hello' }, 'config')
+    expect(stringResult.value).toBe('hello')
+
+    const arrayResult = safeParse(schema, { value: ['a', 'b'] }, 'config')
+    expect(arrayResult.value).toEqual(['a', 'b'])
+  })
+
+  it('rejects invalid union types with clear error', () => {
+    const schema = z.object({
+      value: z.union([z.string(), z.number()]),
+    })
+
+    expect(() => safeParse(schema, { value: [] }, 'config')).toThrow(ValidationError)
+  })
+})

package/src/schemas/config.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod'
+import { ThemeSchema } from './theme'
+
+/**
+ * Schema for presentation settings.
+ * Controls how the presentation behaves during runtime.
+ */
+export const SettingsSchema = z.object({
+  // Start slide (0-indexed)
+  startSlide: z.number().min(0).default(0),
+  // Loop back to first slide after last
+  loop: z.boolean().default(false),
+  // Auto-advance slides (ms, 0 = disabled)
+  autoAdvance: z.number().min(0).default(0),
+  // Show slide numbers
+  showSlideNumbers: z.boolean().default(false),
+  // Show progress bar
+  showProgress: z.boolean().default(false),
+})
+
+export type Settings = z.infer<typeof SettingsSchema>
+
+/**
+ * Schema for export settings.
+ * Controls the output dimensions and quality of exported videos/GIFs.
+ */
+export const ExportSettingsSchema = z.object({
+  // Output width in characters (min 80, max 400)
+  width: z.number().min(80).max(400).default(120),
+  // Output height in characters (min 24, max 100)
+  height: z.number().min(24).max(100).default(40),
+  // Frames per second for video (min 10, max 60)
+  fps: z.number().min(10).max(60).default(30),
+})
+
+export type ExportSettings = z.infer<typeof ExportSettingsSchema>
+
+/**
+ * Schema for validating deck configuration (deck.config.ts).
+ * Defines the complete configuration for a presentation deck.
+ */
+export const DeckConfigSchema = z.object({
+  // Presentation metadata
+  title: z.string().optional(),
+  author: z.string().optional(),
+  date: z.string().optional(),
+
+  // Theme (already validated Theme object)
+  theme: ThemeSchema,
+
+  // Presentation settings
+  settings: SettingsSchema.optional(),
+
+  // Export settings
+  export: ExportSettingsSchema.optional(),
+})
+
+export type DeckConfig = z.infer<typeof DeckConfigSchema>

package/src/schemas/slide.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod'
+
+/**
+ * Schema for validating slide frontmatter.
+ * Defines the metadata for a single slide.
+ */
+export const SlideFrontmatterSchema = z.object({
+  // Required: window title
+  title: z.string().min(1, {
+    message: 'Slide must have a title',
+  }),
+
+  // ASCII art text (figlet) - can be a single line or multiple lines
+  bigText: z.union([
+    z.string(),
+    z.array(z.string()),
+  ]).optional(),
+
+  // Which gradient to use for bigText
+  gradient: z.string().optional(),
+
+  // Override theme for this slide
+  theme: z.string().optional(),
+
+  // Transition effect
+  transition: z.enum([
+    'glitch',      // Default: glitch reveal line by line
+    'fade',        // Fade in
+    'instant',     // No animation
+    'typewriter',  // Character by character
+  ]).default('glitch'),
+
+  // Custom metadata (ignored by renderer, useful for tooling)
+  meta: z.record(z.string(), z.unknown()).optional(),
+})
+
+export type SlideFrontmatter = z.infer<typeof SlideFrontmatterSchema>
+
+/**
+ * Schema for a complete slide after parsing.
+ * Includes the parsed frontmatter, body content, optional notes, and metadata.
+ */
+export const SlideSchema = z.object({
+  // Parsed frontmatter
+  frontmatter: SlideFrontmatterSchema,
+  // Markdown body content
+  body: z.string(),
+  // Presenter notes (extracted from <!-- notes --> block)
+  notes: z.string().optional(),
+  // Source file path
+  sourcePath: z.string(),
+  // Slide index in deck (0-indexed)
+  index: z.number(),
+})
+
+export type Slide = z.infer<typeof SlideSchema>

package/src/schemas/theme.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod'
+
+/**
+ * Schema for validating hex color strings.
+ * Accepts 6-digit hex colors with # prefix (e.g., #ff0066)
+ */
+export const HexColorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/, {
+  message: 'Color must be a valid hex color (e.g., #ff0066)',
+})
+
+export type HexColor = z.infer<typeof HexColorSchema>
+
+/**
+ * Schema for validating gradient color arrays.
+ * A gradient requires at least 2 hex colors.
+ */
+export const GradientSchema = z.array(HexColorSchema).min(2, {
+  message: 'Gradient must have at least 2 colors',
+})
+
+export type Gradient = z.infer<typeof GradientSchema>
+
+/**
+ * Schema for validating theme objects.
+ * Defines the visual appearance of the presentation deck.
+ */
+export const ThemeSchema = z.object({
+  // Theme metadata
+  name: z.string().min(1, { message: 'Theme name is required' }),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  version: z.string().optional(),
+
+  // Color palette
+  colors: z.object({
+    primary: HexColorSchema,
+    secondary: HexColorSchema.optional(),
+    accent: HexColorSchema,
+    background: HexColorSchema,
+    text: HexColorSchema,
+    muted: HexColorSchema,
+    success: HexColorSchema.optional(),
+    warning: HexColorSchema.optional(),
+    error: HexColorSchema.optional(),
+  }),
+
+  // Named gradients for bigText
+  gradients: z.record(z.string(), GradientSchema).refine(
+    (g) => Object.keys(g).length >= 1,
+    { message: 'At least one gradient must be defined' }
+  ),
+
+  // Glyph set for matrix rain background
+  glyphs: z.string().min(10, {
+    message: 'Glyph set must have at least 10 characters',
+  }),
+
+  // Animation settings
+  animations: z.object({
+    // Speed multiplier (1.0 = normal, 0.5 = half speed, 2.0 = double speed)
+    revealSpeed: z.number().min(0.1).max(5.0).default(1.0),
+    // Matrix rain density (number of drops)
+    matrixDensity: z.number().min(10).max(200).default(50),
+    // Glitch effect iterations
+    glitchIterations: z.number().min(1).max(20).default(5),
+    // Delay between lines during reveal (ms)
+    lineDelay: z.number().min(0).max(500).default(30),
+    // Matrix rain update interval (ms)
+    matrixInterval: z.number().min(20).max(200).default(80),
+  }),
+
+  // Window appearance
+  window: z.object({
+    // Border style
+    borderStyle: z.enum(['line', 'double', 'rounded', 'none']).default('line'),
+    // Shadow effect
+    shadow: z.boolean().default(true),
+    // Padding inside windows
+    padding: z.object({
+      top: z.number().min(0).max(5).default(1),
+      bottom: z.number().min(0).max(5).default(1),
+      left: z.number().min(0).max(10).default(2),
+      right: z.number().min(0).max(10).default(2),
+    }).optional(),
+  }).optional(),
+})
+
+export type Theme = z.infer<typeof ThemeSchema>
+
+// ============================================================================
+// Color Token System
+// ============================================================================
+
+/**
+ * Valid color tokens for inline styling in slide body content.
+ * Tokens can be either:
+ * - Built-in colors: GREEN, ORANGE, CYAN, PINK, WHITE, GRAY
+ * - Theme-mapped colors: PRIMARY, SECONDARY, ACCENT, MUTED, TEXT, BACKGROUND
+ *
+ * Usage in slides: {GREEN}colored text{/}
+ */
+export const ColorTokens = [
+  'GREEN',
+  'ORANGE',
+  'CYAN',
+  'PINK',
+  'WHITE',
+  'GRAY',
+  'PRIMARY',    // Maps to theme.colors.primary
+  'SECONDARY',  // Maps to theme.colors.secondary
+  'ACCENT',     // Maps to theme.colors.accent
+  'MUTED',      // Maps to theme.colors.muted
+  'TEXT',       // Maps to theme.colors.text
+  'BACKGROUND', // Maps to theme.colors.background
+] as const
+
+/**
+ * Type for valid color token names.
+ */
+export type ColorToken = typeof ColorTokens[number]
+
+/**
+ * Pattern for matching color tokens in slide content.
+ * Matches: {GREEN}, {ORANGE}, {CYAN}, {PINK}, {WHITE}, {GRAY},
+ *          {PRIMARY}, {SECONDARY}, {ACCENT}, {MUTED}, {TEXT}, {BACKGROUND}, {/}
+ *
+ * The {/} token closes any open color tag.
+ */
+export const COLOR_TOKEN_PATTERN = /\{(GREEN|ORANGE|CYAN|PINK|WHITE|GRAY|PRIMARY|SECONDARY|ACCENT|MUTED|TEXT|BACKGROUND|\/)\}/g
+
+// ============================================================================
+// Partial Theme for Extension
+// ============================================================================
+
+/**
+ * Deep partial utility type that makes all nested properties optional.
+ * Used for theme extension where only specific fields need to be overridden.
+ */
+export type DeepPartial<T> = T extends object ? {
+  [P in keyof T]?: DeepPartial<T[P]>
+} : T
+
+/**
+ * Partial theme type for use with theme.extend() functionality.
+ * All fields (including nested) become optional.
+ */
+export type PartialTheme = DeepPartial<Theme>
+
+/**
+ * Schema for validating partial theme objects.
+ * All fields become optional recursively, allowing partial overrides.
+ * Used for theme extension validation.
+ */
+export const PartialThemeSchema = ThemeSchema.deepPartial()
+
+// ============================================================================
+// Default Theme
+// ============================================================================
+
+/**
+ * Default matrix/cyberpunk theme.
+ * Used when no theme is specified or as a base for theme extension.
+ */
+export const DEFAULT_THEME: Theme = {
+  name: 'matrix',
+  description: 'Default cyberpunk/matrix theme',
+
+  colors: {
+    primary: '#00cc66',
+    accent: '#ff6600',
+    background: '#0a0a0a',
+    text: '#ffffff',
+    muted: '#666666',
+  },
+
+  gradients: {
+    fire: ['#ff6600', '#ff3300', '#ff0066'],
+    cool: ['#00ccff', '#0066ff', '#6600ff'],
+    pink: ['#ff0066', '#ff0099', '#cc00ff'],
+    hf: ['#99cc00', '#00cc66', '#00cccc'],
+  },
+
+  glyphs: 'ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ0123456789',
+
+  animations: {
+    revealSpeed: 1.0,
+    matrixDensity: 50,
+    glitchIterations: 5,
+    lineDelay: 30,
+    matrixInterval: 80,
+  },
+
+  window: {
+    borderStyle: 'line',
+    shadow: true,
+    padding: {
+      top: 1,
+      bottom: 1,
+      left: 2,
+      right: 2,
+    },
+  },
+}

package/src/schemas/validation.ts

@@ -0,0 +1,64 @@
+import { z, ZodError } from 'zod'
+
+/**
+ * Custom error class for validation failures.
+ * Extends Error with a specific name for easy identification.
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
+/**
+ * Format Zod errors into user-friendly messages.
+ * Formats each issue with its field path and message.
+ *
+ * @param error - The ZodError to format
+ * @param context - A description of what was being validated (e.g., "theme", "slide frontmatter")
+ * @returns A formatted string with all validation issues
+ *
+ * @example
+ * const error = new ZodError([...])
+ * formatZodError(error, 'theme')
+ * // Returns:
+ * // "Invalid theme:
+ * //   - colors.primary: Color must be a valid hex color (e.g., #ff0066)
+ * //   - name: Theme name is required"
+ */
+export function formatZodError(error: ZodError, context: string): string {
+  const issues = error.issues.map((issue) => {
+    const path = issue.path.join('.')
+    return `  - ${path ? `${path}: ` : ''}${issue.message}`
+  })
+
+  return `Invalid ${context}:\n${issues.join('\n')}`
+}
+
+/**
+ * Parse data with a Zod schema and throw a ValidationError with friendly messages on failure.
+ *
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @param context - A description of what's being validated (e.g., "theme", "slide frontmatter")
+ * @returns The parsed and validated data
+ * @throws {ValidationError} If validation fails
+ *
+ * @example
+ * const theme = safeParse(ThemeSchema, rawData, 'theme')
+ * // Throws ValidationError with formatted message if invalid
+ */
+export function safeParse<T>(
+  schema: z.ZodSchema<T>,
+  data: unknown,
+  context: string
+): T {
+  const result = schema.safeParse(data)
+
+  if (!result.success) {
+    throw new ValidationError(formatZodError(result.error, context))
+  }
+
+  return result.data
+}

package/src/themes/matrix/index.ts

@@ -0,0 +1,53 @@
+import { createTheme } from '../../core/theme'
+
+const yaml = `
+name: matrix
+description: Default cyberpunk/matrix theme
+author: term-deck
+version: 1.0.0
+
+colors:
+  primary: "#00cc66"
+  accent: "#ff6600"
+  background: "#0a0a0a"
+  text: "#ffffff"
+  muted: "#666666"
+
+gradients:
+  fire:
+    - "#ff6600"
+    - "#ff3300"
+    - "#ff0066"
+  cool:
+    - "#00ccff"
+    - "#0066ff"
+    - "#6600ff"
+  pink:
+    - "#ff0066"
+    - "#ff0099"
+    - "#cc00ff"
+  hf:
+    - "#99cc00"
+    - "#00cc66"
+    - "#00cccc"
+
+glyphs: "ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ0123456789"
+
+animations:
+  revealSpeed: 1.0
+  matrixDensity: 50
+  glitchIterations: 5
+  lineDelay: 30
+  matrixInterval: 80
+
+window:
+  borderStyle: line
+  shadow: true
+  padding:
+    top: 1
+    bottom: 1
+    left: 2
+    right: 2
+`
+
+export default createTheme(yaml)