raindown 0.7.0 → 0.8.0

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

@@ -4,18 +4,22 @@ require 'curses'
 
 require_relative 'input'
 require_relative '../layout'
-require_relative 'quiet'
 require_relative 'ncurses_shim'
+require_relative 'quiet'
 require_relative 'styles'
+require_relative 'terminal_title'
 
 module Raindown
   module TUI
     # Paints a Navigator's Layout with curses, and sends the Navigator the events of keys and clicks, read with Input.
     # Only this class draws on the terminal, so another library could draw the same Layout.
     class Screen
-      # How often, in milliseconds, the open file is checked for changes while no key is pressed, or, while the view
-      # animates, like Code feelings' rain, it's drawn.
-      TICKS = { false => 500, true => 60 }.freeze
+      prepend TerminalTitle
+
+      # 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
@@ -32,11 +36,9 @@ module Raindown
         start
 
         loop do
+          drawn_at = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
           draw
-          effect = @navigator.next_step(read)
-          break if effect == :quit
-
-          perform(effect)
+          break if take_events(drawn_at) == :quit
         end
       rescue Interrupt
         nil
@@ -44,6 +46,23 @@ module Raindown
         stop
       end
 
+      # The Navigator takes the next event, then any others already waiting, like the mouse's many moves, before the
+      # screen's drawn again, so drawing doesn't fall further and further behind them.
+      def take_events(drawn_at)
+        event = Input.read(wait(drawn_at), zones: @zones, typing: @navigator.typing?)
+        loop do
+          effect = @navigator.next_step(event)
+          return effect if effect == :quit
+
+          perform(effect)
+          event = Input.read(0, zones: @zones, typing: @navigator.typing?)
+          return if event == :tick
+        end
+      end
+
+      # The milliseconds left of the pace's tick since the frame started drawing, so drawing doesn't slow the pace.
+      def wait(drawn_at) = [TICKS.fetch(@navigator.pace) + drawn_at - Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond), 0].max
+
       # Runs a command, like the editor, then tells the Navigator, or shows a message while a slow task runs.
       def perform(effect)
         case effect
@@ -105,23 +124,6 @@ module Raindown
         [*rest, last.with(text: last.text[0...-1])]
       end
 
-      # The next event, or :tick when no key is pressed in time, or nil for keys without one, like a resize.
-      def read
-        Curses.stdscr.timeout = TICKS.fetch(@navigator.animating?)
-        key = Curses.stdscr.getch
-        return :tick if key.nil?
-        return mouse if key == Curses::KEY_MOUSE
-
-        Curses.stdscr.clear if key == Curses::KEY_RESIZE
-        Input.key_event(key, typing: @navigator.typing?)
-      end
-
-      # The curses gem warns the first time it makes a MouseEvent, that it's "undefining the allocator" of the class.
-      def mouse
-        event = Quiet.quietly { Curses.getmouse }
-        Input.mouse_event(event, @zones) if event
-      end
-
       # Shows a message in the status line while something slow runs, like an endpoint's request.
       def show(message)
         window = Curses.stdscr
@@ -132,13 +134,16 @@ module Raindown
       end
 
       # Leaves the screen to the command, like the editor, and comes back to it after. The command isn't sent the
-      # mouse's moves meanwhile.
+      # mouse's moves meanwhile. Ctrl+C, like to leave Claude Code, goes to the TUI too, which waits for the command
+      # rather than quitting, while the command gets Ctrl+C as usual.
       def suspend
+        interrupt = trap('INT') { nil }
         Curses.def_prog_mode
         Input.untrack_mouse
         Curses.close_screen
         yield
       ensure
+        trap('INT', interrupt)
         Curses.reset_prog_mode
         Input.track_mouse
         Curses.stdscr.clear

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

@@ -5,7 +5,8 @@ require 'curses'
 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
-    # colour otherwise, like the line between the panes, while the title and headings are cornflower blue. The selected
+    # colour otherwise, while the title, headings, and the lines between the panes and beneath the title are cornflower
+    # blue. The selected
     # row is white on blue, or on dark grey in the panes without the focus, while other colours are on the terminal's own
     # background.
     # With only 8 colours, there's no dark grey, so those rows are underlined, and without colours,
@@ -13,23 +14,31 @@ module Raindown
     module Styles
       COLORS = { button: Curses::COLOR_YELLOW, error: Curses::COLOR_RED }.freeze
       # Directives, like charts' on the Dashboard, in purple, and the folders, projects and pages in the files, the title,
