task_progress 0.0.1

data/lib/task_progress/terminal_output.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # Redraws the tree in place on a terminal, from a ticker thread of its own so spinners turn
+  # while nothing reports. A finished subtree folds into its one line, and when the tree is
+  # taller than the screen the finished lines go first, then the ones not started. When the
+  # root finishes the tree is drawn one last time and left on screen - or erased, with `erase: true`.
+  # A line a task `puts` goes above the tree and stays there
+  #
+  # With `interval: nil` there is no thread and every batch redraws, which is what tests want
+  class TerminalOutput
+    SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze #: Array[String]
+    BAR = 20 #: Integer
+    DEFAULT_SIZE = [24, 80].freeze #: [Integer, Integer]
+    private_constant :SPINNER, :BAR, :DEFAULT_SIZE
+
+    # @rbs @io: IO | StringIO
+    # @rbs @interval: (Integer | Float)?
+    # @rbs @erase: bool
+    # @rbs @clock: ^() -> Float
+    # @rbs @lock: Thread::Mutex
+    # @rbs @drawn: Integer
+    # @rbs @frame: Integer
+    # @rbs @log: Log?
+    # @rbs @closed: bool
+    # @rbs @ticker: Thread?
+    # @rbs @dirty: bool
+
+    # Draws on `io` every `interval` seconds - or on every batch, with `interval: nil`. With `erase: true` the tree is cleared once the root finishes
+    #: (?IO | StringIO, ?interval: (Integer | Float)?, ?erase: bool, ?clock: ^() -> Float) -> void
+    def initialize(io = $stderr, interval: 0.1, erase: false, clock: -> { Process.clock_gettime(Process::CLOCK_REALTIME) })
+      @io = io
+      @interval = interval
+      @erase = erase
+      @clock = clock
+      @lock = Mutex.new
+      @drawn = 0
+      @frame = 0
+      @log = nil
+      @closed = false
+      @ticker = nil
+    end
+
+    # Takes one batch, see Log#add_output
+    #: (Batch, Log) -> void
+    def call(batch, log)
+      said = batch.events.filter_map { it.value if it.op == :say } #: Array[String]
+      @lock.synchronize do
+        @log = log
+        return said.each { @io.puts(it) } if @closed
+        print_above(said) unless said.empty?
+        if log.snapshot[[]]&.finished?
+          finish
+        elsif @interval.nil? || !said.empty?
+          draw
+          @ticker ||= Thread.new { tick } if @interval
+        else
+          @dirty = true
+          @ticker ||= Thread.new { tick }
+        end
+      end
+    end
+
+    # Draws the tree one last time and stops the ticker
+    #: () -> void
+    def close
+      @lock.synchronize { finish if @log && !@closed }
+      @ticker&.join
+    end
+
+    # The lines for a snapshot, without the terminal control around them
+    #: (State, ?width: Integer, ?height: Integer) -> Array[String]
+    def lines(snapshot, width: columns, height: rows)
+      shown = [] #: Array[[path?, Node | Fold | Integer]]
+      snapshot.rows do |path, node|
+        next if path.length.positive? && hidden?(snapshot, path)
+        shown << [path, node]
+      end
+      shown = trim(shown, height - 1)
+      shown.map { |path, node| line(snapshot, path, node, width) }
+    end
+
+    private
+
+    #: () -> void
+    def tick
+      loop do
+        sleep(@interval || 0.1)
+        @lock.synchronize do
+          return if @closed
+          @frame += 1
+          draw
+        end
+      end
+    end
+
+    #: () -> void
+    def finish
+      @closed = true
+      @erase ? clear : draw
+    end
+
+    #: () -> void
+    def draw
+      log = @log or return
+      text = lines(log.snapshot)
+      @io.write("#{up}#{text.join("\n")}\n")
+      @io.flush
+      @drawn = text.length
+    end
+
+    #: (Array[String]) -> void
+    def print_above(said)
+      @io.write("#{up}#{said.join("\n")}\n")
+      @drawn = 0
+    end
+
+    #: () -> void
+    def clear
+      @io.write(up)
+      @io.flush
+      @drawn = 0
+    end
+
+    #: () -> String
+    def up = @drawn.zero? ? "" : "\e[#{@drawn}A\e[J"
+
+    # Under a finished node only what failed shows, so a failure leaves the way down to it
+    #: (State, path) -> bool
+    def hidden?(snapshot, path)
+      (0...path.length).any? { snapshot[path.take(it)]&.finished? && snapshot[path.take(it + 1)]&.status != :failed }
+    end
+
+    # What fits in `room` lines - the last of them saying how many more there are
+    #: (Array[[path?, Node | Fold | Integer]], Integer) -> Array[[path?, Node | Fold | Integer]]
+    def trim(shown, room)
+      room = [room, 2].max
+      %i[done pending].each do |status|
+        break if shown.length <= room
+        excess = shown.length - room
+        shown = shown.each_with_index.reject { |(_, node), i| i.positive? && node.is_a?(Node) && node.status == status && (excess -= 1) >= 0 }.map(&:first)
+      end
+      return shown if shown.length <= room
+      more = [nil, shown.length - room + 1] #: [path?, Node | Fold | Integer]
+      shown.first(room - 1) + [more]
+    end
+
+    #: (State, path?, Node | Fold | Integer, Integer) -> String
+    def line(snapshot, path, node, width)
+      return "  … #{node} more" if path.nil? || node.is_a?(Integer)
+      indent = "  " * path.length
+      return "#{indent}#{(node.status == :done) ? "✓" : "·"} #{node.name}"[0, width - 1].to_s if node.is_a?(Fold)
+      parts = ["#{indent}#{icon(node)} #{node.name}"] #: Array[String?]
+      parts << measure(snapshot, path, node)
+      parts << pace(node) if node.status == :active && node.children.empty?
+      parts << elapsed(node)
+      parts << "attempt #{node.attempt}" if node.attempt.to_i > 1
+      parts << ((node.status == :failed) ? node.error&.dig(:message) : node.message)
+      parts.compact.reject(&:empty?).join("  ")[0, width - 1].to_s
+    end
+
+    #: (Node) -> String
+    def icon(node)
+      case node.status
+      when :done then "✓"
+      when :failed then "✗"
+      when :canceled then "⊘"
+      when :pending then "·"
+      else node.stale ? "?" : SPINNER.fetch(@frame % SPINNER.length)
+      end
+    end
+
+    #: (State, path, Node) -> String?
+    def measure(snapshot, path, node)
+      return nil if node.status == :done && path.length.positive?
+      percent = snapshot.percent(path)
+      if node.children.empty? && node.indeterminate
+        counted = ((node.unit == "bytes") ? TaskProgress.human_bytes(node.count) : node.count.to_s) if node.count.positive?
+        # A barber pole while it runs, a full bar once it is through
+        [(node.status == :active) ? stripes : bar(percent), counted].compact.join(" ")
+      elsif node.children.empty? && (total = node.total)
+        count = (node.unit == "bytes") ? "#{TaskProgress.human_bytes(node.count)} / #{TaskProgress.human_bytes(total)}" : "#{node.count}/#{total}"
+        "#{bar(percent)} #{count}"
+      else
+        format("%s %3d%%", bar(percent), percent)
+      end
+    end
+
+    # Diagonal stripes that crawl one cell along every frame - for work with no measure
+    #: () -> String
+    def stripes = Array.new(BAR) { ((it - @frame) % 6 < 3) ? "╱" : "░" }.join
+
+    #: (Integer) -> String
+    def bar(percent)
+      filled = BAR * percent / 100
+      "#{"█" * filled}#{"░" * (BAR - filled)}"
+    end
+
+    # The rate over the whole run so far, and the time left at that rate. Steadier than a
+    # rate over the last few ticks, which jumps about with every pause in the work
+    #: (Node) -> String?
+    def pace(node)
+      started = node.started_at or return nil
+      seconds = @clock.call - started
+      return nil unless seconds >= 1 && node.count.positive?
+      rate = node.count / seconds
+      per = if node.unit == "bytes"
+        "#{TaskProgress.human_bytes(rate)}/s"
+      else
+        format((rate < 10) ? "%.1f/s" : "%d/s", rate)
+      end
+      total = node.total
+      return per unless total && total > node.count
+      "#{per}  ETA #{TaskProgress.duration((total - node.count) / rate)}"
+    end
+
+    #: (Node) -> String?
+    def elapsed(node)
+      started = node.started_at or return nil
+      TaskProgress.duration((node.finished_at || @clock.call) - started)
+    end
+
+    #: () -> Integer
+    def columns = size[1]
+
+    #: () -> Integer
+    def rows = size[0]
+
+    #: () -> [Integer, Integer]
+    def size
+      io = @io
+      return DEFAULT_SIZE unless io.is_a?(IO) # a StringIO has no screen
+      require "io/console"
+      rows, cols = io.winsize
+      (rows.positive? && cols.positive?) ? [rows, cols] : DEFAULT_SIZE
+    rescue NoMethodError, SystemCallError
+      DEFAULT_SIZE
+    end
+  end
+end

