plushie 0.0.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b62b68b40590aee927eee8df2cf4e0f94d3459b9ddbeb2ac15e13c5c73098e96
-  data.tar.gz: 5178af8c1b52021bd7046e6381db61538323dfb74d58784db3557610f9da08b4
+  metadata.gz: c2f963b103814479cb494a52823c3c9ff0e5e07ba98bc306f5a1682204550869
+  data.tar.gz: 448aad5c90d158c3984bc6d8a2ebfa27f9bb6cdb2509b0bea643df35c11c39a4
 SHA512:
-  metadata.gz: d7355f1468b38e58343072335cc1207b412ec891c6088cc3e81a9b45c3c262ef908367470c19f0526a22c5adc51afa37b9f71f96a1016f335c56a5aadd221ca2
-  data.tar.gz: a2a365e21640dc3d2525b1df4f4124a3ad84267e97d8ae0b77fc1451d66889f72c81e3bcce08fe21c0fcdead6ee0fd12fc77a0a9bf27ea0c9741536d85ccd437
+  metadata.gz: b91eca16110d4f22964cfc17515bc15ce4310119b61947a726f672ad655a9102a3bdc783fd959903546a7b74417188d59ee5c15b3eb7ed8f8ca4e3fb5ed876ac
+  data.tar.gz: ae52385d5fba80f69bf48c06618e848af49ec59c3b016cf61f3937543f6655b7a236d55e60e629ac2f1b15ff0f343af08108775f7ccedf3d3dbc6a8dbb164dde

data/.yardopts

@@ -0,0 +1,22 @@
+--markup markdown
+--output-dir doc
+--protected
+--no-private
+--hide-void-return
+--embed-mixins
+-
+docs/getting-started.md
+docs/tutorial.md
+docs/app-behaviour.md
+docs/layout.md
+docs/events.md
+docs/commands.md
+docs/effects.md
+docs/scoped-ids.md
+docs/theming.md
+docs/testing.md
+docs/running.md
+docs/composition-patterns.md
+docs/accessibility.md
+docs/extensions.md
+docs/dsl-internals.md

