raindown 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad2e1df6e9cbfbac50533a9d6dd7f1d8bedb254aa6277a1889fb380871c52ec1
-  data.tar.gz: d32bbefdbcae559679033db6b1fc7e1dc4846f6a6356c0944e711cf50699eab0
+  metadata.gz: 7683978b726d755dec718ef81848047c736e081504baeec609b5bbfadb1cb72c
+  data.tar.gz: 00e4387dd70604a382a7ad02944df5ac48718c5c90d1994c384011821153404c
 SHA512:
-  metadata.gz: 0dd6247d9f49558b5dc53b9eae6860d841c34c1e03edbaca61ba02ff59ec59a932d647c7f70eff731b1fe195ece4f3d2e999be2a783e0e9f1b57f97a166a5b25
-  data.tar.gz: bfc9d3fed994284ae6f0ec94a51e6599a754e1064e648092e595bd80d6224f8f4acc4e258a790de9fe5bbb9e9cfe07ede3d4c6d7bd633c3574ff9f8ec9a3e90a
+  metadata.gz: 7e411970cde88fcf026aeea5c2eb1a7a2566ca99ba32c5920e6e53013f3e6b39f42a5449d8ecb36061a4dac5518a82516e21c54595c6d54c9906830f64f0c929
+  data.tar.gz: 1a517a2cc89afa59c9deca7b662a415712eff5a81ad1a6caa339c411fb7c4f154c1b95e0456d86c07473519a00624e94f4eeeb2548c9cad3df5690852860dc0c

data/lib/nodes/endpoint_node.rb

@@ -6,7 +6,8 @@ require_relative '../raindown/fragments'
 
 module Raindown
   # Holds an endpoint's curl snippet and response, which render as the code blocks they are,
-  # between Directives markers for its directive and end tag, kept as a fragment.
+  # between hidden Directives markers for its directive and end tag, kept as a fragment. A bare endpoint has markers
+  # in bold around it too, from BareDirectives.
   class EndpointNode < Antlers::BranchNode
     DEF_KEY = :endpoint_def
     END_KEY = :endpoint_end
@@ -19,7 +20,7 @@ module Raindown
 
     def render(**)
       html = Raindown.commonmark(super)
-      Fragments.add("#{Directives.marker(@directive)}\n#{html}#{Directives.marker(':endpoint')}")
+      Fragments.add("#{Directives.marker(@directive, shown: false)}\n#{html}#{Directives.marker(':endpoint', shown: false)}")
     end
 
     class << self

data/lib/raindown/actions.rb

@@ -20,14 +20,16 @@ module Raindown
 
     module_function
 
-    # Writes back the whole file, like saving it while it's watched.
-    def write_back(path)
-      Rewriter.update(path:, metadata: Pages.for(path))
+    # Writes back the whole file, like saving it while it's watched, with bare directives allowed, and endpoints with no
+    # response run, when asked, like with --bare and -x.
+    def write_back(path, bare: false, execute: false)
+      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
     end
 
     # Runs one endpoint's request and writes its response, replacing any response it had.
     def execute(path, directive)
       raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
+      raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
 
       content = File.read(path, encoding: Encoding::UTF_8)
       rewritten = EndpointRunner.new(content:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite

data/lib/raindown/bare_directives.rb

@@ -1,27 +1,26 @@
 # frozen_string_literal: true
 
 require_relative 'code_blocks'
+require_relative 'directives'
 require_relative 'front_matter'
 
 module Raindown
-  # Raindown files (.rd/.raindown) can write a directive like <{ if: draft }> as a bare if: draft on its own line.
-  # Markdown files opt in with "raindown: true" in their front matter, or with the --bare flag.
-  # Nodes like toc: and files: are handled by NodeBlocks, before the rest.
+  # Raindown files (.rd/.raindown) can write a content directive, which writes its output back, bare on its own line,
+  # like endpoint: or toc:, which shows in bold in the HTML. Markdown files opt in with "raindown: true" in their front
+  # matter, or with the --bare flag. Nodes like toc: and files: are handled by NodeBlocks, before the rest.
+  # Template directives, like if: and for:, are always in Antlers' delimiters, so they're never bare.
   #
-  # Bare directives have no end tag. A bare block directive closes itself after the content it applies to,
-  # so where a block needs to wrap more than that, write it with delimiters and an end tag instead:
-  #   <{ if: draft }>
+  # 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:
+  #   <!-- endpoint: -->
   #   ...
-  #   <{ :if }>
+  #   <!-- :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, 'for:' => :after_block, 'if:' => :after_block,
-                       'list:' => :after_block }.freeze
+    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]*$/
-    # An end tag on its own line, like one a bare block directive above added, ends a block.
-    END_TAG = /\A {0,3}<\{\s*:[a-z][\w-]*\s*\}>[ \t]*$/
 
     module_function
 
