hecks 1.3.0 → 1.5.0

data/lib/hecks/forms/html.rb

@@ -11,8 +11,14 @@ module Hecks
     # account number a support rep typed into a form and got wrong — flows
     # through here on every render, so escaping is not optional decoration.
     module Escape
+      # Escapes a value for HTML text content, replacing `&`, `<`, `>`, `"` and `'` with
+      # entities so nothing in it becomes a tag.
+      #
       # Order matters — `&` first, or every escape this method itself just
       # wrote (`&amp;`, `&lt;`, ...) gets re-escaped a second time.
+      #
+      # @param value [Object, nil] the value to show, rendered with `to_s`; nil renders as `""`
+      # @return [String] the escaped text
       def self.html(value)
         value.to_s
              .gsub("&", "&amp;")
@@ -22,14 +28,22 @@ module Hecks
              .gsub("'", "&#39;")
       end
 
+      # Escapes a value for use inside a quoted HTML attribute.
+      #
       # Safe inside a double-quoted HTML attribute specifically — `html`
       # already covers this (it escapes `"`), kept as a named alias so a
       # call site reads "this value fills an attribute" rather than repeating
       # the same escaping and leaving the reader to check they match.
+      #
+      # @param value [Object, nil] the attribute value, rendered with `to_s`; nil renders
+      #   as `""`
+      # @return [String] the escaped text, without surrounding quotes
       def self.attr(value) = html(value)
 
+      # Percent-encodes a value for use as a query-string value.
+      #
       # L12 (docs/audits/2026-08-10-main-bug-audit.md) — safe as a
-      # query-string VALUE. `html`/`attr` guard against the value becoming
+      # query-string value. `html`/`attr` guard against the value becoming
       # markup, but say nothing about it staying inside the URL syntax
       # position it was placed in: an aggregate's identity is free-form
       # unless its value object declares a `pattern:` (see S3 in the same
@@ -38,23 +52,32 @@ module Hecks
       # interpolation (a stray `&` smuggles a second query parameter, `#`
       # truncates the path at a fragment, `/` splits the path into an
       # extra segment, ...). Percent-encodes via
-      # `application/x-www-form-urlencoded` (`+` for space) — correct ONLY
+      # `application/x-www-form-urlencoded` (`+` for space) — correct only
       # for a query-string value (query_form_renderer.rb's `quick_links`,
-      # record_renderer.rb's `?to=`). For a URL PATH segment use `path`
+      # record_renderer.rb's `?to=`). For a URL path segment use `path`
       # below instead — `+` is a literal plus there, not an escaped space,
       # so this method would corrupt any id containing a space. Callers
-      # still wrap the ASSEMBLED href/Location in `attr` (or `html`) as
+      # still wrap the assembled href/Location in `attr` (or `html`) as
       # usual — this only covers the id's own component, not the
       # surrounding markup.
+      #
+      # @param value [Object, nil] the value to encode, rendered with `to_s`
+      # @return [String] the `application/x-www-form-urlencoded` form, a space rendered as `+`
       def self.url(value) = URI.encode_www_form_component(value.to_s)
 
-      # Same guard as `url`, for a URL PATH segment instead of a
+      # Percent-encodes a value for use as one URL path segment.
+      #
+      # Same guard as `url`, for a URL path segment instead of a
       # query-string value. `encode_www_form_component` renders space as
       # `+`, which is only meaningful inside a query string — in a path
       # segment `+` is a literal plus, so an id like "John Smith" would
       # round-trip to "John+Smith" and 404 against the real id "John
       # Smith". Reuse the same percent-encoding and just correct that one
       # character back to `%20`.
