lively 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ffe05b0ea4fbdde40a40b59e85277e9a87bd2ca0cd57350f720a7c4dd1f8445
-  data.tar.gz: d53aedcf48bfd4eab8f1017b214ab2ee3b2cb424ca676c7f495cc7d68dcd5e11
+  metadata.gz: 15152c7881657de7dd4fa32fc683e7ebe4a03d4bc0f4607d012d4c759893f5c9
+  data.tar.gz: 8920462124226fb11f45ae5bfcaebcbe8b31c498ac5747f37e5519824559cda5
 SHA512:
-  metadata.gz: 827c7ea471e0e9075422332e679b7ff05070d040f9e49dc2ce3e69dd23c852b70bd25fed8a6d0c53485391d2e0b906883fae64f6f97a7ad3bc9c30d845b9cc82
-  data.tar.gz: a2bd006da9cce6a5303c3e7aa78bf43d4e895c3fff1f7086b7d071872be1742349d7b6549d5e9b853b7e1e72141f0f4ee039de523f2f2de8bc72198a619eda6d
+  metadata.gz: 3aecbe697281e791829fa34fe243d872c024603bf549d192911c7acde336e9e50fc3460fbdef7935c7aeb9fa533de7bbcda9c500bff141e78bf7acbfb22beb48
+  data.tar.gz: fe65914d211265582cfb6e3d5ad1d84bf61f752900dcc758b1ac4be71502a98c7d8f7d29675bc14761f4e2297c145e13189477685a1553c2ac8d2196be98fc94

data/context/getting-started.md

@@ -82,7 +82,7 @@ class GameState
 end
 
 class GameView < Live::View
-	def initialize(id = self.class.unique_id, data = {}, game_state: nil)
+	def initialize(id, data, game_state: nil)
 		super(id, data)
 		@game_state = game_state
 	end
@@ -117,29 +117,24 @@ class Application < Lively::Application
 	end
 	
 	def configure_routes(router)
-		super
-		
 		router.get("/") do
-			render(DisplayView.new(**state))
+			body = resolver.root(DisplayView)
+			Lively::Pages::Index.new(title: title, body: body).call
 		end
 		
-		router.get("/control") do |_request, parameters|
-			render(ControlView.new(**state, mode: parameters["mode"]))
+		router.get("/control") do
+			body = resolver.root(ControlView)
+			Lively::Pages::Index.new(title: title, body: body).call
 		end
 	end
-	
-	private
-	
-	def render(body)
-		page = Lively::Pages::Index.new(title: "My App", body: body)
-		Protocol::HTTP::Response[200, [], [page.call]]
-	end
 end
 ```
 
-Routes match exact paths and may accept one or more HTTP methods. Query parameters are decoded using `protocol-url` and passed to the handler as its second argument. Routes without an explicit method accept every method.
+`allowed_views` defines the view classes the shared resolver may construct. Each matched route constructs its root view using the shared resolver, wraps that concrete body in a page, and invokes `Page#call` to produce the response. This keeps view construction lazy without making the page body itself callable. Lively installs its `/live` WebSocket route independently, so overriding `configure_routes` does not remove it.
+
+Routes match exact paths and may accept one or more HTTP methods. Handlers receive the original request and can parse query parameters when needed. Routes without an explicit method accept every method.
 
-Requests which do not match a route are passed to the application's delegate. An application using client-side history routing can instead override `#handle` to return its index page for unmatched paths.
+Requests which do not match a route are passed to the application's delegate. Applications that need custom fallback behavior can supply an appropriate delegate when they are constructed.
 
 ## Live Reloading
 

data/lib/lively/application.rb

@@ -23,7 +23,7 @@ module Lively
 	#
 	# Use {.[]} to create a simple application class for a single view, optionally
 	# with shared state. For more complex applications, subclass and override
-	# {#allowed_views}, {#state}, and {#configure_routes}.
+	# {#allowed_views}, {#state}, and {#configure_routes} to route requests to pages.
 	class Application < Protocol::HTTP::Middleware
 		VIEWS = [HelloWorld].freeze
 		STATE = {}.freeze