data/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.5.0] - 2026-03-23
+
+Initial release. Targets plushie-renderer 0.5.0.
+
+### Added
+
+- Elm architecture (init/update/view/subscribe) via `include Plushie::App`
+- Immutable models via `Plushie::Model.define` (Data.define + #with)
+- Block-based UI DSL with 39 widget types
+- Canvas shape DSL with typed structs (Rect, Circle, Line, Text, Path, Group)
+- Canvas Group with transforms array, clip field, and top-level
+  interactive properties (on_click, on_hover, focus_style, focusable, a11y)
+- Canvas widget `role` and `arrow_mode` props for accessible containers
+- Complete wire protocol encode/decode (MessagePack + JSONL)
+- Tree diffing with incremental patch generation
+- 72+ command constructors (async, focus, scroll, window ops, effects,
+  focus_element for canvas, etc.)
+- Platform effects (file dialogs, clipboard, notifications)
+- Subscription system (timers, keyboard, mouse, window events)
+- Three transport modes: spawn, stdio, iostream
+- Renderer lifecycle management with exponential backoff restart
+- Error recovery: StandardError rescue in update/view with model
+  preservation and log throttling
+- 18 property type modules with wire encoding
+- State helpers: Animation, Route, Selection, Undo, DataQuery, State,
+  KeyModifiers
+- Widget extension system (pure Ruby composites + native Rust-backed)
+- Native Rust extension build pipeline via `rake plushie:build` --
+  generates Cargo workspace, validates crate paths and constructors,
+  detects type name and crate collisions, builds custom renderer binary
+- `Plushie.configure` block for SDK-wide configuration: `binary_path`,
+  `source_path`, `build_name`, `extensions`, `extension_config`,
+  `test_backend`
+- `extension_config` runtime configuration passed to Rust extensions
+  via the Settings wire message and `InitCtx`
+- WASM renderer download via `rake plushie:download[wasm]`
+- `PLUSHIE_BIN_FILE` and `PLUSHIE_WASM_DIR` env vars for overriding
+  download and build output paths
+- `rake plushie:connect` task for stdio transport (plushie --exec)
+- Token authentication for --exec and remote rendering
+- `RendererEnv` to filter sensitive environment variables from renderer
+  subprocess
+- Dev server with hot code reloading
+- Test framework with three backends (mock, headless, windowed)
+- Session pooling for parallel test execution
+- Snapshot and screenshot assertion helpers
+- .plushie script format parser and runner
+- Minitest and RSpec integration
+- 100% YARD documentation coverage with zero warnings
+- RBS type signatures for all modules
+- GitHub Actions CI workflow (Ruby 3.2 + 3.3 matrix)
+- CONTRIBUTING.md with commit conventions and development guide
+- Rake tasks: download, build, run, connect, inspect, script, replay,
+  preflight
+- Binary download with SHA-256 checksum verification
+- 9 examples: counter, clock, todo, async_fetch, notes, shortcuts,
+  color_picker, catalog, rate_plushie
+- Extracted reusable canvas widgets: StarRating, ThemeToggle,
+  ColorPickerWidget (in examples/widgets/)

data/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to plushie-ruby
+
+## Setup
+
+```bash
+git clone https://github.com/plushie-ui/plushie-ruby.git
+cd plushie-ruby
+bundle install
+rake plushie:download   # precompiled renderer binary
+```
+
+Requires Ruby 3.2+. No Rust toolchain needed unless building from
+source or writing native extensions.
+
+## Running checks
+
+```bash
+bundle exec rake              # tests + linter + type check
+bundle exec rake test         # tests only
+bundle exec rake standard     # linter only
+bundle exec rake steep        # type check only
+bundle exec rake yard         # generate API docs to doc/
+rake plushie:preflight        # pre-push gate (standard, test, steep, yard)
+```
+
+### Test backends
+
+Tests run against the renderer binary. Three interchangeable backends:
+
+```bash
+bundle exec rake test                                # mock (default, fastest)
+PLUSHIE_TEST_BACKEND=headless bundle exec rake test   # real rendering, no display
+PLUSHIE_TEST_BACKEND=windowed bundle exec rake test   # real windows (needs display)
+```
+
+Mock is fast enough for TDD loops. CI runs both mock and headless.
+
+## Commits
+
+Run `bundle exec rake` before committing. CI runs the same checks.
+
+### Message format
+
+Use imperative mood. Describe what changed and why, not how.
+
+```
+feat: add on_resize subscription for window resize events
+
+The renderer already emits resize events but the SDK had no
+subscription type for them. Apps had to poll window dimensions
+on a timer, which was wasteful and laggy.
+```
+
+Prefix with a category when it clarifies intent:
+
+| Prefix     | Use for                                    |
+|------------|--------------------------------------------|
+| `feat:`    | new user-facing functionality               |
+| `fix:`     | bug fix                                    |
+| `docs:`    | documentation only                         |
+| `test:`    | test additions or corrections              |
+| `refactor:`| restructuring without behaviour change     |
+| `chore:`   | deps, CI, tooling, release prep            |
+
+# Pull requests
+
+- One logical change per PR. If a refactor enables a feature, consider
+  splitting them unless the refactor is small and tightly coupled.
+- PR title follows the same format as commit messages.
+- Include a brief description of what and why. If there's a visual
+  change, a screenshot or before/after helps.
+- All CI checks must pass.
+
+## Code style
+
+[Standard](https://github.com/standardrb/standard) handles formatting
+and linting. No configuration to argue about.
+
+Beyond what Standard enforces:
+
+- **Let the code speak.** Only comment when intent isn't obvious from
+  the code itself.
+- **Prefer real implementations over mocks in tests.** The mock backend
+  is already fast; mocking Ruby internals hides real bugs.
+- **Tests are documentation.** Write them so the next person
+  understands the behaviour, not just that it "passes".
+- **ID is always the first argument** for widget builders.
+
+## Type signatures
+
+RBS signatures live in `sig/`. When adding or changing public API
+methods, update the corresponding `.rbs` file. Run `bundle exec rake
+steep` to verify.
+
+## Documentation
+
+Public API methods use YARD-style doc comments (`@param`, `@return`,
+`@example`). Guides live in `docs/` as Markdown. Generate and browse
+locally:
+
+```bash
+bundle exec rake yard
+open doc/index.html
+```
+
+## Architecture overview
+
+See the [project layout and architecture](README.md#how-it-works) in
+the README, or the detailed guide docs:
+
+- [Getting started](docs/getting-started.md)
+- [App behaviour](docs/app-behaviour.md)
+- [Events](docs/events.md)
+- [Commands](docs/commands.md)
+- [Testing](docs/testing.md)

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"
+gem "minitest", "~> 5.16"
+gem "standard", "~> 1.3"
+gem "steep", require: false
+gem "yard", require: false
+
+# Optional: hot reload in dev mode (Plushie.run(MyApp, dev: true))
+gem "listen", "~> 3.0", require: false

data/{LICENSE → LICENSE.txt}

@@ -1,6 +1,6 @@
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2026 Daniel Hedlund <daniel@digitree.org>
+Copyright (c) 2026 Daniel Hedlund
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,8 +1,300 @@
-# Plushie for Ruby
+# plushie
 
-Native GUI toolkit for Ruby, powered by native rendering via Iced.
+Build native desktop apps in Ruby. **Pre-1.0**
 
-This is a placeholder release to reserve the package name. The first
-functional release is coming soon.
+Plushie is a desktop GUI framework that allows you to write your entire
+application in Ruby -- state, events, UI -- and get native windows
+on Linux, macOS, and Windows. Rendering is powered by
+[iced](https://github.com/iced-rs/iced), a cross-platform GUI library
+for Rust, which plushie drives as a precompiled binary behind the scenes.
 
-Source: <https://github.com/plushie-ui/plushie>
+```ruby
+class Counter
+  include Plushie::App
+
+  Model = Plushie::Model.define(:count)
+
+  def init(_opts) = Model.new(count: 0)
+
+  def update(model, event)
+    case event
+    in Event::Widget[type: :click, id: "inc"]
+      model.with(count: model.count + 1)
+    in Event::Widget[type: :click, id: "dec"]
+      model.with(count: model.count - 1)
+    else
+      model
+    end
+  end
+
+  def view(model)
+    window("main", title: "Counter") do
+      column(padding: 16, spacing: 8) do
+        text("count", "Count: #{model.count}")
+        row(spacing: 8) do
+          button("inc", "+")
+          button("dec", "-")
+        end
+      end
+    end
+  end
+end
+
+Plushie.run(Counter)
+```
+
+This is one of [8 examples](examples/) included in the repo, from a
+minimal counter to a full widget catalog. For complete project demos,
+including native Rust extensions, see the
+[plushie-demos](https://github.com/plushie-ui/plushie-demos/tree/main/ruby)
+repository.
+
+## Getting started
+
+Add plushie to your Gemfile:
+
+```ruby
+gem "plushie", "== 0.1.0"
+```
+
+Then:
+
+```bash
+bundle install
+rake plushie:download   # download precompiled renderer binary
+```
+
+Requires Ruby 3.2+. The precompiled binary requires no Rust toolchain.
+
+### Your first app
+
+Create `lib/counter.rb`:
+
+```ruby
+require "plushie"
+
+class Counter
+  include Plushie::App
+
+  Model = Plushie::Model.define(:count)
+
+  def init(_opts) = Model.new(count: 0)
+
+  def update(model, event)
+    case event
+    in Event::Widget[type: :click, id: "increment"]
+      model.with(count: model.count + 1)
+    in Event::Widget[type: :click, id: "decrement"]
+      model.with(count: model.count - 1)
+    else
+      model
+    end
+  end
+
+  def view(model)
+    window("main", title: "Counter") do
+      column(padding: 16, spacing: 8) do
+        text("count", "Count: #{model.count}", size: 20)
+        row(spacing: 8) do
+          button("increment", "+")
+          button("decrement", "-")
+        end
+      end
+    end
+  end
+end
+
+Plushie.run(Counter)
+```
+
+Run it:
+
+```bash
+ruby lib/counter.rb
+```
+
+## The Elm architecture
+
+Plushie follows the Elm architecture. Your app implements four callbacks:
+
+- **`init(opts)`** -- returns the initial model (any Ruby object, ideally
+  immutable via `Plushie::Model.define`).
+- **`update(model, event)`** -- receives the current model and an event,
+  returns the new model. Pure function. Return `[model, command]` for
+  side effects.
+- **`view(model)`** -- receives the model, returns a UI tree using the
+  block DSL. The runtime diffs trees and sends patches to the renderer.
+- **`subscribe(model)`** (optional) -- returns active subscriptions
+  (timers, keyboard/mouse events).
+
+## Features
+
+- **39 built-in widget types** -- buttons, text inputs, sliders, tables,
+  markdown, canvas, pane grids, and more.
+- **22 built-in themes** -- light, dark, dracula, nord, catppuccin,
+  tokyo night, kanagawa, and more.
+- **Multi-window** -- declare window nodes in your widget tree; the
+  framework manages them automatically.
+- **Platform effects** -- native file dialogs, clipboard, OS
+  notifications.
+- **Accessibility** -- screen reader support via accesskit.
+- **Live reload** -- `Plushie.run(MyApp, dev: true)` watches lib/ and
+  reloads on file changes. Model state is preserved.
+- **Remote rendering** -- native desktop UI for server-side Ruby apps
+  over SSH. Your init/update/view code doesn't change.
+- **Widget extensions** -- pure Ruby composites or native Rust-backed
+  custom widgets via `include Plushie::Extension`.
+- **Configuration system** -- `Plushie.configure` for binary paths,
+  extensions, test backends, and extension runtime config.
+- **WASM renderer** -- `rake plushie:download[wasm]` downloads a WASM
+  build of the renderer for browser targets.
+
+## Documentation
+
+**Guides:**
+
+- [Getting started](docs/getting-started.md) -- setup, first app, rake tasks, dev mode
+- [Tutorial: building a todo app](docs/tutorial.md) -- step-by-step walkthrough
+- [App behaviour](docs/app-behaviour.md) -- init, update, view, subscribe callbacks
+- [Layout](docs/layout.md) -- column, row, container, spacing, alignment
+- [Events](docs/events.md) -- widget, keyboard, mouse, window, canvas events
+- [Commands](docs/commands.md) -- async, timers, widget ops, effects, batching
+- [Effects](docs/effects.md) -- file dialogs, clipboard, notifications
+- [Scoped IDs](docs/scoped-ids.md) -- how container nesting scopes widget IDs
+
+**Advanced:**
+
+- [Running](docs/running.md) -- transports, remote rendering, WASM
+- [Theming](docs/theming.md) -- built-in themes and custom styling
+- [Testing](docs/testing.md) -- mock, headless, and windowed backends
+- [Composition patterns](docs/composition-patterns.md) -- tabs, modals, forms, lists
+- [Accessibility](docs/accessibility.md) -- screen reader support, roles, labels
+- [Extensions](docs/extensions.md) -- Ruby composites and native Rust widgets
+- [DSL internals](docs/dsl-internals.md) -- how the UI builder works under the hood
+
+**API reference:** [rubydoc.info/gems/plushie](https://www.rubydoc.info/gems/plushie)
+
+## Testing
+
+All testing goes through the renderer binary. No Ruby-side mocks.
+The mock backend runs at millisecond speed.
+
+Add `require "plushie/test"` to your test helper:
+
+```ruby
+# test/test_helper.rb
+require "plushie"
+require "plushie/test"
+require "minitest/autorun"
+```
+
+Then write tests:
+
+```ruby
+class CounterTest < Plushie::Test::Case
+  app Counter
+
+  def test_clicking_increment_updates_counter
+    click("#increment")
+    assert_text "#count", "Count: 1"
+  end
+end
+```
+
+Three interchangeable backends:
+
+- **Mock** (`PLUSHIE_TEST_BACKEND=mock`) -- millisecond tests, no display.
+  Default.
+- **Headless** (`PLUSHIE_TEST_BACKEND=headless`) -- real rendering via
+  tiny-skia, no display server. Pixel screenshots.
+- **Windowed** (`PLUSHIE_TEST_BACKEND=windowed`) -- real windows with GPU.
+  Needs display server (Xvfb in CI).
+
+## How it works
+
+Under the hood, a renderer built on iced handles window drawing and
+platform integration. Your Ruby code sends widget trees to the
+renderer over stdin; the renderer draws native windows and sends user
+events back over stdout.
+
+You don't need Rust to use plushie. The renderer is a precompiled
+binary, similar to how your app talks to a database without you
+writing C. If you need custom native rendering, the extension system
+lets you write Rust for just those parts.
+
+The same protocol works over a local pipe, an SSH connection, or any
+bidirectional byte stream.
+
+## State helpers
+
+Plushie ships optional state management utilities:
+
+- **`Plushie::Animation`** -- easing functions and interpolation
+- **`Plushie::Route`** -- navigation stack for multi-view apps
+- **`Plushie::Selection`** -- single, multi, and range selection
+- **`Plushie::Undo`** -- undo/redo stacks with coalescing
+- **`Plushie::DataQuery`** -- filter, search, sort, paginate collections
+- **`Plushie::State`** -- path-based state with revision tracking
+
+## Development
+
+```bash
+bundle exec rake              # tests + linter + type check
+bundle exec rake test         # tests only
+bundle exec rake standard     # linter only
+bundle exec rake steep        # type check only
+bundle exec rake yard         # generate API docs to doc/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
+
+Rake tasks (add `require "plushie/rake"` to your Rakefile):
+
+```bash
+rake plushie:download          # download precompiled binary
+rake plushie:download[wasm]    # download WASM renderer
+rake plushie:build             # build from Rust source (with extensions if configured)
+rake plushie:run[Counter]      # run an app
+rake plushie:connect[Counter]  # connect to renderer via stdio
+rake plushie:inspect[Counter]  # print UI tree as JSON
+rake plushie:script            # run .plushie test scripts
+rake plushie:replay[path]      # replay a script with real windows
+rake plushie:preflight         # run all CI checks
+```
+
+Configure the SDK programmatically:
+
+```ruby
+Plushie.configure do |config|
+  config.binary_path = "/opt/plushie/bin/plushie"
+  config.extensions = [MyGauge]
+  config.test_backend = :headless
+end
+```
+
+## System requirements
+
+The precompiled binary has no additional dependencies. To build from
+source, install a Rust toolchain via [rustup](https://rustup.rs/) and
+the platform-specific libraries:
+
+- **Linux (Debian/Ubuntu):**
+  `sudo apt-get install libxkbcommon-dev libwayland-dev libx11-dev cmake fontconfig pkg-config`
+- **Linux (Arch):**
+  `sudo pacman -S libxkbcommon wayland libx11 cmake fontconfig pkgconf`
+- **macOS:** `xcode-select --install`
+- **Windows:**
+  [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+  with "Desktop development with C++"
+
+## Links
+
+| | |
+|---|---|
+| Ruby SDK | [github.com/plushie-ui/plushie-ruby](https://github.com/plushie-ui/plushie-ruby) |
+| Elixir SDK | [github.com/plushie-ui/plushie-elixir](https://github.com/plushie-ui/plushie-elixir) |
+| Renderer | [github.com/plushie-ui/plushie](https://github.com/plushie-ui/plushie) |
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+require "plushie/rake"
+
+desc "Run Steep type checker"
+task :steep do
+  sh "bundle exec steep check"
+end
+
+desc "Generate YARD documentation"
+task :yard do
+  sh "bundle exec yard doc"
+end
+
+task default: %i[test standard steep]

data/Steepfile

@@ -0,0 +1,8 @@
+# Steepfile
+target :lib do
+  signature "sig"
+  check "lib"
+  library "msgpack"
+  library "json"
+  library "logger"
+end