peachsim 0.1.1644 → 0.1.1653

package/src/settings-flags.ts

@@ -0,0 +1,107 @@
+// auto-generate CLI flag definitions from the settings schema
+
+import {
+  settingsSchema,
+  isSettingKey,
+  type SettingKey,
+  type SettingsValues,
+} from './settingsContract.ts'
+
+export interface FlagDef {
+  name: string // --flag-name
+  short?: string // -f
+  key: SettingKey
+  type: 'string' | 'number' | 'boolean'
+  description: string
+  options?: readonly string[]
+  default: any
+}
+
+// build flag definitions from schema — only settings with cliFlag defined
+const _flags: FlagDef[] = []
+for (const [key, def] of Object.entries(settingsSchema)) {
+  if (!def.cliFlag || !isSettingKey(key)) continue
+  _flags.push({
+    name: `--${def.cliFlag}`,
+    short: def.cliFlagShort ? `-${def.cliFlagShort}` : undefined,
+    key,
+    type: def.type === 'enum' ? 'string' : def.type,
+    description: def.description,
+    options: def.options,
+    default: def.default,
+  })
+}
+
+export const cliFlags: readonly FlagDef[] = _flags
+
+/** parse CLI args and extract settings overrides */
+export function parseSettingsFlags(args: string[]): {
+  settings: Partial<SettingsValues>
+  remaining: string[]
+} {
+  const settings: Record<string, any> = {}
+  const remaining: string[] = []
+  let i = 0
+
+  while (i < args.length) {
+    const arg = args[i]
+
+    // stop at -- separator
+    if (arg === '--') {
+      remaining.push(...args.slice(i))
+      break
+    }
+
+    const flag = cliFlags.find((f) => f.name === arg || f.short === arg)
+    if (flag) {
+      if (flag.type === 'boolean') {
+        settings[flag.key] = true
+        i++
+      } else {
+        const val = args[i + 1]
+        if (val === undefined) {
+          remaining.push(arg)
+          i++
+          continue
+        }
+        if (flag.type === 'number') {
+          const num = Number(val)
+          if (Number.isNaN(num)) {
+            remaining.push(arg, val)
+            i += 2
+            continue
+          }
+          settings[flag.key] = num
+        } else {
+          // validate enum values
+          if (flag.options && !flag.options.includes(val)) {
+            console.error(
+              `  warning: invalid value "${val}" for ${arg} (expected: ${flag.options.join('|')})`,
+            )
+            i += 2
+            continue
+          }
+          settings[flag.key] = val
+        }
+        i += 2
+      }
+    } else {
+      remaining.push(arg)
+      i++
+    }
+  }
+
+  return { settings, remaining }
+}
+
+/** format flag list for --help output */
+export function formatFlagHelp(): string {
+  const lines: string[] = []
+  for (const flag of cliFlags) {
+    const nameStr = flag.short ? `${flag.short}, ${flag.name}` : `    ${flag.name}`
+    const optStr = flag.options ? ` [${flag.options.join('|')}]` : ''
+    const defStr = flag.default !== undefined ? ` (default: ${flag.default})` : ''
+    lines.push(`  ${nameStr.padEnd(24)}${flag.description}${optStr}${defStr}`)
+  }
+  return lines.join('\n')
+}

package/src/settingsContract.ts

