cosmonats 0.6.0 → 0.8.0

data/lib/cosmo/middleware/metrics.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module Middleware
+    # Records every execution for the web UI's Metrics tab while +config.metrics+ is enabled: its run time when it
+    # succeeds, a failure otherwise, and the wait from enqueue to the job's first delivery. ActiveJob jobs count under
+    # their own class.
+    class Metrics
+      # @param job [Cosmo::Job]
+      # @param data [Hash]
+      # @param _message [NATS::Msg]
+      def call(job, data, _message) # rubocop:disable Metrics/AbcSize
+        return yield unless Config.metrics.enabled
+
+        name = job_name(job, data)
+        wait_ms = (Time.now - job.enqueued_at) * 1000 if job.attempt == 1 && job.enqueued_at
+        started = clock
+        result = yield
+        API::Stats::Metrics.instance.record(name, exec_ms: clock - started, wait_ms:)
+        result
+      rescue Exception # rubocop:disable Lint/RescueException
+        API::Stats::Metrics.instance.record(name, wait_ms:, failed: true) if name
+        raise
+      end
+
+      private
+
+      def job_name(job, data)
+        return job.class.name unless defined?(ActiveJobAdapter::Executor) && job.is_a?(ActiveJobAdapter::Executor)
+
+        data.dig(:args, 0, :job_class).to_s
+      end
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      end
+    end
+  end
+end

data/lib/cosmo/middleware/sentry.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize
+module Cosmo
+  module Middleware
+    # Wraps every job execution in a Sentry transaction. Errors reach Sentry through {ERROR_HANDLER}, which also
+    # captures those outside jobs (stream batches, fetches, the scheduler). Needs +sentry-ruby+, so it is not loaded
+    # by default:
+    #
+    #   require "cosmo/middleware/sentry"
+    #
+    #   Cosmo.configure do |config|
+    #     config.server_middleware { |chain| chain.add Cosmo::Middleware::Sentry }
+    #     config.error_handlers << Cosmo::Middleware::Sentry::ERROR_HANDLER
+    #   end
+    class Sentry
+      NAME_PREFIX = "Cosmonats"
+      OP_NAME = "queue.cosmonats"
+      SPAN_ORIGIN = "auto.queue.cosmonats"
+      STATUS_OK = 200
+      STATUS_FAIL = 500
+
+      ERROR_HANDLER = lambda do |error, context|
+        next unless ::Sentry.initialized?
+
+        ::Sentry.capture_exception(error, contexts: { cosmonats: context }, hint: { background: true, integration: "cosmonats" })
+      end
+
+      # @param job [Cosmo::Job]
+      # @param data [Hash]
+      # @param message [NATS::Msg]
+      def call(job, data, message)
+        return yield unless ::Sentry.initialized?
+
+        scope = ::Sentry.get_current_scope
+        transaction_name = "#{NAME_PREFIX}/#{job.class.name}"
+        scope.set_transaction_name(transaction_name, source: :task)
+        transaction = ::Sentry.start_transaction(
+          name: scope.transaction_name,
+          source: scope.transaction_source,
+          op: OP_NAME,
+          origin: SPAN_ORIGIN
+        )
+        transaction&.set_data("messaging.message.id", data[:jid])
+        transaction&.set_data("messaging.destination.name", "#{message.metadata.stream}:#{message.subject}")
+        transaction&.set_data("messaging.message.retry.count", data[:retry] || 0)
+
+        begin
+          result = yield
+          transaction&.set_http_status(STATUS_OK)
+          transaction&.finish
+          result
+        rescue StandardError
+          transaction&.set_http_status(STATUS_FAIL)
+          transaction&.finish
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/cosmo/middleware/totals.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module Middleware
+    # Counts every execution as processed or failed, so a job retried twice and then succeeding adds two failures
+    # and one processed. A counter that cannot be written is logged rather than raised, so stats never fail a job.
+    class Totals
+      # @param _job [Cosmo::Job]
+      # @param _data [Hash]
+      # @param _message [NATS::Msg]
+      def call(_job, _data, _message)
+        result = yield
+        increment(:processed)
+        result
+      rescue Exception # rubocop:disable Lint/RescueException
+        increment(:failed)
+        raise
+      end
+
+      private
+
+      def increment(key)
+        API::Stats::Totals.instance.increment(key)
+      rescue StandardError => e
+        Logger.debug "Totals #{key} counter error: #{e.class} #{e.message}"
+      end
+    end
+  end
+end

