sootsim 0.1.83 → 0.1.85

package/src/screenshots/registry.ts

@@ -0,0 +1,58 @@
+// composer-facing registry. shared tokens live in
+// `sootsim-engine/src/screenshots/tokens.ts` so the live browser
+// screenshot mode and the post-process composer render from the same
+// canvas / background / text / pose / animation / clamp vocabulary.
+//
+// this module re-exports those tokens plus the composer-specific
+// `FrameComposeSpec` shape.
+
+import type { DeviceModel } from 'sootsim-engine/settings'
+
+export {
+  BACKGROUND_PRESETS,
+  DEFAULT_FRAME_SHADOW,
+  DEFAULT_FRAME_STYLE,
+  SCREENSHOT_CANVASES,
+  SCREENSHOT_MODE_ANIM,
+  SCREENSHOT_TEXT_CLAMP,
+  SCREENSHOT_TEXT_SAFE_AREA,
+  cloneBackgroundSpec,
+  resolveBackgroundPreset,
+  resolveCanvasPreset,
+} from 'sootsim-engine/screenshots/tokens'
+
+export type {
+  BackgroundPresetName,
+  BackgroundSpec,
+  CanvasPreset,
+  FrameShadowSpec,
+  GradientStop,
+  PosePresetName,
+  ScreenshotCanvasName,
+  TextPresetName,
+} from 'sootsim-engine/screenshots/tokens'
+
+import type { FrameShadowSpec, PosePresetName } from 'sootsim-engine/screenshots/tokens'
+
+export interface FrameComposeSpec {
+  show: boolean
+  style: DeviceModel
+  pose: PosePresetName
+  scale: number
+  offsetY: number
+  shadow: FrameShadowSpec
+}
+
+export function toAssetKey(value: string): string {
+  const normalized = value
+    .replace(/\\/g, '/')
+    .replace(/\.png$/i, '')
+    .trim()
+    .split('/')
+    .filter(Boolean)
+    .join('--')
+    .replace(/[^A-Za-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+  return normalized || 'slide'
+}

package/src/screenshots/schema.ts

@@ -0,0 +1,364 @@
+import { readFileSync } from 'fs'
+import path from 'path'
+import { devices, type DeviceModel } from 'sootsim-engine/settings'
+import yaml from 'yaml'
+import {
+  cloneBackgroundSpec,
+  DEFAULT_FRAME_SHADOW,
+  DEFAULT_FRAME_STYLE,
+  resolveBackgroundPreset,
+  resolveCanvasPreset,
+  toAssetKey,
+  type BackgroundPresetName,
+  type BackgroundSpec,
+  type CanvasPreset,
+  type FrameComposeSpec,
+  type PosePresetName,
+  type TextPresetName,
+} from './registry'
+
+export type CaptureMode = 'raw' | 'framed' | 'raw+framed'
+export type CapturePathMode = 'auto' | 'plan' | 'flow'
+
+export interface NormalizedScreenshotSlide {
+  id: string
+  assetKey: string
+  screenshot: string
+  headline: string
+  subheadline: string
+  eyebrow: string
+  pose?: PosePresetName
+  scale?: number
+  offsetY?: number
+  background?: BackgroundSpec
+}
+
+export interface NormalizedCapturePlan {
+  flowPath: string | null
+  fromDir: string | null
+  outDir: string
+  rawDir: string
+  framedDir: string
+  mode: CaptureMode
+  pathMode: CapturePathMode
+  simId: string | null
+  openInNewSim: boolean
+}
+
+export interface NormalizedComposePlan {
+  outDir: string
+  locale: string
+  canvases: CanvasPreset[]
+  frame: FrameComposeSpec
+  background: BackgroundSpec
+  text: {
+    preset: TextPresetName
+    color: string
+    subColor: string
+    eyebrowColor: string
+  }
+  slides: NormalizedScreenshotSlide[]
+}
+
+export interface NormalizedScreenshotsPlan {
+  planPath: string
+  planDir: string
+  appTarget: string | null
+  deviceModel: DeviceModel | null
+  capture: NormalizedCapturePlan
+  compose: NormalizedComposePlan
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function expectRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`${label} must be an object`)
+  return value
+}
+
+function readString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback
+}
+
+function readOptionalString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+function readBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+function readNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+function readDeviceModel(
+  value: unknown,
+  fallback: DeviceModel | null,
+): DeviceModel | null {
+  if (typeof value !== 'string' || value.trim().length === 0) return fallback
+  return Object.prototype.hasOwnProperty.call(devices, value)
+    ? (value as DeviceModel)
+    : null
+}
+
+function normalizeBackground(value: unknown, fallback: BackgroundSpec): BackgroundSpec {
+  if (typeof value === 'string') {
+    const preset = resolveBackgroundPreset(value)
+    if (!preset) throw new Error(`unknown background preset: ${value}`)
+    return preset
+  }
+  if (!isRecord(value)) return cloneBackgroundSpec(fallback)
+  const type =
+    value.type === 'solid' || value.type === 'gradient' ? value.type : fallback.type
+  if (type === 'solid') {
+    return {
+      type,
+      color: readString(value.color, fallback.color ?? '#000000'),
+      glow: readOptionalString(value.glow) ?? fallback.glow,
+    }
+  }
+  const stops = Array.isArray(value.stops)
+    ? value.stops
+        .map((stop) => {
+          if (!isRecord(stop)) return null
+          const offset = readNumber(stop.offset, Number.NaN)
+          const color = readOptionalString(stop.color)
+          if (!Number.isFinite(offset) || !color) return null
+          return { offset, color }
+        })
+        .filter((stop): stop is { offset: number; color: string } => !!stop)
+    : (fallback.stops?.map((stop) => ({ ...stop })) ?? [])
+  return {
+    type,
+    direction: readNumber(value.direction, fallback.direction ?? 180),
+    glow: readOptionalString(value.glow) ?? fallback.glow,
+    stops:
+      stops.length > 0 ? stops : (fallback.stops?.map((stop) => ({ ...stop })) ?? []),
+  }
+}
+
+function normalizeCanvasList(value: unknown): CanvasPreset[] {
+  const names = Array.isArray(value) ? value : ['iphone-6-9']
+  const presets = names.map((entry) => {
+    if (typeof entry !== 'string')
+      throw new Error('compose.canvases entries must be strings')
+    const preset = resolveCanvasPreset(entry)
+    if (!preset) throw new Error(`unknown canvas preset: ${entry}`)
+    return preset
+  })
+  if (presets.length === 0)
+    throw new Error('compose.canvases must include at least one preset')
+  return presets
+}
+
+function normalizeTextPreset(value: unknown): TextPresetName {
+  switch (value) {
+    case 'editorial-left':
+    case 'minimal-bottom':
+    case 'none':
+    case 'bold-top':
+      return value
+    default:
+      return 'bold-top'
+  }
+}
+
+function normalizeCapturePathMode(value: unknown): CapturePathMode {
+  switch (value) {
+    case 'plan':
+    case 'flow':
+    case 'auto':
+      return value
+    default:
+      return 'auto'
+  }
+}
+
+function normalizePose(value: unknown): PosePresetName | undefined {
+  switch (value) {
+    case 'straight':
+    case 'tilted-left':
+    case 'tilted-right':
+    case 'cut-bottom':
+    case 'cut-top':
+      return value
+    default:
+      return undefined
+  }
+}
+
+function resolvePlanPath(planDir: string, value: string): string {
+  return path.isAbsolute(value) ? value : path.resolve(planDir, value)
+}
+
+function normalizeSlides(
+  value: unknown,
+  fallbackBackground: BackgroundSpec,
+): NormalizedScreenshotSlide[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error('compose.slides must be a non-empty array')
+  }
+  return value.map((entry, index) => {
+    const slide = expectRecord(entry, `compose.slides[${index}]`)
+    const screenshot = readOptionalString(slide.screenshot)
+    if (!screenshot) {
+      throw new Error(`compose.slides[${index}].screenshot is required`)
+    }
+    const explicitId = readOptionalString(slide.id)
+    const assetKey = toAssetKey(explicitId || screenshot)
+    return {
+      id: explicitId || assetKey,
+      assetKey,
+      screenshot,
+      headline: readString(slide.headline),
+      subheadline: readString(slide.subheadline),
+      eyebrow: readString(slide.eyebrow),
+      pose: normalizePose(slide.pose),
+      scale:
+        typeof slide.scale === 'number' && Number.isFinite(slide.scale)
+          ? slide.scale
+          : undefined,
+      offsetY:
+        typeof slide.offsetY === 'number' && Number.isFinite(slide.offsetY)
+          ? slide.offsetY
+          : undefined,
+      background:
+        slide.theme || slide.background
+          ? normalizeBackground(slide.theme ?? slide.background, fallbackBackground)
+          : undefined,
+    }
+  })
+}
+
+export function loadScreenshotsPlan(planPath: string): NormalizedScreenshotsPlan {
+  const resolvedPlanPath = path.resolve(planPath)
+  const planDir = path.dirname(resolvedPlanPath)
+  const raw = yaml.parse(readFileSync(resolvedPlanPath, 'utf8'))
+  const root = expectRecord(raw, 'screenshots plan')
+  const capture = expectRecord(root.capture ?? {}, 'capture')
+  const compose = expectRecord(root.compose ?? {}, 'compose')
+
+  const appTarget =
+    typeof root.app === 'number' ? String(root.app) : readOptionalString(root.app)
+  const deviceModel = readDeviceModel(root.device, null)
+  const captureOutDir = resolvePlanPath(
+    planDir,
+    readString(capture.out, path.join('.sootsim', 'screenshots', 'capture')),
+  )
+  const captureFrom = readOptionalString(capture.from)
+  const flowPath = readOptionalString(capture.flow)
+  if (!captureFrom && !flowPath) {
+    throw new Error('capture.flow or capture.from is required')
+  }
+  const captureMode =
+    capture.mode === 'raw' || capture.mode === 'framed' || capture.mode === 'raw+framed'
+      ? capture.mode
+      : ('raw+framed' as CaptureMode)
+  const capturePathMode = normalizeCapturePathMode(capture.pathMode)
+  const defaultBackground = normalizeBackground(
+    compose.background ?? ('cyan' as BackgroundPresetName),
+    resolveBackgroundPreset('cyan')!,
+  )
+  const frameConfig: FrameComposeSpec = {
+    show: readBoolean(
+      compose.frame && isRecord(compose.frame) ? compose.frame.show : undefined,
+      true,
+    ),
+    style:
+      readDeviceModel(
+        compose.frame && isRecord(compose.frame) ? compose.frame.style : null,
+        null,
+      ) ||
+      deviceModel ||
+      DEFAULT_FRAME_STYLE,
+    pose:
+      normalizePose(
+        compose.frame && isRecord(compose.frame) ? compose.frame.pose : undefined,
+      ) || 'straight',
+    scale: readNumber(
+      compose.frame && isRecord(compose.frame) ? compose.frame.scale : undefined,
+      1,
+    ),
+    offsetY: readNumber(
+      compose.frame && isRecord(compose.frame) ? compose.frame.offsetY : undefined,
+      0,
+    ),
+    shadow: {
+      color: readString(
+        compose.frame && isRecord(compose.frame) && isRecord(compose.frame.shadow)
+          ? compose.frame.shadow.color
+          : undefined,
+        DEFAULT_FRAME_SHADOW.color,
+      ),
+      blur: readNumber(
+        compose.frame && isRecord(compose.frame) && isRecord(compose.frame.shadow)
+          ? compose.frame.shadow.blur
+          : undefined,
+        DEFAULT_FRAME_SHADOW.blur,
+      ),
+      spread: readNumber(
+        compose.frame && isRecord(compose.frame) && isRecord(compose.frame.shadow)
+          ? compose.frame.shadow.spread
+          : undefined,
+        DEFAULT_FRAME_SHADOW.spread,
+      ),
+      opacity: readNumber(
+        compose.frame && isRecord(compose.frame) && isRecord(compose.frame.shadow)
+          ? compose.frame.shadow.opacity
+          : undefined,
+        DEFAULT_FRAME_SHADOW.opacity,
+      ),
+    },
+  }
+
+  return {
+    planPath: resolvedPlanPath,
+    planDir,
+    appTarget,
+    deviceModel,
+    capture: {
+      flowPath: flowPath ? resolvePlanPath(planDir, flowPath) : null,
+      fromDir: captureFrom ? resolvePlanPath(planDir, captureFrom) : null,
+      outDir: captureOutDir,
+      rawDir: captureFrom
+        ? resolvePlanPath(planDir, captureFrom)
+        : path.join(captureOutDir, 'raw'),
+      framedDir: path.join(captureOutDir, 'framed'),
+      mode: captureMode,
+      pathMode: capturePathMode,
+      simId: readOptionalString(capture.sim),
+      openInNewSim: readBoolean(capture.new, false),
+    },
+    compose: {
+      outDir: resolvePlanPath(
+        planDir,
+        readString(compose.out, path.join('.sootsim', 'screenshots', 'exports')),
+      ),
+      locale: readString(compose.locale, 'en'),
+      canvases: normalizeCanvasList(compose.canvases),
+      frame: frameConfig,
+      background: defaultBackground,
+      text: {
+        preset: normalizeTextPreset(
+          compose.text && isRecord(compose.text) ? compose.text.preset : undefined,
+        ),
+        color: readString(
+          compose.text && isRecord(compose.text) ? compose.text.color : undefined,
+          '#ffffff',
+        ),
+        subColor: readString(
+          compose.text && isRecord(compose.text) ? compose.text.subColor : undefined,
+          'rgba(232,240,247,0.86)',
+        ),
+        eyebrowColor: readString(
+          compose.text && isRecord(compose.text) ? compose.text.eyebrowColor : undefined,
+          'rgba(229,242,255,0.72)',
+        ),
+      },
+      slides: normalizeSlides(compose.slides, defaultBackground),
+    },
+  }
+}

