Search documentation of Plushie

# API Reference Plushie v#0.7.2

Copy Markdown View Source

## Modules

Plushie

Native desktop GUIs from Elixir, powered by iced.

Plushie.Animation

Animation system for Plushie.

Plushie.Animation.Easing

Easing function catalogue for animations and transitions.

Plushie.Animation.Sequence

Renderer-side sequential animation chain.

Plushie.Animation.Spring

Renderer-side physics-based spring descriptor.

Plushie.Animation.Transition

Renderer-side timed transition descriptor.

Plushie.Animation.Tween

SDK-side stateful interpolator for model-level animation.

Plushie.App

Behaviour for Plushie apps following the Elm architecture.

Plushie.Automation

Runtime automation for Plushie apps.

Plushie.Automation.Element

Represents a widget element found in the UI tree during automation.

Plushie.Automation.File

Parser for `.plushie` automation files.

Plushie.Automation.Runner

Executes parsed `.plushie` automation files.

Plushie.Automation.Screenshot

Pixel screenshot for automation and renderer inspection.

Plushie.Automation.Selector

Selector helpers for automation against a normalized Plushie tree.

Plushie.Automation.Session

An automation client attached to a running Plushie app.

Plushie.Binary

Resolves the path to the plushie binary.

Plushie.Bridge

Bridge to the plushie renderer process.

Plushie.Canvas.Angle

Angle type for canvas rotation and arc parameters.

Plushie.Canvas.Circle

Canvas circle element with center, radius, and optional styling.

Plushie.Canvas.Clip

Clip rectangle for canvas groups. Children are clipped to this region.

Plushie.Canvas.Dash

Dash pattern for canvas shape strokes.

Plushie.Canvas.DragBounds

Drag constraint bounds for interactive canvas shapes.

Plushie.Canvas.Element

Behaviour for canvas elements.

Plushie.Canvas.Gradient

Linear gradient descriptor usable as a canvas fill value.

Plushie.Canvas.Group

Canvas group: a structural container for transforms, clips, and visual grouping.

Plushie.Canvas.HitRect

Explicit hit test rectangle override for interactive canvas shapes.

Plushie.Canvas.Image

Canvas raster image element with position, size, and optional rotation.

Plushie.Canvas.Interactive

Interactive canvas element.

Plushie.Canvas.Layer

Canvas layer: a named container that groups shapes for independent caching on the renderer side.

Plushie.Canvas.Line

Canvas line element between two points with optional stroke and opacity.

Plushie.Canvas.Path

Canvas arbitrary path element built from a list of drawing commands.

Plushie.Canvas.Rect

Canvas rectangle element with position, size, and optional styling.

Plushie.Canvas.Shape

Pure builder functions returning typed canvas shape structs.

Plushie.Canvas.ShapeStyle

Style overrides for interactive canvas shape states (hover, pressed).

Plushie.Canvas.Stroke

Canvas stroke descriptor with color, width, and optional cap/join/dash.

Plushie.Canvas.Svg

Canvas SVG element with position and size.

Plushie.Canvas.Text

Canvas text element with position, content, and optional font styling.

Plushie.Canvas.Transform.Rotate

Rotation transform for canvas groups. Stores degrees (wire protocol convention).

Plushie.Canvas.Transform.Scale

Scale transform for canvas groups.

Plushie.Canvas.Transform.Translate

Translation transform for canvas groups.

Plushie.Command

Commands describe side effects that `update/2` wants the runtime to perform.

Plushie.Command.Image

In-memory image commands: create, update, delete, list, and clear.

Plushie.Command.Scroll

Scroll commands: absolute, relative, and snap positioning.

Plushie.Command.Text

Text input commands: selection and cursor movement.

Plushie.Command.Window

Window operation commands.

Plushie.Command.WindowQuery

Window query commands. Results arrive as `%Plushie.Event.SystemEvent{}` in `update/2`.

Plushie.Data

Query pipeline for in-memory record collections. Pure functions supporting filter, search, sort, group, and pagination.

Plushie.Dev.DevServer

File watcher and recompiler for dev-mode live reload.

Plushie.Effect

Native platform effect requests.

Plushie.Effect.Result

Typed results for platform effect responses.

Plushie.Effect.Result.Cancelled

The user dismissed a dialog.