@@ -31,7 +31,7 @@ module Lively
 		# Create a new application class configured for a specific Live view tag,
 		# optionally with shared state that is passed to all views.
 		#
-		# @parameter tag [Class] The Live view class to use as the application body.
+		# @parameter tag [Class] The Live view class to render at the root route.
 		# @parameter state [Hash] Shared state to pass to all views as keyword arguments.
 		# @returns [Class] A new application class configured for the specified tag.
 		def self.[](*tags, **state)
@@ -43,15 +43,6 @@ module Lively
 			return klass
 		end
 		
-		# Initialize a new Lively application.
-		# @parameter delegate [Protocol::HTTP::Middleware] The next middleware in the chain.
-		def initialize(delegate)
-			super(delegate)
-		end
-		
-		# @attribute [Protocol::HTTP::Middleware] The delegate middleware for request handling.
-		attr :delegate
-		
 		# The shared state for this application, passed to all views via the resolver.
 		# Override this in subclasses to provide custom state.
 		# @returns [Hash] Key-value pairs passed as keyword arguments to view constructors.
@@ -87,43 +78,23 @@ module Lively
 			self.class.name
 		end
 		
-		# Create the body content for this application.
-		# @returns [Live::View] A new view instance.
-		def body
-			self.allowed_views.first.new(**self.state)
-		end
-		
-		# Create the index page for this application.
-		# @returns [Pages::Index] A new index page instance.
-		def index
-			Pages::Index.new(title: self.title, body: self.body)
-		end
-		
-		# Handle a standard HTTP request which did not match a configured route.
-		# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
-		# @returns [Protocol::HTTP::Response] The delegate response.
-		def handle(request)
-			return delegate.call(request)
-		end
-		
-		# Add the standard application routes to the given router.
-		# Override this method and call `super` to add application-specific routes.
-		# @parameter router [Router] The router to configure.
+		# Add application routes to the given router.
+		# Override this method to map paths to views or other handlers.
+		# @parameter router [Router::Builder] The router to configure.
 		def configure_routes(router)
 			router.get("/") do
-				Protocol::HTTP::Response[200, [], [self.index.call]]
-			end
-			
-			router.route("/live") do |request|
-				Async::WebSocket::Adapters::HTTP.open(request, &self.method(:live)) || Protocol::HTTP::Response[400]
+				view_class = self.allowed_views.first
+				body = self.resolver.root(view_class) if view_class
+				Pages::Index.new(title: self.title, body: body).call
 			end
 		end
 		
-		# The router for this application. Unmatched requests are handled separately
-		# by {#handle}.
+		# The router for this application. Unmatched requests are passed to the
+		# application delegate.
 		# @returns [Router] The configured router.
 		def router
-			@router ||= Router.new.tap do |router|
+			@router ||= Router.build(delegate) do |router|
+				configure_system_routes(router)
 				configure_routes(router)
 			end
 		end
@@ -132,7 +103,17 @@ module Lively
 		# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
 		# @returns [Protocol::HTTP::Response] The appropriate response for the request.
 		def call(request)
-			return router.call(request) || handle(request)
+			return router.call(request)
+		end
+		
+		private
+		
+		# Add framework-owned routes to the given router.
+		# @parameter router [Router::Builder] The router to configure.
+		def configure_system_routes(router)
+			router.route("/live") do |request|
+				Async::WebSocket::Adapters::HTTP.open(request, &self.method(:live)) || Protocol::HTTP::Response[400]
+			end
 		end
 	end
 end

data/lib/lively/hello_world.rb

@@ -64,11 +64,7 @@ module Lively
 				builder.text(<<~TEXT)
 					#!/usr/bin/env lively
 					
-					class Application < Lively::Application
-						def body
-							Lively::HelloWorld.new
-						end
-					end
+					Application = Lively::Application[Lively::HelloWorld]
 				TEXT
 			end
 			

data/lib/lively/page.rb

@@ -4,6 +4,7 @@
 # Copyright, 2026, by Samuel Williams.
 
 require "json"
+require "protocol/http/response"
 require "xrb/markup"
 require "xrb/tag"
 require "xrb/template"
