activeadmin_annotations 0.1.1 → 0.1.2

data/app/assets/controllers/activeadmin_annotations/highlights.js

@@ -0,0 +1,76 @@
+import { rangeForOffsets } from "activeadmin_annotations/selection";
+import { highlightsSupported } from "activeadmin_annotations/annotator_logic";
+
+export const PENDING_HIGHLIGHT_NAME = "aa-annotations-pending";
+export const SAVED_HIGHLIGHT_NAME = "aa-annotations-saved";
+
+const MARK_CLASS_BY_NAME = {
+  [PENDING_HIGHLIGHT_NAME]: "aa-annotations-mark aa-annotations-mark--pending",
+  [SAVED_HIGHLIGHT_NAME]: "aa-annotations-mark aa-annotations-mark--saved",
+};
+
+export { highlightsSupported };
+
+export class HighlightLayer {
+  constructor(root) {
+    this.root = root;
+    this.supported = highlightsSupported();
+  }
+
+  set(name, offsetPairs) {
+    this.clear(name);
+    if (offsetPairs.length === 0) return;
+
+    if (this.supported) {
+      const highlight = new Highlight();
+      offsetPairs.forEach(([startOffset, endOffset]) => {
+        const range = rangeForOffsets(this.root, startOffset, endOffset);
+        if (range) highlight.add(range);
+      });
+      CSS.highlights.set(name, highlight);
+      return;
+    }
+
+    offsetPairs.forEach(([startOffset, endOffset]) => {
+      const range = rangeForOffsets(this.root, startOffset, endOffset);
+      if (range) this.wrapRange(range, name);
+    });
+  }
+
+  clear(name) {
+    if (this.supported) {
+      CSS.highlights.delete(name);
+      return;
+    }
+
+    this.root.querySelectorAll(`mark[data-aa-highlight="${name}"]`).forEach((mark) => {
+      const parent = mark.parentNode;
+      if (!parent) return;
+
+      while (mark.firstChild) parent.insertBefore(mark.firstChild, mark);
+      parent.removeChild(mark);
+      parent.normalize();
+    });
+  }
+
+  disconnect() {
+    this.clear(PENDING_HIGHLIGHT_NAME);
+    this.clear(SAVED_HIGHLIGHT_NAME);
+  }
+
+  wrapRange(range, name) {
+    if (range.collapsed) return;
+
+    const mark = document.createElement("mark");
+    mark.dataset.aaHighlight = name;
+    mark.className = MARK_CLASS_BY_NAME[name] || "aa-annotations-mark";
+
+    try {
+      range.surroundContents(mark);
+    } catch {
+      const contents = range.extractContents();
+      mark.appendChild(contents);
+      range.insertNode(mark);
+    }
+  }
+}

data/app/assets/controllers/activeadmin_annotations/selection.js

@@ -0,0 +1,73 @@
+export function currentSelection(selection, annotatable) {
+  if (!selection || selection.rangeCount === 0 || selection.isCollapsed) return null;
+
+  const range = selection.getRangeAt(0);
+  if (!selectionInsideAnnotatable(range, annotatable)) return null;
+
+  const selectedText = selection.toString().trim();
+  if (!selectedText) return null;
+
+  const startOffset = offsetWithinAnnotatable(annotatable, range.startContainer, range.startOffset);
+  const endOffset = offsetWithinAnnotatable(annotatable, range.endContainer, range.endOffset);
+  if (startOffset === null || endOffset === null || endOffset <= startOffset) return null;
+
+  return { selectedText, startOffset, endOffset };
+}
+
+export function rangeForOffsets(annotatable, startOffset, endOffset) {
+  const walker = document.createTreeWalker(annotatable, NodeFilter.SHOW_TEXT);
+  let position = 0;
+  let startNode = null;
+  let startPosition = 0;
+  let endNode = null;
+  let endPosition = 0;
+
+  while (walker.nextNode()) {
+    const node = walker.currentNode;
+    const length = node.textContent.length;
+    const nextPosition = position + length;
+
+    if (!startNode && startOffset <= nextPosition) {
+      startNode = node;
+      startPosition = startOffset - position;
+    }
+
+    if (!endNode && endOffset <= nextPosition) {
+      endNode = node;
+      endPosition = endOffset - position;
+      break;
+    }
+
+    position = nextPosition;
+  }
+
+  if (!startNode || !endNode) return null;
+
+  const range = document.createRange();
+  range.setStart(startNode, startPosition);
+  range.setEnd(endNode, endPosition);
+  return range;
+}
+
+function selectionInsideAnnotatable(range, annotatable) {
+  const startElement = elementForNode(range.startContainer);
+  const endElement = elementForNode(range.endContainer);
+  return annotatable.contains(startElement) && annotatable.contains(endElement);
+}
+
+function elementForNode(node) {
+  return node.nodeType === Node.TEXT_NODE ? node.parentElement : node;
+}
+
+function offsetWithinAnnotatable(annotatable, node, offset) {
+  const walker = document.createTreeWalker(annotatable, NodeFilter.SHOW_TEXT);
+  let position = 0;
+
+  while (walker.nextNode()) {
+    const current = walker.currentNode;
+    if (current === node) return position + offset;
+    position += current.textContent.length;
+  }
+
+  return null;
+}