Plushie.Effect.Result.ClipboardCleared

Clipboard was cleared.

Plushie.Effect.Result.ClipboardHtml

Clipboard HTML was read. `alt_text` may be nil.

Plushie.Effect.Result.ClipboardText

Clipboard text was read.

Plushie.Effect.Result.ClipboardWritten

Clipboard write completed.

Plushie.Effect.Result.DirectoriesSelected

Multiple directories were selected from a multi-directory picker.

Plushie.Effect.Result.DirectorySelected

A directory was selected from a directory picker.

Plushie.Effect.Result.Error

A platform error occurred. `message` is renderer-supplied.

Plushie.Effect.Result.FileOpened

A file was selected from an open-file dialog.

Plushie.Effect.Result.FileSaved

A file path was chosen in a save dialog.

Plushie.Effect.Result.FilesOpened

Multiple files were selected from a multi-file open dialog.

Plushie.Effect.Result.NotificationShown

An OS notification was shown.

Plushie.Effect.Result.RendererRestarted

The renderer restarted while this effect was in flight.

Plushie.Effect.Result.Timeout

The effect did not receive a response within its timeout.

Plushie.Effect.Result.Unsupported

The backend does not support this effect.

Plushie.Event

Event types delivered to `update/2`.

Plushie.Event.AsyncEvent

Results from `Plushie.Command.task/2` tasks.

Plushie.Event.BuiltinSpecs

Canonical event specs for all built-in widget event types.

Plushie.Event.CommandError

Renderer error for a command.

Plushie.Event.Diagnostic

Typed diagnostic variants emitted by the renderer.

Plushie.Event.Diagnostic.A11yRefUnresolved

A cross-widget a11y reference did not resolve to any declared widget.

Plushie.Event.Diagnostic.BufferOverflow

A single wire message exceeded the protocol's 64 MiB per-message size cap.

Plushie.Event.Diagnostic.ContentLengthExceeded

A text-like content prop exceeded its per-widget byte cap and was truncated.

Plushie.Event.Diagnostic.DashCacheCapExceeded

The leaked dash-segment cache reached its entry cap.

Plushie.Event.Diagnostic.DispatchLoopExceeded

The runtime's command dispatch chain exceeded the configured depth limit, indicating an `update` loop that keeps returning a command whose delivered event produces another command.

Plushie.Event.Diagnostic.DuplicateId

A widget ID collided with one already declared within the same window scope.

Plushie.Event.Diagnostic.EmitterCoalesceCapExceeded

The renderer-lib event coalesce map hit its cap and was force-flushed.

Plushie.Event.Diagnostic.EmptyId

A view declared a widget with an empty ID where a non-empty one was expected.

Plushie.Event.Diagnostic.FontCacheCapExceeded

The leaked font-family-name cache reached its entry cap.

Plushie.Event.Diagnostic.FontCapExceeded

Inline fonts declared in Settings exceeded the process-wide cap.

Plushie.Event.Diagnostic.FontFamilyNotFound

A font family from default_font or its fallback chain did not resolve.

Plushie.Event.Diagnostic.InvalidSettings

The Settings payload failed typed deny_unknown_fields validation.

Plushie.Event.Diagnostic.MissingAccessibleName

A widget that requires a screen-reader-announcable name was declared without one.

Plushie.Event.Diagnostic.MultipleTopLevelWindows

The tree holds more than one top-level window child.

Plushie.Event.Diagnostic.PropRangeExceeded

A numeric prop was outside its declared range and was clamped.

Plushie.Event.Diagnostic.PropTypeMismatch

A prop value had an unexpected JSON type.

Plushie.Event.Diagnostic.PropUnknown

A widget carried a prop name not in its declared schema.

Plushie.Event.Diagnostic.RequiredWidgetsMissing

The Settings handshake declared native widget names the renderer does not know about.

Plushie.Event.Diagnostic.SvgDecodeTimeout

SVG decode exceeded its wall-clock budget.

Plushie.Event.Diagnostic.SvgParseError

SVG decode returned a parse error.

Plushie.Event.Diagnostic.TooManyDuplicates

Duplicate-ID collection stopped at the configured cap.

Plushie.Event.Diagnostic.TreeDepthExceeded

Tree traversal reached the global depth cap; the subtree was skipped.

