Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

41.6 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { NodeResizer, useReactFlow, useStore, type NodeProps } from '@xyflow/react'
import {
  afterTouch,
  INPUT_HELD_HINT,
  TOUCH_ANSWER_MS,
  ORIENTATION_DEGREES,
  ORIENTATION_PURPLE,
  displayLabel,
  displayToFramebuffer,
  draggedSide,
  fitNodeToScreen,
  hidUsageForCode,
  picturePreRotated,
  touchEdge,
  rotateOrientation,
  simulatorPlatformOf,
  pointerToScreenRatio,
  type SimulatorDevice,
  type SimulatorDisplayInfo,
  type SimulatorPlatform,
  type SimulatorAction,
  type SimulatorCaptureTarget,
  type SimulatorDeviceState,
  type SimulatorInput,
  type SimulatorNodeConfig,
  type SimulatorOrientation,
  type SimulatorStatusEvent,
  type TouchEdge
} from '@shared/simulator'
import { useSession } from '../session/session'
import { SIMULATOR_RELAY_HINT } from '../lib/addMenuSpec'
import { ContextMenu } from '../components/ContextMenu'
import { buildAndroidMenu, buildSimulatorMenu, type SimulatorMenuHandlers } from './simulatorMenu'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
import type { CanvasNode } from '../state/workspace'

/**
 * The Simulator node: a live iOS simulator screen on the canvas (see @shared/simulator and
 * core/simulator). The mouse is the finger — click = tap, drag = swipe, scroll wheel = a swipe —
 * the keyboard types into the device while the screen has focus, and Home / Lock are buttons.
 *
 * Frames arrive as JPEGs (only when the screen changed) and are drawn `object-fit: contain`, so the
 * phone keeps its proportions in any node size; `pointerToScreenRatio` maps a click through the
 * letterbox. The helper streams only while this node is mounted.
 */

type Phase = 'idle' | 'starting' | 'live' | 'error'

const WHEEL_END_MS = 140
/** A wheel notch moves the synthetic finger by this fraction of the screen per 100 px of delta. */
const WHEEL_SCALE = 0.25

/** A Simulator node: the view, in its own box with a title, a close button and resize handles. */
export function SimulatorNode({ id, data, selected }: NodeProps<CanvasNode>) {
  const { updateNodeData, deleteElements, setNodes } = useReactFlow()
  const config = useMemo(() => (data.simulator as SimulatorNodeConfig | undefined) ?? {}, [data.simulator])
  const dockTo = config.dockTo
  const canDock = useStore((st) => !!dockTo && st.nodeLookup.get(dockTo)?.data?.runConfig !== undefined)
  const host = useMemo<SimulatorHost>(
    () => ({
      selected: !!selected,
      color: data.color as string,
      resize: (width, height) =>
        setNodes((ns) =>
          ns.map((n) => (n.id !== id || (n.width === width && n.height === height) ? n : { ...n, width, height, style: { ...n.style, width, height } }))
        )
    }),
    [id, selected, data.color, setNodes]
  )
  const onConfig = useCallback(
    (next: SimulatorNodeConfig, pickedName?: string) =>
      updateNodeData(id, (n) => ({
        simulator: { ...next, ...(dockTo ? { dockTo } : {}) },
        ...(pickedName && n.data.titleAuto !== false ? { title: pickedName } : {})
      })),
    [id, dockTo, updateNodeData]
  )
  return (
    <SimulatorView
      streamId={id}
      config={config}
      onConfig={onConfig}
      label={(data.title as string) || config.name || 'Simulator'}
      className={`sim-node${selected ? ' selected' : ''}`}
      host={host}
      header={
        <div className="sim-node__header" style={{ background: `${data.color}22` }}>
          <span className="sim-node__title" title={data.title as string}>
            {data.title as string}
          </span>
          {canDock && dockTo && (
            <button
              className="run-bar__icon nodrag"
              title="Dock back into its run node"
              aria-label="Dock into run node"
              onClick={() => window.dispatchEvent(new CustomEvent('nodeterm:dock-preview', { detail: { nodeId: id, runNodeId: dockTo } }))}
            >
              ⇲
            </button>
          )}
          <button className="term-node__close nodrag" title="Close" onClick={() => deleteElements({ nodes: [{ id }] })}>
            ×
          </button>
        </div>
      }
    />
  )
}

/** What a standalone node gives the view: it can size the node to the screen, and draws handles. */
export interface SimulatorHost {
  selected: boolean
  color: string
  resize: (width: number, height: number) => void
}

export interface SimulatorViewProps {
  /** Keys the frame stream (`simulator:frame:<id>`): the node id, or `<runNodeId>.sim` inline. */
  streamId: string
  config: SimulatorNodeConfig
  /** A device pick (with its name) or a rotation, to persist. */
  onConfig: (next: SimulatorNodeConfig, pickedName?: string) => void
  /** Names captures. */
  label: string
  className: string
  style?: React.CSSProperties
  header?: React.ReactNode
  /** Standalone node only: fit-to-screen, Actual Size and resize handles. */
  host?: SimulatorHost
  /** Buttons appended to the toolbar (inline: pop out). */
  barExtras?: React.ReactNode
}

