plushie 0.0.1 → 0.6.0

data/CHANGELOG.md

@@ -0,0 +1,209 @@
+# 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.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.
+
+### 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`, `widgets`, `widget_config`,
+  `test_backend`
+- `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
+  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 + 4.0 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/CLAUDE.md

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

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,166 @@
-# Plushie for Ruby
+# plushie
 
-Native GUI toolkit for Ruby, powered by native rendering via Iced.
+Build native desktop apps in Ruby. **[Pre-1.0](#status)**
 
-This is a placeholder release to reserve the package name. The first
-functional release is coming soon.
+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.
 
-Source: <https://github.com/plushie-ui/plushie>
+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
+  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)
+```
+
+Add plushie to your Gemfile and download the renderer:
+
+```bash
+# Gemfile
+gem "plushie", "== 0.1.0"
+```
+
+```bash
+bundle install
+rake plushie:download   # download precompiled renderer binary
+ruby lib/counter.rb
+```
+
+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.
+
+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.
+
+## How it works
+
+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.
+
+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.
+
+The same protocol works over a local pipe, an SSH connection, or
+any bidirectional byte stream. Your code doesn't need to change.
+
+## Features
+
+- **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("#inc")
+    assert_text "#count", "Count: 1"
+  end
+end
+```
+
+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.
+
+## Status
+
+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
+
+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,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"
+
+  # 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