data/lib/task_progress/token.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "openssl"
+
+class TaskProgress
+  # The right to see a tree and to ask for its tasks to be canceled, signed, and good for a while.
+  # The server issues one when it hands out a page - after it has decided the page may show that
+  # tree - and checks it when the page comes back for the tree or with a cancellation. So neither
+  # can be forged without the secret, or used after the token expires, and the tree's own key never
+  # has to reach a page. Which tasks may be canceled is for `cancelable` to say.
+  #
+  #     tokens = TaskProgress::Token.new(ENV.fetch("TASK_PROGRESS_SECRET"))
+  #     token = tokens.issue(import.key, expires_in: 3600)  # into the page
+  #     tokens.verify(token)                                # => import.key, when the page comes back
+  class Token
+    # @rbs @secret: String
+    # @rbs @clock: ^() -> Integer
+
+    # Signs with `secret`, which must be at least 32 bytes
+    #: (String, ?clock: ^() -> Integer) -> void
+    def initialize(secret, clock: -> { Time.now.to_i })
+      raise ArgumentError, "The secret must be at least 32 bytes" if secret.to_s.bytesize < 32
+      @secret = secret.to_s
+      @clock = clock
+    end
+
+    # A token for `subject` - a log id, a run, whatever the tokens are checked against - good for `expires_in` seconds
+    #: (String, ?expires_in: Integer) -> String
+    def issue(subject, expires_in: 3600)
+      payload = encode("#{subject}\n#{@clock.call + expires_in}")
+      "#{payload}.#{sign(payload)}"
+    end
+
+    # What the token was issued for, or nil if it is forged, mangled or expired
+    #: (String?) -> String?
+    def verify(token)
+      payload, signature = token.to_s.split(".", 2)
+      return unless payload && signature && signature.bytesize == sign(payload).bytesize
+      return unless OpenSSL.fixed_length_secure_compare(signature, sign(payload))
+      subject, expires = decode(payload).split("\n", 2)
+      subject if expires && Integer(expires, exception: false)&.>=(@clock.call)
+    rescue ArgumentError
+      nil
+    end
+
+    private
+
+    #: (String) -> String
+    def sign(payload) = encode(OpenSSL::HMAC.digest("SHA256", @secret, "task_progress.token\n#{payload}"))
+
+    #: (String) -> String
+    def encode(bytes) = [bytes].pack("m0").tr("+/", "-_").delete("=")
+
+    #: (String) -> String
+    def decode(text) = (text + "=" * (-text.length % 4)).tr("-_", "+/").unpack1("m0").to_s.force_encoding(Encoding::UTF_8)
+  end
+end

