prev-cli 0.24.19 → 0.25.0

package/src/theme/previews/machines/screen-machine.test.ts

@@ -0,0 +1,149 @@
+import { test, expect, describe } from 'bun:test'
+import {
+  screenReducer,
+  createScreenInitialState,
+  type ScreenMachineState,
+  type ScreenAction,
+} from './screen-machine'
+
+// --- Test fixtures ---
+
+function readyState(overrides?: Partial<ScreenMachineState>): ScreenMachineState {
+  return {
+    ...createScreenInitialState(['index', 'error', 'loading']),
+    status: 'ready',
+    ...overrides,
+  }
+}
+
+// --- Tests ---
+
+describe('createScreenInitialState', () => {
+  test('returns loading state with provided states', () => {
+    const state = createScreenInitialState(['index', 'error', 'loading'])
+    expect(state.status).toBe('loading')
+    expect(state.activeState).toBe('index')
+    expect(state.availableStates).toEqual(['index', 'error', 'loading'])
+    expect(state.viewport).toBe('desktop')
+    expect(state.isFullscreen).toBe(false)
+    expect(state.error).toBeUndefined()
+  })
+
+  test('defaults to index-only when no states provided', () => {
+    const state = createScreenInitialState([])
+    expect(state.activeState).toBe('index')
+    expect(state.availableStates).toEqual([])
+  })
+
+  test('accepts initial state override', () => {
+    const state = createScreenInitialState(['index', 'error'], 'error')
+    expect(state.activeState).toBe('error')
+  })
+})
+
+describe('screenReducer — set_state', () => {
+  test('switches to a valid state', () => {
+    const state = readyState()
+    const next = screenReducer(state, { type: 'set_state', state: 'error' })
+    expect(next.activeState).toBe('error')
+  })
+
+  test('ignores switch to non-existent state', () => {
+    const state = readyState()
+    const same = screenReducer(state, { type: 'set_state', state: 'nonexistent' })
+    expect(same.activeState).toBe('index')
+  })
+})
+
+describe('screenReducer — set_viewport', () => {
+  test('switches viewport to mobile', () => {
+    const state = readyState()
+    const next = screenReducer(state, { type: 'set_viewport', viewport: 'mobile' })
+    expect(next.viewport).toBe('mobile')
+  })
+
+  test('switches viewport to tablet', () => {
+    const state = readyState()
+    const next = screenReducer(state, { type: 'set_viewport', viewport: 'tablet' })
+    expect(next.viewport).toBe('tablet')
+  })
+
+  test('switches viewport to desktop', () => {
+    const state = readyState({ viewport: 'mobile' })
+    const next = screenReducer(state, { type: 'set_viewport', viewport: 'desktop' })
+    expect(next.viewport).toBe('desktop')
+  })
+})
+
+describe('screenReducer — toggle_fullscreen', () => {
+  test('toggles fullscreen on', () => {
+    const state = readyState()
+    const next = screenReducer(state, { type: 'toggle_fullscreen' })
+    expect(next.isFullscreen).toBe(true)
+  })
+
+  test('toggles fullscreen off', () => {
+    const state = readyState({ isFullscreen: true })
+    const next = screenReducer(state, { type: 'toggle_fullscreen' })
+    expect(next.isFullscreen).toBe(false)
+  })
+})
+
+describe('screenReducer — build status FSM', () => {
+  test('loading -> building via build_started', () => {
+    const state = createScreenInitialState(['index'])
+    expect(state.status).toBe('loading')
+
+    const next = screenReducer(state, { type: 'build_started' })
+    expect(next.status).toBe('building')
+  })
+
+  test('building -> ready via build_ready', () => {
+    const state = readyState({ status: 'building' })
+    const next = screenReducer(state, { type: 'build_ready' })
+    expect(next.status).toBe('ready')
+    expect(next.error).toBeUndefined()
+  })
+
+  test('build_ready clears previous error', () => {
+    const state = readyState({ status: 'building', error: 'previous error' })
+    const next = screenReducer(state, { type: 'build_ready' })
+    expect(next.error).toBeUndefined()
+  })
+
+  test('building -> error via build_error', () => {
+    const state = readyState({ status: 'building' })
+    const next = screenReducer(state, { type: 'build_error', error: 'Syntax error in component' })
+    expect(next.status).toBe('error')
+    expect(next.error).toBe('Syntax error in component')
+  })
+
+  test('error -> building via build_started (retry)', () => {
+    const state = readyState({ status: 'error', error: 'previous' })
+    const next = screenReducer(state, { type: 'build_started' })
+    expect(next.status).toBe('building')
+  })
+})
+
+// --- Codex review fixes ---
+
+describe('createScreenInitialState — invalid initial state clamping', () => {
+  test('clamps to index when initialState not in availableStates', () => {
+    const state = createScreenInitialState(['index', 'error'], 'nonexistent')
+    expect(state.activeState).toBe('index')
+  })
+
+  test('clamps to first available when initialState invalid and no index', () => {
+    const state = createScreenInitialState(['error', 'loading'], 'nonexistent')
+    expect(state.activeState).toBe('error')
+  })
+})
+
+describe('screenReducer — immutability', () => {
+  test('does not mutate previous state', () => {
+    const state = readyState()
+    const original = state.activeState
+    screenReducer(state, { type: 'set_state', state: 'error' })
+    expect(state.activeState).toBe(original)
+  })
+})