@@ -11,15 +12,15 @@ require "xrb/template"
 module Lively
 	# Represents a complete HTML document.
 	#
-	# A page combines application content with the stylesheets, import map,
-	# JavaScript modules, and body attributes required to present it. Applications
-	# can use this class directly or subclass it to provide shared defaults.
+	# A page combines a renderable body with the stylesheets, import map,
+	# JavaScript modules, and body attributes required to present it.
+	# Pages render complete HTTP responses after a route has selected their content.
 	class Page
 		TEMPLATE = XRB::Template.load_file(File.expand_path("page.xrb", __dir__))
 		
 		# Initialize a new page.
 		# @parameter title [String] The document title.
-		# @parameter body [Object | Nil] The document body. The result of `to_html` is interpolated into the template.
+		# @parameter body [Object | Nil] The renderable document body.
 		# @parameter icon [String | Nil] The favicon URL.
 		# @parameter stylesheets [Array(String | Hash)] Stylesheets in document order. Hash entries specify link attributes.
 		# @parameter imports [Hash] JavaScript import map entries.
@@ -39,7 +40,7 @@ module Lively
 		# @attribute [String] The document title.
 		attr :title
 		
-		# @attribute [Object | Nil] The document body.
+		# @attribute [Object | Nil] The renderable document body.
 		attr :body
 		
 		# @attribute [String | Nil] The favicon URL.
@@ -79,12 +80,6 @@ module Lively
 			XRB::Tag.closed("link", {rel: "stylesheet", type: "text/css"}.merge(attributes))
 		end
 		
-		# The rendered body content.
-		# @returns [Object]
-		def body_content
-			@body&.to_html || "No body specified!"
-		end
-		
 		# The serialized JavaScript import map.
 		# @returns [XRB::MarkupString]
 		def import_map
@@ -94,10 +89,16 @@ module Lively
 			XRB::MarkupString.raw(json)
 		end
 		
-		# Render this page to a string.
+		# Render this page to an HTML string.
 		# @returns [String]
-		def call
+		def to_html
 			@template.to_string(self)
 		end
+		
+		# Render this page as an HTTP response.
+		# @returns [Protocol::HTTP::Response] A successful HTML response.
+		def call
+			Protocol::HTTP::Response[200, {"content-type" => "text/html; charset=utf-8"}, [to_html]]
+		end
 	end
 end

data/lib/lively/page.xrb

@@ -25,6 +25,6 @@
 	</head>
 	
 	#{self.body_tag}
-		#{self.body_content}
+		#{self.body&.to_html}
 	</body>
 </html>

data/lib/lively/pages/index.rb

@@ -29,7 +29,7 @@ module Lively
 			
 			# Initialize a new index page.
 			# @parameter title [String] The title of the page.
-			# @parameter body [Object] The body content of the page.
+			# @parameter body [Object | Nil] The renderable document body.
 			def initialize(title: "Lively", body: nil)
 				super(
 					title: title,
@@ -37,7 +37,7 @@ module Lively
 					icon: ICON,
 					stylesheets: STYLESHEETS,
 					imports: IMPORTS,
-					modules: MODULES,
+					modules: MODULES
 				)
 			end
 		end

data/lib/lively/resolver.rb

@@ -21,14 +21,11 @@ module Lively
 		# @attribute [Hash] The shared state passed to view constructors.
 		attr :state
 		
-		# Resolve a client-side element to a server-side instance with shared state.
-		# @parameter id [String] The unique element identifier.
-		# @parameter data [Hash] The element data attributes.
-		# @returns [Live::Element | Nil] The resolved element, or `nil`.
-		def call(id, data)
-			if klass = @allowed[data[:class]]
-				return klass.new(id, data, **@state)
-			end
+		private
+		
+		# Construct a view with shared application state.
+		def make(view_class, id, data, **options)
+			super(view_class, id, data, **@state, **options)
 		end
 	end
 end

data/lib/lively/router.rb

@@ -3,136 +3,155 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "protocol/http"
+require "protocol/http/middleware"
 require "protocol/url"
 
 module Lively
 	# Dispatches HTTP requests to handlers using exact path and method matches.
 	#
 	# Request targets are parsed with {Protocol::URL::Reference}. Handlers receive