Plushie.Event.Diagnostic.UnknownMessageType

A wire message carried a `type` field the SDK does not recognise.

Plushie.Event.Diagnostic.UnknownWindow

A subscription was declared for a window not present in the tree.

Plushie.Event.Diagnostic.UnrecognizedWidgetPlaceholder

A widget placeholder in the tree had no registered expander.

Plushie.Event.Diagnostic.UpdatePanicked

The update function panicked and was caught by the runtime. The model is reverted to the last-good snapshot so the app keeps running; the consecutive counter is shared with `ViewPanicked` so the frozen-UI overlay surfaces after enough total panics across either callback.

Plushie.Event.Diagnostic.ViewPanicked

The view function panicked and was caught by the runtime's safety net.

Plushie.Event.Diagnostic.WidgetIdInvalid

A user-authored widget ID violated the canonical ID ruleset.

Plushie.Event.Diagnostic.WidgetIdTypeCollision

A composite widget ID was registered against two different widget types.

Plushie.Event.Diagnostic.WidgetPanic

A non-trusted widget panicked inside the registry's catch_unwind firewall.

Plushie.Event.DiagnosticMessage

A structured diagnostic delivered through the renderer's diagnostic wire channel.

Plushie.Event.EffectEvent

Platform effect responses (file dialogs, clipboard, notifications).

Plushie.Event.ImeEvent

Input Method Editor events from subscriptions.

Plushie.Event.KeyEvent

Keyboard press and release events.

Plushie.Event.ModifiersEvent

Keyboard modifier state change event.

Plushie.Event.StreamEvent

Intermediate values from `Plushie.Command.stream/2` tasks.

Plushie.Event.SystemEvent

System query responses and platform events.

Plushie.Event.TimerEvent

Timer tick events from `Plushie.Subscription.every/2`.

Plushie.Event.WidgetEvent

Events from interactive widgets (buttons, inputs, sliders, etc.).

Plushie.Event.WindowEvent

Window lifecycle events.

Plushie.KeyModifiers

Keyboard modifier state at the time of a key event.

Plushie.Protocol

Wire protocol between the Elixir runtime and the Rust renderer.

Plushie.Protocol.Decode

Wire protocol decoding.

Plushie.Protocol.Error

Raised when the renderer sends a protocol message the SDK considers invalid.

Plushie.Protocol.Keys

Named keyboard key mappings and validation.

Plushie.Protocol.ProtocolVersionMismatchError

Raised when the renderer's advertised protocol version differs from the version the SDK was built against.

Plushie.RendererEnv

Builds a safe, whitelisted environment for the renderer binary.

Plushie.RendererExitError

Structured renderer exit reason for handle_renderer_exit/2.

Plushie.Route

Client-side routing for multi-view apps. Pure data structure maintaining a navigation stack of `{path, params}` entries.

Plushie.Runtime

Core lifecycle GenServer for Plushie applications.

Plushie.Runtime.Commands

Command execution engine for the Plushie runtime.

Plushie.Runtime.Subscriptions

Subscription lifecycle management for the Plushie runtime.

Plushie.Runtime.WidgetHandlers

Runtime support for widget handler event dispatch and state management.

Plushie.Runtime.Windows

Window lifecycle management for the Plushie runtime.

Plushie.ScopedId

Structured representation of a scoped widget ID.

Plushie.Selection

Selection state for lists and tables. Pure data structure supporting single, multi, and range selection modes.

Plushie.State

Path-based state management with revision tracking and transactions.

Plushie.Subscription

Declarative subscription specifications for Plushie apps.

Plushie.Table.Cell

A cell inside a `Plushie.Table.Row`.

Plushie.Table.Element

Behaviour for table structural elements.

Plushie.Table.Row

A row inside a `table` widget.

Plushie.Test

Test helpers for Plushie applications.

Plushie.Test.Backend.Runtime

Test backend that starts a real Plushie app (Runtime + Bridge).

Plushie.Test.Case

ExUnit case template for testing Plushie apps.

Plushie.Test.Helpers

Test helper functions imported by `Plushie.Test.Case`.

Plushie.Test.PoolAdapter

Iostream adapter that connects a Bridge to one SessionPool session.

Plushie.Test.Screenshot

Test helpers for screenshot golden-file assertions.

Plushie.Test.Session