package/src/theme/previews/machines/screen-machine.ts

@@ -0,0 +1,76 @@
+// Pure screen state machine — zero React imports
+
+// --- State ---
+
+export interface ScreenMachineState {
+  status: 'loading' | 'building' | 'ready' | 'error'
+  activeState: string
+  availableStates: string[]
+  viewport: 'mobile' | 'tablet' | 'desktop'
+  isFullscreen: boolean
+  error?: string
+}
+
+// --- Actions ---
+
+export type ScreenAction =
+  | { type: 'set_state'; state: string }
+  | { type: 'set_viewport'; viewport: 'mobile' | 'tablet' | 'desktop' }
+  | { type: 'toggle_fullscreen' }
+  | { type: 'build_started' }
+  | { type: 'build_ready' }
+  | { type: 'build_error'; error: string }
+
+// --- Initial state ---
+
+export function createScreenInitialState(
+  availableStates: string[],
+  initialState?: string,
+): ScreenMachineState {
+  // Clamp: use initialState if valid, else 'index' if available, else first available, else 'index'
+  let active = 'index'
+  if (initialState && availableStates.includes(initialState)) {
+    active = initialState
+  } else if (availableStates.includes('index')) {
+    active = 'index'
+  } else if (availableStates.length > 0) {
+    active = availableStates[0]
+  }
+
+  return {
+    status: 'loading',
+    activeState: active,
+    availableStates,
+    viewport: 'desktop',
+    isFullscreen: false,
+  }
+}
+
+// --- Reducer ---
+
+export function screenReducer(state: ScreenMachineState, action: ScreenAction): ScreenMachineState {
+  switch (action.type) {
+    case 'set_state': {
+      if (!state.availableStates.includes(action.state)) return state
+      return { ...state, activeState: action.state }
+    }
+
+    case 'set_viewport':
+      return { ...state, viewport: action.viewport }
+
+    case 'toggle_fullscreen':
+      return { ...state, isFullscreen: !state.isFullscreen }
+
+    case 'build_started':
+      return { ...state, status: 'building' }
+
+    case 'build_ready':
+      return { ...state, status: 'ready', error: undefined }
+
+    case 'build_error':
+      return { ...state, status: 'error', error: action.error }
+
+    default:
+      return state
+  }
+}

package/src/theme/previews/stores/flow-store.test.ts

