samagotchi 0.9.0 → 0.10.1

data/lib/samagotchi/tools/memory.rb

@@ -125,17 +125,7 @@ module Samagotchi
       end
 
       def self.memories_dir(scope, env: ENV)
-        # Respect MemoryBundle overrides for test isolation (e.g. SystemBundle ensure in specs).
-        if defined?(Samagotchi::MemoryBundle::Installer) &&
-           Samagotchi::MemoryBundle::Installer.system_dir_override
-          if scope == "project"
-            base = Samagotchi::MemoryBundle::Installer.project_dir_base_override
-            return base if base
-          else
-            return Samagotchi::MemoryBundle::Installer.system_dir
-          end
-        end
-        scope == "project" ? MemoryPaths.project_dir(env: env) : MemoryPaths.system_dir(env: env)
+        MemoryPaths.scope_dir(scope == "project" ? "project" : "system", env: env)
       end
     end
 

data/lib/samagotchi/tools/send_note.rb

@@ -30,7 +30,7 @@ module Samagotchi
         return "Error: #{id[0, 8]} is this session; send_note is for other sessions" if id == peers.session_id
 
         owner = SessionManager.session_owner(id, state_dir: peers.state_dir)
-        if owner && owner["kind"] == "tui"
+        if owner&.tui?
           return "Error: session #{id[0, 8]} is open in a chi REPL, which can't take notes"
         end
 

data/lib/samagotchi/update_command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "cli/command"
+require_relative "cli/flags"
 require_relative "config"
 require_relative "desktop"
 require_relative "gem_update"
@@ -19,6 +21,8 @@ module Samagotchi
   # workers and a running chi web are reported, never restarted. Prints one
   # table; a second run changes nothing and says so.
   class UpdateCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]
         Updates this chi's install: the gem (from rubygems.org), then the
@@ -34,9 +38,22 @@ module Samagotchi
         chi sessions stop ID; a running chi web needs a restart.
     TEXT
 
-    FLAGS = { "--dry-run" => :dry_run, "--no-gem" => :no_gem, "--no-bundles" => :no_bundles, "--no-desktop" => :no_desktop,
-              # Hidden: no pbs/lsregister/open/pkill for a helper under HOME=<tmp>.
-              "--no-register" => :no_register }.freeze
+    # Help is a flag here: it doesn't stop the parse (an unknown option
+    # after it is still an error).
+    FLAGS = CLI::Flags.new(args: false) do |f|
+      f.switch "-h", "--help", "help"
+      f.switch "--dry-run"
+      f.switch "--no-gem"
+      f.switch "--no-bundles"
+      f.switch "--no-desktop"
+      # Hidden: no pbs/lsregister/open/pkill for a helper under HOME=<tmp>.
+      f.switch "--no-register"
+      # Hidden: the old version, passed by the chi that installed this one.
+      f.value "--gem-from"
+    end
+    # The switches the newer gem's update gets again (hand_over).
+    HANDED_OVER = { "--no-gem" => :no_gem, "--no-bundles" => :no_bundles, "--no-desktop" => :no_desktop,
+                    "--no-register" => :no_register }.freeze
 
     # A table row. info rows (live workers, chi web) say what runs; they
     # never fail.
@@ -70,7 +87,9 @@ module Samagotchi
 
     # @return [Integer] 0 nothing failed, 1 a part failed (or a checkout), 2 usage
     def run
-      options = parse or return 2
+      options = parse
+      return options if options.is_a?(Integer)
+
       if options[:help]
         @stdout.puts(USAGE)
         return 0
@@ -92,24 +111,15 @@ module Samagotchi
 
     private
 
+    def command_name = "chi update"
+
+    # @return [Hash, Integer] the options, or the usage error's exit status
+    #   (every error reads "unknown option", a --gem-from without its value too)
     def parse
