pinnable 0.1.0

data/app/models/pinnable/comment/encryption.rb

@@ -0,0 +1,8 @@
+module Pinnable::Comment::Encryption
+  extend ActiveSupport::Concern
+
+  # Same opt-in as Pin — a reply can quote PII too.
+  included do
+    encrypts :body if Pinnable.config.encrypt
+  end
+end

data/app/models/pinnable/comment/relationships.rb

@@ -0,0 +1,8 @@
+module Pinnable::Comment::Relationships
+  extend ActiveSupport::Concern
+
+  included do
+    belongs_to :pin, class_name: "Pinnable::Pin", inverse_of: :comments
+    belongs_to :author, polymorphic: true, optional: true
+  end
+end

data/app/models/pinnable/comment/validations.rb

@@ -0,0 +1,7 @@
+module Pinnable::Comment::Validations
+  extend ActiveSupport::Concern
+
+  included do
+    validates :body, presence: true
+  end
+end

data/app/models/pinnable/comment.rb

@@ -0,0 +1,9 @@
+module Pinnable
+  class Comment < ApplicationRecord
+    has_secure_token :public_id
+
+    include Comment::Relationships
+    include Comment::Validations
+    include Comment::Encryption
+  end
+end

data/app/models/pinnable/pin/encryption.rb

@@ -0,0 +1,9 @@
+module Pinnable::Pin::Encryption
+  extend ActiveSupport::Concern
+
+  # Opt-in: hosts set `config.encrypt = true` (and configure Active Record encryption).
+  # Read at load — declared after `serialize :anchor`, so encryption wraps the JSON coder.
+  included do
+    encrypts :body, :anchor if Pinnable.config.encrypt
+  end
+end

data/app/models/pinnable/pin/relationships.rb

@@ -0,0 +1,10 @@
+module Pinnable::Pin::Relationships
+  extend ActiveSupport::Concern
+
+  included do
+    belongs_to :author, polymorphic: true, optional: true
+    belongs_to :tenant, polymorphic: true, optional: true
+    belongs_to :resolved_by, polymorphic: true, optional: true
+    has_many :comments, class_name: "Pinnable::Comment", dependent: :destroy, inverse_of: :pin
+  end
+end

data/app/models/pinnable/pin/scopes.rb

@@ -0,0 +1,8 @@
+module Pinnable::Pin::Scopes
+  extend ActiveSupport::Concern
+
+  included do
+    scope :for_url, ->(url) { where(url:) }
+    scope :recent, -> { order(created_at: :desc) }
+  end
+end

data/app/models/pinnable/pin/transitions.rb

@@ -0,0 +1,7 @@
+module Pinnable::Pin::Transitions
+  extend ActiveSupport::Concern
+
+  included do
+    enum :status, { open: 0, resolved: 1, wont_fix: 2 }, default: :open
+  end
+end

data/app/models/pinnable/pin/validations.rb

@@ -0,0 +1,17 @@
+module Pinnable::Pin::Validations
+  extend ActiveSupport::Concern
+
+  included do
+    validates :url, presence: true
+    validates :body, presence: true
+    validate :anchor_within_limit
+  end
+
+  private
+
+  def anchor_within_limit
+    return if anchor.to_json.bytesize <= Pinnable.config.anchor_max_bytes
+
+    errors.add(:anchor, "is too large")
+  end
+end

data/app/models/pinnable/pin.rb

@@ -0,0 +1,12 @@
+module Pinnable
+  class Pin < ApplicationRecord
+    has_secure_token :public_id
+    serialize :anchor, coder: JSON, type: Hash
+
+    include Pin::Relationships
+    include Pin::Validations
+    include Pin::Scopes
+    include Pin::Transitions
+    include Pin::Encryption
+  end
+end

data/app/serializers/pinnable/marker_serializer.rb

@@ -0,0 +1,27 @@
+module Pinnable
+  # The wire shape the in-page overlay reads: enough to re-anchor (anchor blob) and to
+  # show the note, never the host's User object — only its captured label.
+  class MarkerSerializer
+    def initialize(pin) = @pin = pin
+
+    def call
+      {
+        public_id: pin.public_id,
+        url: pin.url,
+        body: pin.body,
+        status: pin.status,
+        author_label: pin.author_label,
+        anchor: pin.anchor,
+        comments: comments
+      }
+    end
+
+    private
+
+    attr_reader :pin
+
+    def comments
+      pin.comments.order(:created_at).map { |c| { author_label: c.author_label, body: c.body } }
+    end
+  end
+end