@@ -69,34 +68,22 @@ module Raindown
       match = lines[index].match(LINE)
       return index unless match
 
-      lines[index] = wrap(lines[index])
+      lines[index] = "#{Directives.marker(match[2], shown: true)}\n#{wrap(lines[index])}"
       close_block(lines, index, indent: match[1], keyword: match[3])
       index
     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
       lines[last] = "#{lines[last]}\n" unless lines[last].end_with?("\n")
-      lines.insert(last + 1, "#{indent}<{ :#{keyword.delete_suffix(':')} }>\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)
     end
-
-    # The last line of the Markdown block below, after any blank lines: up to the next blank line or end tag,
-    # with fenced code kept whole. Nil when there's nothing below.
-    def after_block(lines, index)
-      index = CodeBlocks.skip_blank_lines(lines, index)
-      last = nil
-
-      while index < lines.length && !lines[index].strip.empty? && !lines[index].match?(END_TAG)
-        last = CodeBlocks.at(lines, index)&.fetch(:close) || index
-        index = last + 1
-      end
-
-      last
-    end
   end
 end

data/lib/raindown/blueprints.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'unicode/display_width'
+require_relative 'projects'
+
+module Raindown
+  # Blueprints from Claude Code's replies, kept in a project's .raindown/blueprints.md, which the terminal UI's Blueprints page
+  # shows, newest first. Each is a code block under a heading of when it was saved and its kind:
+  #   ## 2026-10-30T03:14:07Z · mockup
+  #
+  #   ```mockup
+  #   ╭──────╮
+  #   │ Idea │
+  #   ╰──────╯
+  #   ```
+  # A blueprint is a code block marked with its kind, like "mockup", or one with no language that's drawn, with box-drawing
+  # lines or blocks, whose kind is worked out from what it's drawn with when it's saved (see Blueprints.kind).
+  module Blueprints
+    # A blueprint, saved at a time, or drawn in a comment in the code, in the file at its path, from the project's root,
+    # from its line, with the paragraph above it, if there was one, as its description.
+    Blueprint = Data.define(:time, :kind, :lines, :path, :line, :description) do
+      # Its description and words, without the lines drawn among them, which its filter matches and lists it by.
+      def words = [description, *lines].join(' ').gsub(DRAWN, ' ').squeeze(' ').strip
+      alias_method :text, :words
+
+      # When it was saved, to the minute, or where it's drawn in the code, and its kind.
+      def where
+        return "#{path}:#{line}#{SEPARATOR}#{kind}" unless time
+
+        "#{time.sub('T', ' ').sub(/:\d\dZ\z/, ' UTC')}#{SEPARATOR}#{kind}"
+      end
+
+      # As it's saved in .raindown/blueprints.md, under when it was saved and its kind, then its description.
+      def markdown(saved_at)
+        about = "#{description}\n\n" if description
+        "## #{saved_at}#{SEPARATOR}#{kind}\n\n#{about}```#{kind}\n#{lines.join("\n")}\n```\n\n"
+      end
+    end
+    # A box drawn in a blueprint, by the rows and columns of its corners, as a terminal shows them, and the text inside it and in
+    # its top border, like a card's title.
+    Box = Data.define(:top, :left, :bottom, :right, :text) do
+      def cover?(row, column) = row.between?(top, bottom) && column.between?(left, right)
+      def above?(other) = bottom < other.top
+      def below?(other) = top > other.bottom
+
+      # How far it is from the other box, in rows, then in columns between their middles.
+      def distance(other) = [(top - other.top).abs, (left + right - other.left - other.right).abs]
+    end
+
+    FILE = File.join('.raindown', 'blueprints.md')
+    # The kinds a code block can be marked with to be a blueprint.
+    KINDS = %w[mockup diagram chart table other].freeze
+    # What a blueprint's drawn with: lines, like boxes' and arrows', and blocks, like charts' bars.
+    LINES = /[─━│┃┌┐└┘├┤┬┴┼╭╮╯╰═║╔╗╚╝╱╲]/
+    BLOCKS = /[▁▂▃▄▅▆▇█▀▏▔▕░▒▓]/
+    DRAWN = Regexp.union(LINES, BLOCKS)
+    BLOCK = /^```(\w*)\n(.*?)^```$/m
+    # Arrows that join things, across, which make a blueprint a diagram, like a flow chart's or a sequence diagram's.
+    ACROSS = /─▶|◀─|─>|<─|->|<-|[→←↔]/
+    # Arrows that join things up or down, when there's a line above or below them.
+    UP_DOWN = %w[▼ ▲].freeze
+    # The share of a blueprint's characters that are blocks, from which it's a chart.
+    CHART = 0.25
+    SEPARATOR = ' · '
+    # A box's corners, and the lines its left side is drawn with.
+    TOP_LEFT = %w[╭ ┌ ╔].freeze
+    TOP_RIGHT = %w[╮ ┐ ╗].freeze
+    BOTTOM_LEFT = %w[╰ └ ╚].freeze
+    BOTTOM_RIGHT = %w[╯ ┘ ╝].freeze
+    SIDE = %w[│ ├ ┤ ┼ ║ ╟ ╢].freeze
+
+    module_function
+
+    # The project's blueprints, newest first, each with the line its drawing starts on, counting from 1, like an editor.
+    def read(root)
+      path = File.join(root, FILE)
+      return [] unless File.exist?(path)
+
+      lines = File.readlines(path, chomp: true)
+      starts = lines.each_index.select { lines[it].start_with?('## ') }
+      starts.filter_map { |start| blueprint(lines, start) }.reverse
+    end
+
+    # Saves the blueprints in Claude Code's last reply, from its Stop hook's JSON, to the project it's working in, if any,
+    # each with its kind.
+    def save(hook)
+      root = Projects.root(hook['cwd'].to_s) || return
+      drawn = drawn(last_reply(hook['transcript_path'].to_s))
+      return if drawn.empty?
+
+      time = Time.now.utc.iso8601
+      File.open(File.join(root, FILE), 'a') { |file| drawn.each { file.write(it.markdown(time)) } }
+    end
+
+    # The text's code blocks that are blueprints, each with its kind and the paragraph above it.
+    def drawn(text)
+      text.to_enum(:scan, BLOCK).filter_map do
+        language, body = Regexp.last_match.captures
+        lines = body.lines(chomp: true)
+        next unless whole?(lines)
+
+        kind = drawn_kind(language, lines) || next
+        Blueprint.new(time: nil, kind:, lines:, path: FILE, line: nil, description: description(text[0...Regexp.last_match.begin(0)]))
+      end
+    end
+
+    # The kind the block's marked with, or, without a language, the kind it's drawn as, or nil when it isn't drawn.
+    def drawn_kind(language, lines)
+      return language if KINDS.include?(language)
+
+      kind(lines) if language.empty? && lines.join.match?(DRAWN)
+    end
+
+    # The paragraph at the end of the text before a block, joined into a line, unless it's another block, or a list.
+    def description(before)
+      paragraph = before.split(/\n[ \t]*\n/).last.to_s.strip
+      return if paragraph.empty? || paragraph.include?('```') || paragraph.match?(/\A(?:[-*+] |\d+\. |#)/)
+
+      paragraph.split("\n").map(&:strip).join(' ')
+    end
+
+    # Whether a drawing's more than a line, and closes each box its first line opens, unlike a piece of one quoted, and
+    # isn't art.
+    def whole?(lines)
+      return false if lines.length < 2 || art?(lines)
+
+      boxes(lines).count { it.top.zero? } == columns(lines.first(1)).first.count { TOP_LEFT.include?(it) }
+    end
+
+    # What a blueprint is, from what it's drawn with: a diagram when arrows join its parts, a chart when it's mostly blocks,
+    # a table when its lines cross, a mockup when it's otherwise boxes and lines, and other when it's none of those.
+    def kind(lines)
+      text = lines.join("\n")
+      return 'diagram' if text.match?(ACROSS) || joined_up_or_down?(lines)
+      return 'chart' if text.scan(BLOCKS).length >= CHART * text.delete(" \n").length
+      return 'table' if text.include?('┼')
+      return 'mockup' if text.match?(DRAWN)
+
+      'other'
+    end
+
+    # Whether an up or down arrow has a line above or below it, joining it to what it points from.
+    def joined_up_or_down?(lines)
+      lines.each_with_index.any? do |line, index|
+        line.each_char.with_index.any? do |char, column|
+          UP_DOWN.include?(char) && [lines[index - 1], lines[index + 1]].any? { it&.[](column) == '│' }
+        end
+      end
+    end
+
+    # Whether it's art: drawn in blocks and words but no lines, like a stat's number in block digits, or a waffle, or
+    # with no words or numbers at all, like rain or balloons.
+    def art?(lines)
+      text = lines.join
+      !text.match?(/[[:alnum:]]/) || (text.match?(BLOCKS) && !text.match?(LINES))
+    end
+
+    # The boxes drawn in the blueprint's lines, in reading order, each a top-left corner, the next top-right corner along its
+    # row, and the bottom corners below them, its left side drawn down to the bottom.
+    def boxes(lines)
+      grid = columns(lines)
+      grid.each_with_index.flat_map do |row, top|
+        row.each_index.filter_map { |left| box(grid, top, left) if TOP_LEFT.include?(row[left]) }
+      end
+    end
+
+    def box(grid, top, left)
+      corner = (left + 1...grid[top].length).find { TOP_RIGHT.include?(grid[top][it]) } || return
+      bottom = (top + 1...grid.length).find { !SIDE.include?(grid[it][left]) } || return
+      right = bottom_right(grid[bottom], left, corner) || return
+
+      Box.new(top:, left:, bottom:, right:, text: box_text(grid[top...bottom], left, right))
+    end
+
+    # The lines' characters by the columns a terminal shows them in, with an empty string in the second column of a wide
+    # one, like an emoji, so what's drawn below it lines up.
+    def columns(lines)
+      lines.map { |line| line.grapheme_clusters.flat_map { [it, *Array.new([Unicode::DisplayWidth.of(it) - 1, 0].max, '')] } }
+    end
+
+    # The column of the box's bottom right corner, below its top's, or a column either side, as Claude Code sometimes draws
+    # a box's top a column short or long, or nil when the row isn't its bottom.
+    def bottom_right(row, left, corner) = [corner, corner + 1, corner - 1].find { closed?(row, left, it) }
+
+    # The grid with each box's right side straight down from its bottom right corner, as Claude Code sometimes draws a
+    # box's top, or a row of it, a column short or long, leaving the text inside it as it is.
+    def tidied(grid, boxes)
+      grid = grid.map(&:dup)
+      boxes.each do |box|
+        straighten(grid[box.top], box.right, TOP_RIGHT, '─')
+        (box.top + 1...box.bottom).each { straighten(grid[it], box.right, SIDE, ' ') }
+      end
+      grid
+    end
+
+    # Moves the row's edge, one of the edges, from a column either side of the right one, filling where it was, when
+    # what's at the right column is blank.
+    def straighten(row, right, edges, fill)
+      return if edges.include?(row[right]) || !row[right].to_s.strip.empty?
+
+      off = [right - 1, right + 1].find { edges.include?(row[it]) } || return
+      row[right] = row[off]
+      row[off] = fill
+    end
+
+    # Whether the row is a box's bottom, from its left corner to its right.
+    def closed?(row, left, right) = BOTTOM_LEFT.include?(row[left]) && BOTTOM_RIGHT.include?(row[right])
+
+    # The text across the rows, between the box's sides, without the lines drawn among it.
+    def box_text(rows, left, right) = rows.map { it[(left + 1)...right].to_a.join }.join(' ').gsub(DRAWN, ' ').squeeze(' ').strip
+
+    # The text of the assistant's messages since the last thing the user typed, in a transcript of JSON lines.
+    def last_reply(path)
+      return '' unless File.exist?(path)
+
+      entries = File.readlines(path).filter_map { entry(it) }
+      asked = entries.rindex { it['type'] == 'user' && typed?(it.dig('message', 'content')) } || -1
+      entries[(asked + 1)..].select { it['type'] == 'assistant' }.flat_map { texts(it.dig('message', 'content')) }.join("\n")
+    end
+
+    # A line of the transcript, or nil for one that isn't JSON, like one still being written.
+    def entry(line)
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # A user's message is typed when it's text, rather than a tool's result.
+    def typed?(content) = content.is_a?(String) || Array(content).any? { it['type'] == 'text' }
+
+    def texts(content) = Array(content).filter_map { it['text'] if it.is_a?(Hash) && it['type'] == 'text' }
+
+    def blueprint(lines, start)
+      opening = (start + 1...lines.length).find { lines[it].start_with?('```') } || return
+      closing = (opening + 1...lines.length).find { lines[it] == '```' } || return
+      Blueprint.new(**heading(lines[start]), lines: lines[(opening + 1)...closing], path: FILE, line: opening + 2,
+                                             description: saved_description(lines[(start + 1)...opening]))
+    end
+
+    # When a blueprint was saved and its kind, from its heading, which is other when it's none of the kinds.
+    def heading(line)
+      time, kind = line.delete_prefix('## ').split(SEPARATOR, 2)
+      kind = 'other' unless KINDS.include?(kind)
+      { time:, kind: }
+    end
+
+    # The lines between a blueprint's heading and its drawing, joined, or nil when there are none.
+    def saved_description(lines)
+      description = lines.reject(&:empty?).join(' ')
+      description unless description.empty?
+    end
+  end
+end

data/lib/raindown/cli.rb

@@ -4,9 +4,10 @@ require 'fileutils'
 require 'trees'
 require_relative '../raindown'
 require_relative '../version'
+require_relative 'blueprints'
 require_relative 'rewriter'
-require_relative 'supervisor'
-require_relative 'watcher'
+require_relative 'watcher/file_watcher'
+require_relative 'watcher/supervisor'
 
 module Raindown
   module CLI
@@ -14,24 +15,28 @@ module Raindown
 
     USAGE = <<~TEXT
       Usage: raindown [PATH] [options]
-             raindown FILE --html [OUTPUT]
+             raindown watch [PATH] [options]
+             raindown FILE --html [OUTPUT] [options]
              raindown init [DIRECTORY]
-             raindown tui [PATH]
 
-      Watches PATH and writes back to its Markdown files as they're saved, like their tables of contents and tables.
-      PATH is a file, or a directory (default: current directory) whose projects with a .raindown folder are watched.
+      Opens PATH (default: current directory) in the terminal UI: browse a project's files and outlines, fold
+      directives, run endpoints, open the editor at a line and see a dashboard of the project's charts. While it's open,
+      it watches the folder and writes back to its Markdown files as they're saved, like their tables of contents.
 
       Commands:
+        watch [PATH]        Watch PATH without the terminal UI, writing back to its Markdown files as they're saved.
+                            PATH is a file, or a directory (default: current directory) whose projects with a
+                            .raindown folder are watched
         init [DIRECTORY]    Create a .raindown folder for the project's config and nodes (default: current directory)
-        tui [PATH]          Browse a project's files and outlines in the terminal, fold directives, run endpoints,
-                            open the editor at a line and see a dashboard of the project's charts
+        blueprints            Save the blueprints in Claude Code's last reply to .raindown/blueprints.md, for the terminal
+                            UI's Blueprints page, as a Stop hook that's given the hook's JSON
 
       Options:
         --html [OUTPUT]     Render FILE to HTML once, writing to OUTPUT or else printing to stdout
         --stdin             Render Markdown from stdin to HTML once, without formatting FILE, which only needs
                             its extension (to allow bare directives) and can be unsaved. Add --html OUTPUT to write a file
         --bare              Allow bare directives like :toc in Markdown files
-        -x, --execute       Run endpoint curl snippets that have no output yet
+        -x, --execute       Run endpoint curl snippets that have no output yet, as files are written back
         -h, --help          Show this message
         -v, --version       Show the version
 
@@ -41,61 +46,40 @@ module Raindown
     CONFIG = <<~YAML
       # Raindown project settings. See https://raindown.dev/docs/config
       #
-      # Show directives as HTML comments rather than in bold:
-      # hide_directives: true
-      #
       # Leave code blocks unhighlighted, so the browser can highlight them instead:
       # highlight_code: false
     YAML
 
-    # "--html OUTPUT" is matched as "--html-to OUTPUT" (see run), so a flag after a bare --html isn't read as the OUTPUT.
-    OPTIONS = { html_to: ['--html-to :output'], html: ['--html'], bare: ['--bare'], execute: ['-x', '--execute'],
-                stdin: ['--stdin'] }.freeze
-
-    # Trees matches tokens in order, so there's a line for every order and spelling of the options.
-    OPTION_LINES = (0..OPTIONS.size).flat_map { |count| OPTIONS.keys.permutation(count).to_a }.flat_map do |names|
-      [[]].product(*names.map { |name| OPTIONS[name] }).map { |flags| [names, flags.flatten] }
+    # A path opens the terminal UI, or after "watch" it's watched, and with --html or --stdin it's rendered. The flags
+    # are keyword arguments, in any order, like -x for x:, and --html is the OUTPUT when it's given one.
+    line(':path') do |path, html: nil, stdin: false, bare: false, execute: false, x: false| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
+      execute { open_path(path, html:, stdin:, bare:, execute: execute || x) }
     end
 
-    OPTION_LINES.each do |names, flags|
-      # Endpoints run while formatting, which --stdin skips.
-      next if names.include?(:stdin) && names.include?(:execute)
-      next if names.include?(:html) && names.include?(:html_to)
-
-      command = if names.include?(:stdin) then :render_stdin
-                elsif names.intersect?(%i[html html_to]) then :render
-                else :watch
-                end
-      options = { bare: names.include?(:bare), execute: names.include?(:execute) }
-      pattern = [':path', *flags].join(' ')
-
-      if names.include?(:html_to)
-        line(pattern) { |path, output| execute { send(command, path, output, **options) } }
-      else
-        line(pattern) { |path| execute { send(command, path, **options) } }
-      end
+    line('watch :path') do |path, bare: false, execute: false, x: false|
+      execute { watch(path, bare:, execute: execute || x) }
     end
 
     def self.run(argv)
       return if command(argv)
 
-      # Without a path, like "raindown" or "raindown -x", the current directory is watched.
+      # Without a path, like "raindown", "raindown -x" or "raindown watch", it's the current directory.
+      argv = ['watch', '.', *argv.drop(1)] if argv.first == 'watch' && (argv.size == 1 || argv[1].start_with?('-'))
       argv = ['.', *argv] if argv.empty? || argv.first.start_with?('-')
-      argv = html_output(argv)
 
       super || abort("Unknown arguments: #{argv.join(' ')}\n\n#{USAGE}")
     rescue StandardError => e
       report(e, path: argv.first)
     end
 
-    # The :path line would match help, version, init and tui as the file, so they're checked first.
+    # The :path line would match help, version and init as the file, so they're checked first.
     # Returns true when argv was one of them.
     def self.command(argv)
       abort(USAGE) if argv.intersect?(%w[-h --help])
 
       if argv.intersect?(%w[-v --version]) then puts(VERSION)
       elsif argv.first == 'init' && argv.size <= 2 then init(argv[1])
-      elsif argv.first == 'tui' && argv.size <= 2 then tui(argv[1] || '.')
+      elsif argv == ['blueprints'] then Blueprints.save(JSON.parse($stdin.read))
       else return false
       end
 
@@ -109,15 +93,6 @@ module Raindown
       abort("raindown: #{path}: #{error.message}")
     end
 
-    # "--html out.html" names an OUTPUT, while "--html --bare" doesn't, as OUTPUT never starts with "-".
-    def self.html_output(argv)
-      index = argv.index('--html') || (return argv)
-      output = argv[index + 1]
-      return argv if output.nil? || output.start_with?('-')
-
-      [*argv[0...index], '--html-to', *argv[(index + 1)..]]
-    end
-
     # Creates the .raindown folder that marks a project's root and holds its config.yml and nodes.
     def self.init(directory = nil)
       folder = File.join(directory || Dir.pwd, Nodes::FOLDER)
@@ -130,17 +105,27 @@ module Raindown
       puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/nodes'
     end
 
-    # The terminal UI loads curses, so it's only required when it starts.
-    def self.tui(path)
+    # The terminal UI loads curses, so it's only required when it starts. Without a terminal, the path's watched instead.
+    def self.tui(path, bare: false, execute: false)
       abort("File not found: #{path}") unless File.exist?(path)
 
       require_relative 'tui'
-      TUI.start(path)
+      TUI.start(path, bare:, execute:) || watch(path, bare:, execute:)
     end
 
     class << self
       private
 
+      # Endpoints run while formatting, which --stdin skips, so -x can't go with it.
+      def open_path(path, html:, stdin:, bare:, execute:)
+        output = html unless html == true
+        abort("-x runs endpoints as the file's formatted, which --stdin doesn't do\n\n#{USAGE}") if stdin && execute
+        return render_stdin(path, output, bare:) if stdin
+        return render(path, output, bare:, execute:) if html
+
+        tui(path, bare:, execute:)
+      end
+
       def render(path, output = nil, bare: false, execute: false)
         ensure_exists(path)
         abort('--html renders a file, not a directory') if File.directory?(path)
@@ -160,10 +145,10 @@ module Raindown
       # Watching only writes back to the files, while --html and --stdin render HTML.
       def watch(path, bare: false, execute: false)
         ensure_exists(path)
-        return Supervisor.new(directory: path, bare:, execute:).start if File.directory?(path)
+        return Watcher::Supervisor.new(directory: path, bare:, execute:).start if File.directory?(path)
 
         Nodes.load(path)
-        Watcher.new(path:, bare:, execute:).start
+        Watcher::FileWatcher.new(path:, bare:, execute:).start
       end
 
       def write(output, html)

data/lib/raindown/config.rb

@@ -4,11 +4,10 @@ require 'yaml'
 
 module Raindown
   # A project's settings, from config.yml in its .raindown folder:
-  #   hide_directives: true    # Directives become HTML comments rather than bold text in the HTML.
   #   highlight_code: false    # Code blocks aren't highlighted, so the browser can highlight them instead.
   module Config
     FILE = 'config.yml'
-    DEFAULTS = { hide_directives: false, highlight_code: true }.freeze
+    DEFAULTS = { highlight_code: true }.freeze
 
     module_function
 
@@ -23,7 +22,7 @@ module Raindown
 
     # The settings for rendering a file, like Raindown.render(**Config.render_options(path)).
     def render_options(path)
-      self.for(path).slice(:hide_directives, :highlight_code)
+      self.for(path).slice(:highlight_code)
     end
   end
 end

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