raindown 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ea9df31d83ebabf0649ad353b75e2f2546aeb10c31aa97038bdd85f5e45fd2c
-  data.tar.gz: cc736f0d57e576c476629bfa7fe37405139cb1b880e86908e71e7e8d8b22926c
+  metadata.gz: f795c35070ab8ae4f6b40e5a32595ab9ba6099b99f42aada8d0faafe2f56121d
+  data.tar.gz: a01426b3aab916e21b0e68f66fddd7f6b55d7e9c34ceb9665118a60b3ceae4b5
 SHA512:
-  metadata.gz: 851438f9079a944aca1dc2f97d0c5081822d0ce31df12e536ca10dce8d471233ee0879fc91b7004fcf7949159554dec7cd0d1e4aa3d50b8cee4009dbd3180766
-  data.tar.gz: 27863d35bb59084303144bdc0b1ea3852028a55c854e8142456c3e1d8f9ee495a3d5489dc00c91ce474bcd9eda833deb42d4f3696118bb24c25e913dabb54372
+  metadata.gz: 052231532f48cc3a575388ebe95fa62b70bc3eba2121742142071c2ab256ced437de1f4c80f2e439599d579c2b5eea2d793b7cb05439601523bc72ff9c252dd6
+  data.tar.gz: 98ff7b646f8e380817bbf69efc06a0bf67b4945a233349c9702d3140458bb27e387ecd010498c80dbfa4a9d2e64872b4f7af75bcd12b28b992e8b82ac66f56c9

data/lib/raindown/bare_directives.rb

@@ -13,17 +13,17 @@ module Raindown
   #
   # A bare schema: shows in bold, with its fields in a code block below it.
   #
-  # Bare directives have no end tag. A bare endpoint closes itself after its curl snippet and response, so where it
-  # needs more than that, write it in comments with an end tag instead:
+  # Bare directives have no end tag. A bare endpoint holds the lines straight below it, its curl snippet, the comment
+  # with its response's status, time and date, and its response, up to the next blank line, like a bare node block, so
+  # where it needs blank lines, write it in comments with an end tag instead:
   #   <!-- endpoint: -->
   #   ...
   #   <!-- :endpoint -->
   module BareDirectives
     EXTENSIONS = %w[.rd .raindown].freeze
