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:
- place a window at an exact position,
- set an exact window size,
- force a deterministic theme,
- 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
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:
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.mdarto --open=new --position=80,64 docs/guide.md--size=<w>,<h>Set initial window size.
Examples:
arto --size=1400,920 README.mdarto --position=120,120 --size=1400,920 README.md--theme=<light|dark|system>Override theme for the invocation.
Examples:
arto --theme=light README.mdarto --open=new --theme=dark docs/guide.md--wait-readyWait until the target window completes its initial content render before returning control.
Examples:
arto --wait-ready README.mdarto --open=new --position=120,120 --size=1400,920 --theme=light --wait-ready README.mdBehavior Notes
--openbehavior, not by whether file paths are present.--wait-readyshould use a concrete readiness signal (not fixed sleep), e.g. after initial markdown render pipeline completion.--opensemantics:--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
arto --helpdocumentation updates.Acceptance Criteria
--positioncorrectly sets target window position--sizecorrectly sets target window size--positionand--sizecan be combined in one invocation--themeoverrides theme for the invocation (light/dark/system)--wait-readyreturns only after initial render is ready--openstill determines create-vs-reuse behaviorarto --helpdocuments all new options and value formats