data/app/services/pinnable/add_comment.rb

@@ -0,0 +1,22 @@
+module Pinnable
+  # Appends a reply to a pin, stamping the author's display label like CapturePin does.
+  class AddComment
+    def initialize(pin:, author:, params:)
+      @pin = pin
+      @author = author
+      @params = params
+    end
+
+    def call
+      pin.comments.create!(
+        author:,
+        author_label: Pinnable.config.user_label.call(author),
+        body: params[:body]
+      )
+    end
+
+    private
+
+    attr_reader :pin, :author, :params
+  end
+end

data/app/services/pinnable/capture_pin.rb

@@ -0,0 +1,28 @@
+module Pinnable
+  # Turns a capture payload into a persisted Pin, stamping the author's display label
+  # (resolved through the host's `user_label`) so the inbox never needs the host's User.
+  class CapturePin
+    def initialize(author:, tenant:, params:)
+      @author = author
+      @tenant = tenant
+      @params = params
+    end
+
+    def call
+      Pin.create!(
+        author:,
+        tenant:,
+        author_label: Pinnable.config.user_label.call(author),
+        url: params[:url],
+        body: params[:body],
+        anchor:
+      )
+    end
+
+    private
+
+    attr_reader :author, :tenant, :params
+
+    def anchor = (params[:anchor] || {}).to_h
+  end
+end

data/app/services/pinnable/resolve_pin.rb

@@ -0,0 +1,32 @@
+module Pinnable
+  # Moves a pin along its task lifecycle (open -> resolved/wont_fix and back), stamping
+  # who completed it and when, then emitting the host's audit event. Reopening clears
+  # the completion stamps so the task reads as live again.
+  class ResolvePin
+    COMPLETED = %w[resolved wont_fix].freeze
+
+    def initialize(pin:, by:, status:)
+      @pin = pin
+      @by = by
+      @status = status.to_s
+    end
+
+    def call
+      pin.update!(status:, **completion)
+      Pinnable.config.audit.call(pin, status.to_sym, by)
+      pin
+    end
+
+    private
+
+    attr_reader :pin, :by, :status
+
+    def completion
+      return { resolved_by: nil, resolved_by_label: nil, resolved_at: nil } unless completed?
+
+      { resolved_by: by, resolved_by_label: Pinnable.config.resolver_label.call(by), resolved_at: Time.current }
+    end
+
+    def completed? = COMPLETED.include?(status)
+  end
+end

data/app/views/layouts/pinnable/application.html.erb

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Feedback · Pinnable</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+  <%= yield :head %>
+  <%= stylesheet_link_tag "pinnable/application", media: "all" %>
+</head>
+<body class="pinnable-body">
+  <header class="pinnable-topbar">
+    <span class="pinnable-topbar__dot">📌</span> Pinnable
+  </header>
+
+  <main class="pinnable-wrap">
+    <% if flash[:notice] %>
+      <div class="pinnable-flash"><%= flash[:notice] %></div>
+    <% end %>
+    <%= yield %>
+  </main>
+</body>
+</html>

data/app/views/pinnable/_widget.html.erb

