weft 0.1.0 → 0.2.0

data/lib/weft/router/oob_includes.rb

@@ -1,33 +1,218 @@
 # frozen_string_literal: true
 
+require "weft/context"
+require "weft/dsl/sandbox"
+require "weft/params/assembly"
+
 module Weft
   class Router
-    # OOB-include slice of the Router. Renders sibling components declared
-    # via `includes` alongside an action response or SSE push, with the
-    # `hx-swap-oob` attribute set so htmx swaps each into its own DOM slot.
+    # OOB-include slice of the Router. Renders companion components declared
+    # via `includes` alongside a response, with the `hx-swap-oob` attribute
+    # set so htmx swaps each into its own DOM slot.
     #
-    # Depends on Router internals: `resolver`, `filtered_params`,
-    # `build_component_with_attrs`.
+    # Depends on Router internals: `filtered_params`,
+    # `build_component_with_wire`, and the Errors slice's identity and
+    # recovery helpers (`unbuilt_instance`, `resolved_dom_id`,
+    # `invoke_recovery_block`, `auto_param_overlay`, `component_tag_for`,
+    # `compute_retry_url`, `recovery_status`).
     module OOBIncludes
       private
 
-      # Render OOB-swapped components declared via `includes`.
-      # Filters by action_name when inclusions declare `on:`.
-      def render_oob_includes(component_class, primary_attrs, action_name: nil)
-        applicable = component_class.inclusions.select do |inc|
-          inc[:on].nil? || inc[:on] == action_name
+      # The companions riding an SSE frame. A push is nobody's action and no
+      # transfer's destination, so only unfiltered inclusions — "every
+      # response I render in" — qualify; `on:` and `when:` both name contexts
+      # a stream never enters.
+      def render_push_companions(component_class, primary_params, render_env:, slots:)
+        render_companions(applicable_inclusions(component_class, :push, nil).
+                            map { |inc| [inc, primary_params, render_env] }, slots)
+      end
+
+      # The inclusions of one component that fire in one context.
+      def applicable_inclusions(component_class, context, action_name)
+        component_class.inclusions.select { |inc| inclusion_applies?(inc, context, action_name) }
+      end
+
+      # The inclusions that name an action outright. A transfer's declaring
+      # component never renders, so its unfiltered inclusions ("every
+      # response I render in") stay silent — but `on:` doesn't narrow that
+      # default, it replaces it, and this action is the declarer's own.
+      def explicitly_named_inclusions(component_class, action_name)
+        component_class.inclusions.select { |inc| inc[:on]&.include?(action_name) }
+      end
+
+      # Render a planned set of companions: each entry pairs an inclusion
+      # with the params view its block reads and the environment its
+      # component builds in, because companions arriving from different
+      # branches of one response fork at different points.
+      def render_companions(plan, slots)
+        return "" if plan.empty?
+
+        winners = {}
+        plan.filter_map { |inclusion, view, env| companion_fragment(inclusion, view, env, slots, winners) }.
+          join.html_safe
+      end
+
+      # One companion's fragment, or nil when it yields none. `winners` records
+      # who took each slot, so a collision can name the declaration it lost to.
+      def companion_fragment(inclusion, view, env, slots, winners)
+        fragment = attempt_companion(inclusion, view, env, slots, winners)
+        winners[fragment.id] = inclusion if fragment
+        fragment
+      end
+
+      # Build a companion, unless its slot is already spoken for.
+      #
+      # The component abandons its own render the moment it finds the slot
+      # taken (Component#claim_dom_slot!) and throws the contested id back
+      # here, so a companion that was never going to land doesn't pay for the
+      # build. Companions differing in an id-bearing param claim different
+      # slots and both ride — which is what makes two of a kind, a left eye
+      # and a right eye, a legitimate pair rather than a clash.
+      def attempt_companion(inclusion, view, env, slots, winners)
+        overlays = companion_overlays(inclusion, view, env)
+        component = nil
+        # Where Component#claim_dom_slot!'s throw surfaces — one catch per
+        # companion, so standing down affects only this one. The block's
+        # trailing nil is the no-contest value; the component itself is
+        # captured by assignment so a successful build can't read as an id.
+        contested = catch(Weft::Context::SLOT_TAKEN) do
+          component = build_component_with_wire(inclusion[:component_class], companion_universe(env),
+                                                overlays: overlays, branch_bag: env[:branch_bag],
+                                                slots: slots)
+          nil
         end