A test session wrapping a running Plushie app.

Plushie.Test.SessionPool

Session manager for concurrent test renderer sessions.

Plushie.Test.SessionPool.Multiplexed

State and business logic for the shared-renderer session pool modes.

Plushie.Test.SessionPool.Transport

Transport helpers for `Plushie.Test.SessionPool`.

Plushie.Test.SessionPool.Windowed

State and business logic for the `:windowed` session pool mode.

Plushie.Test.TreeHash

Structural tree hash and golden-file assertions for tests.

Plushie.Test.WidgetCase

ExUnit case template for testing stateful widgets.

Plushie.Transport

Behaviour for renderer transport backends.

Plushie.Transport.BufferOverflowError

Raised when a single wire frame exceeds the protocol's per-message size cap (64 MiB).

Plushie.Transport.Framing

Frame encoding and decoding for the plushie wire protocol.

Plushie.Transport.IOStream

Transport implementation for iostream adapter connections.

Plushie.Transport.Port

Transport implementation for Erlang Port-based connections.

Plushie.Tree

Utilities for working with Plushie UI trees.

Plushie.Tree.Node

Protocol for converting typed structs to `ui_node()` maps.

Plushie.Type

Types for widget fields and events.

Plushie.Type.A11y

Accessibility annotation type for widget nodes.

Plushie.Type.Alignment

Alignment values for `align_x` and `align_y` widget props.

Plushie.Type.Anchor

Anchor values for the scrollbar `alignment` prop.

Plushie.Type.Any

Accepts any value without validation. No guard is generated.

Plushie.Type.Atom

Atom type. Accepts any atom (including `nil`).

Plushie.Type.Boolean

Boolean type. Accepts `true` and `false` only.

Plushie.Type.Border

Border specification for container and widget styling.

Plushie.Type.Color

Color type for iced widget properties.

Plushie.Type.Composite

Behaviour for composite type modules.

Plushie.Type.Composite.Enum

Composite type for a fixed set of values.

Plushie.Type.Composite.List

Composite type for typed lists.

Plushie.Type.Composite.Map

Composite type for typed maps.

Plushie.Type.Composite.Tuple

Composite type for fixed-size typed tuples.

Plushie.Type.Composite.Union

Composite type for unions.

Plushie.Type.ContentFit

Scaling mode for the `content_fit` prop on image and SVG widgets.

Plushie.Type.Direction

Orientation for the scrollable `direction` prop and rule widget.

Plushie.Type.FilterMethod

Interpolation mode for the image `filter_method` prop.

Plushie.Type.Float

Numeric type. Accepts both integers and floats (any `number()`).

Plushie.Type.Font

Font specification with family, weight, style, and stretch.

Plushie.Type.Gradient

Gradient type for container and style backgrounds.

Plushie.Type.Integer

Integer type. Accepts Elixir integers only.

Plushie.Type.Key

Event field type for keyboard key names.

Plushie.Type.KeyModifiers

Event field type for keyboard modifier state.

Plushie.Type.Length

Size value for the `width` and `height` props on most widgets.

Plushie.Type.LineHeight

Line height for text widgets.

Plushie.Type.Map

Untyped map. Accepts any map without validating keys or values.

Plushie.Type.MouseButton

Event field type for mouse buttons.

Plushie.Type.Padding

Padding specification with per-side values.

Plushie.Type.Pointer

Event field types for unified pointer events.

Plushie.Type.Position

Placement value for the tooltip `position` prop.

Plushie.Type.Range

Validates `{min, max}` numeric range tuples.

Plushie.Type.Shadow

Shadow type for widget styling.

Plushie.Type.Shaping

Text shaping strategy for the text `shaping` prop.

Plushie.Type.String

String type. Accepts binaries and atoms (atoms are coerced to strings via `Atom.to_string/1`).

Plushie.Type.Style

Union type for widget styling: a preset atom or a `StyleMap` struct.

Plushie.Type.StyleMap

Per-instance widget styling that crosses the IPC boundary as a plain map.

Plushie.Type.Theme

Built-in iced themes and custom palette support.

Plushie.Type.Wrapping

Line-break strategy for the text `wrapping` prop.

Plushie.UI

Ergonomic builder layer for Plushie UI trees.

Plushie.UI.WidgetSet

