@spec advance_frame(timestamp :: non_neg_integer()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Advance the animation clock by one frame in headless/test mode.

Sends an advance_frame message to the renderer with the given timestamp (monotonic milliseconds). If on_animation_frame is subscribed, the renderer emits an animation_frame event back.

This is a test/headless-only command. In normal daemon mode the renderer drives animation frames from the display vsync.

Example

Plushie.Command.advance_frame(16)

@spec allow_automatic_tabbing(enabled :: boolean()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Sets whether the system can automatically organize windows into tabs.

This is a macOS-specific setting. On other platforms it is a no-op. See: https://developer.apple.com/documentation/appkit/nswindow/1646657-allowsautomaticwindowtabbing

@spec announce(text :: String.t()) :: %Plushie.Command{payload: term(), type: term()}

Triggers a screen reader announcement without a visible widget.

The text is immediately announced by assistive technology as a live-region assertion. Useful for status updates, error messages, and other dynamic content that should be announced but doesn't need to be visually displayed.

Example

Command.announce("File saved successfully")
Command.announce("3 search results found")

@spec async(fun :: fun(), event_tag :: atom()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Run fun asynchronously in a Task. When it returns, the runtime dispatches %Plushie.Event.AsyncEvent{tag: event_tag, result: result} through update/2.

Only one task per tag can be active. If a task with the same tag is already running, it is killed and replaced. Use unique tags if you need concurrent tasks.

@spec batch(commands :: t() | [t()]) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Issue multiple commands. Commands in the batch execute sequentially in list order, with state threaded through each.

Accepts a single command, a list of commands, or a nested list -- anything List.wrap/1 can normalize.

@spec cancel(event_tag :: atom()) :: %Plushie.Command{payload: term(), type: term()}

Cancel a running async or stream command by its tag.

If the task has already completed, this is a no-op. The runtime tracks running tasks by their event tag and terminates the associated process.

Example

Command.cancel(:file_import)

@spec clear_images() :: %Plushie.Command{payload: term(), type: term()}

Clears all in-memory images.

@spec close_window(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Close the window identified by window_id.

@spec create_image(handle :: String.t(), data :: binary()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Creates an in-memory image from encoded PNG/JPEG bytes.

The raw binary is stored as-is in the command payload. The protocol layer handles format-specific encoding (native binary for msgpack, base64 for JSON).

@spec create_image(
  handle :: String.t(),
  width :: pos_integer(),
  height :: pos_integer(),
  pixels :: binary()
) :: %Plushie.Command{payload: term(), type: term()}

Creates an in-memory image from raw RGBA pixel data.

The raw binary is stored as-is in the command payload. The protocol layer handles format-specific encoding (native binary for msgpack, base64 for JSON).

@spec delete_image(handle :: String.t()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Deletes an in-memory image by handle name.

@spec disable_mouse_passthrough(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Disable mouse passthrough on a window.

@spec done(value :: term(), msg_fn :: (term() -> term())) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Wraps an already-resolved value in a command. The runtime immediately dispatches msg_fn.(value) through update/2 without spawning a task.

Useful for lifting a pure value into the command pipeline.

@spec drag_resize_window(window_id :: window_id(), direction :: atom() | String.t()) ::
  %Plushie.Command{payload: term(), type: term()}

Start drag-resizing the window from the given edge/corner direction.

@spec drag_window(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Start dragging the window.

@spec enable_mouse_passthrough(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Enable mouse passthrough on a window (clicks pass through to windows below).

@spec exit() :: %Plushie.Command{payload: term(), type: term()}

Exit the application.

@spec find_focused(tag :: atom()) :: %Plushie.Command{payload: term(), type: term()}

Queries which widget currently has focus.

The result arrives in update/2 as %SystemEvent{type: :find_focused, tag: tag, data: %{"focused" => "..." | nil}}.

Note: if no widget is focused, the "focused" field may be nil.

@spec focus(widget_id :: widget_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Focus the widget identified by widget_id.

Supports window-qualified paths: "main#email" targets widget "email" in window "main".

@spec focus_element(canvas_id :: widget_id(), element_id :: String.t()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Focus a specific interactive element within a canvas. Supports "window#canvas".

@spec focus_next() :: %Plushie.Command{payload: term(), type: term()}

Move focus to the next focusable widget.

@spec focus_previous() :: %Plushie.Command{payload: term(), type: term()}

Move focus to the previous focusable widget.

@spec gain_focus(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Give focus to a window.

@spec get_mode(window_id :: window_id(), tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query the current window mode (windowed, fullscreen, hidden).

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: mode}.

@spec get_scale_factor(window_id :: window_id(), tag :: event_tag()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Query the window's current scale factor (DPI scaling).

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: factor}.

@spec get_system_info(tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query system information (OS, CPU, memory, graphics).

The result arrives in update/2 as %Plushie.Event.SystemEvent{type: :system_info, tag: tag, data: info} where tag is the stringified event tag and info is a map with keys: "system_name", "system_kernel", "system_version", "system_short_version", "cpu_brand", "cpu_cores", "memory_total", "memory_used", "graphics_backend", "graphics_adapter".

System info is always available (the sysinfo iced feature is enabled unconditionally).

Example

def update(model, %Plushie.Event.WidgetEvent{type: :click, id: "sys_info"}) do
  {model, Plushie.Command.get_system_info(:sys_info)}
end

def update(model, %Plushie.Event.SystemEvent{type: :system_info, tag: "sys_info", data: info}) do
  %{model | system: info}
end

@spec get_system_theme(tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query the current system theme (light/dark mode).

The result arrives in update/2 as %Plushie.Event.SystemEvent{type: :system_theme, tag: tag, data: mode} where tag is the stringified event tag and mode is "light", "dark", or "none" (when no system preference is detected). Returns "none" on Linux systems without a desktop environment. Apps should provide a theme fallback.

Example

def update(model, %Plushie.Event.WidgetEvent{type: :click, id: "check_theme"}) do
  {model, Plushie.Command.get_system_theme(:theme_result)}
end

def update(model, %Plushie.Event.SystemEvent{type: :system_theme, tag: "theme_result", data: mode}) do
  %{model | theme_mode: mode}
end

@spec get_window_position(window_id :: window_id(), tag :: event_tag()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Query the position of a window.

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: data} where data is %{x: x, y: y} or nil if unavailable.

@spec get_window_size(window_id :: window_id(), tag :: event_tag()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Query the size of a window.

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: data} where data is %{width: width, height: height}.

@spec is_maximized(window_id :: window_id(), tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query whether a window is maximized.

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: boolean}.

@spec is_minimized(window_id :: window_id(), tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query whether a window is minimized.

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: boolean}.

@spec list_images(tag :: atom()) :: %Plushie.Command{payload: term(), type: term()}

Lists all in-memory image handles.

The result arrives in update/2 as %SystemEvent{type: :image_list, tag: tag, data: %{"handles" => [...]}}.

@spec load_font(data :: binary()) :: %Plushie.Command{payload: term(), type: term()}

Loads a font at runtime from binary data.

The font data should be the raw bytes of a TrueType (.ttf) or OpenType (.otf) font file. Once loaded, the font can be referenced by name in widget font props.

Example

font_data = File.read!("path/to/CustomFont.ttf")
Plushie.Command.load_font(font_data)

@spec maximize_window(window_id :: window_id(), maximized :: boolean()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Maximize or restore a window.

@spec minimize_window(window_id :: window_id(), minimized :: boolean()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Minimize or restore a window.

@spec monitor_size(window_id :: window_id(), tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query the monitor size for the display containing a window.

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: data} where data is %{width: width, height: height} or nil if the monitor cannot be determined.

@spec move_cursor_to(widget_id :: widget_id(), position :: non_neg_integer()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Move the text cursor to a specific position. Supports "window#path".

@spec move_cursor_to_end(widget_id :: widget_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Move the text cursor to the end of the input. Supports "window#path".

@spec move_cursor_to_front(widget_id :: widget_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Move the text cursor to the front of the input. Supports "window#path".

@spec move_window(window_id :: window_id(), x :: number(), y :: number()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Move a window to the given position.

@spec none() :: %Plushie.Command{payload: term(), type: term()}

A no-op command. Returned implicitly when update/2 returns a bare model.

@spec pane_close(pane_grid_id :: widget_id(), pane_id :: term()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Close a pane in the pane grid.

@spec pane_maximize(pane_grid_id :: widget_id(), pane_id :: term()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Maximize a pane in the pane grid.

@spec pane_restore(pane_grid_id :: widget_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Restore all panes from maximized state.

@spec pane_split(
  pane_grid_id :: widget_id(),
  pane_id :: term(),
  axis :: atom() | String.t(),
  new_pane_id :: term()
) :: %Plushie.Command{payload: term(), type: term()}

Split a pane in the pane grid along the given axis.

@spec pane_swap(pane_grid_id :: widget_id(), pane_a :: term(), pane_b :: term()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Swap two panes in the pane grid.

@spec raw_id(window_id :: window_id(), tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Query the raw platform window ID (e.g. X11 window ID, HWND).

Result arrives as %Plushie.Event.SystemEvent{tag: tag, data: platform_id}.

@spec request_user_attention(window_id :: window_id(), urgency :: atom() | nil) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Request user attention for a window. Urgency can be :informational or :critical.

@spec resize_window(window_id :: window_id(), width :: number(), height :: number()) ::
  %Plushie.Command{payload: term(), type: term()}

Resize a window to the given dimensions.

@spec screenshot(window_id :: window_id(), tag :: event_tag()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Take a screenshot of a window. Result arrives as a tagged event.

@spec scroll_by(widget_id :: widget_id(), x :: float(), y :: float()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Scroll the widget by a relative offset. Supports "window#path".

@spec scroll_to(widget_id :: widget_id(), offset :: term()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Scroll the widget identified by widget_id to offset.

Supports window-qualified paths: "main#list".

@spec select_all(widget_id :: widget_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Select all text in the widget identified by widget_id.

Supports window-qualified paths: "main#email".

@spec select_range(
  widget_id :: widget_id(),
  start_pos :: non_neg_integer(),
  end_pos :: non_neg_integer()
) :: %Plushie.Command{payload: term(), type: term()}

Select a range of text in the input. Supports "window#path".

@spec send_after(delay_ms :: non_neg_integer(), event :: term()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Send event through update/2 after delay_ms milliseconds.

If a timer with the same event term is already pending, the previous timer is canceled and replaced. This prevents duplicate deliveries when send_after is called repeatedly for the same event.

@spec set_icon(
  window_id :: window_id(),
  rgba_data :: binary(),
  width :: pos_integer(),
  height :: pos_integer()
) :: %Plushie.Command{payload: term(), type: term()}

Sets the window icon from raw RGBA pixel data.

The rgba_data must be a binary of width * height * 4 bytes (one byte each for R, G, B, A per pixel, row-major). The raw binary is stored as-is in the command payload. The protocol layer handles format-specific encoding (native binary for msgpack via Msgpax.Bin, base64 for JSON).

Example

icon_data = File.read!("icon_32x32.rgba")
Plushie.Command.set_icon("main", icon_data, 32, 32)

@spec set_max_size(window_id :: window_id(), width :: number(), height :: number()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Set the maximum size of a window.

@spec set_min_size(window_id :: window_id(), width :: number(), height :: number()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Set the minimum size of a window.

@spec set_resizable(window_id :: window_id(), resizable :: boolean()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Set whether a window is resizable.

@spec set_resize_increments(
  window_id :: window_id(),
  width :: number() | nil,
  height :: number() | nil
) :: %Plushie.Command{payload: term(), type: term()}

Sets the resize increment size for a window.

When set, the window will only resize in multiples of the given width and height. Pass nil for both to clear the constraint. Useful for terminal emulators and grid-aligned apps.

@spec set_window_level(window_id :: window_id(), level :: atom() | String.t()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Set window stacking level (:normal, :always_on_top, :always_on_bottom).

On Wayland, window stacking is compositor-controlled and this command may be silently ignored.

@spec set_window_mode(window_id :: window_id(), mode :: atom() | String.t()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Set window mode (windowed, fullscreen, etc.).

@spec show_system_menu(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Show the system menu for a window.

@spec snap_to(widget_id :: widget_id(), x :: float(), y :: float()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Snap the scrollable widget to an absolute offset. Supports "window#path".

@spec snap_to_end(widget_id :: widget_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Snap the scrollable widget to the end of its content. Supports "window#path".

@spec stream(fun :: (fun() -> term()), event_tag :: atom()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Run fun as a streaming async task. The function receives an emit callback that sends intermediate results to update/2 as %Plushie.Event.StreamEvent{tag: event_tag, value: value}. The function's final return value is delivered as %Plushie.Event.AsyncEvent{tag: event_tag, result: result}.

Only one task per tag can be active. If a task with the same tag is already running, it is killed and replaced. Use unique tags if you need concurrent streams.

This is sugar over spawning a process manually. You can achieve the same thing with bare Task and send/2 if you prefer direct Elixir patterns.

Example

Command.stream(fn emit ->
  for chunk <- File.stream!("big.csv") do
    emit.({:chunk, process(chunk)})
  end
  :done
end, :file_import)

@spec toggle_decorations(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Toggle window decorations (title bar, borders).

@spec toggle_maximize(window_id :: window_id()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Toggle window maximized state.

@spec tree_hash(tag :: atom()) :: %Plushie.Command{payload: term(), type: term()}

Computes a SHA-256 hash of the renderer's current tree state.

The result arrives in update/2 as %SystemEvent{type: :tree_hash, tag: tag, data: %{"hash" => "..."}}.

@spec update_image(handle :: String.t(), data :: binary()) :: %Plushie.Command{
  payload: term(),
  type: term()
}

Updates an existing in-memory image with new encoded PNG/JPEG bytes.

The raw binary is stored as-is in the command payload. The protocol layer handles format-specific encoding (native binary for msgpack, base64 for JSON).

@spec update_image(
  handle :: String.t(),
  width :: pos_integer(),
  height :: pos_integer(),
  pixels :: binary()
) :: %Plushie.Command{payload: term(), type: term()}

Updates an existing in-memory image with new raw RGBA pixel data.

The raw binary is stored as-is in the command payload. The protocol layer handles format-specific encoding (native binary for msgpack, base64 for JSON).

@spec widget_command(node_id :: String.t(), op :: String.t(), payload :: map()) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Send a command to a native widget.

Widget commands bypass the normal tree update / diff / patch cycle and are delivered directly to the target native widget on the Rust side.

@spec widget_commands(commands :: [{String.t(), String.t(), map()}]) ::
  %Plushie.Command{
    payload: term(),
    type: term()
  }

Send a batch of widget commands (processed in one cycle).

Each command in the list is a {node_id, op, payload} tuple.