-        return "" if applicable.empty?
+        return as_companion(component) unless contested
+
+        warn_companion_collision(contested, winners[contested], inclusion)
+        nil
+      rescue StandardError => e
+        # A delta block that raised leaves no overlays of its own; the
+        # companion falls back to what it inherited from the response.
+        recovered_companion(inclusion, env, overlays || env[:overlays] || {}, e)
+      end
+
+      # Each companion is an OOB-delivered child: it renders against the
+      # same request universe, branches the primary's bag (rich values
+      # included) exactly like a child built in the primary's own build,
+      # and layers its own block delta — blockless is an empty delta.
+      def companion_overlays(inclusion, view, env)
+        inherited = env[:overlays] || {}
+        return inherited unless inclusion[:block]
+
+        delta = Weft::DSL::Sandbox.run(view, &inclusion[:block])
+        delta.is_a?(Hash) ? inherited.merge(delta) : inherited
+      end
 
-        applicable.map { |inc| render_oob_component(inc, primary_attrs) }.join.html_safe
+      def companion_universe(env) = env.fetch(:universe) { filtered_params }
+
+      # A companion is a courtesy, not a contract: the response belongs to
+      # the primary, whose render, status and headers a failing bystander
+      # must never touch. The action has already committed its side effects
+      # by now, so failing the response would misstate what happened. The
+      # companion walks its OWN recovery chain into its OWN slot instead —
+      # component targets only, because a fragment riding inside a successful
+      # response cannot redirect, and a companion must never navigate on the
+      # primary's behalf.
+      #
+      # The recovery renders without the slot register: it inherits the failed
+      # companion's claim rather than competing with it, since a build that
+      # raised after claiming its slot still holds one.
+      def recovered_companion(inclusion, env, overlays, error)
+        klass = inclusion[:component_class]
+        log_companion_failure(inclusion, error)
+        entry = klass.component_recovery_for(error)
+        return nil unless entry
+
+        dom_id = failed_companion_dom_id(klass, env, overlays)
+        recovery_overlays = companion_recovery_overlays(klass, companion_state(klass, env, overlays),
+                                                        entry, error, dom_id)
+        component = build_component_with_wire(klass.resolve_recovery_target(entry),
+                                              companion_universe(env), overlays: recovery_overlays)
+        as_companion(claim_dom_id(component, dom_id))
+      rescue StandardError => e
+        Weft.logger.error("Companion recovery render failed: #{e.class}: #{e.message}")
+        nil
       end
 
-      def render_oob_component(inclusion, primary_attrs)
-        wire_attrs = inclusion[:block] ? inclusion[:block].call(primary_attrs) : filtered_params
-        resolved = resolver.resolve(inclusion[:component_class], wire_attrs)
-        component = build_component_with_attrs(inclusion[:component_class], resolved)
+      # Identity comes from exactly what the failed render was given — a delta
+      # that moves an id-bearing param moves the slot with it, and an error
+      # fragment addressed anywhere else lands on the wrong element.
+      def failed_companion_dom_id(klass, env, overlays)
+        resolved_dom_id(klass, unbuilt_instance(klass, companion_universe(env),
+                                                overlays: overlays, branch_bag: env[:branch_bag]))
+      end
+
+      # The state the failed build was given — its own wire schema over the
+      # request universe, the inclusion block's delta on top, branching
+      # whatever the primary composed. Rebuilt rather than read off the
+      # instance because a build that raised leaves none.
+      #
+      # Keys the class doesn't declare are laid on afterwards rather than
+      # resolved through the stack, which only visits declared keys — that's
+      # what keeps an inclusion block's ad-hoc delta readable in the recovery
+      # block, the same way it stays readable in the block that produced it.
+      def companion_state(klass, env, overlays)
+        Weft::Params::Assembly.call(klass, companion_universe(env),
+                                    overlays: overlays, branched_from: env[:branch_bag]).
+          overlay(overlays.except(*klass.declared_keys))
+      end
+
+      # The recovery target resolves its own schema from the request universe;
+      # the entry's block delta and the auto-injected values ride as overlays,
+      # exactly as on the primary's recovery path. No status is set — the
+      # response's status belongs to the primary.
+      def companion_recovery_overlays(klass, state, entry, error, dom_id)
+        component_ctx = { originating_id: dom_id,
+                          originating_tag: component_tag_for(klass),
+                          retry_url: compute_retry_url(klass, error_wire_params(klass)),
+                          status: recovery_status(error, entry) }
+        invoke_recovery_block(entry, state, error).merge(auto_param_overlay(error, component_ctx))
+      end
+
+      # The marker telling htmx to swap this fragment into the slot its id
+      # names, rather than into the primary's position. The id is already
+      # the component's own; only a recovery fragment has to be told.
+      def as_companion(component)
         component.set_attribute("hx-swap-oob", "true")