data/lib/task_progress/tracked_io.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+begin
+  require "progressive_io"
+rescue LoadError
+  raise LoadError, "TaskProgress#track_io needs the progressive_io gem - add `gem \"progressive_io\"` to your Gemfile"
+end
+
+class TaskProgress
+  # A ProgressiveIO that advances a task by how far it has been read. Readers seek (ZipKit reads
+  # the end of an archive first), so only the furthest position counts. The task moves in steps,
+  # a thousandth of the total by default - a loop of small reads over a big file would otherwise
+  # commit a batch per read, and every output and browser would get each of them
+  class TrackedIO < ::ProgressiveIO
+    STEP_WITHOUT_TOTAL = 64 * 1024 #: Integer
+    private_constant :STEP_WITHOUT_TOTAL
+
+    # @rbs @task: TaskProgress
+    # @rbs @total: Integer?
+    # @rbs @step: Integer
+    # @rbs @furthest: Integer
+    # @rbs @reported: Integer
+
+    # Advances `task` as `io` is read, in steps of `step` bytes - see TaskProgress#track_io, which makes one
+    #: (IO, TaskProgress, ?total: Integer?, ?step: Integer?) -> void
+    def initialize(io, task, total: nil, step: nil)
+      @task = task
+      @total = total
+      @step = step || (total ? [total / 1000, 1].max : STEP_WITHOUT_TOTAL)
+      @furthest = 0
+      @reported = 0
+      super(io) { |pos| moved_to(pos) }
+    end
+
+    # ProgressiveIO lets these through unreported, and IO.copy_stream reads anything that is not
+    # an IO with readpartial
+    # Reads the way IO#readpartial does, and reports how far it got
+    #: (*untyped, **untyped) -> untyped
+    def readpartial(*, **) = super.tap { notify_read }
+
+    # Reads the way IO#read_nonblock does, and reports how far it got
+    #: (*untyped, **untyped) -> untyped
+    def read_nonblock(*, **) = super.tap { notify_read }
+
+    # Reads the way IO#sysread does, and reports how far it got
+    #: (*untyped, **untyped) -> untyped
+    def sysread(*, **) = super.tap { notify_read }
+
+    # Reports what was read since the last step
+    #: () -> void
+    def flush_progress
+      return if @furthest == @reported || @task.finished?
+      @task.advance(@furthest - @reported)
+      @reported = @furthest
+    end
+
+    private
+
+    #: (Integer) -> void
+    def moved_to(pos)
+      return if pos <= @furthest
+      @furthest = pos
+      total = @total
+      flush_progress if @furthest - @reported >= @step || (total && @furthest >= total)
+    end
+  end
+end

