rails-markup 1.2.0

data/app/views/rails_markup/dashboard/board.html.erb

@@ -0,0 +1,135 @@
+<% content_for(:title) { "Board" } %>
+<% content_for(:page_title) { "Annotations Board" } %>
+
+<%= render "styles" %>
+
+<%# View toggle %>
+<div class="rm-filters">
+  <a href="<%= rails_markup.root_path %>" class="rm-pill">List</a>
+  <a href="<%= rails_markup.board_path %>" class="rm-pill rm-pill-active">Board</a>
+</div>
+
+<div class="rm-board">
+  <% column_config = {
+    pending:      { label: "Pending",      color: "#f59e0b", bg: "#fffbeb", border: "#fde68a" },
+    acknowledged: { label: "Acknowledged", color: "#3b82f6", bg: "#eff6ff", border: "#bfdbfe" },
+    resolved:     { label: "Resolved",     color: "#10b981", bg: "#ecfdf5", border: "#a7f3d0" },
+    dismissed:    { label: "Dismissed",    color: "#9ca3af", bg: "#f9fafb", border: "#e5e7eb" }
+  } %>
+
+  <% column_config.each do |status, config| %>
+    <div class="rm-board-column" data-status="<%= status %>"
+         style="border-top: 3px solid <%= config[:color] %>;">
+      <div class="rm-board-column-header" style="background: <%= config[:bg] %>; color: <%= config[:color] %>;">
+        <span><%= config[:label] %></span>
+        <span style="font-size:12px;font-weight:400;"><%= @columns[status].size %></span>
+      </div>
+      <div class="rm-board-cards">
+        <% @columns[status].each do |annotation| %>
+          <div class="rm-board-card" draggable="true" data-annotation-id="<%= annotation.id %>">
+            <div style="display:flex;align-items:center;gap:6px;margin-bottom:6px;">
+              <span class="rm-badge rm-intent-<%= annotation.intent %>" style="font-size:10px;"><%= annotation.intent %></span>
+              <% if annotation.severity != "suggestion" %>
+                <span class="rm-badge rm-severity-<%= annotation.severity %>" style="font-size:10px;"><%= annotation.severity %></span>
+              <% end %>
+              <% if annotation.author_name.present? %>
+                <span style="font-size:10px;color:#9ca3af;margin-left:auto;"><%= annotation.author_name %></span>
+              <% end %>
+            </div>
+            <div style="font-size:13px;line-height:1.5;color:#374151;"><%= truncate(annotation.content, length: 120) %></div>
+            <div style="margin-top:6px;font-size:10px;color:#d1d5db;">
+              <code style="font-size:10px;"><%= truncate(annotation.page_url, length: 30) %></code>
+              &middot;
+              <span title="<%= annotation.created_at.strftime("%B %d, %Y at %H:%M") %>"><%= time_ago_in_words(annotation.created_at) %></span>
+            </div>
+            <%# Touch fallback for drag-and-drop: pick a status directly %>
+            <select class="rm-board-move" data-annotation-id="<%= annotation.id %>"
+                    aria-label="Move annotation to status"
+                    style="margin-top:8px;width:100%;font-size:11px;padding:4px;border:1px solid #e5e7eb;border-radius:6px;background:#fff;color:#6b7280;">
+              <% %w[pending acknowledged resolved dismissed].each do |s| %>
+                <option value="<%= s %>" <%= "selected" if annotation.status == s %>><%= s.capitalize %></option>
+              <% end %>
+            </select>
+          </div>
+        <% end %>
+        <% if @columns[status].empty? %>
+          <div style="text-align:center;padding:24px 8px;color:#d1d5db;font-size:12px;">No items</div>
+        <% end %>
+      </div>
+    </div>
+  <% end %>
+</div>
+
+<script>
+(function() {
+  const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+
+  document.querySelectorAll('.rm-board-card').forEach(card => {
+    card.addEventListener('dragstart', (e) => {
+      e.dataTransfer.setData('text/plain', card.dataset.annotationId);
+      e.dataTransfer.effectAllowed = 'move';
+      card.style.opacity = '0.5';
+    });
+    card.addEventListener('dragend', () => { card.style.opacity = '1'; });
+  });
+
+  document.querySelectorAll('.rm-board-column').forEach(col => {
+    col.addEventListener('dragover', (e) => {
+      e.preventDefault();
+      e.dataTransfer.dropEffect = 'move';
+      col.classList.add('rm-drag-over');
+    });
+    col.addEventListener('dragleave', (e) => {
+      if (!col.contains(e.relatedTarget)) col.classList.remove('rm-drag-over');
+    });
+    col.addEventListener('drop', (e) => {
+      e.preventDefault();
+      col.classList.remove('rm-drag-over');
+      const id = e.dataTransfer.getData('text/plain');
+      moveCard(id, col.dataset.status);
+    });
+  });
+
+  // Touch fallback: status <select> on each card
+  document.querySelectorAll('.rm-board-move').forEach(select => {
+    select.addEventListener('change', () => {
+      moveCard(select.dataset.annotationId, select.value);
+    });
+  });
+
+  function moveCard(id, newStatus) {
+    const card = document.querySelector('[data-annotation-id="' + id + '"]');
+    if (!card || card.closest('[data-status]').dataset.status === newStatus) return;
+
+    // Optimistically move the card to the target column, then reconcile.
+    const targetCol = document.querySelector('.rm-board-column[data-status="' + newStatus + '"]');
+    if (targetCol) targetCol.querySelector('.rm-board-cards').appendChild(card);
+    const select = card.querySelector('.rm-board-move');
+    if (select) select.value = newStatus;
+    updateColumnCounts();
+
+    const basePath = window.location.pathname.replace(/\/board\/?$/, '');
+    fetch(basePath + '/annotations/' + id, {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrfToken || ''
+      },
+      body: JSON.stringify({ action_type: 'transition', status: newStatus })
+    }).then((resp) => {
+      // A rejected transition (422/401/…) resolves without throwing — resync.
+      if (!resp.ok) window.location.reload();
+    }).catch(() => {
+      window.location.reload();
+    });
+  }
+
+  function updateColumnCounts() {
+    document.querySelectorAll('.rm-board-column').forEach(col => {
+      const count = col.querySelectorAll('.rm-board-card').length;
+      const countEl = col.querySelector('.rm-board-column-header span:last-child');
+      if (countEl) countEl.textContent = count;
+    });
+  }
+})();
+</script>