-        component.to_s
+        component
+      end
+
+      def log_companion_failure(inclusion, error)
+        Weft.logger.error(
+          "#{inclusion[:component_class].name} companion declared at " \
+          "#{inclusion[:source_location].join(':')} failed to render: #{error.class}: #{error.message}"
+        )
+      end
+
+      # Names what took the slot: another companion by its declaration site,
+      # or — when nothing declared it — the component the response is about.
+      def warn_companion_collision(dom_id, kept, dropped)
+        claimant = if kept
+                     "the companion declared at #{kept[:source_location].join(':')}"
+                   else
+                     "the component this response renders"
+                   end
+        Weft.logger.warn(
+          "#{dropped[:component_class].name} companion declared at " \
+          "#{dropped[:source_location].join(':')} was dropped: it resolves to DOM id " \
+          "#{dom_id.inspect}, already claimed by #{claimant}. An out-of-band swap is addressed " \
+          "by DOM id, so only one fragment can land there — give them different values for an " \
+          "identifying param, or drop one of the declarations."
+        )
+      end
+
+      def inclusion_applies?(inclusion, context, action_name)
+        return true if inclusion[:on].nil? && inclusion[:when].nil?
+
+        filtered_contexts(inclusion, action_name).include?(context)
+      end
+
+      # The contexts this filtered inclusion fires in — on: and when: union.
+      def filtered_contexts(inclusion, action_name)
+        contexts = []
+        contexts << :action if inclusion[:on]&.include?(action_name)
+        contexts << :transfer if inclusion[:when]&.include?(:transferred)
+        contexts
       end
     end
   end

data/lib/weft/router/streaming.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "weft/params/assembly"
+require "weft/resolver"
+
 module Weft
   class Router
     # SSE streaming slice of the Router. Handles `/component_path/<stream_suffix>`
@@ -8,9 +11,19 @@ module Weft
     # connection that emits formatted `event:`/`data:` frames on the
     # declared cadence.
     #
-    # Depends on Router internals: `build_component`, `render_oob_includes`,
-    # `pass`, `content_type`, `headers`, `stream`.
+    # Push failures route through the component's recovers chain (component
+    # targets only — see Errors#render_push_recovery) and count against an
+    # attempts budget; when it runs out, the CLOSE_EVENT frame tells the
+    # client to stop reconnecting and the connection closes.
+    #
+    # Depends on Router internals: `build_component`, `render_push_companions`,
+    # `render_push_recovery`, `pass`, `content_type`, `headers`, `stream`.
     module Streaming
+      # SSE event name that tells htmx-ext-sse to close the EventSource and
+      # stop reconnecting; every pushing component's wrapper names it in its
+      # sse-close attribute (Component#apply_push_attrs).
+      CLOSE_EVENT = "weft:close"
+
       private
 
       def handle_stream_request(path)
@@ -27,35 +40,88 @@ module Weft
       def stream_component(component_class)
         content_type "text/event-stream"
         headers "Cache-Control" => "no-cache"
-        interval = component_class.push_config[:every]
         klass = component_class
 
         stream :keep_open do |out|