-    # The block directives, and the method that finds the line their end tag goes after.
-    BLOCK_KEYWORDS = { 'endpoint:' => :after_endpoint }.freeze
-    # Four spaces of indent would make the line a Markdown code block.
-    LINE = /\A( {0,3})((#{BLOCK_KEYWORDS.keys.join('|')})(?:[ \t]+\S.*?)?)[ \t]*$/
+    # A bare endpoint, the one bare directive with a block. Four spaces of indent would make the line a Markdown code
+    # block.
+    LINE = /\A( {0,3})(endpoint:(?:[ \t]+\S.*?)?)[ \t]*$/
 
     module_function
 
@@ -75,7 +75,7 @@ module Raindown
       return index unless match
 
       lines[index] = "#{Directives.marker(match[2], shown: true)}\n#{wrap(lines[index])}"
-      close_block(lines, index, indent: match[1], keyword: match[3])
+      close_block(lines, index, indent: match[1])
       index
     end
 
@@ -88,16 +88,10 @@ module Raindown
     end
 
     # The end tag after the block, then the end tag in bold, as a bare directive's shown.
-    def close_block(lines, index, indent:, keyword:)
-      last = public_send(BLOCK_KEYWORDS[keyword], lines, index + 1) || index
+    def close_block(lines, index, indent:)
+      last = CodeBlocks.last_before_blank(lines, index)
       lines[last] = "#{lines[last]}\n" unless lines[last].end_with?("\n")
-      name = keyword.delete_suffix(':')
-      lines.insert(last + 1, "#{indent}<{ :#{name} }>\n#{Directives.marker(":#{name}", shown: true)}\n")
-    end
-
-    # The last line of the curl snippet and response below an endpoint.
-    def after_endpoint(lines, index)
-      CodeBlocks.endpoint(lines, index).last&.fetch(:close)
+      lines.insert(last + 1, "#{indent}<{ :endpoint }>\n#{Directives.marker(':endpoint', shown: true)}\n")
     end
   end
 end

data/lib/raindown/code_blocks.rb

@@ -5,6 +5,9 @@ module Raindown
   module CodeBlocks
     FENCE = /\A {0,3}(`{3,}|~{3,})[ \t]*(\S*)/
     SNIPPET_LANGUAGES = %w[sh bash shell zsh console curl].freeze
+    # The comment Raindown writes between an endpoint's snippet and its response, with the response's status, how long
+    # it took and the date it was fetched, like <!-- response 200 · 142 ms · 2026-10-14 -->.
+    RESPONSE_COMMENT = /\A {0,3}<!-- response [^\n]*? -->[ \t]*$/
     # The line closing a fence, like ``` or ~~~~, compiled once per fence.
     CLOSINGS = Hash.new { |closings, fence| closings[fence] = /\A {0,3}#{fence[0]}{#{fence.length},}[ \t]*$/ }
 
@@ -19,27 +22,32 @@ module Raindown
       { open: index, close:, language:, body: lines[index + 1...close].join } if close
     end
 
-    # An endpoint's curl snippet and its response, if it has one yet.
-    # A second snippet straight after is another example rather than the response.
-    def endpoint(lines, index)
-      snippet, response = following(lines, index, limit: 2)
-      response && snippet?(response) ? [snippet] : [snippet, response].compact
+    # An endpoint's curl snippet and its response, if it has one yet, with the line of the response comment between them
+    # as the response's :comment, if there is one. A second snippet straight after is another example rather than the
+    # response. A bare endpoint's are in the lines straight below it, up to the next blank line.
+    def endpoint(lines, index, bare: false)
+      lines = lines[..last_before_blank(lines, index - 1)] if bare
+      snippet = at(lines, skip_blank_lines(lines, index))
+      return [] unless snippet
+
+      index = skip_blank_lines(lines, snippet[:close] + 1)
+      comment = index if lines[index]&.match?(RESPONSE_COMMENT)
+      response = at(lines, comment ? skip_blank_lines(lines, comment + 1) : index)
+      return [snippet] if response.nil? || snippet?(response)
+
+      [snippet, response.merge(comment:)]
     end
 
     def snippet?(block)
       SNIPPET_LANGUAGES.include?(block[:language].downcase) || block[:body].lstrip.start_with?('curl')
     end
 
-    # Up to limit blocks from index on, with only blank lines before and between them.
-    def following(lines, index, limit:)
-      blocks = []
-
-      while blocks.length < limit && (block = at(lines, skip_blank_lines(lines, index)))
-        blocks << block
-        index = block[:close] + 1
-      end
-
-      blocks
+    # The last of the lines straight below open, up to the next blank line, with fenced code kept whole, or open when
+    # there are none, like a bare block's.
+    def last_before_blank(lines, open)
+      last = open
+      last = at(lines, last + 1)&.fetch(:close) || (last + 1) while lines[last + 1] && !lines[last + 1].strip.empty?
+      last
     end
 
     def skip_blank_lines(lines, index)

data/lib/raindown/document.rb

@@ -16,6 +16,9 @@ module Raindown
   class Document
     Heading = Data.define(:level, :text, :line)
 
+    # Its Markdown, and whether it allows bare directives.
+    attr_reader :markdown, :bare
+
     # A content directive: a node, like toc: or a project's Changelog:, or an endpoint.
     # 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.
@@ -116,21 +119,18 @@ module Raindown
       [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.
+    # The response and the comment above it are the output, while the curl snippet above them is the author's.
     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]))
+      bare = Directives.bare?(@lines[open])
+      curl, response = CodeBlocks.endpoint(@lines, open + 1, bare:)
+      output = response && ((response[:comment] || response[:open])..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 unless Directives.bare?(@lines[open])
+      # A bare endpoint ends at the next blank line, and one in a comment at its end tag.
+      last = bare ? CodeBlocks.last_before_blank(@lines, open) : end_tag(after: last) || last
 
       directive('endpoint', args, open..last, output:, writes:)
     end
 
-    def fetched?(index)
-      @lines[index]&.match?(EndpointRunner::FETCHED)
-    end
-
     # 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)

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -10,17 +10,17 @@ require_relative 'endpoint_variables'
 
 module Raindown
   # 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, its status and how long it took.
+  # block below it, after a comment of its status, how long it took and the date it was fetched.
   # Only runs when that block is missing or empty, and --execute is passed, so a file can't run requests by itself.
   # Or with only: and a directive's line index, runs just that endpoint, replacing any response it has.
   #   <!-- endpoint: -->
   #   ```sh
   #   curl https://api.example.com
   #   ```
+  #   <!-- response 200 · 142 ms · 2026-10-14 -->
   #   ```json
   #   { "id": 1 }
   #   ```
-  #   <!-- raindown:fetched 2026-10-14 · 200 · 142 ms -->
   #   <!-- :endpoint -->
   # Its snippet's {placeholders} are filled from EndpointVariables, and with as: login, later snippets can use its
   # response, like {login.token}. With status: and schema:, each response in the file is checked, and failures are kept.
@@ -32,9 +32,7 @@ module Raindown
     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]*$/
-    # The date a response was fetched, on the line after it.
-    FETCHED = /\A {0,3}<!-- raindown:fetched [^\n]*? -->[ \t]*$/
-    FETCHED_STATUS = /raindown:fetched \S+ · (\d{3}) /
+    RESPONSE_STATUS = /<!-- response (\d{3}) /
 
     attr_reader :failures
 
@@ -83,19 +81,19 @@ module Raindown
 
     # Returns the index of the last line it handled.
     def fill(index, args, directive:)
-      curl, output = CodeBlocks.endpoint(@lines, index)
+      curl, output = CodeBlocks.endpoint(@lines, index, bare: !@lines[directive].match?(COMMENT))
       return index - 1 unless curl&.dig(:body)&.lstrip&.start_with?('curl')
       return write_output(curl:, output:, args:, directive:) if run?(output, directive)
       return curl[:close] unless output
 
       @variables.remember(args.name, output[:body])
-      check(args, directive:, body: output[:body], status: fetched_status(output))
+      check(args, directive:, body: output[:body], status: response_status(output))
       curl[:close]
     end
 
-    # The status in the fetched comment after a response, which responses fetched before statuses were kept don't have.
-    def fetched_status(output)
-      @lines[output[:close] + 1]&.[](FETCHED_STATUS, 1)&.to_i
+    # The status in the comment above a response, which a comment written by hand may not have.
+    def response_status(output)
+      @lines[output[:comment]][RESPONSE_STATUS, 1]&.to_i if output[:comment]
     end
 
     # Run alone, only the endpoint that ran is checked. One without a response or a status hasn't run, so it has nothing
@@ -113,14 +111,15 @@ module Raindown
       @execute && (output.nil? || output[:body].strip.empty?)
     end
 
-    # Replaces the output block and the date it was fetched, or with no block, replaces nothing just after the curl block.
+    # Replaces everything from just after the curl block to the end of the output block, if there is one, like its
+    # comment.
     # Secrets that a response echoes are written as their placeholders.
     def write_output(curl:, output:, args:, directive:)
       response = Curl.run(curl[:body], @variables)
       body = @variables.redact(response.body)
       @variables.remember(args.name, body)
       check(args, directive:, body:, status: response.status)
-      replace_output(curl:, output:, block: [*output_block(body, response.language), fetched(response)])
+      replace_output(curl:, output:, block: [response_comment(response), *output_block(body, response.language)])
     rescue Curl::Error => e
       message = @variables.redact(e.message)
       # The one endpoint that was asked for fails for the caller to show, like in the terminal UI.
@@ -132,21 +131,13 @@ module Raindown
 
     # Returns the index of the block's last line.
     def replace_output(curl:, output:, block:)
-      block.unshift("\n") unless output
-      start = output ? output[:open] : curl[:close] + 1
-
-      @lines[start, output ? replaced_length(output) : 0] = block
+      start = curl[:close] + 1
+      @lines[start, output ? output[:close] - start + 1 : 0] = block
       start + block.length - 1
     end
 
-    # The output block, and the line after it when that's the date it was last fetched.
-    def replaced_length(output)
-      length = output[:close] - output[:open] + 1
-      @lines[output[:close] + 1]&.match?(FETCHED) ? length + 1 : length
-    end
-
-    def fetched(response)
-      "<!-- raindown:fetched #{Date.today.iso8601} · #{response.status} · #{response.milliseconds} ms -->\n"
+    def response_comment(response)
+      "<!-- response #{response.status} · #{response.milliseconds} ms · #{Date.today.iso8601} -->\n"
     end
 
     # The fence is longer than any run of backticks in the body, so the body can't close it.

data/lib/raindown/node_blocks.rb

@@ -127,12 +127,7 @@ module Raindown
     end
 
     # A bare block holds the lines straight below it, up to the next blank line, with fenced code kept whole.
-    def bare_block(lines, open)
-      last = open
-      last = CodeBlocks.at(lines, last + 1)&.fetch(:close) || (last + 1) while lines[last + 1] && !lines[last + 1].strip.empty?
-
-      { open:, close: nil, last: }
-    end
+    def bare_block(lines, open) = { open:, close: nil, last: CodeBlocks.last_before_blank(lines, open) }
 
     # The end tag written the same way as the directive: in a comment, or in Antlers' delimiters.
     def end_tag(lines, open, name, comment:)

data/lib/raindown/node_injector.rb

@@ -35,7 +35,8 @@ module Raindown
     private
 
     def block_lines(lines, block)
-      markdown = Nodes.call(block[:node], :replace, document: @content, metadata: @metadata, bare: @bare).to_s.chomp
+      context = { document: @content, metadata: @metadata, bare: @bare, written: written_lines(lines, block) }
+      markdown = Nodes.call(block[:node], :replace, **context).to_s.chomp
       written = markdown.empty? ? [] : "#{markdown}\n".lines
       return [line(lines[block[:open]]), *bare(written, block)] unless block[:close]
 
@@ -54,6 +55,11 @@ module Raindown
       raise BlankLine, "#{name} writes blank lines, so it needs <!-- #{name}: --> and <!-- :#{name} --> around it"
     end
 
+    # What the block's node wrote last time, between its directive and its end tag, or the next blank line.
+    def written_lines(lines, block)
+      lines[(block[:open] + 1)...(block[:close] || (block[:last] + 1))]
+    end
+
     def line(line)
       line.end_with?("\n") ? line : "#{line}\n"
     end

data/lib/raindown/nodes.rb

@@ -6,6 +6,7 @@ require_relative 'js/js_nodes'
 require_relative 'markdown_nodes'
 require_relative 'node'
 require_relative 'stat'
+require_relative 'table/table'
 require_relative 'toc'
 
 module Raindown
@@ -13,11 +14,12 @@ module Raindown
   # A project keeps them in a .raindown folder, which is loaded with Dirload, beside its JavaScript and Markdown
   # Components, if any.
   # A node writes Markdown with #replace, and HTML with #render if it has one. Either can take the keywords
-  # document: (the Markdown being rendered), metadata: and bare:, and gets the ones it asks for.
+  # document: (the Markdown being rendered), metadata:, bare: and written: (the lines it wrote last time), and gets the
+  # ones it asks for.
   module Nodes
     FOLDER = '.raindown'
-    # Lowercase directives for Raindown's own nodes. A project's own TOC, Files or Chart node replaces Raindown's.
-    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files', 'chart' => 'Chart' }.freeze
+    # Lowercase directives for Raindown's own nodes. A project's own TOC, Files, Chart or Table node replaces Raindown's.
+    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files', 'chart' => 'Chart', 'table' => 'Table' }.freeze
     # A placeholder for a node's HTML, which stays as it is through Commonmarker and Antlers.
     PLACEHOLDER = /<!-- raindown:node (\d+) -->/
 

data/lib/raindown/pages.rb

@@ -61,10 +61,12 @@ module Raindown
     attr_reader :root
 
     # Render options, like highlight_code: false, are for rendering each listed file's content.
-    def initialize(metadata:, root:, render_options: {})
+    # Eager reads every file's front matter straight away, for an app like Raindeer that needs all of it from the start.
+    def initialize(root:, metadata:, render_options: {}, eager: false)
       @root = root
       @render_options = render_options
       @file_paths = metadata.file_types.values_at(*EXTENSIONS).flatten.compact
+      load_metadata if eager
     end
 
     # The files with any of the tags, like list(folder: 'basics') or list(tags: 'ruby'), sorted by order.
@@ -81,16 +83,16 @@ module Raindown
     private
 
     def metadata
-      process_files unless @metadata
+      load_metadata unless @metadata
       @metadata
     end
 
     def tags
-      process_files unless @tags
+      load_metadata unless @tags
       @tags
     end
 
-    def process_files
+    def load_metadata
       @metadata = {}
       @tags = {}
       @file_paths.each { |file_path| process(file_path:) }

data/lib/raindown/table/markdown_table.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Raindown
+  # Rows of cells as a Markdown table, its first row the header, and back again. A | in a cell is escaped as \|, and
+  # a line break is written as a space, as a table's cells are one line. The TableFormatter lines up its columns.
+  module MarkdownTable
+    SEPARATOR = /\A\|?(\s*:?-+:?\s*\|)*\s*:?-+:?\s*\|?\z/
+    # A | that isn't escaped.
+    PIPE = /(?<!\\)\|/
+
+    module_function
+
+    def format(rows)
+      header, *body = rows.map { |row| "| #{row.map { escape(it) }.join(' | ')} |" }
+      [header, "|#{Array.new(rows.first.length, '---').join('|')}|", *body].join("\n")
+    end
+
+    # The rows of the table in the lines, leaving out its separator, or none when they aren't a table.
+    def parse(lines)
+      return [] unless lines[1]&.strip&.match?(SEPARATOR)
+
+      [lines[0], *lines.drop(2)].take_while { it.strip.start_with?('|') }.map { cells(it.strip) }
+    end
+
+    def cells(line)
+      line.delete_prefix('|').delete_suffix('|').split(PIPE, -1).map { it.strip.gsub('\|', '|') }
+    end
+
+    def escape(cell)
+      cell.gsub('|', '\|').gsub(/\s*\R\s*/, ' ')
+    end
+  end
+end

data/lib/raindown/table/table.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'digest'
+require 'json'
+
+require_relative '../node'
+require_relative 'markdown_table'
+
+module Raindown
+  # The node behind table:, a CSV or TSV file relative to the project as a Markdown table, after a comment of how many
+  # rows it has and a hash of them, as they were when the table and the file last matched:
+  #   table: 'data/team.csv'
+  #   <!-- table 2 rows · 3f2a9c -->
+  #   | name | role     |
+  #   |------|----------|
+  #   | Ada  | engineer |
+  #   | Lin  | design   |
+  # Edit the table and its rows are written back to the file, or edit the file and the table's written again. When
+  # both changed, neither is, and the table's comment says so until they match again.
+  class Table < Node
+    COMMENT = /\A<!-- table (?:conflict|\d+ rows?) · (\h+) -->\z/
+    SEPARATORS = { '.csv' => ',', '.tsv' => "\t" }.freeze
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Written is what it wrote last time, so it can tell which of the table and the file changed since.
+    def replace(written: [], metadata: NoMetadata)
+      path = File.expand_path(@data.to_s, metadata.respond_to?(:root) ? metadata.root : Dir.pwd)
+      return "Can't show #{@data.inspect} as a table: only CSV and TSV files can be" unless SEPARATORS.key?(File.extname(path).downcase)
+      return "Can't show #{@data.inspect} as a table: no such file" unless File.file?(path)
+
+      synced(path, written.map(&:chomp))
+    end
+
+    private
+
+    def synced(path, written)
+      file = read_rows(path)
+      synced_hash = written.first&.[](COMMENT, 1)
+      table = MarkdownTable.parse(written.drop(1))
+      return markdown(file) if synced_hash.nil? || table.empty? || [synced_hash, hash_rows(file)].include?(hash_rows(table))
+      return markdown(write_rows(path, table)) if hash_rows(file) == synced_hash
+
+      warn "raindown: #{@data} and its table both changed, so neither is written until they match"
+      ["<!-- table conflict · #{synced_hash} -->", *written.drop(1)].join("\n")
+    end
+
+    def markdown(rows)
+      return '' if rows.empty?
+
+      count = rows.length - 1
+      "<!-- table #{count} row#{'s' unless count == 1} · #{hash_rows(rows)} -->\n#{MarkdownTable.format(rows)}"
+    end
+
+    def read_rows(path)
+      rows = CSV.read(path, col_sep: SEPARATORS[File.extname(path).downcase], skip_blanks: true, encoding: Encoding::UTF_8)
+      width = rows.map(&:length).max.to_i
+      rows.map { |row| Array.new(width) { row[it].to_s.strip } }
+    end
+
+    def write_rows(path, rows)
+      File.write(path, rows.map { CSV.generate_line(it, col_sep: SEPARATORS[File.extname(path).downcase]) }.join)
+      rows
+    end
+
+    def hash_rows(rows)
+      Digest::SHA256.hexdigest(JSON.generate(rows))[0, 6]
+    end
+  end
+end

data/lib/raindown/tui/cloud.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Raindown
+  module TUI
+    # Raindown's logo, raindown.dev's rain cloud, in the middle of the screen while the terminal UI loads: bumps and a
+    # rounded base of blocks, each its own blue, lighter at the top, with a few corrupted, and rain falling from under it
+    # to the bottom of the screen, fading and thinning out as it goes:
+    #                   ███████████████▞███▄██████████
+    #                    ██████████████████████████
+    #                   ╎╎,┊ '  ,   ┊ ┊ '   ┊' ╎,
+    #                ╎  │ ││ ,  │   │ , '   ' ┊,
+    # It's drawn like the site's RainCloud, with the same seed, so it's the same cloud, in the nearest of the 256 colours
+    # most terminals have.
+    class Cloud
+      WIDTH = 50
+      ROWS = 19
+      SEED = 5
+      # Bumps as [column, row, radius], and the base under them, with its corners rounded. Rows are stretched, as
+      # characters are taller than they're wide.
+      BUMPS = [[25, 8, 11], [13, 12, 7.5], [37, 11, 8.5]].freeze
+      BASE_ROWS = 12..18
+      BASE_COLUMNS = 7..43
+      CORNER = 5
+      ROW_STRETCH = 1.7
+      SHADES = %w[█ ▓].freeze
+      CORRUPT = %w[▀ ▄ ▚ ▞ ▌ ▐].freeze
+      CORRUPTED = 0.015
+      RAIN = %w[│ ╎ ┊ ' ,].freeze
+      # The rain's blue, as hue, saturation and lightness, which fades in steps as it falls, and thins out.
+      RAIN_BLUE = [212, 100, 70].freeze
+      RAIN_STEPS = 8
+      FADE = 0.11
+      # The levels of red, green and blue in the 256 colours' cube, from 16 to 231, leaving out the greys after it, so
+      # the rain stays blue as it fades.
+      CUBE = [0, 95, 135, 175, 215, 255].freeze
+      XTERM = (16..231).to_h { [it, CUBE.values_at((it - 16) / 36, ((it - 16) / 6) % 6, (it - 16) % 6)] }.freeze
+
+      class << self
+        # Each cell inside the cloud, by its row and column, as its block and its blue's style.
+        def cells = drawing.first
+
+        # The columns it rains from.
+        def rainy = drawing.last
+
+        # The rain's style at each step, from just under the cloud to the bottom of the screen.
+        def rain_styles
+          @rain_styles ||= Array.new(RAIN_STEPS) { |step| style(rgb(*RAIN_BLUE).map { (it * (1 - (step * FADE))).round }) }
+        end
+
+        # Every blue it's drawn in, for the screen's colours.
+        def styles = (cells.values.map(&:last) + rain_styles).uniq
+
+        private
+
+        # Rolled in the site's order, a cell at a time, then the rainy columns.
+        def drawing
+          @drawing ||= begin
+            random = Random.new(SEED)
+            cells = ROWS.times.to_a.product(WIDTH.times.to_a).select { inside?(*it) }.to_h { [it, cell(it.first, random)] }
+            [cells, ((BASE_COLUMNS.begin + 1)..(BASE_COLUMNS.end - 1)).select { random.rand < 0.6 }]
+          end
+        end
+
+        # A corrupted block now and then, and otherwise a shade, denser towards the bottom, with some noise.
+        def cell(row, random)
+          return [CORRUPT.sample(random:), blue(row, random)] if random.rand < CORRUPTED
+
+          depth = (row / ROWS.to_f) + random.rand(-0.25..0.25)
+          [SHADES[(1 - (depth * 2)).round.clamp(0, 1)], blue(row, random)]
+        end
+
+        # A random blue, lighter at the top of the cloud and darker at the bottom.
+        def blue(row, random)
+          light = (82 - (row * 2.4) + random.rand(-12..12)).round.clamp(25, 90)
+          style(rgb(random.rand(198..235), random.rand(65..100), light))
+        end
+
+        # The style of the nearest of the 256 colours.
+        def style(rgb) = :"cloud_#{XTERM.min_by { |_, color| color.zip(rgb).sum { (it[0] - it[1])**2 } }.first}"
+
+        def rgb(hue, saturation, lightness)
+          saturation /= 100.0
+          lightness /= 100.0
+          chroma = saturation * [lightness, 1 - lightness].min
+          [0, 8, 4].map do |offset|
+            k = (offset + (hue / 30.0)) % 12
+            ((lightness - (chroma * [[k - 3, 9 - k, 1].min, -1].max)) * 255).round
+          end
+        end
+
+        def inside?(row, column)
+          BUMPS.any? { |x, y, radius| ((column - x)**2) + (((row - y) * ROW_STRETCH)**2) <= radius**2 } || base?(row, column)
+        end
+
+        def base?(row, column)
+          return false unless BASE_ROWS.cover?(row) && BASE_COLUMNS.cover?(column)
+
+          corner_row, corner_column = corner(row, column)
+          ((column - corner_column)**2) + (((row - corner_row) * ROW_STRETCH)**2) <= CORNER**2
+        end
+
+        # The nearest point to the cell that's a corner's radius in from the base's edges, where its corners curve in
+        # from, reaching at most halfway up the base.
+        def corner(row, column)
+          inset = [CORNER / ROW_STRETCH, (BASE_ROWS.end - BASE_ROWS.begin) / 2.0].min
+          [row.clamp(BASE_ROWS.begin + inset, BASE_ROWS.end - inset), column.clamp(BASE_COLUMNS.begin + CORNER, BASE_COLUMNS.end - CORNER)]
+        end
+      end
+
+      attr_reader :width, :height
+
+      def initialize(width:, height:)
+        @width = width
+        @height = height
+        @left = (width - WIDTH) / 2
+        @top = [(height - ROWS) / 3, 0].max
+      end
+
+      # Draws the cloud and its rain at the tick into a Scene's cells.
+      def draw(cells, tick)
+        self.class.cells.each { |(row, column), (block, style)| put(cells, row, column, block, style) }
+        rain(cells, tick)
+      end
+
+      private
+
+      # Drops in the rainy columns, moving down a row a tick, fading and thinning out in steps below the cloud.
+      def rain(cells, tick)
+        falling = height - @top - ROWS
+        falling.times do |below|
+          step = below * RAIN_STEPS / falling
+          self.class.rainy.each { |column| drop(cells, column, below - tick, ROWS + below, step) }
+        end
+      end
+
+      # The drop in the column at the row, if there's one there at the tick, from a checksum of where it is in the rain.
+      def drop(cells, column, falling, row, step)
+        drop = Zlib.crc32("#{column} #{falling}")
+        return unless (drop % 100) < 90 - (step * 9)
+
+        put(cells, row, column, RAIN[drop % RAIN.length], self.class.rain_styles[step])
+      end
+
+      # The cell at the cloud's row and column, where it's on the screen.
+      def put(cells, row, column, char, style)
+        row += @top
+        column += @left
+        cells[row][column] = [char, style] if row.between?(0, height - 1) && column.between?(0, width - 1)
+      end
+    end
+  end
+end

data/lib/raindown/tui/feelings/celebration/celebration_renderer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../../text'
+require_relative '../waffle/waffle'
+require_relative 'scene'
+
+module Raindown
+  module TUI
+    # A Celebration over the whole screen, in place of the Layout: rain and fireworks, then a waffle popping out, among
+    # confetti, balloons and sparkles.
+    CelebrationRenderer = Struct.new(:celebration, :width, :height) do
+      include Text
+      include Waffle
+
+      def lines
+        return Scene.new(width:, height:).lines(celebration.frame) if celebration.raining?
+
+        waffle(Scene.new(width:, height:, animations: [Confetti, Balloons, Sparkles]).lines(celebration.popping), celebration.popping)
+      end
+    end
+  end
+end

data/lib/raindown/tui/feelings/feelings_renderer.rb

@@ -7,14 +7,11 @@ require_relative 'bins'
 require_relative 'feelings_code_box'
 require_relative 'magnifier'
 require_relative 'motion'
-require_relative 'celebration/scene'
-require_relative 'waffle/waffle'
 
 module Raindown
   module TUI
     # Code feelings, right of the files: the methods as clusters of digits in a grid, with the selected one highlighted
     # and its code below, then why it felt that way while that's typed, then the five bins and how many each holds.
-    # When the batch is refined, it rains over them, then there's a waffle:
     #     0  0  2  2  2  5  5  9  9  9  9  1
     #     1  3  3  7  7  7  6  4  4  0  8  8
     #    ╭─ lib/text.rb:62 · Text#segments_between ──────────── changed 6× ─╮
@@ -29,7 +26,6 @@ module Raindown
       include FeelingsCodeBox
       include Magnifier
       include Motion
-      include Waffle
 
       # The columns a cell takes, on a line of its own, its digit small in the middle, which is magnified in a stat's block
       # digits across the cell and over the cells above and below it when the mouse is over its method.
@@ -66,7 +62,7 @@ module Raindown
         return too_small if too_small?
 
         cells = view.cells(columns, filled_rows)
-        return instead if view.code_methods.empty? || view.celebration
+        return instead if view.code_methods.empty?
 
         below = [*code_box, *bins]
         (grid(cells, below.length) + below).first(height)
@@ -76,20 +72,11 @@ module Raindown
 
       def view = navigator.view
 
-      # Instead of the grid, that there's nothing to feel, as there are no projects or no methods, or the celebration.
+      # Instead of the grid, that there's nothing to feel, as there are no projects or no methods.
       def instead
         return alert(NO_PROJECTS) if navigator.projects.empty?
-        return alert(["No functions or methods in #{File.basename(navigator.root)} to feel."]) if view.code_methods.empty?
 
-        celebration(view.celebration)
-      end
-
-      # Rain and fireworks over the pane when the batch is refined, then a waffle popping out, among confetti, balloons and
-      # sparkles.
-      def celebration(celebration)
-        return Scene.new(width:, height:).lines(celebration.frame) if celebration.raining?
-
-        waffle(Scene.new(width:, height:, animations: [Confetti, Balloons, Sparkles]).lines(celebration.popping), celebration.popping)
+        alert(["No functions or methods in #{File.basename(navigator.root)} to feel."])
       end
 
       # The rows of the grid around the selected method's, between blank lines that leave the first and last rows room to

data/lib/raindown/tui/layout.rb

@@ -5,6 +5,7 @@ require_relative 'text'
 require_relative 'title'
 require_relative 'project_box'
 require_relative 'search_box'
+require_relative 'feelings/celebration/celebration_renderer'
 
 module Raindown
   module TUI
@@ -49,7 +50,7 @@ module Raindown
       def lines
         return [status].first(height) if height < CHROME_HEIGHT + 1
 
-        overlaid([title, *panes, status, button_bar])
+        celebration || overlaid([title, *panes, status, button_bar])
       end
 
       # A third of the width, within NAV_WIDTH, and never more than half of a narrow screen.
@@ -59,6 +60,12 @@ module Raindown
 
       private
 
+      # Code feelings' celebration over the whole screen, while it's on.
+      def celebration
+        celebration = navigator.feelings.celebration
+        CelebrationRenderer.new(celebration, width, height).lines if celebration
+      end
+
       # The project menu or Teleport, drawn over the lines while it's open.
       def overlaid(lines)
         return ProjectBox.new(navigator, width:, column: display_width(name)).apply(lines) if navigator.menu

data/lib/raindown/tui/project.rb

@@ -46,7 +46,7 @@ module Raindown
 
       # A file's lines, headings and directives.
       def outline(path)
-        document = Document.read(path, bare: @bare)
+        document = document(path)
         Outline.new(lines: File.readlines(path, chomp: true), headings: document.headings, directives: document.directives)
       end
 
@@ -66,9 +66,12 @@ module Raindown
       # the ones whose snippet can't be read.
       def endpoints
         Projects.files(root).flat_map do |path|
-          lines = Utils.read_markdown(path).lines
-          runnable = Document.read(path, bare: @bare).directives.select { it.endpoint? && it.writes }
-          runnable.filter_map { |directive| endpoint(path, lines, directive) }
+          document = document(path)
+          # Most files have no endpoint, so they aren't parsed for one.
+          next [] unless document.markdown.include?('endpoint')
+
+          runnable = document.directives.select { it.endpoint? && it.writes }
+          runnable.filter_map { |directive| endpoint(path, document.markdown.lines, directive) }
         rescue StandardError
           []
         end
@@ -96,19 +99,28 @@ module Raindown
       end
 
       def charts_in(path)
-        content = Utils.read_markdown(path)
-        bare = @bare || BareDirectives.enabled?(path:, content:)
-        lines = content.lines
-        headings = Document.parse(content, bare:).headings
-
-        NodeBlocks.find(lines, front_matter: FrontMatter.parse(content).first, bare:)
+        document = document(path)
+        lines = document.markdown.lines
+        # Its headings are only parsed when it has a chart, as most files don't.
+        NodeBlocks.find(lines, front_matter: FrontMatter.parse(document.markdown).first, bare: document.bare)
                   .select { it[:node].respond_to?(:card_lines) }
-                  .map { |block| chart(block, path:, lines:, headings:) }
+                  .map { |block| chart(block, path:, lines:, headings: document.headings) }
       rescue StandardError => e
         @file_errors << "#{path.delete_prefix(File.join(root, ''))}: #{e.message}"
         []
       end
 
+      # The file's Document, read and parsed again only once the file's changed, so its endpoints, charts and outline
+      # share it, and finding them again only parses the files that changed.
+      def document(path)
+        stat = File.stat(path)
+        changed = [stat.mtime, stat.size]
+        cached_at, document = (@documents ||= {})[path]
+        return document if cached_at == changed
+
+        Document.read(path, bare: @bare).tap { @documents[path] = [changed, it] }
+      end
+
       def drawn
         pages = {}
         @charts.map do |chart|

data/lib/raindown/tui/renderers/endpoint_renderer.rb

@@ -12,7 +12,7 @@ module Raindown
     #    │ GET https://httpbin.org/uuid       [Run] │
     #    ╰──────────────────────────────────────────╯
     #
-    #    Response · json · fetched 2026-10-26
+    #    response 200 · 142 ms · 2026-10-26 · json
     #    {
     #      "uuid": "48024974-f1b1-431a-a0cf-5cac0099a1a5"
     #    }
@@ -73,8 +73,9 @@ module Raindown
         return [segment(" #{view.error}", :error, width:)] if view.error
         return [segment(' No response yet. X runs the request.', :heading, width:)] if view.response.empty?
 
-        details = ['Response', view.language, ("fetched #{view.fetched}" if view.fetched)].reject { it.to_s.empty? }
-        [segment(" #{details.join(' · ')}", :heading, width:)]
+        # As its comment in the file reads, or just response when it has none, then its language.
+        heading = [view.comment || 'response', view.language].reject { it.to_s.empty? }.join(' · ')
+        [segment(" #{heading}", :heading, width:)]
       end
     end
   end

data/lib/raindown/tui/terminal/loading.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../cloud'
+require_relative '../feelings/celebration/scene'
+
+module Raindown
+  module TUI
+    # The Screen's first frames, which it's prepended to: Raindown's rain cloud over the whole screen while the Navigator's
+    # made in another thread, like while Rouge loads.
+    module Loading
+      private
+
+      def start
+        super
+        loading = Thread.new(&@loading)
+        loading.report_on_exception = false
+        rain_until(loading)
+        @navigator = loading.value
+      end
+
+      # The rain cloud, a frame each animation tick, until the thread's done.
+      def rain_until(thread)
+        scene = Scene.new(width: Curses.cols, height: Curses.lines, animations: [Cloud])
+        tick = 0
+        loop do
+          draw(scene.lines(tick))
+          break if thread.join(Screen::TICKS[:animation] / 1000.0)
+
+          tick += 1
+        end
+      end
+    end
+  end
+end

data/lib/raindown/tui/terminal/screen.rb

@@ -3,6 +3,7 @@
 require 'curses'
 
 require_relative 'input'
+require_relative 'loading'
 require_relative '../layout'
 require_relative 'ncurses_shim'
 require_relative 'quiet'
@@ -15,15 +16,16 @@ module Raindown
     # Only this class draws on the terminal, so another library could draw the same Layout.
     class Screen
       prepend TerminalTitle
+      prepend Loading
 
       # How often, in milliseconds, the screen's drawn, and the open file checked for changes, while no key is pressed, by
       # the view's pace, from when the last frame started drawing: every half second while it's active, at 12 frames a
       # second while it's reactive, just faster than Code feelings' digits tremble, and at 20 during an animation.
       TICKS = { active: 500, reactive: 83, animation: 50 }.freeze
 
-      def initialize(navigator)
-        @navigator = navigator
-        @zones = []
+      # Loading makes the Navigator, while the rain cloud's drawn.
+      def initialize(&loading)
+        @loading = loading
       end
 
       def run
@@ -89,8 +91,7 @@ module Raindown
         Curses.close_screen
       end
 
-      def draw
-        lines = Layout.new(@navigator, width: Curses.cols, height: Curses.lines).lines
+      def draw(lines = Layout.new(@navigator, width: Curses.cols, height: Curses.lines).lines)
         @zones = Input.zones(lines)
         window = Curses.stdscr
         window.erase

data/lib/raindown/tui/terminal/styles.rb

@@ -2,6 +2,8 @@
 
 require 'curses'
 
+require_relative '../cloud'
+
 module Raindown
   module TUI
     # The curses attributes of a Layout's styles. Text is periwinkle where there are 256 colours, and the terminal's own
@@ -92,7 +94,7 @@ module Raindown
       def colored
         in_text_color.merge(
           title: pair(:title) | Curses::A_BOLD, directive: pair(:directive), error: pair(:error) | Curses::A_BOLD,
-          button: pair(:button) | Curses::A_BOLD, **selections, **emphasis, **dividers, **code_tokens, **bright, **files,
+          button: pair(:button) | Curses::A_BOLD, **selections, **emphasis, **dividers, **code_tokens, **bright, **cloud, **files,
           **unfocused
         )
       end
@@ -130,6 +132,8 @@ module Raindown
       # The bright colours, bold, so they're bright in 8 colours too.
       def bright = BRIGHT.keys.to_h { [it, pair(it) | Curses::A_BOLD] }
 
+      def cloud = Cloud.styles.to_h { [it, pair(it)] }
+
       # The lines between the panes and beneath the title.
       def dividers = { divider: pair(:divider) }
 
@@ -156,6 +160,7 @@ module Raindown
          *(many ? METHODS : BASIC_METHODS).map { |name, color| [:"method_#{name}", color, -1] },
          *(many ? CODE.merge(BRIGHT, FEELINGS, ACCENTS) : BASIC_CODE.merge(BASIC_BRIGHT, BASIC_FEELINGS, BASIC_ACCENTS))
            .map { |name, color| [name, color, -1] },
+         *cloud_pairs,
          [:text, text, -1],
          [:selected, white, blues[:selected]], [:felt_selected, white, blues[:felt]], [:too_small, white, many ? DARK_RED : Curses::COLOR_RED],
          [:selected_button, Curses::COLOR_YELLOW, blues[:selected]],
@@ -163,6 +168,13 @@ module Raindown
          [:shine, white, -1]]
       end
 
+      # The rain cloud's blues while the terminal UI loads, each the 256 colour its style's named after, or cyan with 8.
+      def cloud_pairs
+        return Cloud.styles.map { [it, Curses::COLOR_CYAN, -1] } if Curses.colors < 256
+
+        Cloud.styles.map { [it, it.to_s.delete_prefix('cloud_').to_i, -1] }
+      end
+
       def pair(name)
         Curses.color_pair(pairs.index { it.first == name } + 1)
       end

data/lib/raindown/tui/views/endpoint_view.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../../code_blocks'
 require_relative '../events'
 require_relative '../../workers/worker'
 
@@ -9,11 +10,11 @@ module Raindown
     # Worker when it's opened, which scrolls.
     # A key's next step, for the Navigator, is nil, an Open or Edit of its directive, or an Execute of it.
     class EndpointView
-      # The date a response was fetched, on the line after it.
-      FETCHED = /raindown:fetched (\S+)/
+      # The text of the comment above a response, like "response 200 · 142 ms · 2026-10-26".
+      COMMENT = /<!--\s*(.*?)\s*-->/
       FENCE = /\A\s*`{3,}(\S*)/
 
-      attr_reader :endpoint, :response, :language, :fetched, :error
+      attr_reader :endpoint, :response, :language, :comment, :error
 
       def initialize(endpoint, workers:)
         @endpoint = endpoint
@@ -36,7 +37,7 @@ module Raindown
       # Reads the response again, like after the request's run.
       def load
         lines = output_lines
-        @fetched = lines.pop[FETCHED, 1] if lines.last&.match?(FETCHED)
+        @comment = lines.shift[COMMENT, 1] if lines.first&.match?(CodeBlocks::RESPONSE_COMMENT)
         @language = lines.first.to_s[FENCE, 1]
         @response = @language ? lines[1...-1] : lines
         @error = nil

data/lib/raindown/tui.rb

@@ -27,12 +27,16 @@ module Raindown
       # so two projects' nodes of the same name stay apart.
       workers = Project.workers(root:, bare:, execute:)
 
-      # Rouge loads here, rather than with Raindown, which doesn't highlight code outside the TUI.
-      require 'rouge'
-      # Saved files are written back, like when the folder's watched.
-      require_relative 'tui/saves'
-      saves = Saves.new(root)
-      Screen.new(Navigator.new(root:, path: (path unless File.directory?(path)), workers:, saves:, runs_endpoints: execute)).run
+      saves = nil
+      Screen.new do
+        # Rouge loads here, rather than with Raindown, which doesn't highlight code outside the TUI, while the screen shows
+        # the rain cloud.
+        require 'rouge'
+        # Saved files are written back, like when the folder's watched.
+        require_relative 'tui/saves'
+        saves = Saves.new(root)
+        Navigator.new(root:, path: (path unless File.directory?(path)), workers:, saves:, runs_endpoints: execute)
+      end.run
       true
     ensure
       saves&.stop

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raindown
-  VERSION = '0.12.0'
+  VERSION = '0.13.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-11-04 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -251,6 +251,8 @@ files:
 - lib/raindown/rewriter.rb
 - lib/raindown/server.rb
 - lib/raindown/stat.rb
+- lib/raindown/table/markdown_table.rb
+- lib/raindown/table/table.rb
 - lib/raindown/table_formatter.rb
 - lib/raindown/toc.rb
 - lib/raindown/tui.rb
@@ -262,6 +264,7 @@ files:
 - lib/raindown/tui/blueprints/traced_code.rb
 - lib/raindown/tui/blueprints/tracing.rb
 - lib/raindown/tui/card.rb
+- lib/raindown/tui/cloud.rb
 - lib/raindown/tui/code_box.rb
 - lib/raindown/tui/endpoint.rb
 - lib/raindown/tui/endpoints.rb
@@ -269,6 +272,7 @@ files:
 - lib/raindown/tui/feelings/batch.rb
 - lib/raindown/tui/feelings/bins.rb
 - lib/raindown/tui/feelings/celebration/celebration.rb
+- lib/raindown/tui/feelings/celebration/celebration_renderer.rb
 - lib/raindown/tui/feelings/celebration/fireworks.rb
 - lib/raindown/tui/feelings/celebration/rain.rb
 - lib/raindown/tui/feelings/celebration/scene.rb
@@ -308,6 +312,7 @@ files:
 - lib/raindown/tui/saves.rb
 - lib/raindown/tui/search_box.rb
 - lib/raindown/tui/terminal/input.rb
+- lib/raindown/tui/terminal/loading.rb
 - lib/raindown/tui/terminal/ncurses_shim.rb
 - lib/raindown/tui/terminal/quiet.rb
 - lib/raindown/tui/terminal/screen.rb