data/app/views/rails_markup/dashboard/index.html.erb

@@ -0,0 +1,38 @@
+<% content_for(:title) { "Dashboard" } %>
+<% content_for(:page_title) { "Annotations" } %>
+
+<%= render "styles" %>
+
+
+<div class="rm-layout">
+  <div class="rm-main">
+    <turbo-frame id="annotations-content">
+      <%= render "stats" %>
+      <%= render "filters" %>
+      <%= render "annotation_list" %>
+    </turbo-frame>
+  </div>
+
+  <turbo-frame id="detail-panel" class="rm-panel rm-panel-empty">
+  </turbo-frame>
+</div>
+
+<script>
+  document.addEventListener("turbo:frame-load", (e) => {
+    if (e.target.id !== "detail-panel") return;
+    // Show panel (hidden when empty)
+    e.target.classList.remove("rm-panel-empty");
+    // Highlight active card
+    document.querySelectorAll(".rm-card-active").forEach(c => c.classList.remove("rm-card-active"));
+    const src = e.target.getAttribute("src") || "";
+    const match = src.match(/annotations\/(\d+)/);
+    if (match) {
+      const card = document.querySelector(`[data-annotation-id="${match[1]}"]`);
+      if (card) card.classList.add("rm-card-active");
+    }
+    // Scroll to panel on mobile
+    if (window.innerWidth <= 900) {
+      e.target.scrollIntoView({ behavior: "smooth", block: "start" });
+    }
+  });
+</script>

data/app/views/rails_markup/dashboard/show.html.erb