data/lib/task_progress/transaction.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # What a block given to Log#transaction adds its events through. Each one is applied to the
+  # tree as it comes, and journaled, so the whole transaction can be undone if the block raises
+  class Transaction # :nodoc:
+    # What it has added so far, in order
+    attr_reader :events #: Array[Event]
+    # What it changed, to undo it by
+    attr_reader :journal #: Journal
+    # The time it opened - every event in it happens then
+    attr_reader :at #: Float
+    # The tree as the transaction has it so far
+    attr_reader :state #: State
+
+    # @rbs @random: Random
+
+    # For changing `state` at `at`, drawing task ids from `random` - see Log#transaction, which opens one
+    #: (State, Float, Random) -> void
+    def initialize(state, at, random)
+      @state = state
+      @at = at
+      @random = random
+      @events = []
+      @journal = Journal.new
+    end
+
+    # Applies the event, and adds it to the batch
+    #: (Event) -> self
+    def <<(event)
+      @state.apply(event, at: @at, journal: @journal)
+      @events << event
+      self
+    end
+
+    # A path for a new child of `path` - see State#new_child
+    #: (path) -> path
+    def new_child(path) = @state.new_child(path, @random)
+  end
+end

data/lib/task_progress/trees_app.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+class TaskProgress
+  # A Rack app that serves handed-off trees to pages, by a Token rather than by the tree's key -
+  # what TaskProgress.for_page hands out links to. The Railtie mounts it at `/task_progress/trees`.
+  #
+  #     GET  /:token/events          Server-Sent Events, see SSE
+  #     GET  /:token/poll            the tree, polled or long-polled, see Poll
+  #     POST /:token/cancellations   path=x3k0-00af (a form, or JSON)
+  #       202  {"path": ..., "state": "requested"}   asked of whoever works on it
+  #       200  {"path": ..., "state": "moot"}        nothing left to cancel - no such task, or it ended
+  #       409  the task is not cancelable
+  #     403  a token that is forged, mangled or expired
+  #     404  a tree that is gone, or anything else
+  #
+  # Issuing the token is the authorization: it happens in an action of yours, which has decided
+  # the page may see that tree. The key itself never leaves the server
+  class TreesApp
+    # @rbs @tokens: Token
+    # @rbs @stream_store: untyped
+
+    # Checks tokens with `tokens`, and reads trees from `stream_store` - TaskProgress.stream_store
+    # unless given
+    #: (tokens: Token, ?stream_store: untyped) -> void
+    def initialize(tokens:, stream_store: nil)
+      @tokens = tokens
+      @stream_store = stream_store
+    end
+
+    # Serves one request
+    #: (Hash[String, untyped]) -> [Integer, Hash[String, String], untyped]
+    def call(env)
+      _, token, action = env["PATH_INFO"].to_s.split("/", 3)
+      key = @tokens.verify(token) or return respond(403, {error: "invalid or expired token"})
+      stream_store = @stream_store || TaskProgress.stream_store
+      case [env["REQUEST_METHOD"], action]
+      in ["GET", "events"] then SSE.response(key, stream_store:)
+      in ["GET", "poll"] then Poll.response(key, env, stream_store:)
+      in ["POST", "cancellations"] then cancel(key, env, stream_store)
+      else respond(404, {error: "not found"})
+      end
+    end
+
+    private
+
+    #: (String, Hash[String, untyped], untyped) -> [Integer, Hash[String, String], Array[String]]
+    def cancel(key, env, stream_store)
+      path = CancellationsApp.params(env)["path"].to_s.split("-")
+      return respond(422, {error: "malformed path"}) unless path.length <= Wire::MAX_DEPTH && path.all? { it.match?(Wire::SEGMENT) }
+      outcome = TaskProgress.fetch(key, stream_store:).request_cancel(path, "Canceled from the page")
+      case outcome
+      when :refused then respond(409, {error: "not cancelable"})
+      when :moot then respond(200, {path: path.join("-"), state: "moot"})
+      else respond(202, {path: path.join("-"), state: "requested"})
+      end
+    rescue KeyError
+      respond(404, {error: "no such tree"})
+    end
+
+    #: (Integer, Hash[Symbol, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def respond(status, body) = [status, {"content-type" => "application/json"}, [JSON.generate(body)]]
+  end
+end