-          # New subscribers get an immediate state snapshot, then the regular
-          # cadence — sleep only kicks in from the second frame onward. The flag
-          # flips before the push (not after a *successful* one) so a persistently
-          # failing push still throttles on the interval instead of busy-looping.
-          after_first = false
-          loop do
-            sleep interval if after_first
-            after_first = true
-            push_component_event(out, klass)
-          rescue Errno::EPIPE, IOError
-            break
-          rescue StandardError => e
-            Weft.logger.error("SSE push error for #{klass.name}: #{e.message}")
-          end
+          run_push_loop(out, klass)
+          # Both exits — dead client and exhausted attempts — are final, so
+          # close explicitly: under :keep_open, merely returning from this
+          # block does not end the response (observed on Puma as the block
+          # re-running and the countdown restarting on a live connection).
+          out.close
+        end
+      end
+
+      # New subscribers get an immediate state snapshot, then the regular
+      # cadence — sleep only kicks in from the second frame onward — unless
+      # the component declared `immediate: false`, which pre-arms the sleep.
+      # The flag flips before the push (not after a *successful* one) so a
+      # persistently failing push still throttles on the interval instead of
+      # busy-looping.
+      def run_push_loop(out, klass)
+        interval = klass.push_config[:every]
+        attempts = klass.push_config[:attempts] || Weft.configuration.push_attempts
+        after_first = !klass.push_config.fetch(:immediate, true)
+        failures = 0
+        loop do
+          sleep interval if after_first
+          after_first = true
+          push_component_event(out, klass)
+          failures = 0
+        rescue Errno::EPIPE, IOError
+          break
+        rescue StandardError => e
+          failures += 1
+          break unless push_failure_frames(out, klass, e, failures: failures, attempts: attempts)
         end
       end
 
       def push_component_event(out, component_class)
-        component = build_component(component_class)
-        html = component.content + render_oob_includes(component_class, component.attrs)
-        out << format_sse_event(component.weft_id, html)
+        slots = Set.new
+        component = build_component(component_class, slots: slots)
+        env = { universe: filtered_params, branch_bag: component.params }
+        html = component.content +
+               render_push_companions(component_class, component.params, render_env: env, slots: slots)
+        out << format_sse_event(component.weft_dom_id, html)
+      end
+
+      # A failure cycle's frames: the recovery fragment (when the chain yields
+      # a component target) and, once the attempts budget is spent, the close
+      # event that tells the client to stop reconnecting. Returns false when
+      # the stream is done — budget exhausted or the client vanished mid-write.
+      def push_failure_frames(out, component_class, error, failures:, attempts:)
+        Weft.logger.error("SSE push error for #{component_class.name}: #{error.message}")
+        remaining = attempts - failures
+        push_recovery_frame(out, component_class, error, remaining)
+        return true if remaining.positive?
+
+        Weft.logger.error(
+          "SSE stream for #{component_class.name} closed after #{attempts} consecutive failed pushes"
+        )
+        out << format_sse_event(CLOSE_EVENT, "")
+        false
+      rescue Errno::EPIPE, IOError
+        false
+      end
+
+      # Resolve, render, write. The event name is recomputed from the class +
+      # resolved wire params — the failed build left no instance to ask. Any
+      # render-path StandardError is logged and swallowed: the failure already
+      # counts against the budget, and the close logic must still run.
+      def push_recovery_frame(out, component_class, error, attempts_remaining)
+        resolved = Weft::Resolver.resolve(component_class, filtered_params)
+        state = Weft::Params::Assembly.for_request(component_class, filtered_params)
+        html = render_push_recovery(component_class, state, error, attempts_remaining: attempts_remaining)
+        out << format_sse_event(component_class.weft_dom_id_for(resolved), html) if html
+      rescue Errno::EPIPE, IOError
+        raise
+      rescue StandardError => e
+        Weft.logger.error("Push recovery render failed: #{e.class}: #{e.message}")
       end
 
       def format_sse_event(event_name, html)
         sse_data = html.each_line.map { |line| "data: #{line.chomp}" }.join("\n")
+        sse_data = "data: " if sse_data.empty? # dataless SSE events are never dispatched
         "event: #{event_name}\n#{sse_data}\n\n"
       end
     end

data/lib/weft/router.rb

@@ -63,11 +63,20 @@ module Weft
       end
     end
 