@@ -0,0 +1,129 @@
+<% content_for(:title) { "Annotation ##{@annotation.id}" } %>
+
+<%= render "styles" %>
+
+<turbo-frame id="detail-panel">
+<div class="rm-detail">
+  <%# Close button %>
+  <button type="button" class="rm-back" onclick="var f=this.closest('turbo-frame'); f.innerHTML=''; f.classList.add('rm-panel-empty'); document.querySelectorAll('.rm-card-active').forEach(c => c.classList.remove('rm-card-active'));">&#10005; Close</button>
+
+  <%# Header badges %>
+  <div class="rm-detail-header">
+    <span class="rm-dot rm-dot-<%= @annotation.status %>"></span>
+    <span class="rm-badge rm-status-<%= @annotation.status %>"><%= @annotation.status %></span>
+    <span class="rm-badge rm-intent-<%= @annotation.intent %>"><%= @annotation.intent %></span>
+    <span class="rm-badge rm-severity-<%= @annotation.severity %>"><%= @annotation.severity %></span>
+  </div>
+
+  <%# Content %>
+  <div class="rm-detail-content"><%= @annotation.content %></div>
+
+  <%# Metadata %>
+  <dl class="rm-detail-meta">
+    <dt>Page</dt>
+    <dd><code><%= @annotation.page_url %></code></dd>
+
+    <% if @annotation.selected_text.present? %>
+      <dt>Selected text</dt>
+      <dd>&ldquo;<%= truncate(@annotation.selected_text, length: 200) %>&rdquo;</dd>
+    <% end %>
+
+    <% if @annotation.target.present? && @annotation.target["selector"].present? %>
+      <dt>Element</dt>
+      <dd><code><%= @annotation.target["selector"] %></code></dd>
+    <% end %>
+
+    <% if @annotation.target.present? && @annotation.target["boundingBox"].present? %>
+      <dt>Position</dt>
+      <dd><%= @annotation.target["boundingBox"].values_at("x", "y", "width", "height").compact.join(" \u00D7 ") %></dd>
+    <% end %>
+
+    <% if @annotation.author_name.present? %>
+      <dt>Author</dt>
+      <dd><%= @annotation.author_name %></dd>
+    <% end %>
+
+    <dt>Created</dt>
+    <dd><span title="<%= @annotation.created_at.strftime("%B %d, %Y at %H:%M:%S") %>"><%= time_ago_in_words(@annotation.created_at) %> ago</span></dd>
+
+    <% if @annotation.updated_at != @annotation.created_at %>
+      <dt>Updated</dt>
+      <dd><span title="<%= @annotation.updated_at.strftime("%B %d, %Y at %H:%M:%S") %>"><%= time_ago_in_words(@annotation.updated_at) %> ago</span></dd>
+    <% end %>
+
+    <% if @annotation.metadata&.dig("screenshot").present? %>
+      <dt>Screenshot</dt>
+      <dd><img src="<%= @annotation.metadata["screenshot"] %>" style="max-width:100%;border:1px solid #e5e7eb;border-radius:8px;" alt="Element screenshot"></dd>
+    <% end %>
+  </dl>
+
+  <%# Actions (only for non-terminal states) %>
+  <% if @annotation.status.in?(%w[pending acknowledged]) %>
+    <div class="rm-actions">
+      <% if @annotation.status == "pending" %>
+        <%= form_tag(rails_markup.annotation_path(@annotation, action_type: "acknowledge"), method: :patch, style: "display:inline") do %>
+          <button type="submit" class="rm-btn rm-btn-primary">Acknowledge</button>
+        <% end %>
+      <% end %>
+
+      <button type="button" class="rm-btn rm-btn-success" onclick="document.getElementById('resolve-form-<%= @annotation.id %>').style.display='block'">Resolve</button>
+      <button type="button" class="rm-btn rm-btn-danger" onclick="document.getElementById('dismiss-form-<%= @annotation.id %>').style.display='block'">Dismiss</button>
+    </div>
+
+    <%# Resolve form %>
+    <div id="resolve-form-<%= @annotation.id %>" style="display:none; margin-top: 16px;">
+      <%= form_tag(rails_markup.annotation_path(@annotation, action_type: "resolve"), method: :patch) do %>
+        <div class="rm-form-group">
+          <label for="summary">Resolution summary (optional)</label>
+          <textarea name="summary" id="summary" class="rm-input" rows="2" placeholder="What was done to resolve this?"></textarea>
+        </div>
+        <button type="submit" class="rm-btn rm-btn-success">Confirm Resolve</button>
+        <button type="button" class="rm-btn" onclick="this.parentElement.parentElement.style.display='none'">Cancel</button>
+      <% end %>
+    </div>
+
+    <%# Dismiss form %>
+    <div id="dismiss-form-<%= @annotation.id %>" style="display:none; margin-top: 16px;">
+      <%= form_tag(rails_markup.annotation_path(@annotation, action_type: "dismiss"), method: :patch) do %>
+        <div class="rm-form-group">
+          <label for="reason">Dismiss reason (optional)</label>
+          <textarea name="reason" id="reason" class="rm-input" rows="2" placeholder="Why is this being dismissed?"></textarea>
+        </div>
+        <button type="submit" class="rm-btn rm-btn-danger">Confirm Dismiss</button>
+        <button type="button" class="rm-btn" onclick="this.parentElement.parentElement.style.display='none'">Cancel</button>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%# Thread %>
+  <% if @annotation.thread.any? %>
+    <div class="rm-thread">
+      <h3>Thread (<%= @annotation.thread.size %>)</h3>
+      <% @annotation.thread.each do |entry| %>
+        <div class="rm-thread-entry rm-thread-<%= entry['role'] || 'user' %>">
+          <div class="rm-thread-role"><%= entry["role"] || "user" %></div>
+          <div><%= entry["message"] %></div>
+          <div class="rm-thread-time"><%= entry["timestamp"] %></div>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%# Reply form %>
+  <div class="rm-thread" style="<%= @annotation.thread.empty? ? 'margin-top: 24px; border-top: 1px solid #e5e7eb; padding-top: 20px;' : '' %>">
+    <h3>Add reply</h3>
+    <%= form_tag(rails_markup.annotation_path(@annotation, action_type: "reply"), method: :patch) do %>
+      <div class="rm-form-group">
+        <textarea name="message" class="rm-input" rows="2" placeholder="Type a reply..." required></textarea>
+      </div>
+      <div class="rm-form-group">
+        <select name="role" class="rm-select">
+          <option value="agent">Agent</option>
+          <option value="user">User</option>
+        </select>
+      </div>
+      <button type="submit" class="rm-btn rm-btn-primary">Reply</button>
+    <% end %>
+  </div>
+</div>
+</turbo-frame>

