proctolog 0.1.0

data/app/controllers/proctolog/open_pull_requests_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The repository's open pull requests, to pick what to review: where the
+  # desk opens while it has no burst. A press makes the burst for the pick
+  # among the reviewer's own, so nobody writes one to review a pull request.
+  class OpenPullRequestsController < ApplicationController
+    before_action do
+      @repository = Project.current.github_repository or raise Failure, "#{Project.current.root} has no GitHub repository as its origin."
+      @github = Github.new(@repository)
+    end
+
+    # `fresh` reads GitHub again, then comes back to an address a reload can repeat.
+    def index
+      @pick = Pick.new(@github.open_pull_requests(fresh: params.key?(:fresh)), viewer: Github.viewer, unopened: unopened)
+      return redirect_to(open_pull_requests_path) if params.key?(:fresh)
+
+      @bursts, @put_away = Burst.newest_first.partition { !it.put_away? }
+      @put_away_shown = params.key?(:put_away)
+      @read_at = @github.read_at
+    end
+
+    # One pull request, reviewed alone: one open on GitHub, or one nobody
+    # has opened yet, which its burst names by its branch.
+    def alone
+      pull_request = held(params.expect(:id))
+      slug = pull_request.opened? ? "pr-#{pull_request.number}" : "branch-#{pull_request.head.parameterize}"
+      burst = Burst.find_or_start(slug, name: "##{pull_request.number} #{pull_request.title}", pull_requests: [pull_request.listed_as])
+      redirect_to burst_pull_request_path(burst.slug, pull_request.number)
+    end
+
+    # A pull request nobody has opened yet, with the chain under it,
+    # followed down by base branches.
+    def chain
+      top = held(params.expect(:id))
+      burst = Burst.find_or_start("chain-#{top.head.parameterize}", name: "Up to #{top.head}: #{top.title}", tops: [top.listed_as])
+      redirect_to burst_path(burst.slug)
+    end
+
+    # One of GitHub's stacks, whole.
+    def stack
+      number = params.expect(:id).to_i
+      layers = @github.open_pull_requests.select { it.stack == number }.sort_by(&:position)
+      layers.any? or raise Failure, "No open pull request is in stack #{number}."
+      burst = Burst.find_or_start("stack-#{number}", name: "Stack #{number}: #{layers.last.title}", stacks: [number])
+      redirect_to burst_path(burst.slug)
+    end
+
+    private
+
+    def held(id)
+      number = PullRequest.number(id)
+      [*@github.open_pull_requests, *unopened].find { it.number == number } || raise(Failure, "##{id} is neither open nor waiting unopened.")
+    end
+
+    # Those nobody has opened yet: on a branch with no open pull request.
+    def unopened = Unopened.waiting(open: @github.open_pull_requests).map(&:pull_request)
+  end
+end

data/app/controllers/proctolog/pictures_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class PicturesController < ApplicationController
+    rescue_from(Picture::Unavailable) { render plain: it.message, status: :bad_gateway }
+
+    # A picture never changes under its asset id, so the browser keeps it.
+    def show
+      extension = params[:format]
+      return head(:not_found) unless Picture::EXTENSIONS.include?(extension)
+
+      file = Picture.new(params.expect(:asset), extension).file
+      expires_in 1.year, public: true
+      send_file file, type: Mime::Type.lookup_by_extension(extension).to_s, disposition: :inline
+    end
+
+    # Where the halves of a pair differ, for the viewer to outline and go
+    # through, and whether they could be compared at all.
+    def compare
+      pictures = params.expect(:before, :after).map { Picture.new(*it.split(".", 2)) }
+      return head(:not_found) unless pictures.all? { Picture::EXTENSIONS.include?(it.extension) }
+
+      result = Difference.between(*pictures.map(&:file), cache: Project.current.cache)
+      render json: result.to_h.slice(:compared, :same, :sizes, :boxes)
+    end
+  end
+end