+      #
+      # @param value [Object, nil] the segment to encode, rendered with `to_s`
+      # @return [String] the percent-encoded segment, a space rendered as `%20` and `/` as
+      #   `%2F`
       def self.path(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
     end
 
@@ -64,6 +87,14 @@ module Hecks
     # `true` renders as a bare boolean attribute (`required`, not
     # `required="true"`); `nil`/`false` are dropped entirely.
     module Tag
+      # Renders a Hash of attributes as the text that sits inside an opening tag, escaping
+      # every value and spelling an underscored name with hyphens.
+      #
+      # @param pairs [Hash{Symbol => Object}] attribute values by name; `true`
+      #   renders the bare name, nil and `false` drop the attribute, anything else is
+      #   rendered with `to_s`
+      # @return [String] space-separated attributes, such as `required aria-describedby="x"`;
+      #   `""` when every pair is dropped
       def self.attrs(pairs)
         pairs.filter_map do |name, value|
           next if value.nil? || value == false
@@ -73,15 +104,28 @@ module Hecks
         end.join(" ")
       end
 
+      # Renders an opening tag with its attributes. The tag name is interpolated unescaped,
+      # so it must come from code, never from domain data.
+      #
+      # @param name [String] the element name, such as `"input"`
+      # @param pairs [Hash{Symbol => Object}] attributes, rendered as `attrs` renders them
+      # @return [String] the opening tag, such as `<input type="text" required>`
       def self.open(name, **pairs)
         rendered = attrs(pairs)
         rendered.empty? ? "<#{name}>" : "<#{name} #{rendered}>"
       end
 
-      # `self.open(...)`, not bare `open(...)` — this Html.open (an HTML tag
+      # Renders a void element such as `<input>`. A self-closing tag reads the same as an
+      # opening one; HTML5 needs no slash.
+      #
+      # `self.open(...)`, not bare `open(...)` — this `Tag.open` (an HTML tag
       # renderer, right above) shadows Kernel#open safely either way, but the
       # explicit receiver also settles Security/Open's static ambiguity.
-      def self.void(name, **pairs) = self.open(name, **pairs) # self-closing tags read the same; HTML5 needs no slash
+      #
+      # @param name [String] the element name, such as `"input"`
+      # @param pairs [Hash{Symbol => Object}] attributes, rendered as `attrs` renders them
+      # @return [String] the tag, identical to what `open` renders
+      def self.void(name, **pairs) = self.open(name, **pairs)
     end
   end
 end

data/lib/hecks/forms/index_renderer.rb

@@ -4,9 +4,15 @@ module Hecks
   module Forms
     # The home page: every exposed chapter, every aggregate on it — the
     # entry point into what would otherwise be a URL you'd have to already
-    # know. `chapters` is `{domain_name => Bluebook}`, in `expose` order
-    # (see config.rb).
+    # know. `chapters` is `{domain_name => Bluebook::Chapter}`, in `expose`
+    # order (see `Forms::Config` in forms.rb).
     module IndexRenderer
+      # Renders the home page body: one section per exposed chapter, each linking to its
+      # aggregates.
+      #
+      # @param chapters [Hash{String => Bluebook::Chapter}] the loaded chapters by domain
+      #   name, in `expose` order
+      # @return [String] the HTML page body; only the heading when `chapters` is empty
       def self.render(chapters)
         sections = chapters.map { |name, chapter| chapter_section(name, chapter) }
         <<~HTML
@@ -15,6 +21,12 @@ module Hecks
         HTML
       end
 
+      # Renders one chapter's section: its name, its vision as a badge when it declares one,
+      # and a link per aggregate showing how many commands and queries it has.
+      #
+      # @param name [String] the domain name, used as the heading and the first path segment
+      # @param chapter [Bluebook::Chapter] the loaded chapter
+      # @return [String] HTML for the section's heading and aggregate list
       def self.chapter_section(name, chapter)
         items = chapter.aggregates.map do |aggregate|
           counts = "#{aggregate.commands.size} command#{'s' unless aggregate.commands.size == 1}, " \

data/lib/hecks/forms/page.rb

@@ -9,6 +9,15 @@ module Hecks
     # `prefers-color-scheme` alone; nothing here reads a cookie or a query
     # param for it, so it is never wrong for the browser rendering it.
     module Page
+      # Wraps one page's own body HTML in the shared shell: doctype, head, nav, footer,
+      # inline styles and script.
+      #
+      # @param title [String] the page title, escaped into `<title>` and the browser tab
+      # @param body [String] the page's own body markup, inserted unescaped inside `<main>`
+      # @param breadcrumbs [Array<Array(String, String), Array(String, nil)>] each
+      #   `[label, href]` pair, in order; the last pair's `href` should be `nil` for the
+      #   current page
+      # @return [String] the complete HTML document
       def self.render(title:, body:, breadcrumbs: [])
         <<~HTML
           <!doctype html>
@@ -36,6 +45,11 @@ module Hecks
         HTML
       end
 
+      # Renders the breadcrumb trail as a `<nav>`, each crumb a link except the last.
+      #
+      # @param crumbs [Array<Array(String, String), Array(String, nil)>] each
+      #   `[label, href]` pair; a `nil` href renders as the current, unlinked page
+      # @return [String] the `<nav>` markup, HTML-escaped; `""` when `crumbs` is empty
       def self.breadcrumbs_html(crumbs)
         return "" if crumbs.empty?
 

data/lib/hecks/forms/params.rb

@@ -4,35 +4,59 @@ require_relative "field_renderer"
 
 module Hecks
   module Forms
-    # The two directions between a flat, dotted, ALL-STRINGS web payload
+    # The two directions between a flat, dotted, all-strings web payload
     # (`{"amount.cents"=>"1050", "amount.currency"=>"USD"}`, whether it came
     # off a POST form body or a GET query string — Rack hands back the same
     # flat shape for both as long as nothing uses `[]` bracket names) and the
     # nested, typed hash `Dispatcher#dispatch`/`#query` actually take
     # (`{amount: {cents: 1050, currency: "USD"}}`).
     #
-    # `extract` NEEDS the Field tree, not just the raw params — a numeric
+    # `extract` needs the Field tree, not just the raw params — a numeric
     # leaf's own runtime check (`Value::Coercion#check_numeric_fields`)
     # requires an actual `Integer`/`Float`, not a String that merely looks
     # like one (`given.is_a?(expected)`, no coercion attempted there); a web
     # form can only ever hand back strings, so the cast has to happen here,
-    # once, using the SAME shape `FieldShape` already resolved for
+    # once, using the same shape `FieldShape` already resolved for
     # rendering the input in the first place — one reading of the IR, not
     # two that could disagree.
     module Params
-      # Every LEAF field carries its own full dotted path regardless of how
+      # Casts a flat, all-strings web payload into the nested, typed arguments a command or
+      # query takes, guided by the field tree the form was rendered from.
+      #
+      # Every leaf field carries its own full dotted path regardless of how
       # deep `FieldShape` nested it to get there — a single-attribute value
-      # object unwraps to a leaf sitting at the TOP of the fields array with
+      # object unwraps to a leaf sitting at the top of the fields array with
       # a two-segment path (`"reference.value"`), the exact same shape a
       # `:group`'s own child carries. So this collects every leaf as
-      # (full path -> value) FIRST, and nests by the path's OWN segments
+      # (full path -> value) first, and nests by the path's own segments
       # last — one nesting rule, blind to how a field arrived at its path.
+      #
+      # @param fields [Array<Forms::Field>] the resolved field tree the payload was posted
+      #   against
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @return [Hash{Symbol => Object}] nested, typed arguments keyed by path segment, ready
+      #   to splat into a dispatch; a blank optional field is left out
+      # @raise [ArgumentError] if a number field's text is not numeric, or two fields collide
+      #   at one path (see `nest`)
+      # @raise [TypeError] if a required number field is missing from `raw`
+      # @raise [JSON::ParserError] if a line of a list-of-value-objects field is not JSON
       def self.extract(fields, raw)
         pairs = {}
         fields.each { |field| collect(field, raw, pairs) }
         nest(pairs)
       end
 
+      # Gathers one field's typed value, and recursively its children's, into `pairs` under
+      # each leaf's full dotted path; a blank optional leaf adds nothing.
+      #
+      # @param field [Forms::Field] the field to read
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @param pairs [Hash{String => Object}] accumulator of typed values by dotted path,
+      #   added to in place
+      # @return [void]
+      # @raise [ArgumentError] if a number field's text is not numeric
+      # @raise [TypeError] if a required number field is missing from `raw`
+      # @raise [JSON::ParserError] if a line of a list-of-value-objects field is not JSON
       def self.collect(field, raw, pairs)
         case field.kind
         when :group, :money then field.children.each { |child| collect(child, raw, pairs) }
@@ -41,23 +65,32 @@ module Hecks
         end
       end
 
+      # Nests values keyed by dotted path into a Hash keyed by path segment, refusing two
+      # paths that cannot share one result.
+      #
       # A path-prefix collision: one field named (say) "price" alongside
-      # another named "price.cents" implies "price" is BOTH a scalar leaf
+      # another named "price.cents" implies "price" is both a scalar leaf
       # and the parent of a nested group — the two can never coexist in
       # the same result hash. Depending on which pair `each_with_object`
-      # reaches first, the naive walk below used to fail in one of two
-      # ways: a scalar planted first left `acc[segment] ||= {}` seeing a
-      # truthy non-Hash and reusing IT as `node`, so the next `node[leaf] =
-      # value` blew up with a raw `TypeError` from calling `String#[]=`
-      # with a Symbol key; a scalar planted AFTER the nested group instead
-      # sailed through `node[leaf] = value` and silently clobbered the
-      # entire nested hash with the scalar, losing every sibling under it
-      # with no error at all. Both directions are checked explicitly here
-      # so either order raises the SAME clear `ArgumentError` instead of a
-      # confusing crash or silent data loss — this is the family of error
-      # every command/query submission path in app.rb already rescues into
-      # a 422 (`ArgumentError` sits right alongside the domain refusals in
-      # every one of those rescue clauses).
+      # reaches first, an unguarded walk fails in one of two ways: a scalar
+      # planted first leaves `acc[segment] ||= {}` seeing a truthy non-Hash
+      # and reusing it as `node`, so the next `node[leaf] = value` blows up
+      # with a raw `TypeError` from calling `String#[]=` with a Symbol key;
+      # a scalar planted after the nested group instead sails through
+      # `node[leaf] = value` and silently clobbers the entire nested hash
+      # with the scalar, losing every sibling under it with no error at
+      # all. Both directions are checked explicitly here so either order
+      # raises the same clear `ArgumentError` instead of a confusing crash
+      # or silent data loss — this is the family of error every
+      # command/query submission path in app.rb already rescues into a 422
+      # (`ArgumentError` sits right alongside the domain refusals in every
+      # one of those rescue clauses).
+      #
+      # @param pairs [Hash{String => Object}] values keyed by dotted path, such as
+      #   `{"amount.cents" => 1050}`
+      # @return [Hash{Symbol => Object}] the nested result, such as `{amount: {cents: 1050}}`
+      # @raise [ArgumentError] if one path names a plain value where another names a nested
+      #   group, in either order
       def self.nest(pairs)
         pairs.each_with_object({}) do |(path, value), result|
           segments = path.to_s.split(".").map(&:to_sym)
@@ -74,6 +107,10 @@ module Hecks
         end
       end
 
+      # Builds, without raising, the error `nest` raises for a path-prefix collision.
+      #
+      # @param path [String] the dotted path at which the collision was found
+      # @return [ArgumentError] an error whose message names the conflicting path
       def self.nesting_collision(path)
         ArgumentError.new("#{path.inspect} conflicts with another field at the same path — " \
                           "one names it as a plain value and another as a nested group")
@@ -82,11 +119,21 @@ module Hecks
       SKIP = Object.new.freeze
       private_constant :SKIP
 
+      # Reads a `:list` field's textarea into an Array, one element per non-blank line.
+      #
       # One line of the textarea per element. A line that itself needs
       # several fields (a multi-attribute value object as a list element)
       # is read as JSON on that one line — the honest fallback documented in
       # docs/command-form-and-query-form-bluebook.md rather than a second
       # widget this prototype doesn't build yet.
+      #
+      # @param field [Forms::Field] a `:list` field whose first child describes one element
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @return [Array<Object>, Object] the elements — cast scalars for a leaf element,
+      #   symbol-keyed parsed JSON otherwise — or the private `SKIP` sentinel when the field
+      #   is absent or blank
+      # @raise [ArgumentError] if a number element's line is not numeric
+      # @raise [JSON::ParserError] if a non-leaf element's line is not JSON
       def self.extract_list(field, raw)
         text = raw[field.path]
         return SKIP if text.nil? || text.strip.empty?
@@ -97,6 +144,16 @@ module Hecks
         end
       end
 
+      # Reads one leaf field's typed value out of the payload; a boolean always answers, since
+      # an unticked checkbox is itself a value.
+      #
+      # @param field [Forms::Field] a leaf field
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @return [Boolean, Integer, Float, String, nil, Object] the cast value; nil when a
+      #   required non-number field is missing; the private `SKIP` sentinel when an optional
+      #   field is absent or empty
+      # @raise [ArgumentError] if a number field's text is not numeric
+      # @raise [TypeError] if a required number field is missing from `raw`
       def self.extract_leaf(field, raw)
         return checkbox(raw[field.path]) if field.kind == :boolean
 
@@ -106,10 +163,24 @@ module Hecks
         cast_scalar(field, text)
       end
 
+      # Reads a submitted checkbox value as a Boolean.
+      #
+      # @param raw_value [String, nil] the submitted text; nil when the field was not posted
+      # @return [Boolean] true for `"on"`, `"1"` or `"true"` in any letter case, false for
+      #   anything else
       def self.checkbox(raw_value)
         %w[on 1 true].include?(raw_value.to_s.downcase)
       end
 
+      # Casts a leaf's submitted text to the Ruby type the runtime's numeric check requires,
+      # which accepts an actual `Integer` or `Float` and never a numeric-looking String.
+      #
+      # @param field [Forms::Field] the leaf the text was submitted for
+      # @param text [String, nil] the submitted text
+      # @return [Integer, Float, String, nil] an Integer for a `:number` field with `step`
+      #   `"1"`, a Float for any other `:number` field, and `text` itself for every other kind
+      # @raise [ArgumentError] if a number field's text is not numeric
+      # @raise [TypeError] if a number field's text is nil
       def self.cast_scalar(field, text)
         case field.kind
         when :number then field.step == "1" ? Integer(text) : Float(text)
@@ -117,13 +188,23 @@ module Hecks
         end
       end
 
+      # Flattens held values back into the dotted-path, all-strings pairs a query string
+      # carries — the reverse of `extract`.
+      #
       # The other direction — a nested value hash back to the flat dotted
       # pairs a GET link's query string carries, so a query view's
-      # "shareable link" and its filter FORM stay two renderings of the
-      # SAME data rather than two formats that can drift. Reads with
+      # "shareable link" and its filter form stay two renderings of the
+      # same data rather than two formats that can drift. Reads with
       # `FieldRenderer.dig` — the identical full-path lookup a re-rendered
       # input's own value comes from — for the same reason `extract` above
       # nests by full path rather than by tree shape.
+      #
+      # @param fields [Array<Forms::Field>] the field tree naming which paths to read
+      # @param values [Hash{String, Symbol => Object}] held values, flat or nested; see
+      #   `FieldRenderer.dig`
+      # @param into [Hash{String => String}] accumulator the pairs are added to in place
+      # @return [Hash{String => String}] `into`, holding one pair per leaf with a non-nil value
+      #   and one per list (its elements newline-joined, `""` when it holds nothing)
       def self.flatten(fields, values, into: {})
         fields.each do |field|
           case field.kind
@@ -137,11 +218,19 @@ module Hecks
         into
       end
 
+      # Lists every dotted path a field tree submits under, whether or not anything was
+      # entered for it.
+      #
       # Every leaf/list path a field tree carries, independent of any
       # values — what `command_form_renderer.rb`'s inspect panel wants
       # ("which fields does this command take"), where `flatten` above wants
-      # "what does THIS submission look like" and returns nothing for a
+      # "what does this one submission look like" and returns nothing for a
       # field nothing was entered for.
+      #
+      # @param fields [Array<Forms::Field>] the field tree to walk
+      # @param into [Array<String>] accumulator the paths are appended to in place
+      # @return [Array<String>] `into`, holding each leaf and list path in render order;
+      #   `:group` and `:money` fields contribute their children's paths, not their own
       def self.paths(fields, into: [])
         fields.each do |field|
           case field.kind
@@ -152,6 +241,14 @@ module Hecks
         into
       end
 
+      # Renders held values as a URL query string, percent-encoding each flattened path and
+      # value.
+      #
+      # @param fields [Array<Forms::Field>] the field tree naming which paths to read
+      # @param values [Hash{String, Symbol => Object}] held values, flat or nested; see
+      #   `FieldRenderer.dig`
+      # @return [String] `key=value` pairs joined with `&`, without a leading `?`; `""` when
+      #   `flatten` yields no pairs
       def self.to_query_string(fields, values)
         pairs = flatten(fields, values)
         pairs.map { |key, value| "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(value)}" }.join("&")

data/lib/hecks/forms/port_argument.rb

@@ -5,13 +5,13 @@ module Hecks
     # boot. Two spellings the previous inline version got wrong:
     #
     #   --port=8080   the equals form — the old `ARGV.each_cons(2)` scan
-    #                 only ever recognized "--port", "8080" as TWO
+    #                 only ever recognized "--port", "8080" as two
     #                 separate argv entries, so this spelling matched
     #                 nothing and silently fell through to the default.
     #   -p abc        a non-numeric value — the old code did `.to_i` on
     #                 whatever followed unconditionally, so a typo
     #                 quietly became port 0 (Rackup/WEBrick's actual
-    #                 behavior for `Port: 0` is to bind an EPHEMERAL
+    #                 behavior for `Port: 0` is to bind an ephemeral
     #                 port — arguably useful on purpose elsewhere, but
     #                 never what a mistyped `-p abc` meant to ask for).
     #
@@ -22,6 +22,13 @@ module Hecks
     module PortArgument
       module_function
 
+      # Reads the `-p`/`--port` argument out of an argv array.
+      #
+      # @param argv [Array<String>] the command-line arguments, ARGV-shaped
+      # @param default [Integer] the port to use when neither spelling appears at all
+      # @return [Array(Integer, nil), Array(nil, String)] `[port, nil]` on a clean
+      #   parse, or `[nil, message]` when an explicit port was given but isn't a
+      #   real port number
       def parse(argv, default: 4567)
         equals = argv.find { |arg| arg.start_with?("--port=") }
         return resolve(equals.split("=", 2).last) if equals
@@ -32,6 +39,11 @@ module Hecks
         resolve(argv[index + 1])
       end
 
+      # Validates and converts a raw `-p`/`--port` argument value.
+      #
+      # @param value [String, nil] the text following `-p`/`--port`, or nil if none
+      # @return [Array(Integer, nil), Array(nil, String)] `[port, nil]` if `value`
+      #   is a whole number between 1 and 65535, or `[nil, message]` otherwise
       def resolve(value)
         return [nil, "-p/--port requires a value"] if value.nil? || value.empty?
         return [nil, "-p/--port must be a whole number, got #{value.inspect}"] unless value.match?(/\A\d+\z/)

data/lib/hecks/forms/query_form_renderer.rb

@@ -16,10 +16,25 @@ module Hecks
     # hiding that behind a form); a row of ready-made links for any
     # closed-set parameter, since a caller filtering by an enum should not
     # have to fill in a form to get a link they could just click; a filter
-    # FORM for everything else, which — being a GET form — produces
+    # form for everything else, which — being a GET form — produces
     # exactly the same kind of link on submit; and the results table once
     # a request actually supplies parameters.
     module QueryFormRenderer
+      # Renders one query's whole GET view: header, canonical link, quick links, filter
+      # form, any error, results, and the inspect panel.
+      #
+      # @param registry [Runtime::Registry] the booted registry, for resolving reference
+      #   fields' target aggregates
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @param action [String] the form's `action` URL and the canonical link's base
+      # @param params [Hash] the request's own query params, pre-filling the filter form
+      # @param results [Array<Hash>, nil] the query's own answer rows; `nil` renders no
+      #   results section
+      # @param error [StandardError, nil] a raised error to show in the error banner;
+      #   `nil` renders none
+      # @return [String] the page body markup
       def self.render(registry:, domain:, aggregate:, query:, action:, params: {}, results: nil, error: nil)
         fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
         reference_options = ReferenceOptions.collect(registry, domain, fields)
@@ -35,6 +50,12 @@ module Hecks
         HTML
       end
 
+      # Renders the query's title, description and badges.
+      #
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @return [String] the header markup
       def self.header(domain, aggregate, query)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}")}</h1>
