raindown 0.7.0 → 0.8.0

data/lib/raindown/document.rb

@@ -20,7 +20,8 @@ module Raindown
     # It spans line to end_line, its end tag, or the last line of a bare block.
     # Body is the lines inside it, between it and its end tag, like an endpoint's request and response.
     # Output is the lines Raindown writes back, like a node's Markdown or an endpoint's response, and is nil
-    # when nothing's written yet. A self-closing directive like <{ :toc }> only renders, so it never writes.
+    # when nothing's written yet. One in Antlers' delimiters, like <{ toc: }> or <{ :toc }>, only renders, so it never
+    # writes.
     Directive = Data.define(:name, :args, :line, :end_line, :body, :output, :writes) do
       def endpoint? = name == 'endpoint'
     end
@@ -28,17 +29,17 @@ module Raindown
     # Inline nodes whose text a reader sees, like code spans, as opposed to inline HTML tags.
     TEXT_NODES = %i[text code].freeze
     BREAK_NODES = %i[softbreak linebreak].freeze
-    ENDPOINT_END_TAG = /\A {0,3}<\{\s*:endpoint\s*\}>[ \t]*$/
-    END_TAG = /\A {0,3}<\{\s*:[\w:]+\s*\}>[ \t]*$/
+    END_TAG = /\A {0,3}(?:<\{\s*:[\w:]+\s*\}>|<!--\s*:[\w:]+\s*-->)[ \t]*$/
 
     def self.parse(markdown, bare: false)
       new(markdown:, bare:)
     end
 
-    # Raindown files read bare directives, as do Markdown files with "raindown: true" front matter.
+    # Raindown files read bare directives, as do Markdown files with "raindown: true" front matter, or any file when
+    # they're allowed, like with --bare.
     # A project's own nodes are only directives once they're loaded, like with Nodes.load(path), the same as when the file renders.
-    def self.read(path)
-      new(markdown: File.read(path, encoding: Encoding::UTF_8), bare: BareDirectives.file?(path))
+    def self.read(path, bare: false)
+      new(markdown: File.read(path, encoding: Encoding::UTF_8), bare: bare || BareDirectives.file?(path))
     end
 
     def initialize(markdown:, bare: false)
@@ -83,7 +84,7 @@ module Raindown
     def node_directives
       NodeBlocks.spans(@lines, bare: @bare).map do |span|
         output = trimmed(span[:open] + 1, span[:close] ? span[:close] - 1 : span[:last])
-        directive(span[:name], span[:args], span[:open]..span[:last], output:, writes: !span[:self_closing])
+        directive(span[:name], span[:args], span[:open]..span[:last], output:, writes: span[:writes])
       end
     end
 
@@ -94,8 +95,8 @@ module Raindown
       while index < @lines.length
         if (code = CodeBlocks.at(@lines, index))
           index = code[:close]
-        elsif (args = endpoint_args(@lines[index]))
-          directives << endpoint(index, args)
+        elsif (found = endpoint_args(@lines[index]))
+          directives << endpoint(index, *found)
           index = directives.last.end_line - 1
         end
 
@@ -105,20 +106,25 @@ module Raindown
       directives
     end
 
+    # The endpoint's arguments, in any of the ways it can be written, and whether it writes its response back, which
+    # it does unless it's in Antlers' delimiters, or nil when the line isn't an endpoint.
     def endpoint_args(line)
-      line = BareDirectives.wrap(line) || line if @bare
-      line[EndpointRunner::DIRECTIVE, 1]&.strip
+      return [line[EndpointRunner::DIRECTIVE, 1].strip, false] if line.match?(EndpointRunner::DIRECTIVE)
+      return [line[EndpointRunner::COMMENT, 1].strip, true] if line.match?(EndpointRunner::COMMENT)
+
+      bare = BareDirectives.wrap(line)&.[](EndpointRunner::DIRECTIVE, 1) if @bare
+      [bare.strip, true] if bare
     end
 
     # The response and the date it was fetched are the output, while the curl snippet above them is the author's.
