rnxsim 0.1.313 → 0.1.315

package/cli/commands/three-mode.ts

@@ -0,0 +1,763 @@
+// sootsim mode three — toggle the live browser 3d device stage.
+//
+// wraps the existing `toggle-three-mode` shell action so CLI, rail, and
+// menu all use the same plugin-owned state path.
+
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, extname, resolve } from 'node:path'
+import {
+  callInBridgeWrite,
+  createBridgeFromParsed,
+  parseBridgeCliArgs,
+  type WsBridge,
+} from '../ws-bridge'
+import { runShellBooleanMode, type ShellBooleanModeOptions } from './shell-boolean-mode'
+
+type ThreeModeConfig = Record<string, unknown>
+type ThreeModeState = Record<string, unknown> & {
+  ready?: boolean
+  disabled?: boolean
+}
+
+const THREE_MODE_READY_TIMEOUT_MS = 12_000
+// a supersampled path-traced frame (soft-orbs export) legitimately spends
+// minutes on shader compile + sample convergence on slower GPUs; raster
+// timeline batches stay far under this either way.
+const THREE_MODE_RENDER_TIMEOUT_MS = 600_000
+const TIMELINE_ACTIONS = new Set(['load', 'seek', 'play', 'pause', 'render', 'measure'])
+
+export async function runThreeMode(args: string[], opts: ShellBooleanModeOptions) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+rnxsim mode three — toggle the 3d device stage
+
+usage:
+  rnxsim mode three [on|off|toggle]
+  rnxsim mode three configure [options]
+  rnxsim mode three load <timeline.json>
+  rnxsim mode three seek <time-ms>
+  rnxsim mode three play|pause
+  rnxsim mode three render <timeline.json> --output <dir> [options]
+  rnxsim mode three measure <timeline.json> [options]
+
+arguments:
+  on        enable 3d mode
+  off       disable 3d mode
+  toggle    flip the current state (default)
+
+configure options:
+  --device <id>          set the phone body: iphone-17-air | iphone-17-pro |
+                         pixel-10 (a film authors its own via initial.device)
+  --background <id>      set the 3d background
+  --gradient <stops>     custom gradient bg: comma-separated css hex stops,
+                         e.g. "#0a0e1a,#16243f,#05080f" (overrides --background;
+                         evenly spaced, or use "color@offset" for explicit %)
+  --gradient-angle <deg> custom gradient angle (default 180 = top→bottom)
+  --colorway <id>        set the phone colorway
+  --script <id>          apply a camera preset pose
+  --progress <0..1>      script progress to sample (default: 1)
+  --animate              run the script instead of sampling one frame
+  --slow                 run the script slowly when --animate is set
+  --environment on|off   enable or disable environment objects
+  --env-shape <id>       orb | pill | diamond | pane
+  --env-spread <id>      tight | medium | wide
+  --env-size <id>        small | medium | large
+  --env-color <id>       peach | gold | mint | sky | violet
+  --env-glow on|off      enable or disable environment glow
+  --env-plastic on|off   enable or disable environment plastic material
+  --setting <id>         none | room | white-backdrop
+  --focus on|off         enable or disable Focus depth of field
+  --focus-amount <id>    subtle | medium | strong | intense | extreme
+  --focus-range <id>     tight | balanced | wide
+  --reset-pose           return to the default hero pose before other changes
+
+render options:
+  --output <dir>         write frame-%05d.png + timeline-render.json
+  --fps <number>         frames per second (default: 30)
+  --width <px>           exact output width (default: 1920)
+  --height <px>          exact output height (default: 1080)
+  --from <ms>            first timeline time (default: 0)
+  --to <ms>              exclusive end time (default: timeline duration)
+  --overwrite            replace this command's existing frames in the dir
+
+measure options (projected bounds only — no pixels rendered):
+  --fps <number>         sample rate (default: 30)
+  --width <px>           output width the bounds project into (default: 1920)
+  --height <px>          output height the bounds project into (default: 1080)
+  --from <ms>            first timeline time (default: 0)
+  --to <ms>              exclusive end time (default: timeline duration)
+  --count <n>            sample n frames from --from at the --fps spacing
+  --at <ms[,ms...]>      sample exact timeline times (overrides from/to/count)
+  --output <file.json>   write the measurement JSON here instead of stdout
+
+examples:
+  rnxsim mode three
+  rnxsim mode three on
+  rnxsim mode three configure --script hero-arc --background gradient-tide
+  rnxsim mode three configure --environment on --env-shape pane --setting room
+  rnxsim mode three render ./cinematic.json --output ./frames --fps 30
+  rnxsim mode three measure ./cinematic.json --width 450 --height 900 --at 0,1200
+  rnxsim mode three off
+`)
+    process.exit(0)
+  }
+
+  const timelineAction = findTimelineAction(args)
+  if (timelineAction) {
+    await runThreeModeTimelineAction(timelineAction, args, opts)
+    return
+  }
+
+  if (shouldConfigure(args)) {
+    await runThreeModeConfigure(args, opts)
+    return
+  }
+
+  const result = await runShellBooleanMode(args, opts, {
+    modeKey: 'threeMode',
+    displayName: 'three-mode',
+    actionId: 'toggle-three-mode',
+  })
+  if (result.target) {
+    await waitForThreeModeRuntimeReady(args, opts)
+  }
+}
+
+function shouldConfigure(args: string[]) {
+  return (
+    args[0] === 'configure' ||
+    args.some((arg) =>
+      [
+        '--device',
+        '--background',
+        '--gradient',
+        '--gradient-angle',
+        '--colorway',
+        '--script',
+        '--progress',
+        '--animate',
+        '--slow',
+        '--environment',
+        '--env-shape',
+        '--env-spread',
+        '--env-size',
+        '--env-color',
+        '--env-glow',
+        '--env-plastic',
+        '--setting',
+        '--focus',
+        '--focus-amount',
+        '--focus-range',
+        '--reset-pose',
+      ].includes(arg),
+    )
+  )
+}
+
+async function runThreeModeConfigure(args: string[], opts: ShellBooleanModeOptions) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: ['--animate', '--slow', '--reset-pose'],
+    stripValueFlags: [
+      '--device',
+      '--background',
+      '--gradient',
+      '--gradient-angle',
+      '--colorway',
+      '--script',
+      '--progress',
+      '--environment',
+      '--env-shape',
+      '--env-spread',
+      '--env-size',
+      '--env-color',
+      '--env-glow',
+      '--env-plastic',
+      '--setting',
+      '--focus',
+      '--focus-amount',
+      '--focus-range',
+    ],
+  })
+  const options = buildConfigureOptions(args)
+  const bridge = createBridgeFromParsed({
+    ...parsed,
+    commandTimeoutMs: THREE_MODE_READY_TIMEOUT_MS + 1000,
+  })
+  try {
+    await waitForThreeModeRuntimeReadyOnBridge(bridge)
+    const state = await callInBridgeWrite<Record<string, unknown>>(
+      bridge,
+      'SootSim.bridges.threeMode.configure',
+      options,
+    )
+    console.log(`  three-mode: configured (${summarizeState(state)})`)
+  } finally {
+    bridge.close()
+  }
+}
+
+async function waitForThreeModeRuntimeReady(
+  args: string[],
+  opts: ShellBooleanModeOptions,
+) {
+  const parsed = parseBridgeCliArgs(args, { port: opts.port })
+  const bridge = createBridgeFromParsed({
+    ...parsed,
+    commandTimeoutMs: THREE_MODE_READY_TIMEOUT_MS + 1000,
+  })
+  try {
+    await waitForThreeModeRuntimeReadyOnBridge(bridge)
+  } finally {
+    bridge.close()
+  }
+}
+
+export async function waitForThreeModeRuntimeReadyOnBridge(bridge: WsBridge) {
+  const state = (await bridge.send({
+    type: 'evaluate',
+    code: `(async () => {
+      const deadline = Date.now() + ${THREE_MODE_READY_TIMEOUT_MS}
+      while (Date.now() < deadline) {
+        const settings = window.SootSim?.bridges?.settings?.get?.()
+        if (settings && settings.threeMode !== true) {
+          return { ready: false, disabled: true }
+        }
+        const bridge = window.SootSim?.bridges?.threeMode
+        const state = typeof bridge?.getState === 'function' ? bridge.getState() : null
+        if (state?.ready === true) return state
+        await new Promise((resolve) => setTimeout(resolve, 50))
+      }
+      const bridge = window.SootSim?.bridges?.threeMode
+      const state = typeof bridge?.getState === 'function' ? bridge.getState() : null
+      return state || { ready: false }
+    })()`,
+  })) as ThreeModeState | null
+
+  if (state?.ready === true) return state
+  if (state?.disabled) {
+    throw new Error('3d mode is off; run `rnxsim mode three on` before configure')
+  }
+  throw new Error('3d mode runtime did not become ready')
+}
+
+type TimelineSampleResult = {
+  durationMs: number
+  timeMs: number
+  shotId: string | null
+}
+
+type TimelineRenderedFrame = {
+  index: number
+  timeMs: number
+  width: number
+  height: number
+  dataUrl: string
+  alpha: {
+    min: number
+    max: number
+    transparentPixels: number
+  }
+  phoneCollision: {
+    hull: Array<{ x: number; y: number }>
+  }
+}
+
+type TimelineRenderedFrames = {
+  frames: TimelineRenderedFrame[]
+}
+
+type TimelineMeasuredFrame = {
+  index: number
+  timeMs: number
+  camera: {
+    position: [number, number, number]
+    target: [number, number, number]
+    fov: number
+  }
+  targets: Record<
+    string,
+    {
+      hull: Array<{ x: number; y: number }>
+      bounds: { left: number; right: number; top: number; bottom: number }
+    }
+  >
+}
+
+type TimelineMeasuredFrames = {
+  fps: number
+  from: number
+  to: number
+  width: number
+  height: number
+  frames: TimelineMeasuredFrame[]
+}
+
+function findTimelineAction(args: string[]): string | null {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--sim' || arg === '--port' || arg === '-p') {
+      index += 1
+      continue
+    }
+    if (arg.startsWith('-')) continue
+    return TIMELINE_ACTIONS.has(arg) ? arg : null
+  }
+  return null
+}
+
+function readFlagValue(args: string[], flag: string) {
+  const index = args.indexOf(flag)
+  return index >= 0 ? args[index + 1] : undefined
+}
+
+function readNumberFlag(args: string[], flag: string, fallback: number, minimum = 0) {
+  const raw = readFlagValue(args, flag)
+  if (raw === undefined) return fallback
+  const value = Number.parseFloat(raw)
+  if (!Number.isFinite(value) || value < minimum) {
+    throw new Error(`${flag} expects a number greater than or equal to ${minimum}`)
+  }
+  return value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function mimeTypeForAsset(path: string, contentType: unknown) {
+  const extension = extname(path).toLowerCase()
+  if (contentType === 'recording') {
+    if (extension === '.mp4' || extension === '.m4v') return 'video/mp4'
+    return 'video/webm'
+  }
+  if (extension === '.jpg' || extension === '.jpeg') return 'image/jpeg'
+  if (extension === '.webp') return 'image/webp'
+  return 'image/png'
+}
+
+function inlineTimelineAssets(value: unknown, baseDirectory: string): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => inlineTimelineAssets(entry, baseDirectory))
+  }
+  if (!isRecord(value)) return value
+
+  const result: Record<string, unknown> = {}
+  for (const [key, entry] of Object.entries(value)) {
+    result[key] = inlineTimelineAssets(entry, baseDirectory)
+  }
+  if (
+    (result.type === 'recording' ||
+      result.type === 'screenshot' ||
+      result.kind === 'screen') &&
+    typeof result.src === 'string' &&
+    !/^(?:blob:|data:|https?:)/i.test(result.src)
+  ) {
+    const assetPath = resolve(baseDirectory, result.src)
+    const bytes = readFileSync(assetPath)
+    result.src = `data:${mimeTypeForAsset(assetPath, result.type === 'recording' ? 'recording' : 'screenshot')};base64,${bytes.toString('base64')}`
+  }
+  return result
+}
+
+function readTimelineFile(path: string) {
+  const absolutePath = resolve(path)
+  const parsed: unknown = JSON.parse(readFileSync(absolutePath, 'utf8'))
+  return {
+    absolutePath,
+    timeline: inlineTimelineAssets(parsed, dirname(absolutePath)),
+  }
+}
+
+async function ensureThreeModeRuntimeOnBridge(bridge: WsBridge) {
+  await callInBridgeWrite(bridge, 'SootSim.bridges.settings.set', 'threeMode', true)
+  await waitForThreeModeRuntimeReadyOnBridge(bridge)
+}
+
+async function runThreeModeTimelineAction(
+  action: string,
+  args: string[],
+  opts: ShellBooleanModeOptions,
+) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: THREE_MODE_RENDER_TIMEOUT_MS,
+    stripBooleanFlags: ['--overwrite'],
+    stripValueFlags: [
+      '--output',
+      '--fps',
+      '--width',
+      '--height',
+      '--from',
+      '--to',
+      '--count',
+      '--at',
+    ],
+  })
+  const bridge = createBridgeFromParsed(parsed)
+  try {
+    await ensureThreeModeRuntimeOnBridge(bridge)
+    if (action === 'seek') {
+      const rawTime = parsed.positional[1]
+      const timeMs = rawTime === undefined ? Number.NaN : Number.parseFloat(rawTime)
+      if (!Number.isFinite(timeMs)) throw new Error('three-mode seek expects time in ms')
+      const sample = await callInBridgeWrite<TimelineSampleResult>(
+        bridge,
+        'SootSim.bridges.threeMode.seek',
+        timeMs,
+      )
+      console.log(
+        `  three-mode: ${Math.round(sample.timeMs)}ms / ${Math.round(sample.durationMs)}ms (${sample.shotId ?? 'no shot'})`,
+      )
+      return
+    }
+    if (action === 'play' || action === 'pause') {
+      const state = await callInBridgeWrite<Record<string, unknown>>(
+        bridge,
+        `SootSim.bridges.threeMode.${action}`,
+      )
+      const timeline = isRecord(state.timeline) ? state.timeline : {}
+      console.log(
+        `  three-mode: ${action} (${Math.round(Number(timeline.timeMs ?? 0))}ms)`,
+      )
+      return
+    }
+
+    const timelinePath = parsed.positional[1]
+    if (!timelinePath)
+      throw new Error(`three-mode ${action} expects a timeline JSON path`)
+    const loadedFile = readTimelineFile(timelinePath)
+    const loaded = await callInBridgeWrite<TimelineSampleResult>(
+      bridge,
+      'SootSim.bridges.threeMode.loadTimeline',
+      loadedFile.timeline,
+    )
+    if (action === 'load') {
+      console.log(
+        `  three-mode: loaded ${loadedFile.absolutePath} (${Math.round(loaded.durationMs)}ms)`,
+      )
+      return
+    }
+
+    if (action === 'measure') {
+      const fps = readNumberFlag(args, '--fps', 30, 0.001)
+      const width = Math.round(readNumberFlag(args, '--width', 1_920, 1))
+      const height = Math.round(readNumberFlag(args, '--height', 1_080, 1))
+      const atValue = readFlagValue(args, '--at')
+      let measured: TimelineMeasuredFrames
+      if (atValue !== undefined) {
+        const times = atValue.split(',').map((token) => {
+          const value = Number.parseFloat(token)
+          if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`--at expects comma-separated times in ms, got "${token}"`)
+          }
+          return Math.min(value, loaded.durationMs)
+        })
+        const frames: TimelineMeasuredFrame[] = []
+        for (const timeMs of times) {
+          const single = await callInBridgeWrite<TimelineMeasuredFrames>(
+            bridge,
+            'SootSim.bridges.threeMode.measure',
+            { fps, width, height, from: timeMs, count: 1 },
+          )
+          frames.push({ ...single.frames[0], index: frames.length })
+        }
+        measured = {
+          fps,
+          from: times[0],
+          to: times[times.length - 1],
+          width,
+          height,
+          frames,
+        }
+      } else {
+        const from = readNumberFlag(args, '--from', 0, 0)
+        const countValue = readFlagValue(args, '--count')
+        const options: {
+          fps: number
+          width: number
+          height: number
+          from: number
+          to?: number
+          count?: number
+        } = { fps, width, height, from }
+        if (countValue === undefined) {
+          const to = readNumberFlag(args, '--to', loaded.durationMs, 0)
+          if (to <= from || to > loaded.durationMs) {
+            throw new Error(
+              `--to must be greater than --from and at most ${loaded.durationMs}`,
+            )
+          }
+          options.to = to
+        } else {
+          options.count = Math.round(readNumberFlag(args, '--count', 1, 1))
+        }
+        measured = await callInBridgeWrite<TimelineMeasuredFrames>(
+          bridge,
+          'SootSim.bridges.threeMode.measure',
+          options,
+        )
+      }
+      const json = `${JSON.stringify(measured, null, 2)}\n`
+      const outputValue = readFlagValue(args, '--output')
+      if (outputValue) {
+        const outputPath = resolve(outputValue)
+        mkdirSync(dirname(outputPath), { recursive: true })
+        writeFileSync(outputPath, json)
+        // stderr keeps a caller piping stdout (phone-film bounds) JSON-clean.
+        process.stderr.write(
+          `  three-mode: measured ${measured.frames.length} frames → ${outputPath}\n`,
+        )
+      } else {
+        process.stdout.write(json)
+      }
+      return
+    }
+
+    const outputValue = readFlagValue(args, '--output')
+    if (!outputValue) throw new Error('three-mode render requires --output <dir>')
+    const outputDirectory = resolve(outputValue)
+    const fps = readNumberFlag(args, '--fps', 30, 0.001)
+    const width = Math.round(readNumberFlag(args, '--width', 1_920, 1))
+    const height = Math.round(readNumberFlag(args, '--height', 1_080, 1))
+    const from = readNumberFlag(args, '--from', 0, 0)
+    const to = readNumberFlag(args, '--to', loaded.durationMs, 0)
+    if (to <= from || to > loaded.durationMs) {
+      throw new Error(`--to must be greater than --from and at most ${loaded.durationMs}`)
+    }
+    const frameDurationMs = 1_000 / fps
+    const frameCount = Math.ceil((to - from) / frameDurationMs)
+    mkdirSync(outputDirectory, { recursive: true })
+    const ownedOutputs = readdirSync(outputDirectory).filter(
+      (name) => /^frame-\d{5}\.png$/.test(name) || name === 'timeline-render.json',
+    )
+    if (ownedOutputs.length > 0 && !args.includes('--overwrite')) {
+      throw new Error(
+        `${outputDirectory} already has timeline frames; pass --overwrite to replace them`,
+      )
+    }
+    for (const name of ownedOutputs) unlinkSync(resolve(outputDirectory, name))
+
+    const manifestFrames: Array<{
+      file: string
+      timeMs: number
+      sha256: string
+      alpha: TimelineRenderedFrame['alpha']
+      phoneCollision: TimelineRenderedFrame['phoneCollision']
+    }> = []
+    const batchSize = 4
+    for (let frameIndex = 0; frameIndex < frameCount; frameIndex += batchSize) {
+      const count = Math.min(batchSize, frameCount - frameIndex)
+      const batchFrom = from + frameIndex * frameDurationMs
+      const batchTo = Math.min(to, batchFrom + count * frameDurationMs)
+      const rendered = await callInBridgeWrite<TimelineRenderedFrames>(
+        bridge,
+        'SootSim.bridges.threeMode.renderFrames',
+        { fps, from: batchFrom, to: batchTo, width, height, count },
+      )
+      if (rendered.frames.length !== count) {
+        throw new Error(
+          `3d renderer returned ${rendered.frames.length} frames for a ${count}-frame batch`,
+        )
+      }
+      for (const frame of rendered.frames) {
+        const globalIndex = frameIndex + frame.index
+        const file = `frame-${String(globalIndex).padStart(5, '0')}.png`
+        const separator = frame.dataUrl.indexOf(',')
+        if (
+          separator < 0 ||
+          !frame.dataUrl.slice(0, separator).includes('image/png;base64')
+        ) {
+          throw new Error(`3d renderer returned a non-PNG frame at ${frame.timeMs}ms`)
+        }
+        const bytes = Buffer.from(frame.dataUrl.slice(separator + 1), 'base64')
+        writeFileSync(resolve(outputDirectory, file), bytes)
+        manifestFrames.push({
+          file,
+          timeMs: frame.timeMs,
+          sha256: createHash('sha256').update(bytes).digest('hex'),
+          alpha: frame.alpha,
+          phoneCollision: frame.phoneCollision,
+        })
+      }
+      process.stderr.write(
+        `\r  three-mode: rendered ${Math.min(frameIndex + count, frameCount)}/${frameCount}`,
+      )
+    }
+    process.stderr.write('\n')
+
+    const manifest = {
+      version: 2,
+      timeline: loadedFile.absolutePath,
+      fps,
+      from,
+      to,
+      width,
+      height,
+      frameCount,
+      transparent: manifestFrames.every((frame) => frame.alpha.transparentPixels > 0),
+      frames: manifestFrames,
+    }
+    writeFileSync(
+      resolve(outputDirectory, 'timeline-render.json'),
+      `${JSON.stringify(manifest, null, 2)}\n`,
+    )
+    console.log(
+      `  three-mode: wrote ${frameCount} deterministic RGBA frames to ${outputDirectory}`,
+    )
+  } finally {
+    bridge.close()
+  }
+}
+
+export function buildConfigureOptions(args: string[]): ThreeModeConfig {
+  const value = (flag: string) => args.find((_, i) => args[i - 1] === flag)
+  const options: ThreeModeConfig = {}
+
+  // the body itself. a timeline authors this through initial.device; this
+  // flag is for driving the live stage by hand.
+  const device = value('--device')
+  if (device) {
+    if (
+      device !== 'iphone-17-air' &&
+      device !== 'iphone-17-pro' &&
+      device !== 'pixel-10'
+    ) {
+      throw new Error(
+        `--device expects iphone-17-air, iphone-17-pro, or pixel-10, got "${device}"`,
+      )
+    }
+    options.device = device
+  }
+
+  const colorway = value('--colorway')
+  if (colorway) options.colorway = colorway
+
+  const background = value('--background')
+  if (background) options.background = background
+
+  // custom gradient: "color[@offset],color[@offset],…". offsets are
+  // 0..1 or 0..100 (auto-detected); omitted offsets spread evenly.
+  const gradient = value('--gradient')
+  if (gradient) {
+    const raw = gradient
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+    const stops = raw.map((token, i) => {
+      const [color, offsetStr] = token.split('@')
+      let offset =
+        offsetStr !== undefined
+          ? Number.parseFloat(offsetStr)
+          : raw.length > 1
+            ? i / (raw.length - 1)
+            : 0
+      if (offset > 1) offset = offset / 100
+      if (!Number.isFinite(offset)) offset = raw.length > 1 ? i / (raw.length - 1) : 0
+      return { color: color.trim(), offset }
+    })
+    const angleStr = value('--gradient-angle')
+    const angleDeg = angleStr === undefined ? undefined : Number.parseFloat(angleStr)
+    if (angleStr !== undefined && !Number.isFinite(angleDeg)) {
+      throw new Error(`--gradient-angle expects a number, got "${angleStr}"`)
+    }
+    options.customGradient = { stops, ...(angleDeg !== undefined ? { angleDeg } : {}) }
+  }
+
+  const setting = value('--setting')
+  if (setting) {
+    if (setting !== 'none' && setting !== 'room' && setting !== 'white-backdrop') {
+      throw new Error(`--setting expects none, room, or white-backdrop, got "${setting}"`)
+    }
+    options.setting = setting
+  }
+
+  const focus: Record<string, unknown> = {}
+  const focusEnabled = parseBooleanValue(value('--focus'), '--focus')
+  if (focusEnabled !== undefined) focus.enabled = focusEnabled
+  for (const [flag, key] of [
+    ['--focus-amount', 'amount'],
+    ['--focus-range', 'range'],
+  ] as const) {
+    const setting = value(flag)
+    if (setting) focus[key] = setting
+  }
+  if (Object.keys(focus).length > 0) options.focus = focus
+
+  if (args.includes('--reset-pose')) options.resetPose = true
+
+  const environment = parseBooleanValue(value('--environment'), '--environment')
+  const pins: Record<string, string> = {}
+  const effects: Record<string, boolean> = {}
+  for (const [flag, key] of [
+    ['--env-shape', 'shape'],
+    ['--env-spread', 'spread'],
+    ['--env-size', 'size'],
+    ['--env-color', 'color'],
+  ] as const) {
+    const pin = value(flag)
+    if (pin) pins[key] = pin
+  }
+  const glow = parseBooleanValue(value('--env-glow'), '--env-glow')
+  if (glow !== undefined) effects.glow = glow
+  const plastic = parseBooleanValue(value('--env-plastic'), '--env-plastic')
+  if (plastic !== undefined) effects.plastic = plastic
+
+  if (
+    environment !== undefined ||
+    Object.keys(pins).length > 0 ||
+    Object.keys(effects).length > 0
+  ) {
+    options.environment =
+      environment === false
+        ? false
+        : {
+            pins,
+            effects,
+          }
+  }
+
+  const scriptId = value('--script')
+  if (scriptId) {
+    const progressValue = value('--progress')
+    const progress = progressValue === undefined ? 1 : Number.parseFloat(progressValue)
+    if (!Number.isFinite(progress)) {
+      throw new Error(`--progress expects a number from 0 to 1, got "${progressValue}"`)
+    }
+    options.script = {
+      id: scriptId,
+      progress,
+      animate: args.includes('--animate'),
+      slow: args.includes('--slow'),
+    }
+  }
+
+  return options
+}
+
+function parseBooleanValue(value: string | undefined, flag: string): boolean | undefined {
+  if (value === undefined) return undefined
+  const normalized = value.toLowerCase()
+  if (['on', 'true', 'yes', '1'].includes(normalized)) return true
+  if (['off', 'false', 'no', '0'].includes(normalized)) return false
+  throw new Error(`${flag} expects on or off, got "${value}"`)
+}
+
+function summarizeState(state: Record<string, unknown>) {
+  const parts = [
+    `ready=${Boolean(state.ready)}`,
+    `background=${String(state.background ?? 'unknown')}`,
+    `colorway=${String(state.colorway ?? 'unknown')}`,
+    `environment=${state.environmentActive ? 'on' : 'off'}`,
+    `setting=${String(state.setting ?? 'none')}`,
+    `focus=${
+      state.focus &&
+      typeof state.focus === 'object' &&
+      (state.focus as { enabled?: boolean }).enabled
+        ? 'on'
+        : 'off'
+    }`,
+  ]
+  return parts.join(', ')
+}