-    # In standalone mode (no downstream Rack app), Sinatra's not_found
-    # block fires when no route matched. Walk the Weft::Page recovers chain
-    # (default → Weft::Defaults::NotFoundPage). In middleware mode, `pass`
-    # falls through to the downstream app — this block doesn't fire.
-    not_found do
+    # Both error registrations are exception-keyed, never status-keyed: an
+    # error(404)/not_found handler fires on response *status* after every
+    # dispatch — custom recovery bodies return normally, no exception
+    # recorded — and would overwrite them with the default chain's output.
+    # Exception keys only fire when Sinatra itself raises.
+
+    # Routing miss in standalone mode: Sinatra raises Sinatra::NotFound
+    # after the final `pass` (middleware mode forwards downstream instead).
+    # Translate and walk the default Weft::Page chain. The exact-class key
+    # is load-bearing: Sinatra dispatches exact keys across all superclasses
+    # before walking the exception hierarchy, and Sinatra::Base registers
+    # its own development-mode `error NotFound` ("doesn't know this ditty")
+    # that must be shadowed here — StandardError below wouldn't be reached.
+    error Sinatra::NotFound do
       content_type :html
       handle_page_chain_failure(Weft::NotFound.new(request.path),
                                 originating_page_class: nil)
@@ -116,10 +125,6 @@ module Weft
       pass
     end
 
-    def resolver
-      @resolver ||= Resolver.new
-    end
-
     def filtered_params
       params.except("splat", "captures")
     end
@@ -127,24 +132,28 @@ module Weft
     # Render a component as HTML. inner: true returns children only
     # (for SSE innerHTML swap where the wrapper element must persist).
     def render_component(component_class, inner: false)
-      resolved_attrs = resolver.resolve(component_class, filtered_params)
-      component = build_component_with_attrs(component_class, resolved_attrs)
+      state = Weft::Params::Assembly.for_request(component_class, filtered_params)
+      component = build_component_with_wire(component_class, filtered_params, branch_bag: state)
       inner ? component.content : component.to_s
     rescue StandardError => e
-      render_error(component_class, resolved_attrs || {}, e)
+      render_error(component_class, state || Weft::Params.new({}), e)
     end
 
     # Build a component instance from the current request params.
-    def build_component(component_class)
-      resolved_attrs = resolver.resolve(component_class, filtered_params)
-      build_component_with_attrs(component_class, resolved_attrs)
+    def build_component(component_class, slots: nil)
+      build_component_with_wire(component_class, filtered_params, slots: slots)
     end
 
-    # Build a component instance from pre-resolved attributes.
-    def build_component_with_attrs(component_class, resolved_attrs)
+    # Build a component in a fresh context carrying the wire source; the
+    # component resolves its own declared params from it at construction.
+    # Arbre's builder attributes stay pure chrome — params travel their own
+    # channel. `overlays` carries request-scoped verb-block deltas;
+    # `branch_bag` lets the root inherit a primary's bag (OOB companions),
+    # and `slots` arbitrates which root gets to claim a DOM id.
+    def build_component_with_wire(component_class, wire_params, overlays: {}, branch_bag: nil, slots: nil)
       klass = component_class
-      attrs = resolved_attrs
-      context = Weft::Context.new({}, nil) { insert_tag(klass, **attrs) }
+      context = Weft::Context.new({}, nil, wire_params: wire_params, overlays: overlays,
+                                           branch_bag: branch_bag, slots: slots) { insert_tag(klass) }
       context.children.first
     end
 
@@ -155,14 +164,13 @@ module Weft
     # (B1 / C1 page-context); the gem-default catches StandardError.
     def render_page(page_class, route_params)
       merged_params = filtered_params.merge(route_params)
-      resolved_attrs = resolver.resolve(page_class, merged_params)
       klass = page_class
-      attrs = resolved_attrs
-      Weft::Context.new({}, nil) { insert_tag(klass, **attrs) }.to_s
+      Weft::Context.new({}, nil, wire_params: merged_params) { insert_tag(klass) }.to_s
     rescue StandardError => e
       handle_page_chain_failure(e,
                                 originating_page_class: page_class,
-                                originating_attrs: resolved_attrs || {})
+                                originating_params: Weft::Params::Assembly.for_request(page_class, merged_params),
+                                originating_wire: merged_params)
     end
 
     def htmx_request?