data/lib/cosmo/middleware.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "cosmo/middleware/chain"
+require "cosmo/middleware/limit"
+require "cosmo/middleware/busy"
+require "cosmo/middleware/totals"
+require "cosmo/middleware/metrics"

data/lib/cosmo/processor.rb

@@ -5,20 +5,29 @@ module Cosmo
     STREAM_PAUSED_RECHECK_TTL = "5s" # How long a stream's paused state is cached before re-checking (override via COSMO_STREAM_PAUSED_RECHECK_TTL)
     STREAMS_PAUSED_IDLE_SLEEP = "1s" # How long to sleep when every stream is paused, preventing a tight CPU spin (override via COSMO_STREAMS_PAUSED_IDLE_SLEEP)
     STREAM_EMPTY_BACKOFF_MAX = "5s"  # Max sleep between empty fetches (override via COSMO_STREAM_EMPTY_BACKOFF_MAX)
+    QUIET_SLEEP = "5s"               # How long to sleep between checks while in quiet mode (override via COSMO_QUIET_IDLE_SLEEP)
 
     def self.run(...)
       new(...).tap(&:run)
     end
 
+    # Checks the command-line options this processor understands, before anything is booted or connected.
+    #
+    # @param options [Hash]
+    # @return [void]
+    def self.validate_options!(_options); end
+
     attr_reader :consumers
 
-    def initialize(pool, running, options)
+    def initialize(pool, running, options, quiet:)
       @pool = pool
       @running = running
+      @quiet = quiet
       @options = options
       @threads = []
       @consumers = []
       @cache = Utils::TTLCache.new
+      @busy = Concurrent::AtomicFixnum.new
     end
 
     def run
@@ -29,6 +38,13 @@ module Cosmo
       run_loop
     end
 
+    # Threads processing fetched messages right now; threads waiting on a fetch don't count.
+    #
+    # @return [Integer]
+    def busy
+      @busy.value
+    end
+
     def stop(timeout = Config[:timeout])
       @running.make_false
       @pool.shutdown
@@ -52,6 +68,11 @@ module Cosmo
       while running?
         break if shutdown
 
+        if quiet?
+          sleep(Utils::Duration.parse(ENV.fetch("COSMO_QUIET_IDLE_SLEEP", QUIET_SLEEP)))
+          next
+        end
+
         all_empty = true  # every stream is empty
         all_paused = true # every stream is paused
         consumers.each do |(subscription, config, processor)| # rubocop:disable Metrics/BlockLength
@@ -65,9 +86,10 @@ module Cosmo
           end
           all_paused = false
 
-          _, skip_t = consumer_state[stream_name]
+          key = backoff_key(config)
+          _, skip_t = consumer_state[key]
           if skip_t && Time.now < skip_t
-            Logger.trace "stream #{stream_name} is empty, backing off"
+            Logger.trace "#{key} is empty, backing off"
             next
           end
           all_empty = false
@@ -75,20 +97,23 @@ module Cosmo
           begin
             @pool.post do
               # Re-check, after possibly being blocked on post to thread pool
-              _, skip_t = consumer_state[stream_name]
+              _, skip_t = consumer_state[key]
               next if skip_t && Time.now < skip_t
 
               timeout = fetch_timeout(config)
               Logger.trace "fetching #{fetch_subjects(config).inspect}, timeout=#{timeout}"
+              started_at = Time.now
               messages = fetch(subscription, batch_size: config[:batch_size], timeout:)
               Logger.trace "fetched (#{messages&.size.to_i}) messages"
               if messages&.any?
-                consumer_state.delete(stream_name)
-                process(messages, processor)
+                consumer_state.delete(key)
+                track_busy { process(messages, processor) }
               else
                 max_backoff = Utils::Duration.parse(ENV.fetch("COSMO_STREAM_EMPTY_BACKOFF_MAX", STREAM_EMPTY_BACKOFF_MAX))
