lively 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a673a59bd33ad2da10a565846eb708b9dc2390745e22a468763758ce8f6d3296
-  data.tar.gz: 4366967a33057ad99f803015799f63574f1fd2fc393053cd37f30dacd5881232
+  metadata.gz: d4f90097ca71e02dffa056e9251b96a63f0d45262ad5eddd0f073d2d02d42b6e
+  data.tar.gz: 214a19575d3f3fa624a3d71494b888feccebc18774fa1e38255ec4ceb90c84a6
 SHA512:
-  metadata.gz: e5bc31ac8e9c2dd9f7f3f400080de7d12b625a9795eea0601b03c2c5f5fde79a3d8bd1f185684655c2ada88ffe7f1113c9ec11c67a13969031bdaa14734644e3
-  data.tar.gz: b90a6057a65af77b8fb5221e6760893e78e7d39cc7e986180d0ea97ded8510130a7d372572bec213d74e1538f55fe43b61295ffad66464db949b980b04ee1b9d
+  metadata.gz: 23cc87763d59471eaabdfee09f234f389c3576f7bb6d59df85f65e0205d7f6244710c20cfed77c3e0543513f4db581664e776062383c9a05491673ca8bfc88b8
+  data.tar.gz: 5b905206f71fcea3f15da3f6db3f0e8fcd9f1bd85f06278654d621affb4d72cf42828b828a1f6821602a98f8af5b8441fe701a4785a7626b4327f972dad8b03d

data/context/getting-started.md

@@ -99,7 +99,7 @@ Application = Lively::Application[GameView, game_state: GameState.new]
 
 The `game_state:` keyword is passed to every `GameView` instance — whether created by the initial page load or by a WebSocket reconnection. This means all connected browsers share the same `GameState` object.
 