-      # and headings, like the outline's and the Dashboard cards', in cornflower blue, from the 256 colours most terminals
+      # and headings, like the outline's and the Dashboard cards', in cornflower blue, and the waffle's syrup in brown,
+      # from the 256 colours most terminals
       # have, or magenta and blue with 8.
-      ACCENTS = { directive: 141, folder: 111, title: 111, heading: 111 }.freeze
+      CORNFLOWER = 111
+      ACCENTS = { directive: 141, folder: CORNFLOWER, title: CORNFLOWER, heading: CORNFLOWER, syrup: 130 }.freeze
       BASIC_ACCENTS = { directive: Curses::COLOR_MAGENTA, folder: Curses::COLOR_BLUE, title: Curses::COLOR_BLUE,
-                        heading: Curses::COLOR_BLUE }.freeze
+                        heading: Curses::COLOR_BLUE, syrup: Curses::COLOR_YELLOW }.freeze
+
+      # The green of GET, and of a selected method in Code feelings that's already been felt.
+      GREEN = 34
+
       # The colours of endpoints' HTTP methods, like GET in green, from the 256 colours most terminals have,
       # which are the same in every theme, unlike the 8 they all do, where green can look yellow.
-      METHODS = { get: 40, post: 33, delete: 196, put: 220, patch: 171, head: 44, options: 44 }.freeze
+      METHODS = { get: GREEN, post: 33, delete: 196, put: 220, patch: 171, head: 44, options: 44 }.freeze
       BASIC_METHODS = { get: Curses::COLOR_GREEN, post: Curses::COLOR_BLUE, delete: Curses::COLOR_RED,
                         put: Curses::COLOR_YELLOW, patch: Curses::COLOR_MAGENTA, head: Curses::COLOR_CYAN,
                         options: Curses::COLOR_CYAN }.freeze
+
       # Highlighted code's colours, by the kind of token, from the 256 colours most terminals have, or the 8 they all do,
       # where comments are dim instead of grey.
       CODE = { code_keyword: 204, code_string: 114, code_number: 179, code_function: 75, code_constant: 117,
                code_comment: 244 }.freeze
       BASIC_CODE = { code_keyword: Curses::COLOR_MAGENTA, code_string: Curses::COLOR_GREEN, code_number: Curses::COLOR_YELLOW,
                      code_function: Curses::COLOR_BLUE, code_constant: Curses::COLOR_CYAN, code_comment: Curses::COLOR_WHITE }.freeze