data/app/controllers/proctolog/prompts_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The prompt for a fresh session: what would be handed over now; and the
+  # handover `e` asks for, written as a folder where the desk keeps
+  # handovers, with the address of a new session that reads it.
+  class PromptsController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    def show
+      @taken_in = @burst.reports.take_in
+      @handover = @burst.handover(@burst.route, focus:)
+    end
+
+    # The pass is the desk's own, from the choices the page saved before it
+    # asked. `again` takes back what an agent took and never answered.
+    def create
+      route = @burst.route
+      worklist = Rounds.new(@burst, route:, focus:).worklist(batch_id: SecureRandom.uuid, again: params[:again].present?)
+      file = @burst.handover(route, focus:, worklist:).write
+      render json: {file: file.to_s, session: helpers.new_session_address(file), prompt: helpers.session_prompt(file),
+                    requests: worklist.items.size, withAgent: worklist.with_agent.size}
+    end
+
+    # What `create` would write, file by file, and writes nothing.
+    def preview = render(plain: @burst.handover(@burst.route, focus:).to_s)
+  end
+end

data/app/controllers/proctolog/pull_request_scoped.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # For a controller nested under a pull request of a burst: finds the
+  # burst and the pull request's place in its route, and answers by going
+  # back to the pull request's page.
+  module PullRequestScoped
+    extend ActiveSupport::Concern
+
+    included do
+      before_action { @burst = Burst.find(params.expect(:burst_id)) }
+      before_action { @stop = @burst.route.at(PullRequest.number(params.expect(:pull_request_number))) || render(plain: "##{params[:pull_request_number]} is not part of #{@burst.name}.", status: :not_found) }
+    end
+
+    private
+
+    def marks = @marks ||= @burst.marks(@stop.number)
+
+    def back_to_the_page(anchor:) = redirect_to(burst_pull_request_path(@burst, @stop.number, anchor:))
+  end
+end

data/app/controllers/proctolog/pull_requests_controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class PullRequestsController < ApplicationController
+    # One pull request of a burst: where it stands and what moved since the
+    # owner's mark, then its description as GitHub renders it, with the
+    # owner's notes drawn on it and listed beside it. `fresh` reads GitHub
+    # again, then comes back to an address that a reload can repeat.
+    def show
+      @burst = Burst.find(params.expect(:burst_id))
+      @route = @burst.route(fresh: params.key?(:fresh))
+      return redirect_to(burst_pull_request_path(@burst, params.expect(:number))) if params.key?(:fresh)
+
+      @burst.reports.take_in
+      @stop = @route.at(PullRequest.number(params.expect(:number))) or return render(plain: "##{params[:number]} is not part of #{@burst.name}.", status: :not_found)
+      standings = @burst.standings(@route)
+      @standing = standings.fetch(@stop)
+      # Next to review is the next with blocking decisions left: the non-blocking
+      # wait for one gesture, and do not hold up deciding.
+      @next_to_review = focus.round_from(@stop).find { standings.fetch(it).progress.blocking_left.positive? }
+      @since = @burst.since(@stop) if @standing.changed?
+      @scenarios = @burst.scenarios.select { it.pr == @stop.number }
+      @rendering = Rendering.new(@burst.rendering(@stop.number), notes: @standing.marks.notes, pages: pages, linked: @stop.description.linked)
+      @decisions = @burst.decisions(pages:)
+      @boxes = @decisions.boxes_of(@stop)
+      @code = CodeReview.new(@burst, @stop.number).tally
+    end
+
+    private
+
+    # Where each pull request of the burst is, as GitHub says and as the desk says.
+    def pages = @route.to_h { [it.url, burst_pull_request_path(@burst, it.number)] }
+  end
+end

data/app/controllers/proctolog/put_away_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The owner putting a burst away while some of it is still open, as a
+  # finished one is put away, or taking it out again.
+  class PutAwayController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    def create
+      @burst.put_away!
+      redirect_to burst_path(@burst), notice: "Put away."
+    end
+
+    def destroy
+      @burst.take_out!
+      redirect_to burst_path(@burst), notice: "Out again."
+    end
+  end
+end

data/app/controllers/proctolog/recordings_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class RecordingsController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    # Every recording of the burst, a folder at a time: the owner's sitting
+    # first, then the pull requests in number order.
+    def index
+      @folders = Recording.of(@burst).group_by(&:folder).sort_by { |folder, _| [(folder == "sitting") ? 0 : 1, folder.to_i, folder] }
+    end
+
+    # One recording to play, with the owner's notes pinned to its moments.
+    def show
+      @recording = Recording.find(@burst, params.expect(:path)) or return render(plain: "There is no recording at #{params[:path]}.", status: :not_found)
+      @notes = @recording.noted_in(@burst.marks(@recording.folder))
+      @changes = @recording.changes(Recording::Rounds.new(@burst).before(@recording)) if @recording.chapters.any?
+    end
+
+    # The picture a step of a film opens on, for the strip beside it; none
+    # when it cannot be had, and the step's name stands alone.
+    def still
+      recording = Recording.find(@burst, params.expect(:path)) or return head(:not_found)
+      file = recording.still(params.expect(:index).to_i) or return head(:not_found)
+      send_file file, type: "image/png", disposition: :inline
+    end
+  end
+end