data/app/views/rails_markup/shared/_toolbar.html.erb

@@ -0,0 +1,28 @@
+<%# Rails Markup annotation toolbar — self-contained, no Tailwind/Stimulus dependency %>
+<% if RailsMarkup.config.toolbar_enabled %>
+<script>
+<%== File.read(File.expand_path("../../../assets/javascripts/rails_markup/toolbar.js", __dir__)) %>
+</script>
+<script>
+  (function() {
+    if (window.__rmToolbarBound) return;
+    window.__rmToolbarBound = true;
+
+    var opts = {
+      endpoint: "<%= rails_markup.root_path.chomp("/") %>/api",
+      accent: "<%= j(RailsMarkup.config.toolbar_accent) %>",
+      position: "<%= j(RailsMarkup.config.toolbar_position) %>",
+      size: "<%= j(RailsMarkup.config.toolbar_size) %>",
+      fabVisible: <%= RailsMarkup.config.fab_visible ? "true" : "false" %>,
+      enableScreenshots: <%= RailsMarkup.config.enable_screenshots ? "true" : "false" %>,
+      healthInterval: <%= RailsMarkup.config.health_interval %>
+    };
+    // Init immediately (DOM is ready — script is at end of body)
+    RailsMarkupToolbar.init(opts);
+    // Re-init after Turbo Drive navigations (DOMContentLoaded won't fire again)
+    document.addEventListener("turbo:load", function() {
+      RailsMarkupToolbar.init(opts);
+    });
+  })();
+</script>
+<% end %>