+
       # Code feelings' bright colours, for its rain and fireworks, from the 256 colours most terminals have, or
       # the 8 they all do.
       BRIGHT = { bright_red: 203, bright_orange: 215, bright_yellow: 227, bright_green: 120, bright_cyan: 87,
@@ -37,17 +46,26 @@ module Raindown
       BASIC_BRIGHT = { bright_red: Curses::COLOR_RED, bright_orange: Curses::COLOR_YELLOW, bright_yellow: Curses::COLOR_YELLOW,
                        bright_green: Curses::COLOR_GREEN, bright_cyan: Curses::COLOR_CYAN, bright_blue: Curses::COLOR_BLUE,
                        bright_purple: Curses::COLOR_MAGENTA, bright_pink: Curses::COLOR_MAGENTA }.freeze
-      # The selected row's blue, from the 256 colours most terminals have, or the 8 they all do.
-      BLUES = { selected: 33 }.freeze
-      BASIC_BLUES = { selected: Curses::COLOR_CYAN }.freeze
+
+      # The selected row's blue, the green of a selected method in Code feelings that's already been felt, and the
+      # cornflower blue of the lines between the panes and beneath the title, from the 256 colours most terminals have,
+      # or the 8 they all do.
+      BLUES = { selected: 33, felt: GREEN, line: CORNFLOWER }.freeze
+      BASIC_BLUES = { selected: Curses::COLOR_CYAN, felt: Curses::COLOR_GREEN, line: Curses::COLOR_BLUE }.freeze
+
       # Text that has no colour of its own, from the 256 colours most terminals have, or the terminal's own with 8.
       PERIWINKLE = 147
-      # Code feelings' text and lines, the Dashboard cards' charts, and code blocks, in lavender, or magenta in 8 colours.
-      FEELINGS = { feelings: 183 }.freeze
-      BASIC_FEELINGS = { feelings: Curses::COLOR_MAGENTA }.freeze
+
+      # Code feelings' text and lines, in lavender, or magenta in 8 colours, and the purple its magnified digits take turns
+      # with, or blue.
+      FEELINGS = { feelings: 183, feelings_purple: 135 }.freeze
+      BASIC_FEELINGS = { feelings: Curses::COLOR_MAGENTA, feelings_purple: Curses::COLOR_BLUE }.freeze
       BRIGHT_WHITE = 15
       DARK_GREY = 238
 
+      # Code feelings' red when the screen's too small for it, or the 8 colours' red.
+      DARK_RED = 88
+
       module_function
 
       # Sets up the colours, once the screen has started, and returns the attribute of each style.
@@ -61,24 +79,32 @@ module Raindown
       # Without colours, a style that isn't here is the terminal's own.
       def plain
         Hash.new(Curses::A_NORMAL).merge(
-          title: Curses::A_REVERSE | Curses::A_BOLD, selected: Curses::A_REVERSE, selected_button: Curses::A_REVERSE,
+          title: Curses::A_REVERSE | Curses::A_BOLD, selected: Curses::A_REVERSE, too_small: Curses::A_REVERSE,
+          feelings_selected: Curses::A_REVERSE | Curses::A_BOLD, felt_selected: Curses::A_REVERSE | Curses::A_BOLD,
+          selected_button: Curses::A_REVERSE,
           cursor: Curses::A_UNDERLINE, cursor_button: Curses::A_UNDERLINE | Curses::A_BOLD, heading: Curses::A_BOLD,
           body: Curses::A_DIM, error: Curses::A_BOLD, button: Curses::A_BOLD, folder: Curses::A_BOLD, project: Curses::A_BOLD, page: Curses::A_BOLD,
           key: Curses::A_REVERSE, border: Curses::A_DIM, divider: Curses::A_BOLD,
-          selected_divider: Curses::A_REVERSE, cursor_divider: Curses::A_BOLD,
           code_keyword: Curses::A_BOLD, code_comment: Curses::A_DIM
         )
       end
 
       def colored
         in_text_color.merge(
-          title: pair(:title) | Curses::A_BOLD, selected: pair(:selected) | white_bold,
-          selected_button: pair(:selected_button) | Curses::A_BOLD, directive: pair(:directive),
-          error: pair(:error) | Curses::A_BOLD, button: pair(:button) | Curses::A_BOLD, **emphasis,
-          **dividers, **code_tokens, **bright, **files, **unfocused
+          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,
+          **unfocused
         )
       end
 
+      # The selected row, its buttons, Code feelings' selected method, bold, on green when it's already been felt, and its
+      # red when the screen's too small for it.
+      def selections
+        { selected: pair(:selected) | white_bold, feelings_selected: pair(:selected) | Curses::A_BOLD,
+          felt_selected: pair(:felt_selected) | Curses::A_BOLD,
+          too_small: pair(:too_small) | white_bold, selected_button: pair(:selected_button) | Curses::A_BOLD }
+      end
+
       # The styles without a colour of their own, or that are only bold, dim or the like, in the text's colour, which is
       # also any style that isn't here.
       def in_text_color
@@ -86,11 +112,11 @@ module Raindown
         Hash.new(text).merge(plain.transform_values { it | text })
       end
 
-      # Headings, and Code feelings' text and lines, whose lavender the Dashboard cards' charts and code
-      # blocks are too, apart from highlighted code's keywords, strings and the like.
+      # Headings, the waffle's butter's shine and its syrup, and Code feelings' text and lines, bold around the method the
+      # mouse is over, and its purple.
       def emphasis
-        lavender = pair(:feelings)
-        { heading: pair(:heading) | Curses::A_BOLD, feelings: lavender, chart: lavender, code: lavender }
+        { heading: pair(:heading) | Curses::A_BOLD, feelings: pair(:feelings), nearby: pair(:feelings) | Curses::A_BOLD,
+          feelings_purple: pair(:feelings_purple), shine: pair(:shine) | Curses::A_BOLD, syrup: pair(:syrup) }
       end
 
       # Highlighted code's tokens, like keywords and comments, with comments dim in 8 colours, where there's no grey.
@@ -103,8 +129,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] }
 
