Skip to content

Add CLI options for deterministic window geometry and readiness #147

Description

@lambdalisue

Summary

Add deterministic window bootstrap options to the Arto CLI so users can reliably control initial window geometry, theme, and capture timing.

Motivation

Arto already supports per-invocation open behavior (--open) and root directory control (--directory).
For automation workflows (screen capture, demos, regression repros, scripted QA), we still lack a stable way to:

  1. place a window at an exact position,
  2. set an exact window size,
  3. force a deterministic theme,
  4. know when the initial render is actually ready.

This currently forces fragile AppleScript timing and ad-hoc retries.

Proposed CLI Interface

--position=<x>,<y>

Set initial window position in screen coordinates.

Examples:

  • arto --position=120,120 README.md
  • arto --open=new --position=80,64 docs/guide.md

--size=<w>,<h>

Set initial window size.

Examples:

  • arto --size=1400,920 README.md
  • arto --position=120,120 --size=1400,920 README.md

--theme=<light|dark|system>

Override theme for the invocation.

Examples:

  • arto --theme=light README.md
  • arto --open=new --theme=dark docs/guide.md

--wait-ready

Wait until the target window completes its initial content render before returning control.

Examples:

  • arto --wait-ready README.md
  • arto --open=new --position=120,120 --size=1400,920 --theme=light --wait-ready README.md

Behavior Notes

  • Window target selection (new vs reuse) is decided by --open behavior, not by whether file paths are present.
  • Options should apply to the selected target window for that invocation.
  • --wait-ready should use a concrete readiness signal (not fixed sleep), e.g. after initial markdown render pipeline completion.
  • These options should work correctly through single-instance IPC (secondary instance -> primary instance).
  • No-path invocation: when no files/directories are provided, Arto should still follow --open semantics:
    • --open=new: create a new window, then apply geometry/theme options.
    • --open=screen / default behavior: select/reuse the target window, then apply geometry/theme options.

Scope

  • Applies to CLI invocations that open files/directories and no-path invocations used for window control.
  • Includes argument parsing, IPC protocol propagation, and main-window creation/selection path updates.
  • Includes arto --help documentation updates.

Acceptance Criteria

  • --position correctly sets target window position
  • --size correctly sets target window size
  • --position and --size can be combined in one invocation
  • --theme overrides theme for the invocation (light / dark / system)
  • --wait-ready returns only after initial render is ready
  • With no path, --open still determines create-vs-reuse behavior
  • Secondary-instance invocations forward these options through IPC correctly
  • arto --help documents all new options and value formats

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions