weft 0.1.0

data/lib/weft/resolver.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Weft
+  # Maps request params (string keys/values) to component attribute hashes.
+  # Coerces types based on attribute defaults. Future home of the reification
+  # step (wire primitives → rich objects).
+  class Resolver
+    def resolve(component_class, params)
+      component_class.attributes.each_with_object({}) do |(name, meta), result|
+        raw = params[name.to_s] || params[name]
+        result[name] = raw.nil? ? meta[:default] : coerce(raw, meta[:default])
+      end
+    end
+
+    private
+
+    def coerce(value, default)
+      case default
+      when Integer then value.to_i
+      when Float then value.to_f
+      when true, false then coerce_boolean(value)
+      else value
+      end
+    end
+
+    def coerce_boolean(value) # rubocop:disable Naming/PredicateMethod
+      case value
+      when true, "true", "1" then true
+      else false
+      end
+    end
+  end
+end

data/lib/weft/router/actions.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Weft
+  class Router
+    # Action-dispatch slice of the Router. Resolves a request path to a
+    # `[Action, ComponentClass]` pair, invokes the action callable, and
+    # renders the result (either the component the action renders or a
+    # Weft::Redirect). Error-handling delegates to Weft::Router::Errors via
+    # `render_error`; the small `render_action_error` wrapper sets the
+    # destructive-swap header before delegating.
+    #
+    # Depends on Router internals: `resolver`, `filtered_params`,
+    # `handle_redirect`, `apply_trigger_header`, `render_oob_includes`,
+    # `render_error`, `headers`.
+    module Actions
+      private
+
+      # Parse path into component + action name, look up the action.
+      # Returns [action, component_class] or nil.
+      def resolve_action(path, http_method)
+        component_class, action_name = find_component_and_action(path)
+        return nil unless component_class&.routable?
+
+        key = [action_name, http_method]
+        action = component_class.actions[key]
+        action ? [action, component_class] : nil
+      end
+
+      # Walk the path from longest to shortest prefix to find a registered
+      # component. Any remaining path segment is the action name.
+      def find_component_and_action(path)
+        parts = path.split("/").reject(&:empty?)
+        (parts.length - 1).downto(0) do |i|
+          component_class = Weft.registry.lookup("/#{parts[0..i].join('/')}")
+          next unless component_class
+
+          action_name = i < parts.length - 1 ? parts[i + 1].to_sym : nil
+          return [component_class, action_name]
+        end
+        nil
+      end
+
+      def handle_action(action, component_class)
+        resolved_attrs = resolver.resolve(component_class, filtered_params)
+        attrs = Weft::Attributes.new(resolved_attrs)
+
+        returned = action.callable&.call(attrs)
+        return handle_redirect(returned) if returned.is_a?(Weft::Redirect)
+
+        render_action_response(action, component_class, resolved_attrs, returned)
+      rescue StandardError => e
+        render_action_error(action, component_class, resolved_attrs || {}, e)
+      end
+
+      # Successive resolution across the component-class boundary. The bag
+      # accumulates the declaring component's resolved attrs plus any hash the
+      # callable returned; the rendered class then runs its OWN resolution pass
+      # over the bag, so only its declared attributes reach the builder splat
+      # (closing the cross-class leak). The bag itself keeps every key so
+      # downstream OOB includes still see callable-returned attrs.
+      def render_action_response(action, component_class, resolved_attrs, returned)
+        bag = returned.is_a?(Hash) ? resolved_attrs.merge(returned) : resolved_attrs
+        apply_trigger_header(component_class)
+        html = action.renders.render(**resolver.resolve(action.renders, bag))
+        html + render_oob_includes(component_class, Weft::Attributes.new(bag), action_name: action.name)
+      end
+
+      # Error handling for actions. Adds HX-Reswap header when the action's
+      # swap strategy is destructive (e.g., :delete) so the error fragment
+      # renders visibly instead of the element being silently removed.
+      def render_action_error(action, component_class, resolved_attrs, error)
+        headers["HX-Reswap"] = "outerHTML" if action.swap == :delete
+        render_error(component_class, resolved_attrs, error)
+      end
+    end
+  end
+end

data/lib/weft/router/errors.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Weft
+  class Router
+    # Error-and-recovery slice of the Router. Walks recovers chains for
+    # component-context failures (A1–A5, C1–C3) and page-context failures
+    # (B1, B2, C1 page-context, C4), implements the htmx_errors = :redirect
+    # knob (D1, D2 no-op, D3 no-op), and houses the safety-net fallbacks
+    # for unmatched errors and recovery handlers that themselves raise.
+    #
+    # Also owns the schema-gated auto-injection of recovery attributes
+    # (:exception, :request_path, :status_code, :component_id, :retry_url).
+    #
+    # Depends on Router internals: `resolver`, `headers`, `status`,
+    # `request`, `redirect`, `htmx_request?`.
+    module Errors # rubocop:disable Metrics/ModuleLength
+      # Each entry: { redirect_safe: true } means the auto-injected attribute is
+      # included even when building a redirect URL. The component-context
+      # attributes (:exception, :component_id, :retry_url) are not redirect-safe
+      # — no element to preserve identity of, Exception objects aren't
+      # URL-encodable, and the destination Page rebuilds its own URL.
+      AUTO_INJECTED_ATTRS = [
+        { key: :exception,    redirect_safe: false },
+        { key: :request_path, redirect_safe: true },
+        { key: :status_code,  redirect_safe: true },
+        { key: :component_id, redirect_safe: false },
+        { key: :retry_url,    redirect_safe: false }
+      ].freeze
+      private_constant :AUTO_INJECTED_ATTRS
+
+      private
+
+      # Walk a Page-context recovers chain (B1, B2, C1 page-context, C4).
+      # `originating_page_class` is nil for routing misses (no specific Page);
+      # the gem-default chain on Weft::Page handles those.
+      def handle_page_chain_failure(error, originating_page_class:, originating_attrs: {})
+        root = originating_page_class || Weft::Page
+        entry = root.recovery_for(error)
+        return page_safety_net(error) unless entry
+
+        # D1: htmx + :redirect knob + gem-default fallthrough → HX-Redirect
+        # (D3 carves out routing misses).
+        return htmx_redirect_to_error_page(error) if d1_applies?(entry, error)
+
+        target = root.resolve_recovery_target(entry)
+        merged_attrs = recovery_merged_attrs(entry, originating_attrs, error)
+
+        if page_target?(target)
+          dispatch_page_recovery(target, merged_attrs, error)
+        else
+          render_recovery_component(target, merged_attrs, error, component_ctx: {})
+        end
+      end
+
+      def recovery_merged_attrs(entry, originating_attrs, error)
+        block_result = invoke_recovery_block(entry, originating_attrs, error)
+        originating_attrs.merge(block_result)
+      end
+
+      # Render or redirect for a Page recovery target. htmx requests get the
+      # Page's body content as a fragment; traditional requests get the full
+      # document. Status comes from the exception.
+      def dispatch_page_recovery(page_class, merged_attrs, error)
+        injected = inject_auto_attrs(page_class, merged_attrs, error, on_redirect: false)
+        render_attrs = resolver.resolve(page_class, injected)
+        status recovery_status(error)
+        htmx_request? ? page_body_html(page_class, render_attrs) : page_class.render(**render_attrs)
+      end
+
+      # Extract the rendered HTML inside a Page's <body>. For htmx fragment
+      # responses to full-document failures — the surrounding doc shell is
+      # already on the client; only the body content should swap.
+      def page_body_html(page_class, attrs)
+        klass = page_class
+        ctx = Weft::Context.new({}, nil) { insert_tag(klass, **attrs) }
+        page_instance = ctx.children.first
+        body_el = page_instance.children.find { |c| c.respond_to?(:tag_name) && c.tag_name == "body" }
+        body_el ? body_el.children.join : page_instance.to_s
+      end
+
+      # Last-resort hardcoded response when no recovers entry matched and
+      # the gem-default Page can't be rendered. Avoids unbounded recursion
+      # while still producing something sensible.
+      def page_safety_net(error)
+        status recovery_status(error)
+        message = "Internal error (#{error.class}: #{error.message})"
+        if htmx_request?
+          "<div style='padding:1rem;color:#991b1b'>#{message}</div>"
+        else
+          "<!DOCTYPE html>\n<html><head><title>Error</title></head>" \
+            "<body><div style='padding:1rem;color:#991b1b'>#{message}</div></body></html>"
+        end
+      end
+
+      def render_error(component_class, resolved_attrs, error)
+        entry = component_class.recovery_for(error)
+        if entry
+          # D1: htmx + :redirect knob + gem-default fallthrough → HX-Redirect.
+          return htmx_redirect_to_error_page(error) if d1_applies?(entry, error)
+
+          begin
+            return render_recovery(component_class, entry, resolved_attrs, error)
+          rescue StandardError => e
+            # The recovery handler itself raised — fall through to the hardcoded
+            # safety net rather than recursing. Surface the original error;
+            # the recovery error is dropped (it's almost always a coding bug).
+            Weft.logger.error("Recovery render failed: #{e.class}: #{e.message}")
+          end
+        end
+
+        status recovery_status(error)
+        render_generic_error(component_class, resolved_attrs, error)
+      end
+
+      # D1 applies when: the htmx_errors knob is :redirect, the request is htmx,
+      # the matched entry came from a gem-default (Symbol with:), and the error
+      # is not a routing miss (D3 — Weft::NotFound short-circuits the knob).
+      def d1_applies?(entry, error)
+        Weft.configuration.htmx_errors == :redirect &&
+          htmx_request? &&
+          entry[:with].is_a?(Symbol) &&
+          !error.is_a?(Weft::NotFound)
+      end
+
+      def htmx_redirect_to_error_page(error)
+        target = Weft.configuration.error_page
+        attrs = inject_auto_attrs(target, {}, error, on_redirect: true)
+        headers["HX-Redirect"] = target.redirect_url(attrs)
+        status 204
+        ""
+      end
+
+      # Execute a matched recovery entry: invoke block, merge attrs, dispatch
+      # to either a Page-redirect (HX-Redirect / 302) or a fragment render
+      # depending on the target's type.
+      def render_recovery(component_class, entry, resolved_attrs, error)
+        block_result = invoke_recovery_block(entry, resolved_attrs, error)
+        merged_attrs = resolved_attrs.merge(block_result)
+        target = component_class.resolve_recovery_target(entry)
+        component_ctx = {
+          originating_id: component_class.weft_id_for(resolved_attrs),
+          retry_url: compute_retry_url(component_class, resolved_attrs)
+        }
+
+        if page_target?(target)
+          redirect_to_recovery_page(target, merged_attrs, error)
+        else
+          render_recovery_component(target, merged_attrs, error, component_ctx: component_ctx)
+        end
+      end
+
+      # GET URL to render the failing component fresh: its resolved_component_path
+      # plus the resolved attrs as query string. For action endpoints this gives
+      # the underlying component's view (not the action URL).
+      def compute_retry_url(component_class, resolved_attrs)
+        url = component_class.resolved_component_path
+        params = resolved_attrs.compact
+        params.empty? ? url : "#{url}?#{URI.encode_www_form(params)}"
+      end
+
+      def invoke_recovery_block(entry, resolved_attrs, error)
+        return {} unless entry[:block]
+
+        result = entry[:block].call(Weft::Attributes.new(resolved_attrs), error)
+        result.is_a?(Hash) ? result : {}
+      end
+
+      def page_target?(target)
+        target.is_a?(Class) && defined?(Weft::Page) && target <= Weft::Page
+      end
+
+      def redirect_to_recovery_page(target, merged_attrs, error)
+        attrs_for_url = inject_auto_attrs(target, merged_attrs, error, on_redirect: true)
+        url = target.redirect_url(attrs_for_url)
+
+        if request.env["HTTP_HX_REQUEST"]
+          headers["HX-Redirect"] = url
+          status 204
+          ""
+        else
+          redirect url, 302
+        end
+      end
+
+      def render_recovery_component(target, merged_attrs, error, component_ctx:)
+        injected = inject_auto_attrs(target, merged_attrs, error,
+                                     on_redirect: false, component_ctx: component_ctx)
+        status recovery_status(error)
+        # Resolve schema-exact for the target so the failing component's attrs
+        # (which may share no schema with the target) can't leak as HTML
+        # attributes. Declared auto-injected attrs survive: their defaults are
+        # nil, and Resolver#coerce passes non-nil values through unchanged.
+        target.render(**resolver.resolve(target, injected))
+      end
+
+      # Schema-gated auto-injection of recovery attributes. A recovers target
+      # opts in to receiving each value by declaring `attribute :<key>` — the
+      # Router only injects keys the target's schema knows about (and only if
+      # the value is non-nil).
+      def inject_auto_attrs(target, attrs, error, on_redirect:, component_ctx: {})
+        schema = target.respond_to?(:attributes) ? target.attributes : {}
+        values = auto_attr_values(error, component_ctx)
+        injected = attrs.dup
+        AUTO_INJECTED_ATTRS.each do |meta|
+          next if on_redirect && !meta[:redirect_safe]
+          next unless schema.key?(meta[:key])
+
+          value = values[meta[:key]]
+          injected[meta[:key]] = value unless value.nil?
+        end
+        injected
+      end
+
+      def auto_attr_values(error, component_ctx)
+        {
+          exception: error,
+          request_path: request.path,
+          status_code: recovery_status(error),
+          component_id: component_ctx[:originating_id],
+          retry_url: component_ctx[:retry_url]
+        }
+      end
+
+      def recovery_status(error)
+        error.is_a?(Weft::HTTPError) ? error.status : 500
+      end
+
+      def render_generic_error(component_class, resolved_attrs, error)
+        component_name = component_class.name || "Component"
+        retry_url = compute_retry_url(component_class, resolved_attrs)
+
+        Weft::Context.new({}, nil) do
+          error_style = "padding:1rem; border:1px solid #fca5a5; border-radius:6px; " \
+                        "background:#fef2f2; color:#991b1b; font-size:0.875rem"
+          div(class: "weft-error", style: error_style) do
+            div(style: "font-weight:600; margin-bottom:0.5rem") { text_node "#{component_name} error" }
+            div(style: "margin-bottom:0.5rem; font-family:monospace; font-size:0.8rem") do
+              text_node "#{error.class}: #{error.message}"
+            end
+            button "Retry", class: "btn btn-sm btn-outline-danger", retry: retry_url
+          end
+        end.to_s
+      end
+    end
+  end
+end

data/lib/weft/router/oob_includes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # Depends on Router internals: `resolver`, `filtered_params`,
+    # `build_component_with_attrs`.
+    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
+        end
+        return "" if applicable.empty?
+
+        applicable.map { |inc| render_oob_component(inc, primary_attrs) }.join.html_safe
+      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)
+        component.set_attribute("hx-swap-oob", "true")
+        component.to_s
+      end
+    end
+  end
+end

data/lib/weft/router/streaming.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Weft
+  class Router
+    # SSE streaming slice of the Router. Handles `/component_path/<stream_suffix>`
+    # requests (stream_suffix defaults to "_stream") for components declaring
+    # `pushes every:`, opening a long-lived
+    # 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`.
+    module Streaming
+      private
+
+      def handle_stream_request(path)
+        component_path = path.delete_suffix("/#{Weft.configuration.stream_suffix}")
+        component_class = Weft.registry.lookup(component_path)
+
+        if component_class&.push_config&.key?(:every)
+          stream_component(component_class)
+        else
+          pass
+        end
+      end
+
+      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
+        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)
+      end
+
+      def format_sse_event(event_name, html)
+        sse_data = html.each_line.map { |line| "data: #{line.chomp}" }.join("\n")
+        "event: #{event_name}\n#{sse_data}\n\n"
+      end
+    end
+  end
+end