@@ -43,12 +64,22 @@ module Hecks
         HTML
       end
 
+      # Renders the query's declared badges — today, just its `limit` when it declares one.
+      #
+      # @param query [Bluebook::Query] the query being rendered
+      # @return [String] the badge markup; `""` when the query declares no `limit`
       def self.badges(query)
         parts = []
         parts << %(<span class="badge">limit #{Escape.html(query.limit.to_h[:value])}</span>) if query.limit
         parts.join
       end
 
+      # Renders the query's plain-GET canonical link template, one `path={path}` per
+      # parameter.
+      #
+      # @param action [String] the query's base URL
+      # @param fields [Array<Forms::Field>] the resolved field tree naming the parameters
+      # @return [String] the help text and the templated link markup
       def self.canonical_link(action, fields)
         paths = Params.paths(fields)
         template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join('&')}"
@@ -60,10 +91,16 @@ module Hecks
 
       # The one enum-shaped parameter (if there is one) rendered as literal,
       # clickable links — no form to fill in for "show me the suspended
-      # ones". Capped at the FIRST closed-set field on purpose: a second one
+      # ones". Capped at the first closed-set field on purpose: a second one
       # would mean a cross product of links, which reads as noise rather
       # than help. A query with more than one is still fully reachable
       # through the filter form below.