@@ -0,0 +1,609 @@
+import {
+  DEFAULT_PROFILER_CATEGORIES,
+  formatProfilerCategories,
+} from '@peach/globals/profiler'
+import {
+  SOOTSIM_AMBIENT_GLOW_LEVELS,
+  SOOTSIM_RENDER_RESOLUTION_LEVELS,
+  SOOTSIM_STAGE_BACKGROUNDS,
+  type SootSimAmbientGlowLevel,
+  type SootSimRenderResolution,
+  type SootSimStageBackground,
+} from 'peachsim/menu'
+import {
+  type DeviceModel,
+  type DevicePosture,
+  type LandscapeSide,
+  listDeviceModels,
+  DEFAULT_DEVICE,
+} from './device-catalog.ts'
+import { DEFAULT_REACT_NATIVE_CONFIGURATION } from './reactNativeConfigurationContract.ts'
+import {
+  BACKGROUND_PRESET_NAMES,
+  POSE_PRESET_NAMES,
+  SCREENSHOT_CANVAS_NAMES,
+  TEXT_PRESET_NAMES,
+  type BackgroundPresetName,
+  type PosePresetName,
+  type ScreenshotCanvasName,
+  type TextPresetName,
+} from './screenshots/preset-names.ts'
+
+export type SettingType = 'string' | 'number' | 'boolean' | 'enum'
+
+export interface SettingDef<T = any> {
+  type: SettingType
+  default: T
+  description: string
+  cliFlag?: string // --flag-name (omit for settings not exposed as CLI flags)
+  cliFlagShort?: string // single-char shorthand like -d
+  options?: readonly string[] // for enum type
+  group: SettingGroup
+  validate?: (value: T) => boolean
+}
+
+export type SettingGroup =
+  | 'device'
+  | 'appearance'
+  | 'network'
+  | 'locale'
+  | 'simulator'
+  | 'privacy'
+  | 'agent'
+
+export type AgentProvider = 'codex' | 'claude'
+
+export type A11yMode = 'off' | 'delayed' | 'active'
+
+export type A11yDepth = 'shallow' | 'deep'
+
+export type ColorScheme = 'light' | 'dark' | 'auto'
+
+// the glow's strength lives on the public menu protocol so the menus, the
+// electron shared config and the hosts that seed it all read one definition.
+export type AmbientGlowLevel = SootSimAmbientGlowLevel
+
+// the render resolution level lives on the same protocol for the same reason.
+export type RenderResolution = SootSimRenderResolution
+
+// and the stage background, for the same reason.
+export type StageBackground = SootSimStageBackground
+
+export type NetworkCondition = 'wifi' | 'lte' | 'fast-3g' | 'slow-3g' | 'offline'
+
+export type Orientation = 'portrait' | 'landscape'
+
+// all settings
+export interface SettingsValues {
+  // device
+  deviceModel: DeviceModel
+  posture: DevicePosture
+  orientation: Orientation
+  landscapeSide: LandscapeSide
+  // portrayed os version overriding the device profile; empty means the
+  // profile truth. boot-pinned only (?osVersion=), never persisted
+  osVersionOverride: string
+  // settings > general > keyboard > predictive text (TIPreferences
+  // KeyboardPrediction); off hides the QuickType lane above the keys
+  predictiveText: boolean
+  // appearance
+  colorScheme: ColorScheme
+  reduceMotion: boolean
+  boldText: boolean
+  fontSize: number
+  largerAccessibilitySizes: boolean
+  reduceTransparency: boolean
+  // settings > accessibility > display & text size > increase contrast
+  // (UIAccessibilityDarkerSystemColorsEnabled)
+  increaseContrast: boolean
+  // display & text size > show borders (UIAccessibilityButtonShapesEnabled)
+  showBorders: boolean
+  // display & text size > on/off labels (_UIAccessibilityIsOnOffSwitchLabelsEnabled)
+  onOffLabels: boolean
+  // display & text size > differentiate without color
+  // (UIAccessibilityShouldDifferentiateWithoutColor)
+  differentiateWithoutColor: boolean
+  // display & text size > smart invert (UIAccessibilityIsInvertColorsEnabled)
+  smartInvert: boolean
+  // motion > prefer cross-fade transitions. the row shows only while reduce
+  // motion is on, and UIAccessibilityPrefersCrossFadeTransitions reads both
+  preferCrossFadeTransitions: boolean
+  // settings > appearance > liquid glass: 0 most clear, 1 most tinted
+  glassTintAmount: number
+  // network
+  networkCondition: NetworkCondition
+  // locale
+  language: string
+  region: string
+  // simulator
+  renderDensity: number
+  renderResolution: RenderResolution
+  slowAnimations: boolean
+  // the Performance pane's chosen recording categories, comma separated
+  profilerCategories: string
+  showTouches: boolean
+  showFrame: boolean
+  showMenuBar: boolean
+  showRail: boolean
+  agentIndicator: boolean
+  solidWindow: boolean
+  ambientGlow: AmbientGlowLevel
+  stageBackground: StageBackground
+  stageChecker: boolean
+  screenshotMode: boolean
+  screenshotCanvasEditing: boolean
+  threeMode: boolean
+  threeRecordingEditor: boolean
+  screenshotCanvas: ScreenshotCanvasName
+  screenshotBackground: BackgroundPresetName
+  screenshotText: TextPresetName
+  screenshotPose: PosePresetName
+  screenshotDynamicSize: boolean
+  showStatusBar: boolean
+  showHomeIndicator: boolean
+  alwaysShowLiveWebViews: boolean
+  a11yMode: A11yMode
+  a11yDepth: A11yDepth
+  inspectMode: boolean
+  // privacy
+  productAnalytics: boolean
+  crashReports: boolean
+  sendToBoxCarryAuth: boolean
+  // agent
+  agentProvider: AgentProvider
+}
+
+export type SettingKey = keyof SettingsValues
+
+// these values belong to the simulated device. erase-all resets them while
+// preserving simulator-app preferences such as bezels, rail, and privacy controls.
+export const SIMULATED_DEVICE_SETTING_KEYS = [
+  'predictiveText',
+  'colorScheme',
+  'reduceMotion',
+  'boldText',
+  'fontSize',
+  'largerAccessibilitySizes',
+  'glassTintAmount',
+  'reduceTransparency',
+  'increaseContrast',
+  'showBorders',
+  'onOffLabels',
+  'differentiateWithoutColor',
+  'smartInvert',
+  'preferCrossFadeTransitions',
+] as const satisfies readonly SettingKey[]
+
+export const settingsSchema: Record<SettingKey, SettingDef> = {
+  // device
+  deviceModel: {
+    type: 'enum',
+    default: DEFAULT_DEVICE,
+    description: 'device model to simulate',
+    cliFlag: 'device',
+    cliFlagShort: 'd',
+    options: listDeviceModels(),
+    group: 'device',
+  },
+  posture: {
+    type: 'enum',
+    default: 'closed',
+    description: 'posture for devices that support more than one physical state',
+    options: ['closed', 'open'] as const,
+    group: 'device',
+  },
+  orientation: {
+    type: 'enum',
+    default: 'portrait',
+    description: 'screen orientation',
+    cliFlag: 'orientation',
+    options: ['portrait', 'landscape'] as const,
+    group: 'device',
+  },
+  landscapeSide: {
+    type: 'enum',
+    default: 'left',
+    description: 'which landscape the device turns to: left (clockwise) or right',
+    cliFlag: 'landscape-side',
+    options: ['left', 'right'] as const,
+    group: 'device',
+  },
+
+  osVersionOverride: {
+    type: 'string',
+    default: '',
+    description:
+      "os version the device reports instead of its profile's (empty = the profile's version); set per launch with ?osVersion=, never saved",
+    group: 'device',
+  },
+
+  predictiveText: {
+    type: 'boolean',
+    default: true,
+    description: 'keyboard predictive text (off hides the QuickType lane)',
+    group: 'device',
+  },
+
+  // appearance
+  colorScheme: {
+    type: 'enum',
+    default: 'auto',
+    description: 'color scheme (auto follows system preference)',
+    cliFlag: 'theme',
+    cliFlagShort: 't',
+    options: ['light', 'dark', 'auto'] as const,
+    group: 'appearance',
+  },
+  reduceMotion: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.reduceMotion,
+    description: 'reduce motion',
+    group: 'appearance',
+  },
+  boldText: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.boldText,
+    description: 'bold text',
+    group: 'appearance',
+  },
+  fontSize: {
+    type: 'number',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.fontSize,
+    description: 'font size multiplier (1.0 = default)',
+    group: 'appearance',
+    // android permits continuous font scales; ios settings and capture urls
+    // constrain their own inputs to the discrete dynamic type ramp.
+    validate: (value: number) => value >= 0.5 && value <= 4,
+  },
+  largerAccessibilitySizes: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.largerAccessibilitySizes,
+    description: 'show accessibility categories in the dynamic type size picker',
+    group: 'appearance',
+  },
+  reduceTransparency: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.reduceTransparency,
+    description: 'reduce transparency',
+    group: 'appearance',
+  },
+  increaseContrast: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.increaseContrast,
+    description: 'increase contrast',
+    group: 'appearance',
+  },
+  showBorders: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.showBorders,
+    description: 'show borders on text buttons',
+    group: 'appearance',
+  },
+  onOffLabels: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.onOffLabels,
+    description: 'on/off labels inside switches',
+    group: 'appearance',
+  },
+  differentiateWithoutColor: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.differentiateWithoutColor,
+    description: 'differentiate without color',
+    group: 'appearance',
+  },
+  smartInvert: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.smartInvert,
+    description: 'smart invert',
+    group: 'appearance',
+  },
+  preferCrossFadeTransitions: {
+    type: 'boolean',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.preferCrossFadeTransitions,
+    description: 'prefer cross-fade transitions while reduce motion is on',
+    group: 'appearance',
+  },
+  // ios persists the slider as com.apple.UIKit UIViewGlassTintAmount in steps
+  // of 0.05; with the key absent the material reads the middle.
+  glassTintAmount: {
+    type: 'number',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.glassTintAmount,
+    description: 'liquid glass tint amount (0 most clear, 0.5 default, 1 most tinted)',
+    group: 'appearance',
+    validate: (value: number) => value >= 0 && value <= 1,
+  },
+
+  // network
+  networkCondition: {
+    type: 'enum',
+    default: 'wifi',
+    description: 'simulated network condition',
+    cliFlag: 'network',
+    options: ['wifi', 'lte', 'fast-3g', 'slow-3g', 'offline'] as const,
+    group: 'network',
+  },
+
+  // locale
+  language: {
+    type: 'string',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.language,
+    description: 'language code (ISO 639-1)',
+    cliFlag: 'language',
+    group: 'locale',
+  },
+  region: {
+    type: 'string',
+    default: DEFAULT_REACT_NATIVE_CONFIGURATION.region,
+    description: 'region code (ISO 3166-1)',
+    cliFlag: 'region',
+    group: 'locale',
+  },
+
+  // simulator
+  renderDensity: {
+    type: 'number',
+    default: 0,
+    description:
+      'explicit render density in device pixels per point for high-resolution capture (0 = follow the render resolution level)',
+    group: 'simulator',
+    validate: (v: number) => v === 0 || (v >= 1 && v <= 9),
+  },
+  renderResolution: {
+    type: 'enum',
+    default: 'medium',
+    description:
+      'how many pixels Peach renders per iphone point (high = device native, medium = 2, low = on-screen pixels capped at native)',
+    options: SOOTSIM_RENDER_RESOLUTION_LEVELS,
+    group: 'simulator',
+  },
+  slowAnimations: {
+    type: 'boolean',
+    default: false,
+    description: 'Run simulated app and OS animations at one tenth speed',
+    group: 'simulator',
+  },
+  profilerCategories: {
+    type: 'string',
+    default: formatProfilerCategories(DEFAULT_PROFILER_CATEGORIES),
+    description: 'Categories the Performance pane records, comma separated',
+    group: 'simulator',
+  },
+  showTouches: {
+    type: 'boolean',
+    default: false,
+    description: 'show touch indicators',
+    cliFlag: 'show-touches',
+    group: 'simulator',
+  },
+  showFrame: {
+    type: 'boolean',
+    default: true,
+    description: 'show device frame',
+    cliFlag: 'frame',
+    group: 'simulator',
+  },
+  showMenuBar: {
+    type: 'boolean',
+    default: true,
+    description: 'keep the menu bar visible instead of revealing it at the top edge',
+    group: 'simulator',
+  },
+  showRail: {
+    type: 'boolean',
+    default: true,
+    description: 'keep the rail visible instead of revealing it on hover',
+    group: 'simulator',
+  },
+  agentIndicator: {
+    type: 'boolean',
+    default: true,
+    description:
+      'show the connected agent indicator over the device while a CLI or agent drives it',
+    cliFlag: 'agent-indicator',
+    group: 'simulator',
+  },
+  solidWindow: {
+    type: 'boolean',
+    default: false,
+    description:
+      'desktop app: always use the solid, freely-resizable window instead of the device-shaped transparent one (3d mode uses it regardless)',
+    group: 'simulator',
+  },
+  ambientGlow: {
+    type: 'enum',
+    default: 'off',
+    description:
+      "bleed the app's own edge colors outward behind the device, like bias lighting behind a TV (off, soft, full)",
+    options: SOOTSIM_AMBIENT_GLOW_LEVELS,
+    cliFlag: 'ambient-glow',
+    group: 'simulator',
+  },
+  stageBackground: {
+    type: 'enum',
+    default: 'system',
+    description:
+      "the stage behind the device: system follows the computer's appearance (white in light mode, black in dark), or light, dark or gray",
+    options: SOOTSIM_STAGE_BACKGROUNDS,
+    cliFlag: 'stage-background',
+    group: 'simulator',
+  },
+  stageChecker: {
+    type: 'boolean',
+    default: true,
+    description: 'a faint checker pattern on the stage behind the device, under the glow',
+    group: 'simulator',
+  },
+  screenshotMode: {
+    type: 'boolean',
+    default: false,
+    description: 'show screenshot composition mode in the browser shell',
+    group: 'simulator',
+  },
+  screenshotCanvasEditing: {
+    type: 'boolean',
+    default: false,
+    description:
+      'experimental figma-style slide editing: draggable copy block, drop-in image layers (owner review pending)',
+    group: 'simulator',
+  },
+  threeMode: {
+    type: 'boolean',
+    default: false,
+    description: 'show the experimental 3d device stage in the browser shell',
+    group: 'simulator',
+  },
+  threeRecordingEditor: {
+    type: 'boolean',
+    default: false,
+    description: 'dock the 3d recording editor in the 3d stage (toggled from its rail)',
+    group: 'simulator',
+  },
+  screenshotCanvas: {
+    type: 'enum',
+    default: 'iphone-6-9',
+    description: 'target app-store canvas preset for screenshot mode',
+    options: SCREENSHOT_CANVAS_NAMES,
+    group: 'simulator',
+  },
+  screenshotBackground: {
+    type: 'enum',
+    default: 'dark',
+    description: 'background preset rendered inside the screenshot canvas',
+    options: BACKGROUND_PRESET_NAMES,
+    group: 'simulator',
+  },
+  screenshotText: {
+    type: 'enum',
+    default: 'bold-top',
+    description: 'text layout preset for the screenshot canvas',
+    options: TEXT_PRESET_NAMES,
+    group: 'simulator',
+  },
+  screenshotPose: {
+    type: 'enum',
+    default: 'straight',
+    description: 'device pose preset inside the screenshot canvas',
+    options: POSE_PRESET_NAMES,
+    group: 'simulator',
+  },
+  screenshotDynamicSize: {
+    type: 'boolean',
+    default: false,
+    description:
+      'let the screenshot canvas rect fit available space (off = pin to exact preset pixels)',
+    group: 'simulator',
+  },
+  showStatusBar: {
+    type: 'boolean',
+    default: true,
+    description: 'show status bar',
+    group: 'simulator',
+  },
+  showHomeIndicator: {
+    type: 'boolean',
+    default: true,
+    description: 'show home indicator',
+    group: 'simulator',
+  },
+  alwaysShowLiveWebViews: {
+    type: 'boolean',
+    default: false,
+    description: 'always render WebViews as live browser views',
+    group: 'simulator',
+  },
+  a11yMode: {
+    type: 'enum',
+    default: 'delayed',
+    description: 'accessibility tree sync mode (off, delayed=100ms, active=30ms)',
+    options: ['off', 'delayed', 'active'] as const,
+    group: 'simulator',
+  },
+  a11yDepth: {
+    type: 'enum',
+    default: 'deep',
+    description: 'accessibility tree structure depth (shallow or deep)',
+    options: ['shallow', 'deep'] as const,
+    group: 'simulator',
+  },
+  inspectMode: {
+    type: 'boolean',
+    default: false,
+    description: 'inspect mode',
+    group: 'simulator',
+  },
+
+  // privacy
+  productAnalytics: {
+    type: 'boolean',
+    default: true,
+    description: 'send bounded product usage analytics',
+    group: 'privacy',
+  },
+  crashReports: {
+    type: 'boolean',
+    default: true,
+    description: 'send anonymous crash reports',
+    group: 'privacy',
+  },
+  sendToBoxCarryAuth: {
+    type: 'boolean',
+    default: true,
+    description:
+      'send to box carries the signed-in session into the box it creates (off = the app boots signed out)',
+    group: 'privacy',
+  },
+
+  // agent — default ai agent used by the prompt bar's auto-attach + startSession.
+  agentProvider: {
+    type: 'enum',
+    default: 'codex',
+    description: 'ai agent used by the peach agent prompt bar',
+    options: ['codex', 'claude'] as const,
+    group: 'agent',
+  },
+}
+
+const SETTING_VALUE_TYPES = {
+  string: 'string',
+  enum: 'string',
+  number: 'number',
+  boolean: 'boolean',
+} as const satisfies Record<SettingType, string>
+
+// the one gate for every write and load: a value of the wrong type (an object
+// written into language) would otherwise reach every app's configuration and
+// persist across launches.
+export function isValidSettingValue(key: SettingKey, value: unknown): boolean {
+  const def = settingsSchema[key]
+  if (!def || typeof value !== SETTING_VALUE_TYPES[def.type]) return false
+  if (def.options && !def.options.some((option) => option === value)) return false
+  return !def.validate || def.validate(value)
+}
+
+export const DEFAULT_SIMULATED_DEVICE_SETTINGS = {
+  predictiveText: settingsSchema.predictiveText.default,
+  colorScheme: settingsSchema.colorScheme.default,
+  reduceMotion: settingsSchema.reduceMotion.default,
+  boldText: settingsSchema.boldText.default,
+  fontSize: settingsSchema.fontSize.default,
+  largerAccessibilitySizes: settingsSchema.largerAccessibilitySizes.default,
+  glassTintAmount: settingsSchema.glassTintAmount.default,
+  reduceTransparency: settingsSchema.reduceTransparency.default,
+  increaseContrast: settingsSchema.increaseContrast.default,
+  showBorders: settingsSchema.showBorders.default,
+  onOffLabels: settingsSchema.onOffLabels.default,
+  differentiateWithoutColor: settingsSchema.differentiateWithoutColor.default,
+  smartInvert: settingsSchema.smartInvert.default,
+  preferCrossFadeTransitions: settingsSchema.preferCrossFadeTransitions.default,
+} satisfies Pick<SettingsValues, (typeof SIMULATED_DEVICE_SETTING_KEYS)[number]>
+
+export function isSettingKey(key: string): key is SettingKey {
+  return Object.hasOwn(settingsSchema, key)
+}
+
+export function getSettingsByGroup(group: SettingGroup): [SettingKey, SettingDef][] {
+  return Object.entries(settingsSchema).filter(
+    (entry): entry is [SettingKey, SettingDef] =>
+      isSettingKey(entry[0]) && entry[1].group === group,
+  )
+}