data/app/controllers/proctolog/rendered_pieces_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Draws pieces of a description, which the page has only as markdown.
+  class RenderedPiecesController < ApplicationController
+    def create
+      burst = Burst.find(params.expect(:burst_id))
+      render json: {pieces: burst.draw(params.expect(markdown: []))}
+    end
+  end
+end

data/app/controllers/proctolog/review_data_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # What the pages' script needs of the burst's review rounds, built from the
+  # whole burst; with `pr`, that pull request's descriptions too.
+  class ReviewDataController < ApplicationController
+    def show
+      @burst = Burst.find(params.expect(:burst_id))
+      render json: helpers.round_data(@burst, pr: params[:pr]&.then { PullRequest.number(it) })
+    end
+  end
+end

data/app/controllers/proctolog/rules_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A rule the owner made of an answer, edited or withdrawn from the burst
+  # page. The pages' script makes rules; these change the kept choices the
+  # same way, and an open page catches up with them.
+  class RulesController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    def update
+      @burst.rules.edit(params.expect(:id), params.expect(:text))
+      redirect_to burst_path(@burst, anchor: "rules"), notice: "Rule saved."
+    end
+
+    def destroy
+      @burst.rules.withdraw(params.expect(:id))
+      redirect_to burst_path(@burst, anchor: "rules"), notice: "Rule withdrawn."
+    end
+  end
+end

data/app/controllers/proctolog/scenario_notes_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A note on a scenario, and moving it along. It is kept with the marks of
+  # the scenario's pull request, or of the sitting for a step of it.
+  class ScenarioNotesController < ApplicationController
+    include ScenarioScoped
+    include NoteParams
+
+    before_action { @scenario = @burst.scenario(params.expect(:scenario_id)) }
+
+    def create
+      marks.pin(kind: one_of(Note::KINDS, params.expect(:kind)), text: params.expect(:text).strip, place: Note::Scenario.new(name: @scenario.name))
+      back_to_the_page(notice: "Note saved.")
+    end
+
+    def update
+      note = marks.move(params.expect(:id), to: one_of(Note::STATES, params.expect(:state))) or return head(:not_found)
+      back_to_the_page(notice: "The note is #{note.state}.")
+    end
+
+    private
+
+    def marks = @burst.marks(@scenario.marked_on)
+  end
+end

