raindown 0.6.0 → 0.8.0

data/lib/raindown/directives.rb

@@ -3,27 +3,44 @@
 require 'cgi/escape'
 
 module Raindown
-  # Content directives, like a node's directive and end tag or an endpoint's, are kept in the HTML:
-  # in bold by default, or as HTML comments with the hide_directives setting.
-  # Until then each is a comment marker, which ends the Markdown block before it and starts nothing itself,
-  # so a node's list stays its own list.
-  # Template directives, like for: and if:, are always invisible, since they often sit inside tables and lists.
+  # How a content directive is written says what it does, and how it shows in the HTML:
+  #   toc:                          bare, it writes its output into the file, and shows in bold
+  #   <!-- toc: --> <!-- :toc -->   as comments, it writes its output into the file, and is left out of the HTML
+  #   <{ toc: }> <{ :toc }>         in Antlers' delimiters, it only renders, and is left out of the HTML
+  # Template directives, like for: and if:, are always in Antlers' delimiters, and always hidden.
+  # Until the HTML's done each is a comment marker, which ends the Markdown block before it and starts nothing itself,
+  # so a node's list stays its own list. A hidden one is left out of the HTML altogether.
   module Directives
     MARKER = /<!-- raindown:directive (.*?) -->/
+    HIDDEN = /<!-- raindown:hidden .*? -->\n?/
+    # A directive in an HTML comment, which writes back, or in Antlers' delimiters, which only renders.
+    COMMENT = ['<!--', '-->'].freeze
+    DELIMITERS = ['<{', '}>'].freeze
 
     module_function
 
-    # A directive like "files: folder: 'notes'", or a whole line like <{ :files }>, as a marker.
-    def marker(directive)
-      text = directive.strip.delete_prefix('<{').delete_suffix('}>').strip.gsub('--', '- -')
+    # A directive's line without its delimiters, like "files: folder: 'notes'" for <!-- files: folder: 'notes' -->.
+    def text(line)
+      line = line.strip
+      [COMMENT, DELIMITERS].each do |open, close|
+        return line.delete_prefix(open).delete_suffix(close).strip if line.start_with?(open) && line.end_with?(close)
+      end
+      line
+    end
+
+    # Whether the directive's line is bare, without delimiters, so it shows in bold.
+    def bare?(line) = text(line) == line.strip
+
+    # A directive's line as a marker: in bold when it's shown, like a bare directive, or else hidden.
+    def marker(line, shown: bare?(line))
+      text = text(line).gsub('--', '- -')
+      return "<!-- raindown:hidden #{text} -->" unless shown
+
       "<!-- raindown:directive #{text} -->"
     end
 
-    def render(html, hide: false)
-      html.gsub(MARKER) do
-        text = ::Regexp.last_match(1)
-        hide ? "<!-- #{text} -->" : "<p><strong>#{CGI.escapeHTML(text.to_s)}</strong></p>"
-      end
+    def render(html)
+      html.gsub(HIDDEN, '').gsub(MARKER) { "<p><strong>#{CGI.escapeHTML(::Regexp.last_match(1).to_s)}</strong></p>" }
     end
   end
 end

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)
@@ -49,7 +50,7 @@ module Raindown
 
     # The headings in the order they appear, with their source text, like "Notes for {name}" before it's rendered.
     def headings
-      @headings ||= nodes(:heading).map do |node|
+      @headings ||= root.walk.select { |node| node.type == :heading }.map do |node|
         Heading.new(level: node.header_level, text: text(node), line: node.source_position[:start_line])
       end
     end
@@ -71,10 +72,6 @@ module Raindown
       @root ||= Commonmarker.parse(@markdown, options: MARKDOWN_OPTIONS)
     end
 
-    def nodes(type)
-      [].tap { |nodes| root.walk { |node| nodes << node if node.type == type } }
-    end
-
     def text(heading)
       parts = []
       heading.walk do |node|
@@ -87,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
 
@@ -98,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
 
@@ -109,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)
@@ -132,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/curl.rb

@@ -66,19 +66,23 @@ module Raindown
     end
 
     # The snippet's method and URL, like GET https://httpbin.org/uuid, or nil when it can't be read.
-    # A snippet that sends data is a POST, unless it says otherwise, as with curl.
     def request(snippet)
       args = arguments(snippet)
-      url = args.find { it.match?(URL) }
-      method = args[args.index('--request') + 1] if args.include?('--request')
-      method ||= 'HEAD' if args.include?('--head')
-      method ||= 'POST' if args.intersect?(VALUE_CHECKS.keys.grep(/data|json/))
-
-      Request.new(method: (method || 'GET').upcase, url:) if url
+      Request.new(method: request_method(args), url: args.find { it.match?(URL) })
     rescue Error
       nil
     end
 