-      argv = @argv.dup
-      options = {}
-      while (arg = argv.shift)
-        if %w[-h --help help].include?(arg)
-          options[:help] = true
-        elsif arg == "--gem-from" && argv.first
-          # Hidden: the old version, passed by the chi that installed this one.
-          options[:gem_from] = argv.shift
-        elsif FLAGS.key?(arg)
-          options[FLAGS[arg]] = true
-        else
-          @stderr.puts("chi update: unknown option #{arg}")
-          @stderr.puts(USAGE)
-          return nil
-        end
-      end
-      options
+      parsed = FLAGS.parse(@argv)
+      return usage_error("unknown option #{parsed.error.arg}") if parsed.error
+
+      parsed.options
     end
 
     # Installs a newer gem and hands over to it (exec: the new code syncs
@@ -150,7 +160,7 @@ module Samagotchi
       wrapper = InstalledGem.wrapper(@gem_spec)
       return done(row, :update, "run chi update again to sync with it") unless wrapper
 
-      passed = FLAGS.select { |_, key| options[key] && key != :dry_run }.keys
+      passed = HANDED_OVER.select { |_, key| options[key] }.keys
       @stdout.flush
       @exec.call([RbConfig.ruby, wrapper, "update", "--no-gem", "--gem-from", VERSION, *passed])
       done(row, :update) # only when exec is a spec's stand-in

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/vision_support.rb

@@ -25,10 +25,9 @@ module Samagotchi
     # @param profile [ModelProfile, nil] the model's prompt profile (native)
     # @param adapter [LLM::OpenAIChat, nil] the chat host's adapter
     # @param models [Hash, nil] ConfigFile.model_settings (specs)
-    # @param names [Array<String>, nil] the model's lookup names, the typed
-    #   alias first (Engine#model_lookup_names); default: the target's names
+    # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
     # @return [Answer]
-    def self.for(target, profile: nil, adapter: nil, models: nil, names: nil)
+    def self.for(target, names:, profile: nil, adapter: nil, models: nil)
       entry = target.entry
       configured = configured(target, entry, models, names)
       return configured if configured&.no?
@@ -46,13 +45,13 @@ module Samagotchi
       marker.is_a?(String) && !marker.empty? ? marker : nil
     end
 
-    def self.configured(target, entry, models, names = nil)
+    def self.configured(target, entry, models, names)
       models ||= begin
         ConfigFile.model_settings
       rescue StandardError
         {}
       end
-      key, value = ConfigFile.model_setting(names || [target.model, target.bare_model], :vision, models: models)
+      key, value = ConfigFile.model_setting(names, :vision, models: models)
       return Answer.new(value: value, reason: value ? nil : "models: #{key} sets vision: false") if key
       return nil if entry.vision.nil?
 

data/lib/samagotchi/web/app.rb

@@ -47,9 +47,6 @@ module Samagotchi
       IMAGE_NAME_RE = /\A[0-9a-f]{16}\.(png|jpe?g|gif|webp)\z/
       IMAGE_TYPES = { "png" => "image/png", "jpg" => "image/jpeg", "jpeg" => "image/jpeg", "gif" => "image/gif",
                       "webp" => "image/webp" }.freeze
-      # The cancel reasons a client may give, as the Bridge takes them
-      # (Bridge::CANCEL_REASONS); anything else is sent and echoed as manual.
-      CANCEL_REASONS = %w[manual user ctrl_c].freeze
 
       # POST /stop waits this long for the worker to let go of the session.
       STOP_WAIT_SECONDS = 2.0
@@ -76,8 +73,9 @@ module Samagotchi
       # @param annotate_presets [String, Array] the quick replies next to
       #   Annotate (web.annotate_presets, "|"-separated); "" shows none. The
       #   page parses them (annotate_presets.js).
-      # @param hub [SessionHub, nil] the session projection GET /api/events
-      #   streams from; without one the route answers 503
+      # @param hub [SessionHub, nil] the session projection GET /api/sessions
+      #   lists and GET /api/events streams from (Server always builds one);
+      #   without one both routes answer 503
       # @param registry [HostRegistry, nil] the hosts GET /api/models lists
       #   (built from the config on first use)
       # @param models_wait_timeout [Float] bounded seconds GET /api/models
@@ -324,14 +322,16 @@ module Samagotchi
 
       # The page's scope: ?dir=<folder> lists that folder's project (every
       # session when the folder is in no repo). A dir that isn't an existing