data/app/assets/javascripts/activeadmin_annotations/annotator_logic.mjs

@@ -0,0 +1,73 @@
+export function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+}
+
+export function categoryLabelFor(value, categories) {
+  if (!value) return ""
+  return categories[value] || value
+}
+
+export function createAnnotationPayload(panel, comment) {
+  const payload = {
+    annotation: {
+      field_name: panel.fieldValue,
+      selected_text: panel.pendingSelection.selectedText,
+      start_offset: panel.pendingSelection.startOffset,
+      end_offset: panel.pendingSelection.endOffset,
+      comment: comment,
+      category: panel.categoryInputTarget.value || null,
+      context_paths_json: [],
+    },
+  }
+
+  if (panel.reviewIdValue) {
+    payload.annotation.annotation_review_id = panel.reviewIdValue
+  } else {
+    payload.annotation.subject_type = panel.subjectTypeValue
+    payload.annotation.subject_id = panel.subjectIdValue
+    payload.annotation.context_json = panel.contextValue
+    payload.annotation.context_digest = panel.contextDigestValue
+  }
+
+  if (panel.hasContentRevisionVersionValue) {
+    payload.annotation.displayed_content_revision_version = panel.contentRevisionVersionValue
+  }
+
+  return payload
+}
+
+export function normalizeAnnotation(annotation) {
+  return {
+    id: annotation.id,
+    field_name: annotation.field_name,
+    selected_text: annotation.selected_text,
+    start_offset: annotation.start_offset,
+    end_offset: annotation.end_offset,
+    comment: annotation.comment,
+    category: annotation.category,
+  }
+}
+
+export function savedHighlightOffsetPairs(annotations, editingAnnotationId) {
+  return annotations.flatMap((annotation) => {
+    if (editingAnnotationId && String(annotation.id) === String(editingAnnotationId)) {
+      return []
+    }
+
+    const startOffset = Number(annotation.start_offset)
+    const endOffset = Number(annotation.end_offset)
+    if (!Number.isFinite(startOffset) || !Number.isFinite(endOffset) || endOffset <= startOffset) {
+      return []
+    }
+
+    return [[startOffset, endOffset]]
+  })
+}
+
+export function highlightsSupported() {
+  return typeof CSS !== "undefined" && Boolean(CSS.highlights)
+}

data/app/assets/stylesheets/activeadmin_annotations.css

@@ -298,6 +298,21 @@
   text-underline-offset: 2px;
 }
 