+      #
+      # @param action [String] the query's base URL
+      # @param fields [Array<Forms::Field>] the resolved field tree to search for a
+      #   `:select` or `:radio` field
+      # @return [String] one clickable link per option of the first closed-set field
+      #   found; `""` when no field is `:select` or `:radio`
       def self.quick_links(action, fields)
         field = fields.find { |f| %i[select radio].include?(f.kind) }
         return "" unless field
@@ -75,6 +112,14 @@ module Hecks
         %(<div class="example-links">#{links.join}</div>)
       end
 
+      # Renders the GET filter form covering every declared parameter.
+      #
+      # @param action [String] the form's `action` URL
+      # @param fields [Array<Forms::Field>] the resolved field tree to render
+      # @param params [Hash] the request's own query params, pre-filling each field
+      # @param reference_options [Hash{String => Array<Array(String, String)>, nil}] each
+      #   `:reference` field's own dropdown options, as `ReferenceOptions.collect` returns
+      # @return [String] the form markup; `""` when the query declares no parameters
       def self.filter_form(action, fields, params, reference_options)
         return "" if fields.empty?
 
@@ -86,6 +131,10 @@ module Hecks
         HTML
       end
 
+      # Renders a raised error as a dismissable-looking alert banner.
+      #
+      # @param error [StandardError, nil] the error to show
+      # @return [String] the banner markup; `""` when `error` is `nil`
       def self.error_banner(error)
         return "" unless error
 
@@ -93,12 +142,26 @@ module Hecks
           "#{Escape.html(error.message)}</p></div>"
       end
 
+      # Renders the results heading and table, once a request actually supplied
+      # parameters.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose fields shape the table
+      # @param results [Array<Hash>, nil] the query's own answer rows
+      # @param domain [String] the owning chapter's name, for building record links
+      # @return [String] the results section markup; `""` when `results` is `nil`
       def self.results_section(aggregate, results, domain)
         return "" unless results
 
         "<h2>Results (#{results.size})</h2>#{RecordTable.render(aggregate, results, domain: domain)}"
       end
 
+      # Renders a collapsed panel with the query's own parameter list and raw IR JSON.
+      #
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @param fields [Array<Forms::Field>] the resolved field tree, for the parameter list
+      # @return [String] the `<details>` panel markup
       def self.inspect_panel(domain, aggregate, query, fields)
         verb = "#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}"
         paths = Params.paths(fields)