data/lib/task_progress/turbo_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # View helpers, in every view once the gem is in a Rails app
+  module TurboHelper
+    # The tree a job broadcasts with `TaskProgress.broadcast(record, ...)`, kept up to date: drawn
+    # as it stood at its last frame, and subscribed to every frame after that. Needs turbo-rails,
+    # and `task_tree.css` on the page - plus `task_progress_clock.js`, for elapsed times to tick
+    #
+    #     <%= task_progress_tree @csv_import %>
+    #: (untyped, ?store: untyped) -> String
+    def task_progress_tree(record, store: ::Rails.cache) # steep:ignore
+      drawn = store.read(RailsDefaults.key(record)) || %(<div id="#{ERB::Util.html_escape(RailsDefaults.id(record))}" class="tree"></div>)
+      safe_join([turbo_stream_from(record, :task_progress), drawn.html_safe]) # steep:ignore
+    end
+  end
+end

data/lib/task_progress/turbo_sse.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "cgi/escape"
+
+class TaskProgress
+  # A Rack body streaming a tree as Turbo Streams over Server-Sent Events, for a page that shows
+  # it with `<turbo-stream-source src="...">` - Turbo with no Action Cable, and no JavaScript of
+  # your own. Every frame replaces the whole tree by morphing, at most every `interval` seconds
+  # however fast the tree changes; a reconnect starts with the whole tree, so nothing is ever
+  # missed for good. Given a subtask, it streams that branch alone.
+  #
+  #   TaskProgress::TurboSSE.response(task, renderer:, source: "progress-source")
+  #
+  # Once the task finishes it sends the last frame, removes the element with the id `source` -
+  # the `<turbo-stream-source>`, so the browser does not reconnect to a finished stream - and ends.
+  # Without a `source` the browser reconnects every `reconnect` seconds, and gets the last frame
+  # each time. Given a key, it follows the tree handed off there, as SSE does
+  class TurboSSE
+    # What a Turbo SSE response is sent with - the same as an SSE one
+    HEADERS = SSE::HEADERS #: Hash[String, String]
+
+    # @rbs @task: TaskProgress
+    # @rbs @renderer: TurboStreamOutput::_Renderer
+    # @rbs @interval: Integer | Float
+    # @rbs @heartbeat: Integer | Float
+    # @rbs @source: String?
+    # @rbs @reconnect: Integer | Float
+    # @rbs @close: bool
+
+    # A whole Rack response: status, headers and this body - or a 404, for a key with nothing at it
+    #: (TaskProgress | String, **untyped) -> [Integer, Hash[String, String], TurboSSE | Array[String]]
+    def self.response(source, **)
+      [200, HEADERS.dup, new(source, **)]
+    rescue KeyError
+      [404, {"content-type" => "text/plain"}, ["Nothing to follow"]]
+    end
+
+    # Streams `task`, drawn by `renderer` - an HTMLRenderer, or anything that answers `id` and
+    # `render(snapshot, from)`, `from` being the task's path. `source` is the id of the
+    # `<turbo-stream-source>` to remove at the end
+    #: (TaskProgress | String, renderer: TurboStreamOutput::_Renderer, ?stream_store: untyped, ?interval: Integer | Float, ?heartbeat: Integer | Float, ?reconnect: Integer | Float, ?source: String?) -> void
+    def initialize(task, renderer:, stream_store: TaskProgress.stream_store, interval: 0.25, heartbeat: 15, reconnect: 2, source: nil)
+      @close = task.is_a?(String)
+      @task = task.is_a?(String) ? TaskProgress.follow(task, stream_store:) : task
+      @reconnect = reconnect
+      @renderer = renderer
+      @interval = interval
+      @heartbeat = heartbeat
+      @source = source
+    end
+
+    # Yields the stream a chunk at a time, until the task finishes - as a Rack body does
+    #: () { (String) -> void } -> void
+    def each
+      queue = Thread::Queue.new
+      output = @task.add_output(replay: false) { |batch, _log| queue << batch }
+      yield "retry: #{(@reconnect * 1000).round}\n\n"
+      yield message(frame)
+      until ended?
+        next yield(": ping\n\n") unless queue.pop(timeout: @heartbeat)
+        queue.clear # one frame for all of them: it draws the tree as it stands
+        yield message(frame)
+        sleep(@interval) unless ended?
+      end
+      yield message(frame)
+      source = @source
+      yield message(%(<turbo-stream action="remove" target="#{CGI.escapeHTML(source)}"></turbo-stream>)) if source
+    ensure
+      @task.remove_output(output) if output
+      close
+    end
+
+    # Stops following a tree it followed by its key - Rack calls it when the response is over
+    #: () -> void
+    def close
+      @task.log.close if @close
+    end
+
+    private
+
+    # Finished, or pruned away - which is as finished as it will ever be
+    #: () -> bool
+    def ended?
+      node = @task.log.snapshot[@task.path]
+      node.nil? || node.finished?
+    end
+
+    #: () -> String
+    def frame
+      snapshot = @task.log.snapshot
+      TurboStreamOutput.frame(@renderer.id, render(snapshot))
+    end
+
+    #: (State) -> String
+    def render(snapshot) = @renderer.render(snapshot, @task.path)
+
+    # An unnamed event - what `<turbo-stream-source>` listens for. A line of SSE ends at a CR as
+    # much as at a LF, and task names and messages - curl's and ffmpeg's, say - are full of CRs
+    #: (String) -> String
+    def message(html) = "#{html.split(/\r\n|\r|\n/).map { "data: #{it}\n" }.join}\n"
+  end
+end