+.aa-annotations-mark {
+  color: inherit;
+}
+
+.aa-annotations-mark--saved {
+  background-color: color-mix(in srgb, #2563eb 30%, #fef08a);
+}
+
+.aa-annotations-mark--pending {
+  background-color: color-mix(in srgb, #2563eb 40%, #fef08a);
+  text-decoration: underline;
+  text-decoration-color: #2563eb;
+  text-underline-offset: 2px;
+}
+
 .aa-annotations-context {
   margin-top: 1rem;
 }

data/app/helpers/active_admin/annotations/panel_helper.rb

@@ -18,9 +18,10 @@ module ActiveAdmin::Annotations
       advance_review_url: nil,
       annotations: nil,
       review: nil,
+      readonly: false,
       &content_block
     )
-      rendered_content = content.presence || capture(&content_block)
+      rendered_content = PanelHtml.prepare(content.presence || capture(&content_block))
       reviewer = current_activeadmin_annotations_reviewer
       unless reviewer
         return render partial: "active_admin/annotations/read_only_content",
@@ -28,7 +29,7 @@ module ActiveAdmin::Annotations
       end
 
       revision_enabled = content_revision_enabled.nil? ? ContentRevision.enabled_for?(subject) : content_revision_enabled
-      review ||= ReviewService.find_or_sync_review!(
+      review ||= ReviewService.preview_review(
         subject: subject,
         reviewer: reviewer,
         context: context,
@@ -37,7 +38,8 @@ module ActiveAdmin::Annotations
         latest_content_revision_version: latest_content_revision_version || content_revision_version || 0,
         content_revision_enabled: revision_enabled
       )
-      annotations ||= annotations_for(review:, field:, revision_enabled:)
+      display_version = content_revision_version.nil? ? review.content_revision_version : content_revision_version.to_i
+      annotations ||= annotations_for(review:, field:, revision_enabled:, display_version:)
       stale_message = stale_message_for(
         review: review,
         revision_enabled: revision_enabled,
@@ -51,27 +53,32 @@ module ActiveAdmin::Annotations
           field: field.to_s,
           review: review,
           annotations: annotations,
+          context: context,
+          context_digest: context_digest || Context.digest_for(context),
           context_panels: context_panels,
           categories: categories || ActiveAdmin::Annotations.categories,
           category_label: category_label || ActiveAdmin::Annotations.category_label,
           content: rendered_content,
           content_revision_enabled: revision_enabled,
-          content_revision_version: review.content_revision_version,
+          content_revision_version: display_version,
           latest_content_revision_version: latest_content_revision_version || review.content_revision_version,
-          content_revision_label: ContentRevision.version_label(review.content_revision_version),
+          content_revision_label: ContentRevision.version_label(display_version),
           content_stale: content_stale || review.context_stale?,
           stale_message: stale_message,
-          advance_review_url: advance_review_url
+          advance_review_url: advance_review_url,
+          readonly: readonly
         }
     end
 
     private
 
-    def annotations_for(review:, field:, revision_enabled:)
+    def annotations_for(review:, field:, revision_enabled:, display_version:)
+      return [] unless review&.persisted?
+
       scope = review.annotations.where(field_name: field.to_s).order(:created_at)
       return scope unless revision_enabled
 
-      scope.where(content_revision_version: review.content_revision_version)
+      scope.where(content_revision_version: display_version)
     end
 
     def stale_message_for(review:, revision_enabled:, pinned_version:, latest_version:)

data/app/models/active_admin/annotations/review.rb

@@ -30,13 +30,18 @@ class ActiveAdmin::Annotations::Review < ActiveAdmin::Annotations::ApplicationRe
   }
 
   def needs_follow_up?
-    ActiveModel::Type::Boolean.new.cast(metadata_json.to_h["needs_follow_up"])
+    metadata_flag("needs_follow_up")
   end
 
   def context_stale?
-    ActiveModel::Type::Boolean.new.cast(metadata_json.to_h["context_stale"])
+    metadata_flag("context_stale")
   end
 
+  def metadata_flag(key)
+    ActiveModel::Type::Boolean.new.cast(metadata_json.to_h[key]) == true
+  end
+  private :metadata_flag
+
   def self.ransackable_attributes(_auth_object = nil)
     %w[
       subject_type

data/app/services/active_admin/annotations/review_service.rb

@@ -3,6 +3,10 @@
 module ActiveAdmin::Annotations
   class ReviewService
     class << self
+      def preview_review(**kwargs)
+        assemble_review!(**kwargs, persist: false)
+      end
+
       def find_or_sync_review!(
         subject:,
         reviewer:,
@@ -52,35 +56,19 @@ module ActiveAdmin::Annotations
 
       private
 
-      def sync_with_content_revision!(review, context_hash:, digest:, pinned_version:, latest_version:)
-        if review.new_record?
-          review.assign_attributes(
-            content_revision_version: pinned_version,
-            context_json: context_hash,
-            context_digest: digest,
-            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
-          )
-        elsif latest_version > review.content_revision_version
-          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => true)
-        elsif review.content_revision_version == pinned_version && review.context_digest != digest
-          review.assign_attributes(
-            context_json: context_hash,
-            context_digest: digest,
-            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
-          )
-        elsif !review.context_stale?
-          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => false)
-        end
+      def sync_and_save_review!(**kwargs)
+        assemble_review!(**kwargs, persist: true)
       end
 
-      def sync_and_save_review!(
+      def assemble_review!(
         subject:,
         reviewer:,
         context:,
-        context_digest:,
-        content_revision_version:,
-        latest_content_revision_version:,
-        content_revision_enabled:
+        persist:,
+        context_digest: nil,
+        content_revision_version: 0,
+        latest_content_revision_version: content_revision_version,
+        content_revision_enabled: ContentRevision.enabled_for?(subject)
       )
         context_hash = context.deep_stringify_keys
         digest = context_digest.presence || Context.digest_for(context_hash)
@@ -104,12 +92,31 @@ module ActiveAdmin::Annotations
           sync_without_content_revision!(review, context_hash: context_hash, digest: digest)
         end
 
-        return review unless review.changed?
-
-        review.save!
+        review.save! if persist
         review
       end
 
+      def sync_with_content_revision!(review, context_hash:, digest:, pinned_version:, latest_version:)
+        if review.new_record?
+          review.assign_attributes(
+            content_revision_version: pinned_version,
+            context_json: context_hash,
+            context_digest: digest,
+            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+          )
+        elsif latest_version > review.content_revision_version
+          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => true)
+        elsif review.content_revision_version == pinned_version && review.context_digest != digest
+          review.assign_attributes(
+            context_json: context_hash,
+            context_digest: digest,
+            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+          )
+        elsif !review.context_stale?
+          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => false)
+        end
+      end
+
       def sync_without_content_revision!(review, context_hash:, digest:)
         if review.new_record?
           review.assign_attributes(

data/app/views/active_admin/annotations/_panel.html.erb

@@ -10,7 +10,10 @@
      }
    end %>
 <% category_options = categories.to_h %>