data/bin/rails-markup

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rails_markup/cli"
+RailsMarkup::Cli.start(ARGV)

data/config/routes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+RailsMarkup::Engine.routes.draw do
+  # Dashboard
+  root to: "dashboard#index"
+  resources :annotations, only: [:show, :update], controller: "dashboard", constraints: { id: /\d+/ }
+  post "dismiss_all", to: "dashboard#dismiss_all"
+  get "load_more", to: "dashboard#load_more", as: :load_more
+  get "board", to: "dashboard#board"
+  get "export.csv", to: "dashboard#export_csv", as: :export_csv
+  get "export.json", to: "dashboard#export_json", as: :export_json
+
+  # Toolbar API (same-origin, used by browser toolbar)
+  scope :api, defaults: { format: :json } do
+    post "sessions", to: "annotations#create_session"
+    post "sessions/:session_id/annotations", to: "annotations#create"
+    get "health", to: "annotations#health"
+
+    get "annotations", to: "annotations#index"
+    put "annotations/:client_uuid", to: "annotations#upsert"
+    delete "annotations/:client_uuid", to: "annotations#destroy"
+
+    scope "annotations/:id", constraints: { id: /\d+/ } do
+      post "acknowledge", to: "annotations#acknowledge"
+      post "resolve", to: "annotations#resolve"
+      post "dismiss", to: "annotations#dismiss"
+      post "reply", to: "annotations#reply"
+    end
+  end
+
+  # External API (token-authenticated, used by MCP/CLI tools)
+  # Paths: /external/pending, /external/:id, /external/:id/{action}
+  # Full URL (with mount): /admin/annotations/external/pending
+  namespace :external, defaults: { format: :json } do
+    get "pending", to: "annotations#pending"
+    get ":id", to: "annotations#show", constraints: { id: /\d+/ }
+
+    scope ":id", constraints: { id: /\d+/ } do
+      patch "acknowledge", to: "annotations#acknowledge"
+      patch "resolve", to: "annotations#resolve"
+      patch "dismiss", to: "annotations#dismiss"
+      patch "reply", to: "annotations#reply"
+    end
+  end
+end

data/db/migrate/20260720000000_add_client_uuid_to_rails_markup_annotations.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class AddClientUuidToRailsMarkupAnnotations < ActiveRecord::Migration[7.0]
+  def change
+    # Honor a custom config.table_name — hardcoding the default silently skips
+    # the migration (and defeats create-dedup) on installs that renamed the table.
+    table = RailsMarkup.config.table_name.to_sym
+    return unless table_exists?(table)
+
+    add_column table, :client_uuid, :string, limit: 64 unless column_exists?(table, :client_uuid)
+    add_index table, :client_uuid, unique: true unless index_exists?(table, :client_uuid, unique: true)
+  end
+end

data/db/migrate/20260721000000_backfill_rails_markup_client_uuids.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails_markup/client_uuid_maintenance"
+
+class BackfillRailsMarkupClientUuids < ActiveRecord::Migration[7.0]
+  def up
+    RailsMarkup::ClientUuidMaintenance.repair!(
+      connection:,
+      table_name: RailsMarkup.config.table_name
+    )
+  end
+
+  # The expand/backfill release deliberately leaves the column nullable while
+  # old application instances may still write rows. A later contract migration
+  # adds NOT NULL only after repair + verification and old-instance shutdown.
+  def down; end
+end

data/lib/generators/rails_markup/install/templates/auth_controller.rb.erb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Base controller for Rails Markup engine.
+# Inherits host authentication from <%= options[:base_controller] %> and denies
+# access unless the conventional current_user.admin? contract is satisfied.
+# Customize authorize_rails_markup! when your application uses another policy.
+class RailsMarkupAuthController < <%= options[:base_controller] %>
+  before_action :authorize_rails_markup!
+
+  private
+
+  def authorize_rails_markup!
+    return if respond_to?(:current_user, true) && current_user&.respond_to?(:admin?) && current_user.admin?
+
+    head :forbidden
+  end
+end

