samagotchi 0.124.0 → 0.125.0

data/lib/samagotchi/terminal_ui/exit_lines.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../tools/task_record"
+
+module Samagotchi
+  class TerminalUI
+    # The /exit ask and its reply lines: pure text from a reply, holds, and
+    # the invocation used to spell commands.
+    module ExitLines
+      module_function
+
+      # Why a request the Bridge read after its deadline didn't go through.
+      LATE = "worker not answering in time"
+      # An exit the worker agreed to in an empty session. Said before it has
+      # left: it checks again once it lets go, and a note or prompt arriving
+      # first keeps the session (SessionManager.discard_left_session).
+      EMPTY_WORDS = "the session is empty: it will be discarded if nothing arrives before its worker stops."
+      EMPTY_EXIT = "Detached; #{EMPTY_WORDS}"
+      # Why the worker stayed up after /exit, by the reason it gave.
+      HELD_REASONS = {
+        "turn_running" => "a turn is running", "input_queued" => "prompts are queued",
+        "continue_offered" => "a continue offer is pending", "client_connected" => "another UI is attached",
+        "reminders" => "reminders are set", "starting" => "the worker is still starting",
+        "background_tasks" => "background tasks it started are still running",
+        "delegates" => "delegates of this session are still running"
+      }.freeze
+      # How to end a background task that holds the worker up (an older
+      # worker's 409 has no hint of its own).
+      TASK_STOP_HINT = "stop one with the web's stop-task button or by asking for task_stop"
+      # The /exit ask, when every hold is one the user can stop: what still
+      # runs, then the three answers. Each kind, singular and plural.
+      EXIT_HOLD_WORDS = {
+        "reminders" => %w[reminder reminders],
+        "background_tasks" => ["background task", "background tasks"],
+        "delegates" => %w[delegate delegates]
+      }.freeze
+      # The 200's +stopped+ keys, by the kind the ask lists them under.
+      STOPPED_KEYS = { "reminders" => "reminders", "tasks" => "background_tasks", "delegates" => "delegates" }.freeze
+      EXIT_ASK_OPTIONS = ["Keep running in the background (detach)", "Stop them and exit", "Back to the session"].freeze
+      # How the ask reads an answer.
+      EXIT_ANSWERS = {
+        "1" => :keep, "keep" => :keep, "detach" => :keep, "background" => :keep,
+        "2" => :stop, "stop" => :stop, "exit" => :stop,
+        "3" => :back, "back" => :back, "stay" => :back
+      }.freeze
+
+      # The ask: what still runs, then the three answers.
+      def ask_lines(holds)
+        lines = holds.map do |hold|
+          items = Array(hold["items"])
+          singular, plural = hold_words(hold["kind"])
+          "  • #{items.size} #{items.size == 1 ? singular : plural}: #{items.map { |item| item_word(item, hold["kind"]) }.join(", ")}"
+        end
+        lines += EXIT_ASK_OPTIONS.each_with_index.map { |option, index| "  #{index + 1}. #{option}" }
+        (["This session still has:"] + lines).join("\n")
+      end
+
+      # One entry of a hold: the command or name, with its detail in
+      # brackets; a delegate leads with its short id and its title in quotes.
+      def item_word(item, kind)
+        label = item["label"].to_s
+        label = "#{item["id"].to_s[0, 8]} \"#{label}\"" if kind == "delegates"
+        detail = item["detail"].to_s
+        detail.empty? ? label : "#{label} (#{detail})"
+      end
+
+      # 1: detach, everything left running.
+      def kept_line(holds, via:, session_id:)
+        "Detached; the session keeps running (#{hold_words_list(holds)}). " \
+          "Re-attach with: #{via.attach(session_id)}"
+      end
+
+      # "2 reminders, 1 background task, 1 delegate" from the ask's holds.
+      def hold_words_list(holds)
+        holds.map do |hold|
+          items = Array(hold["items"])
+          singular, plural = hold_words(hold["kind"])
+          "#{items.size} #{items.size == 1 ? singular : plural}"
+        end.join(", ")
+      end
+
+      def hold_words(kind) = EXIT_HOLD_WORDS.fetch(kind.to_s, [kind.to_s, kind.to_s])
+
+      # What a stop-all exit stopped: "stopped 2 reminders (api_health, git
+      # push), 1 background task (rails s)"; nil when it stopped nothing.
+      def stopped_words(stopped)
+        return nil unless stopped.is_a?(Hash)
+
+        parts = STOPPED_KEYS.filter_map do |key, kind|
+          names = Array(stopped[key])
+          next if names.empty?
+
+          singular, plural = hold_words(kind)
+          "#{names.size} #{names.size == 1 ? singular : plural} (#{names.join(", ")})"
+        end
+        parts.empty? ? nil : "stopped #{parts.join(", ")}"
+      end
+
+      def exit_line(reply, via:, session_id:)
+        error = reply.json&.fetch("error", nil)
+        case reply.status
+        when 200
+          stopped = stopped_words(reply.json&.fetch("stopped", nil))
+          return EMPTY_EXIT if discards?(reply) && stopped.nil?
+          return "Detached; #{stopped}. #{EMPTY_WORDS.capitalize}" if discards?(reply)
+
+          "Detached; #{stopped || "the session's worker is stopping"}. Resume with: #{via.resume(session_id)}"
+        when 409
+          reason = reply.json&.fetch("reason", nil).to_s
+          "Detached; the session keeps running (#{held_words(reason, reply.json&.fetch("tasks", nil))}). " \
+            "Re-attach with: #{via.attach(session_id)}"
+        when 0 then exit_failed_line("no reply", via: via, session_id: session_id)
+        when 408 then exit_failed_line(LATE, via: via, session_id: session_id)
+        else
+          # A worker from before the route answers the Bridge's plain 404.
+          if error == "not_found"
+            return "Detached; this worker runs an older chi and can't be stopped from here: #{via.command("sessions stop #{session_id}")}"
+          end
+
+          exit_failed_line([reply.status, reply.json&.fetch("detail", nil) || error].compact.join(" "),
+                           via: via, session_id: session_id)
+        end
+      end
+
+      # Why the worker stayed up; the background tasks it waits for by
+      # their short id and command (a finish wake's, D3), and how to stop one.
+      def held_words(reason, tasks)
+        words = HELD_REASONS.fetch(reason, reason)
+        listed = Array(tasks).filter_map { |t| "#{Tools::TaskRecord.short_id(t["id"])} (#{t["command"]})" if t.is_a?(Hash) }
+        listed.empty? ? words : "#{words}: #{listed.join(", ")}; #{TASK_STOP_HINT}"
+      end
+
+      # An older worker leaves the field out.
+      def discards?(reply) = reply.json&.fetch("discard", nil) == true
+
+      def exit_failed_line(why, via:, session_id:)
+        "Detached (could not ask the worker to stop: #{why}). Re-attach with: #{via.attach(session_id)}"
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/join_replay.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require_relative "../context_note"
+require_relative "../image_store"
+require_relative "../log"
+require_relative "../message_parts"
+require_relative "../output_formatter"
+require_relative "../steer"
+require_relative "../tool_activity"
+require_relative "../tool_view"
+require_relative "../turn_note"
+require_relative "event_renderer"
+require_relative "formatting"
+
+module Samagotchi
+  class TerminalUI
+    # Draws the saved part of a worker snapshot when an attached TUI joins or
+    # resyncs. The live loop owns the collaborators; this owns replay only.
+    class JoinReplay
+      include Formatting
+
+      # How much of the last answer a join shows.
+      JOIN_ANSWER_LINES = 12
+      JOIN_ANSWER_CHARS = 1200
+
+      def initialize(screen:, view:, link:, gaps:, renderer:)
+        @screen = screen
+        @view = view
+        @link = link
+        @gaps = gaps
+        @renderer = renderer
+      end
+
+      def render_join(snapshot, saved)
+        render_join_header(Array(snapshot[:messages]))
+        render_join_gap(snapshot, saved)
+      end
+
+      # The snapshot's cards and between-turns notices (Bridge CardStore):
+      # on join the ones since the last turn (and the running turn's), as
+      # the join header shows the last exchange; on a resync only cards not
+      # shown here yet, and not the ones an earlier worker saved (a resync
+      # onto a new worker: earlier turns, not news). A turn's own rows (notices, retries) are left out:
+      # the running turn's come with its parts, and the join shows no older
+      # turn's steps.
+      def render_snapshot_cards(entries, joining:)
+        entries.each do |entry|
+          case entry[:type].to_s
+          when "hook_notice"
+            next if entry[:in_turn]
+
+            @screen.commit(EventRenderer.hook_notice_line(entry)) if joining && entry[:turns_since].to_i.zero?
+          when "card"
+            next unless joining ? entry[:turns_since].to_i.zero? : !entry[:earlier] && !@renderer.card_shown?(entry[:id])
+
+            @renderer.render_card(entry, updated: entry[:updated] == true)
+          end
+        end
+      end
+
+      private
+
+      # Where the session's last activity was: its newest stamped entry,
+      # else its saved recap's time. A gap ago (and no turn running): one
+      # line after the join block says when.
+      def render_join_gap(snapshot, saved)
+        @gaps.seed(snapshot[:messages], fallback: saved&.dig(:created_at))
+        return if snapshot[:current_turn]
+
+        line = @gaps.join_line
+        @screen.commit(gap_divider(line)) if line
+      end
+
+      def render_join_header(messages)
+        exchange = messages.select { |m| %w[user model assistant].include?(m[:role].to_s) }
+        # The id stays findable: the detach line and chi sessions list show it.
+        Log.session_id = @link.client.session_id
+        Log.info(:attached, "joined", session: @link.client.session_id, messages: exchange.size,
+                                      notes: messages.count { |m| ContextNote.note?(m) })
+        last_user = exchange.rindex { |m| Steer.prompt?(m) }
+        render_join_notes(messages)
+        return unless last_user
+
+        @screen.commit(join_prompt_line(exchange[last_user]))
+        # An image-only turn's text names its images already.
+        unless ImageRef.placeholder_only?(exchange[last_user][:content])
+          Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
+        end
+        from = messages.index { |m| m.equal?(exchange[last_user]) }
+        render_join_steps(messages, from, durations: join_tool_records(exchange[last_user]))
+        record = @link.saved_turn_record(exchange[last_user][:turn_id] || exchange[last_user]["turn_id"])
+        failed = join_failed_record(record)
+        # A turn that ended with no answer: its notice, as live.
+        empty = messages.drop(from + 1).filter_map { |m| TurnNote.empty_answer(m) }.last
+        if empty
+          @screen.commit(format_empty_answer_line(empty[:retries] || empty["retries"], empty[:refusal] || empty["refusal"]))
+        elsif failed
+          # A failed turn whose steps stayed: the line the live view left,
+          # and no step text as if it were the answer (the web keeps a
+          # failed turn's texts as steps too).
+          failure = failed["failure"]
+          @screen.commit(@view.turn_failed_line(failure["summary"] || failure["message"], failed["duration_ms"]))
+          @screen.commit(@view.turn_end_hint(ROLLBACK_HINT)) if failure["kept_steps"]
+        elsif record && record["status"] == "canceled"
+          # A canceled turn (a Stop, Ctrl-C): its line, as live, and no
+          # text it streamed before the cancel as if it were the answer.
+          @screen.commit(@view.turn_canceled_line(record["cancellation_reason"], record["duration_ms"], by: record["cancelled_by"]))
+          @screen.commit(@view.turn_end_hint(ROLLBACK_HINT)) unless record["continue"]
+        else
+          # The saved answer is raw: the latest keeps its thinking, and one may
+          # be only a tool call.
+          answer = exchange[(last_user + 1)..].reverse_each
+                                             .map { |m| OutputFormatter.strip_markup(m[:content]) }
+                                             .find { |text| !text.empty? }
+          @screen.commit(last_lines(answer)) if answer
+        end
+        render_join_notes(messages, after_exchange: true)
+      end
+
+      # What the last exchange did, as the live turn drew it: each saved
+      # call's tool row (action, params, status from its result, and its
+      # duration from +durations+, the turn's saved tool records) and a
+      # plugin's steer where it came. The step texts stay out, as live (the
+      # ticker's).
+      def render_join_steps(messages, from, durations: [])
+        records = durations.dup
+        messages.each_with_index.drop(from + 1).each do |m, i|
+          if Steer.steer?(m)
+            @screen.commit(format_steer_line(source: m[:source], text: m[:content]))
+          elsif %w[model assistant].include?(m[:role].to_s)
+            responses = messages.drop(i + 1).take_while { |r| r[:role].to_s == "tool_response" }
+            Array(MessageParts.for_message(m, responses)&.dig(:tools)).each do |part|
+              record = join_record(records, part)
+              duration = record&.dig("duration_ms")
+              @screen.commit(join_tool_line(part, duration_ms: duration.is_a?(Numeric) ? duration : nil,
+                                                  saved_status: record&.dig("status"),
+                                                  auto_allowed: record&.dig("guardrail")))
+            end
+          end
+        end
+      end
+
+      # The prompt's turn's saved tool records (AttachLink: SessionMetrics,
+      # in this machine's state dir, as #attach_images): none for a prompt
+      # with no turn id (an older session) or a session with no analytics.
+      def join_tool_records(prompt)
+        @link.saved_tool_records(prompt[:turn_id] || prompt["turn_id"])
+      end
+
+      # The turn's saved +record+ when it failed with the fields its line is
+      # made of (SessionMetrics#failure_fields), else nil: a completed or
+      # older turn — or one saved before the failure field — draws its
+      # answer as before (a canceled one its line).
+      def join_failed_record(record)
+        return nil unless record && record["status"] == "failed" && record["failure"].is_a?(Hash)
+
+        failure = record["failure"]
+        return nil if failure["summary"].to_s.empty? && failure["message"].to_s.empty?
+
+        record
+      end
+
+      # The saved record of +part+'s call (its duration and status): the
+      # next record of its tool, in call order, consumed with the ones it
+      # skipped. By tool and order, not by iteration: an empty retry spends
+      # an iteration that left no message (as the web's timing.js
+      # takeRecord). nil for a call that left none: it never finished, or a
+      # worker before turn ids saved it.
+      def join_record(records, part)
+        return nil if part[:output].nil?
+
+        at = records.index { |r| r["tool"].to_s == part[:tool].to_s }
+        return nil unless at
+
+        records.shift(at + 1).last
+      end
+
+      # A saved call's row; "no result" for a call the turn never answered
+      # (it ended first). Its status is the saved record's, as live and the
+      # web's reload (a guardrail's "blocked" is no error), else read from
+      # its result (a guardrail's deny text reads blocked too). A record that
+      # System 1 allowed once (+auto_allowed+, its saved {rule, p}) says so,
+      # as the live row does.
+      def join_tool_line(part, duration_ms: nil, saved_status: nil, auto_allowed: nil)
+        output = part[:output]
+        command = part.dig(:view, :truncated) ? nil : part.dig(:view, :command)
+        text = ToolActivity.saved_result_text(output) unless output.nil?
+        status = if output.nil?
+                   "no result"
+                 elsif !saved_status.to_s.empty?
+                   saved_status.to_s
+                 elsif ToolActivity.guardrail_denied?(text)
+                   "blocked"
+                 else
+                   ToolActivity.tool_activity_status(text, part[:tool], command: command)
+                 end
+        activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
+                     params: part[:params], status: status,
+                     description: ToolView.description_title(part[:view] || {}) }
+        "#{format_tool_activity_line(activity, duration_ms: duration_ms)}" \
+          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}#{format_tool_cut_suffix(part[:output_truncated])}" \
+          "#{auto_allowed_suffix(auto_allowed)}"
+      end
+
+      # The live row's System 1 suffix for a saved record's {rule, p}.
+      def auto_allowed_suffix(saved)
+        return "" unless saved.is_a?(Hash)
+
+        format_tool_guardrail_suffix({ decided_by: "system one", p: saved["p"] || saved[:p] })
+      end
+
+      # The context notes that came since the last prompt (all of them in a
+      # session with none), after the exchange the header shows.
+      def render_join_notes(messages, after_exchange: false)
+        last_user = messages.rindex { |m| Steer.prompt?(m) }
+        return if after_exchange != !last_user.nil?
+
+        messages[(last_user ? last_user + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
+          @screen.commit(context_note_line(ContextNote.label_of(m), ContextNote.text_of(m)))
+        end
+      end
+
+      # The end of a long answer; the whole of it is in the session.
+      def last_lines(text)
+        lines = text.split("\n", -1)
+        if lines.size > JOIN_ANSWER_LINES
+          text = "(… #{lines.size - JOIN_ANSWER_LINES} earlier lines)\n#{lines.last(JOIN_ANSWER_LINES).join("\n")}"
+        end
+        return text if text.length <= JOIN_ANSWER_CHARS
+
+        "(… earlier text)\n…#{text[-JOIN_ANSWER_CHARS..]}"
+      end
+    end
+  end
+end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.124.0"
+  VERSION = "0.125.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -1878,9 +1878,10 @@ module Samagotchi
       def home_label(dir) = Paths.tilde(dir)
 
       # <body> data for the page: where sessions are stored, where an
-      # all-view new chat starts (the start folder), and, when ?dir names a
-      # folder in a repo, that project's name and root. A bad dir adds
-      # nothing here: the list call answers 400 and the page says so.
+      # all-view new chat starts (the start folder), the home folder, and,
+      # when ?dir names a folder in a repo, that project's name and root. A
+      # bad dir adds nothing here: the list call answers 400 and the page
+      # says so.
       # Without ?dir (and without ?scope=all) the page is the start folder's
       # project view when that folder is in a repo: data-scope-dir names it
       # for the page (the URL stays bare, so a token's 303, a link code's
@@ -1890,6 +1891,9 @@ module Samagotchi
         # version: the chi that served the page; the events snapshot names
         # the one serving now (an upgraded chi web after a reconnect).
         attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(start_dir), "version" => Samagotchi::VERSION }
+        # The owner's home: a claim link's quote reads it "~", as the
+        # participant page shows it (claim_link.js).
+        attrs["home"] = Dir.home
         attrs["view"] = view_name(req.params["view"])
         # Only when on: the page reads its presence (the turn view ignores it).
         attrs["working-set"] = "1" if working_set?(req.params["working_set"])

data/lib/samagotchi/web/participants_admin.rb

@@ -26,15 +26,17 @@ module Samagotchi
       # +identity_header+: the header this chi web's auth proxy names the
       # signed-in user in (null without one), for the Invite's email field;
       # +mode+: what a participant invited now gets, "pair" or "review"
-      # (ReviewStart.share_terms), for the panel's words.
-      def handle_participants_list(_req, id = nil)
+      # (ReviewStart.share_terms), for the panel's words; +link_base+: where
+      # a participant's link opens (participant_base), for a claim link
+      # (claim_link.js) the participant's browser opens with its cookie.
+      def handle_participants_list(req, id = nil)
         now = @grants.now
         grants = @grants.list(session_id: id).map { |grant| grant.public_h(now) }
         return json_response(200, { participants: grants }) unless id
 
         terms = ReviewStart.share_terms(Session.load(id, state_dir: default_state_dir), state_dir: default_state_dir)
         json_response(200, { participants: with_spend(id, grants), warning: terms.warning, mode: terms.mode.to_s,
-                             identity_header: @public_url&.identity_header })
+                             identity_header: @public_url&.identity_header, link_base: participant_base(req) })
       rescue Grants::Unwritable => e
         grants_unwritable(e)
       end