-      # absolute folder answers 400 before anything else runs.
+      # absolute folder answers 400 before anything else runs. The list is
+      # the hub's projection (archived ones too: the page filters them at
+      # render), with Session.list's sort, paging and total.
       def handle_list(req)
+        return error_response(503, "no_hub", "this chi web has no session hub") unless @hub
+
         dir, error = scope_dir(req.params["dir"])
         return error if error
 
-        scope = {}
         root = dir && ProjectScope.root_for(dir)
-        scope[:project_root] = root if root
         # Lazy retention sweep (once per 24h)
         if @manager.respond_to?(:retention_sweep_if_due)
           begin
@@ -340,45 +340,9 @@ module Samagotchi
             nil
           end
         end
-        sort = sanitize_sort(req.params["sort"])
-        order = sanitize_order(req.params["order"])
         limit = sanitize_limit(req.params["limit"])
         offset = sanitize_offset(req.params["offset"])
-        return list_from_hub(root, sort: sort, order: order, limit: limit, offset: offset) if @hub
-
-        # Archived ones too, as the hub's: the page filters them at render.
-        scope[:include_archived] = true
-        sessions = if @state_dir
-                     @manager.list_sessions(state_dir: @state_dir, sort: sort, order: order, limit: limit, offset: offset,
-                                            **scope)
-                   else
-                     @manager.list_sessions(sort: sort, order: order, limit: limit, offset: offset, **scope)
-                   end
-        roots = {}
-        payload = sessions.map do |s|
-          owner = session_owner(s.id)
-          session_to_json(s, status: displayed_status(s, owner: owner), owner: owner, root_cache: roots)
-        end
-        # Expose total via header for pagination (total unordered count)
-        headers = { "Content-Type" => "application/json; charset=utf-8", "Cache-Control" => "no-store" }
-        # Compute total without limit/offset for header
-        if limit || offset.positive?
-          total = if @state_dir
-                    @manager.list_sessions(state_dir: @state_dir, sort: sort, order: order, **scope).size
-                  else
-                    @manager.list_sessions(sort: sort, order: order, **scope).size
-                  end
-          headers["X-Total-Count"] = total.to_s
-        end
-        body = JSON.generate(payload)
-        headers["Content-Length"] = body.bytesize.to_s
-        [200, headers, [body]]
-      end
-
-      # The list from the hub's projection (the page's fallback and the
-      # first paint): the same sort, paging and total as from the files.
-      def list_from_hub(root, sort:, order:, limit:, offset:)
-        all = @hub.snapshot(project_root: root, sort: sort, order: order)
+        all = @hub.snapshot(project_root: root, sort: sanitize_sort(req.params["sort"]), order: sanitize_order(req.params["order"]))
         page = all.drop(offset)
         page = page.first(limit) if limit
         headers = { "Content-Type" => "application/json; charset=utf-8", "Cache-Control" => "no-store" }
@@ -647,39 +611,20 @@ module Samagotchi
         return error_response(404, "not_found", "Session not found: #{id}") unless session
 
         body = parse_json(request_body(req))
-        unless body.is_a?(Hash)
-          return error_response(400, "invalid_json", "invalid JSON body")
-        end
+        return error_response(400, "invalid_json", "invalid JSON body") unless body.is_a?(Hash)
+
         qid = body["id"]