-                consumer_state.compute(stream_name) do |current|
-                  count = (current&.first || 0) + 1
+                consumer_state.compute(key) do |(count, wake_at)|
+                  next [count, wake_at] if wake_at && wake_at > started_at
+
+                  count = count.to_i + 1
                   backoff = [timeout * (2**(count - 1)), max_backoff].min
                   [count, Time.now + backoff]
                 end
@@ -129,10 +154,21 @@ module Cosmo
       raise NotImplementedError
     end
 
+    def track_busy
+      @busy.increment
+      yield
+    ensure
+      @busy.decrement
+    end
+
     def running?
       @running.true?
     end
 
+    def quiet?
+      @quiet.true?
+    end
+
     def scheduler?
       false
     end
@@ -144,6 +180,7 @@ module Cosmo
     rescue StandardError => e
       Logger.error "Snap! Error just happened"
       Logger.error "#{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+      Cosmo.handle_error(e, { source: :fetch })
 
       backoff = ENV.fetch("COSMO_STREAMS_FETCH_BACKOFF", 5).to_f
       sleep([timeout, backoff].max) # backoff before retry
@@ -161,5 +198,9 @@ module Cosmo
     def consumer_state
       @consumer_state ||= Concurrent::Map.new
     end
+
+    def backoff_key(config)
+      config[:stream].to_s
+    end
   end
 end

data/lib/cosmo/publisher.rb

@@ -7,7 +7,7 @@ module Cosmo
     class << self
       extend Forwardable
 
-      delegate %i[publish publish_job publish_batch] => :instance
+      delegate %i[publish] => :instance
     end
 
     def self.instance
@@ -22,17 +22,5 @@ module Cosmo
       payload = (serializer || Stream::Serializer).serialize(data)
       @client.publish(subject, payload, **options)
     end
-
-    def publish_job(data)
-      subject, payload, params = data.to_args
-      @client.publish(subject, payload, **params)
-      data.jid
-    rescue NATS::JetStream::Error::NoStreamResponse
-      raise StreamNotFoundError, params[:stream].to_s
-    end
-
-    def publish_batch(subject, batch, **options)
-      batch.each { publish(subject, _1, **options) }
-    end
   end
 end

data/lib/cosmo/railtie.rb

@@ -12,10 +12,10 @@ module Cosmo
       require "cosmo/active_job"
     end
 
-    # Autoload config/cosmo.yml when it exists and no config has been loaded yet.
+    # Loads config/cosmo.yml, or the built-in defaults without one, unless a config has been loaded already.
     initializer "cosmo.load_config", after: "cosmo.active_job_adapter" do |app|
       config_path = app.root.join("config", "cosmo.yml")
-      Config.load(config_path.to_s) if config_path.exist? && Config.instance.none?
+      Config.load(config_path.exist? ? config_path.to_s : nil) if Config.instance.none?
     end
   end
 end