-	# the original request and the decoded query parameters.
-	class Router
-		EMPTY_PARAMETERS = {}.freeze
+	# the original request.
+	class Router < Protocol::HTTP::Middleware
 		ANY_METHOD = nil
-		private_constant :EMPTY_PARAMETERS, :ANY_METHOD
+		private_constant :ANY_METHOD
 		
-		# Initialize a router.
-		# @yields {|router| ...} The router to configure.
-		def initialize
-			@routes = {}
+		# Builds an immutable route table.
+		class Builder
+			# Initialize a route builder.
+			def initialize
+				@routes = {}
+			end
 			
-			yield self if block_given?
-		end
-		
-		# Add a route.
-		#
-		# When `methods` is omitted, the handler accepts every HTTP method. Otherwise,
-		# it may be a single method or an array of methods.
-		#
-		# @parameter path [String] The absolute path to match.
-		# @parameter methods [String | Symbol | Array(String | Symbol) | Nil] The accepted HTTP methods.
-		# @yields {|request, parameters| ...} The route handler.
-		# 	@parameter request [Protocol::HTTP::Request] The original request.
-		# 	@parameter parameters [Hash] The decoded query parameters.
-		# @returns [Router] The router.
-		def route(path, methods: nil, &handler)
-			raise ArgumentError, "A route handler is required!" unless handler
+			# A frozen snapshot of the configured routes.
+			# @returns [Hash] The route table.
+			def routes
+				@routes.transform_values do |handlers|
+					handlers.dup.freeze
+				end.freeze
+			end
+			
+			# Add a route.
+			#
+			# When `methods` is omitted, the handler accepts every HTTP method. Otherwise,
+			# it may be a single method or an array of methods.
+			#
+			# @parameter path [String] The absolute path to match.
+			# @parameter handler [Interface(:call) | Nil] A callable route handler.
+			# @parameter methods [String | Symbol | Array(String | Symbol) | Nil] The accepted HTTP methods.
+			# @yields {|request| ...} The route handler.
+			# 	@parameter request [Protocol::HTTP::Request] The original request.
+			# @returns [Builder] The builder.
+			def route(path, handler = nil, methods: nil, &block)
+				raise ArgumentError, "Provide a route handler or block, not both!" if handler && block
+				handler ||= block
+				raise ArgumentError, "A route handler is required!" unless handler
+				
+				path = route_path(path)
+				methods = route_methods(methods)
+				handlers = (@routes[path] ||= {})
+				
+				methods.each do |method|
+					if handlers.key?(method)
+						raise ArgumentError, "Route already defined for #{method || "any method"} #{path}!"
+					end
+					
+					handlers[method] = handler
+				end
+				
+				return self
+			end
 			
-			path = route_path(path)
-			methods = route_methods(methods)
-			handlers = (@routes[path] ||= {})
+			Protocol::HTTP::Methods.each do |name, method|
+				# Add a route for this HTTP method.
+				# @parameter path [String] The absolute path to match.
+				# @yields {|request| ...} The route handler.
+				# @returns [Builder] The builder.
+				define_method(name) do |path, handler = nil, &block|
+					route(path, handler, methods: method, &block)
+				end
+			end
+			
+			private
 			
-			methods.each do |method|
-				if handlers.key?(method)
-					raise ArgumentError, "Route already defined for #{method || "any method"} #{path}!"
+			def route_path(path)
+				url = Protocol::URL[path]
+				
+				unless url && !url.is_a?(Protocol::URL::Absolute)
+					raise ArgumentError, "Route must be an absolute path: #{path.inspect}!"
+				end
+				
+				reference = Protocol::URL::Reference[url]
+				
+				unless reference.path.absolute?
+					raise ArgumentError, "Route must be an absolute path: #{path.inspect}!"
+				end
+				
+				if reference.query? || reference.fragment?
+					raise ArgumentError, "Route path cannot include a query or fragment: #{path.inspect}!"
 				end
 				
-				handlers[method] = handler
+				return reference.path.freeze
 			end
 			