-        selected = body["selected"]
-        freeform = body["freeform"]
-        if qid.to_s.strip.empty?
-          return error_response(400, "missing_fields", "id is required")
-        end
-        # Try live Engine via Bridge first (in-process answer without file IPC)
-        client = bridge_client(id)
-        if client
-          begin
-            reply = client.answer(id: qid, selected: selected, freeform: freeform)
-            return json_response(200, { status: "answered", session_id: id, id: qid }) if reply.ok?
-            # Read after its deadline and dropped (see #worker_timeout).
-            return worker_timeout("the answer was not sent") if reply.status == 408
-
-            # Pass the bridge's verdict through: 409 = another client answered
-            # first (or the question was cancelled), 400 = invalid selection.
-            if [400, 409].include?(reply.status)
-              detail = reply.json&.dig("detail") || "answer rejected"
-              return error_response(reply.status, reply.status == 409 ? "question_not_pending" : "invalid_answer", detail)
-            end
-          rescue Errno::ETIMEDOUT
-            return worker_timeout("the answer was not sent")
-          rescue StandardError
-            nil
+        return error_response(400, "missing_fields", "id is required") if qid.to_s.strip.empty?
+
+        request = ->(client) { client.answer(id: qid, selected: body["selected"], freeform: body["freeform"]) }
+        relay(id, bridge_client(id), request, what: "the answer was not sent", cant: "answer questions") do |reply|
+          case reply.status
+          when 200 then json_response(200, { status: "answered", session_id: id, id: qid })
+          # Another client answered first (or the question was cancelled).
+          when 409 then error_response(409, "question_not_pending", reply_detail(reply, "question not pending"))
+          when 400 then error_response(400, "invalid_answer", reply_detail(reply, "answer rejected"))
           end
         end
-        error_response(503, "not_live", "no live bridge for session #{id}")
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # Leave the pending question unanswered (the card's Dismiss). A question
@@ -691,22 +636,13 @@ module Samagotchi
         qid = body["id"].to_s
         return error_response(400, "missing_fields", "id is required") if qid.strip.empty?
 
-        client = bridge_client(id)
-        return error_response(503, "not_live", "no live bridge for session #{id}") unless client
-
-        reply = client.dismiss_question(id: qid)
-        case reply.status
-        when 200 then json_response(200, { status: "dismissed", session_id: id, id: qid })
-        when 409 then error_response(409, "question_not_pending", reply.json&.dig("detail") || "question not pending")
-        when 408 then worker_timeout("the question was not dismissed")
-        when 404
-          error_response(501, "not_supported", BridgeClient.stale_worker_message(id, cant: "dismiss questions"))
-        else error_response(503, "not_live", "no live bridge for session #{id}")
+        request = ->(client) { client.dismiss_question(id: qid) }
+        relay(id, bridge_client(id), request, what: "the question was not dismissed", cant: "dismiss questions") do |reply|
+          case reply.status
+          when 200 then json_response(200, { status: "dismissed", session_id: id, id: qid })
+          when 409 then error_response(409, "question_not_pending", reply_detail(reply, "question not pending"))
+          end
         end
-      rescue Errno::ETIMEDOUT
-        worker_timeout("the question was not dismissed")
-      rescue StandardError
-        error_response(503, "not_live", "no live bridge for session #{id}")
       end
 
       # A session command typed in the composer (/model, /models, !rollback,
@@ -720,29 +656,60 @@ module Samagotchi
         return error_response(400, "missing_fields", "line is required") if line.empty?
 
         @manager.resume_session(id, state_dir: @state_dir) if @manager.respond_to?(:resume_session)
-        client = live_bridge_client(id)
-        return error_response(503, "not_live", "no live bridge for session #{id}") unless client
-
         # card: a card's action; its command events say so (no echo).
-        reply = client.post_command(line: line, client_id: body["client_id"], card: body["card"] == true)
-        case reply.status
-        when 202 then json_response(202, reply.json || { status: "accepted" })
-        when 400 then error_response(400, reply.json&.dig("error") || "unknown_command", reply.json&.dig("detail") || "not a session command")
-        when 408 then worker_timeout("the command was not run")
-        when 404
-          error_response(501, "not_supported", BridgeClient.stale_worker_message(id, cant: "run commands"))
-        else error_response(503, "not_live", "no live bridge for session #{id}")
+        request = ->(client) { client.post_command(line: line, client_id: body["client_id"], card: body["card"] == true) }
+        relay(id, live_bridge_client(id), request, what: "the command was not run", cant: "run commands") do |reply|
+          case reply.status
+          when 202 then json_response(202, reply.json || { status: "accepted" })
+          when 400 then error_response(400, reply.json&.dig("error") || "unknown_command", reply_detail(reply, "not a session command"))
+          end
         end
       rescue SessionManager::OwnedByTUI => e
         error_response(409, "owned_by_tui", e.message)
       rescue ArgumentError => e
         error_response(404, "not_found", e.message)