-      # The line between the panes, and where it meets a selected row.
-      def dividers = { divider: pair(:divider), selected_divider: pair(:selected_divider) }
+      # The lines between the panes and beneath the title.
+      def dividers = { divider: pair(:divider) }
 
       def files
         { folder: pair(:folder) | Curses::A_BOLD, project: pair(:folder) | Curses::A_BOLD,
@@ -113,9 +139,9 @@ module Raindown
 
       # The selected rows of the panes without the focus, on dark grey where there's one.
       def unfocused
-        return { cursor_button: pair(:button) | Curses::A_BOLD, cursor_divider: pair(:divider) } unless Curses.colors >= 256
+        return { cursor_button: pair(:button) | Curses::A_BOLD } unless Curses.colors >= 256
 
-        { cursor: pair(:cursor), cursor_button: pair(:cursor_button) | Curses::A_BOLD, cursor_divider: pair(:cursor_divider) }
+        { cursor: pair(:cursor), cursor_button: pair(:cursor_button) | Curses::A_BOLD }
       end
 
       # Each colour pair as [name, foreground, background], where -1 is the terminal's own background.
@@ -130,9 +156,10 @@ module Raindown
          *(many ? CODE.merge(BRIGHT, FEELINGS, ACCENTS) : BASIC_CODE.merge(BASIC_BRIGHT, BASIC_FEELINGS, BASIC_ACCENTS))
            .map { |name, color| [name, color, -1] },
          [:text, text, -1],
-         [:selected, white, blues[:selected]], [:selected_button, Curses::COLOR_YELLOW, blues[:selected]],
-         [:cursor, white, DARK_GREY], [:cursor_button, Curses::COLOR_YELLOW, DARK_GREY], [:divider, text, -1],
-         [:selected_divider, text, blues[:selected]], [:cursor_divider, text, DARK_GREY]]
+         [: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]],
+         [:cursor, white, DARK_GREY], [:cursor_button, Curses::COLOR_YELLOW, DARK_GREY], [:divider, blues[:line], -1],
+         [:shine, white, -1]]
       end
 
       def pair(name)

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # The terminal's title while the Screen's open, which it's prepended to: blank, rather than the command's name,
+    # saving the title it had, then putting it back, which terminals that can't ignore. It's a space, as terminals like
+    # Ghostty take an empty title to mean their own.
+    module TerminalTitle
+      BLANK_TITLE = "\e]2; \a"
+      SAVE_TITLE = "\e[22;2t"
+      RESTORE_TITLE = "\e[23;2t"
+
+      private
+
+      def start
+        super
+        terminal("#{SAVE_TITLE}#{BLANK_TITLE}")
+      end
+
+      def stop
+        terminal(RESTORE_TITLE)
+        super
+      end
+
+      def terminal(sequence)
+        $stdout.write(sequence)
+        $stdout.flush
+      end
+    end
+  end
+end

data/lib/raindown/tui/text.rb

@@ -8,6 +8,16 @@ module Raindown
     module Text
       Segment = Data.define(:text, :style, :event)
       INDENT = '  '
+      WIDTHS = 10_000
+
+      # Printable ASCII, like most code and labels, is a column a character, without asking Unicode, and other text,
+      # like boxes' borders and magnified digits, is the same every frame, so its width's remembered, up to WIDTHS texts.
+      def self.display_width(text)
+        return text.length if text.match?(/\A[ -~]*\z/)
+
+        @widths = {} if @widths.nil? || @widths.size >= WIDTHS
+        @widths[text] ||= Unicode::DisplayWidth.of(text)
+      end
 
       private
 
@@ -27,7 +37,9 @@ module Raindown
       # Text cut or padded to the width, with a cut shown by an ellipsis.
       def fit(text, width)
         return '' if width <= 0
-        return text + (' ' * (width - display_width(text))) if display_width(text) <= width
+
+        text_width = display_width(text)
+        return text + (' ' * (width - text_width)) if text_width <= width
 
         cut = +''
         cut_width = 0
@@ -83,28 +95,39 @@ module Raindown
         [*segments_between(line, 0, column), *segments, *segments_between(line, column + width, Float::INFINITY)]
       end
 
-      # The parts of the line's segments between two columns, where a wide character cut in two leaves spaces.
+      # The parts of the line's segments between two columns, where a wide character cut in two leaves spaces. A segment
+      # wholly between them, or wholly outside, is kept or left out whole, without going through its characters.
       def segments_between(line, from, to)
         column = 0
         line.filter_map do |segment|
-          text = segment.text.each_char.map do |char|
-            start = column
-            column += display_width(char)
-            overlap = [column, to].min - [start, from].max
-            overlap == display_width(char) ? char : ' ' * [overlap, 0].max
-          end.join
-          segment.with(text:) unless text.empty?
+          start = column
+          column += display_width(segment.text)
+          next if segment.text.empty? || column <= from || start >= to
+          next segment if start >= from && column <= to
+
+          segment.with(text: chars_between(segment.text, start, from, to))
         end
       end
 