-For more complex applications, subclass {ruby Lively::Application} and override `#state`, `#allowed_views`, and `#body`:
+For more complex applications, subclass {ruby Lively::Application} and add routes with `#configure_routes`:
 
 ```ruby
 class Application < Lively::Application
@@ -116,26 +116,34 @@ class Application < Lively::Application
 		super
 	end
 	
-	def body(request)
-		case request.path
-		when "/"
-			DisplayView.new(**state)
-		when "/control"
-			ControlView.new(**state)
+	def configure_routes(router)
+		super
+		
+		router.get("/") do
+			render(DisplayView.new(**state))
+		end
+		
+		router.get("/control") do |_request, parameters|
+			render(ControlView.new(**state, mode: parameters["mode"]))
 		end
 	end
 	
+	# Unmatched routes are passed here:
 	def handle(request)
-		if body = self.body(request)
-			page = Lively::Pages::Index.new(title: "My App", body: body)
-			Protocol::HTTP::Response[200, [], [page.call]]
-		else
-			Protocol::HTTP::Response[404, [], ["Not Found"]]
-		end
+		delegate.call(request)
+	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.
+
 ## Live Reloading
 
 To enable live reloading, add the `io-watch` gem to your `gems.rb` file:

data/lib/lively/application.rb

@@ -8,6 +8,7 @@ require "protocol/http/middleware"
 require "async/websocket/adapters/http"
 
 require_relative "resolver"
+require_relative "router"
 require_relative "pages/index"
 require_relative "hello_world"
 
@@ -22,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 {#body}.
+	# {#allowed_views}, {#state}, and {#configure_routes}.
 	class Application < Protocol::HTTP::Middleware
 		VIEWS = [HelloWorld].freeze
 		STATE = {}.freeze
@@ -98,22 +99,36 @@ module Lively
 			Pages::Index.new(title: self.title, body: self.body)
 		end
 		
-		# Handle a standard HTTP request.
+		# 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 HTTP response with the rendered page.
 		def handle(request)
 			return Protocol::HTTP::Response[200, [], [self.index.call]]
 		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.
+		def configure_routes(router)
+			router.route("/live") do |request|
+				Async::WebSocket::Adapters::HTTP.open(request, &self.method(:live)) || Protocol::HTTP::Response[400]
+			end
+		end
+		
+		# The router for this application. Unmatched requests are handled separately
+		# by {#handle}.
+		# @returns [Router] The configured router.
+		def router
+			@router ||= Router.new.tap do |router|
+				configure_routes(router)
+			end
+		end
+		
 		# Process an incoming HTTP request.
 		# @parameter request [Protocol::HTTP::Request] The incoming HTTP request.
 		# @returns [Protocol::HTTP::Response] The appropriate response for the request.
 		def call(request)
-			if request.path == "/live"
-				return Async::WebSocket::Adapters::HTTP.open(request, &self.method(:live)) || Protocol::HTTP::Response[400]
-			else
-				return handle(request)
-			end
+			return router.call(request) || handle(request)
 		end
 	end
 end

data/lib/lively/page.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+require "xrb/markup"
+require "xrb/tag"
+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.
+	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 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.
+		# @parameter modules [Array(String)] JavaScript module URLs in document order.
+		# @parameter body_attributes [Hash] Attributes applied to the body element.
+		def initialize(title: "Lively", body: nil, icon: nil, stylesheets: [], imports: {}, modules: [], body_attributes: {})
+			@title = title
+			@body = body
+			@icon = icon
+			@stylesheets = stylesheets
+			@imports = imports
+			@modules = modules
+			@body_attributes = body_attributes
+			@template = TEMPLATE
+		end
+		
+		# @attribute [String] The document title.
+		attr :title
+		
+		# @attribute [Object | Nil] The document body.
+		attr :body
+		
+		# @attribute [String | Nil] The favicon URL.
+		attr :icon
+		
+		# @attribute [Array(String | Hash)] Stylesheets in document order.
+		attr :stylesheets
+		
+		# @attribute [Hash] JavaScript import map entries.
+		attr :imports
+		
+		# @attribute [Array(String)] JavaScript module URLs in document order.
+		attr :modules
+		
+		# @attribute [Hash] Attributes applied to the body element.
+		attr :body_attributes
+		
+		# @attribute [XRB::Template] The document template.
+		attr :template
+		
+		# The opening body tag including configured attributes.
+		# @returns [XRB::Tag]
+		def body_tag
+			XRB::Tag.opened("body", @body_attributes)
+		end
+		
+		# A stylesheet link tag for the given URL or attributes.
+		# @parameter stylesheet [String | Hash] The stylesheet URL or link attributes.
+		# @returns [XRB::Tag]
+		def stylesheet_tag(stylesheet)
+			attributes = if stylesheet.respond_to?(:to_hash)
+				stylesheet.to_hash
+			else
+				{href: stylesheet}
+			end
+			
+			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
+			json = JSON.pretty_generate(imports: @imports)
+			json = json.gsub("<", "\\u003c").gsub(">", "\\u003e").gsub("&", "\\u0026")
+			
+			XRB::MarkupString.raw(json)
+		end
+		
+		# Render this page to a string.
+		# @returns [String]
+		def call
+			@template.to_string(self)
+		end
+	end
+end

data/lib/lively/page.xrb

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>#{self.title}</title>
+		
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		
+		<?r if self.icon ?>
+		<link rel="icon" type="image/png" href="#{self.icon}" />
+		<?r end ?>
+		<?r self.stylesheets.each do |stylesheet| ?>
+		#{self.stylesheet_tag(stylesheet)}
+		<?r end ?>
+		
+		<?r unless self.imports.empty? ?>
+		<script type="importmap">
+		#{self.import_map}
+		</script>
+		<?r end ?>
+		
+		<?r self.modules.each do |source| ?>
+		<script type="module" src="#{source}"></script>
+		<?r end ?>
+	</head>
+	
+	#{self.body_tag}
+		#{self.body_content}
+	</body>
+</html>

data/lib/lively/pages/index.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2021-2026, by Samuel Williams.
 
-require "xrb/template"
+require_relative "../page"
 
 # @namespace
 module Lively
@@ -14,31 +14,31 @@ module Lively
 		# This class renders the initial HTML page that users see when they visit
 		# a Lively application. It uses an XRB template to generate the page structure
 		# and embeds the Live view component for dynamic content.
-		class Index
+		class Index < Page
+			ICON = "/_static/icon.png"
+			STYLESHEETS = [
+				{href: "/_static/site.css", media: "screen"}.freeze,
+				{href: "/_static/index.css", media: "screen"}.freeze,
+			].freeze
+			IMPORTS = {
+				"live" => "/_components/@socketry/live/Live.js",
+				"live-audio" => "/_components/@socketry/live-audio/Live/Audio.js",
+				"morphdom" => "/_components/morphdom/morphdom-esm.js",
+			}.freeze
+			MODULES = ["/application.js"].freeze
+			
 			# Initialize a new index page.
 			# @parameter title [String] The title of the page.
 			# @parameter body [Object] The body content of the page.
 			def initialize(title: "Lively", body: nil)
-				@title = title
-				@body = body
-				
-				path = File.expand_path("index.xrb", __dir__)
-				@template = XRB::Template.load_file(path)
-			end
-			
-			# @attribute [String] The title of the page.
-			attr :title
-			
-			# @attribute [Object] The body content of the page.
-			attr :body
-			
-			# @attribute [XRB::Template] The XRB template for rendering the page.
-			attr :template
-			
-			# Render this page to a string.
-			# @returns [String] The rendered HTML for this page.
-			def call
-				@template.to_string(self)
+				super(
+					title: title,
+					body: body,
+					icon: ICON,
+					stylesheets: STYLESHEETS,
+					imports: IMPORTS,
+					modules: MODULES,
+				)
 			end
 		end
 	end

data/lib/lively/router.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http"
+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
+		ANY_METHOD = nil
+		private_constant :EMPTY_PARAMETERS, :ANY_METHOD
+		
+		# Initialize a router.
+		# @yields {|router| ...} The router to configure.
+		def initialize
+			@routes = {}
+			
+			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
+			
+			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
+		
+		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
+		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.
+		def call(request)
+			reference = parse_reference(request.path)
+			return Protocol::HTTP::Response[400] unless reference
+			
+			unless handlers = @routes[reference.path]
+				return nil
+			end
+			
+			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)
+		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.18.0"
+	VERSION = "0.19.0"
 end

data/lib/lively.rb

@@ -5,6 +5,8 @@
 
 require_relative "lively/version"
 
+require_relative "lively/page"
+require_relative "lively/router"
 require_relative "lively/assets"
 require_relative "lively/application"
 

data/readme.md

@@ -20,6 +20,10 @@ Please see the [project documentation](https://socketry.github.io/lively/) for m
 
 Please see the [project releases](https://socketry.github.io/lively/releases/index) for all releases.
 
+### v0.18.0
+
+  - Add support for HTTY.
+
 ### v0.17.0
 
   - Expose shared application state via `Application[..., controller: Controller.new]`.
@@ -57,13 +61,6 @@ Please see the [project releases](https://socketry.github.io/lively/releases/ind
 
   - Tidied up gem dependencies.
 
-### v0.13.0
-
-  - Added `live-audio` support for background and positional audio in applications.
-  - Added game audio example demonstrating audio playback.
-  - Fixed serving non-existent asset paths gracefully.
-  - Achieved 100% test and documentation coverage.
-
 ## See Also
 
   - [live](https://github.com/socketry/live) — Provides client-server communication using websockets.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.18.0
+
+  - Add support for HTTY.
+
 ## v0.17.0
 
   - Expose shared application state via `Application[..., controller: Controller.new]`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lively
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: protocol-url
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: xrb
   requirement: !ruby/object:Gem::Requirement
@@ -155,9 +169,11 @@ files:
 - lib/lively/environment/htty.rb
 - lib/lively/environment/middleware.rb
 - lib/lively/hello_world.rb
+- lib/lively/page.rb
+- lib/lively/page.xrb
 - lib/lively/pages/index.rb
-- lib/lively/pages/index.xrb
 - lib/lively/resolver.rb
+- lib/lively/router.rb
 - lib/lively/version.rb
 - license.md
 - public/_components/@socketry/live-audio/Live/Audio.js
@@ -203,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A simple client-server SPA framework.
 test_files: []

metadata.gz.sig

@@ -1,5 +1 @@
-����&f�QskӪ�P7y�ز���Aw��1�aD�)d����@L;7�3�P&3u�hW,{4�����w��.�r���[��//̒}7'�Ӈd'�"?ɨ4W�gs�ub�u|t3��b�@j��Đ�0�y3��F,��}��|����[@k���`%u\�0d�L��W�X��l{5�0���Ԥ��
�#-�d�`�J���>���M��`�-.��T�h��=�D"�c��m������D�`Z�S�Dzȴ�Ku����&�����
-pլ�U 
�*M�\Z��)�X�N�U�_Z�Rj��7�D^���×lb�� �)��p�8P򄺺
-��
-W�����jA����D���F��0���,��
-߻�W|؛~�zV�w̤�m���C
+Rg�D��O�(���>W�`C=W`�R��T:=
�����*-��y�;�}@l��!>K��n�K��_�@*�E���B�����r�
�aO�9��o=�cx�������z�l'Hm�(�/�*@�o����K��ל�T��`UOӕ�z�H��u�_t�����x��F�֥�<;u4x2��G;��E�s��`��V�S�۾��Yw7p�Z�D���
�Z����

data/lib/lively/pages/index.xrb

@@ -1,29 +0,0 @@
-<!DOCTYPE html>
-<html>
-	<head>
-		<title>#{self.title}</title>
-		
-		<meta charset="UTF-8" />
-		<meta name="viewport" content="width=device-width, initial-scale=1" />
-		
-		<link rel="icon" type="image/png" href="/_static/icon.png" />
-		<link rel="stylesheet" href="/_static/site.css" type="text/css" media="screen" />
-		<link rel="stylesheet" href="/_static/index.css" type="text/css" media="screen" />
-		
-		<script type="importmap">
-		{
-			"imports": {
-				"live": "/_components/@socketry/live/Live.js",
-				"live-audio": "/_components/@socketry/live-audio/Live/Audio.js",
-				"morphdom": "/_components/morphdom/morphdom-esm.js"
-			}
-		}
-		</script>
-		
-		<script type="module" src="/application.js"></script>
-	</head>
-	
-	<body>
-		#{self.body&.to_html || "No body specified!"}
-	</body>
-</html>