data/app/controllers/proctolog/scenario_scoped.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # For a controller that works on a scenario of a burst and answers by going
+  # back to the page it was asked from, at the scenario: the scenarios page or
+  # a pull request's.
+  module ScenarioScoped
+    extend ActiveSupport::Concern
+
+    included do
+      before_action { @burst = Burst.find(params.expect(:burst_id)) }
+    end
+
+    private
+
+    def back_to_the_page(**flash)
+      page = url_from(request.referer&.sub(/#.*/, "")) || burst_scenarios_path(@burst)
+      redirect_to "#{page}##{@scenario&.to_param}", **flash
+    end
+  end
+end

data/app/controllers/proctolog/scenarios_controller.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class ScenariosController < ApplicationController
+    include ScenarioScoped
+
+    before_action(only: %i[open saw pull]) { @scenario = @burst.scenario(params[:id]) }
+    rescue_from(Server::Error) { back_to_the_page(alert: it.message.truncate(1200)) }
+
+    def index
+      @server = @burst.server
+      @state = @server.state
+      @route = @burst.route
+    end
+
+    # Opens the app in the scenario's state. Every browser comes by an address
+    # of the desk that is good once and sets the cookies, so the session never
+    # shows in an address: your own browser follows it at once, and the other
+    # kinds are started at it.
+    #
+    # Where the app names an `overlay`, the press opens Grouse's overlay there
+    # too, labelled with the scenario, and keeps its session beside it.
+    def open
+      visit = @scenario.visit(@burst.server, overlay: (brief if @burst.server.app.overlay?))
+      keep(visit.overlay)
+      address = entry_url(visit.keep)
+      flash[:alert] = visit.overlay&.missing if visit.overlay&.missing
+      return redirect_to(address, status: :see_other) if @scenario.browser.mine?
+
+      @scenario.browser.launch(address, size: @scenario.window)
+      back_to_the_page(notice: "Opened in a #{@scenario.browser.name} Chrome.")
+    end
+
+    # Brings back what the owner wrote in the scenario's overlays, each note
+    # pinned on the scenario once.
+    def pull
+      back_to_the_page(notice: Overlay.pull(@burst.server, @burst.marks(@scenario.marked_on), @scenario.name).sentence)
+    end
+
+    # What the owner saw, kept with the commit it was seen on.
+    def saw
+      result = params.expect(:result)
+      return head(:unprocessable_content) unless Scenario::RESULTS.value?(result)
+
+      @burst.marks(@scenario.marked_on).saw(@scenario.name, head:, result:)
+      back_to_the_page
+    end
+
+    private
+
+    # The commit the scenario is seen on: its pull request's head, or the sitting's.
+    def head = @scenario.pr ? @burst.route.at(@scenario.pr)&.head_oid : @burst.server.head
+
+    # The scenario as the overlay's strip shows it, with the way back to the
+    # page the press was made on.
+    def brief
+      stop = @scenario.pr && @burst.route.at(@scenario.pr)
+      page = url_from(request.referer&.sub(/#.*/, "")) || burst_scenarios_url(@burst)
+      Overlay::Brief.for(@scenario, burst: @burst, steps: stop ? @scenario.steps_in(stop.description).map(&:text) : [], head:,
+        desk_url: "#{page}##{@scenario.to_param}")
+    end
+
+    def keep(overlay)
+      @burst.marks(@scenario.marked_on).keep_overlay(@scenario.name, Overlay.opening(overlay.session, head:)) if overlay&.session
+    end
+  end
+end

data/app/controllers/proctolog/sitting_servers_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The server a burst's scenarios open the app on: asked after, started,
+  # stopped. A press goes back to the page it was made on, the Scenarios page
+  # or a pull request's; asked for JSON, it answers where the server stands,
+  # so that page can stay where it is.
+  class SittingServersController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+    rescue_from(Server::Error) { answer(alert: it.message.truncate(1200)) }
+
+    def show = render(json: {state: @burst.server.state})
+
+    def create = answer(notice: @burst.server.start)
+
+    def destroy
+      @burst.server.stop
+      answer(notice: "The server was stopped.")
+    end
+
+    private
+
+    def answer(**flash)
+      respond_to do |format|
+        format.html { redirect_back_or_to burst_scenarios_path(@burst), **flash }
+        format.json { render json: {state: @burst.server.state, **flash}, status: flash.key?(:alert) ? :unprocessable_content : :ok }
+      end
+    end
+  end
+end

data/app/controllers/proctolog/waiting_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # What a pull request waits on, outside the burst, in a sentence. An empty
+  # sentence says it waits on nothing.
+  class WaitingController < ApplicationController
+    include PullRequestScoped
+
+    def update
+      marks.wait_on(params[:what].to_s.strip)
+      back_to_the_page(anchor: "standing")
+    end
+  end
+end

data/app/controllers/proctolog/with_decisions.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # What every page that works on the boxes of "Decisions for the owner"
+  # starts from: the burst, and its decisions as GitHub holds them now. A
+  # page that names a box GitHub no longer holds as it was shown goes back to
+  # the list with a sentence.
+  module WithDecisions
+    extend ActiveSupport::Concern
+
+    included do
+      before_action { @burst = Burst.find(params.expect(:burst_id)) }
+      rescue_from(Decisions::Changed) { redirect_to(decisions_path_for(params[:pull_request_number]), alert: it.message) }
+    end
+
+    private
+
+    def decisions = @decisions ||= @burst.decisions(pages:)
+
+    # Where each pull request of the burst is, as GitHub says and as the desk says.
+    def pages = @burst.route.to_h { [it.url, burst_pull_request_path(@burst, it.number)] }
+
+    def number = PullRequest.number(params.expect(:pull_request_number))
+
+    # The list as the page that sent the request had it, at a pull request.
+    def decisions_path_for(number) = burst_decisions_path(@burst, show: params[:show], anchor: ("pr-#{number}" if number.present?))
+  end
+end

data/app/helpers/proctolog/bursts_helper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Proctolog
+  module BurstsHelper
+    # Which of the two a mark will later be compared against moved last.
+    def last_change(pull_request)
+      what, at = {"description" => pull_request.described_at, "code" => pull_request.committed_at}.max_by(&:last)
+      tag.time("#{what}, #{time_ago_in_words(at)} ago", datetime: at.iso8601, title: at.localtime.strftime("%-d %b %H:%M"))
+    end
+
+    def open_threads(pull_request)
+      " · #{pluralize(pull_request.open_threads, "review thread")} open" if pull_request.open_threads.positive?
+    end
+
+    # "Stack #1055, 21 from the bottom up", "A chain of 2 on #1062, from the
+    # bottom up", "Standing alone". A stack placed from the membership kept
+    # beside the marks, when GitHub could not say, is said to be as last read.
+    def part_heading(part, route)
+      stops = route.stops_of(part)
+      if part.alone? then "Standing alone"
+      elsif part.stack? then "Stack ##{part.id}#{" as last read" unless route.stacks_known?}, #{stops.size} from the bottom up"
+      else "A chain of #{stops.size}#{" on ##{stops.first.on}" if stops.first.on}, from the bottom up"
+      end
+    end
+
+    # The heading over each kind of disagreement between a burst's file and GitHub.
+    DISAGREEMENTS = {off_the_burst: "On a member's branch, not in this burst", empty_stack: "Listed stacks with nothing open",
+                     filed_twice: "Filed twice", held_elsewhere: "Also in another burst"}.freeze
+
+    def disagreement_heading(cause) = DISAGREEMENTS.fetch(cause)
+
+    # What the owner chose on a decision of a pull request that left.
+    CHOSEN = {"leave" => "Left as is", "question" => "Question", "change" => "Change", "later" => "Left for later"}.freeze
+
+    def entry_line(entry)
+      said = entry.draft ? "Draft" : CHOSEN.fetch(entry.kind, entry.kind.to_s)
+      safe_join([tag.strong("#{said}:"), entry.lead, (tag.span("— #{entry.text}", class: "text") if entry.text.present?)].compact, " ")
+    end
+
+    # What a rule's state means for the next handover.
+    RULE_STATES = {written: "goes in the next handover", sent: "handed over; the agent's answer is awaited",
+                   answered: "answered: yours to confirm under Returned work", confirmed: "recorded, and confirmed", withdrawn: "withdrawn"}.freeze
+
+    # A rule's line once the cursor is on it: what it was made from, what its
+    # state means, and the line it replaces until the replacement is handed over.
+    def rule_facts(rule)
+      [("made from #{rule.from.map { "##{it.pr} “#{it.lead}”" }.to_sentence}" if rule.from.any?),
+        RULE_STATES.fetch(rule.state),
+        ("replaces “#{rule.replaces}”" if rule.replaces && rule.state == :written)].compact.join(" · ")
+    end
+  end
+end

data/app/helpers/proctolog/decisions_helper.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Proctolog
+  module DecisionsHelper
+    # Every decision of the burst as the pages' script takes it, in JSON. It
+    # holds what GitHub says and nothing of the owner's marks, so it is built
+    # once for a reading: building it reads every description again. It is of
+    # the whole burst whatever a page is focused on, so a choice outside the
+    # focus is never taken for one whose decision is gone.
+    # What the inventory holds changed with the desk: a page built from an
+    # older one would read its decisions wrong.
+    INVENTORY = 3
+
+    # The pictures' files and pixel signatures are looked up at each page,
+    # not kept with the rest: a picture fetched since the reading is known.
+    def decision_inventory(burst)
+      Rails.cache.fetch([:inventory, INVENTORY, burst.slug, burst.read_at.to_f]) { burst.decisions.boxes.map { draft_decision(it) } }
+        .map { |decision| decision.merge(pictures: decision[:pictures].map { picture_now(it) }) }.to_json
+    end
+
+    def draft_decision(box)
+      {id: box.to_param, pr: box.stop.number, title: box.stop.title, url: box.stop.url, branch: box.stop.pull_request.head,
+       head: box.stop.head_oid, description: box.stop.description.digest, position: box.position, lead: box.lead,
+       text: box.decision.text, key: box.decision.key, ticked: box.decision.ticked, protected: @burst.refusal(box.stop.number).present?,
+       grade: box.decision.grade, theme: box.decision.theme_name, pictures: box.decision.pictures.map(&:to_h)}
+    end
+
+    # A picture a decision rests on, with its file on this Mac and its pixels'
+    # signature; both nil while it is not here, its signature while
+    # ImageMagick cannot read it.
+    def picture_now(picture) = picture.merge(file: Picture.on_disk(picture[:asset])&.basename&.to_s, signature: Picture.signature(picture[:asset]))
+
+    # "3 blocking · 12 non-blocking". More blocking decisions than one owner
+    # should be asked at once says so in words: "8 blocking · over five".
+    def grades_of(decisions)
+      blocking = decisions.count(&:blocking?)
+      [("#{blocking} blocking" if blocking.positive?), ("over five" if blocking > Check::MOST_BLOCKING),
+        ("#{decisions.size - blocking} non-blocking" if decisions.size > blocking)].compact.join(" · ")
+    end
+
+    # A grade as the end of a pull request's decisions heads it, and what it
+    # asks of the owner, in a sentence under its name.
+    Grade = Data.define(:name, :meaning)
+    GRADES = {
+      blocking: Grade.new("Blocking", "Each needs your answer before the work goes on."),
+      non_blocking: Grade.new("Non-blocking", "Each has a sensible default: left as is, what the agent built stands.")
+    }.freeze
+
+    def grade_named(grade) = GRADES.fetch(grade)
+
+    # Why leaving every non-blocking decision at once passes over this one,
+    # as the desk knows it: the page adds a draft of its own.
+    def held_by(box)
+      [("starred" if box.starred), ("named in the burst file" if box.named.any?), ("answered" if box.answers.any?), ("asked" if box.asked.any?)].compact
+    end
+
+    def decision_html(box, burst)
+      Nokogiri::HTML5.fragment(box.html).tap do |html|
+        html.css('a[href^="#screenshot-"]').each do |link|
+          link["href"] = burst_pull_request_path(burst, box.stop.number) + link["href"]
+        end
+      end.to_html
+    end
+
+    # The ways to look at the boxes, each with how many it lists.
+    def filter_links(burst, decisions, current)
+      safe_join(Decisions::FILTERS.map do |filter, name|
+        link_to(safe_join([name, tag.span(number_with_delimiter(decisions.count(filter)), class: "count")], " "),
+          burst_decisions_path(burst, show: filter), data: {filter:}, aria: {current: ("page" if filter == current)})
+      end)
+    end
+
+    def filter_name(filter) = Decisions::FILTERS.fetch(filter.to_s)
+
+    # "22 open, 2 ticked elsewhere": what a pull request's boxes are in, all of them.
+    def tally_of(decisions, stop)
+      decisions.tally(stop).map { |state, count| "#{number_with_delimiter(count)} #{filter_name(state).downcase}" }.to_sentence
+    end
+
+    # What a box says of itself beyond being open: where it stands, and what
+    # else says it needs the owner. Nothing, for a box that is simply open.
+    def status_of(box)
+      parts = [("Starred by you" if box.starred), ("Named by #{named_by(box.named)}" if box.named.any?)]
+      parts.unshift(tag.span(filter_name(box.state), class: "state")) unless box.state == :open
+      safe_join(parts.compact, " · ")
+    end
+
+    def named_by(entries) = entries.filter_map(&:by).uniq.to_sentence.presence || "the burst file"
+
+    # The box's place on its pull request's page, which numbers its boxes.
+    def box_on_its_page(burst, box) = burst_pull_request_path(burst, box.stop.number, anchor: "decision-#{box.position}")
+
+    # The star, which comes back to the page it was pressed on, at `back`.
+    def star_button(burst, box, back)
+      button_to(box.starred ? "★ Starred" : "☆ Star", burst_pull_request_decision_path(burst, box.stop.number, box.position),
+        method: :patch, params: {lead: box.lead, starred: box.starred ? 0 : 1, return: back}, class: "quiet", form_class: "star", aria: {pressed: box.starred.to_s})
+    end
+
+    # What a button under a box asks: the kind of note it writes, as a word of the owner's.
+    def respond_button(label, kind) = tag.button(label, type: "button", class: "quiet", data: {respond: kind})
+  end
+end