-<% panel_id = "aa-annotation-#{review.id}" %>
+<% readonly = local_assigns.fetch(:readonly, false) %>
+<% panel_id = review.id.present? ? "aa-annotation-#{review.id}" : "aa-annotation-new-#{field}" %>
+<% context_payload = local_assigns.fetch(:context, {}) %>
+<% context_digest_value = local_assigns[:context_digest] %>
 
 <%= stylesheet_link_tag "activeadmin_annotations", "data-turbo-track": "reload" %>
 
@@ -32,6 +35,12 @@
     data-controller="activeadmin-annotations--annotator"
     data-activeadmin-annotations--annotator-review-id-value="<%= review.id %>"
     data-activeadmin-annotations--annotator-field-value="<%= field %>"
+    data-activeadmin-annotations--annotator-subject-type-value="<%= subject.class.name %>"
+    data-activeadmin-annotations--annotator-subject-id-value="<%= subject.id %>"
+    data-activeadmin-annotations--annotator-context-value="<%= ERB::Util.html_escape(context_payload.to_json) %>"
+    data-activeadmin-annotations--annotator-context-digest-value="<%= context_digest_value %>"
+    data-activeadmin-annotations--annotator-content-revision-version-value="<%= content_revision_version %>"
+    data-activeadmin-annotations--annotator-readonly-value="<%= readonly ? "true" : "false" %>"
     data-activeadmin-annotations--annotator-category-label-value="<%= category_label %>"
     data-activeadmin-annotations--annotator-categories-value="<%= ERB::Util.html_escape(category_options.to_json) %>"
     data-activeadmin-annotations--annotator-create-url-value="<%= admin_annotation_spans_path(format: :json) %>"
@@ -60,7 +69,11 @@
 
     <aside class="aa-annotations-sidebar" data-activeadmin-annotations--annotator-target="sidebar">
       <h4>Annotations</h4>