data/lib/generators/rails_markup/install/templates/bin_markup.erb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rails_markup/cli"
+RailsMarkup::Cli.start(ARGV)

data/lib/generators/rails_markup/install/templates/create_rails_markup_annotations.rb.erb

@@ -0,0 +1,27 @@
+class CreateRailsMarkupAnnotations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # jsonb on PostgreSQL; json elsewhere (SQLite/MySQL have no jsonb type).
+    json_type = connection.adapter_name.downcase.include?("postgres") ? :jsonb : :json
+
+    create_table :<%= options[:table_name] %> do |t|
+      t.bigint :user_id
+      t.string :page_url, null: false
+      t.send json_type, :target, default: {}
+      t.text :content, null: false
+      t.string :intent, null: false, default: "change"
+      t.string :severity, null: false, default: "suggestion"
+      t.string :status, null: false, default: "pending"
+      t.text :selected_text
+      t.send json_type, :metadata, default: {}
+      t.send json_type, :thread, default: []
+      t.string :client_uuid, limit: 64, null: false
+
+      t.timestamps
+    end
+
+    add_index :<%= options[:table_name] %>, [:status, :created_at]
+    add_index :<%= options[:table_name] %>, :page_url
+    add_index :<%= options[:table_name] %>, :user_id
+    add_index :<%= options[:table_name] %>, :client_uuid, unique: true
+  end
+end

data/lib/generators/rails_markup/install/templates/initializer.rb.erb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+RailsMarkup.configure do |config|
+  # Base controller class for the dashboard and toolbar API. This controller
+  # must enforce authentication and authorization; a public controller makes
+  # both interfaces public. The generated controller denies non-admin users by
+  # default and is the place to integrate your host application's policy.
+  config.base_controller_class = "RailsMarkupAuthController"
+
+  # Bearer token for the external API (used by MCP production tools).
+  # Set to enable the /external/* endpoints.
+  # config.api_token = Rails.application.credentials.dig(:rails_markup, :api_token)
+
+  # Database table name (default: "rails_markup_annotations")
+  # config.table_name = "rails_markup_annotations"
+
+  # Annotations per page on the dashboard (default: 25)
+  # config.per_page = 25
+
+  # Toolbar accent color: "indigo", "amber", "blue", "emerald", "rose"
+  # config.toolbar_accent = "indigo"
+
+  # Render the annotation toolbar system at all — FAB, panel, pins, sync (default: true)
+  # config.toolbar_enabled = true
+
+  # Show the floating action button specifically. When false the FAB is hidden
+  # but pins still render and the panel stays reachable (default: true)
+  # config.fab_visible = true
+
+  # FAB button position: "bl" (bottom-left), "br" (bottom-right),
+  # "tl" (top-left), "tr" (top-right). Default: "bl"
+  # config.toolbar_position = "bl"
+
+  # FAB button size: "default" (48px), "compact" (40px), "slim" (32px)
+  # config.toolbar_size = "default"
+
+  # "Back to app" link in the dashboard header.
+  # config.return_url = "/admin"
+
+  # How to resolve the author's display name from current_user.
+  # Symbol: calls the method on the user — e.g. :name, :email, :display_name
+  # Proc: receives user, returns string — e.g. ->(u) { "#{u.first_name} #{u.last_name}" }
+  # Default: :email
+  # config.author_name_method = :name
+
+  # Callback fired after each annotation is created.
+  # Use for Slack, email, or webhook notifications.
+  # config.on_create_callback = ->(annotation) {
+  #   SlackNotifier.notify("New feedback on #{annotation.page_url}: #{annotation.content}")
+  # }
+
+  # Enable element screenshot capture in the toolbar (default: true)
+  # config.enable_screenshots = true
+end