sootsim 0.1.83 → 0.1.85

package/README.md

@@ -184,7 +184,6 @@ the frame for quick art-direction passes.
 the published CLI registry and the generated website docs both come from
 `packages/sootsim-skills/`.
 
-- `packages/sootsim/cli/registry.ts` re-exports the shared CLI metadata
 - `packages/sootsim/skills/soot.md` is generated from that registry
 - `src/features/site/docs/sootsim/cli/*` is generated output, not hand-edited source
 

package/detox/colors.ts

@@ -0,0 +1,54 @@
+// re-export color utilities from kitchen-sink for convenience
+// these are the same implementations used in detox tests
+
+import * as fs from 'fs'
+import { PNG } from 'pngjs'
+
+export type RGB = { r: number; g: number; b: number }
+
+export function getDominantColor(screenshotPath: string): RGB {
+  const data = fs.readFileSync(screenshotPath)
+  const png = PNG.sync.read(data)
+
+  const startX = Math.floor(png.width * 0.25)
+  const endX = Math.floor(png.width * 0.75)
+  const startY = Math.floor(png.height * 0.25)
+  const endY = Math.floor(png.height * 0.75)
+
+  let totalR = 0,
+    totalG = 0,
+    totalB = 0,
+    count = 0
+
+  for (let y = startY; y < endY; y++) {
+    for (let x = startX; x < endX; x++) {
+      const idx = (png.width * y + x) * 4
+      totalR += png.data[idx]
+      totalG += png.data[idx + 1]
+      totalB += png.data[idx + 2]
+      count++
+    }
+  }
+
+  return {
+    r: Math.round(totalR / count),
+    g: Math.round(totalG / count),
+    b: Math.round(totalB / count),
+  }
+}
+
+export function isBlueish(color: RGB): boolean {
+  return color.b > 100 && color.b > color.r && color.b > color.g
+}
+
+export function isReddish(color: RGB): boolean {
+  return color.r > 100 && color.r > color.b && color.r > color.g
+}
+
+export function isGreenish(color: RGB): boolean {
+  return color.g > 100 && color.g > color.r && color.g > color.b
+}
+
+export function formatRGB(color: RGB): string {
+  return `RGB(${color.r}, ${color.g}, ${color.b})`
+}

package/detox/config-loader.ts

@@ -0,0 +1,135 @@
+// parse detox configuration from various locations
+// maps detox device config to sootsim settings
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+export interface DetoxConfig {
+  testRunner?: {
+    args?: Record<string, any>
+    jest?: { setupTimeout?: number; teardownTimeout?: number }
+  }
+  apps?: Record<string, { type: string; binaryPath?: string; build?: string }>
+  devices?: Record<string, { type: string; device?: { type?: string } }>
+  configurations?: Record<string, { device?: string; app?: string }>
+  testMatch?: string[]
+  testDir?: string
+}
+
+export interface SootSimDetoxConfig {
+  testFiles: string[]
+  testTimeout: number
+  sootsimUrl: string
+  deviceModel: string
+  maxWorkers: number
+}
+
+// search order: .detoxrc.js, .detoxrc.json, detox.config.js, detox.config.json, package.json#detox
+export function loadDetoxConfig(projectDir: string): DetoxConfig | null {
+  const candidates = [
+    '.detoxrc.js',
+    '.detoxrc.json',
+    'detox.config.js',
+    'detox.config.json',
+  ]
+
+  for (const file of candidates) {
+    const filePath = path.join(projectDir, file)
+    if (fs.existsSync(filePath)) {
+      try {
+        if (file.endsWith('.json')) {
+          return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+        }
+        // for JS files, we can't easily require them without running them
+        // return a basic config indicating file was found
+        return { testDir: 'e2e' }
+      } catch {
+        continue
+      }
+    }
+  }
+
+  // check package.json
+  const pkgPath = path.join(projectDir, 'package.json')
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+      if (pkg.detox) return pkg.detox
+    } catch {}
+  }
+
+  return null
+}
+
+// find test files matching detox patterns
+export function findDetoxTestFiles(
+  projectDir: string,
+  config: DetoxConfig | null,
+): string[] {
+  const testDirs = ['e2e', 'test/e2e', 'detox', '__tests__/e2e']
+  const patterns = [
+    '.test.ts',
+    '.test.js',
+    '.test.tsx',
+    '.test.jsx',
+    '.spec.ts',
+    '.spec.js',
+  ]
+
+  // if config specifies a test dir, prioritize it
+  if (config?.testDir) {
+    testDirs.unshift(config.testDir)
+  }
+
+  const files: string[] = []
+
+  for (const dir of testDirs) {
+    const fullDir = path.join(projectDir, dir)
+    if (!fs.existsSync(fullDir)) continue
+
+    const entries = fs.readdirSync(fullDir, { recursive: true })
+    for (const entry of entries) {
+      const entryStr = String(entry)
+      if (patterns.some((p) => entryStr.endsWith(p))) {
+        files.push(path.join(fullDir, entryStr))
+      }
+    }
+  }
+
+  return files
+}
+
+// map detox device type to sootsim device model
+export function mapDetoxDevice(config: DetoxConfig | null): string {
+  if (!config?.devices) return 'iphone-15-pro'
+
+  const devices = Object.values(config.devices)
+  for (const dev of devices) {
+    const type = dev.device?.type?.toLowerCase() || ''
+    if (type.includes('se')) return 'iphone-se'
+    if (type.includes('16 pro max') || type.includes('16-pro-max'))
+      return 'iphone-16-pro-max'
+    if (type.includes('16 pro') || type.includes('16-pro')) return 'iphone-16-pro'
+    if (type.includes('16')) return 'iphone-16'
+    if (type.includes('15 pro max') || type.includes('15-pro-max'))
+      return 'iphone-15-pro-max'
+    if (type.includes('15 pro') || type.includes('15-pro')) return 'iphone-15-pro'
+    if (type.includes('15')) return 'iphone-15'
+  }
+
+  return 'iphone-15-pro'
+}
+
+// generate a sootsim-compatible config from detox config
+export function toSootSimConfig(
+  projectDir: string,
+  config: DetoxConfig | null,
+): SootSimDetoxConfig {
+  return {
+    testFiles: findDetoxTestFiles(projectDir, config),
+    testTimeout: config?.testRunner?.jest?.setupTimeout || 120000,
+    sootsimUrl: process.env.SOOTSIM_URL || 'http://localhost:5173',
+    deviceModel: mapDetoxDevice(config),
+    maxWorkers: 1,
+  }
+}