package/src/skills/builtin/a11y-review.ts

@@ -0,0 +1,126 @@
+// built-in skill: accessibility audit
+
+import type { SootSimSkill } from '../types'
+
+export const skill: SootSimSkill = {
+  name: 'a11y-review',
+  description: 'Check the app for accessibility issues',
+  type: 'review',
+  version: '1.0.0',
+  triggers: ['accessibility', 'a11y', 'check accessibility', 'audit accessibility'],
+  tools: [
+    {
+      name: 'audit_accessibility',
+      description: 'Run an accessibility audit on the current screen',
+      parameters: {
+        screen: { type: 'string', description: 'Screen name or URL to audit' },
+      },
+      async execute(params, context) {
+        const { chromium } = await import('playwright')
+        const path = await import('path')
+        const fs = await import('fs')
+
+        const browser = await chromium.launch({ headless: true })
+        const page = await browser.newPage({ viewport: { width: 500, height: 900 } })
+
+        try {
+          await page.goto(context.url, { waitUntil: 'networkidle' })
+          await page.waitForFunction('window.__sootsimTest', { timeout: 10000 })
+          await page.waitForTimeout(2000)
+
+          // get accessibility tree
+          const tree = await page.evaluate(
+            'window.__sootsimTest.dumpAccessibilityTree(10)',
+          )
+          const allNodes = await page.evaluate('window.__sootsimTest.queryAll({})')
+
+          // analyze for common issues
+          const issues: {
+            severity: 'error' | 'warning' | 'info'
+            message: string
+            node?: string
+          }[] = []
+
+          if (Array.isArray(allNodes)) {
+            for (const node of allNodes) {
+              // check for missing accessibility labels on interactive elements
+              if (
+                (node.accessibilityRole === 'button' ||
+                  node.accessibilityRole === 'link' ||
+                  node.type === 'TouchableOpacity' ||
+                  node.type === 'Pressable') &&
+                !node.accessibilityLabel &&
+                !node.text
+              ) {
+                issues.push({
+                  severity: 'error',
+                  message: `Interactive element missing accessibility label`,
+                  node: node.testID || node.id || node.type,
+                })
+              }
+
+              // check for missing roles
+              if (
+                (node.type === 'TouchableOpacity' || node.type === 'Pressable') &&
+                !node.accessibilityRole
+              ) {
+                issues.push({
+                  severity: 'warning',
+                  message: `Touchable element missing accessibility role`,
+                  node: node.testID || node.id || node.type,
+                })
+              }
+
+              // check for images without alt text
+              if (node.type === 'Image' && !node.accessibilityLabel && !node.accessible) {
+                issues.push({
+                  severity: 'warning',
+                  message: `Image missing accessibility label`,
+                  node: node.testID || node.id || 'Image',
+                })
+              }
+
+              // check for small touch targets
+              if (
+                node.layout &&
+                (node.accessibilityRole === 'button' ||
+                  node.type === 'TouchableOpacity') &&
+                (node.layout.width < 44 || node.layout.height < 44)
+              ) {
+                issues.push({
+                  severity: 'warning',
+                  message: `Touch target too small (${Math.round(node.layout.width)}x${Math.round(node.layout.height)}pt, minimum 44x44pt)`,
+                  node: node.testID || node.text || node.type,
+                })
+              }
+            }
+          }
+
+          // write report
+          const report = {
+            timestamp: new Date().toISOString(),
+            screen: params.screen || 'current',
+            nodeCount: Array.isArray(allNodes) ? allNodes.length : 0,
+            issues,
+            errors: issues.filter((i) => i.severity === 'error').length,
+            warnings: issues.filter((i) => i.severity === 'warning').length,
+            tree: typeof tree === 'string' ? tree : JSON.stringify(tree),
+          }
+
+          const reportPath = path.join(context.outputDir, 'a11y-report.json')
+          fs.mkdirSync(path.dirname(reportPath), { recursive: true })
+          fs.writeFileSync(reportPath, JSON.stringify(report, null, 2))
+
+          return {
+            success: issues.filter((i) => i.severity === 'error').length === 0,
+            message: `${report.errors} errors, ${report.warnings} warnings across ${report.nodeCount} nodes`,
+            artifacts: [{ type: 'report', name: 'a11y-report', path: reportPath }],
+            data: report,
+          }
+        } finally {
+          await browser.close()
+        }
+      },
+    },
+  ],
+}