/**
 * The simulator screen with its toolbar, ⋯ menu and input — everything but the box around it, so a
 * Simulator node and a run node's inline panel show the same thing.
 */
export function SimulatorView(props: SimulatorViewProps) {
  // A relay tab's project belongs to another machine; its simulator nodes would otherwise stream
  // THIS machine's devices into it. Refused with the reason (the add rows are disabled there too).
  const { source } = useSession()
  if (source === 'relay') {
    return (
      <div className={props.className} style={props.style}>
        {props.header}
        <div className="sim-node__placeholder">{SIMULATOR_RELAY_HINT}.</div>
      </div>
    )
  }
  return <SimulatorViewLive {...props} />
}

function SimulatorViewLive({ streamId: id, config, onConfig, label, className, style, header, host, barExtras }: SimulatorViewProps) {
  const { api } = useSession()
  const configRef = useRef(config)
  configRef.current = config
  const udid = config.udid
  const orientation: SimulatorOrientation = config.orientation ?? 'portrait'
  const plat: SimulatorPlatform = simulatorPlatformOf(udid) ?? 'ios'
  const platRef = useRef(plat)
  platRef.current = plat
  // Read by the draw loop and the input path, which live in long-lived closures.
  const orientationRef = useRef(orientation)
  orientationRef.current = orientation
  /** The newest decoded frame, kept so a rotation can redraw it even when the device sends no new
   *  frame (an app that does not rotate leaves the framebuffer unchanged). */
  const lastBitmap = useRef<ImageBitmap | null>(null)

  const [devices, setDevices] = useState<SimulatorDevice[] | null>(null)
  /** Why a platform's list is empty when its tools could not run (no Xcode selected, no Android SDK). */
  const [listError, setListError] = useState<string | undefined>(undefined)
  const [phase, setPhase] = useState<Phase>('idle')
  const [message, setMessage] = useState<string | null>(null)
  const [displays, setDisplays] = useState<SimulatorDisplayInfo[]>([])
  const [activeDisplay, setActiveDisplay] = useState(0)
  const [pinned, setPinned] = useState(false)
  const [frameSize, setFrameSize] = useState<{ w: number; h: number } | null>(null)
  const [booting, setBooting] = useState(false)
  const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null)
  const [devState, setDevState] = useState<SimulatorDeviceState>({})
  const [recording, setRecording] = useState(false)
  const [toast, setToast] = useState<{ text: string; error?: boolean } | null>(null)
  const [prompt, setPrompt] = useState<PromptSpec | null>(null)
  const [confirm, setConfirm] = useState<ConfirmSpec | null>(null)
  const [dropping, setDropping] = useState(false)
  /** "DeviceHub may be holding the input": shown after several touches in a row changed nothing. */
  const [inputHint, setInputHint] = useState(false)
  /** Frames received so far; a touch is answered when this moves after it lifts. */
  const framesSeen = useRef(0)
  const unanswered = useRef(0)
  const touchTimers = useRef(new Set<ReturnType<typeof setTimeout>>())
  const canvasRef = useRef<HTMLCanvasElement>(null)
  const screenRef = useRef<HTMLDivElement>(null)
  const rootRef = useRef<HTMLDivElement>(null)

  const sim = devices ?? []
  const device = sim.find((d) => d.id === udid)
  const booted = device?.state === 'booted'

  const loadDevices = useCallback(
    (refresh: boolean) => {
      void api.simulator.devices(refresh).then((r) => {
        setDevices(r.devices)
        setListError([r.iosError, r.androidError].filter(Boolean).join(' ') || undefined)
      })
    },
    [api]
  )
  useEffect(() => loadDevices(false), [loadDevices])

  /** Draw the newest frame, turned to match how the device is held: the framebuffer is always
   *  portrait and iOS draws rotated content into it, so the picture is turned, as on a real panel. */
  const paint = useCallback(() => {
    const canvas = canvasRef.current
    const b = lastBitmap.current
    if (!canvas || !b) return
    // An Android emulator sends its frames already turned; only iOS frames are always portrait.
    const deg = picturePreRotated(platRef.current) ? 0 : ORIENTATION_DEGREES[orientationRef.current]
    const w = deg % 180 ? b.height : b.width
    const h = deg % 180 ? b.width : b.height
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w
      canvas.height = h
    }
    const ctx = canvas.getContext('2d')
    if (!ctx) return
    ctx.setTransform(1, 0, 0, 1, 0, 0)
    if (deg === 90) ctx.setTransform(0, 1, -1, 0, w, 0)
    else if (deg === 180) ctx.setTransform(-1, 0, 0, -1, w, h)
    else if (deg === 270) ctx.setTransform(0, -1, 1, 0, 0, h)
    ctx.drawImage(b, 0, 0)
    ctx.setTransform(1, 0, 0, 1, 0, 0)
    setFrameSize((s) => (s && s.w === w && s.h === h ? s : { w, h }))
  }, [])
  useEffect(() => paint(), [orientation, paint])

  // ── Stream ───────────────────────────────────────────────────────────────────────────────────
  useEffect(() => {
    if (!udid || !booted) {
      setPhase('idle')
      return
    }
    let live = true
    setPhase('starting')
    setMessage(null)
    // Frames are decoded straight to an ImageBitmap and drawn on a canvas. Not an <img> with a
    // blob: URL: the renderer's CSP allows img-src 'self' data: nt-media: only, so every frame was
    // a broken image — and a canvas needs no URL at all.
    let pending: { bitmap: ImageBitmap; w: number; h: number } | null = null
    let raf = 0
    let decoding = 0
    const offFrame = api.simulator.onFrame(id, (f) => {
      if (!live) return
      framesSeen.current++
      const seq = ++decoding
      void createImageBitmap(new Blob([f.jpeg as BlobPart], { type: f.mime ?? 'image/jpeg' })).then(
        (bitmap) => {
          // A newer frame decoded first (or the node went away): this one is stale.
          if (!live || seq < decoding) {
            bitmap.close()
            return
          }
          pending?.bitmap.close()
          pending = { bitmap, w: f.width, h: f.height }
          // Draw at most once per animation frame: a burst of frames shows the newest.
          if (!raf) {
            raf = requestAnimationFrame(() => {
              raf = 0
              if (!pending) return
              const { bitmap } = pending
              pending = null
              lastBitmap.current?.close()
              lastBitmap.current = bitmap
              paint()
              setPhase('live')
            })
          }
        },
        () => undefined
      )
    })
    const offStatus = api.simulator.onStatus(id, (e: SimulatorStatusEvent) => {
      if (!live) return
      if (e.kind === 'ready') {
        // Tell the device how the node holds it: after a reboot it is portrait whatever was saved.
        void api.simulator.input(id, { t: 'orientation', value: ORIENTATION_PURPLE[orientationRef.current] })
      } else if (e.kind === 'displays') {
        setDisplays(e.displays)
        setActiveDisplay(e.active)
        setPinned(e.pinned)
      } else if (e.kind === 'error') {
        setMessage(e.message)
        if (e.code !== 'hid-send' && e.code !== 'button') setPhase('error')
      } else if (e.kind === 'exited') {
        setPhase('error')
        // The helper reports why before it exits; keep that sentence when there is one.
        setMessage((prev) => prev ?? `The simulator view stopped (exit ${e.code ?? e.signal}).`)
      }
    })
    void api.simulator.start(id, udid).then((r) => {
      if (!live) return
      if (!r.ok) {
        setPhase('error')
        setMessage(r.error)
      }
    })
    return () => {
      live = false
      offFrame()
      offStatus()
      if (raf) cancelAnimationFrame(raf)
      pending?.bitmap.close()
      lastBitmap.current?.close()
      lastBitmap.current = null
      void api.simulator.stop(id)
    }
  }, [api, id, udid, booted, paint])

  // ── Fit the node to the screen ───────────────────────────────────────────────────────────────
  //
  // No black bars: whenever the screen's shape changes (first frame, a rotation, a foldable moving
  // to its other screen) the node is resized so the screen area has exactly that shape. The longer
  // side of the screen keeps its length, so a rotation turns a tall phone into a wide one of the
  // same size rather than shrinking it into the old box. The header and toolbar are measured, not
  // assumed (the toolbar wraps on a narrow node), so a second pass a frame later settles any wrap.
  // Layout pixels (offsetWidth/Height), which the canvas zoom does not touch — the same units as
  // the node's own size.
  const fitToScreen = useCallback(
    (by: 'long' | 'width' | 'height' = 'long') => {
      const root = rootRef.current
      const screen = screenRef.current
      if (!host || !root || !screen || !frameSize || screen.offsetWidth <= 0 || screen.offsetHeight <= 0) return
      const { width, height } = fitNodeToScreen({
        screenW: screen.offsetWidth,
        screenH: screen.offsetHeight,
        chromeW: root.offsetWidth - screen.offsetWidth,
        chromeH: root.offsetHeight - screen.offsetHeight,
        aspect: frameSize.w / frameSize.h,
        by,
        minW: NODE_MIN_SIZES.simulator.width,
        minH: NODE_MIN_SIZES.simulator.height
      })
      host.resize(width, height)
    },
    [frameSize, host]
  )
  /** The screen area's size when a hand resize began, to tell which side was dragged. */
  const resizeFrom = useRef<{ w: number; h: number } | null>(null)

  useEffect(() => {
    if (!frameSize) return
    fitToScreen()
    const raf = requestAnimationFrame(() => fitToScreen())
    return () => cancelAnimationFrame(raf)
    // Only when the screen's SHAPE changes — not on every frame.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [frameSize?.w, frameSize?.h])

  // ── Input ────────────────────────────────────────────────────────────────────────────────────
  const touchEdgeRef = useRef<TouchEdge>(0)
  // Touches are measured on the (turned) picture and sent in portrait framebuffer coordinates.
  const send = useCallback(
    (cmd: SimulatorInput) => {
      let out: SimulatorInput = cmd
      if (cmd.t === 'down' || cmd.t === 'move' || cmd.t === 'up') {
        const p = displayToFramebuffer(cmd.x, cmd.y, orientationRef.current)
        // The panel edge the finger went down on rides the whole contact: it is how iOS tells the
        // home swipe (up from the bottom) from a drag in the app. Android has no such flag.
        if (cmd.t === 'down') touchEdgeRef.current = platRef.current === 'ios' ? touchEdge(p.x, p.y) : 0
        const edge = touchEdgeRef.current
        out = { ...cmd, ...p, ...(edge ? { edge } : {}) }
        if (cmd.t === 'up') touchEdgeRef.current = 0
      }
      void api.simulator.input(id, out)
    },
    [api, id]
  )

  // A touch that lifted with no frame after it changed nothing on the screen (see afterTouch).
  // Counted from the finger going DOWN, so a drag that moved the screen while held is answered.
  const touchStartFrames = useRef(0)
  const watchTouch = useCallback(() => {
    // The hint is about DeviceHub holding an iOS device's input; Android has no such rule.
    if (platRef.current !== 'ios') return
    const before = touchStartFrames.current
    const t = setTimeout(() => {
      touchTimers.current.delete(t)
      const r = afterTouch(unanswered.current, framesSeen.current !== before)
      unanswered.current = r.count
      setInputHint(r.hint)
    }, TOUCH_ANSWER_MS)
    touchTimers.current.add(t)
  }, [])
  useEffect(() => {
    const timers = touchTimers.current
    return () => {
      for (const t of timers) clearTimeout(t)
      timers.clear()
    }
  }, [])
  // A different device starts with a clean slate.
  useEffect(() => {
    unanswered.current = 0
    setInputHint(false)
  }, [udid])

  const rotate = useCallback(
    (dir: 'left' | 'right') => {
      const next = rotateOrientation(orientationRef.current, dir)
      orientationRef.current = next
      onConfig({ ...configRef.current, orientation: next })
      void api.simulator.input(id, { t: 'orientation', value: ORIENTATION_PURPLE[next] })
    },
    [api, id, onConfig]
  )

  const ratioAt = useCallback(
    (clientX: number, clientY: number) => {
      const box = screenRef.current?.getBoundingClientRect()
      if (!box || !frameSize) return null
      // Client-space on both sides, so the canvas zoom cancels out.
      return pointerToScreenRatio(clientX - box.left, clientY - box.top, box.width, box.height, frameSize.w, frameSize.h)
    },
    [frameSize]
  )

  const pressed = useRef<{ x: number; y: number } | null>(null)
  const moveRaf = useRef(0)
  const onPointerDown = (e: React.PointerEvent) => {
    if (e.button !== 0 || phase !== 'live') return
    const p = ratioAt(e.clientX, e.clientY)
    screenRef.current?.focus()
    if (!p) return
    e.currentTarget.setPointerCapture(e.pointerId)
    pressed.current = p
    touchStartFrames.current = framesSeen.current
    send({ t: 'down', ...p })
    e.preventDefault()
  }
  const onPointerMove = (e: React.PointerEvent) => {
    if (!pressed.current) return
    const { clientX, clientY } = e
    if (moveRaf.current) return
    moveRaf.current = requestAnimationFrame(() => {
      moveRaf.current = 0
      const box = screenRef.current?.getBoundingClientRect()
      if (!box || !frameSize || !pressed.current) return
      // While pressed, a drag past the screen's edge pins to the edge instead of dropping out.
      const p = ratioAt(clientX, clientY) ?? clampedRatio(clientX, clientY, box, frameSize)
      pressed.current = p
      send({ t: 'move', ...p })
    })
  }
  const onPointerUp = (e: React.PointerEvent) => {
    if (!pressed.current) return
    const box = screenRef.current?.getBoundingClientRect()
    const p = ratioAt(e.clientX, e.clientY) ?? (box && frameSize ? clampedRatio(e.clientX, e.clientY, box, frameSize) : pressed.current)
    pressed.current = null
    send({ t: 'up', ...p })
    watchTouch()
  }

  // The scroll wheel becomes a swipe: a finger that goes down where the pointer is, follows the
  // wheel, and lifts once the wheel stops.
  const wheel = useRef<{ x: number; y: number; timer: ReturnType<typeof setTimeout> } | null>(null)
  const onWheel = (e: React.WheelEvent) => {
    if (phase !== 'live') return
    const box = screenRef.current?.getBoundingClientRect()
    if (!box || !frameSize) return
    if (!wheel.current) {
      const p = ratioAt(e.clientX, e.clientY)
      if (!p) return
      touchStartFrames.current = framesSeen.current
      send({ t: 'down', ...p })
      wheel.current = { ...p, timer: setTimeout(() => undefined, 0) }
    }
    const w = wheel.current
    clearTimeout(w.timer)
    w.x = Math.min(1, Math.max(0, w.x - (e.deltaX / 100) * WHEEL_SCALE))
    w.y = Math.min(1, Math.max(0, w.y - (e.deltaY / 100) * WHEEL_SCALE))
    send({ t: 'move', x: w.x, y: w.y })
    w.timer = setTimeout(() => {
      send({ t: 'up', x: w.x, y: w.y })
      wheel.current = null
      watchTouch()
    }, WHEEL_END_MS)
  }

  // Keys go to the device as physical keys (it applies its own layout and Shift). ⌘-chords stay
  // with nodeterm so the app's own shortcuts keep working while the screen has focus.
  const onKey = (down: boolean) => (e: React.KeyboardEvent) => {
    if (e.target !== e.currentTarget) return
    // ⌘V on Android: let the app's own paste happen — the screen's paste event carries the text.
    if (phase === 'live' && e.metaKey && e.code === 'KeyV' && plat === 'android') return
    // ⌘V pastes the Mac clipboard: sync it to the device, then press ⌘V there.
    if (phase === 'live' && e.metaKey && e.code === 'KeyV') {
      e.preventDefault()
      e.stopPropagation()
      if (down && !e.repeat) {
        void act({ a: 'pasteboard', dir: 'to-device' }).then(() => {
          send({ t: 'key', usage: 0xe3, down: true })
          send({ t: 'key', usage: 0x19, down: true })
          send({ t: 'key', usage: 0x19, down: false })
          send({ t: 'key', usage: 0xe3, down: false })
        })
      }
      return
    }
    // ⌘← / ⌘→ rotate, as they did in Simulator.app.
    if (phase === 'live' && e.metaKey && (e.code === 'ArrowLeft' || e.code === 'ArrowRight')) {
      e.preventDefault()
      e.stopPropagation()
      if (down && !e.repeat) rotate(e.code === 'ArrowLeft' ? 'left' : 'right')
      return
    }
    if (phase !== 'live' || (e.metaKey && e.code !== 'MetaLeft' && e.code !== 'MetaRight')) return
    const usage = hidUsageForCode(e.code)
    if (usage === undefined) return
    e.preventDefault()
    e.stopPropagation()
    if (down && e.repeat) return
    send({ t: 'key', usage, down })
  }

  // Android ⌘V: put the host's text on the device clipboard, then press Ctrl+V there (Android's own
  // paste shortcut in a text field).
  const onPaste = (e: React.ClipboardEvent) => {
    if (plat !== 'android' || phase !== 'live') return
    const text = e.clipboardData.getData('text/plain')
    e.preventDefault()
    e.stopPropagation()
    if (!text) return
    void act({ a: 'clipboard-set', text }).then(() => {
      send({ t: 'key', usage: 0xe0, down: true })
      send({ t: 'key', usage: 0x19, down: true })
      send({ t: 'key', usage: 0x19, down: false })
      send({ t: 'key', usage: 0xe0, down: false })
    })
  }

  // ── Header actions ───────────────────────────────────────────────────────────────────────────
  const pick = (value: string) => {
    const d = sim.find((x) => x.id === value)
    onConfig({ udid: value, name: d?.name }, d?.name)
  }
  const boot = async () => {
    if (!udid) return
    setBooting(true)
    setMessage(null)
    const r = await api.simulator.boot(udid)
    setBooting(false)
    if (!r.ok) setMessage(r.error)
    loadDevices(true)
  }
  const shutdown = async () => {
    if (!udid) return
    await api.simulator.shutdown(udid)
    loadDevices(true)
  }

  // ── ⋯ menu ───────────────────────────────────────────────────────────────────────────────────
  useEffect(() => {
    if (!toast) return
    const t = setTimeout(() => setToast(null), toast.error ? 6000 : 3500)
    return () => clearTimeout(t)
  }, [toast])

  const say = (r: { ok: true; message?: string } | { ok: false; error: string }) => {
    if (r.ok) {
      if (r.message) setToast({ text: r.message })
    } else setToast({ text: r.error, error: true })
  }

  const act = useCallback(
    async (a: SimulatorAction) => {
      if (!udid) return
      const r = await api.simulator.action(udid, a)
      say(r)
      if (r.ok && r.text !== undefined) api.clipboard.writeText(r.text)
      if (r.ok && (a.a === 'appearance' || a.a === 'increase-contrast' || a.a === 'content-size')) {
        void api.simulator.state(udid).then(setDevState)
      }
      if (r.ok && (a.a === 'restart' || a.a === 'erase')) loadDevices(true)
    },
    [api, udid, loadDevices]
  )

  const activeScreenID = displays[activeDisplay]?.screenID ?? 0
  const deviceName = label

  const screenshot = async (target: SimulatorCaptureTarget) => {
    if (!udid) return
    const r = await api.simulator.screenshot(udid, activeScreenID, target, deviceName)
    say(r)
    if (r.ok && target === 'canvas' && r.path) window.dispatchEvent(new CustomEvent('nodeterm:open-file', { detail: { path: r.path } }))
  }

  const toggleRecording = async () => {
    if (!udid) return
    if (recording) {
      const r = await api.simulator.stopRecording(udid)
      setRecording(false)
      say(r)
      if (r.ok && r.path) window.dispatchEvent(new CustomEvent('nodeterm:open-file', { detail: { path: r.path } }))
    } else {
      const r = await api.simulator.startRecording(udid, activeScreenID, deviceName)
      if (r.ok) setRecording(true)
      else say(r)
    }
  }
  useEffect(() => {
    if (udid) void api.simulator.isRecording(udid).then(setRecording)
  }, [api, udid])

  /** One device point per canvas point: the framebuffer's pixels over the device's scale (2× iPad,
   *  3× iPhone — the two scales current simulators use). */
  const actualSize = () => {
    const disp = displays[activeDisplay]
    const root = rootRef.current
    const screen = screenRef.current
    if (!host || !disp || !root || !screen) return
    const scale = disp.scale ?? (/ipad/i.test(device?.name ?? config.name ?? '') ? 2 : 3)
    const turned = ORIENTATION_DEGREES[orientationRef.current] % 180 !== 0
    const w = Math.round((turned ? disp.height : disp.width) / scale + (root.offsetWidth - screen.offsetWidth))
    const h = Math.round((turned ? disp.width : disp.height) / scale + (root.offsetHeight - screen.offsetHeight))
    host.resize(w, h)
  }

  const pickFile = async (kind: 'install' | 'media') => {
    const p = await api.dialog.selectFile()
    if (!p) return
    if (kind === 'install') void act({ a: 'install', path: p })
    else void act({ a: 'add-media', paths: [p] })
  }

  const openMenu = (e: React.MouseEvent) => {
    const r = (e.currentTarget as HTMLElement).getBoundingClientRect()
    setMenuAt({ x: r.left, y: r.bottom + 4 })
    if (udid) void api.simulator.state(udid).then(setDevState)
  }

  const menuHandlers: SimulatorMenuHandlers = {
      button: (name) => send({ t: 'button', name }),
      rotate,
      action: (a) => void act(a),
      screenshot: (t) => void screenshot(t),
      toggleRecording: () => void toggleRecording(),
      shutDown: () => void shutdown(),
      confirmErase: () =>
        setConfirm({
          title: 'Reset Content and Settings?',
          body: `Erases everything on “${deviceName}” — apps, data and settings — like a factory reset. It restarts afterwards.`,
          confirmLabel: 'Erase',
          onConfirm: () => void act({ a: 'erase' })
        }),
      promptCustomLocation: () =>
        setPrompt({
          title: 'Custom Location',
          fields: [
            { key: 'lat', label: 'Latitude', placeholder: '37.3349' },
            { key: 'lon', label: 'Longitude', placeholder: '-122.0090' }
          ],
          submitLabel: 'Set Location',
          onSubmit: (v) => void act({ a: 'location-set', lat: Number(v.lat), lon: Number(v.lon) })
        }),
      promptOpenUrl: () =>
        setPrompt({
          title: 'Open URL',
          fields: [{ key: 'url', label: 'URL or deep link', placeholder: 'https://… or myapp://path' }],
          submitLabel: 'Open',
          onSubmit: (v) => void act({ a: 'open-url', url: v.url })
        }),
      promptPush: () =>
        setPrompt({
          title: 'Send Push Notification',
          fields: [
            { key: 'bundleId', label: 'App bundle ID', placeholder: 'com.example.app' },
            {
              key: 'payload',
              label: 'Payload (JSON)',
              multiline: true,
              value: JSON.stringify({ aps: { alert: { title: 'Hello', body: 'From nodeterm' }, sound: 'default' } }, null, 2)
            }
          ],
          submitLabel: 'Send',
          onSubmit: (v) => void act({ a: 'push', bundleId: v.bundleId.trim(), payload: v.payload })
        }),
      promptPrivacy: (op) =>
        setPrompt({
          title: op === 'grant' ? 'Grant All Permissions' : 'Revoke All Permissions',
          fields: [{ key: 'bundleId', label: 'App bundle ID', placeholder: 'com.example.app' }],
          submitLabel: op === 'grant' ? 'Grant' : 'Revoke',
          onSubmit: (v) => void act({ a: 'privacy', op, service: 'all', bundleId: v.bundleId.trim() })
        }),
      pickInstall: () => void pickFile('install'),
      pickMedia: () => void pickFile('media'),
      actualSize: host ? actualSize : undefined,
      fitToScreen: host ? () => fitToScreen('long') : undefined
    }
  const menuItems =
    plat === 'android'
      ? buildAndroidMenu(menuHandlers, { device: devState })
      : buildSimulatorMenu(menuHandlers, { device: devState, recording })

  // Drop a built .app to install it, photos/videos to add them to the library.
  const onDrop = (e: React.DragEvent) => {
    e.preventDefault()
    setDropping(false)
    if (!udid || phase !== 'live') return
    const paths = Array.from(e.dataTransfer.files)
      .map((f) => window.nodeTerminal.getPathForFile(f))
      .filter(Boolean)
    const apps = paths.filter((p) => (plat === 'android' ? /\.apks?$/i : /\.app\/?$/).test(p))
    const media = paths.filter((p) => /\.(png|jpe?g|gif|heic|heif|webp|mov|mp4|m4v)$/i.test(p))
    for (const app of apps) void act({ a: 'install', path: app.replace(/\/$/, '') })
    if (media.length) void act({ a: 'add-media', paths: media })
    if (!apps.length && !media.length)
      setToast({
        text: plat === 'android' ? 'Drop an .apk to install it, or photos and videos to add them to Pictures.' : 'Drop a built .app to install it, or photos and videos to add them to Photos.',
        error: true
      })
  }

  const statusText =
    booting
      ? 'Booting…'
      : phase === 'starting'
        ? 'Connecting…'
        : phase === 'live'
          ? ''
          : !udid
            ? ''
            : device && !booted
              ? 'Shut down'
              : ''

  const twins = useMemo(() => new Set(sim.filter((d, i) => sim.findIndex((o) => o.name === d.name && o.os === d.os) !== i).map((d) => `${d.name}|${d.os}`)), [sim])
  const deviceLabel = (d: SimulatorDevice) =>
    `${d.name}${d.os ? ` · ${d.os}` : ''}${twins.has(`${d.name}|${d.os}`) ? ` · ${d.id.replace(/^avd:/, '').slice(0, 4)}` : ''}${d.state === 'booted' ? '' : ' (off)'}`
  const iosDevices = sim.filter((d) => d.platform === 'ios')
  const androidDevices = sim.filter((d) => d.platform === 'android')

  return (
    <>
      <div ref={rootRef} className={className} style={style}>
        {header}
        <div className="sim-node__bar nodrag nowheel">
          <select className="run-bar__select sim-node__device" value={udid ?? ''} onChange={(e) => pick(e.target.value)}>
            {!udid && <option value="">{devices ? 'Pick a simulator…' : 'Loading…'}</option>}
            {udid && !device && <option value={udid}>{config.name ?? udid}</option>}
            {iosDevices.length > 0 && (
              <optgroup label="iOS">
                {iosDevices.map((d) => (
                  <option key={d.id} value={d.id}>
                    {deviceLabel(d)}
                  </option>
                ))}
              </optgroup>
            )}
            {androidDevices.length > 0 && (
              <optgroup label="Android">
                {androidDevices.map((d) => (
                  <option key={d.id} value={d.id}>
                    {deviceLabel(d)}
                  </option>
                ))}
              </optgroup>
            )}
          </select>
          <button className="run-bar__icon" title="Refresh simulators" onClick={() => loadDevices(true)}>
            ⟳
          </button>
          {udid && device && !booted && (
            <button className="run-bar__btn run-bar__btn--run" disabled={booting} onClick={() => void boot()}>
              Boot
            </button>
          )}
          {displays.length > 1 && (
            <select
              className="run-bar__select"
              title="Which screen to show (a foldable has two)"
              value={pinned ? String(activeDisplay) : '-1'}
              onChange={(e) => send({ t: 'display', index: Number(e.target.value) })}
            >
              <option value="-1">Auto ({displayLabel(displays[activeDisplay] ?? displays[0], displays)})</option>
              {displays.map((d) => (
                <option key={d.index} value={d.index}>
                  {displayLabel(d, displays)}
                </option>
              ))}
            </select>
          )}
          <span className="run-bar__spacer" />
          {phase === 'live' && (
            <>
              <button className="run-bar__icon" title="Rotate left (⌘←)" onClick={() => rotate('left')}>
                ↺
              </button>
              <button className="run-bar__icon" title="Rotate right (⌘→)" onClick={() => rotate('right')}>
                ↻
              </button>
              {plat === 'android' && (
                <button className="run-bar__icon" title="Back" onClick={() => send({ t: 'button', name: 'back' })}>
                  ◁
                </button>
              )}
              <button className="run-bar__icon" title="Home" onClick={() => send({ t: 'button', name: 'home' })}>
                ⌂
              </button>
              {plat === 'android' && (
                <button className="run-bar__icon" title="Recent apps" onClick={() => send({ t: 'button', name: 'recents' })}>
                  ▢
                </button>
              )}
              <button className="run-bar__icon" title="Lock / side button" onClick={() => send({ t: 'button', name: 'lock' })}>
                ⏻
              </button>
              <button className="run-bar__icon" title="Shut down this simulator" onClick={() => void shutdown()}>
                ⏏
              </button>
            </>
          )}
          {recording && (
            <button className="sim-node__rec" title="Recording — click to stop" onClick={() => void toggleRecording()}>
              ● REC
            </button>
          )}
          {udid && booted && (
            <button className="run-bar__icon" title={plat === 'android' ? 'More' : 'More (everything DeviceHub offers)'} aria-label="More" onClick={openMenu}>
              ⋯
            </button>
          )}
          {statusText && <span className="run-bar__status">{statusText}</span>}
          {barExtras}
        </div>
        <div
          ref={screenRef}
          className="sim-node__screen nodrag nowheel"
          tabIndex={0}
          onPointerDown={onPointerDown}
          onPointerMove={onPointerMove}
          onPointerUp={onPointerUp}
          onPointerCancel={onPointerUp}
          onWheel={onWheel}
          onKeyDown={onKey(true)}
          onKeyUp={onKey(false)}
          onPaste={onPaste}
          onDragOver={(e) => {
            if (phase !== 'live') return
            e.preventDefault()
            setDropping(true)
          }}
          onDragLeave={() => setDropping(false)}
          onDrop={onDrop}
        >
          <canvas ref={canvasRef} className="sim-node__frame" style={{ visibility: phase === 'live' ? 'visible' : 'hidden' }} />
          {phase !== 'live' && (
            <div className="sim-node__placeholder">
              {!udid
                ? `Pick a simulator above.${listError ? ` ${listError}` : ''}`
                : device && !booted
                  ? 'This simulator is shut down — Boot it to see its screen.'
                  : phase === 'starting'
                    ? plat === 'android'
                      ? 'Connecting to the emulator…'
                      : 'Connecting to the simulator… (the first time builds a small helper with Xcode)'
                    : (message ?? '')}
            </div>
          )}
          {phase === 'live' && message && <div className="sim-node__note">{message}</div>}
          {phase === 'live' && inputHint && (
            <div className="sim-node__hint" role="status">
              <span>{INPUT_HELD_HINT}</span>
              <button
                className="sim-node__hint-close"
                aria-label="Dismiss"
                onPointerDown={(e) => e.stopPropagation()}
                onClick={() => {
                  unanswered.current = 0
                  setInputHint(false)
                }}
              >
                ×
              </button>
            </div>
          )}
          {dropping && <div className="sim-node__drop">Drop a .app to install · photos or videos to add</div>}
        </div>
        {toast && <div className={`sim-node__toast${toast.error ? ' sim-node__toast--error' : ''}`}>{toast.text}</div>}
        {prompt && <SimPrompt spec={prompt} onClose={() => setPrompt(null)} />}
        {confirm && (
          <div className="sim-node__overlay nodrag nowheel">
            <div className="sim-node__dialog">
              <div className="sim-node__dialog-title">{confirm.title}</div>
              <div className="sim-node__dialog-body">{confirm.body}</div>
              <div className="sim-node__dialog-actions">
                <button className="run-bar__btn" onClick={() => setConfirm(null)}>
                  Cancel
                </button>
                <button
                  className="run-bar__btn run-bar__btn--stop"
                  onClick={() => {
                    confirm.onConfirm()
                    setConfirm(null)
                  }}
                >
                  {confirm.confirmLabel}
                </button>
              </div>
            </div>
          </div>
        )}
      </div>
      {menuAt && <ContextMenu x={menuAt.x} y={menuAt.y} items={menuItems} onClose={() => setMenuAt(null)} />}
      {host && (
      <NodeResizer
        minWidth={NODE_MIN_SIZES.simulator.width}
        minHeight={NODE_MIN_SIZES.simulator.height}
        isVisible={host.selected}
        color={host.color}
        // A hand resize snaps to the screen's shape when it ends, following the side that was
        // dragged — widen it and the height follows; make it taller and the width follows.
        onResizeStart={() => {
          const sc = screenRef.current
          resizeFrom.current = sc ? { w: sc.offsetWidth, h: sc.offsetHeight } : null
        }}
        onResizeEnd={() =>
          requestAnimationFrame(() => {
            const sc = screenRef.current
            const from = resizeFrom.current
            resizeFrom.current = null
            fitToScreen(sc && from ? draggedSide(from, { w: sc.offsetWidth, h: sc.offsetHeight }) : 'long')
          })
        }
      />
      )}
    </>
  )
}

/** A point outside the drawn screen, pinned to its nearest edge (a drag that leaves the screen). */
function clampedRatio(clientX: number, clientY: number, box: DOMRect, frame: { w: number; h: number }) {
  const scale = Math.min(box.width / frame.w, box.height / frame.h)
  const left = box.left + (box.width - frame.w * scale) / 2
  const top = box.top + (box.height - frame.h * scale) / 2
  return {
    x: Math.min(1, Math.max(0, (clientX - left) / (frame.w * scale))),
    y: Math.min(1, Math.max(0, (clientY - top) / (frame.h * scale)))
  }
}

interface PromptField {
  key: string
  label: string
  placeholder?: string
  multiline?: boolean
  value?: string
}
interface PromptSpec {
  title: string
  fields: PromptField[]
  submitLabel: string
  onSubmit: (values: Record<string, string>) => void
}
interface ConfirmSpec {
  title: string
  body: string
  confirmLabel: string
  onConfirm: () => void
}

/** A small in-node form for the menu items that need a value (URL, push payload, coordinates). */
function SimPrompt({ spec, onClose }: { spec: PromptSpec; onClose: () => void }) {
  const [values, setValues] = useState<Record<string, string>>(() =>
    Object.fromEntries(spec.fields.map((f) => [f.key, f.value ?? '']))
  )
  const submit = () => {
    spec.onSubmit(values)
    onClose()
  }
  return (
    <div className="sim-node__overlay nodrag nowheel" onKeyDown={(e) => e.stopPropagation()}>
      <form
        className="sim-node__dialog"
        onSubmit={(e) => {
          e.preventDefault()
          submit()
        }}
        onKeyDown={(e) => {
          if (e.key === 'Escape') onClose()
        }}
      >
        <div className="sim-node__dialog-title">{spec.title}</div>
        {spec.fields.map((f, i) => (
          <label key={f.key} className="sim-node__field">
            <span>{f.label}</span>
            {f.multiline ? (
              <textarea
                autoFocus={i === 0}
                rows={7}
                spellCheck={false}
                value={values[f.key]}
                placeholder={f.placeholder}
                onChange={(e) => setValues((v) => ({ ...v, [f.key]: e.target.value }))}
              />
            ) : (
              <input
                autoFocus={i === 0}
                spellCheck={false}
                value={values[f.key]}
                placeholder={f.placeholder}
                onChange={(e) => setValues((v) => ({ ...v, [f.key]: e.target.value }))}
              />
            )}
          </label>
        ))}
        <div className="sim-node__dialog-actions">
          <button type="button" className="run-bar__btn" onClick={onClose}>
            Cancel
          </button>
          <button type="submit" className="run-bar__btn run-bar__btn--run">
            {spec.submitLabel}
          </button>
        </div>
      </form>
    </div>
  )
}