package/detox/element-types.ts

@@ -0,0 +1,36 @@
+import type { Matcher } from './matchers'
+
+// element interaction object returned by element(matcher)
+export interface SootElement {
+  // reference to the matcher for lazy evaluation
+  _matcher: Matcher
+
+  tap(point?: { x?: number; y?: number }): Promise<void>
+  multiTap(times: number): Promise<void>
+  longPress(duration?: number): Promise<void>
+  longPressAndDrag(
+    duration: number,
+    normalizedStartX: number,
+    normalizedStartY: number,
+    targetElement: SootElement,
+    normalizedEndX: number,
+    normalizedEndY: number,
+    speed?: string,
+    holdDuration?: number,
+  ): Promise<void>
+  typeText(text: string): Promise<void>
+  replaceText(text: string): Promise<void>
+  clearText(): Promise<void>
+  scroll(pixels: number, direction: 'up' | 'down' | 'left' | 'right'): Promise<void>
+  scrollTo(edge: 'top' | 'bottom' | 'left' | 'right'): Promise<void>
+  swipe(
+    direction: 'up' | 'down' | 'left' | 'right',
+    speed?: string,
+    percentage?: number,
+  ): Promise<void>
+  pinch(scale: number, speed?: 'fast' | 'slow', angle?: number): Promise<void>
+  rotate(radians: number, speed?: 'fast' | 'slow'): Promise<void>
+  takeScreenshot(name: string): Promise<string>
+  getAttributes(): Promise<any>
+  atIndex(index: number): SootElement
+}

package/detox/expectations.ts