+      end
+
+      # Hand a request to the session's live Bridge (+client+, nil without
+      # one) and map its reply. The block gets the reply and answers the
+      # statuses its route knows (nil for the rest); every relay maps the
+      # rest the same way: 408 deadline_passed or a read timeout → 504
+      # worker_timeout (+what+ didn't happen), a 404 for a route the worker
+      # doesn't have → 501 not_supported (it runs an older chi that +cant+;
+      # 501, not 503: it is live, and the page reads 503 as "not running"),
+      # and no live bridge, a refused connection or anything else → 503
+      # not_live.
+      # @param request [#call] sends with the client, answers its Response
+      def relay(id, client, request, what:, cant:)
+        return not_live(id) unless client
+
+        reply = request.call(client)
+        mapped = yield(reply)
+        return mapped if mapped
+
+        case reply.status
+        when 408 then worker_timeout(what)
+        when 404
+          return not_live(id) if reply.json&.dig("error") == "unknown_session"
+
+          error_response(501, "not_supported", BridgeClient.stale_worker_message(id, cant: cant))
+        else not_live(id)
+        end
       rescue Errno::ETIMEDOUT
-        worker_timeout("the command was not run")
-      rescue SystemCallError, IOError
+        worker_timeout(what)
+      rescue SystemCallError, IOError, SocketError
+        not_live(id)
+      end
+
+      def not_live(id)
         error_response(503, "not_live", "no live bridge for session #{id}")
       end
 
+      # The Bridge's detail for a refusal, or +fallback+.
+      def reply_detail(reply, fallback)
+        reply.json&.dig("detail") || fallback
+      end
+
       # The worker didn't take a request in time: its read timed out, or the
       # Bridge read it after its deadline (408 deadline_passed) and dropped
       # it. Either way +what+ didn't happen, and a frozen worker that wakes
@@ -795,18 +762,11 @@ module Samagotchi
       # session's images/), or a String saying what's wrong. Never a path.
       def turn_images(id, raw)
         return [] if raw.nil?
-        return "images must be a list" unless raw.is_a?(Array)
 
         session_dir = image_session_dir(id)
         return "unknown session" unless session_dir
 
-        raw.map do |image|
-          return "each image must be {file:, name:}" unless image.is_a?(Hash)
-          return "images are refs to uploaded files, not paths" if image.key?("path") || image.key?(:path)
-          return "unknown image" unless ImageStore.valid_ref?(session_dir, image)
-
-          { file: (image["file"] || image[:file]).to_s, name: File.basename((image["name"] || image[:name]).to_s)[0, 120] }
-        end
+        ImageStore.check_refs(session_dir, raw)
       end
 
       # The session's folder, or nil for an id that isn't one.
@@ -864,8 +824,7 @@ module Samagotchi
         port && BridgeClient.new(session_id: id, port: port, host: DEFAULT_HOST)
       end
 
-      # The process holding the session: {"pid", "kind" => "worker"|"tui"}, or
-      # nil. A worker always runs a Bridge; a TUI (plain `chi`) doesn't share.
+      # The process holding the session (an OwnerLock::Owner), or nil. A worker always runs a Bridge; a TUI (plain `chi`) doesn't share.
       def session_owner(id)
         return nil unless @manager.respond_to?(:session_owner)
 
@@ -874,46 +833,25 @@ module Samagotchi
         nil
       end
 
+      # The Bridge decides the reason (Bridge::CANCEL_REASONS; anything
+      # else is manual) and the reply echoes its choice. No reason: user.
       def handle_cancel(req, id)
-        # Validate session exists
-        begin
-          @session_class.load(id, state_dir: default_state_dir)
-        rescue ArgumentError => e
-          return error_response(404, "not_found", e.message)
-        end
+        @session_class.load(id, state_dir: default_state_dir)
 
         body = request_body(req)