Macro for creating widget set modules that override built-in widget macros.

Plushie.Undo

Undo/redo stack for reversible commands. Pure data structure, no processes.

Plushie.Widget

Macro-based DSL for declaring Plushie widgets.

Plushie.Widget.Build

Internal helpers for widget `to_node/1` implementations.

Plushie.Widget.Button

Button, clickable widget that emits `%WidgetEvent{type: :click}` events.

Plushie.Widget.Canvas

Canvas for drawing shapes, organized into named layers.

Plushie.Widget.Checkbox

Checkbox, toggleable boolean input.

Plushie.Widget.Column

Column layout, arranges children vertically.

Plushie.Widget.ComboBox

Combo box, searchable dropdown with free-form text input.

Plushie.Widget.Container

Container layout, wraps a single child with padding, sizing, and styling.

Plushie.Widget.Floating

Floating overlay, positions child with optional translation and scaling.

Plushie.Widget.Grid

Grid layout, arranges children in a fixed-column grid.

Plushie.Widget.Handler

Runtime support for stateful widgets.

Plushie.Widget.Image

Image display, renders a raster image from a file path or an in-memory handle.

Plushie.Widget.KeyedColumn

Keyed column layout, arranges children vertically with stable identity keys.

Plushie.Widget.Markdown

Markdown display, renders parsed markdown content.

Plushie.Widget.Overlay

Overlay container, positions the second child as a floating overlay relative to the first child (anchor).

Plushie.Widget.PaneGrid

Pane grid, resizable tiled panes.

Plushie.Widget.PickList

Pick list, dropdown selection.

Plushie.Widget.Pin

Pin layout, positions child at absolute coordinates.

Plushie.Widget.PointerArea

Pointer area, captures mouse events on child content.

Plushie.Widget.ProgressBar

Progress bar, displays progress within a range.

Plushie.Widget.QrCode

QR Code, renders a QR code from a data string.

Plushie.Widget.Radio

Radio button, one-of-many selection.

Plushie.Widget.Responsive

Responsive layout, adapts to available size by reporting resize events.

Plushie.Widget.RichText

Rich text display with individually styled spans.

Plushie.Widget.RichText.Span

A typed span for `Plushie.Widget.RichText`.

Plushie.Widget.Row

Row layout, arranges children horizontally.

Plushie.Widget.Rule

Horizontal or vertical rule (divider line).

Plushie.Widget.Scrollable

Scrollable container, wraps child content in a scrollable viewport.

Plushie.Widget.Sensor

Sensor, detects visibility and size changes on child content.

Plushie.Widget.Slider

Slider, horizontal range input.

Plushie.Widget.Space

Empty space, invisible spacer widget.

Plushie.Widget.Stack

Stack layout, layers children on top of each other.

Plushie.Widget.Svg

SVG display, renders a vector image from a file path.

Plushie.Widget.Table

Data table with children-based rows for efficient diffing.

Plushie.Widget.Text

Text display, renders static text.

Plushie.Widget.TextEditor

Text editor, multi-line editable text area.

Plushie.Widget.TextInput

Text input field, single-line editable text.

Plushie.Widget.Themer

Per-subtree theme override, applies a different theme to a single child widget.

Plushie.Widget.Toggler

Toggler, on/off switch.

Plushie.Widget.Tooltip

Tooltip, shows a popup tip over child content on hover.

Plushie.Widget.VerticalSlider

Vertical slider, vertical range input.

Plushie.Widget.Window

Top-level window container node.

Plushie.WidgetRegistry

Discovers widgets via `Plushie.Widget` protocol consolidation.

## Mix Tasks

mix compile.plushie_binary

Mix compiler that checks for the plushie binary.

mix plushie.build

Build the plushie renderer binary and/or WASM renderer from source.

mix plushie.connect

Runs a Plushie application that connects to an already-listening renderer via a Unix domain socket or TCP port.

mix plushie.download

Download precompiled plushie artifacts for the current platform.

mix plushie.gui

Starts a Plushie GUI application.

mix plushie.inspect

Inspect a Plushie app's UI tree.

mix plushie.replay

Replay a `.plushie` automation file with real timing and windows.

mix plushie.script

Run `.plushie` automation files.

mix preflight

Runs all CI checks locally. Exits with a non-zero status on first failure.