stream_weaver 0.3.0

data/lib/stream_weaver/university/listener.rb

@@ -0,0 +1,467 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'rbconfig'
+require 'stream_weaver/canvas/client'
+require 'stream_weaver/canvas/scroll_top_hint'
+require 'stream_weaver/university/course'
+require 'stream_weaver/university/progress'
+require 'stream_weaver/university/runner'
+require 'stream_weaver/university/scripts/growing_doc_state'
+
+module StreamWeaver
+  module University
+    # Turns one canvas click event into a ledger write plus a re-push.
+    # Mark-done writes the ledger directly; Run/Repeat hands off to
+    # Runner, which sends the step's prompt to the recorded worker session
+    # (or records why it wouldn't), warms up that step's own demo canvas
+    # the moment (and only if) the send actually lands (see `.warm_up!`),
+    # and leaves the outcome in the ledger for the re-push to render.
+    #
+    # Button ids come from lib/stream_weaver/university/canvas.rb's `id:`
+    # scheme: "mark-done-N", "run-N" / "repeat-N", "hero-run-N" /
+    # "hero-repeat-N" on the course list; "view-N" (a row's Details/Hide
+    # button) toggles that row's inline expansion; "reset-course" (the
+    # recap screen and the course-list footer) clears the whole course.
+    # The rendered `id:` (e.g. "mark-done-3") becomes a
+    # `btn_<label-slug>_<id>` DOM/dispatch id (app.rb `button`), so every
+    # pattern below is anchored to the string's end, not its start.
+    module Listener
+      SESSION = 'university'
+
+      # How long run! waits before reconnecting to a bridge that went away.
+      RECONNECT_DELAY = 1
+
+      # name/theme pair for one step's own demo canvas session.
+      DemoSession = Struct.new(:name, :theme)
+
+      # Which of the course's own canvas demo sessions each step opens, and
+      # the theme its prompt creates that session with -- mined from
+      # course.rb's step prompts, and named in
+      # features/university-getting-started.context.md ("Course session
+      # names"). The theme matters here specifically because
+      # `Bridge#create_session` is `@sessions[name] ||= Session.new(...)`
+      # (canvas/bridge.rb): a session's theme is fixed by whichever `create`
+      # reaches the bridge FIRST, and every later `create` for that name --
+      # including the worker's own, e.g. `streamweaver panel doc-demo
+      # --theme=doc` (course.rb) or `growing_doc.rb`'s `create(...,
+      # theme: :doc)` -- is a no-op. `warm_up!` runs before any of that, so
+      # it has to create with the SAME theme the real demo will, not the
+      # bridge's `:default`, or the worker's own theme call would silently
+      # never take effect for the rest of that get-started run. Steps 2 and
+      # 5 never open a demo canvas of their own (a standalone `ruby app.rb`,
+      # and gists/org-export respectively), so neither appears here: a Run
+      # click on either has nothing to warm up, and "Reset course" has
+      # nothing of theirs to close.
+      STEP_DEMO_SESSIONS = {
+        1 => DemoSession.new('dashboard', :default),
+        3 => DemoSession.new('decision', :default),
+        4 => DemoSession.new('doc-demo', :doc)
+      }.freeze
+
+      # "Reset course" closes exactly these, by name, and nothing else:
+      # never the controller session (SESSION, above) and never a session
+      # the user opened on their own that just happens to still exist.
+      # Derived from STEP_DEMO_SESSIONS so the two lists can never drift.
+      DEMO_SESSION_NAMES = STEP_DEMO_SESSIONS.values.map(&:name).freeze
+
+      # Applies one dispatched button token to the ledger. Returns the step
+      # number acted on, true for a whole-course action with no step of its
+      # own (reset-course), or nil if the token didn't match a known
+      # action.
+      def self.handle_token(token, progress)
+        case token.to_s
+        when /mark-done-(\d+)\z/
+          step = Regexp.last_match(1).to_i
+          mark_step_done!(progress, step)
+          step
+        when /(?:run|repeat)-(\d+)\z/ # also catches hero-run-N / hero-repeat-N
+          step = Regexp.last_match(1).to_i
+          # Dispatches to the worker session and records the outcome
+          # (including the refusals) in the ledger; the re-push in `step!`
+          # then renders whatever it wrote. The block runs once, only after
+          # Runner confirms the send actually landed -- warm_up! paints
+          # something instantly (Forrest's UAT round 5 clocked the worker's
+          # own first push at ~5 minutes) without ever promising "your
+          # agent is preparing" on a click that turned out refused or
+          # degraded (no recorded worker, a closed session, or the RPC
+          # itself failing) -- Runner is the one place that already knows
+          # which of those this click was.
+          Runner.run_step!(step, progress: progress) { warm_up!(step) }
+          step
+        when /view-(\d+)\z/
+          # Toggles: Details on the already-expanded row hides it again
+          # (Hide), Details on any other row expands that one instead --
+          # at most one row is ever expanded, so this is also what makes
+          # "expanding one collapses others" true.
+          step = Regexp.last_match(1).to_i
+          if progress.expanded_step == step
+            progress.collapse!
+          else
+            progress.expand_step!(step)
+          end
+          step
+        when /reset-course\z/
+          # Same effect as `streamweaver university-reset -y`: back up +
+          # clear the ledger, close the demo sessions the course itself
+          # opened. The trailing repush in `handle_event` below is what
+          # then renders the zero-state list -- this branch does not push.
+          progress.reset!
+          close_demo_sessions!
+          true
+        end
+      end
+
+      # The ledger write a "step is done" action makes: stamps `last_done`
+      # (rendered as an inline confirmation band) and collapses whichever
+      # row was expanded, so a stale expansion never sits open under the
+      # confirmation. Shared by handle_token's mark-done branch above
+      # (whose own caller, handle_event, does its own repush after every
+      # token) and `university_done!` below (which has no such caller and
+      # does its own repush) -- one write, two callers, so neither can drift
+      # from what "a step just got marked done" actually means.
+      def self.mark_step_done!(progress, step_number)
+        progress.mark_done!(step_number)
+        progress.collapse!
+      end
+
+      # True when `progress`'s ledger flips from "not all done" to "all
+      # done" somewhere inside the block -- the exact moment canvas.rb's
+      # completion recap (`all_done`) first appears in the very next
+      # repush, regardless of which step's write did it or whether the
+      # steps finished in order. Shared by `handle_event` (every canvas
+      # click, including a manual Mark-done) and `university_done!` (the
+      # CLI door a worker's closing ritual runs) so BOTH doors ask the same
+      # question the same way -- round-9 UAT first wired the scroll-to-top
+      # decision off the step-NUMBER argument, scoped to the CLI door alone,
+      # and missed the manual-click path: clicking Mark done on the last
+      # step from partway down the page reproduces the exact "recap appears
+      # below where you're looking" bug this exists to fix (code review).
+      def self.course_just_completed?(progress)
+        was_complete = progress.done_count >= Course::TOTAL_STEPS
+        yield
+        !was_complete && progress.done_count >= Course::TOTAL_STEPS
+      end
+
+      # The terminal door onto exactly what a Mark-done click does, for
+      # `streamweaver university-done` (CLI): the same ledger write plus the
+      # same repush, with no button event in the loop. Round-8 UAT: every
+      # step's closing ritual used to hand the "click Mark done" click back
+      # to the user; asking a worker to run this instead removes that
+      # hand-off entirely -- the manual button still works exactly as
+      # before, this is just a second door onto the same effect.
+      def self.university_done!(step_number, session_name: SESSION)
+        progress = Progress.load
+        just_completed = course_just_completed?(progress) { mark_step_done!(progress, step_number) }
+        repush(session_name: session_name, scroll_top: just_completed)
+        step_number
+      end
+
+      # Applies one event to the ledger and re-pushes the app so the
+      # rendered page reflects the new state. The re-push is not optional
+      # bookkeeping: a click swaps the page for the canvas_continue spinner
+      # (see canvas.rb), and this push is what puts the real page back --
+      # and, for Mark-done specifically, is what makes the row visibly flip
+      # to done AND shows the "Step N done" confirmation, both read
+      # straight off the ledger this same push just wrote.
+      # Returns the button token handled, or nil if the event carried none.
+      def self.handle_event(event, session_name: SESSION)
+        token = event.dig(:data, :button)
+        return nil unless token
+
+        progress = Progress.load
+        just_completed = course_just_completed?(progress) { handle_token(token, progress) }
+        repush(session_name: session_name, scroll_top: just_completed)
+        token
+      end
+
+      # "Reset course": closes DEMO_SESSION_NAMES, one `close` message each.
+      # Best-effort per session -- a session that was never opened (most
+      # courses never get all three names created) or an already-closed
+      # one just gets "Session not found" back, which is not a reason to
+      # skip the rest. Shared by the canvas's own Reset button
+      # (`handle_token`, above) and `streamweaver university-reset`.
+      def self.close_demo_sessions!
+        DEMO_SESSION_NAMES.each do |name|
+          begin
+            ::StreamWeaver::Canvas::Client.send_message(
+              ::StreamWeaver::Canvas::Protocol::Messages.close(name)
+            )
+          rescue ::StreamWeaver::Canvas::Client::NotRunningError, ::StreamWeaver::Canvas::Client::ConnectionError
+            nil
+          end
+          # growing_doc.rb's own persisted --extend keys (round-7 UAT) --
+          # otherwise a reset course still remembers last run's picks the
+          # next time its script runs. A no-op (FileUtils.rm_f) for every
+          # name but doc-demo's, which never had state to begin with.
+          ::StreamWeaver::University::Scripts::GrowingDocState.clear(name)
+        end
+      end
+
+      # Pushes a deterministic, no-LLM placeholder card to step `step_number`'s
+      # own demo canvas session -- called by Runner.run_step!'s block, which
+      # only runs once a send has actually landed, so the pane paints
+      # something in well under a second instead of sitting empty for
+      # however long the worker takes to reach its own first push
+      # (Forrest's UAT round 5: ~5 minutes), and never on a refused or
+      # degraded send. Creates the session first if it doesn't exist yet
+      # (canvas `push` errors on a session it can't find), WITH the same
+      # theme the step's own demo uses (STEP_DEMO_SESSIONS) -- a session's
+      # theme is fixed by whichever `create` reaches the bridge first, so
+      # creating with the wrong one here would permanently strand the
+      # worker's own later `--theme=doc` as a no-op for the rest of this
+      # get-started run. The worker's own first real push against the same
+      # session name replaces this outright -- nothing here persists.
+      # No-op for a step with no demo session of its own (steps 2 and 5).
+      def self.warm_up!(step_number)
+        demo = STEP_DEMO_SESSIONS[step_number.to_i] or return
+        step = Course.step(step_number) or return
+
+        ::StreamWeaver::Canvas::Client.send_message(
+          ::StreamWeaver::Canvas::Protocol::Messages.create(demo.name, theme: demo.theme)
+        )
+        ::StreamWeaver::Canvas::Client.send_message(
+          ::StreamWeaver::Canvas::Protocol::Messages.push(demo.name, warm_up_dsl(step), source_dir: nil)
+        )
+      rescue ::StreamWeaver::Canvas::Client::NotRunningError, ::StreamWeaver::Canvas::Client::ConnectionError
+        nil
+      end
+
+      # The warm-up card's own DSL source, instance_eval'd bridge-side --
+      # same "one string of Ruby, eval'd fresh" contract canvas.rb's own
+      # file header describes. Deliberately small: a title, one line of
+      # what's coming, a tasteful mini stat row plus a one-sentence
+      # callout, and the "preparing" line -- everything a terminal-only
+      # tool cannot show while a real worker is still thinking.
+      def self.warm_up_dsl(step)
+        <<~RUBY
+          use_theme :doc
+          use_layout :default
+          card(depth: :elevated) do
+            card_header { header2 #{step[:title].inspect} }
+            card_body do
+              phrase #{"Coming up: #{step[:payoff]}".inspect}
+              div(style: "display:flex; gap:14px; margin:16px 0;") do
+                stat_display value: #{step[:number].to_s.inspect}, label: "this step"
+                stat_display value: #{StreamWeaver::University::Course::GETTING_STARTED_STEPS.size.to_s.inspect}, label: "steps in the course"
+              end
+              callout "Your agent is preparing the live demo…", variant: :info
+            end
+          end
+        RUBY
+      end
+
+      # An invisible marker element, appended to canvas.rb's own pushed text
+      # only when `scroll_top:` is true -- never part of the file itself.
+      # bridge_server.rb's polling script looks for this element's id in the
+      # HTML a poll just swapped in and, when present, scrolls the viewer to
+      # the TOP of the new page instead of running its ordinary "follow the
+      # viewer's own near-bottom scroll position" logic (built for a growing
+      # doc continuing in place, not a full page reshape -- round-9 UAT).
+      # Carries no ledger state and needs no cleanup: it only exists in the
+      # one push's HTML that asked for it, and the very next poll response
+      # replaces the whole DOM regardless, so "honored once" is true by
+      # construction rather than something this code has to enforce.
+      #
+      # The id itself is interpolated from Canvas::SCROLL_TOP_HINT_ID (a
+      # tiny standalone file both this module and BridgeServer require --
+      # see its own comment for why it isn't just defined on BridgeServer)
+      # rather than repeated here as a second literal -- two copies of the
+      # same string is exactly the drift this marker's own contract cannot
+      # survive.
+      SCROLL_TOP_HINT_DSL =
+        %(div(id: #{Canvas::SCROLL_TOP_HINT_ID.inspect}, style: "display:none") {})
+
+      def self.repush(session_name: SESSION, scroll_top: false)
+        canvas_path = File.expand_path('canvas.rb', __dir__)
+        dsl = File.read(canvas_path)
+        dsl = "#{dsl}\n\n#{SCROLL_TOP_HINT_DSL}" if scroll_top
+        ::StreamWeaver::Canvas::Client.send_message(
+          ::StreamWeaver::Canvas::Protocol::Messages.push(session_name, dsl, source_dir: nil)
+        )
+      end
+
+      # Blocks for exactly one canvas event, applies it, and re-pushes.
+      # Returns the button token handled, or nil on timeout / no bridge.
+      # Kept as the single-shot form for manual verification; `run!` uses
+      # the persistent stream instead.
+      def self.step!(session_name: SESSION, timeout: 300)
+        result = ::StreamWeaver::Canvas::Client.send_and_wait(
+          { type: 'subscribe', name: session_name },
+          event_type: 'event',
+          timeout: timeout
+        )
+        return nil unless result
+
+        handle_event(result, session_name: session_name)
+      rescue ::StreamWeaver::Canvas::Client::NotRunningError, ::StreamWeaver::Canvas::Client::ConnectionError
+        nil
+      end
+
+      # Runs until killed, over ONE held-open connection at a time. Not a
+      # loop of `step!`: that reconnects after every event, and the gap
+      # lands exactly where the user is most likely to click again -- while
+      # the re-push is in flight.
+      #
+      # The outer loop is not optional robustness. `each_event` returns when
+      # the bridge closes the socket, which a `canvas-restart` does
+      # routinely; without reconnecting, the listener would exit and the
+      # canvas would go permanently dead -- and worse than before this
+      # story, because the canvas_continue marker means a click with no
+      # re-push leaves "Working..." on screen forever and sets
+      # _swFeedbackActive, which makes the adapter swallow every later
+      # click. Same reason a not-yet-running bridge waits rather than
+      # exiting: `university-listener start` must not report a pid for a
+      # process that is already gone.
+      def self.run!(session_name: SESSION)
+        complained = false
+
+        loop do
+          begin
+            ::StreamWeaver::Canvas::Client.each_event(session_name) do |event|
+              handle_event(event, session_name: session_name)
+            rescue StandardError => e
+              # One bad click must not take down a listener nobody can see.
+              warn "university-listener: #{e.class}: #{e.message}"
+            end
+            complained = false
+          rescue StandardError => e
+            # Deliberately every StandardError, not just the two bridge
+            # errors: this process must not die anywhere the user can't see
+            # it, and RECONNECT_DELAY below already rules out a hot spin, so
+            # there is no failure here from which exiting beats retrying.
+            #
+            # Logged once per outage, not once per second: the log is
+            # append-only with nothing rotating it, and a bridge left down
+            # overnight would otherwise put ~86k lines in a file the user
+            # doesn't know exists.
+            unless complained
+              warn "university-listener: waiting for the canvas bridge (#{e.class}: #{e.message})"
+              complained = true
+            end
+          end
+
+          sleep RECONNECT_DELAY
+        end
+      end
+
+      # --- Process lifecycle ------------------------------------------------
+      # `get-started` starts this in the background; without it every button
+      # on the canvas does nothing at all (UAT 2026-08-29). The env
+      # overrides mirror Progress/Runner so specs never touch the real files.
+
+      def self.pid_path
+        ENV['STREAMWEAVER_UNIVERSITY_LISTENER_PID'] ||
+          File.expand_path('~/.streamweaver/university/listener.pid')
+      end
+
+      def self.log_path
+        ENV['STREAMWEAVER_UNIVERSITY_LISTENER_LOG'] ||
+          File.expand_path('~/.streamweaver/university/listener.log')
+      end
+
+      # The pid recorded by `start!`, or nil if there isn't a usable one.
+      def self.recorded_pid
+        pid = File.read(pid_path).to_i
+        pid.positive? ? pid : nil
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      def self.running?
+        pid = recorded_pid or return false
+        ours?(pid)
+      end
+
+      # Alive AND plausibly the listener we spawned. `start!` uses
+      # `pgroup: true`, so our listener is its own process-group leader;
+      # a pid recycled onto some unrelated process almost never is. Without
+      # this check, a crash plus enough pid churn has `get-started` sending
+      # TERM to whatever the user happens to be running.
+      def self.ours?(pid)
+        Process.kill(0, pid)
+        Process.getpgid(pid) == pid
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+      private_class_method :ours?
+
+      # How long start! waits for the listener it just TERMed to actually go.
+      EXIT_POLL = 0.05
+      EXIT_WAIT = 40 # * EXIT_POLL = 2s
+
+      # Stops any listener already recorded, waits for it to actually exit,
+      # then spawns a fresh detached one. Stopping first is what keeps a
+      # second `get-started` (or a canvas-restart) from leaving two
+      # listeners racing to re-push -- whichever push lands second wins, so
+      # the loser shows stale state. Returns the new pid.
+      def self.start!(session_name: SESSION)
+        previous = recorded_pid
+        stop!
+        await_exit(previous)
+
+        FileUtils.mkdir_p(File.dirname(log_path))
+        FileUtils.mkdir_p(File.dirname(pid_path))
+
+        pid = Process.spawn(
+          RbConfig.ruby,
+          "-I#{File.expand_path('../..', __dir__)}",
+          '-r', 'stream_weaver/university/listener',
+          '-e', "StreamWeaver::University::Listener.run!(session_name: #{session_name.inspect})",
+          out: [log_path, 'a'], err: %i[child out], pgroup: true
+        )
+        Process.detach(pid)
+        File.write(pid_path, "#{pid}\n")
+        pid
+      end
+
+      # TERM is asynchronous, so "stopped" is a request, not a fact. Spawning
+      # the replacement while the old one still holds its connection gives
+      # two listeners racing to re-push, and whichever push lands second
+      # wins -- so the canvas can settle on state the user did not ask for.
+      def self.await_exit(pid)
+        return unless pid
+
+        EXIT_WAIT.times do
+          return unless ours?(pid)
+
+          sleep EXIT_POLL
+        end
+
+        # Falling through here is the very race this method exists to
+        # prevent, so escalate rather than spawn a rival quietly.
+        warn "university-listener: pid #{pid} ignored TERM, sending KILL"
+        Process.kill('KILL', pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+      private_class_method :await_exit
+
+      # Terminates the recorded listener. Always clears the pid file, even
+      # when the process was already gone -- a stale pid file left by a
+      # crash must not look like a running listener forever.
+      def self.stop!
+        pid = recorded_pid
+        return false unless pid && ours?(pid)
+
+        Process.kill('TERM', pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      ensure
+        FileUtils.rm_f(pid_path)
+      end
+
+      def self.status
+        alive = running?
+        { running: alive, pid: alive ? recorded_pid : nil, log: log_path }
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  $LOAD_PATH.unshift(File.expand_path('../..', __dir__))
+  require 'stream_weaver'
+  StreamWeaver::University::Listener.run!
+end

data/lib/stream_weaver/university/progress.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+require 'time'
+
+module StreamWeaver
+  module University
+    # Getting Started's per-step completion ledger, persisted as YAML at
+    # `~/.streamweaver/university/progress.yml`. A plain file, not in-memory
+    # session state, so "survives a bridge restart" just means every write
+    # hits disk immediately and a later re-push re-reads it (progress-ledger
+    # criterion 5).
+    #
+    # STREAMWEAVER_UNIVERSITY_PROGRESS overrides the path -- used by specs
+    # (never touch the developer's real ledger) and by anyone running a
+    # second, isolated University instance.
+    class Progress
+      DEFAULT_PATH = '~/.streamweaver/university/progress.yml'
+
+      # Expanded per call, not at the constant, so a spec that redirects
+      # HOME is redirected here too -- and so this mirrors
+      # University::Runner.worker_path exactly, as its comment claims.
+      def self.path
+        ENV['STREAMWEAVER_UNIVERSITY_PROGRESS'] || File.expand_path(DEFAULT_PATH)
+      end
+
+      # Loads the ledger at the current path (honoring the env override at
+      # call time, not at class-load time).
+      def self.load
+        new(path)
+      end
+
+      def initialize(path = self.class.path)
+        @path = path
+        @data = read
+      end
+
+      attr_reader :path
+
+      def done?(step_number)
+        !!@data['done'][step_number.to_s]
+      end
+
+      # Clears `last_run` along the way: that field reports what the user's
+      # last click did, and marking a step done IS a later click. Without
+      # this, a run notice (in degraded mode, a whole copy-this-prompt
+      # block for step 1) stays pinned above the step list for days.
+      #
+      # Stamps `last_done` for the SAME reason `record_run!` stamps
+      # `last_run`: the next canvas render needs to say what a click just
+      # did, and it needs to say so reliably. An earlier version of this
+      # feedback used a bridge toast instead -- broken by construction,
+      # because the toast and this same write's re-push land in the same
+      # ~500ms poll response, and the client unconditionally clears any
+      # toast the instant new HTML arrives (bridge_server.rb's poll()).
+      # Putting the message IN the re-pushed HTML has no such race.
+      def mark_done!(step_number)
+        @data['done'][step_number.to_s] = true
+        @data['last_run'] = nil
+        @data['last_done'] = { 'step' => step_number.to_i, 'at' => Time.now.utc.iso8601 }
+        write
+        self
+      end
+
+      # Undoes a mark-done -- not exercised by the current UI, but the
+      # natural inverse and cheap to keep correct for tests/future use.
+      # Clears `last_run`/`last_done` for the same reason mark_done! sets
+      # them: this instance no longer reflects what either field claims.
+      def unmark_done!(step_number)
+        @data['done'].delete(step_number.to_s)
+        @data['last_run'] = nil
+        @data['last_done'] = nil
+        write
+        self
+      end
+
+      def done_steps
+        @data['done'].select { |_k, v| v }.keys.map(&:to_i).sort
+      end
+
+      def done_count
+        done_steps.size
+      end
+
+      # Records the outcome of one Run/Repeat click (Runner#run_step!).
+      #
+      # `requested` only gains a timestamp when the prompt actually reached
+      # the worker session -- a click that found no worker, or a closed
+      # tab, is not a send, and a `requested_at` for it would be a lie the
+      # ledger tells forever. `last_run` always updates: it is what the
+      # next canvas render reads to report what happened, including the
+      # failures that need a copy-the-prompt fallback.
+      def record_run!(step_number, status:)
+        now = Time.now.utc.iso8601
+        @data['requested'][step_number.to_s] = now if status.to_s == 'sent'
+        @data['last_run'] = { 'step' => step_number.to_i, 'status' => status.to_s, 'at' => now }
+        @data['last_done'] = nil
+        write
+        self
+      end
+
+      def requested_at(step_number)
+        @data['requested'][step_number.to_s]
+      end
+
+      # The last Run/Repeat outcome: {'step' =>, 'status' =>, 'at' =>}, or
+      # nil before the first click.
+      def last_run
+        @data['last_run']
+      end
+
+      # The step a Mark-done click just finished: {'step' =>, 'at' =>}, or
+      # nil. Mutually exclusive with `last_run` -- each write clears the
+      # other, so the canvas only ever has one "what just happened" band to
+      # show, whichever action was more recent.
+      def last_done
+        @data['last_done']
+      end
+
+      # Which step's row is expanded inline on the course list, or nil if
+      # none is. canvas-push instance_evals canvas.rb fresh on every render
+      # (no in-memory app state survives between pushes -- see canvas.rb's
+      # file header), so which row (if any) renders expanded has to live
+      # somewhere that does survive: this ledger, same as done/last_run.
+      # Also what makes a deep link work -- whoever set this before the
+      # canvas was last (re)pushed gets that row auto-expanded on load,
+      # with no separate navigation step to get there.
+      #
+      # Still the `'viewing'` key on disk -- deliberately not renamed to
+      # `'expanded'` alongside this method (single-mode, 2026-09-03): only
+      # the meaning of "which row" changed (a screen to navigate to versus
+      # a row to expand in place), not what's being tracked, and a silent
+      # key rename would orphan whatever any already-running canvas last
+      # wrote. Renaming the key belongs to a real migration, not this diff.
+      def expanded_step
+        @data['viewing']
+      end
+
+      # Expands step `step_number`'s row inline on the next render --
+      # "Details" on a step row. At most one step is ever expanded: this
+      # simply overwrites whichever was expanded before, which is what
+      # makes "expanding one collapses others" true by construction.
+      def expand_step!(step_number)
+        @data['viewing'] = step_number.to_i
+        write
+        self
+      end
+
+      # Collapses whichever row is expanded -- "Hide" on an expanded row's
+      # own Details button, and what mark_done! calls so a Mark-done click
+      # never leaves a stale expansion open under the confirmation band.
+      def collapse!
+        @data['viewing'] = nil
+        write
+        self
+      end
+
+      # "Reset course": backs up whatever was on disk to `<path>.bak`
+      # (overwriting any earlier backup -- one reset's worth of undo, not a
+      # history) and returns to the zero-state. Deletes rather than
+      # rewrites the file, so this in-memory instance and a freshly loaded
+      # one agree the same way every other zero-state case already does
+      # (`#read`, below, and the "does not create the file just by reading
+      # it" contract) -- there is exactly one representation of "nothing
+      # done yet", not two that both mean it.
+      def reset!
+        FileUtils.cp(@path, "#{@path}.bak") if File.exist?(@path)
+        FileUtils.rm_f(@path)
+        @data = blank_data
+        self
+      end
+
+      private
+
+      def read
+        return blank_data unless File.exist?(@path)
+
+        loaded = YAML.safe_load(File.read(@path)) || {}
+        {
+          'done' => loaded['done'] || {},
+          'requested' => loaded['requested'] || {},
+          'last_run' => loaded['last_run'],
+          'last_done' => loaded['last_done'],
+          'viewing' => loaded['viewing']
+        }
+      rescue Psych::SyntaxError
+        blank_data
+      end
+
+      def blank_data
+        { 'done' => {}, 'requested' => {}, 'last_run' => nil, 'last_done' => nil, 'viewing' => nil }
+      end
+
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, YAML.dump(@data))
+      end
+    end
+  end
+end