-      <p class="aa-annotations-hint">Select text in the block, then add a comment.</p>
+      <% if readonly %>
+        <p class="aa-annotations-hint">These notes belong to another version. Add notes on the version being reviewed.</p>
+      <% else %>
+        <p class="aa-annotations-hint">Select text in the block, then add a comment.</p>
+      <% end %>
       <% if content_revision_enabled && content_revision_label.present? %>
         <p class="aa-annotations-version"><%= content_revision_label %></p>
       <% end %>

data/db/migrate/20260617120000_create_activeadmin_annotations_tables.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
-class CreateActiveadminAnnotationsTables < ActiveRecord::Migration[8.1]
+class CreateActiveadminAnnotationsTables < ActiveRecord::Migration[7.1]
   def change
-    create_table :annotation_reviews, id: :uuid do |t|
-      t.references :subject, polymorphic: true, null: false, type: :uuid, index: true
-      t.uuid :reviewer_id, null: false
+    enable_pgcrypto_for_postgres
+
+    json_column_type = postgres? ? :jsonb : :json
+    uuid_column_type = postgres? ? :uuid : :string
+
+    create_table :annotation_reviews, id: uuid_column_type do |t|
+      t.references :subject, polymorphic: true, null: false, type: uuid_column_type, index: true
+      t.column :reviewer_id, uuid_column_type, null: false
       t.string :review_status, null: false, default: "pending"
       t.text :notes
-      t.jsonb :context_json, null: false, default: {}
+      t.send(json_column_type, :context_json, null: false, default: {})
       t.string :context_digest
       t.integer :content_revision_version, null: false, default: 0
-      t.jsonb :metadata_json, null: false, default: {}
+      t.send(json_column_type, :metadata_json, null: false, default: {})
 
       t.timestamps
     end
@@ -20,8 +25,8 @@ class CreateActiveadminAnnotationsTables < ActiveRecord::Migration[8.1]
     add_index :annotation_reviews, :context_digest
     add_index :annotation_reviews, :reviewer_id
 
-    create_table :annotation_spans, id: :uuid do |t|
-      t.references :annotation_review, null: false, type: :uuid, foreign_key: {to_table: :annotation_reviews}, index: true
+    create_table :annotation_spans, id: uuid_column_type do |t|
+      t.references :annotation_review, null: false, type: uuid_column_type, foreign_key: {to_table: :annotation_reviews}, index: true
       t.string :field_name, null: false
       t.text :selected_text, null: false
       t.integer :start_offset, null: false
@@ -29,8 +34,8 @@ class CreateActiveadminAnnotationsTables < ActiveRecord::Migration[8.1]
       t.text :comment, null: false
       t.string :category
       t.integer :content_revision_version, null: false, default: 0
-      t.jsonb :context_paths_json, null: false, default: []
-      t.jsonb :metadata_json, null: false, default: {}
+      t.send(json_column_type, :context_paths_json, null: false, default: [])
+      t.send(json_column_type, :metadata_json, null: false, default: {})
 
       t.timestamps
     end
@@ -38,4 +43,16 @@ class CreateActiveadminAnnotationsTables < ActiveRecord::Migration[8.1]
     add_index :annotation_spans, :category
     add_index :annotation_spans, :field_name
   end
+
+  private
+
+  def enable_pgcrypto_for_postgres
+    return unless postgres?
+
+    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
+  end
+
+  def postgres?
+    connection.adapter_name.match?(/postgres/i)
+  end
 end

data/db/migrate/20260706150000_add_metadata_json_gin_index_to_annotation_reviews.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class AddMetadataJsonGinIndexToAnnotationReviews < ActiveRecord::Migration[8.1]
+class AddMetadataJsonGinIndexToAnnotationReviews < ActiveRecord::Migration[7.1]
   def change
     return unless connection.adapter_name.match?(/postgres/i)
 

data/db/migrate/20260710120000_add_panel_query_index_to_annotation_spans.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class AddPanelQueryIndexToAnnotationSpans < ActiveRecord::Migration[8.1]
+class AddPanelQueryIndexToAnnotationSpans < ActiveRecord::Migration[7.1]
   def change
     add_index :annotation_spans,
       %i[annotation_review_id field_name content_revision_version],