@@ -0,0 +1,157 @@
+import { test, expect, describe } from 'bun:test'
+import { createFlowStore } from './flow-store'
+import type { FlowStep } from '../../../content/preview-types'
+
+const steps: FlowStep[] = [
+  {
+    id: 'step1',
+    title: 'Sign Up',
+    screen: 'signup',
+    regions: {
+      submit: { goto: 'step2' },
+    },
+  },
+  {
+    id: 'step2',
+    title: 'Dashboard',
+    screen: 'dashboard',
+    regions: {
+      'upgrade-btn': {
+        outcomes: {
+          success: { goto: 'step3', label: 'Paid' },
+          failure: { goto: 'step1' },
+        },
+      },
+    },
+  },
+  {
+    id: 'step3',
+    title: 'Done',
+    screen: 'settings',
+    terminal: true,
+  },
+]
+
+describe('createFlowStore', () => {
+  test('starts in loading state', () => {
+    const store = createFlowStore()
+    expect(store.getState().status).toBe('loading')
+    expect(store.getState().currentStepId).toBeNull()
+  })
+
+  test('loaded action transitions to ready with steps', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test Flow', 'A flow')
+    const state = store.getState()
+    expect(state.status).toBe('ready')
+    expect(state.name).toBe('Test Flow')
+    expect(state.steps).toEqual(steps)
+    expect(state.currentStepId).toBe('step1')
+  })
+
+  test('goto navigates and updates history', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test')
+    store.getState().goto('step2')
+    expect(store.getState().currentStepId).toBe('step2')
+    expect(store.getState().history).toEqual(['step1', 'step2'])
+  })
+
+  test('back pops history', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test')
+    store.getState().goto('step2')
+    store.getState().back()
+    expect(store.getState().currentStepId).toBe('step1')
+    expect(store.getState().history).toEqual(['step1'])
+  })
+
+  test('regionClick with goto navigates', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test')
+    store.getState().regionClick('submit')
+    expect(store.getState().currentStepId).toBe('step2')
+  })
+
+  test('regionClick with outcomes opens picker', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test')
+    store.getState().goto('step2')
+    store.getState().regionClick('upgrade-btn')
+    expect(store.getState().outcomePicker).not.toBeNull()
+    expect(store.getState().currentStepId).toBe('step2')
+  })
+
+  test('pickOutcome navigates and clears picker', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test')
+    store.getState().goto('step2')
+    store.getState().regionClick('upgrade-btn')
+    store.getState().pickOutcome('step3')
+    expect(store.getState().currentStepId).toBe('step3')
+    expect(store.getState().outcomePicker).toBeNull()
+  })
+
+  test('cancelPicker clears picker without navigating', () => {
+    const store = createFlowStore()
+    store.getState().loaded(steps, 'Test')
+    store.getState().goto('step2')
+    store.getState().regionClick('upgrade-btn')
+    store.getState().cancelPicker()
+    expect(store.getState().outcomePicker).toBeNull()
+    expect(store.getState().currentStepId).toBe('step2')
+  })
+
+  test('toggleOverlay toggles showOverlay', () => {
+    const store = createFlowStore()
+    expect(store.getState().showOverlay).toBe(true)
+    store.getState().toggleOverlay()
+    expect(store.getState().showOverlay).toBe(false)
+  })
+
+  test('toggleFullscreen toggles isFullscreen', () => {
+    const store = createFlowStore()
+    expect(store.getState().isFullscreen).toBe(false)
+    store.getState().toggleFullscreen()
+    expect(store.getState().isFullscreen).toBe(true)
+  })
+
+  test('linearNext advances for non-region steps', () => {
+    const linearSteps: FlowStep[] = [
+      { id: 'a', screen: 'page-a' },
+      { id: 'b', screen: 'page-b' },
+    ]
+    const store = createFlowStore()
+    store.getState().loaded(linearSteps, 'Test')
+    store.getState().linearNext()
+    expect(store.getState().currentStepId).toBe('b')
+  })
+
+  test('linearPrev goes back', () => {
+    const linearSteps: FlowStep[] = [
+      { id: 'a', screen: 'page-a' },
+      { id: 'b', screen: 'page-b' },
+    ]
+    const store = createFlowStore()
+    store.getState().loaded(linearSteps, 'Test')
+    store.getState().linearNext()
+    store.getState().linearPrev()
+    expect(store.getState().currentStepId).toBe('a')
+  })
+
+  // Codex review: missing store-level tests
+  test('loadError sets error state', () => {
+    const store = createFlowStore()
+    store.getState().loadError('Network failure')
+    expect(store.getState().status).toBe('error')
+    expect(store.getState().error).toBe('Network failure')
+  })
+
+  test('load_error -> loaded clears stale error', () => {
+    const store = createFlowStore()
+    store.getState().loadError('oops')
+    store.getState().loaded(steps, 'Recovered')
+    expect(store.getState().status).toBe('ready')
+    expect(store.getState().error).toBeUndefined()
+  })
+})

package/src/theme/previews/stores/flow-store.ts