@@ -0,0 +1,61 @@
+<div
+  class="pinnable"
+  data-controller="pinnable"
+  data-pinnable-pins-url-value="<%= pinnable.pins_path %>"
+  data-pinnable-markers-url-value="<%= pinnable.markers_path %>"
+  data-pinnable-current-url-value="<%= request.path %>"
+  data-pinnable-focus-value="<%= params[:pinnable] %>"
+  data-pinnable-csrf-value="<%= form_authenticity_token %>"
+>
+  <button
+    type="button"
+    class="pinnable-toggle"
+    data-pinnable-target="toggle"
+    data-action="pinnable#toggle"
+  >💬 Comments: Off</button>
+</div>
+
+<%= javascript_import_module_tag "pinnable" %>
+
+<style>
+  .pinnable-toggle {
+    position: fixed; right: 16px; bottom: 16px; z-index: 2147483000;
+    padding: 8px 14px; border: 0; border-radius: 999px; cursor: pointer;
+    background: #1f2937; color: #fff; font: 500 13px system-ui, sans-serif;
+    box-shadow: 0 2px 8px rgba(0,0,0,.25);
+  }
+  .pinnable-toggle--on { background: #6366f1; }
+  .pinnable-composer {
+    position: absolute; z-index: 2147483001; width: 240px; padding: 10px;
+    background: #fff; border: 1px solid #d1d5db; border-radius: 8px;
+    box-shadow: 0 6px 20px rgba(0,0,0,.18); font: 13px system-ui, sans-serif;
+  }
+  .pinnable-composer__text { width: 100%; min-height: 64px; box-sizing: border-box; resize: vertical; }
+  .pinnable-composer__actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 8px; }
+  .pinnable-composer__actions button { cursor: pointer; padding: 4px 10px; border-radius: 6px; border: 1px solid #d1d5db; background: #f9fafb; }
+  .pinnable-composer__save { background: #6366f1 !important; color: #fff; border-color: #6366f1 !important; }
+  .pinnable-marker {
+    position: absolute; z-index: 2147483000; transform: translate(-50%, -50%);
+    width: 22px; height: 22px; padding: 0; border: 0; border-radius: 50%;
+    background: #6366f1; color: #fff; font-size: 12px; line-height: 22px; cursor: pointer;
+    box-shadow: 0 1px 4px rgba(0,0,0,.3);
+  }
+  .pinnable-marker--flash { outline: 3px solid #f59e0b; outline-offset: 2px; }
+  .pinnable-pop {
+    position: absolute; z-index: 2147483001; width: 220px; padding: 10px;
+    background: #fff; border: 1px solid #d1d5db; border-radius: 8px;
+    box-shadow: 0 6px 20px rgba(0,0,0,.18); font: 13px system-ui, sans-serif;
+  }
+  .pinnable-pop__resolve { cursor: pointer; margin-top: 8px; padding: 4px 10px; border-radius: 6px; border: 1px solid #6366f1; background: #6366f1; color: #fff; }
+  .pinnable-pop__thread { margin: 8px 0 6px; max-height: 140px; overflow-y: auto; }
+  .pinnable-pop__comment { font-size: 12px; line-height: 1.4; margin: 4px 0; }
+  .pinnable-pop__author { font-weight: 600; margin-right: 4px; color: #4338ca; }
+  .pinnable-pop__reply { margin: 6px 0 0; }
+  .pinnable-pop__input { width: 100%; box-sizing: border-box; padding: 5px 8px; border: 1px solid #d1d5db; border-radius: 6px; font: 12px system-ui, sans-serif; }
+  .pinnable-tray {
+    position: fixed; left: 16px; bottom: 16px; z-index: 2147483000; max-width: 260px;
+    padding: 10px; background: #fff; border: 1px solid #d1d5db; border-radius: 8px;
+    box-shadow: 0 2px 8px rgba(0,0,0,.2); font: 12px system-ui, sans-serif;
+  }
+  .pinnable-tray__item { display: block; width: 100%; text-align: left; cursor: pointer; margin-top: 6px; background: #f9fafb; border: 1px solid #e5e7eb; border-radius: 6px; padding: 4px 8px; }
+</style>

data/app/views/pinnable/pins/index.html.erb

@@ -0,0 +1,66 @@
+<section class="pinnable-inbox">
+  <div class="pinnable-head">
+    <h1>Feedback<% if @pins.any? %><span class="pinnable-count"><%= @pins.size %></span><% end %></h1>
+    <p>Comments left across the app. Open one to jump back to the exact element it was pinned on.</p>
+  </div>
+
+  <% if @pins.empty? %>
+    <div class="pinnable-card">
+      <div class="pinnable-empty">
+        <strong>No feedback yet</strong>
+        Toggle comment mode on any page, then click an element to leave the first note.
+      </div>
+    </div>
+  <% else %>
+    <div class="pinnable-card">
+      <table class="pinnable-table">
+        <thead>
+          <tr>
+            <th>Comment</th>
+            <th>Page</th>
+            <th>By</th>
+            <th>Status</th>
+            <th>When</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @pins.each do |pin| %>
+            <tr class="<%= "is-done" unless pin.open? %>">
+              <td class="pinnable-cell-body">
+                <%= pin.body %>
+                <% if pin.comments.any? %><span class="pinnable-replies">💬 <%= pin.comments.size %></span><% end %>
+              </td>
+              <td class="pinnable-cell-muted"><%= pin.url %></td>
+              <td class="pinnable-cell-muted"><%= pin.author_label %></td>
+              <td><span class="pinnable-status pinnable-status--<%= pin.status %>"><%= pin.status.tr("_", " ") %></span></td>
+              <td class="pinnable-cell-muted"><%= time_ago_in_words(pin.created_at) %> ago</td>
+              <td>
+                <div class="pinnable-actions">
+                  <%= link_to "Open on page", pin_path(pin.public_id), class: "pinnable-btn" %>
+                  <% if pin.open? %>
+                    <%=
+                      button_to "Resolve", pin_path(pin.public_id),
+                        method: :patch,
+                        params: { pin: { status: "resolved" } },
+                        form_class: "pinnable-resolve",
+                        class: "pinnable-btn pinnable-btn--primary"
+                    %>
+                  <% else %>
+                    <%=
+                      button_to "Reopen", pin_path(pin.public_id),
+                        method: :patch,
+                        params: { pin: { status: "open" } },
+                        form_class: "pinnable-resolve",
+                        class: "pinnable-btn"
+                    %>
+                  <% end %>
+                </div>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+</section>

data/config/importmap.rb

@@ -0,0 +1,3 @@
+# Single self-contained entrypoint. It imports only "@hotwired/stimulus" (which the
+# host already pins), so there are no further pins to resolve.
+pin "pinnable", to: "pinnable.js", preload: true

data/config/routes.rb

@@ -0,0 +1,7 @@
+Pinnable::Engine.routes.draw do
+  resources :pins, only: %i[index show create update], param: :public_id do
+    resources :comments, only: :create
+  end
+  root to: "pins#index"
+  resources :markers, only: :index
+end

data/db/migrate/20260101000010_create_pinnable_pins.rb

@@ -0,0 +1,37 @@
+# Portable types only (string/text/integer/datetime) — no JSONB — so the engine runs
+# identically on SQLite, MySQL, and Postgres. The anchor blob is JSON-serialized text.
+# author/tenant/resolved_by are polymorphic with string id columns to tolerate any host
+# primary-key type (bigint or uuid).
+class CreatePinnablePins < ActiveRecord::Migration[8.0]
+  def change
+    create_table :pinnable_pins do |t|
+      t.string :public_id, null: false
+
+      t.string :author_type
+      t.string :author_id
+      t.string :author_label
+
+      t.string :tenant_type
+      t.string :tenant_id
+
+      t.string :url, null: false
+      t.text :body
+      t.text :anchor
+
+      t.integer :status, null: false, default: 0
+      t.string :resolved_by_type
+      t.string :resolved_by_id
+      t.string :resolved_by_label
+      t.datetime :resolved_at
+
+      t.string :user_agent
+
+      t.timestamps
+    end
+
+    add_index :pinnable_pins, :public_id, unique: true
+    add_index :pinnable_pins, %i[tenant_type tenant_id]
+    add_index :pinnable_pins, :url
+    add_index :pinnable_pins, :status
+  end
+end

data/db/migrate/20260101000030_create_pinnable_comments.rb

@@ -0,0 +1,17 @@
+# Replies on a pin — the conversation thread. Portable types; body encrypts at rest when
+# the host opts into config.encrypt (it can quote PII just like a pin body).
+class CreatePinnableComments < ActiveRecord::Migration[8.0]
+  def change
+    create_table :pinnable_comments do |t|
+      t.references :pin, null: false, foreign_key: { to_table: :pinnable_pins }
+      t.string :public_id, null: false
+      t.string :author_type
+      t.string :author_id
+      t.string :author_label
+      t.text :body
+      t.timestamps
+    end
+
+    add_index :pinnable_comments, :public_id, unique: true
+  end
+end

data/lib/generators/pinnable/install/install_generator.rb

@@ -0,0 +1,27 @@
+require "rails/generators/base"
+
+module Pinnable
+  module Generators
+    # `rails generate pinnable:install` — drops the config initializer and mounts the
+    # engine. Migrations are installed separately via `rails pinnable:install:migrations`
+    # (the standard engine task), kept out of here so the schema stays single-sourced.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "pinnable.rb", "config/initializers/pinnable.rb"
+      end
+
+      def mount_engine
+        route 'mount Pinnable::Engine => "/pinnable"'
+      end
+
+      def show_post_install
+        say ""
+        say "Pinnable installed. Two steps left:", :green
+        say "  1. bin/rails pinnable:install:migrations && bin/rails db:migrate"
+        say "  2. Add <%= pinnable_widget %> to your layout, just before </body>."
+      end
+    end
+  end
+end

data/lib/generators/pinnable/install/templates/pinnable.rb

@@ -0,0 +1,23 @@
+# Pinnable configuration. Everything app-specific lives here; the engine assumes none of it.
+Pinnable.configure do |c|
+  # The gate. Return false and the widget never renders and every endpoint 404s.
+  c.enabled_for = ->(user) { user&.admin? }
+
+  # How to find the current user from a controller (whatever your auth uses).
+  c.current_user = ->(controller) { controller.current_user }
+
+  # How to label a user in the inbox. No host User object is stored — only this label.
+  c.user_label = ->(user) { user.try(:email) || user.try(:name) || user.to_s }
+
+  # Engine controllers inherit this, picking up your auth, CSRF, and layout.
+  c.parent_controller = "ApplicationController"
+
+  # Optional: scope pins to a tenant (account/org). Return nil for a single-tenant app.
+  # c.tenant_scope = ->(controller) { controller.current_account }
+
+  # Optional: a sink for status changes (open -> resolved/wont_fix and back).
+  # c.audit = ->(pin, event, by) { Rails.logger.info("pinnable #{event} #{pin.public_id}") }
+
+  # Optional: encrypt body + anchor at rest (requires Active Record encryption configured).
+  # c.encrypt = true
+end

data/lib/pinnable/configuration.rb

@@ -0,0 +1,22 @@
+module Pinnable
+  # The single seam between the engine and its host. Defaults are safe-off: with no
+  # configuration the widget never renders and every endpoint 404s, so a host opts in
+  # deliberately rather than by accident.
+  class Configuration
+    attr_accessor :enabled_for, :current_user, :tenant_scope, :user_label,
+      :resolver_label, :parent_controller, :encrypt, :audit, :anchor_max_bytes, :layout
+
+    def initialize
+      @enabled_for       = ->(_user) { false }                 # the gate
+      @current_user      = ->(_controller) { nil }             # host's auth
+      @tenant_scope      = ->(_controller) { nil }             # optional multitenancy
+      @user_label        = ->(user) { user.try(:email) || user.try(:name) || user.to_s }
+      @resolver_label    = @user_label
+      @parent_controller = "ActionController::Base"            # inherit host auth/CSRF/layout
+      @encrypt           = false                               # opt-in AR encryption of body/anchor
+      @audit             = ->(_pin, _event, _by) {}            # optional sink
+      @anchor_max_bytes  = 50_000
+      @layout            = "pinnable/application"          # host sets its own for native chrome
+    end
+  end
+end

data/lib/pinnable/engine.rb

@@ -0,0 +1,20 @@
+module Pinnable
+  class Engine < ::Rails::Engine
+    isolate_namespace Pinnable
+
+    # Expose the host-facing helper (`<%= pinnable_widget %>`) in the host's views,
+    # regardless of the host's `include_all_helpers` setting.
+    initializer "pinnable.helpers" do
+      ActiveSupport.on_load(:action_controller_base) { helper Pinnable::WidgetHelper }
+    end
+
+    # Merge the engine's pins into the host import map so `import "pinnable"` resolves.
+    # No-op on hosts that don't use importmap-rails (they include the asset themselves).
+    initializer "pinnable.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+  end
+end

data/lib/pinnable/version.rb

@@ -0,0 +1,3 @@
+module Pinnable
+  VERSION = "0.1.0"
+end

data/lib/pinnable.rb

@@ -0,0 +1,17 @@
+require "pinnable/version"
+require "pinnable/configuration"
+require "pinnable/engine"
+
+# Pinnable — a host-agnostic, mountable visual-feedback layer. Enable it for some
+# users, flip a toggle, click any element on any page, leave a note. Notes remember
+# who/where/which-element, re-anchor on reload, and are worked like a task list.
+#
+# Everything the host differs on — auth, the gate, multitenancy, the audit sink — is
+# injected through `Pinnable.config`, so the engine carries no app-specific coupling.
+module Pinnable
+  class << self
+    def config = @config ||= Configuration.new
+    def configure = yield config
+    def reset_config! = @config = Configuration.new
+  end
+end

data/lib/tasks/pinnable_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :pinnable do
+#   # Task goes here
+# end