+      # The text's characters between two columns, from the column it starts at, where a wide character cut in two
+      # leaves spaces.
+      def chars_between(text, column, from, to)
+        text.each_char.map do |char|
+          start = column
+          column += display_width(char)
+          overlap = [column, to].min - [start, from].max
+          overlap == display_width(char) ? char : ' ' * [overlap, 0].max
+        end.join
+      end
+
       # Tabs and control characters, like in a directive's output, would move the terminal's cursor.
       def printable(text)
+        return text unless text.match?(/[[:cntrl:]]/)
+
         text.gsub("\t", INDENT).gsub(/[[:cntrl:]]/, '')
       end
 
-      def display_width(text)
-        Unicode::DisplayWidth.of(text)
-      end
+      def display_width(text) = Text.display_width(text)
     end
   end
 end

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

@@ -32,7 +32,7 @@ module Raindown
       def path = nil
       def changed? = false
       def typing? = false
-      def animating? = false
+      def pace(_hovered) = :active
 
       def status(_navigator)
         found = "#{charts.length} #{charts.length == 1 ? 'chart' : 'charts'} in #{File.basename(project || root)}"
@@ -111,7 +111,7 @@ module Raindown
           answer = worker.call(:charts, find:)
           @cards.concat(answer[:cards])
           @errors.concat(answer[:errors])
-        rescue Worker::Error => e
+        rescue Workers::Worker::Error => e
           @errors << "#{File.basename(worker.root)}: #{e.message}"
         end
         @cards.sort_by! { [it.project, it.path, it.line] }

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../events'
-require_relative '../workers/worker'
+require_relative '../../workers/worker'
 
 module Raindown
   module TUI
@@ -27,7 +27,7 @@ module Raindown
       def status(_navigator) = [:info, endpoint.text]
       def changed? = false
       def typing? = false
-      def animating? = false
+      def pace(_hovered) = :active
       def next_step?(key) = %i[up down enter edit execute].include?(key)
 
       # Clicks on the response only move the focus to it.
@@ -40,7 +40,7 @@ module Raindown
         @language = lines.first.to_s[FENCE, 1]
         @response = @language ? lines[1...-1] : lines
         @error = nil
-      rescue Worker::Error => e
+      rescue Workers::Worker::Error => e
         @response = []
         @error = e.message
       end

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

@@ -14,7 +14,7 @@ module Raindown
 
       def renderer = ListRenderer
       def typing? = false
-      def animating? = false
+      def pace(_hovered) = :active
 
       def rows = @rows.call
       def selected = rows[cursor]

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

@@ -5,7 +5,7 @@ require_relative '../events'
 require_relative 'list_view'
 require_relative '../highlighter'
 require_relative '../row'
-require_relative '../workers/worker'
+require_relative '../../workers/worker'
 
 module Raindown
   module TUI
@@ -37,7 +37,7 @@ module Raindown
         @directives = outline.directives
         @highlighted = {}
         @error = nil
-      rescue Worker::Error, SystemCallError => e
+      rescue Workers::Worker::Error, SystemCallError => e
         @error = e.message
       end
 
@@ -128,12 +128,13 @@ module Raindown
       def buttons(directive, expanded:)
         buttons = []
         buttons << [expanded ? '[-]' : "[+#{directive.body.size}]", :toggle] if directive.body
-        buttons << ['[Run]', :execute] if directive.endpoint?
+        buttons << ['[Run]', :execute] if directive.endpoint? && directive.writes
         buttons
       end
 
+      # A self-closing directive, like <{ :toc }>, by its name after a colon, and the rest by theirs before one.
       def directive_text(directive)
-        return ":#{directive.name}" unless directive.writes
+        return ":#{directive.name}" if !directive.writes && directive.line == directive.end_line
 
         [directive.name, ':', (" #{directive.args}" unless directive.args.empty?)].join
       end

data/lib/raindown/tui.rb

@@ -4,28 +4,38 @@ require_relative 'projects'
 require_relative 'tui/navigator/navigator'
 
 module Raindown
-  # The terminal UI, started with "raindown tui": a project's Markdown files beside the open file's outline,
+  # The terminal UI, started with "raindown": a project's Markdown files beside the open file's outline,
   # where directives fold, endpoints run and the editor opens at a line. Curses only loads here,
   # so watching and rendering start without it.
   module TUI
     module_function
 