-    def endpoint(open, args)
+    def endpoint(open, args, writes)
       curl, response = CodeBlocks.endpoint(@lines, open + 1)
       output = response && (response[:open]..(fetched?(response[:close] + 1) ? response[:close] + 1 : response[:close]))
       last = output&.end || curl&.fetch(:close) || open
       # A bare endpoint, which isn't delimited, ends after its blocks.
-      last = end_tag(after: last) || last if @lines[open].match?(EndpointRunner::DIRECTIVE)
+      last = end_tag(after: last) || last unless Directives.bare?(@lines[open])
 
-      directive('endpoint', args, open..last, output:, writes: true)
+      directive('endpoint', args, open..last, output:, writes:)
     end
 
     def fetched?(index)
@@ -128,7 +134,7 @@ module Raindown
     # The end tag after the endpoint's blocks, with only blank lines between.
     def end_tag(after:)
       index = CodeBlocks.skip_blank_lines(@lines, after + 1)
-      index if @lines[index]&.match?(ENDPOINT_END_TAG)
+      index if @lines[index]&.match?(EndpointRunner::END_TAG)
     end
 
     # Lines from first to last with the blank lines around them left out, or nil when there are none.

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -6,11 +6,12 @@ require_relative '../code_blocks'
 require_relative 'curl'
 
 module Raindown
-  # Runs the curl block under an endpoint directive and writes the response in the code block below it,
+  # Runs the curl block under an endpoint directive in a comment, or a bare one, and writes the response in the code
+  # block below it,
   # followed by the date it was fetched.
   # Only runs when that block is missing or empty, and the directive has :x/:execute or --execute is passed.
   # Or with only: and a directive's line index, runs just that endpoint, replacing any response it has.
-  #   <{ endpoint: :x }>
+  #   <!-- endpoint: :x -->
   #   ```sh
   #   curl https://api.example.com
   #   ```
@@ -18,9 +19,14 @@ module Raindown
   #   { "id": 1 }
   #   ```
   #   <!-- raindown:fetched 2026-10-14 -->
-  #   <{ :endpoint }>
+  #   <!-- :endpoint -->
+  # One in Antlers' delimiters, <{ endpoint: }>, only renders, so it's never run.
   class EndpointRunner
+    # An endpoint's directive in Antlers' delimiters, which only renders, or in a comment, which writes its response back,
+    # and the end tag of either.
     DIRECTIVE = /\A {0,3}<\{\s*endpoint:(.*?)\}>[ \t]*$/
+    COMMENT = /\A {0,3}<!--\s*endpoint:(.*?)-->[ \t]*$/
+    END_TAG = /\A {0,3}(?:<\{\s*:endpoint\s*\}>|<!--\s*:endpoint\s*-->)[ \t]*$/
     EXECUTE_ARGS = %w[:x :execute].freeze
     # The date a response was fetched, on the line after it.
     FETCHED = /\A {0,3}<!-- raindown:fetched [^\n]*? -->[ \t]*$/
@@ -54,9 +60,11 @@ module Raindown
 
     private
 
+    # The arguments of an endpoint that writes back: in a comment, or bare.
     def directive_args(line)
-      line = BareDirectives.wrap(line) || line if @bare
-      line[DIRECTIVE, 1]&.split
+      args = line[COMMENT, 1]
+      args ||= BareDirectives.wrap(line)&.[](DIRECTIVE, 1) if @bare
+      args&.split
     end
 
     # Returns the index of the last line it handled.

data/lib/raindown/node_blocks.rb

@@ -10,20 +10,21 @@ require_relative 'variables'
 
 module Raindown
   # Finds node blocks in a file's lines: a node's directive and the Markdown it wrote below it.
-  # With delimiters the block ends with the node's end tag, and without them at the next blank line:
-  #   <{ Changelog: limit=3 }>          Changelog: limit=3
-  #                                     - **1.2.0** Bare directives
+  # In comments the block ends with the node's end tag, and bare at the next blank line, and both write back:
+  #   <!-- Changelog: limit=3 -->        Changelog: limit=3
+  #                                      - **1.2.0** Bare directives
   #   - **1.2.0** Bare directives
   #