@@ -149,10 +151,19 @@ module Samagotchi
           return @public_url.link(@link_codes.issue(kind: :grant, token: token, ttl: ttl), "s=#{id}")
         end
 
+        "#{participant_base(req)}?token=#{token}#s=#{id}"
+      end
+
+      # Where a participant's link opens, no token: web.public_url's origin,
+      # else this chi web's LAN address, else the Host asked
+      # ("http://192.168.1.5:4567/").
+      def participant_base(req)
+        return "#{@public_url.origin}/" if @public_url
+
         host = req.get_header("HTTP_HOST").to_s
         port = host[/:(\d+)\z/, 1] || req.port.to_s
         name = @lan ? @lan[:ip] : host.sub(/:\d*\z/, "")
-        "http://#{name}:#{port}/?token=#{token}#s=#{id}"
+        "http://#{name}:#{port}/"
       end
     end
   end

data/lib/samagotchi/web/public/annotate_bar.css

@@ -1,6 +1,6 @@
-/* The selection bubble (annotate_bar.js): Annotate + the presets (web.annotate_presets), small pills with a gap (they
-   wrap on a narrow page). Both pages link it: the owner's (app.js) and the participant page (participant.js). Colours
-   are tokens.css's. */
+/* The selection bubble (annotate_bar.js): Annotate + the presets (web.annotate_presets), Copy link last where the page
+   has one, small pills with a gap (they wrap on a narrow page). Both pages link it: the owner's (app.js) and the
+   participant page (participant.js). Colours are tokens.css's. */
 #annotateBar{position:fixed;z-index:20;display:flex;flex-wrap:wrap;gap:4px;max-width:calc(100vw - 16px)}
 #annotateBar[hidden]{display:none}
 #annotateBar button{font-size:12px;padding:4px 10px;border-radius:999px;box-shadow:0 2px 8px var(--shadow-strong)}