data/lib/task_progress/turbo_stream_output.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "cgi/escape"
+
+class TaskProgress
+  # Draws the whole tree as HTML on every batch, as a Turbo Stream that replaces it in the page by
+  # morphing, and hands that to `to` - in Rails, Turbo::StreamsChannel, which reaches every
+  # page subscribed with `turbo_stream_from`, whichever process the tree lives in. Put it behind a
+  # BufferedOutput, as TaskProgress.broadcast does, and a spammy job is drawn a few times a second.
+  #
+  # The whole tree, every time: a Turbo Stream has no seq and no gaps to notice, so a page that
+  # missed a frame - or joined late - is set right by the next one. Morphing touches only what
+  # differs, so a bar's width eases rather than jumps.
+  #
+  # With a `store`, the latest frame is also written under `key`, for a page to draw the tree
+  # before the first broadcast reaches it - see TurboHelper#task_progress_tree
+  class TurboStreamOutput
+    # @rbs!
+    #   interface _Renderer
+    #     def render: (State snapshot, ?path from) -> String
+    #     def id: () -> String
+    #   end
+    #
+    #   interface _Store
+    #     def read: (String key) -> untyped
+    #     def write: (String key, untyped value, **untyped) -> void
+    #     def delete: (String key) -> void
+    #   end
+
+    # The store key the latest frame is written under
+    attr_reader :key #: String
+
+    # @rbs @renderer: _Renderer
+    # @rbs @to: ^(String) -> void
+    # @rbs @store: _Store?
+
+    # Draws with `renderer`, and hands each frame - a `<turbo-stream>` element - to `to`
+    #: (renderer: _Renderer, to: ^(String) -> void, ?store: _Store?, ?key: String) -> void
+    def initialize(renderer:, to:, store: nil, key: "task_progress/#{renderer.id}")
+      @renderer = renderer
+      @to = to
+      @store = store
+      @key = key
+    end
+
+    # Draws the tree as it stands - the batch only says it changed
+    #: (Batch, Log) -> void
+    def call(_batch, log)
+      html = @renderer.render(log.snapshot)
+      @store&.write(@key, html)
+      @to.call(TurboStreamOutput.frame(@renderer.id, html))
+    end
+
+    # A Turbo Stream that replaces the element `target` with `html`, morphing it
+    #: (String, String) -> String
+    def self.frame(target, html)
+      %(<turbo-stream action="replace" method="morph" target="#{CGI.escapeHTML(target)}"><template>#{html}</template></turbo-stream>)
+    end
+  end
+end

data/lib/task_progress/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # The gem's version
+  VERSION = "0.0.1" #: String
+end