@@ -181,8 +189,8 @@ module Weft
       end
     end
 
-    def apply_trigger_header(component_class)
-      events = component_class.trigger_events
+    def apply_trigger_header(component_class, action_name)
+      events = component_class.trigger_events(action_name)
       return if events.empty?
 
       headers["HX-Trigger"] = events.join(", ")

data/lib/weft/version.rb

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

data/lib/weft.rb

@@ -7,9 +7,13 @@ require "active_support/core_ext/integer/time"
 require "active_support/core_ext/string/inflections"
 require "arbre"
 
+require "weft/autoloading"
 require "weft/error"
-require "weft/attributes"
-require "weft/dsl/attributes"
+require "weft/context/traversal"
+require "weft/params"
+require "weft/params/assembly"
+require "weft/dsl/params"
+require "weft/dsl/sandbox"
 require "weft/dsl/recoveries"
 require "weft/dsl/triggers"
 require "weft/dsl/inclusions"
@@ -47,30 +51,47 @@ module Weft
       @configuration ||= Configuration.new
     end
 
-    def registry
-      @registry ||= Registry.new
-    end
-
     def configure
       yield configuration
       apply_configuration
     end
 
+    # Set up Zeitwerk-managed autoloading (and, optionally, dev-mode reloading)
+    # for the application's own code. The imperative older sibling of
+    # {configure}: call it FIRST in your boot file — it builds the loader and
+    # eager-loads everything on the spot, so constants from these paths are
+    # resolvable by the time a configure block references them.
+    #
+    #   Weft.configure_autoloading(
+    #     paths: [File.join(APP_ROOT, "app", "components"),
+    #             File.join(APP_ROOT, "app", "pages")],
+    #     inflections: { "dropship_ui" => "DropshipUI" },
+    #     reload: ENV["APP_ENV"] == "development"
+    #   )
+    #
+    # With reload: true, code changes take effect without restarting: constants
+    # reload on every request, unloaded classes are evicted from the registry
+    # the moment Zeitwerk removes them, and class-valued configuration knobs
+    # rebind to their fresh definitions. Returns the Zeitwerk::Loader.
+    def configure_autoloading(paths:, inflections: {}, reload: false)
+      Autoloading.setup(paths: paths, inflections: inflections, reload: reload)
+    end
+
     # Convenience wrapper for Weft::Redirect.to.
-    def redirect(target, **attrs)
-      Redirect.to(target, **attrs)
+    def redirect(target, **params)
+      Redirect.to(target, **params)
     end
 
-    # Register a named interaction shorthand. Delegates to Weft::Shorthands.
+    # Register a named interaction preset. Delegates to Weft::Presets.
     #
-    #   Weft.register_shorthand :tooltip, trigger: :hover, swap: :fill
-    def register_shorthand(name, **defaults)
-      Shorthands.register(name, **defaults)
+    #   Weft.register_preset :tooltip, trigger: :hover, swap: :fill
+    def register_preset(name, **defaults)
+      Presets.register(name, **defaults)
     end
 
-    # Look up a registered shorthand by name. Delegates to Weft::Shorthands.
-    def shorthand(name)
-      Shorthands.lookup(name)
+    # Look up a registered preset by name. Delegates to Weft::Presets.
+    def preset(name)
+      Presets.lookup(name)
     end
 
     private
@@ -81,17 +102,9 @@ module Weft
     def apply_configuration
       logger.level = configuration.resolved_log_level
       Router.set(:logging, configuration.router_logging)
-      enable_auto_reload! if configuration.auto_reload && !@auto_reload_applied
       apply_static_assets!
     end
 
-    def enable_auto_reload!
-      require "sinatra/reloader"
-      Router.register(Sinatra::Reloader)
-      configuration.reload_paths.each { |path| Router.also_reload(path) }
-      @auto_reload_applied = true
-    end
-
     def apply_static_assets!
       @mounted_static_bundles ||= Set.new
       configuration.static_assets.each do |name, bundle|
@@ -120,5 +133,5 @@ module Weft
   end
 end
 
-require "weft/shorthands"
+require "weft/presets"
 require "weft/defaults"