plushie 0.5.0 → 0.6.0

data/CHANGELOG.md

@@ -4,6 +4,150 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.6.0] - 2026-05-09
+
+Targets plushie-renderer 0.7.1.
+
+### Breaking changes
+
+- Environment variable `PLUSHIE_SOURCE_PATH` renamed to
+  `PLUSHIE_RUST_SOURCE_PATH`. Update shell profiles and CI configs.
+- Constant `Plushie::BINARY_VERSION` renamed to
+  `Plushie::PLUSHIE_RUST_VERSION` to match the plushie-rust release
+  identifier. Anything referencing the old name needs updating.
+- `Command.async` renamed to `Command.task` for cross-SDK consistency
+  (`async` is reserved in Python and Rust). `Command.done` renamed to
+  `Command.dispatch` to reflect the "send through update" semantic.
+  `Command.widget_commands` renamed to `Command.widget_batch` to match
+  the Elixir SDK and disambiguate from the `Plushie::Command` type.
+- Grid widget `columns` prop renamed to `num_columns`.
+- `Command.Image.create_image` and `update_image` no longer accept
+  `pixels:`, `width:`, `height:` keyword arguments for raw RGBA data.
+  Use the new dedicated `create_image_rgba(handle, width, height, pixels)`
+  and `update_image_rgba(handle, width, height, pixels)` constructors
+  instead. The blob-data form of `create_image` and `update_image`
+  (passing raw binary data directly) is unchanged.
+- Table widget `:selected` and `:striped` props removed; they were
+  dead code with no renderer-side effect.
+
+### Added
+
+- `Plushie::CargoPlushie.resolve` helper that locates a usable
+  cargo-plushie via `PLUSHIE_RUST_SOURCE_PATH`, falling back to a
+  version-matched binary on `PATH`, otherwise raising with
+  `cargo install cargo-plushie --version <version> --locked`
+  guidance.
+- `docs/versioning.md` documenting the `PLUSHIE_RUST_VERSION` pin and
+  SDK-vs-plushie-rust versioning rules.
+- `Event::SessionError` and `Event::SessionClosed` typed variants.
+  `SessionError` includes a `code` field carrying the numeric error code
+  from the renderer.
+- `Event::Diagnostic` typed variants: `crash`, `update_panicked`,
+  `renderer_error`, `protocol_error`, and `unknown`. Previously all
+  diagnostics arrived as the generic `Diagnostic` struct; each kind
+  now has its own Data class with kind-specific fields.
+- `Plushie::BufferOverflowError` and `Plushie::ProtocolVersionMismatchError`
+  typed error classes raised on the matching renderer-side conditions.
+- `Event::Effect` typed per-kind result variants. Effect callbacks now
+  receive a typed struct rather than a raw Hash.
+- `RichText::Span` typed Data class for inline text spans.
+- `link_click` events decoded as a typed `:link_click` variant on
+  `Event::Widget`.
+- Touch release events carry a `lost` flag when the pointer left the
+  window before the release.
+- `Rule` widget `thickness` prop as a direction-agnostic alternative to
+  the existing `width`/`height` split.
+- SDK-side event coalescing: high-frequency events declared coalesable
+  are deduplicated in the bounded queue before reaching `update`.
+- `Command.dispatch` chain depth is now capped; dispatching beyond the
+  limit raises rather than looping indefinitely.
+- `Binary.resolve` falls back to a locally built renderer binary under
+  `../plushie-rust/target/{release,debug}/plushie-renderer` when
+  `PLUSHIE_RUST_SOURCE_PATH` is set and no explicit path is configured.
+- `rake plushie:preflight` rebuilds the renderer binary from the local
+  plushie-rust checkout when `PLUSHIE_RUST_SOURCE_PATH` is set.
+- Negative padding, border width, and border radius values are now
+  rejected at build time with an `ArgumentError`.
+
+### Fixed
+
+- Subscription `key_press` and `key_release` events now read the
+  structured key payload (`key`, `modified_key`, `physical_key`,
+  `location`, `text`, `repeat`) from the `value` field. The previous
+  fallback to top-level message fields read modifiers from the wrong
+  location when value was non-Hash and would silently misread future
+  shape changes.
+- `animation_frame` and `theme_changed` no longer carry dead fallback
+  reads alongside the canonical `value` access; the fallbacks could
+  never fire against the real renderer and masked the intended source
+  field.
+- `ime_preedit` and `ime_commit` now raise `ArgumentError` when the
+  `value` payload is missing or non-Hash, surfacing wire-shape drift
+  instead of producing an `Event::Ime` with nil text and cursor.
+- Concurrency bugs in the runtime, bridge, and session pool: a race in
+  the timer scheduler, a missing mutex on effect-kind state, and a
+  session-pool drain condition that could deadlock under session churn.
+- Cancelled async threads are now properly released; previously a
+  cancelled task could hold its thread until the pool was torn down.
+- Effect cancellation events are dispatched to `update` during SDK
+  shutdown so apps can clean up transient state.
+- `image_list` and `image_clear` now route through the typed `image_op`
+  wire channel rather than a generic command envelope.
+- `default_font` is always encoded as a `{ family: ... }` object; the
+  previous path emitted a bare string that the renderer rejected.
+- `window_opened` position fields are now read from top-level `x`/`y`
+  keys as the protocol specifies; the previous path read from a nested
+  `position` map that does not exist.
+- Effect tag supersession correctly clears the effect-kinds index when
+  a new registration replaces an existing one under the same tag.
+- Unknown event families tolerate a missing `window_id` field instead
+  of raising a `KeyError`.
+- Wayland-specific environment variables are now forwarded to the
+  renderer subprocess.
+- `Plushie.configure { |c| c.log_level = ... }` is now honoured; the
+  previous path set the logger level only on the initial connection,
+  which was overwritten on restart.
+- Renderer build lookup no longer raises on a missing `_build` directory;
+  it falls through to the next resolution step.
+- Runtime event queue is bounded; a stalled app no longer causes
+  unbounded memory growth under high-frequency event sources.
+- Widget state callbacks are no longer inherited across unrelated widget
+  subclasses defined with `Widget.define`.
+- Effects are cancelled and their callbacks suppressed when the SDK
+  shuts down.
+- Timeout error messages include the action and selector for easier
+  diagnosis in test output.
+- Widget set override names are validated to prevent accidental
+  shadowing of built-in DSL methods.
+- Renderer exit details are sanitised before appearing in error messages
+  and logs.
+
+### Changed
+
+- Native widget builds now delegate workspace generation and
+  `cargo build` to [cargo-plushie](https://crates.io/crates/cargo-plushie).
+  The Ruby SDK writes a minimal virtual app manifest under
+  `_build/plushie-renderer-spec/` and shells out to
+  `cargo plushie build`. Widget discovery, [patch.crates-io] forwarding,
+  collision checks, and constructor validation now live in
+  cargo-plushie and are shared across host SDKs.
+- Native widget crates must now declare
+  `[package.metadata.plushie.widget] { type_name, constructor }` in
+  their Cargo.toml. cargo-plushie uses that table for discovery.
+- Renderer subprocess environment is now filtered to variables with a
+  `PLUSHIE_` prefix plus a small display-server allowlist. Previously
+  the full shell environment was forwarded.
+- Per-timer threads replaced with a single `TimerScheduler` thread
+  using deadline-based `IO.select`. Timer count no longer scales the
+  thread count.
+- Renderer restart backoff parameters, nil-view handling, and frozen
+  overlay semantics aligned with the Elixir and other SDKs.
+
+### Removed
+
+- The checked-in `native/plushie/Cargo.lock` stash. cargo-plushie
+  manages the scratch workspace's lock file.
+
 ## [0.5.0] - 2026-03-23
 
 Initial release. Targets plushie-renderer 0.5.0.
@@ -35,9 +179,9 @@ Initial release. Targets plushie-renderer 0.5.0.
   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`,
+  `source_path`, `build_name`, `widgets`, `widget_config`,
   `test_backend`
-- `extension_config` runtime configuration passed to Rust extensions
+- `widget_config` runtime configuration passed to native widgets
   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
@@ -54,7 +198,7 @@ Initial release. Targets plushie-renderer 0.5.0.
 - 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)
+- GitHub Actions CI workflow (Ruby 3.2 + 3.3 + 4.0 matrix)
 - CONTRIBUTING.md with commit conventions and development guide
 - Rake tasks: download, build, run, connect, inspect, script, replay,
   preflight

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/README.md

@@ -1,12 +1,21 @@
 # plushie
 
-Build native desktop apps in Ruby. **Pre-1.0**
+Build native desktop apps in Ruby. **[Pre-1.0](#status)**
 
-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.
+Write your entire application in Ruby (state, events, UI) and get
+native windows on Linux, macOS, and Windows. Available on
+[RubyGems](https://rubygems.org/gems/plushie) as `plushie`. The
+[renderer](https://github.com/plushie-ui/plushie-rust) is built on
+[Iced](https://github.com/iced-rs/iced) and ships as a precompiled
+binary, no Rust toolchain required.
+
+SDKs are also available for
+[Elixir](https://github.com/plushie-ui/plushie-elixir),
+[Gleam](https://github.com/plushie-ui/plushie-gleam),
+[Python](https://github.com/plushie-ui/plushie-python), and
+[TypeScript](https://github.com/plushie-ui/plushie-typescript).
+
+## Quick start
 
 ```ruby
 class Counter
@@ -43,257 +52,114 @@ 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:
+Add plushie to your Gemfile and download the renderer:
 
-```ruby
+```bash
+# Gemfile
 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:**
+Requires Ruby 3.2+. The repo includes
+[several other examples](examples/) you can try. For multi-file
+projects (custom widgets, native Rust extensions, real project
+scaffolding), see the
+[plushie-demos](https://github.com/plushie-ui/plushie-demos/tree/main/ruby)
+repo.
 
-- [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
+To add Plushie to your own project, see the
+[getting started guide](docs/getting-started.md), or browse the
+[docs](docs/) for all guides and references.
 
-**API reference:** [rubydoc.info/gems/plushie](https://www.rubydoc.info/gems/plushie)
+## How it works
 
-## Testing
+Your Ruby application and the renderer run as two OS processes
+that exchange messages. Think of it like talking to a database,
+except the database is a GPU-accelerated GUI toolkit. The SDK builds
+UI trees and handles events; the renderer draws native windows and
+captures input.
 
-All testing goes through the renderer binary. No Ruby-side mocks.
-The mock backend runs at millisecond speed.
+The SDK diffs each new tree against the previous one and sends only
+the changes. If the renderer crashes, Plushie restarts it and
+re-syncs your state. If your code raises, the SDK reverts to the
+last good state. Neither process can take the other down.
 
-Add `require "plushie/test"` to your test helper:
+The same protocol works over a local pipe, an SSH connection, or
+any bidirectional byte stream. Your code doesn't need to change.
 
-```ruby
-# test/test_helper.rb
-require "plushie"
-require "plushie/test"
-require "minitest/autorun"
-```
+## Features
 
-Then write tests:
+- **Elm architecture** - init, update, view. State lives in Ruby,
+  pure functions, predictable updates
+- **Block DSL** - nested Ruby blocks build the widget tree with
+  natural indentation, no templates or markup
+- **Built-in widgets** - layout, input, display, and interactive
+  widgets out of the box
+- **Canvas** - shapes, paths, gradients, transforms, and
+  interactive elements for custom 2D drawing
+- **Themes** - dark, light, nord, catppuccin, tokyo night, and
+  more, with custom palettes and per-widget style overrides
+- **Animation** - renderer-side transitions, springs, and
+  sequences with no wire traffic per frame
+- **Multi-window** - declare windows in your view; the framework
+  manages the rest
+- **Platform effects** - native file dialogs, clipboard, OS
+  notifications
+- **Accessibility** - keyboard navigation, screen readers, and
+  focus management via [AccessKit](https://accesskit.dev)
+- **Custom widgets** - compose existing widgets in pure Ruby,
+  draw on the canvas, or extend with native Rust
+- **Hot reload** - `Plushie.run(MyApp, dev: true)` watches lib/
+  and reloads on file changes with full state preservation
+- **Remote rendering** - app on a server or embedded device,
+  renderer on a display machine over SSH or any byte stream
+- **Fault-tolerant** - renderer crashes auto-recover; app
+  exceptions are caught and state reverted
+- **Configuration system** - `Plushie.configure` for binary paths,
+  extensions, test backends, and widget runtime config
+- **WASM renderer** - `rake plushie:download[wasm]` for browser
+  targets
+
+## Testing and automation
+
+Tests run through the real renderer binary, not mocks. Interact like
+a user: click, type, find elements, assert on text. All backends
+support concurrent test execution to keep your suite fast as it
+grows. Three interchangeable backends:
+
+- **Mock** - millisecond tests, no display server
+- **Headless** - real rendering via
+  [tiny-skia](https://github.com/linebender/tiny-skia), supports
+  screenshots for pixel regression in CI
+- **Windowed** - real windows with GPU rendering, platform effects,
+  real input
 
 ```ruby
 class CounterTest < Plushie::Test::Case
   app Counter
 
   def test_clicking_increment_updates_counter
-    click("#increment")
+    click("#inc")
     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++"
+The same interaction API is available outside Minitest via
+`Plushie::Automation::Session`. Attach to any running app and drive
+it programmatically. Agent-friendly by design.
 
-## Links
+## Status
 
-| | |
-|---|---|
-| 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) |
+Pre-1.0. The core works (built-in widgets, event system, themes,
+multi-window, testing framework, accessibility) but the API is
+still evolving. Pin to an exact version and read the
+[CHANGELOG](CHANGELOG.md) when upgrading.
 
 ## License
 

data/Steepfile

@@ -1,8 +1,52 @@
 # Steepfile
+#
+# Files listed here are type-checked against their RBS declarations.
+# Files with heavy metaprogramming (widget.rb define_method closures,
+# Widget.define class_eval blocks) are excluded because Steep cannot
+# analyze their dynamic method generation.
 target :lib do
   signature "sig"
-  check "lib"
-  library "msgpack"
+
+  # Core modules
+  check "lib/plushie/app.rb"
+  check "lib/plushie/encode.rb"
+  check "lib/plushie/event/specs.rb"
+  check "lib/plushie/key_modifiers.rb"
+  check "lib/plushie/route.rb"
+  check "lib/plushie/selection.rb"
+  check "lib/plushie/undo.rb"
+  check "lib/plushie/version.rb"
+
+  # Excluded from checking (RBS declarations retained for consumers):
+  #
+  # - model.rb: Extensions#with is defined inside a Data.define block;
+  #   Steep resolves `self` to the enclosing module, not the Data class.
+  # - node.rb: Node = Data.define block; same self-resolution issue.
+  # - subscription.rb: Sub = Data.define block; same self-resolution issue.
+  # - event.rb: Widget/Key/Ime/Window/Modifiers/CommandError/System are
+  #   all Data.define with block overrides; same self-resolution issue.
+
+  # Tree (normalization, search, diff)
+  check "lib/plushie/tree.rb"
+  check "lib/plushie/tree/search.rb"
+  check "lib/plushie/tree/diff.rb"
+
+  # Protocol (decode is the most type-critical)
+  check "lib/plushie/protocol.rb"
+  check "lib/plushie/protocol/decode.rb"
+
+  # Runtime
+  check "lib/plushie/runtime.rb"
+  check "lib/plushie/runtime/commands.rb"
+  check "lib/plushie/animation.rb"
+
+  # Widget build helpers
+  check "lib/plushie/widget/build.rb"
+
+  # Type modules
+  check "lib/plushie/type/line_height.rb"
+
   library "json"
   library "logger"
+  library "securerandom"
 end

data/docs/README.md

@@ -0,0 +1,56 @@
+# Documentation
+
+## Guides
+
+Sequential chapters that build on each other. Start here if you're
+new to Plushie.
+
+1. [Introduction](guides/01-introduction.md) - what Plushie is and how it works
+2. [Getting Started](guides/02-getting-started.md) - installation, binary setup, first run
+3. [Your First App](guides/03-your-first-app.md) - building a counter with the Elm architecture
+4. [The Development Loop](guides/04-the-development-loop.md) - hot reload, IRB, debugging
+5. [Events](guides/05-events.md) - widget events, keyboard, pointer, pattern matching
+6. [Lists and Inputs](guides/06-lists-and-inputs.md) - dynamic lists, text inputs, forms
+7. [Layout](guides/07-layout.md) - rows, columns, containers, responsive sizing
+8. [Styling](guides/08-styling.md) - themes, colors, fonts, per-widget style overrides
+9. [Animation and Transitions](guides/09-animation.md) - transitions, springs, tweens, easing
+10. [Subscriptions](guides/10-subscriptions.md) - timers, global key/pointer events, window events
+11. [Async and Effects](guides/11-async-and-effects.md) - tasks, streams, platform effects
+12. [Canvas](guides/12-canvas.md) - shapes, layers, transforms, interactive elements
+13. [Custom Widgets](guides/13-custom-widgets.md) - composing widgets, canvas widgets, native Rust widgets
+14. [State Management](guides/14-state-management.md) - routing, undo/redo, selection, data pipelines
+15. [Testing](guides/15-testing.md) - test framework, backends, selectors, screenshots
+16. [Shared State](guides/16-shared-state.md) - multi-session apps over SSH
+17. [Packaging](guides/17-packaging.md) - publishing a gem and shipping a native renderer
+
+## Reference
+
+Lookup material organized by topic. Each page is self-contained.
+
+- [Accessibility](reference/accessibility.md) - AccessKit integration, roles, labels, keyboard navigation
+- [Animation](reference/animation.md) - transitions, springs, sequences, easing curves, animatable props
+- [App Lifecycle](reference/app-lifecycle.md) - init/update/view callbacks, startup, renderer restart
+- [Built-in Widgets](reference/built-in-widgets.md) - every widget with props, events, and examples
+- [Canvas](reference/canvas.md) - shapes, layers, groups, transforms, clips, gradients
+- [Commands and Effects](reference/commands.md) - async, focus, scroll, window ops, platform effects
+- [Composition Patterns](reference/composition-patterns.md) - reusable components, overlays, navigation, state-helper integration
+- [Configuration](reference/configuration.md) - Plushie.configure, environment variables, runtime options
+- [Custom Types](reference/custom-types.md) - shared prop-type catalog
+- [Custom Widgets](reference/custom-widgets.md) - Widget.define, behavioral widgets, canvas widgets, native crates
+- [DSL](reference/dsl.md) - block DSL mechanics, context stack, auto-IDs, memo caching
+- [Events](reference/events.md) - every event class, widget event taxonomy, pattern-matching cookbook
+- [Native Extensions](reference/native-extension.md) - authoring a Rust widget crate and shipping it alongside a Ruby gem
+- [Rake Tasks](reference/rake-tasks.md) - plushie:download, plushie:build, plushie:run, preflight
+- [Scoped IDs](reference/scoped-ids.md) - ID scoping rules, scope matching, command paths
+- [Subscriptions](reference/subscriptions.md) - timer, keyboard, pointer, window, catch-all subscriptions
+- [Testing](reference/testing.md) - Plushie::Test::Case, RSpec helpers, backends, snapshots, scripts
+- [Themes and Styling](reference/themes-and-styling.md) - built-in themes, custom palettes, style maps, gradients
+- [Versioning](reference/versioning.md) - SDK version, PLUSHIE_RUST_VERSION pinning, Ruby version floor
+- [Windows and Layout](reference/windows-and-layout.md) - window props, layout containers, Length/Padding/Alignment/Border/Shadow
+- [Wire Protocol](reference/wire-protocol.md) - MessagePack/JSONL framing, handshake, session multiplexing
+
+## Other resources
+
+- [Examples](https://github.com/plushie-ui/plushie-ruby/tree/main/examples) - example apps included in the repo
+- [Changelog](../CHANGELOG.md) - version history and migration notes
+- [Demo apps](https://github.com/plushie-ui/plushie-demos/tree/main/ruby) - multi-file projects with custom widgets and real scaffolding