-  #   <{ :Changelog }>
-  # A self-closing <{ :Changelog }> or bare :Changelog that doesn't end a block renders the node without writing it.
-  # toc: and files: are Raindown's own nodes. A name only starts a block when it's a loaded node,
-  # so other text like "Note:" is left alone.
+  #   <!-- :Changelog -->
+  # In Antlers' delimiters, <{ Changelog: }> to <{ :Changelog }>, or a self-closing <{ :Changelog }> or bare
+  # :Changelog, it renders the node without writing it. toc: and files: are Raindown's own nodes. A name only starts
+  # a block when it's a loaded node, so other text like "Note:" is left alone.
   module NodeBlocks
     class MissingEndTag < StandardError; end
 
     NAME = "(?:#{Nodes::BUILT_INS.keys.join('|')}|[A-Z]\\w*(?:::[A-Z]\\w*)*)".freeze
     OPEN = /\A( {0,3})<\{\s*(#{NAME}):(?:\s+(.*?))?\s*\}>[ \t]*$/
+    COMMENT_OPEN = /\A( {0,3})<!--\s*(#{NAME}):(?:\s+(.*?))?\s*-->[ \t]*$/
     BARE_OPEN = /\A( {0,3})(#{NAME}):(?:[ \t]+(.*?))?[ \t]*$/
     SELF_CLOSING = /\A( {0,3})<\{\s*:(#{NAME})(?:\s+(.*?))?\s*\}>[ \t]*$/
     BARE_SELF_CLOSING = /\A( {0,3}):(#{NAME})(?:[ \t]+(.*?))?[ \t]*$/
@@ -35,8 +36,9 @@ module Raindown
 
     module_function
 
-    # Each block outside code and front matter as { open:, close:, last:, node: }, where close is nil for a bare block.
-    # A self-closing node is a block of one line with self_closing: true.
+    # Each block outside code and front matter as { open:, close:, last:, writes:, node: }, where close is nil for a
+    # bare block, and writes is whether its output's written into the file. A self-closing node is a block of one line
+    # with self_closing: true.
     def find(lines, front_matter: {}, bare: false)
       variables = Variables.new(front_matter)
 
@@ -99,15 +101,17 @@ module Raindown
 
       span = { name: found[2], class: klass, args: found[3].to_s }
       case pattern
-      when :open then end_tag(lines, index, found[2]).then { |close| { open: index, close:, last: close, **span } }
-      when :bare_open then { **bare_block(lines, index), **span }
-      else { open: index, close: nil, last: index, self_closing: true, **span }
+      when :open, :comment_open
+        end_tag(lines, index, found[2], comment: pattern == :comment_open)
+          .then { |close| { open: index, close:, last: close, writes: pattern == :comment_open, **span } }
+      when :bare_open then { **bare_block(lines, index), writes: true, **span }
+      else { open: index, close: nil, last: index, writes: false, self_closing: true, **span }
       end
     end
 
     # The directive on the line and which kind it is, or nil.
     def directive(line, bare:)
-      patterns = { open: OPEN, self_closing: SELF_CLOSING }
+      patterns = { open: OPEN, comment_open: COMMENT_OPEN, self_closing: SELF_CLOSING }
       patterns.merge!(bare_open: BARE_OPEN, bare_self_closing: BARE_SELF_CLOSING) if bare
 
       patterns.each do |pattern, regexp|
@@ -126,10 +130,12 @@ module Raindown
       { open:, close: nil, last: }
     end
 
-    def end_tag(lines, open, name)
-      tag = /\A {0,3}<\{\s*:#{Regexp.escape(name)}\s*\}>[ \t]*$/
+    # The end tag written the same way as the directive: in a comment, or in Antlers' delimiters.
+    def end_tag(lines, open, name, comment:)
+      first, last = comment ? Directives::COMMENT : Directives::DELIMITERS
+      tag = /\A {0,3}#{Regexp.escape(first)}\s*:#{Regexp.escape(name)}\s*#{Regexp.escape(last)}[ \t]*$/
       close = (open + 1...lines.length).find { |index| lines[index].match?(tag) }
-      raise MissingEndTag, "<{ #{name}: }> on line #{open + 1} needs <{ :#{name} }>" unless close
+      raise MissingEndTag, "#{first} #{name}: #{last} on line #{open + 1} needs #{first} :#{name} #{last}" unless close
 
       close
     end

data/lib/raindown/node_injector.rb

@@ -6,8 +6,8 @@ require_relative 'front_matter'
 require_relative 'node_blocks'
 
 module Raindown
-  # Writes each node block's Markdown below its directive, replacing what it wrote before.
-  # Self-closing nodes only render, so they're left alone.
+  # Writes each node block's Markdown below its directive, replacing what it wrote before, when it's in comments or
+  # bare. Ones in Antlers' delimiters, and self-closing ones, only render, so they're left alone.
   class NodeInjector
     class BlankLine < StandardError; end
 
@@ -25,7 +25,7 @@ module Raindown
     def call
       lines = @content.lines
       blocks = NodeBlocks.find(lines, front_matter: FrontMatter.parse(@content).first, bare: @bare)
-                         .reject { |block| block[:self_closing] }
+                         .select { |block| block[:writes] }
       return @content if blocks.empty?
 
       blocks.reverse_each { |block| lines[block[:open]..block[:last]] = block_lines(lines, block) }
@@ -42,19 +42,16 @@ module Raindown
       delimited(lines, block, written)
     end
 
-    # The directive, what the node wrote and the end tag, each separated by a blank line.
-    def delimited(lines, block, written)
-      result = [line(lines[block[:open]])]
-      result.push("\n", *written) unless written.empty?
-      result.push("\n", line(lines[block[:close]]))
-    end
+    # The directive, what the node wrote and the end tag, straight after each other, as a comment on its own line ends
+    # at its -->, so what's written below it, like a list, is its own block.
+    def delimited(lines, block, written) = [line(lines[block[:open]]), *written, line(lines[block[:close]])]
 
     # A bare block ends at the next blank line, so what it writes can't have one.
     def bare(written, block)
       return written unless written.any? { |line| line.strip.empty? }
 
       name = block[:node].class.name
-      raise BlankLine, "#{name} writes blank lines, so it needs <{ #{name}: }> and <{ :#{name} }> around it"
+      raise BlankLine, "#{name} writes blank lines, so it needs <!-- #{name}: --> and <!-- :#{name} --> around it"
     end
 
     def line(line)

data/lib/raindown/pages.rb

@@ -33,7 +33,7 @@ module Raindown
 
     attr_reader :root
 
-    # Render options, like hide_directives: true, are for rendering each listed file's content.
+    # Render options, like highlight_code: false, are for rendering each listed file's content.
     def initialize(metadata:, root:, render_options: {})
       @root = root
       @render_options = render_options

data/lib/raindown/pre_renderer.rb

@@ -4,6 +4,7 @@ require 'antlers'
 require_relative '../elements'
 require_relative 'bare_directives'
 require_relative 'code'
+require_relative 'code_blocks'
 require_relative 'front_matter'
 
 module Raindown
@@ -16,11 +17,14 @@ module Raindown
     BLOCK_DIRECTIVES = %w[for if list].freeze
     # A for, if or list directive alone on its line, which leaves no line behind, so a loop's list items stay together.
     BLOCK_LINE = /^[ \t]*(<\{\s*:?(?:#{BLOCK_DIRECTIVES.join('|')})\b[^}]*\}>)[ \t]*\n/
+    # An endpoint's directive or end tag in a comment, which renders as it would in Antlers' delimiters.
+    ENDPOINT_COMMENT = /\A( {0,3})<!--\s*(endpoint:.*?|:endpoint)\s*-->/
 
     module_function
 
     def render(markdown, variables:, metadata: {}, bare: false)
       markdown = BareDirectives.expand(markdown) if bare
+      markdown = delimited_endpoints(markdown) if markdown.include?('<!--')
       return markdown unless markdown.include?('{')
 
       markdown = Code.hide_braces(markdown.dup.force_encoding('UTF-8'))
@@ -28,6 +32,20 @@ module Raindown
       "#{markdown.delete_suffix(body)}#{render_body(body, variables, metadata)}"
     end
 
+    # The endpoints in comments in Antlers' delimiters, which the template pass renders, leaving code as it is.
+    def delimited_endpoints(markdown)
+      lines = markdown.lines
+      index = 0
+
+      while index < lines.length
+        code = CodeBlocks.at(lines, index)
+        lines[index] = lines[index].sub(ENDPOINT_COMMENT) { "#{::Regexp.last_match(1)}<{ #{::Regexp.last_match(2)} }>" } unless code
+        index = code ? code[:close] + 1 : index + 1
+      end
+
+      lines.join
+    end
+
     def render_body(body, variables, metadata)
       template = body.gsub(BLOCK_LINE, '\1')
       return body unless template.include?('{')

data/lib/raindown/tui/blueprints/blueprints_renderer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'tracing'
+require_relative '../renderers/renderer'
+require_relative '../search_box'
+
+module Raindown
+  module TUI
+    # The blueprints from Claude Code's replies, right of the files, below the keywords they're filtered by, in the border,
+    # which opens the filter, like Teleport, over it, listing those that match: when it was saved and its kind, and which one of how
+    # many, then the blueprint, cut to fit the pane:
+    #    ─────┌─────────────────── Filter ──────────────────┐───
+    #         │ / weather▏                                  │
+    #       ╭─│ Weather Report Light rain   2026-10-30 03:14 │
+    #       │ └─────────────────────────────────────────────┘
+    # Each is traced to its code: it's cornflower blue, the selected box is highlighted, and the code it names is below:
+    #     ╭──────────────╮   ╭──────────────╮
+    #     │ Watcher.listen│  │ Workers       │
+    #     ╰──────────────╯   ╰──────────────╯
+    #    ╭─ lib/raindown/watcher/changes.rb:17 · Watcher#listen ─────────────╮
+    #    │ def self.listen(directory, &)                                      │
+    #    ╰────────────────────────────────────────────────────────────────────╯
+    class BlueprintsRenderer < Renderer
+      include Tracing
+
+      BUTTONS = [['Tab', 'Pane', :tab], ['f', 'Filter', :filter], ['↑↓←→', 'Box', nil], ['Space', 'Code', :toggle],
+                 ['Enter', 'More', :expand], ['e', 'Edit', :edit], ['/', 'Search', :search], ['q', 'Quit', :quit]].freeze
+
+      def buttons = BUTTONS
+
+      def page = 'Blueprints'
+
+      # The keywords the blueprints are filtered by, in the middle of the line above the panes, which opens the filter,
+      # whose box's top is drawn over it while it's open.
+      def spacer
+        return title_line unless view.typing?
+
+        with_filter.first
+      end
+
+      # The blueprint, with the rest of the filter over it while it's open.
+      def lines
+        return shown_lines unless view.typing?
+
+        with_filter.drop(1)
+      end
+
+      private
+
+      def view = navigator.view
+
+      def title_line
+        title = " #{filtered_by} ▾ "
+        title_width = display_width(title)
+        left = [(width - title_width) / 2, 0].max
+        padded([segment('', :blank, width: left), segment(title, :divider, width: title_width, event: filter_click),
+                segment('', :blank, width: [width - left - title_width, 0].max)])
+      end
+
+      # The title line and the blueprint, with the filter drawn over them from the title line, once a frame.
+      def with_filter = @with_filter ||= SearchBox.new(view, width:, title: 'Filter', pane:, top: 0).apply([title_line, *shown_lines])
+
+      def shown_lines
+        return traced_lines if view.selected
+        return blank(" No blueprints match #{filtered_by}.") unless view.query.to_s.empty?
+
+        blank(" No blueprints yet. #{saving}")
+      end
+
+      def filtered_by
+        return 'All' if view.query.to_s.strip.empty?
+
+        "“#{view.query.strip}”"
+      end
+
+      # The click on the title, which keeps the blueprint shown.
+      def filter_click = Click.new(pane:, index: view.cursor, action: :filter)
+
+      # When it was saved and its kind, then which one it is of how many, at the right.
+      def about(blueprint)
+        saved = " #{blueprint.where}"
+        place = "#{view.cursor + 1} of #{view.blueprints.length} "
+        [segment(saved, :body, width: [width - display_width(place), 0].max), segment(place, :body, width: display_width(place))]
+      end
+
+      def saving = "Claude Code's are saved to #{Blueprints::FILE} by `raindown blueprints`."
+
+      def blank(message)
+        [[segment(message, :info)], *Array.new([height - 1, 0].max) { [segment('', :blank)] }]
+      end
+    end
+  end
+end

data/lib/raindown/tui/blueprints/blueprints_view.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative '../code_box'
+require_relative '../events'
+require_relative '../../blueprints'
+require_relative 'traced_code'
+require_relative 'canvas'
+require_relative 'code_comments'
+require_relative 'filter'
+
+module Raindown
+  module TUI
+    # The blueprints from Claude Code's replies, in the project's .raindown/blueprints.md, newest first, then those in its
+    # code's comments, one at a time, of
+    # those its Filter's keywords match, each traced to its code: the arrows move between the boxes drawn in one, or a
+    # click on one, the code each box names shows below, Space or another click moving on to
+    # the next it names, Enter showing more of it, and E opens it, or the blueprint when the box names none.
+    # The file's read again when it changes, like when a reply's saved more, showing the newest then.
+    class BlueprintsView
+      include Canvas
+      include TracedCode
+      include ShownCode
+      include Filter
+
+      # Left and right move between the boxes drawn in a blueprint, in reading order, and up and down to the nearest box
+      # above or below, while up and down move between the filter's matches.
+      BOX_MOVES = { left: -1, right: 1 }.freeze
+      MOVES = { up: -1, down: 1 }.freeze
+      BOX_ROWS = { up: :above?, down: :below? }.freeze
+      # Space moves on to the next code the selected box names, Enter or clicking its more lines shows them, and E opens it.
+      ACTIONS = { toggle: :next_code, enter: :toggle_expanded, expand: :toggle_expanded, edit: :edit }.freeze
+
+      attr_reader :cursor
+
+      def initialize(root:)
+        @root = root
+        @path = File.join(root, Blueprints::FILE)
+        @all = []
+        @cursor = 0
+        select_box(0)
+      end
+
+      def renderer = BlueprintsRenderer
+      def target = self
+      def path = nil
+      def pace(_hovered) = :active
+
+      def status(_navigator)
+        commented = @all.count { it.time.nil? }
+        [:info, "#{count(@all.length - commented, 'blueprint')} from Claude Code, in #{Blueprints::FILE}, and #{commented} in comments"]
+      end
+
+      # Whether there are any blueprints yet, saved or in the code's comments, which are looked for once until it's loaded.
+      def any? = File.exist?(@path) || commented.any?
+
+      # Whether the file's changed since it was read, so it's read again on the next tick.
+      def changed? = mtime != @read_at
+
+      def load
+        @read_at = mtime
+        newest = @all.first&.time
+        @commented = nil
+        @all = Blueprints.read(@root) + commented
+        self.cursor = 0 unless @all.first&.time == newest
+        self.cursor = @cursor
+      end
+
+      def selected = blueprints[@cursor]
+
+      # Another blueprint's shown from its first box, while the same one keeps its box and canvas, like when it's clicked.
+      def cursor=(index)
+        shown = selected
+        @cursor = index.clamp(0, [blueprints.length - 1, 0].max)
+        return if selected == shown
+
+        select_box(0)
+        follow(from_start: true)
+      end
+
+      # The selected box, of those drawn in the selected blueprint, or nil when it has none.
+      def box = (@box.to_i.clamp(0, boxes.length - 1) if boxes.any?)
+
+      # Every key but Tab to the files, or left from the first box, while the filter's closed.
+      def next_step?(key) = !%i[tab tick].include?(key) && !(key == :left && box.to_i.zero? && !typing?)
+
+      # The selected blueprint's characters by the columns they're shown in, with its boxes' sides straightened, and the
+      # boxes drawn in it, found again when another's selected.
+      def drawing
+        @drawing = [selected, Blueprints.tidied(Blueprints.columns(selected&.lines || []), boxes)] unless @drawing&.first == selected
+        @drawing.last
+      end
+
+      def boxes
+        @boxes = [selected, Blueprints.boxes(selected&.lines || [])] unless @boxes&.first == selected
+        @boxes.last
+      end
+
+      def next_step(key)
+        return filter_step(key) if typing?
+        return open_filter if %i[feelings filter].include?(key)
+        return clicked(key) unless key.is_a?(Symbol)
+        return move_box(BOX_MOVES[key]) if BOX_MOVES.key?(key)
+        return move_row(BOX_ROWS[key]) if BOX_ROWS.key?(key)
+        return scroll(*SCROLLS[key]) if SCROLLS.key?(key)
+
+        send(ACTIONS[key]) if ACTIONS.key?(key)
+      end
+
+      private
+
+      # The selected box's code, or the blueprint when the box names none.
+      def edit
+        return unless selected
+
+        method = code
+        return Edit.new(path: method.path, line: method.line) if method
+
+        Edit.new(path: File.join(@root, selected.path), line: selected.line)
+      end
+
+      # A click on a box drawn in the blueprint, which moves on to the next code it names when it's already selected.
+      def clicked(action)
+        return next_code if boxes.index(action) == box
+
+        select_box(boxes.index(action))
+      end
+
+      def move_box(by)
+        select_box((box + by).clamp(0, boxes.length - 1)) if box
+      end
+
+      # The nearest box above or below the selected one, if there's one that way.
+      def move_row(way)
+        from = boxes[box] if box
+        nearest = boxes.select { from && it.public_send(way, from) }.min_by { it.distance(from) }
+        select_box(boxes.index(nearest)) if nearest
+      end
+
+      def count(number, noun) = "#{number} #{number == 1 ? noun : "#{noun}s"}"
+
+      def mtime = File.exist?(@path) ? File.mtime(@path) : nil
+
+      def commented = @commented ||= CodeComments.blueprints(@root)
+    end
+  end
+end

data/lib/raindown/tui/blueprints/canvas.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # A blueprint's drawing seen through the canvas, a window of a fixed size, from its offset: the columns and rows of
+    # the drawing off its left and top. The canvas follows the selected box, bringing it into view, until it's scrolled,
+    # with Shift and the arrows or by dragging the mouse, and follows again when another box is selected.
+    module Canvas
+      # Shift and an arrow scroll the canvas by columns across, or by rows up and down, like the arrows' own steps.
+      SCROLLS = { scroll_left: [-4, 0], scroll_right: [4, 0], scroll_up: [0, -1], scroll_down: [0, 1] }.freeze
+
+      # The offset for a canvas of the width and height, with the selected box in view while it's followed, and the
+      # drawing no further off than it can be while still filling the canvas.
+      def canvas(width, height)
+        column, row = @offset || [0, 0]
+        column, row = into_view(column, row, width, height) if @following && box
+        @offset = [column.clamp(0, [drawing_width - width, 0].max), row.clamp(0, [drawing_height - height, 0].max)]
+      end
+
+      # Whether there's more of the drawing past the canvas, to the left, right, top and bottom.
+      def beyond(width, height)
+        column, row = @offset
+        { left: column.positive?, right: drawing_width > column + width, up: row.positive?, down: drawing_height > row + height }
+      end
+
+      # Dragging the drawing moves it with the mouse, so the canvas scrolls the other way.
+      def drag(drag)
+        scroll(-drag.columns, -drag.rows)
+      end
+
+      private
+
+      def scroll(columns, rows)
+        column, row = @offset || [0, 0]
+        @offset = [[column + columns, 0].max, [row + rows, 0].max]
+        @following = false
+        nil
+      end
+
+      # Shown from its first column and row, following the selected box, like when another blueprint's selected.
+      def follow(from_start: false)
+        @offset = [0, 0] if from_start
+        @following = true
+      end
+
+      # The offset moved as little as it can for the box to be in view, or its top left when it's bigger than the canvas.
+      def into_view(column, row, width, height)
+        selected_box = boxes[box]
+        column = selected_box.right - width + 1 if selected_box.right >= column + width
+        row = selected_box.bottom - height + 1 if selected_box.bottom >= row + height
+        [[column, selected_box.left].min, [row, selected_box.top].min]
+      end
+
+      def drawing_width = drawing.map(&:length).max.to_i
+      def drawing_height = drawing.length
+    end
+  end
+end