gemstack-http 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24968edac68aecf39777e4896dde4da2eb3666fddd5adfc7e74b762e111dac3b
+  data.tar.gz: 9885773b193aee11dc47546fda5567f5d23ae4c9dd82028ac509f91f70d30ecf
+SHA512:
+  metadata.gz: 3c1154c7dea23ad9ad39f65531818077f29870257f2286c495d6cd70753c661ff892c0cee5fe94b92343dbaf7a94ba947624bdeb8904a9144159ee3089d505a7
+  data.tar.gz: c70c6bc253e4e6acb467443e21979a5896e98d8a1de839711d66b96e0823a06c6fe0cb56584b91643849f2ce99543f54bed4a7eb7d2c6cb54d4d534acbfd1593

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,26 @@
+# gemstack-http
+
+GemStack HTTP: router, middleware, controllers, params and JSON for Rack.
+
+The API layer of GemStack, built on Rack 3.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Installed with the `gemstack` gem; you rarely need to add it yourself.
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/controllers.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-http`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/http/app.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # The Rack application: the compiled middleware stack in front of the
+    # router. Built once; the router can be replaced (for reloading) without
+    # rebuilding the stack.
+    class App
+      attr_reader :config, :codec
+      attr_accessor :router
+
+      def initialize(config:, router:)
+        @config = config
+        @router = router
+        @codec = JSONCodec.resolve(config.json, max_nesting: config.json_max_nesting)
+        @stack = config.middleware.build(method(:endpoint))
+      end
+
+      def call(env) = @stack.call(env)
+
+      private
+
+      def endpoint(env)
+        env[JSON_CODEC] = @codec
+        env[CONFIG] = @config
+        @router.call(env)
+      end
+    end
+  end
+end

data/lib/gemstack/http/config.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # `config.http` — every setting has a production-ready default.
+    class Config < Settings
+      # Where the API lives. Routes are declared relative to it, and the dev
+      # gateway uses it to send traffic to Ruby. "" mounts the API at the root.
+      setting :api_path, default: "/api"
+
+      # Liveness endpoint answered by HealthCheck. nil disables it.
+      setting :health_path, default: -> { "#{api_path}/health" }
+
+      # Maximum request body size in bytes (413 beyond it).
+      setting :max_body_size, default: 10 * 1024 * 1024
+
+      # JSON codec: :json (stdlib, default), :oj, or any object responding to
+      # dump(object) -> String and load(String) -> object.
+      setting :json, default: :json
+
+      # Maximum nesting depth accepted when parsing JSON request bodies.
+      setting :json_max_nesting, default: 64
+
+      # Include exception class, message and backtrace in 500 responses.
+      # Never enable in production.
+      setting :show_exceptions, default: -> { GemStack.env.local? }
+
+      # Accept X-Request-Id from clients/proxies (validated) instead of
+      # always generating one.
+      setting :trust_request_id, default: true
+
+      # Headers added to every response unless the response already sets them.
+      setting :security_headers, default: {
+        "x-content-type-options" => "nosniff",
+        "x-frame-options" => "DENY",
+        "referrer-policy" => "strict-origin-when-cross-origin",
+        "cross-origin-opener-policy" => "same-origin",
+        "content-security-policy" => "default-src 'none'; frame-ancestors 'none'"
+      }
+
+      # Strict-Transport-Security for HTTPS requests. nil disables.
+      setting :hsts, default: -> { GemStack.env.production? ? "max-age=63072000; includeSubDomains" : nil }
+
+      # Cross-origin access. Off by default: same-origin apps need none.
+      namespace :cors do
+        # Allowed origins: exact strings, Regexps, or "*".
+        setting :origins, default: []
+        setting :methods, default: %w[GET POST PUT PATCH DELETE OPTIONS]
+        setting :headers, default: %w[content-type authorization x-request-id]
+        setting :expose_headers, default: %w[x-request-id]
+        setting :credentials, default: false
+        setting :max_age, default: 600
+      end
+
+      # Response compression (Middleware::Compression).
+      namespace :compression do
+        setting :enabled, default: true
+        # Bodies smaller than this are sent as they are (compression overhead
+        # outweighs the savings on tiny responses).
+        setting :min_size, default: 1024
+        # Server preference; "br" is used only when the brotli gem is installed.
+        setting :encodings, default: %w[br gzip]
+        # Measured on varied JSON (docs/performance.md): gzip 4 costs half the
+        # CPU of gzip 6 for ~2% larger output; Brotli 4 is smaller than gzip 4 and cheaper.
+        setting :brotli_quality, default: 4
+        setting :gzip_level, default: 4
+      end
+
+      # ETags for GET/HEAD responses and 304 Not Modified (Rack::ETag + Rack::ConditionalGet).
+      setting :etags, default: true
+
+      # Defaults for `paginate` in controllers.
+      namespace :pagination do
+        setting :per_page, default: 25
+        setting :max_per_page, default: 100
+      end
+
+      # The middleware stack. Edit it with use / insert_before / insert_after /
+      # swap / delete. Middleware receive this config and read it when the
+      # application is built, so settings may be changed in any order.
+      setting :middleware, default: -> { MiddlewareStack.default(self) }
+    end
+  end
+end

data/lib/gemstack/http/controller.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module GemStack
+  module HTTP
+    # Base class for API controllers.
+    #
+    #   class ProductsController < ApplicationController
+    #     before :load_product, only: %i[show update]
+    #     rescue_from Payments::Declined, status: 402
+    #
+    #     def index = render(Product.all)
+    #     def show = render(@product)
+    #
+    #     def create
+    #       product = Product.create!(params.require(:product).permit(:name, :price))
+    #       render product, status: :created
+    #     end
+    #
+    #     private
+    #
+    #     def load_product = @product = Product.find(params[:id])
+    #   end
+    #
+    # Actions are the public methods defined in subclasses. An action that
+    # doesn't render responds 204 No Content. A `before` callback that
+    # renders halts the chain and the action is skipped.
+    class Controller
+      class DoubleRenderError < Error; end
+      class ActionNotFound < Error; end
+
+      Callback = Struct.new(:callback_method, :block, :only, :except) do
+        def applies?(action)
+          (only.nil? || only.include?(action)) && (except.nil? || !except.include?(action))
+        end
+      end
+
+      RescueHandler = Struct.new(:classes, :handler, :status, :code)
+
+      class << self
+        def before_callbacks = @before_callbacks ||= inherited_copy(:before_callbacks)
+        def after_callbacks = @after_callbacks ||= inherited_copy(:after_callbacks)
+        def rescue_handlers = @rescue_handlers ||= inherited_copy(:rescue_handlers)
+
+        # before :authenticate, only: %i[create update]
+        # before { render({ error: "..." }, status: 401) unless ok? }
+        def before(*methods, only: nil, except: nil, &block)
+          add_callbacks(before_callbacks, methods, block, only, except)
+        end
+
+        def after(*methods, only: nil, except: nil, &block)
+          add_callbacks(after_callbacks, methods, block, only, except)
+        end
+
+        def skip_before(*methods)
+          names = methods.map(&:to_sym)
+          @before_callbacks = before_callbacks.reject { |cb| names.include?(cb.callback_method) }
+        end
+
+        # rescue_from Stripe::CardError, with: :card_declined
+        # rescue_from Timeout::Error, status: 504, code: "upstream_timeout"
+        # rescue_from(MyError) { |error| render({ message: error.message }, status: 400) }
+        # Later declarations take precedence (they are checked first).
+        def rescue_from(*classes, with: nil, status: nil, code: nil, &block)
+          handler = with || block
+          raise ArgumentError, "rescue_from needs with:, a block, or status:" unless handler || status
+
+          rescue_handlers.unshift(RescueHandler.new(classes, handler, status, code))
+        end
+
+        # Declares the request schema for actions; `input` returns the
+        # validated, coerced data inside those actions (DECISIONS D-021).
+        #
+        #   accepts :create, with: Product.input_schema
+        #   accepts :update, with: Product.input_schema, partial: true
+        #   accepts(:search) { required :q, :string }
+        def accepts(*actions, with: nil, partial: false, &)
+          schema = with || Schema.define(&)
+          raise ArgumentError, "accepts needs with: SchemaClass or a block" unless schema
+
+          schema = schema.partial if partial
+          actions.each { |action| input_schemas[action.to_s] = schema }
+        end
+
+        def input_schemas = @input_schemas ||= inherited_copy(:input_schemas, {})
+
+        # Declares an action's response type for the API contract when the
+        # convention (<Resource>Serializer, see docs/typescript.md) doesn't apply:
+        #   returns :search, [ProductSerializer]
+        #   returns :stats, StatsSerializer
+        #   returns :ping, nil          # no body
+        def returns(*actions, type)
+          actions.each { |action| response_types[action.to_s] = type }
+        end
+
+        def response_types = @response_types ||= inherited_copy(:response_types, {})
+
+        # Public instance methods added by subclasses of Controller.
+        def action_methods
+          @action_methods ||= (public_instance_methods(true) - Controller.public_instance_methods(true))
+                              .to_set(&:to_s).freeze
+        end
+
+        def method_added(name)
+          super
+          @action_methods = nil
+        end
+
+        def dispatch(action, env)
+          raise ActionNotFound, "#{name}##{action} is not a public action" unless action_methods.include?(action)
+
+          new(env).process(action)
+        end
+
+        private
+
+        def inherited_copy(name, empty = [])
+          superclass.respond_to?(name) ? superclass.public_send(name).dup : empty
+        end
+
+        def add_callbacks(list, methods, block, only, except)
+          only &&= Array(only).map(&:to_s)
+          except &&= Array(except).map(&:to_s)
+          methods.each { |m| list << Callback.new(m.to_sym, nil, only, except) }
+          list << Callback.new(nil, block, only, except) if block
+        end
+      end
+
+      attr_reader :env, :request, :action_name
+
+      def initialize(env)
+        @env = env
+        @request = Request.new(env)
+        @response = nil
+        @response_headers = {}
+      end
+
+      def params
+        @params ||= Params.new(request.all_params)
+      end
+
+      # The validated input for the current action, as declared with `accepts`.
+      def input
+        @input ||= begin
+          schema = self.class.input_schemas[action_name] or
+            raise Error, "#{self.class.name}##{action_name} has no `accepts` declaration; use params.validate instead"
+          schema.call(params)
+        end
+      end
+
+      # Headers to add to the response. Set them before or after rendering.
+      def headers = @response_headers
+
+      def logger = GemStack.logger
+
+      def rendered? = !@response.nil?
+
+      # Renders value as JSON.
+      #   render product
+      #   render products, status: :ok
+      #   render({ ok: true }, status: 202, headers: { "cache-control" => "no-store" })
+      #   render product, serializer: Admin::ProductSerializer
+      def render(value = nil, status: 200, headers: {}, serializer: nil)
+        raise DoubleRenderError, "render/head called twice in #{self.class.name}##{action_name}" if rendered?
+
+        @response_headers.merge!(headers)
+        @response_headers["content-type"] ||= "application/json; charset=utf-8"
+        body = serializer ? apply_serializer(serializer, value) : serialize(value)
+        @response = [status_code(status), [codec.dump(body)]]
+      end
+
+      # Responds without a body: head :no_content, head 404
+      def head(status, headers = {})
+        raise DoubleRenderError, "render/head called twice in #{self.class.name}##{action_name}" if rendered?
+
+        @response_headers.merge!(headers)
+        @response = [status_code(status), []]
+      end
+
+      # Turns domain objects into JSON-ready structures. By convention an
+      # object of class Product is rendered with ProductSerializer (also for
+      # arrays and datasets of them). Values without a serializer go to the
+      # JSON codec as they are. Override for custom behaviour.
+      def serialize(value)
+        return { data: serialize(value.items), meta: value.meta } if value.is_a?(HTTP::Page)
+
+        Serializer.render(value, serializer_context)
+      end
+
+      # Paginates a dataset (or array) using the `page` and `per_page` query
+      # parameters, bounded by config.http.pagination:
+      #
+      #   render paginate(Product.order(:id))
+      #   render paginate(Product.where(active: true).order(:name), per_page: 50)
+      #
+      # Invalid values are a 422 with field errors. The dataset should be
+      # ordered, or pages may overlap.
+      def paginate(scope, per_page: nil)
+        settings = pagination_settings
+        max = settings.max_per_page
+        page, size = PAGE_SCHEMA.call(params).values_at(:page, :per_page)
+        size = (size || per_page || settings.per_page).clamp(1, max)
+        page ||= 1
+        total = scope.count
+        offset = (page - 1) * size
+        items = scope.is_a?(Array) ? scope[offset, size] || [] : scope.limit(size).offset(offset).all
+        HTTP::Page.new(items, page: page, per_page: size, total: total)
+      end
+
+      PAGE_SCHEMA = Schema.define do
+        optional :page, :integer, gte: 1
+        optional :per_page, :integer, gte: 1
+      end
+
+      # HTTP caching. Sets ETag / Last-Modified and answers 304 Not Modified
+      # (without rendering) when the client already has this version:
+      #
+      #   def show
+      #     product = Product.find(params[:id])
+      #     render product if stale?(etag: product, last_modified: product.updated_at)
+      #   end
+      #
+      # etag: any value; records use #cache_key when they have one.
+      def stale?(etag: nil, last_modified: nil)
+        headers["etag"] = %(W/"#{Digest::SHA256.hexdigest(etag_source(etag))[0, 32]}") unless etag.nil?
+        headers["last-modified"] = last_modified.httpdate if last_modified
+        return true unless fresh?
+
+        head :not_modified
+        false
+      end
+
+      def fresh_when(**) = stale?(**)
+
+      #   cache_control max_age: 60                        # private, max-age=60
+      #   cache_control max_age: 300, public: true, stale_while_revalidate: 30
+      #   cache_control :no_store
+      def cache_control(directive = nil, max_age: nil, public: false, stale_while_revalidate: nil)
+        headers["cache-control"] =
+          if directive == :no_store then "no-store"
+          else
+            [public ? "public" : "private", ("max-age=#{Integer(max_age)}" if max_age),
+             ("stale-while-revalidate=#{Integer(stale_while_revalidate)}" if stale_while_revalidate)].compact.join(", ")
+          end
+      end
+
+      # Passed to serializers as `context` (e.g. { current_user: current_user }).
+      def serializer_context = {}
+
+      def process(action)
+        @action_name = action
+        run_callbacks(self.class.before_callbacks)
+        public_send(action) unless rendered?
+        run_callbacks(self.class.after_callbacks)
+        finish
+      rescue StandardError => e
+        handle_exception(e)
+        finish
+      end
+
+      private
+
+      def finish
+        head(:no_content) unless rendered?
+        status, body = @response
+        [status, @response_headers, body]
+      end
+
+      def run_callbacks(callbacks)
+        callbacks.each do |callback|
+          next unless callback.applies?(@action_name)
+
+          callback.callback_method ? send(callback.callback_method) : instance_exec(&callback.block)
+          break if rendered? && callbacks.equal?(self.class.before_callbacks)
+        end
+      end
+
+      def handle_exception(error)
+        rescuer = self.class.rescue_handlers.find { |h| h.classes.any? { |klass| error.is_a?(klass) } }
+        raise error unless rescuer
+
+        @response = nil
+        @response_headers = @response_headers.slice("x-request-id")
+        if rescuer.handler
+          rescuer.handler.is_a?(Proc) ? instance_exec(error, &rescuer.handler) : call_handler(rescuer.handler, error)
+        else
+          status = status_code(rescuer.status)
+          wrapped = GemStack::Error.new(error.message, status: status,
+                                                       code: rescuer.code || ErrorRenderer.code_for(status))
+          status, headers, body = ErrorRenderer.render(wrapped, request_id: request.request_id)
+          @response_headers.merge!(headers)
+          @response = [status, body]
+        end
+      end
+
+      def pagination_settings = (env[CONFIG] || Config.new).pagination
+
+      def etag_source(value)
+        case value
+        when Array then value.map { |v| etag_source(v) }.join("/")
+        else value.respond_to?(:cache_key) ? value.cache_key.to_s : value.to_s
+        end
+      end
+
+      def fresh?
+        none_match = request.get_header("HTTP_IF_NONE_MATCH")
+        etag = headers["etag"]
+        if none_match && etag
+          tags = none_match.split(",").map { |t| t.strip.delete_prefix("W/") }
+          return tags.include?("*") || tags.include?(etag.delete_prefix("W/"))
+        end
+        modified_since = request.get_header("HTTP_IF_MODIFIED_SINCE")
+        last_modified = headers["last-modified"]
+        return false unless modified_since && last_modified
+
+        Time.httpdate(last_modified) <= Time.httpdate(modified_since)
+      rescue ArgumentError
+        false
+      end
+
+      def apply_serializer(serializer, value)
+        return { data: serializer.many(value.items, serializer_context), meta: value.meta } if value.is_a?(HTTP::Page)
+
+        list = value.is_a?(Array) || (value.respond_to?(:all) && value.respond_to?(:model))
+        list ? serializer.many(value, serializer_context) : serializer.serialize(value, serializer_context)
+      end
+
+      def call_handler(name, error)
+        method(name).arity.zero? ? send(name) : send(name, error)
+      end
+
+      def status_code(status)
+        return status if status.is_a?(Integer)
+
+        Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(status.to_sym) { raise ArgumentError, "unknown status #{status}" }
+      end
+
+      def codec = env[JSON_CODEC] || JSONCodec.default
+    end
+  end
+end

data/lib/gemstack/http/error_page.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module GemStack
+  module HTTP
+    # The development error page: shown instead of the JSON envelope when a
+    # *browser* opens an API URL that raises (a 500 with show_exceptions on).
+    # fetch() and API clients keep getting JSON. Self-contained HTML, no JS.
+    module ErrorPage
+      CONTEXT_LINES = 5
+
+      module_function
+
+      # A top-level navigation from a browser (not fetch/XHR or an API client).
+      def browser?(env)
+        dest = env["HTTP_SEC_FETCH_DEST"]
+        return dest == "document" if dest
+
+        env["HTTP_ACCEPT"].to_s.include?("text/html")
+      end
+
+      def render(exception, env, request_id: nil)
+        html = page(exception, env, request_id)
+        [500, { "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store",
+                "content-security-policy" => "default-src 'none'; style-src 'unsafe-inline'" }, [html]]
+      end
+
+      def page(exception, env, request_id)
+        frames = frames(exception)
+        first_app = frames.find { |frame| frame[:app] }
+        <<~HTML
+          <!doctype html>
+          <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>#{h(exception.class.name)} · GemStack</title><style>#{STYLE}</style></head>
+          <body><main>
+          <p class="tag">#{h(env[Rack::REQUEST_METHOD])} #{h(env[Rack::PATH_INFO])}#{" · request #{h(request_id)}" if request_id}</p>
+          <h1>#{h(exception.class.name)}</h1>
+          <pre class="message">#{h(exception.message)}</pre>
+          #{source(first_app || frames.first)}
+          #{cause(exception)}
+          <h2>Backtrace</h2>
+          <ol class="trace">#{frames.map { |frame| trace_line(frame) }.join}</ol>
+          <p class="hint">Shown because <code>config.http.show_exceptions</code> is on (development). API clients get the
+          JSON error envelope; production shows neither the message nor the backtrace.</p>
+          </main></body></html>
+        HTML
+      end
+
+      def frames(exception)
+        root = GemStack.config.root.to_s
+        Array(exception.backtrace).first(60).map do |line|
+          file, number, label = line.match(/\A(.+?):(\d+)(?::in [`'](.*)')?/)&.captures
+          relative = file&.start_with?("#{root}/") ? file.delete_prefix("#{root}/") : nil
+          app = !relative.nil? && !relative.start_with?("vendor/", "tmp/") && !relative.include?("/gems/")
+          { line: line, file: file, number: number&.to_i, label: label,
+            display: app ? line.delete_prefix("#{root}/") : shorten(line), app: app }
+        end
+      end
+
+      def source(frame)
+        return "" unless frame && frame[:file] && File.file?(frame[:file])
+
+        lines = File.readlines(frame[:file])
+        from = [frame[:number] - CONTEXT_LINES, 1].max
+        to = [frame[:number] + CONTEXT_LINES, lines.size].min
+        rows = (from..to).map do |n|
+          css = n == frame[:number] ? ' class="hit"' : ""
+          "<span#{css}><i>#{n}</i>#{h(lines[n - 1].to_s.chomp)}</span>"
+        end
+        %(<h2>#{h(frame[:display].to_s.sub(/:in .*/, ""))}</h2><pre class="source">#{rows.join}</pre>)
+      rescue SystemCallError, ArgumentError
+        ""
+      end
+
+      def cause(exception)
+        cause = exception.cause or return ""
+        return "" if exception.message.include?(cause.message.to_s.lines.first.to_s.strip) # wrapped, already shown
+
+        %(<p class="cause">Caused by <b>#{h(cause.class.name)}</b>: #{h(cause.message)}</p>)
+      end
+
+      def trace_line(frame)
+        %(<li#{' class="app"' if frame[:app]}>#{h(frame[:display])}</li>)
+      end
+
+      # /…/gems/4.0.0/gems/sequel-5.108.0/lib/x.rb → sequel-5.108.0/lib/x.rb
+      def shorten(line)
+        prefixes = Gem.path.map { |dir| "#{dir}/gems/" } + ["#{RbConfig::CONFIG["rubylibdir"]}/"]
+        prefix = prefixes.find { |dir| line.start_with?(dir) }
+        prefix ? line.delete_prefix(prefix) : line
+      end
+
+      def h(value) = Rack::Utils.escape_html(value.to_s)
+
+      STYLE = <<~CSS
+        :root { color-scheme: light dark; --bg: #fff; --fg: #16181d; --muted: #5b6170; --panel: #f3f4f7; --hit: #fde2e2; --accent: #c53030; }
+        @media (prefers-color-scheme: dark) { :root { --bg: #0f1115; --fg: #e6e8ee; --muted: #9aa0ad; --panel: #1b1f2a; --hit: #4a1d22; --accent: #ff7b7b; } }
+        body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }
+        main { max-width: 64rem; margin: 0 auto; padding: 2rem 1rem 4rem; }
+        h1 { color: var(--accent); margin: .2rem 0; font-size: 1.6rem; overflow-wrap: anywhere; }
+        h2 { font-size: .95rem; margin: 1.8rem 0 .5rem; color: var(--muted); font-weight: 600; overflow-wrap: anywhere; }
+        pre, ol { background: var(--panel); border-radius: 8px; padding: .8rem 1rem; overflow-x: auto; font: 13px/1.55 ui-monospace, Menlo, monospace; }
+        .message { white-space: pre-wrap; font-size: 14px; }
+        .source span { display: block; } .source i { display: inline-block; width: 3.5em; color: var(--muted); font-style: normal; }
+        .source .hit { background: var(--hit); } .trace { padding-left: 3rem; color: var(--muted); } .trace .app { color: var(--fg); font-weight: 600; }
+        .tag, .hint, .cause { color: var(--muted); } code { font-family: ui-monospace, Menlo, monospace; }
+      CSS
+    end
+  end
+end