data/lib/activeadmin/annotations/copy_text.rb

@@ -40,7 +40,6 @@ module ActiveAdmin::Annotations
         "Review",
         "Subject: #{review.subject_type} ##{review.subject_id}",
         "Status: #{review.review_status}",
-        "Reviewer ID: #{review.reviewer_id}",
         "Review ID: #{review.id}"
       ]
       if content_revision_enabled?

data/lib/activeadmin/annotations/engine.rb

@@ -25,6 +25,18 @@ module ActiveAdmin
             to: "activeadmin_annotations/annotator_controller.js"
           importmap.pin "controllers/activeadmin_annotations/clipboard_controller",
             to: "activeadmin_annotations/clipboard_controller.js"
+          importmap.pin "activeadmin_annotations/selection",
+            to: "activeadmin_annotations/selection.js"
+          importmap.pin "activeadmin_annotations/highlights",
+            to: "activeadmin_annotations/highlights.js"
+          importmap.pin "activeadmin_annotations/annotation_list",
+            to: "activeadmin_annotations/annotation_list.js"
+          importmap.pin "activeadmin_annotations/annotation_client",
+            to: "activeadmin_annotations/annotation_client.js"
+          importmap.pin "activeadmin_annotations/composer",
+            to: "activeadmin_annotations/composer.js"
+          importmap.pin "activeadmin_annotations/annotator_logic",
+            to: "activeadmin_annotations/annotator_logic.mjs"
         end
 
         Rails.application.importmap.draw(&pin_controller)
@@ -33,7 +45,10 @@ module ActiveAdmin
 
       initializer "activeadmin_annotations.assets" do |app|
         assets_path = root.join("app/assets")
-        app.config.importmap.cache_sweepers << assets_path.join("controllers") if app.config.respond_to?(:importmap)
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.cache_sweepers << assets_path.join("controllers")
+          app.config.importmap.cache_sweepers << assets_path.join("javascripts")
+        end
 
         assets = app.config.assets if app.config.respond_to?(:assets)
         assets.precompile << "activeadmin_annotations.css" if assets&.respond_to?(:precompile)

data/lib/activeadmin/annotations/exporter.rb

@@ -36,7 +36,7 @@ module ActiveAdmin::Annotations
 
     def export_relation_in_batches
       reviews.find_in_batches(batch_size: BATCH_SIZE) do |batch|
-        ActiveRecord::Associations::Preloader.new(records: batch, associations: :annotations).call
+        ActiveRecord::Associations::Preloader.new(records: batch, associations: [:annotations, :subject]).call
         batch.each do |review|
           rows_for(review).each { |row| yield row }
         end

data/lib/activeadmin/annotations/panel_html.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  class PanelHtml
+    def self.prepare(content)
+      return "".html_safe if content.nil?
+
+      html = content.to_s
+      prepared = if content.respond_to?(:html_safe?) && content.html_safe?
+        sanitizer.sanitize(html)
+      else
+        ERB::Util.html_escape(html)
+      end
+      prepared.html_safe
+    end
+
+    def self.sanitizer
+      Rails::HTML::Sanitizer.safe_list_sanitizer.new
+    end
+  end
+end

data/lib/activeadmin/annotations/review_access.rb

@@ -18,8 +18,20 @@ module ActiveAdmin::Annotations
       review
     end
 
+    def self.subject_for_span_create!(subject_type:, subject_id:)
+      raise NotFound, "Subject not found" if subject_type.blank? || subject_id.blank?
+
+      klass = subject_type.to_s.safe_constantize
+      raise NotFound, "Subject not found" unless klass.is_a?(Class) && klass < ActiveRecord::Base
+
+      subject = klass.find_by(id: subject_id)
+      raise NotFound, "Subject not found" unless subject
+
+      subject
+    end
+
     def self.authorize_annotation!(annotation:, reviewer:)
-      raise Forbidden, "Annotation not found" unless annotation
+      raise NotFound, "Annotation not found" unless annotation
       raise Forbidden, "Annotation access denied" unless reviewer.present? &&
         annotation.annotation_review.reviewer_id == reviewer.id