@@ -15,4 +15,8 @@
 #annotateBar.docked{right:8px;justify-content:center}
 @media (pointer:coarse){#annotateBar button{font-size:14px;padding:8px 14px}}
 #annotateBar .annotate-more-list[hidden]{display:none}
-#annotateBar .annotate-preset{background:var(--bg-raised);color:var(--text-2);border:1px solid var(--border-strong);padding:3px 10px;max-width:32ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#annotateBar .annotate-preset,#annotateBar .annotate-link{background:var(--bg-raised);color:var(--text-2);border:1px solid var(--border-strong);padding:3px 10px;max-width:32ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+/* A claim link's target (claim_link.js): its bubble (or its turn's opening) ringed, the quote itself highlighted. One
+   name for both pages; --claim-mark/--claim-ring follow the palette (warn-bright and warn are set per palette). */
+.claim-hit{outline:2px solid var(--claim-ring);outline-offset:3px;border-radius:12px}
+::highlight(chi-claim){background-color:var(--claim-mark);color:inherit}

data/lib/samagotchi/web/public/annotate_bar.js

@@ -9,7 +9,8 @@
 //
 // A bundle's pills (chi.annotation) come after the presets: each prepares
 // its command line with the selection (annotate_actions.js), at most 3
-// inline, the rest behind "⋯".
+// inline, the rest behind "⋯". Last, "Copy link" where the page has a
+// link for the selection (a claim link, claim_link.js).
 //
 // On a touch screen the bar docks above the composer instead: the OS's own
 // selection menu (Copy, Look Up…) and the handles sit next to the selection,
@@ -21,7 +22,8 @@ import { annotateBarLeft, annotationSource, quoteBlock } from "./annotations.js"
 import { presetNote } from "./annotate_presets.js";
 import { actionEnabled, actionTitle, sameActions, selectionFields, splitInline } from "./annotate_actions.js";
 
-// @param presets the preset texts (annotate_presets.js parsePresets)
+// @param presets the presets: each a text (annotate_presets.js
+//   parsePresets) or {label, text} (verify_preset.js)
 // @param canAnnotate () => whether the open session takes annotations (one
 //   is open and the composer can send)
 // @param roots () => the elements a selection may start in (the history,
@@ -45,12 +47,17 @@ import { actionEnabled, actionTitle, sameActions, selectionFields, splitInline }
 //   passes its own, participant_annotate.js)
 // @param quote (text, source) => the quote block for the selected +text+
 //   (annotations.js quoteBlock by default), or null for no text
+// @param link (source, range) => the selection's link, {url, title}, or
+//   null for no "Copy link" (the default); +range+ the selection clipped
+//   to +source+'s root
+// @param onLink (link) runs on "Copy link"; the selection is cleared and
+//   the bar hidden first
 // @param doc, win the page's document and window
 // @return {schedule(), hide(), el}; schedule() re-reads the selection on the
 //   next frame (call it on scroll)
 export function createAnnotateBar({
   presets, canAnnotate, roots, isLive, onQuote, actions = () => [], running = () => false, onAction = () => {},
-  dock = () => null, source: sourceOf = annotationSource, quote = quoteBlock,
+  dock = () => null, source: sourceOf = annotationSource, quote = quoteBlock, link = () => null, onLink = () => {},
   doc = globalThis.document, win = globalThis.window,
 }) {
   const bar = doc.createElement("div");
@@ -66,8 +73,9 @@ export function createAnnotateBar({
     return btn;
   }
   bar.appendChild(button("Annotate", "annotate-main"));
-  presets.forEach((text, i) => {
-    const btn = button(text, "annotate-preset");
+  presets.forEach((preset, i) => {
+    const { label, text } = presetParts(preset);
+    const btn = button(label, "annotate-preset");
     btn.dataset.index = String(i);
     btn.title = text;
     bar.appendChild(btn);
@@ -78,10 +86,14 @@ export function createAnnotateBar({
   group.className = "annotate-actions";
   group.hidden = true;
   bar.appendChild(group);
+  const linkBtn = button("Copy link", "annotate-link");
+  linkBtn.hidden = true;
+  bar.appendChild(linkBtn);
   doc.body.appendChild(bar);
   const touch = win.matchMedia?.("(pointer: coarse)");
   let pendingQuote = null;
   let pendingFields = null;
+  let pendingLink = null;
   let drawn = [];
   let moreList = null;
 
@@ -129,6 +141,7 @@ export function createAnnotateBar({
   function hide() {
     pendingQuote = null;
     pendingFields = null;
+    pendingLink = null;
     if (moreList) moreList.hidden = true;
     bar.hidden = true;
   }
@@ -151,6 +164,9 @@ export function createAnnotateBar({
     if (!block) return hide();
     pendingQuote = block;
     pendingFields = selectionFields(raw, source);
+    pendingLink = link(source, clipped) || null;
+    linkBtn.hidden = !pendingLink;
+    linkBtn.title = pendingLink?.title || "";
     const list = actions() || [];
     if (!sameActions(list, drawn)) drawActions(list);
     markActions();
@@ -209,6 +225,13 @@ export function createAnnotateBar({
       moreList.hidden = !moreList.hidden;
       return;
     }
+    if (btn === linkBtn) {
+      const target = pendingLink;
+      win.getSelection()?.removeAllRanges();
+      hide();
+      if (target) onLink(target);
+      return;
+    }
     if (btn.dataset.action !== undefined) {
       const action = drawn[Number(btn.dataset.action)];
       if (!action || btn.disabled) return;
@@ -219,7 +242,7 @@ export function createAnnotateBar({
       return;
     }
     const preset = btn.dataset.index === undefined ? null : presets[Number(btn.dataset.index)];
-    const text = preset ? presetNote(pendingQuote, preset) : pendingQuote;
+    const text = preset ? presetNote(pendingQuote, presetParts(preset).text) : pendingQuote;
     win.getSelection()?.removeAllRanges();
     hide();
     onQuote(text);
@@ -227,3 +250,8 @@ export function createAnnotateBar({
 
   return { schedule, hide, el: bar };
 }
+
+// A preset's button label and note: a text is both.
+function presetParts(preset) {
+  return typeof preset === "string" ? { label: preset, text: preset } : { label: preset.label, text: preset.text };
+}