package/src/skills/builtin/compat-check.ts

@@ -0,0 +1,104 @@
+// built-in skill: package compatibility check
+
+import type { SootSimSkill } from '../types'
+
+function getCompatStatus(entry: {
+  stubType: 'native' | 'works' | 'build-only'
+  versions: Array<{ coverage: number }>
+}): 'full' | 'partial' | 'auto-stub' {
+  if (entry.stubType === 'works') return 'full'
+  if (entry.stubType === 'build-only') return 'full'
+  return entry.versions.some((version) => version.coverage >= 1) ? 'full' : 'auto-stub'
+}
+
+export const skill: SootSimSkill = {
+  name: 'compat-check',
+  description: 'Check package compatibility with sootsim',
+  type: 'review',
+  version: '1.0.0',
+  triggers: ['compatibility', 'compat', 'check package', 'supported packages'],
+  tools: [
+    {
+      name: 'check_compatibility',
+      description: 'Scan project dependencies for sootsim compatibility',
+      parameters: {
+        packageName: {
+          type: 'string',
+          description: 'Specific package to check (optional)',
+        },
+      },
+      async execute(params, context) {
+        const fs = await import('fs')
+        const path = await import('path')
+
+        const { POLYFILL_REGISTRY } = await import('../../../../compat/src/web.ts')
+
+        if (params.packageName) {
+          const entry = POLYFILL_REGISTRY[params.packageName]
+          if (!entry) {
+            return {
+              success: true,
+              message: `${params.packageName}: not in registry (may be auto-stubbed if native)`,
+              data: { package: params.packageName, status: 'unknown' },
+            }
+          }
+          const status = getCompatStatus(entry)
+          return {
+            success: true,
+            message: `${params.packageName}: ${status}`,
+            data: { package: params.packageName, status, ...entry },
+          }
+        }
+
+        // scan project deps
+        const pkgPath = path.join(context.projectDir, 'package.json')
+        if (!fs.existsSync(pkgPath)) {
+          return { success: false, message: 'No package.json found' }
+        }
+
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+        const results: Record<string, string[]> = {
+          full: [],
+          partial: [],
+          'auto-stub': [],
+          unsupported: [],
+          unknown: [],
+        }
+
+        for (const dep of Object.keys(allDeps)) {
+          const entry = POLYFILL_REGISTRY[dep]
+          if (entry) {
+            const status = getCompatStatus(entry)
+            if (results[status]) results[status].push(dep)
+          } else if (isNative(dep)) {
+            results.unknown.push(dep)
+          }
+        }
+
+        const reportPath = path.join(context.outputDir, 'compat-report.json')
+        fs.mkdirSync(path.dirname(reportPath), { recursive: true })
+        fs.writeFileSync(reportPath, JSON.stringify(results, null, 2))
+
+        return {
+          success: results.unsupported.length === 0,
+          message: `${results.full.length} full, ${results.partial.length} partial, ${results.unsupported.length} unsupported, ${results.unknown.length} unknown`,
+          artifacts: [{ type: 'report', name: 'compat-report', path: reportPath }],
+          data: results,
+        }
+      },
+    },
+  ],
+}
+
+function isNative(name: string): boolean {
+  return (
+    name.startsWith('expo-') ||
+    name.startsWith('react-native-') ||
+    name.startsWith('@react-native/') ||
+    name.startsWith('@react-native-community/') ||
+    name.startsWith('@expo/') ||
+    name === 'expo'
+  )
+}