@@ -0,0 +1,49 @@
+// Zustand store wrapping the flow state machine
+
+import { createStore } from 'zustand/vanilla'
+import { flowReducer, createFlowInitialState, type FlowMachineState } from '../machines/flow-machine'
+import type { FlowStep } from '../../../content/preview-types'
+
+export interface FlowStoreActions {
+  loaded: (steps: FlowStep[], name: string, description?: string) => void
+  loadError: (error?: string) => void
+  goto: (stepId: string) => void
+  back: () => void
+  linearNext: () => void
+  linearPrev: () => void
+  regionClick: (region: string) => void
+  pickOutcome: (stepId: string) => void
+  cancelPicker: () => void
+  toggleOverlay: () => void
+  toggleFullscreen: () => void
+}
+
+export type FlowStore = FlowMachineState & FlowStoreActions
+
+export function createFlowStore() {
+  return createStore<FlowStore>((set) => ({
+    ...createFlowInitialState(),
+    loaded: (steps, name, description) =>
+      set(s => flowReducer(s, { type: 'loaded', steps, name, description })),
+    loadError: (error) =>
+      set(s => flowReducer(s, { type: 'load_error', error })),
+    goto: (stepId) =>
+      set(s => flowReducer(s, { type: 'goto', stepId })),
+    back: () =>
+      set(s => flowReducer(s, { type: 'back' })),
+    linearNext: () =>
+      set(s => flowReducer(s, { type: 'linear_next' })),
+    linearPrev: () =>
+      set(s => flowReducer(s, { type: 'linear_prev' })),
+    regionClick: (region) =>
+      set(s => flowReducer(s, { type: 'region_click', region })),
+    pickOutcome: (stepId) =>
+      set(s => flowReducer(s, { type: 'pick_outcome', stepId })),
+    cancelPicker: () =>
+      set(s => flowReducer(s, { type: 'cancel_picker' })),
+    toggleOverlay: () =>
+      set(s => flowReducer(s, { type: 'toggle_overlay' })),
+    toggleFullscreen: () =>
+      set(s => flowReducer(s, { type: 'toggle_fullscreen' })),
+  }))
+}

package/src/theme/previews/stores/screen-store.test.ts

@@ -0,0 +1,68 @@
+import { test, expect, describe } from 'bun:test'
+import { createScreenStore } from './screen-store'
+
+describe('createScreenStore', () => {
+  test('starts in loading state', () => {
+    const store = createScreenStore(['index', 'error'])
+    expect(store.getState().status).toBe('loading')
+    expect(store.getState().activeState).toBe('index')
+    expect(store.getState().availableStates).toEqual(['index', 'error'])
+  })
+
+  test('accepts initial state override', () => {
+    const store = createScreenStore(['index', 'error'], 'error')
+    expect(store.getState().activeState).toBe('error')
+  })
+
+  test('setState switches to valid state', () => {
+    const store = createScreenStore(['index', 'error'])
+    store.getState().setState('error')
+    expect(store.getState().activeState).toBe('error')
+  })
+
+  test('setState ignores invalid state', () => {
+    const store = createScreenStore(['index', 'error'])
+    store.getState().setState('nonexistent')
+    expect(store.getState().activeState).toBe('index')
+  })
+
+  test('setViewport switches viewport', () => {
+    const store = createScreenStore(['index'])
+    store.getState().setViewport('mobile')
+    expect(store.getState().viewport).toBe('mobile')
+  })
+
+  test('toggleFullscreen toggles', () => {
+    const store = createScreenStore(['index'])
+    expect(store.getState().isFullscreen).toBe(false)
+    store.getState().toggleFullscreen()
+    expect(store.getState().isFullscreen).toBe(true)
+  })
+
+  test('build status FSM: loading -> building -> ready', () => {
+    const store = createScreenStore(['index'])
+    expect(store.getState().status).toBe('loading')
+    store.getState().buildStarted()
+    expect(store.getState().status).toBe('building')
+    store.getState().buildReady()
+    expect(store.getState().status).toBe('ready')
+    expect(store.getState().error).toBeUndefined()
+  })
+
+  test('build status FSM: building -> error', () => {
+    const store = createScreenStore(['index'])
+    store.getState().buildStarted()
+    store.getState().buildError('Syntax error')
+    expect(store.getState().status).toBe('error')
+    expect(store.getState().error).toBe('Syntax error')
+  })
+
+  test('build_ready clears previous error', () => {
+    const store = createScreenStore(['index'])
+    store.getState().buildStarted()
+    store.getState().buildError('oops')
+    store.getState().buildStarted()
+    store.getState().buildReady()
+    expect(store.getState().error).toBeUndefined()
+  })
+})

package/src/theme/previews/stores/screen-store.ts