-    # PATH is a file to open, or a directory. Its project is the one it's in, or else the directory itself.
-    def start(path)
+    # PATH is a file to open, or a directory. Its project is the one it's in, or else the directory itself. It returns
+    # true once it's quit. Without a terminal, like in a script or a service, it says so, once curses has loaded, and returns false, to be
+    # watched instead, as curses' own error would be "Error opening terminal: unknown". Bare and execute, like --bare and
+    # -x, allow bare directives in any file and run endpoints with no response as it writes back.
+    def start(path, bare: false, execute: false)
       require_relative 'tui/terminal/screen'
-      # Without a terminal, curses' own error is "Error opening terminal: unknown".
-      abort('raindown tui needs a terminal') unless $stdin.tty? && $stdout.tty?
+      unless $stdin.tty? && $stdout.tty?
+        warn("raindown needs a terminal, so it's watching instead")
+        return false
+      end
 
       path = File.expand_path(path)
       root = Projects.root(path) || (File.directory?(path) ? path : File.dirname(path))
       # The projects inside it are shown too. Each loads its own nodes in its worker's process, like when watching,
       # so two projects' nodes of the same name stay apart.
-      workers = Workers.new(root:)
+      workers = Project.workers(root:, bare:, execute:)
 
       # Rouge loads here, rather than with Raindown, which doesn't highlight code outside the TUI.
       require 'rouge'
-      Screen.new(Navigator.new(root:, path: (path unless File.directory?(path)), workers:)).run
+      # 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
+      true
     ensure
+      saves&.stop
       workers&.stop
     end
   end

data/lib/raindown/watcher/changes.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../projects'
+
+module Raindown
+  module Watcher
+    # Listening skips these folders as they hold dependencies and builds, which Projects ignores too.
+    IGNORE = %r{(?:\A|/)(?:#{Projects::IGNORED.join('|')})/}
+
+    # A change to a project's nodes, or to one of its Markdown files, which is written back when it's been saved.
+    Change = Data.define(:root, :path, :nodes) do
+      def nodes? = nodes
+      def saved? = !nodes && File.exist?(path)
+    end
+
+    # A listener, still to start, that gives the block the paths saved, added or removed in the directory.
+    def self.listen(directory, &)
+      require 'listen'
+      Listen.to(directory, ignore: IGNORE) { |modified, added, removed| yield(modified + added + removed) }
+    end
+
+    # The changes among the paths, by the project each is in, the nearest one above it, or else the root, when there is
+    # one, leaving out files that are neither nodes nor Markdown, or are in ignored folders.
+    def self.changes(paths, root: nil)
+      paths.filter_map do |path|
+        project = Projects.root(path) || root || next
+        next Change.new(root: project, path:, nodes: true) if Projects.node?(path, root: project)
+
+        Change.new(root: project, path:, nodes: false) if Projects.markdown?(path, root: project)
+      end
+    end
+  end
+end

data/lib/raindown/watcher/file_watcher.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative '../../raindown'
+require_relative '../rewriter'
+require_relative 'changes'
+
+module Raindown
+  module Watcher
+    # Watches one file and writes back to it as it's saved, like its TOC, tables and endpoint responses.
+    class FileWatcher
+      attr_reader :path, :bare, :execute
+
+      def initialize(path:, bare: false, execute: false)
+        @path = path
+        @bare = bare
+        @execute = execute
+      end
+
+      def start
+        $stdout.sync = true
+
+        safely { rewrite }
+        puts "Watching #{path} for changes..."
+
+        listener.start
+        sleep
+      end
+
+      private
+
+      def listener
+        directory = File.dirname(File.expand_path(path))
+        filename = File.basename(path)
+
+        Watcher.listen(directory) do |paths|
+          next unless paths.any? { File.basename(it) == filename && File.exist?(it) }
+
+          # Writing back saves the file again, and that save changes nothing, so it ends there.
+          safely { puts "Updated #{path}" if rewrite }
+        end
+      end
+
+      # An error in the file is shown rather than stopping the watcher, so it can be fixed and saved again.
+      def safely
+        yield
+      rescue StandardError => e
+        raise if ENV['RAINDOWN_DEBUG']
+
+        warn "raindown: #{path}: #{e.message}"
+      end
+
+      # The files' metadata is loaded again each time, so new and renamed files are listed.
+      def rewrite
+        Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
+      end
+    end
+  end
+end