-			return self
+			def route_methods(methods)
+				return [ANY_METHOD] unless methods
+				
+				methods = Array(methods)
+				raise ArgumentError, "At least one HTTP method is required!" if methods.empty?
+				
+				return methods.map do |method|
+					raise ArgumentError, "HTTP method cannot be nil!" unless method
+					
+					method.to_s.upcase
+				end.uniq
+			end
 		end
 		
-		Protocol::HTTP::Methods.each do |name, method|
-			# Add a route for this HTTP method.
-			# @parameter path [String] The absolute path to match.
-			# @yields {|request, parameters| ...} The route handler.
-			# @returns [Router] The router.
-			define_method(name) do |path, &handler|
-				route(path, methods: method, &handler)
-			end
+		# Build and configure a frozen router.
+		# @parameter delegate [Protocol::HTTP::Middleware] The middleware for unmatched requests.
+		# @yields {|builder| ...} Configures the routes.
+		# 	@parameter builder [Builder] The route builder.
+		# @returns [Router] The configured router.
+		def self.build(delegate = Protocol::HTTP::Middleware::NotFound)
+			builder = Builder.new
+			yield builder
+			
+			return new(delegate, builder.routes).freeze
+		end
+		
+		# Initialize a router.
+		# @parameter delegate [Protocol::HTTP::Middleware] The middleware for unmatched requests.
+		# @parameter routes [Hash] The frozen route table.
+		def initialize(delegate, routes)
+			super(delegate)
+			@routes = routes
 		end
 		
 		# Dispatch a request to a matching route.
 		# @parameter request [Protocol::HTTP::Request] The request to dispatch.
-		# @returns [Protocol::HTTP::Response | Nil] The handler or error response, or `nil` when no path matches.
+		# @returns [Protocol::HTTP::Response] The handler, error, or delegate response.
 		def call(request)
 			reference = parse_reference(request.path)
 			return Protocol::HTTP::Response[400] unless reference
 			
-			unless handlers = @routes[reference.path]
-				return nil
-			end
+			return super unless handlers = @routes[reference.path]
 			
 			unless handler = handlers[request.method] || handlers[ANY_METHOD]
 				allowed_methods = handlers.keys.compact.sort.join(", ")
 				return Protocol::HTTP::Response[405, [["allow", allowed_methods]]]
 			end
 			
-			parameters = parse_query(reference)
-			return Protocol::HTTP::Response[400] unless parameters
-			
-			return handler.call(request, parameters)
+			return handler.call(request)
 		end
 		
 		private
 		
-		def route_path(path)
-			url = Protocol::URL[path]
-			
-			unless url && !url.is_a?(Protocol::URL::Absolute)
-				raise ArgumentError, "Route must be an absolute path: #{path.inspect}!"
-			end
-			
-			reference = Protocol::URL::Reference[url]
-			
-			unless reference.path.absolute?
-				raise ArgumentError, "Route must be an absolute path: #{path.inspect}!"
-			end
-			
-			if reference.query? || reference.fragment?
-				raise ArgumentError, "Route path cannot include a query or fragment: #{path.inspect}!"
-			end
-			
-			return reference.path.freeze
-		end
-		
-		def route_methods(methods)
-			return [ANY_METHOD] unless methods
-			
-			methods = Array(methods)
-			raise ArgumentError, "At least one HTTP method is required!" if methods.empty?
-			
-			return methods.map do |method|
-				raise ArgumentError, "HTTP method cannot be nil!" unless method
-				
-				method.to_s.upcase
-			end.uniq
-		end
-		
 		def parse_reference(path)
 			reference = Protocol::URL::Reference[path]
 			return if reference&.fragment?
 			
 			return reference
-		rescue ArgumentError
-			nil
 		end
 		
-		def parse_query(reference)
-			reference.parse_query! || EMPTY_PARAMETERS
-		rescue ArgumentError
-			nil
-		end
 	end
 end

data/lib/lively/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Lively
-	VERSION = "0.20.0"
+	VERSION = "0.22.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lively
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -114,28 +114,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
 - !ruby/object:Gem::Dependency
   name: protocol-url
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
 - !ruby/object:Gem::Dependency
   name: xrb
   requirement: !ruby/object:Gem::Requirement