@@ -0,0 +1,477 @@
+// detox-compatible expectations for sootsim
+// expect(element).toExist(), .toBeVisible(), .toHaveText(), etc.
+// waitFor(element).toExist().withTimeout(ms)
+
+import { dragScrollNode, readSootsimInteractiveViewport } from './gestures'
+import type { SootElement } from './element-types'
+import type { Matcher } from './matchers'
+import type { Page } from 'playwright'
+
+type FindFn = (matcher: Matcher) => Promise<any>
+type GetPageFn = () => Page
+const DEFAULT_VISIBILITY_THRESHOLD = 0.75
+
+async function scrollMatcherElement(
+  page: Page,
+  findNode: FindFn,
+  matcher: Matcher,
+  pixels: number,
+  direction: 'up' | 'down' | 'left' | 'right',
+): Promise<void> {
+  const node = await findNode(matcher)
+  if (!node) {
+    throw new Error(`scroll container not found: ${JSON.stringify(matcher)}`)
+  }
+  await dragScrollNode(page, node, pixels, direction)
+}
+
+type Viewport = { width: number; height: number }
+
+function isNodeVisibleInViewport(node: any, viewport: Viewport): boolean {
+  if (!node || node.layout.width <= 0 || node.layout.height <= 0) {
+    return false
+  }
+
+  const frame = node.visibleFrame ?? {
+    x: node.absolutePosition?.x ?? node.layout?.x ?? 0,
+    y: node.absolutePosition?.y ?? node.layout?.y ?? 0,
+    width: node.layout.width,
+    height: node.layout.height,
+  }
+  const right = frame.x + frame.width
+  const bottom = frame.y + frame.height
+
+  const visibleWidth = Math.max(0, Math.min(right, viewport.width) - Math.max(frame.x, 0))
+  const visibleHeight = Math.max(
+    0,
+    Math.min(bottom, viewport.height) - Math.max(frame.y, 0),
+  )
+  const visibleArea = visibleWidth * visibleHeight
+  const totalArea = node.layout.width * node.layout.height
+
+  return totalArea > 0 && visibleArea / totalArea >= DEFAULT_VISIBILITY_THRESHOLD
+}
+
+async function isNodeVisible(page: Page, node: any): Promise<boolean> {
+  if (!node || node.layout.width <= 0 || node.layout.height <= 0) {
+    return false
+  }
+  return isNodeVisibleInViewport(node, await readSootsimInteractiveViewport(page))
+}
+
+function describeNodeVisibility(node: any, viewport?: Viewport): string {
+  if (!node) return 'not found'
+  const absX = node.absolutePosition?.x ?? node.layout?.x ?? 0
+  const absY = node.absolutePosition?.y ?? node.layout?.y ?? 0
+  return JSON.stringify({
+    layout: node.layout,
+    absolutePosition: node.absolutePosition ?? null,
+    frame: {
+      x: absX,
+      y: absY,
+      right: absX + (node.layout?.width ?? 0),
+      bottom: absY + (node.layout?.height ?? 0),
+    },
+    visibleFrame: node.visibleFrame ?? null,
+    viewport: viewport ?? null,
+    style: node.style ?? null,
+  })
+}
+
+// expect(element) returns an object with assertion methods
+export function createExpect(findNode: FindFn, getPage: GetPageFn) {
+  return function sootExpect(el: SootElement): SootExpectation {
+    return new SootExpectation(el._matcher, findNode, getPage, false)
+  }
+}
+
+class SootExpectation {
+  private matcher: Matcher
+  private findNode: FindFn
+  private getPage: GetPageFn
+  private negated: boolean
+
+  constructor(matcher: Matcher, findNode: FindFn, getPage: GetPageFn, negated: boolean) {
+    this.matcher = matcher
+    this.findNode = findNode
+    this.getPage = getPage
+    this.negated = negated
+  }
+
+  get not(): SootExpectation {
+    return new SootExpectation(this.matcher, this.findNode, this.getPage, !this.negated)
+  }
+
+  async toExist(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    const exists = node !== null && node !== undefined
+    if (this.negated) {
+      if (exists) {
+        throw new Error(
+          `expected element NOT to exist but it does: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else {
+      if (!exists) {
+        throw new Error(
+          `expected element to exist but it was not found: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+  }
+
+  async toBeVisible(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    const page = this.getPage()
+    const viewport = node ? await readSootsimInteractiveViewport(page) : undefined
+    const visible = viewport ? isNodeVisibleInViewport(node, viewport) : false
+    if (this.negated) {
+      if (visible) {
+        throw new Error(
+          `expected element NOT to be visible: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else {
+      if (!visible) {
+        throw new Error(
+          `expected element to be visible but it is ${describeNodeVisibility(node, viewport)}: ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+  }
+
+  async toBeNotVisible(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    const visible = await isNodeVisible(this.getPage(), node)
+    if (visible) {
+      throw new Error(
+        `expected element NOT to be visible: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+  }
+
+  async toHaveText(expectedText: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(`element not found for toHaveText: ${JSON.stringify(this.matcher)}`)
+    }
+    const actualText = node.text || ''
+    const matches = actualText === expectedText || actualText.includes(expectedText)
+
+    if (this.negated) {
+      if (matches) {
+        throw new Error(
+          `expected text NOT to be "${expectedText}" but got "${actualText}": ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    } else {
+      if (!matches) {
+        throw new Error(
+          `expected text "${expectedText}" but got "${actualText}": ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+  }
+
+  async toHaveId(expectedId: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(`element not found for toHaveId: ${JSON.stringify(this.matcher)}`)
+    }
+    const hasId = node.testID === expectedId || node.id === expectedId
+    if (this.negated) {
+      if (hasId) throw new Error(`expected element NOT to have id "${expectedId}"`)
+    } else {
+      if (!hasId)
+        throw new Error(
+          `expected element to have id "${expectedId}" but got "${node.testID || node.id}"`,
+        )
+    }
+  }
+
+  async toHaveLabel(expectedLabel: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toHaveLabel: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    // check explicit accessibilityLabel, then derived text content
+    const actual = node.accessibilityLabel || node.text || ''
+    const matches = actual === expectedLabel
+    if (this.negated) {
+      if (matches)
+        throw new Error(`expected label NOT to be "${expectedLabel}" but it was`)
+    } else {
+      if (!matches)
+        throw new Error(
+          `expected label "${expectedLabel}" but got "${actual}": ${JSON.stringify(this.matcher)}`,
+        )
+    }
+  }
+
+  async toHaveAccessibilityRole(expectedRole: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toHaveAccessibilityRole: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    const actual = node.accessibilityRole || ''
+    const matches = actual === expectedRole
+    if (this.negated) {
+      if (matches) throw new Error(`expected role NOT to be "${expectedRole}" but it was`)
+    } else {
+      if (!matches)
+        throw new Error(
+          `expected role "${expectedRole}" but got "${actual}": ${JSON.stringify(this.matcher)}`,
+        )
+    }
+  }
+
+  async toBeEnabled(): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toBeEnabled: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    const disabled = node.accessibilityState?.disabled ?? false
+    if (this.negated) {
+      if (!disabled) throw new Error(`expected element to be disabled but it is enabled`)
+    } else {
+      if (disabled) throw new Error(`expected element to be enabled but it is disabled`)
+    }
+  }
+
+  async toBeFocused(): Promise<void> {
+    // in sootsim we don't track focus state fully, so just check existence
+    await this.toExist()
+  }
+
+  async toHaveValue(value: string): Promise<void> {
+    const node = await this.findNode(this.matcher)
+    if (!node) {
+      throw new Error(
+        `element not found for toHaveValue: ${JSON.stringify(this.matcher)}`,
+      )
+    }
+    // value could be in text or props
+    const actual = node.text || ''
+    if (this.negated) {
+      if (actual.includes(value)) {
+        throw new Error(
+          `expected element NOT to have value "${value}" but got "${actual}"`,
+        )
+      }
+    } else {
+      if (!actual.includes(value)) {
+        throw new Error(`expected element to have value "${value}" but got "${actual}"`)
+      }
+    }
+  }
+
+  async toHaveSliderPosition(
+    normalizedPosition: number,
+    tolerance?: number,
+  ): Promise<void> {
+    // stub for slider tests -- sootsim doesn't have native sliders yet
+    await this.toExist()
+  }
+
+  async toHaveToggleValue(value: boolean): Promise<void> {
+    await this.toExist()
+  }
+}
+
+// waitFor(element) returns a chainable object that polls until the assertion passes
+export function createWaitFor(findNode: FindFn, getPage: GetPageFn) {
+  return function sootWaitFor(el: SootElement): SootWaitForChain {
+    return new SootWaitForChain(el._matcher, findNode, getPage)
+  }
+}
+
+class SootWaitForChain {
+  private matcher: Matcher
+  private findNode: FindFn
+  private getPage: GetPageFn
+  private assertionFn: (() => Promise<void>) | null = null
+  private _negated = false
+
+  constructor(matcher: Matcher, findNode: FindFn, getPage: GetPageFn) {
+    this.matcher = matcher
+    this.findNode = findNode
+    this.getPage = getPage
+  }
+
+  get not(): SootWaitForChain {
+    this._negated = true
+    return this
+  }
+
+  toExist(): SootWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      const exists = node !== null && node !== undefined
+      if (this._negated ? exists : !exists) {
+        throw new Error(`waitFor toExist failed: ${JSON.stringify(this.matcher)}`)
+      }
+    }
+    return new SootWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toBeVisible(): SootWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      const page = this.getPage()
+      const viewport = node ? await readSootsimInteractiveViewport(page) : undefined
+      const visible = viewport ? isNodeVisibleInViewport(node, viewport) : false
+      if (this._negated ? visible : !visible) {
+        throw new Error(
+          `waitFor toBeVisible failed (${describeNodeVisibility(node, viewport)}): ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+    return new SootWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toBeNotVisible(): SootWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      const visible = await isNodeVisible(this.getPage(), node)
+      if (visible) {
+        throw new Error(`waitFor toBeNotVisible failed: ${JSON.stringify(this.matcher)}`)
+      }
+    }
+    return new SootWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toHaveText(expectedText: string): SootWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      if (!node)
+        throw new Error(
+          `waitFor toHaveText: element not found: ${JSON.stringify(this.matcher)}`,
+        )
+      const actual = node.text || ''
+      const matches = actual === expectedText || actual.includes(expectedText)
+      if (this._negated ? matches : !matches) {
+        throw new Error(
+          `waitFor toHaveText: expected "${expectedText}" but got "${actual}" ${JSON.stringify(this.matcher)}`,
+        )
+      }
+    }
+    return new SootWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+
+  toHaveValue(value: string): SootWaitForAction {
+    this.assertionFn = async () => {
+      const node = await this.findNode(this.matcher)
+      if (!node) throw new Error(`waitFor toHaveValue: element not found`)
+      const actual = node.text || ''
+      if (!actual.includes(value)) {
+        throw new Error(`waitFor toHaveValue: expected "${value}" in "${actual}"`)
+      }
+    }
+    return new SootWaitForAction(this.assertionFn, this.findNode, this.getPage)
+  }
+}
+
+class SootWaitForAction {
+  private assertionFn: () => Promise<void>
+  private findNode: FindFn
+  private getPage: GetPageFn
+
+  constructor(assertionFn: () => Promise<void>, findNode: FindFn, getPage: GetPageFn) {
+    this.assertionFn = assertionFn
+    this.findNode = findNode
+    this.getPage = getPage
+  }
+
+  async withTimeout(ms: number): Promise<void> {
+    const start = Date.now()
+    const pollInterval = 100
+    let lastError: Error | null = null
+
+    while (Date.now() - start < ms) {
+      try {
+        await this.assertionFn()
+        return // assertion passed
+      } catch (e) {
+        lastError = e as Error
+        await new Promise((r) => setTimeout(r, pollInterval))
+      }
+    }
+
+    throw lastError || new Error(`waitFor timed out after ${ms}ms`)
+  }
+
+  // if no withTimeout is called, just run the assertion once
+  async then(resolve: (v: void) => void, reject: (e: any) => void): Promise<void> {
+    try {
+      // default 5 second timeout
+      await this.withTimeout(5000)
+      resolve(undefined)
+    } catch (e) {
+      reject(e)
+    }
+  }
+
+  whileElement(matcher: Matcher): SootWaitForScrollAction {
+    return new SootWaitForScrollAction(
+      this.assertionFn,
+      this.findNode,
+      this.getPage,
+      matcher,
+    )
+  }
+}
+
+class SootWaitForScrollAction {
+  private assertionFn: () => Promise<void>
+  private findNode: FindFn
+  private getPage: GetPageFn
+  private matcher: Matcher
+
+  constructor(
+    assertionFn: () => Promise<void>,
+    findNode: FindFn,
+    getPage: GetPageFn,
+    matcher: Matcher,
+  ) {
+    this.assertionFn = assertionFn
+    this.findNode = findNode
+    this.getPage = getPage
+    this.matcher = matcher
+  }
+
+  async scroll(
+    pixels: number,
+    direction: 'up' | 'down' | 'left' | 'right',
+    _startPositionX?: number,
+    _startPositionY?: number,
+  ): Promise<void> {
+    const page = this.getPage()
+    const start = Date.now()
+    const timeoutMs = 5000
+    let lastError: Error | null = null
+
+    while (Date.now() - start < timeoutMs) {
+      try {
+        await this.assertionFn()
+        return
+      } catch (error) {
+        lastError = error as Error
+      }
+
+      await scrollMatcherElement(page, this.findNode, this.matcher, pixels, direction)
+    }
+
+    throw (
+      lastError ||
+      new Error(
+        `waitFor whileElement(...).scroll() timed out: ${JSON.stringify(this.matcher)}`,
+      )
+    )
+  }
+}