data/lib/weft/router.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "sinatra/base"
+require "uri"
+
+module Weft
+  # Rack middleware that auto-generates routes for Weft::Components.
+  #
+  # GET routes render components as HTML fragments (partial rendering).
+  # POST/PUT/DELETE/PATCH routes invoke component actions declared via
+  # `performs` or `transfers`, then render the action's target component.
+  #
+  # Usage:
+  #   # Middleware (coexists with any Rack app)
+  #   use Weft::Router
+  #
+  #   # Standalone
+  #   run Weft::Router
+  class Router < Sinatra::Base
+    # Behavior slices live under Weft::Router::*. Required inside the class
+    # body so each slice's reopened `class Router` finds the Sinatra::Base
+    # superclass already declared.
+    require_relative "router/streaming"
+    require_relative "router/oob_includes"
+    require_relative "router/actions"
+    require_relative "router/errors"
+    include Streaming
+    include OOBIncludes
+    include Actions
+    include Errors
+
+    set :logging, false
+    set :show_exceptions, false
+    # In Sinatra's :test environment, raise_errors defaults to true (so test
+    # frameworks see exceptions). Weft's own error block must run instead —
+    # uncaught route exceptions feed the Page recovers chain.
+    set :raise_errors, false
+    set :dump_errors, false
+
+    # GET: render a component, invoke a nameless GET action, or stream SSE
+    get "/*" do
+      path = "/#{params['splat'].first}"
+
+      if stream_request?(path)
+        handle_stream_request(path)
+      else
+        handle_get_request(path)
+      end
+    end
+
+    # POST/PUT/DELETE/PATCH: invoke named or nameless actions
+    %i[post put delete patch].each do |http_method|
+      send(http_method, "/*") do
+        path = "/#{params['splat'].first}"
+        result = resolve_action(path, http_method)
+
+        if result
+          content_type :html
+          handle_action(*result)
+        else
+          pass
+        end
+      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
+      content_type :html
+      handle_page_chain_failure(Weft::NotFound.new(request.path),
+                                originating_page_class: nil)
+    end
+
+    # Catch any error escaping a route handler and walk the Weft::Page
+    # chain. Covers full-document Page render failures that escape
+    # render_page's own rescue (and any direct user-raised errors).
+    error StandardError do
+      e = env["sinatra.error"]
+      content_type :html
+      handle_page_chain_failure(e, originating_page_class: nil)
+    end
+
+    private
+
+    # A GET targets a component's SSE stream endpoint when its path ends with
+    # "/<stream_suffix>" (default "/_stream"). See Streaming slice.
+    def stream_request?(path)
+      path.end_with?("/#{Weft.configuration.stream_suffix}")
+    end
+
+    def handle_get_request(path)
+      # Action resolution handles both named (/component/action_name)
+      # and nameless (/component with actions[[nil, :get]]) GET actions.
+      result = resolve_action(path, :get)
+      if result
+        content_type :html
+        return handle_action(*result)
+      end
+
+      # No action matched — render the component directly if it exists and is routable.
+      component_class = Weft.registry.lookup(path)
+      if component_class&.routable?
+        content_type :html
+        return render_component(component_class)
+      end
+
+      # Try page routes (pattern match against registered page paths).
+      page_match = Weft.registry.match_page(path)
+      if page_match
+        content_type :html
+        return render_page(*page_match)
+      end
+
+      pass
+    end
+
+    def resolver
+      @resolver ||= Resolver.new
+    end
+
+    def filtered_params
+      params.except("splat", "captures")
+    end
+
+    # 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)
+      inner ? component.content : component.to_s
+    rescue StandardError => e
+      render_error(component_class, resolved_attrs || {}, 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)
+    end
+
+    # Build a component instance from pre-resolved attributes.
+    def build_component_with_attrs(component_class, resolved_attrs)
+      klass = component_class
+      attrs = resolved_attrs
+      context = Weft::Context.new({}, nil) { insert_tag(klass, **attrs) }
+      context.children.first
+    end
+
+    # Render a Page as a full HTML document. Query/body params and
+    # path-extracted params are merged; path params override on key
+    # conflicts, matching Sinatra's precedence convention.
+    # Page render failures walk the failing Page's recovers chain
+    # (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
+    rescue StandardError => e
+      handle_page_chain_failure(e,
+                                originating_page_class: page_class,
+                                originating_attrs: resolved_attrs || {})
+    end
+
+    def htmx_request?
+      request.env["HTTP_HX_REQUEST"] == "true"
+    end
+
+    # Handle a Weft::Redirect return from a callable or recovers block.
+    # htmx requests get HX-Redirect header; traditional requests get 302.
+    def handle_redirect(redir)
+      if request.env["HTTP_HX_REQUEST"]
+        headers["HX-Redirect"] = redir.url
+        status 204
+        ""
+      else
+        redirect redir.url
+      end
+    end
+
+    def apply_trigger_header(component_class)
+      events = component_class.trigger_events
+      return if events.empty?
+
+      headers["HX-Trigger"] = events.join(", ")
+    end
+  end
+end