data/lib/cosmo/services.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Cosmo
+  # The streams Cosmo itself depends on. They are built from the settings in Cosmo.configure, never from cosmo.yml,
+  # and `cosmo --setup` creates them next to the user's streams.
+  module Services
+    SCHEDULED = Job::StreamFilter::SCHEDULED.to_s
+    DEAD = "dead"
+    METADATA = { "_cosmo.type" => "jobs" }.freeze
+    RETENTION_CHANGE = 10_052
+
+    module_function
+
+    # Holds delayed jobs and every cron template. It alone enables NATS message scheduling, since a schedule can only
+    # target a subject its own stream covers, and NATS refuses +discard: new+ wherever scheduling is enabled.
+    #
+    # @return [Hash, nil] nil when scheduling is turned off
+    def scheduled_stream
+      return unless Config.scheduled.enabled
+
+      { storage: "file", retention: "workqueue", discard: "old", allow_direct: true, allow_msg_schedules: true,
+        duplicate_window: Config.to_ns(120), subjects: ["jobs.#{SCHEDULED}.>", "#{API::Cron::Entry::SUBJECT_PREFIX}.>"],
+        num_replicas: Config.replicas, description: "Scheduled jobs and cron schedules", metadata: METADATA }
+    end
+
+    # +max_deliver+ stays above 1: the scheduler naks a message that is not yet due, and one whose dispatch failed,
+    # and both need another delivery.
+    #
+    # @return [Hash, nil] nil when scheduling is turned off
+    def scheduled_consumer
+      return unless Config.scheduled.enabled
+
+      { ack_policy: "explicit", max_deliver: 5, max_ack_pending: 100, ack_wait: 10, subject: "jobs.#{SCHEDULED}.>" }
+    end
+
+    # @return [Hash, nil] nil when dead-lettering is turned off
+    def dead_stream
+      dead = Config.dead
+      return unless dead.enabled
+
+      { storage: "file", retention: "workqueue", discard: "old", allow_direct: true, duplicate_window: Config.to_ns(120),
+        max_age: Config.to_ns(Utils::Duration.parse(dead.max_age)), max_msgs: dead.max_msgs, max_bytes: dead.max_bytes,
+        subjects: ["jobs.#{DEAD}.>"], num_replicas: Config.replicas, description: "Dead jobs", metadata: METADATA }
+    end
+
+    # Creates or updates every enabled service stream, plus the internal totals and batch counters and, while enabled,
+    # the job metrics.
+    #
+    # @return [Array<String>] the names of the service streams set up, without the internal ones
+    def setup!
+      streams = { SCHEDULED => scheduled_stream, DEAD => dead_stream }.compact
+      streams.each { |name, config| setup_stream(name, config) }
+      API::Stats::Totals.setup!
+      Batch::Counters.setup!
+      API::Stats::Metrics.setup! if Config.metrics.enabled
+      streams.keys
+    end
+
+    # @raise [Error] when an existing stream has another retention policy, which NATS can't change in place
+    def setup_stream(name, config)
+      Client.instance.setup_stream(name, config)
+    rescue NATS::JetStream::Error::APIError => e
+      raise unless e.err_code == RETENTION_CHANGE
+
+      raise Error, "The existing `#{name}` stream has another retention policy, which NATS can't change in place: " \
+                   "delete it (`nats stream rm #{name}`, dropping its messages) and rerun `cosmo --setup`"
+    end
+  end
+end

data/lib/cosmo/stream/message.rb

@@ -7,8 +7,9 @@ module Cosmo
     class Message
       extend Forwardable
 
-      delegate %i[subject reply header metadata ack nack term in_progress] => :@msg
+      delegate %i[subject reply header metadata ack nak term in_progress] => :@msg
       delegate %i[timestamp num_delivered num_pending] => :metadata
+      alias nack nak
 
       def initialize(msg, serializer: nil)
         @msg = msg

data/lib/cosmo/stream/processor.rb

@@ -3,6 +3,11 @@
 module Cosmo
   module Stream
     class Processor < ::Cosmo::Processor
+      # @return [Array<String>] names of the stream classes being processed
+      def subscriptions
+        @consumers.map { |(_, config, _)| config[:class].name }
+      end
+
       private
 
       def setup
@@ -33,8 +38,10 @@ module Cosmo
         processor.process(messages)
         Logger.with(elapsed: sw.elapsed_seconds) { Logger.info "done" }
       rescue StandardError => e
-        Logger.debug e
+        Logger.error e
         Logger.with(elapsed: sw.elapsed_seconds) { Logger.info "fail" }
+        Cosmo.handle_error(e, { source: :stream, stream: metadata&.stream, processor: processor.class.name,
+                                size: messages&.size })
       rescue Exception # rubocop:disable Lint/RescueException
         Logger.with(elapsed: sw.elapsed_seconds) { Logger.info "fail" }
         raise
@@ -65,6 +72,10 @@ module Cosmo
         config.dig(:consumer, :subjects)
       end
 
+      def backoff_key(config)
+        config[:consumer_name] || config[:class].name
+      end
+
       def fetch_timeout(config)
         timeout = config[:fetch_timeout].to_f
         if timeout <= 0

data/lib/cosmo/utils/hash.rb

@@ -36,14 +36,13 @@ module Cosmo
         end
       end
 
