hibiki 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68d12a0c95c1bc55b68b6fe1377a2ca6bcd9bf9116a2ced78de0d6748dd40abb
+  data.tar.gz: 5288e41ed33db0976d15b17bac1aac827344207841921467b25c0e9eef76da8d
+SHA512:
+  metadata.gz: c36067422510591e66e4d244d4a27dd1ae0c6c9f6f33ef4e8d82f340a12b5f7ec456c272855ee8c425df9bdb2f98f8062899169b2c97155f976e076aaf8431bc
+  data.tar.gz: d69a165a500e5355709d98c079f0b026dfe2eea9f09de14b20378513274f02c9f8790021992a8ce9a4e738bd4d5a8feeb89e0e9b3bc3418eb56394edd4579571

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - TBD
+
+### Added
+
+- Initial signal core: `Hibiki::State` (writable signal), `Hibiki::Derived`
+  (lazy computed signal with runtime dependency tracking), `Hibiki::Effect`
+  (eager side effects).
+- Opt-in `Hibiki::DSL` providing bare `state` / `derived` / `effect` helpers.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 planetaska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+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 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.

data/README.md

@@ -0,0 +1,212 @@
+# Hibiki (響き) — Svelte-5-style signals for Ruby
+
+Svelte-5-style signals for Ruby: `state`, `derived`, `effect`.
+
+Hibiki is a fine-grained reactivity library modeled on the signal systems in [Svelte 5](https://svelte.dev/docs/svelte/what-are-runes) and [SolidJS](https://www.solidjs.com/guides/reactivity). Dependency tracking is done at **runtime** (not by static AST analysis): while a derived value or effect is computing, it sits on an observer stack, and any signal read during that window subscribes it.
+
+No runtime dependencies. Requires Ruby >= 3.4.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "hibiki"
+```
+
+Or `gem install hibiki`.
+
+## Usage
+
+You can use Hibiki in two flavors:
+
+```ruby
+# 1. With DSL
+require "hibiki"
+include Hibiki::DSL
+
+x = state(0)
+y = derived { x.value + 1 }
+```
+
+Or if you wish to avoid using DSL:
+
+```ruby
+# 2. Without DSL
+require "hibiki"
+
+x = Hibiki::State.new(0)
+y = Hibiki::Derived.new { x.value + 1 }
+
+x.value = 10
+y.value # => 11
+```
+
+### The three primitives
+
+**`state(v)`** — a writable signal. Reading `.value` registers a dependency; writing notifies subscribers. Writing an `==`-equal value is a no-op.
+
+```ruby
+counter = state(0)
+counter.value += 1
+counter.update { it + 1 } # in-place sugar
+```
+
+**`derived { }`** — a lazy computed signal. It recomputes on read when marked dirty, never on write, and caches its value until a dependency changes.
+
+```ruby
+doubled = derived { counter.value * 2 }
+doubled.value # => 4
+```
+
+**`effect { }`** — an eager side effect. It runs immediately and re-runs whenever a dependency changes.
+
+```ruby
+name = state("world")
+effect { puts "hello, #{name.value}!" } # prints "hello, world!"
+
+# Effect triggers whenever any of the subscribed values changes
+name.value = "Ruby"                     # prints "hello, Ruby!"
+```
+
+### Untracked reads
+
+Sometimes an effect should *sample* a signal without depending on it.
+`Hibiki.untrack { }` suppresses dependency registration for a block, and
+`#peek` is the per-signal shorthand — the classic use is read-modify-write,
+where an effect must not depend on the signal it writes:
+
+```ruby
+count = state(0)
+history = state([])
+
+# Log every count change — without peek, writing history would re-trigger
+# this effect forever (it would depend on its own output).
+effect { history.value = history.peek + [count.value] }
+```
+
+A dirty derived still recomputes on `peek`; only the reader's subscription is
+skipped. Signals also respond to `#call`, mirroring Solid's
+signals-as-getter-functions: `count.call` (or `count.()`) reads and registers.
+
+### Dynamic dependencies
+
+Dependencies are re-collected on every recompute, so conditional reads work:
+
+```ruby
+flag = state(true)
+a = state("A")
+b = state("B")
+picked = derived { flag.value ? a.value : b.value }
+
+picked.value        # => "A"
+b.value = "B2"      # picked doesn't depend on b right now — no recompute
+flag.value = false
+picked.value        # => "B2" (deps re-collected)
+```
+
+### Lifecycle: `root` and `on_cleanup`
+
+Effects created while another effect runs are *owned* by it and disposed
+automatically when the owner re-runs or is disposed. For everything else
+there is `Hibiki.root` (Solid's `createRoot`): an ownership scope you tear
+down yourself — the anchor for long-lived graphs (a session, a connection)
+whose teardown is an external event, not a rerun.
+
+`Hibiki.on_cleanup` (Solid's `onCleanup`) registers teardown on the owning
+effect or root; it runs before each re-run and on dispose — the place to
+release timers, sockets, subscriptions an effect sets up:
+
+```ruby
+interval = state(1)
+
+ticker = Hibiki.root do
+  effect do
+    timer = start_timer(every: interval.value)
+    Hibiki.on_cleanup { timer.cancel } # runs before each re-run, and on dispose
+  end
+end
+
+interval.value = 5 # old timer cancelled, new one started
+ticker.dispose     # tears down every effect in the scope, cleanups included
+```
+
+A root's block runs untracked, and a root created inside an effect is *not*
+adopted by it — it deliberately escapes the automatic owner tree, so its
+lifetime is exactly `Hibiki.root` … `root.dispose`. Individual effects can
+still be disposed directly with `Effect#dispose`.
+
+### Class-based reactivity
+
+Svelte 5 allows `$state`/`$derived`/`$effect` as class fields; `Hibiki::Reactive`
+is the Ruby analogue. Declare signals with class macros and use them as plain
+attributes — no `.value` at usage sites:
+
+```ruby
+class Counter
+  include Hibiki::Reactive
+
+  state :count, 0
+  state(:history) { [] }          # block form: fresh default per instance
+  derived(:doubled) { count * 2 }
+  effect { puts "count is now #{count}" } # starts on Counter.new
+
+  def increment = self.count += 1
+end
+
+counter = Counter.new  # prints "count is now 0"
+counter.increment      # prints "count is now 1"
+counter.doubled        # => 2
+```
+
+Signals are per-instance and created lazily; subclasses inherit all
+declarations. Use the block form for mutable defaults (a positional default
+is one shared object, the same gotcha as Rails attribute defaults).
+
+Effect lifecycle: an instance created *inside* a running effect is adopted by
+the owner tree and cleaned up automatically when that owner re-runs or is
+disposed. For long-lived instances whose effects read signals *outside* the
+instance, call `#dispose` — effects that only read the instance's own signals
+form a self-contained island that garbage-collects with it.
+
+### Why no transparent signals?
+
+Two designs were evaluated and rejected, so they don't need relitigating:
+
+- **Transparent value wrappers** (`method_missing` forwarding to `.value`):
+  Ruby object truthiness cannot be overridden, so `if flag` on a wrapper is
+  always true — it silently breaks conditionals, the exact thing dynamic
+  dependency tracking is best at. `nil?` and `==` lie similarly.
+- **A `reactive do ... end` block DSL**: Ruby has no hook for bare local
+  variable reads or writes, so writes need `self.x =` anyway — at which point
+  a class (above) wears the same design better.
+
+The full walkthrough with examples lives in
+[docs-md/why-no-transparent-signals.md](docs-md/why-no-transparent-signals.md).
+
+## Documentation
+
+Browsable documentation site: <https://planetaska.github.io/hibiki/>
+
+More detail in [docs-md/](docs-md/):
+
+- [Why no transparent signals?](docs-md/why-no-transparent-signals.md) — the two
+  rejected transparency designs, with the failure cases spelled out.
+- [Threading model](docs-md/threading-model.md) — fiber-confined bookkeeping,
+  what is and isn't isolated across threads, fibers, and Ractors.
+- [Status & limitations](docs-md/status-and-limitations.md) — what the signal
+  core already guarantees.
+- [Fragment-level render effects](docs-md/fragment-level-render-effects.md) —
+  a deferred design note: collapsing per-fragment partials/components into
+  methods, each wrapped in its own effect.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake     # specs + rubocop
+ruby demo.rb         # quick smoke demo
+```
+
+## License
+
+[MIT](LICENSE.txt)

data/lib/hibiki/batch.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- batching ---------------------------------------------------------------
+  # Coalesces effect runs. Writes inside the block apply immediately — reads
+  # always see fresh values, and deriveds stay lazy dirty-flags — but effects
+  # invalidated during the block are queued, deduplicated, and run once when
+  # the outermost batch exits. Same semantics as Solid's `batch`.
+  #
+  # Depth and queue are per-execution-context in Thread.current[] — which is
+  # fiber-local, not thread-local, despite the name. Deliberately NOT Fiber[]
+  # (unlike the observer in tracking.rb): Fiber storage is inherited at fiber
+  # creation, and a fiber or thread spawned mid-batch would inherit a nonzero
+  # depth it can never unwind — batching? true forever, its effects deferred
+  # into a queue nobody flushes. The flush belongs to the exact fiber whose
+  # ensure runs it.
+  class << self
+    def batch
+      Thread.current[:hibiki_batch_depth] = batch_depth + 1
+      yield
+    ensure
+      # Flush even when the block raises: writes before the raise have
+      # already landed, so effects must catch up with them.
+      depth = batch_depth - 1
+      Thread.current[:hibiki_batch_depth] = depth
+      flush_effects if depth.zero?
+    end
+
+    def batching? = batch_depth.positive?
+
+    def schedule(effect) = (Thread.current[:hibiki_pending_effects] ||= Set.new) << effect
+
+    # Where effect errors raised during a flush go (Solid's handleError):
+    # a callable receiving (error, effect). With a handler set the flush
+    # never raises; a raising handler propagates — we don't swallow it.
+    # Ractor-local, not a module ivar (IsolationError off the main Ractor)
+    # and not Thread.current[] (configuration set once, e.g. in an
+    # initializer, must be visible to threads spawned later). Per-Ractor
+    # fits the one-independent-world-per-Ractor model.
+    def error_handler = Ractor.current[:hibiki_error_handler]
+
+    def error_handler=(handler)
+      Ractor.current[:hibiki_error_handler] = handler
+    end
+
+    private
+
+    def batch_depth = Thread.current[:hibiki_batch_depth] || 0
+
+    # Swap the queue out before running: an effect may write states and
+    # invalidate further effects, and with the batch over those run eagerly.
+    #
+    # A raising effect must not take the rest of the queue down with it
+    # (Solid's runUpdates completes the queue and routes errors to a
+    # handler): rescue per effect, finish the flush, then re-raise the
+    # first error unless an error_handler took it. StandardError only —
+    # Interrupt and friends should still abort the flush.
+    def flush_effects
+      pending = Thread.current[:hibiki_pending_effects]
+      return if pending.nil? || pending.empty?
+
+      Thread.current[:hibiki_pending_effects] = Set.new
+      first_error = nil
+      pending.each do |effect|
+        error = invalidate_isolated(effect)
+        first_error ||= error
+      end
+      raise first_error if first_error
+    end
+
+    # One queue entry: run it, and route or return its error instead of
+    # raising, so the flush loop always reaches every pending effect.
+    def invalidate_isolated(effect)
+      effect.invalidate
+      nil
+    rescue StandardError => e
+      handler = error_handler
+      return e unless handler
+
+      handler.call(e, effect)
+      nil
+    end
+  end
+end

data/lib/hibiki/derived.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- derived / computed -----------------------------------------------------
+  class Derived
+    include Trackable # observed by downstream deriveds/effects
+    include Observer  # observes its own dependencies
+
+    def initialize(&block)
+      @block = block
+      @dirty = true
+    end
+
+    def value
+      recompute if @dirty
+      register_dependency
+      @value
+    end
+
+    # Read without subscribing the reader. A dirty derived still recomputes
+    # (collecting its own deps as usual) — peek only skips the outward edge.
+    def peek
+      recompute if @dirty
+      @value
+    end
+
+    # Solid signals are getter functions; `sig.()` reads (and registers).
+    def call = value
+
+    def invalidate
+      return if @dirty
+
+      @dirty = true
+      notify # propagate dirtiness downstream (derived-of-derived, effects)
+    end
+
+    def to_s = value.to_s
+    def inspect = "#<Hibiki::Derived #{@dirty ? 'dirty' : @value.inspect}>"
+
+    private
+
+    def recompute
+      clear_sources
+      @value = Hibiki.track(self) { @block.call }
+      @dirty = false
+    end
+  end
+end

data/lib/hibiki/dsl.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- top-level DSL ----------------------------------------------------------
+  # Opt-in: `include Hibiki::DSL` where you want the bare helpers.
+  # The gem never includes it for you (no polluting Object/main).
+  module DSL
+    def state(value) = State.new(value)
+    def derived(&) = Derived.new(&)
+    def effect(scheduler: nil, &) = Effect.new(scheduler:, &)
+    def batch(&)   = Hibiki.batch(&)
+    def root(&)    = Hibiki.root(&)
+    def on_cleanup(&) = Hibiki.on_cleanup(&)
+  end
+end

data/lib/hibiki/effect.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- effect -----------------------------------------------------------------
+  class Effect
+    include Observer # observes, but is never observed (no Trackable)
+    include Owner    # owns effects and cleanups registered while running
+
+    # scheduler: hands re-runs to the caller instead of running inline
+    # (Vue's ReactiveEffect scheduler): a callable receiving the effect,
+    # which calls #run whenever it's ready — on the graph's own execution
+    # context. The initial run is never scheduled: dependency collection
+    # must happen at creation, and Vue's constructor runs directly too.
+    def initialize(scheduler: nil, &block)
+      @block = block
+      @scheduler = scheduler
+      @disposed = false
+      # Effects created while another effect (or root) runs are owned by it
+      # and disposed when the owner re-runs or is disposed.
+      Hibiki.current_owner&.adopt(self)
+      run
+    end
+
+    def disposed? = @disposed
+
+    # Sever every subscription and take owned children/cleanups down with
+    # us. A disposed effect never runs again — including a pending batch
+    # flush.
+    def dispose
+      return if @disposed
+
+      @disposed = true
+      dispose_owned
+      clear_sources
+    end
+
+    # Under a batch, defer: Hibiki queues us (deduplicated) and re-runs the
+    # block once at flush instead of once per write. With a scheduler, the
+    # re-run is handed to it right where it would have happened — after the
+    # batch dedup, so the flush's error isolation covers a raising scheduler
+    # too, and N batched writes mean one scheduler call.
+    def invalidate
+      return if @disposed
+      return Hibiki.schedule(self) if Hibiki.batching?
+      return @scheduler.call(self) if @scheduler
+
+      run
+    end
+
+    # Public for scheduled effects: the scheduler (or whoever it handed us
+    # to) calls this when it's time to re-run. No-op once disposed — a
+    # debounced run firing late must lose to dispose, like a pending flush
+    # does. A raise propagates to the caller: a deferred run is outside any
+    # flush, so the integration owns rescue there.
+    def run
+      return if @disposed
+
+      dispose_owned
+      clear_sources
+      Hibiki.own(self) do
+        Hibiki.track(self) { @block.call }
+      end
+    end
+  end
+end

data/lib/hibiki/reactive.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- class-level reactivity -------------------------------------------------
+  # Svelte 5 allows $state/$derived/$effect as class fields; Reactive is the
+  # Ruby analogue — declare signals with class macros, use them as plain
+  # attributes:
+  #
+  #   class Counter
+  #     include Hibiki::Reactive
+  #     state :count, 0
+  #     derived(:doubled) { count * 2 }
+  #     effect { puts "count is now #{count}" } # starts on initialize
+  #
+  #     def increment = self.count += 1
+  #   end
+  #
+  # Readers and writers are ordinary methods over per-instance signals, so
+  # usage sites never touch `.value` and dependency tracking flows through
+  # plain method calls. Signals are created lazily on first touch (read or
+  # write): no initialize hook is needed for state/derived, and subclasses
+  # inherit declarations because the generated methods inherit.
+  module Reactive
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.prepend(Initializer)
+    end
+
+    module ClassMethods
+      # state :count, 0
+      # state(:items) { [] }
+      # A positional default is shared across instances (it's one object) —
+      # use the block form for mutable defaults. The block is evaluated per
+      # instance, instance_exec'd, and untracked: first touch may happen
+      # inside some effect's tracking window, and a default that reads other
+      # signals must not subscribe that outer observer.
+      def state(name, default = nil, &default_block)
+        init = proc do
+          State.new(default_block ? Hibiki.untrack { instance_exec(&default_block) } : default)
+        end
+        define_method(name) { __hibiki_signal(name, init).value }
+        define_method(:"#{name}=") { |new_value| __hibiki_signal(name, init).value = new_value }
+      end
+
+      def derived(name, &)
+        init = proc { Derived.new { instance_exec(&) } }
+        define_method(name) { __hibiki_signal(name, init).value }
+      end
+
+      # Anonymous, so unlike state/derived it can't ride on method
+      # inheritance: blocks are collected per class and gathered up the
+      # ancestor chain at initialize.
+      def effect(&block) = hibiki_effect_blocks << block
+
+      def hibiki_effect_blocks = (@hibiki_effect_blocks ||= [])
+    end
+
+    # Prepended so declared effects start after the user's initialize ran
+    # (they usually read state the constructor is expected to have set up).
+    module Initializer
+      def initialize(...)
+        super
+        blocks = self.class.ancestors.reverse.flat_map do |mod|
+          mod.respond_to?(:hibiki_effect_blocks) ? mod.hibiki_effect_blocks : []
+        end
+        @__hibiki_effects = blocks.map { |block| Effect.new { instance_exec(&block) } }
+      end
+    end
+
+    # Dispose every effect this instance started. Instances created inside a
+    # running effect don't need this — Effect.new adopts them into the owner
+    # tree and the owner's rerun/dispose takes them down. Explicitly needed
+    # only for long-lived instances whose effects read signals *outside* the
+    # instance (effects reading only the instance's own signals form a
+    # self-contained island that garbage-collects with it).
+    def dispose = @__hibiki_effects.each(&:dispose)
+
+    private
+
+    def __hibiki_signal(name, init)
+      (@__hibiki_signals ||= {})[name] ||= instance_exec(&init)
+    end
+  end
+end

data/lib/hibiki/root.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- root -------------------------------------------------------------------
+  # Solid's createRoot: an ownership scope that is not an effect. Effects
+  # and cleanups created inside the block belong to the root and live until
+  # #dispose — the lifecycle anchor for long-lived graphs (a session, a
+  # connection) whose teardown is an external event, not a rerun.
+  #
+  # Deliberately detached: a root created inside a running effect is NOT
+  # adopted, so the enclosing effect's rerun/disposal leaves it alone
+  # (Solid's escape hatch from the owner tree). Whoever holds the root
+  # disposes it.
+  #
+  # The block runs untracked (Solid clears the Listener in createRoot): a
+  # root built mid-effect must not subscribe that effect to signals it
+  # reads.
+  class Root
+    include Owner
+
+    def initialize(&block)
+      @disposed = false
+      Hibiki.own(self) do
+        Hibiki.untrack { block.call(self) }
+      end
+    end
+
+    def disposed? = @disposed
+
+    def dispose
+      return if @disposed
+
+      @disposed = true
+      dispose_owned
+    end
+  end
+
+  class << self
+    # Hibiki.root { |root| ... } — build a graph inside an ownership scope;
+    # tear the whole thing down later with root.dispose. Unlike Solid
+    # (which returns the block's result and yields a dispose function) the
+    # root itself is yielded AND returned: in Ruby the caller, not the
+    # block, typically owns teardown.
+    def root(&) = Root.new(&)
+  end
+end

data/lib/hibiki/state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- writable signal --------------------------------------------------------
+  class State
+    include Trackable
+
+    def initialize(value)
+      @value = value
+    end
+
+    def value
+      register_dependency
+      @value
+    end
+
+    # Read without subscribing (per-signal untrack), for read-modify-write
+    # effects that must not depend on what they write.
+    def peek = @value
+
+    # Solid signals are getter functions; `sig.()` reads (and registers).
+    def call = value
+
+    def value=(new_value)
+      return if new_value == @value
+
+      @value = new_value
+      # Solid wraps every write in runUpdates; mirroring that, an unbatched
+      # write becomes an implicit batch of one. The whole invalidation wave
+      # (all diamond branches) lands before effects flush, so an effect runs
+      # once per write and never sees a half-updated graph.
+      Hibiki.batch { notify }
+    end
+
+    # sugar for in-place updates: counter.update { it + 1 }
+    def update = self.value = yield(@value)
+
+    def to_s = value.to_s
+    def inspect = "#<Hibiki::State #{@value.inspect}>"
+  end
+end

data/lib/hibiki/tracking.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Hibiki
+  # ---- observer / owner context (the heart of runtime dependency tracking) --
+  # Per-execution-context, in Fiber storage (Fiber[], Ruby 3.2+), not module
+  # ivars: concurrent contexts must not see each other's tracking windows, and
+  # module ivars raise Ractor::IsolationError off the main Ractor. Fiber[] over
+  # Thread.current[] (which is fiber-local too, despite the name) because it is
+  # inherited at fiber creation — reads inside an Enumerator's internal fiber
+  # still register, where uninherited storage would silently drop the edge.
+  # The explicit stacks are gone: save/restore around the block makes the call
+  # stack the stack.
+  class << self
+    def current_observer = Fiber[:hibiki_observer]
+
+    def track(observer)
+      prev = Fiber[:hibiki_observer]
+      Fiber[:hibiki_observer] = observer
+      yield
+    ensure
+      Fiber[:hibiki_observer] = prev
+    end
+
+    # Solid's untrack: reads inside the block register nothing. Only the
+    # listener is suppressed — the owner slot is left alone, so effects
+    # created under untrack are still adopted.
+    def untrack(&) = track(nil, &)
+
+    # Solid keeps Owner separate from Listener: only effects own, and a lazy
+    # derived computing mid-effect must not steal ownership of effects its
+    # block creates. Hence a second slot rather than reusing the observer's.
+    def current_owner = Fiber[:hibiki_owner]
+
+    def own(owner)
+      prev = Fiber[:hibiki_owner]
+      Fiber[:hibiki_owner] = owner
+      yield
+    ensure
+      Fiber[:hibiki_owner] = prev
+    end
+
+    # Solid's onCleanup: registers on the current OWNER, not the listener —
+    # a lazy derived computing mid-effect registers cleanups on the effect,
+    # matching how effects created there are adopted. The block runs before
+    # the owner's next rerun and on dispose. Outside any owner it can never
+    # run; mirror Solid and warn rather than raise.
+    def on_cleanup(&block)
+      owner = current_owner
+      return warn("Hibiki.on_cleanup: no current owner (effect or root); the cleanup can never run") unless owner
+
+      owner.add_cleanup(block)
+      block
+    end
+  end
+
+  # ---- shared subscription behaviour -----------------------------------------
+  module Trackable
+    def subscribers = (@subscribers ||= Set.new)
+
+    # Called on every read: if someone reactive is currently computing,
+    # they now depend on us — record both directions of the edge, so the
+    # observer can sever it before its next rerun.
+    def register_dependency
+      observer = Hibiki.current_observer
+      return unless observer
+
+      subscribers << observer
+      observer.add_source(self)
+    end
+
+    def unsubscribe(observer) = subscribers.delete(observer)
+
+    def notify
+      # dup: invalidation may mutate the set while we iterate
+      subscribers.dup.each(&:invalidate)
+    end
+  end
+
+  # ---- shared observer behaviour ----------------------------------------------
+  # The reverse edges of Trackable: what an observer read on its last run.
+  module Observer
+    def sources = (@sources ||= Set.new)
+    def add_source(source) = sources << source
+
+    # Solid clears deps before rerun (cleanNode); we mirror that, so stale
+    # branches of dynamic deps (flag ? a : b) stop invalidating us.
+    def clear_sources
+      sources.each { |source| source.unsubscribe(self) }
+      sources.clear
+    end
+  end
+
+  # ---- shared owner behaviour ---------------------------------------------------
+  # Solid's Owner half of a computation: effects and roots own the child
+  # effects and cleanups registered while their block runs, and tear them
+  # down together on rerun/dispose.
+  module Owner
+    # Effects created while our block runs become ours: when we re-run or
+    # are disposed, they are disposed too (Solid's owner tree). Otherwise a
+    # re-creating rerun would leak live duplicates.
+    def adopt(child) = (@children ||= []) << child
+
+    def add_cleanup(block) = (@cleanups ||= []) << block
+
+    private
+
+    # Solid's cleanNode: children go down before our own cleanups run (a
+    # child's cleanup may still need a resource ours tears down), cleanups
+    # in LIFO order like nested ensure blocks. Both lists are swapped out
+    # first, so a rerun adopts fresh entries into a clean slate while the
+    # previous generation is being torn down.
+    def dispose_owned
+      children = @children || []
+      @children = []
+      children.each(&:dispose)
+
+      cleanups = @cleanups || []
+      @cleanups = []
+      cleanups.reverse_each(&:call)
+    end
+  end
+end

data/lib/hibiki/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hibiki
+  VERSION = "0.1.0"
+end

data/lib/hibiki.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Hibiki — a minimal Svelte-5-style signal system in Ruby.
+#
+# Three primitives, same as Solid/Svelte 5 internals:
+#   state(v)      -> writable signal
+#   derived { }   -> lazy computed signal with runtime dependency tracking
+#   effect { }    -> side effect that re-runs when its dependencies change
+#
+# Plus `batch { }`, which coalesces effect runs across multiple writes, and
+# lifecycle scoping: `root { }` (an ownership scope disposed by its holder)
+# and `on_cleanup { }` (per-run teardown on the owning effect or root).
+#
+# Dependency tracking works exactly like the JS frameworks: while a derived
+# or effect is (re)computing, it is pushed onto an "observer stack". Any
+# signal whose value is READ during that window registers the observer as a
+# subscriber. Writes then invalidate subscribers transitively.
+
+require_relative "hibiki/version"
+require_relative "hibiki/tracking"
+require_relative "hibiki/batch"
+require_relative "hibiki/state"
+require_relative "hibiki/derived"
+require_relative "hibiki/effect"
+require_relative "hibiki/root"
+require_relative "hibiki/reactive"
+require_relative "hibiki/dsl"

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: hibiki
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- planetaska
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A fine-grained reactivity library modeled on the signal systems in Svelte
+  5 and SolidJS. Runtime dependency tracking, not static analysis: while a derived
+  or effect computes, any signal read during that window subscribes it. Writable state,
+  lazy derived values, and eager effects.'
+email:
+- planetaska@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/hibiki.rb
+- lib/hibiki/batch.rb
+- lib/hibiki/derived.rb
+- lib/hibiki/dsl.rb
+- lib/hibiki/effect.rb
+- lib/hibiki/reactive.rb
+- lib/hibiki/root.rb
+- lib/hibiki/state.rb
+- lib/hibiki/tracking.rb
+- lib/hibiki/version.rb
+homepage: https://github.com/planetaska/hibiki
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/planetaska/hibiki
+  source_code_uri: https://github.com/planetaska/hibiki
+  changelog_uri: https://github.com/planetaska/hibiki/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Svelte-5-style signals for Ruby: state, derived, effect.'
+test_files: []