@@ -0,0 +1,33 @@
+// Zustand store wrapping the screen state machine
+
+import { createStore } from 'zustand/vanilla'
+import { screenReducer, createScreenInitialState, type ScreenMachineState } from '../machines/screen-machine'
+
+export interface ScreenStoreActions {
+  setState: (state: string) => void
+  setViewport: (viewport: 'mobile' | 'tablet' | 'desktop') => void
+  toggleFullscreen: () => void
+  buildStarted: () => void
+  buildReady: () => void
+  buildError: (error: string) => void
+}
+
+export type ScreenStore = ScreenMachineState & ScreenStoreActions
+
+export function createScreenStore(availableStates: string[], initialState?: string) {
+  return createStore<ScreenStore>((set) => ({
+    ...createScreenInitialState(availableStates, initialState),
+    setState: (state) =>
+      set(s => screenReducer(s, { type: 'set_state', state })),
+    setViewport: (viewport) =>
+      set(s => screenReducer(s, { type: 'set_viewport', viewport })),
+    toggleFullscreen: () =>
+      set(s => screenReducer(s, { type: 'toggle_fullscreen' })),
+    buildStarted: () =>
+      set(s => screenReducer(s, { type: 'build_started' })),
+    buildReady: () =>
+      set(s => screenReducer(s, { type: 'build_ready' })),
+    buildError: (error) =>
+      set(s => screenReducer(s, { type: 'build_error', error })),
+  }))
+}

package/src/theme/storage.test.ts

@@ -0,0 +1,97 @@
+import { test, expect, describe, beforeEach } from 'bun:test'
+import { PrefixedStorageAdapter } from './storage'
+
+function createMemoryBackend() {
+  const store = new Map<string, string>()
+  return {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => store.set(k, v),
+    removeItem: (k: string) => store.delete(k),
+    key: (i: number) => [...store.keys()][i] ?? null,
+    get length() { return store.size },
+    _store: store,
+  }
+}
+
+describe('PrefixedStorageAdapter', () => {
+  let backend: ReturnType<typeof createMemoryBackend>
+  let storage: PrefixedStorageAdapter
+
+  beforeEach(() => {
+    backend = createMemoryBackend()
+    storage = new PrefixedStorageAdapter(backend)
+  })
+
+  test('get returns null for missing key', () => {
+    expect(storage.get('nonexistent')).toBeNull()
+  })
+
+  test('set and get round-trip', () => {
+    storage.set('test-key', { name: 'hello', count: 42 })
+    expect(storage.get('test-key')).toEqual({ name: 'hello', count: 42 })
+  })
+
+  test('set overwrites existing value', () => {
+    storage.set('key', 'first')
+    storage.set('key', 'second')
+    expect(storage.get('key')).toBe('second')
+  })
+
+  test('remove deletes a key', () => {
+    storage.set('to-remove', 'value')
+    storage.remove('to-remove')
+    expect(storage.get('to-remove')).toBeNull()
+  })
+
+  test('list returns keys matching prefix', () => {
+    storage.set('annotations:screen1:a', { id: 'a' })
+    storage.set('annotations:screen1:b', { id: 'b' })
+    storage.set('status:screen1', { status: 'draft' })
+
+    const keys = storage.list('annotations:')
+    expect(keys).toContain('annotations:screen1:a')
+    expect(keys).toContain('annotations:screen1:b')
+    expect(keys).not.toContain('status:screen1')
+  })
+
+  test('list returns empty array when no matches', () => {
+    expect(storage.list('nothing:')).toEqual([])
+  })
+
+  test('clear removes all keys matching prefix', () => {
+    storage.set('annotations:a', 1)
+    storage.set('annotations:b', 2)
+    storage.set('status:x', 3)
+
+    storage.clear('annotations:')
+
+    expect(storage.get('annotations:a')).toBeNull()
+    expect(storage.get('annotations:b')).toBeNull()
+    expect(storage.get('status:x')).toBe(3)
+  })
+
+  test('get handles corrupt JSON gracefully', () => {
+    backend._store.set('prev:corrupt', '{bad json')
+    expect(storage.get('corrupt')).toBeNull()
+  })
+
+  test('stores and retrieves arrays', () => {
+    storage.set('arr', [1, 2, 3])
+    expect(storage.get('arr')).toEqual([1, 2, 3])
+  })
+
+  test('stores and retrieves nested objects', () => {
+    const data = { a: { b: { c: 'deep' } } }
+    storage.set('nested', data)
+    expect(storage.get('nested')).toEqual(data)
+  })
+
+  test('prefix isolation - different prefixes dont collide', () => {
+    const storage2 = new PrefixedStorageAdapter(backend, 'other:')
+    storage.set('key', 'from-prev')
+    storage2.set('key', 'from-other')
+
+    expect(storage.get('key')).toBe('from-prev')
+    expect(storage2.get('key')).toBe('from-other')
+  })
+})