-      # deep set
-      def set(hash, *keys, value)
-        last_key = keys.pop
-        target = keys.reduce(hash) do |base, key|
-          base[key] ||= {}
-          base[key]
-        end
-        target[last_key] = value
+      # Nested hashes merge recursively, +other+ winning; any other value in +other+ replaces the one in +base+.
+      #
+      # @param base [::Hash]
+      # @param other [::Hash]
+      # @return [::Hash] a new hash
+      def deep_merge(base, other)
+        base.merge(other) { |_, old, new| old.is_a?(::Hash) && new.is_a?(::Hash) ? deep_merge(old, new) : new }
       end
 
       # deep dup

data/lib/cosmo/utils/json.rb

@@ -8,7 +8,7 @@ module Cosmo
       module_function
 
       def parse(value, default: nil, symbolize_names: true, **options)
-        JSON.parse(value, options.merge(symbolize_names:))
+        JSON.parse(value, **options, symbolize_names:)
       rescue TypeError, JSON::ParserError
         default
       end

data/lib/cosmo/utils/overrides.rb

@@ -1,20 +1,24 @@
 # frozen_string_literal: true
 
 Cosmo::Utils::Warnings.silence do
-  members = NATS::JetStream::API::StreamConfig.members + %i[allow_msg_counter allow_msg_schedules]
-  NATS::JetStream::API::StreamConfig = Struct.new(*members, keyword_init: true) do
-    def initialize(opts = {})
-      rem = opts.keys - members
-      opts.delete_if { |k| rem.include?(k) }
-      super
+  unless NATS::JetStream::API::StreamConfig.members.include?(:allow_msg_schedules)
+    members = NATS::JetStream::API::StreamConfig.members + %i[allow_msg_counter allow_msg_schedules]
+    NATS::JetStream::API::StreamConfig = Struct.new(*members, keyword_init: true) do
+      def initialize(opts = {})
+        rem = opts.keys - members
+        opts.delete_if { |k| rem.include?(k) }
+        super
+      end
     end
   end
 
-  members = NATS::JetStream::PubAck.members + [:val]
-  NATS::JetStream::PubAck = Struct.new(*members, keyword_init: true)
+  unless NATS::JetStream::PubAck.members.include?(:val)
+    members = NATS::JetStream::PubAck.members + [:val]
+    NATS::JetStream::PubAck = Struct.new(*members, keyword_init: true)
+  end
 end
 
-# Upstream bug in nats-pure 2.5.0 (https://github.com/nats-io/nats.rb):
+# Upstream bug in nats-pure 2.5.0 and 2.6.0 (https://github.com/nats-io/nats-pure.rb):
 # NATS::JetStream::PullSubscription#fetch only assigns its `start_time` local in the
 # `batch > 1` branch, but the final "did we time out" check outside the case statement
 # reads it unconditionally. For `batch == 1` (what Cosmo::Processor always uses),
@@ -44,7 +48,9 @@ end
 #
 # Vendored copy of nats-pure's PullSubscription#fetch, kept as close to
 # upstream as possible (two one-line fixes, see comments above), so it's easy to diff against the
-# next nats-pure release and drop once fixed there.
+# next nats-pure release and drop once fixed there. Fixed on nats-pure main by the fetch rewrite
+# (#181), recognized by its private #take_pending, in which case this copy is not loaded.
+return if NATS::JetStream.const_get(:PullSubscription).private_method_defined?(:take_pending)
 
 # rubocop:disable all
 module NATS

data/lib/cosmo/utils/thread_pool.rb

@@ -16,11 +16,16 @@ module Cosmo
 
       def initialize(concurrency)
         @mutex = Thread::Mutex.new
+        @concurrency = concurrency
         @available = concurrency
         @cond = ConditionVariable.new
         @pool = Concurrent::FixedThreadPool.new(concurrency)
       end
 
+      def wait_idle
+        @mutex.synchronize { @cond.wait(@mutex) until @available == @concurrency }
+      end
+
       def post
         @mutex.synchronize do
           @cond.wait(@mutex) while @available <= 0

data/lib/cosmo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cosmo
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/cosmo/web/assets/app.css

@@ -163,6 +163,14 @@ button:hover, .btn:hover {
   );
 }
 