+    # A snippet that sends data is a POST, unless it says otherwise, as with curl.
+    def request_method(args)
+      index = args.index('--request')
+      return args[index + 1].upcase if index
+      return 'HEAD' if args.include?('--head')
+      return 'POST' if args.intersect?(VALUE_CHECKS.keys.grep(/data|json/))
+
+      'GET'
+    end
+
     def arguments(snippet)
       words = Shellwords.split(snippet.gsub(/\\\r?\n/, ' ').strip.delete_prefix('$ '))
       raise Error, 'Endpoint snippets must start with curl' unless words.first == 'curl'

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)
 
@@ -77,13 +79,16 @@ module Raindown
     end
 
     def rendered_lines(lines, block, markdown:, metadata:, bare:)
-      node = block[:node]
-      output = if Nodes.html?(node) then ["#{Nodes.placeholder(node)}\n"]
-               else "#{Nodes.call(node, :replace, document: markdown, metadata:, bare:).to_s.chomp}\n".lines
-               end
-      output = [] if output == ["\n"]
+      output = node_markdown(block[:node], markdown:, metadata:, bare:).chomp
+      close = marker(lines[block[:close]]) if block[:close]
 
-      [marker(lines[block[:open]]), *output, *(marker(lines[block[:close]]) if block[:close])]
+      [marker(lines[block[:open]]), *("#{output}\n".lines unless output.empty?), *close]
+    end
+
+    def node_markdown(node, markdown:, metadata:, bare:)
+      return Nodes.placeholder(node) if Nodes.html?(node)
+
+      Nodes.call(node, :replace, document: markdown, metadata:, bare:).to_s
     end
 
     def marker(line)
@@ -96,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|
@@ -123,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/nodes.rb

@@ -3,6 +3,7 @@
 require_relative 'chart/chart'
 require_relative 'files'
 require_relative 'node'
+require_relative 'stat'
 require_relative 'toc'
 
 module Raindown

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/stat.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Raindown
+  # The base of a project's stats: one big number in block digits, above its label, written into the Markdown as code,
+  # and shown on the terminal UI's Dashboard as a card, like a chart:
+  #    ▀█  ▀▀█
+  #     █  █▀▀
+  #    ▀▀▀ ▀▀▀
+  #   open issues
+  # A stat's a node in .raindown that says its value, and its label:
+  #   class Issues < Raindown::Stat
+  #     def value(metadata:) = Issue.open.count
+  #     def label = 'open issues'
+  #   end
+  class Stat < Node
+    # Each character's three lines in block digits, which end on the top half of the third, where a point sits too.
+    # Others are left as they are, on the middle line.
+    DIGITS = { '0' => ['█▀█', '█ █', '▀▀▀'], '1' => ['▀█ ', ' █ ', '▀▀▀'], '2' => ['▀▀█', '█▀▀', '▀▀▀'],
+               '3' => ['▀▀█', ' ▀█', '▀▀▀'], '4' => ['█ █', '▀▀█', '  ▀'], '5' => ['█▀▀', '▀▀█', '▀▀▀'],
+               '6' => ['█▀▀', '█▀█', '▀▀▀'], '7' => ['▀▀█', '  █', '  ▀'], '8' => ['█▀█', '█▀█', '▀▀▀'],
+               '9' => ['█▀█', '▀▀█', '▀▀▀'], '-' => ['   ', '▀▀▀', '   '], '+' => [' ▄ ', '▀█▀', '   '],
+               '.' => [' ', ' ', '▀'], ',' => [' ', ' ', '▀'] }.freeze
+
+    def replace(metadata: NoMetadata) = "```\n#{card_lines(metadata:).join("\n")}\n```"
+
+    # The number in block digits, then the label, as a card on the Dashboard shows them.
+    def card_lines(metadata: NoMetadata)
+      characters = number(value(metadata:)).chars.map { digit(it) }
+      [*Array.new(3) { |line| characters.map { it[line] }.join(' ').rstrip }, label]
+    end
+
+    def value(metadata: NoMetadata) = raise(NotImplementedError, "#{self.class} needs a value")
+
+    def label = ''
+
+    # How the value's written, which a stat can change, like with a sign.
+    def number(value) = value.to_s
+
+    private
+
+    # The character's three lines in block digits, or itself on the middle line.
+    def digit(character) = DIGITS.fetch(character) { [' ', character, ' '] }
+
+    # The project's folder, from the page being rendered, or else the current one.
+    def root(metadata)
+      return metadata.root if metadata.respond_to?(:root)
+
+      Dir.pwd
+    end
+  end
+end

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