-        reason = "user"
-        unless body.nil? || body.strip.empty?
-          parsed = parse_json(body)
-          if parsed.is_a?(Hash)
-            r = parsed["reason"] || parsed[:reason] || parsed["cancellation_reason"]
-            r = r.to_s.strip
-            reason = if r.empty? then "user"
-                     elsif CANCEL_REASONS.include?(r) then r
-                     else "manual"
-                     end
-          end
-        end
-
-        # Try direct bridge cancel first (in-process, low latency)
-        client = bridge_client(id)
-        if client
-          begin
-            reply = client.cancel(reason: reason)
-            if reply.status == 202
-              return json_response(202, { status: "cancel_requested", session_id: id, reason: reason, via: "bridge" })
-            end
-            # The bridge answers 409 when there is no active turn to cancel.
-            if reply.status == 409
-              return json_response(409, { error: "not_running", detail: "no active turn to cancel", session_id: id })
-            end
-          rescue StandardError
-            nil
+        parsed = body.nil? || body.strip.empty? ? nil : parse_json(body)
+        reason = (parsed["reason"] if parsed.is_a?(Hash)).to_s.strip
+        reason = "user" if reason.empty?
+
+        request = ->(client) { client.cancel(reason: reason) }
+        relay(id, bridge_client(id), request, what: "the turn was not cancelled", cant: "cancel turns") do |reply|
+          case reply.status
+          when 202
+            json_response(202, { status: "cancel_requested", session_id: id, reason: reply.json&.dig("reason"), via: "bridge" })
+          # No active turn to cancel.
+          when 409 then json_response(409, { error: "not_running", detail: "no active turn to cancel", session_id: id })
           end
         end
-
-        error_response(503, "not_live", "no live bridge for session #{id}")
       rescue ArgumentError => e
         error_response(404, "not_found", e.message)
       end
@@ -1174,9 +1112,9 @@ module Samagotchi
         SessionSummary.displayed_status(session, snapshot, owner: owner)
       end
 