+.btn-sm {
+  box-shadow: none;
+  font-size: var(--font-size-small);
+  font-weight: 600;
+  line-height: var(--space-2x);
+  padding: var(--space-1-2) var(--space);
+}
+
 /* ── Badges ────────────────────────────────────────────────────────────── */
 .badge {
   border-radius: var(--space-1-2);
@@ -343,6 +351,12 @@ section .pending {
   align-items: center;
 }
 
+section .pending .poll-status {
+  align-items: center;
+  display: inline-flex;
+  gap: var(--space);
+}
+
 /* ── Stat cards ────────────────────────────────────────────────────────── */
 .cards-container {
   display: grid;
@@ -425,6 +439,15 @@ td {
 tr:last-child td { border-bottom: none; }
 tr:hover         { background: var(--color-table-bg-alt); }
 
+tr.group-row td,
+tr.group-row:hover { background: var(--color-table-bg-alt); }
+tr.group-row td {
+  color: var(--color-text-light);
+  font-size: var(--font-size-small);
+  font-weight: 600;
+  padding: var(--space) var(--space-2x);
+}
+
 /* ── Subjects ──────────────────────────────────────────────────────────── */
 .subjects { display: flex; flex-wrap: wrap; gap: var(--space-1-2); }
 
@@ -479,6 +502,13 @@ time {
   font-size: var(--font-size-small);
   word-wrap: break-word;
 }
+.error-message details code {
+  max-width: 600px;
+  max-height: 320px;
+  overflow: auto;
+  white-space: pre;
+  font-size: var(--font-size-small);
+}
 
 /* ── Links ─────────────────────────────────────────────────────────────── */
 .stream-link { color: var(--color-primary); font-weight: 600; }
@@ -518,6 +548,15 @@ details summary {
 details summary code { display: inline; user-select: text; }
 details[open] summary { margin-bottom: var(--space); }
 details code { display: block; max-width: 400px; white-space: pre-wrap; }
+details summary:has(> code.truncate) { white-space: nowrap; }
+details summary code.truncate {
+  display: inline-block;
+  max-width: 32ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  vertical-align: middle;
+  white-space: nowrap;
+}
 
 /* ── HTMX ──────────────────────────────────────────────────────────────── */
 .htmx-indicator { opacity: 0; transition: opacity 200ms; }
@@ -542,6 +581,46 @@ details code { display: block; max-width: 400px; white-space: pre-wrap; }
 }
 
 /* ── Responsive ────────────────────────────────────────────────────────── */
+
+.metrics-chart {
+  background: var(--color-elevated);
+  border-radius: var(--space-1-2);
+  box-shadow: 0 1px 3px var(--color-shadow);
+  padding: var(--space-2x) var(--space-3x);
+  margin-bottom: var(--space-3x);
+}
+.metrics-chart svg { width: 100%; height: auto; display: block; }
+.metrics-chart-header {
+  display: flex;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: var(--space);
+  margin-bottom: var(--space);
+}
+.metrics-legend { display: flex; gap: var(--space-2x); font-size: var(--font-size-small); color: var(--color-text-light); }
+.metrics-legend span::before {
+  content: "";
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  margin-right: 6px;
+  border-radius: 2px;
+}
+.metrics-legend-runs::before { background: var(--color-primary); opacity: 0.45; }
+.metrics-legend-exec::before { background: var(--color-warning); }
+.chart-grid  { stroke: var(--color-border); stroke-width: 1; }
+.chart-axis  { fill: var(--color-text-light); font-size: 11px; font-family: var(--font-sans); }
+.chart-bar   { fill: var(--color-primary); opacity: 0.45; }
+.chart-bar:hover { opacity: 0.7; }
+.chart-line  { fill: none; stroke: var(--color-warning); stroke-width: 2; }
+.chart-point { fill: var(--color-warning); stroke: var(--color-elevated); stroke-width: 2; }
+.metrics-hint { margin: 0 0 var(--space); font-size: var(--font-size-small); color: var(--color-text-light); }
+.metrics-table tr.selectable { cursor: pointer; }
+.metrics-table tr.selectable:hover { background: var(--color-selected); }
+.metrics-table tr.selected { background: var(--color-selected); }
+.metrics-table tr.selected td:first-child { box-shadow: inset 3px 0 0 var(--color-primary); }
+.metrics-table tr.selected code { color: var(--color-primary); }
+
 @media (max-width: 768px) {
   .nav            { flex-wrap: wrap; }
   .nav-list       { order: 3; width: 100%; margin-top: var(--space); }