-      # @param owner [Hash, nil] #session_owner; its kind is shown as `owner`
-      def session_to_json(s, status: s.status, owner: nil, root_cache: nil)
-        SessionSummary.build(s, status: status, owner: owner, root_cache: root_cache,
+      # @param owner [OwnerLock::Owner, nil] #session_owner; its kind is shown as `owner`
+      def session_to_json(s, status: s.status, owner: nil)
+        SessionSummary.build(s, status: status, owner: owner,
                                 session_dir: @session_class.session_dir(s.id, state_dir: default_state_dir))
       end
 

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

@@ -23,7 +23,7 @@ export function toolName(row) {
 
 // Create a fresh activity model for one turn.
 export function newActivity() {
-  return { finalized: false, rows: [] };
+  return { rows: [] };
 }
 
 // Stable key for a call within a turn. iteration + call_index are both present
@@ -107,13 +107,3 @@ export function completedStatus(status) {
   if (status === "stopped") return ROW_STATUS.STOPPED;
   return ROW_STATUS.OK;
 }
-
-// Mark a turn's activity model as finalized (rows stay; rendering collapses).
-export function finalizeActivity(model) {
-  if (model) model.finalized = true;
-  return model;
-}
-
-export function activityCount(model) {
-  return model ? model.rows.length : 0;
-}

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

@@ -0,0 +1,120 @@
+// ── Annotate ───────────────────────────────────────────────────────────────
+// Selecting text in an answer, thinking, a tool row or an own message shows
+// "Annotate" and the presets (web.annotate_presets); Annotate appends the
+// quote (with where it came from) to the composer, a preset the quote with
+// its text as the note. Nothing is sent. The bar lives outside #history,
+// which is re-rendered whole. The selection is read when it changes: a live
+// bubble rewrites its text every frame, which would collapse it by the time
+// a button is clicked.
+//
+// The quoting rules are annotations.js'; this is the bar.
+
+import { annotateBarLeft, annotationSource, quoteBlock } from "./annotations.js";
+import { presetNote } from "./annotate_presets.js";
+
+// @param presets the preset texts (annotate_presets.js parsePresets)
+// @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,
+//   the stage)
+// @param isLive (root) => whether a source root is still streaming (refused
+//   until its step closes)
+// @param onQuote (text) runs with the quote (and a preset's note) to append
+//   to the composer; 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, doc = globalThis.document, win = globalThis.window,
+}) {
+  const bar = doc.createElement("div");
+  bar.id = "annotateBar";
+  bar.hidden = true;
+  bar.setAttribute("role", "toolbar");
+  bar.setAttribute("aria-label", "Annotate");
+  function button(text, cls) {
+    const btn = doc.createElement("button");
+    btn.type = "button";
+    btn.className = cls;
+    btn.textContent = text;
+    return btn;
+  }
+  bar.appendChild(button("Annotate", "annotate-main"));
+  presets.forEach((text, i) => {
+    const btn = button(text, "annotate-preset");
+    btn.dataset.index = String(i);
+    btn.title = text;
+    bar.appendChild(btn);
+  });
+  doc.body.appendChild(bar);
+  let pendingQuote = null;
+
+  function hide() {
+    pendingQuote = null;
+    bar.hidden = true;
+  }
+
+  function update() {
+    const sel = win.getSelection();
+    if (!canAnnotate() || !sel || sel.isCollapsed || !sel.rangeCount) return hide();
+    const range = sel.getRangeAt(0);
+    if (!roots().some((root) => root.contains(range.startContainer))) return hide();
+    const source = annotationSource(range.startContainer);
+    // A running turn's narration box shows complete sentences and its thinking
+    // is appended by delta; a selection in either is refused while the step is
+    // live — the quote lands once it closes (then on the full text).
+    if (!source || isLive(source.root)) return hide();
+    // Clip to where the selection starts: one tool row, one bubble.
+    const clipped = range.cloneRange();
+    if (!source.root.contains(range.endContainer)) clipped.setEnd(source.root, source.root.childNodes.length);
+    const block = quoteBlock(clipped.toString(), source);
+    if (!block) return hide();
+    pendingQuote = block;
+    const rects = clipped.getClientRects();
+    const rect = rects.length ? rects[rects.length - 1] : clipped.getBoundingClientRect();
+    bar.hidden = false;
+    // Measured at the left edge: a fixed element's shrink-to-fit width is
+    // capped by what's right of it, so at the last (right) spot it would
+    // measure wrapped.
+    bar.style.left = "8px";
+    const w = bar.offsetWidth;
+    const h = bar.offsetHeight;
+    const maxTop = win.innerHeight - h - 8;
+    const top = Math.min(rect.bottom + 6, maxTop);
+    bar.style.top = `${Math.max(top, 8)}px`;
+    bar.style.left = `${annotateBarLeft(rect, w, win.innerWidth)}px`;
+    // Not over a copy button (this bubble's, one inside it, the next
+    // bubble's).
+    const box = bar.getBoundingClientRect();
+    const bubble = source.root.closest(".bubble");
+    const near = [bubble, bubble?.nextElementSibling].filter(Boolean);
+    for (const btn of near.flatMap((el) => [...el.querySelectorAll(".copy-btn")])) {
+      const r = btn.getBoundingClientRect();
+      if (r.bottom < box.top || r.top > box.bottom || r.right < box.left || r.left > box.right) continue;
+      bar.style.top = `${Math.max(Math.min(r.bottom + 4, maxTop), 8)}px`;
+      break;
+    }
+  }
+
+  let raf = false;
+  function schedule() {
+    if (raf) return;
+    raf = true;
+    win.requestAnimationFrame(() => { raf = false; update(); });
+  }
+  doc.addEventListener("selectionchange", schedule);
+  win.addEventListener("resize", schedule);
+  // Keep the selection when a button is pressed.
+  bar.addEventListener("mousedown", (e) => e.preventDefault());
+  bar.addEventListener("click", (e) => {
+    const btn = e.target.closest("button");
+    if (!btn || !pendingQuote) return;
+    const preset = btn.dataset.index === undefined ? null : presets[Number(btn.dataset.index)];
+    const text = preset ? presetNote(pendingQuote, preset) : pendingQuote;
+    win.getSelection()?.removeAllRanges();
+    hide();
+    onQuote(text);
+  });
+
+  return { schedule, hide, el: bar };
+}