pinnable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b167cdfced85f0afd9739517d1590c0c6d3958c525f80bdd4e5b1c0c544f8bf
+  data.tar.gz: a63ab8d983cd4c8c8710712c6828b878c668930026d5c057968fd06b95790e6e
+SHA512:
+  metadata.gz: 2c69c4ced059ab377c6d51844f640b38a34bab16af2c2d7ad5a33793dddec768a1251287cafd07eb1124dcb226a896300427203fed7a18d12daf4bea8bd6f9b3
+  data.tar.gz: d6b00982085b84adaf48eb3468c1c49a4c6dffe26c9445f3e608bc197fbdb1cb46bd66035413dab055e213f6ddbad8d86b4bc5c8d88987b7cafecbb83bf0ca57

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.0] — 2026-06-22
+
+Initial release.
+
+- Mountable Rails engine for in-app visual feedback — enable it for some users, toggle comment
+  mode, click any DOM element, leave a note.
+- **Anchoring with zero JS dependencies**: each pin stores a CSS selector, XPath, and text-quote;
+  re-resolves in order so the pin survives DOM drift, with an "unanchored" tray when it can't.
+- **Task management**: pins move open → resolved → won't-fix, stamped with resolver + timestamp.
+- **Polished, self-contained inbox** (own layout + scoped CSS), with deep-link "open on page".
+- **Reply threads** on a pin — on-page popover and inbox reply count.
+- **Host-agnostic config seam**: `enabled_for`, `current_user`, `tenant_scope`, `user_label`,
+  `parent_controller`, `layout`, `audit`, `encrypt`.
+- **Optional at-rest encryption** of `body` + `anchor` via Active Record encryption.
+- **Any database** — portable schema, no JSONB.
+- Hotwire/Stimulus, delivered via importmap merge. `pinnable:install` generator.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Vlad Mehakovic
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# Pinnable
+
+Click any element, pin a comment, work it like a task list.
+
+Pinnable is a mountable Rails engine for **in-app visual feedback**. Enable it for some users
+(superadmins, your team, a client), they flip a toggle, click **any** element on **any** page, and
+leave a note. Each note remembers *who*, *which page*, and *which element* — so it re-anchors on the
+next visit and someone else can jump straight to it. Every note is a task: open → resolved, with who
+completed it and when.
+
+It's the BugHerd/Marker.io idea, self-hosted, with your data staying in your database.
+
+- **Host-agnostic.** Your auth, your gate, your multitenancy, your audit sink — all injected through
+  one config object. The engine assumes none of it.
+- **Any database.** Portable schema (no JSONB); proven on SQLite, works on MySQL/Postgres.
+- **Hotwire/Stimulus, zero JS dependencies.** One self-contained Stimulus controller; element
+  anchoring (CSS selector → XPath → text-quote, tried in order) is hand-rolled, no vendored libs.
+- **Test-first.** Model/controller/service tests plus a headless-Chrome system test of the full
+  click-to-pin flow.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "pinnable"
+```
+
+```bash
+bundle
+bin/rails generate pinnable:install
+bin/rails pinnable:install:migrations && bin/rails db:migrate
+```
+
+Then add the widget to your layout, just before `</body>`:
+
+```erb
+<%= pinnable_widget %>
+```
+
+## Configuration
+
+`pinnable:install` writes `config/initializers/pinnable.rb`:
+
+```ruby
+Pinnable.configure do |c|
+  # The gate. Return false → the widget never renders and every endpoint 404s.
+  c.enabled_for  = ->(user) { user&.admin? }
+
+  # How to find the current user from a controller.
+  c.current_user = ->(controller) { controller.current_user }
+
+  # How a user is labelled in the inbox (no host User object is stored — only this label).
+  c.user_label   = ->(user) { user.try(:email) || 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). nil = single-tenant.
+  # c.tenant_scope = ->(controller) { controller.current_account }
+
+  # Optional: audit sink for status changes.
+  # c.audit = ->(pin, event, by) { Rails.logger.info("pinnable #{event} #{pin.public_id}") }
+
+  # Optional: encrypt body + anchor at rest (needs Active Record encryption configured).
+  # c.encrypt = true
+end
+```
+
+> **Turning encryption on later:** Active Record `encrypts` can't read rows written before it
+> was enabled, so an existing `pinnable_pins` table with plaintext rows will raise on read. Either
+> set `c.encrypt = true` from the start, or clear/re-encrypt existing rows before flipping it on
+> (`Pinnable::Pin.delete_all` in dev). Fresh installs are unaffected.
+
+## How it works
+
+- **Capture.** In comment mode a capture-phase click is intercepted (so the underlying control
+  doesn't fire) and the clicked element is recorded as three anchors — a CSS selector, an XPath, and
+  a `{ prefix, exact, suffix }` text quote — plus a percentage-relative click point.
+- **Render.** On each visit the open pins for that path are fetched and re-resolved (css → xpath →
+  text-quote, first hit wins) and drawn as numbered markers. If all three miss, the note drops into
+  an "unanchored" tray instead of being lost.
+- **Work it.** The inbox at `/pinnable` lists every pin, filterable; resolve/reopen stamps who and
+  when. A deep link (`/pinnable/pins/:id`) takes anyone to the page with that pin focused.
+
+The widget is the only host touchpoint: `<%= pinnable_widget %>`. Pins are addressed by an opaque
+`public_id`, never a raw database id.
+
+## Development
+
+```bash
+bin/rails test          # models, controllers, services, generator
+bin/rails test:system   # headless-Chrome flow (requires Chrome)
+```
+
+The dummy host app under `test/dummy` shows a minimal integration (a `User`, an
+`ApplicationController#current_user`, and the `Pinnable.configure` initializer).
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/javascripts/pinnable.js

@@ -0,0 +1,308 @@
+import { Application, Controller } from "@hotwired/stimulus"
+
+// ----------------------------------------------------------------------------
+// Anchoring — no dependencies. Each pin stores three independent anchors and we
+// re-resolve them in order (css -> xpath -> text quote); the redundancy is why a
+// "dumb" structural selector is enough. See lib/specs/069 in the host app.
+// ----------------------------------------------------------------------------
+
+const MAX_QUOTE = 80
+
+function cssPath(el) {
+  if (el.id) return `#${cssEscape(el.id)}`
+  const parts = []
+  let node = el
+  while (node && node.nodeType === 1 && node !== document.body) {
+    if (node.id) { parts.unshift(`#${cssEscape(node.id)}`); break }
+    const tag = node.tagName.toLowerCase()
+    const i = nthOfType(node)
+    parts.unshift(i ? `${tag}:nth-of-type(${i})` : tag)
+    node = node.parentElement
+  }
+  return parts.join(" > ")
+}
+
+function nthOfType(node) {
+  const siblings = Array.from(node.parentElement?.children || []).filter(n => n.tagName === node.tagName)
+  return siblings.length > 1 ? siblings.indexOf(node) + 1 : 0
+}
+
+function xpathOf(el) {
+  if (el.id) return `//*[@id=${xpathLiteral(el.id)}]`
+  const parts = []
+  let node = el
+  while (node && node.nodeType === 1 && node !== document.body) {
+    if (node.id) { parts.unshift(`*[@id=${xpathLiteral(node.id)}]`); break }
+    parts.unshift(`${node.tagName.toLowerCase()}[${sameTagIndex(node)}]`)
+    node = node.parentElement
+  }
+  return "//" + parts.join("/")
+}
+
+function sameTagIndex(node) {
+  let i = 1, sib = node
+  while ((sib = sib.previousElementSibling)) if (sib.tagName === node.tagName) i++
+  return i
+}
+
+function textQuote(el) {
+  return { exact: (el.textContent || "").trim().replace(/\s+/g, " ").slice(0, MAX_QUOTE) }
+}
+
+function captureAnchor(el, event) {
+  const r = el.getBoundingClientRect()
+  return {
+    css: cssPath(el),
+    xpath: xpathOf(el),
+    ...textQuote(el),
+    tag: el.tagName.toLowerCase(),
+    x_pct: r.width ? round((event.clientX - r.left) / r.width) : 0,
+    y_pct: r.height ? round((event.clientY - r.top) / r.height) : 0
+  }
+}
+
+function resolveAnchor(anchor) {
+  let el = null
+  try { if (anchor.css) el = document.querySelector(anchor.css) } catch (_) {}
+  if (!el && anchor.xpath) el = byXPath(anchor.xpath)
+  if (!el && anchor.exact) el = byText(anchor.exact)
+  return el
+}
+
+function byXPath(xpath) {
+  try {
+    return document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue
+  } catch (_) { return null }
+}
+
+function byText(exact) {
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT)
+  let node
+  while ((node = walker.nextNode())) {
+    if (node.closest(".pinnable")) continue
+    const text = (node.textContent || "").trim().replace(/\s+/g, " ")
+    if (node.children.length === 0 && text.includes(exact)) return node
+  }
+  return null
+}
+
+function cssEscape(s) { return window.CSS && CSS.escape ? CSS.escape(s) : s.replace(/([^\w-])/g, "\\$1") }
+function xpathLiteral(s) { return s.includes("'") ? `concat('${s.split("'").join(`',"'",'`)}')` : `'${s}'` }
+function round(n) { return Math.round(n * 1000) / 1000 }
+
+// ----------------------------------------------------------------------------
+// Controller — toggle comment mode, capture clicks, render + work pins.
+// ----------------------------------------------------------------------------
+
+class PinnableController extends Controller {
+  static values = { pinsUrl: String, markersUrl: String, currentUrl: String, focus: String, csrf: String }
+  static targets = ["toggle"]
+
+  connect() {
+    this.active = false
+    this.onClick = this.onClick.bind(this)
+    this.onMove = this.onMove.bind(this)
+    this.loadMarkers()
+  }
+
+  disconnect() { this.deactivate() }
+
+  toggle() { this.active ? this.deactivate() : this.activate() }
+
+  activate() {
+    this.active = true
+    this.toggleTarget.textContent = "💬 Comments: On"
+    this.toggleTarget.classList.add("pinnable-toggle--on")
+    document.addEventListener("click", this.onClick, true)
+    document.addEventListener("mousemove", this.onMove, true)
+  }
+
+  deactivate() {
+    this.active = false
+    if (this.hasToggleTarget) {
+      this.toggleTarget.textContent = "💬 Comments: Off"
+      this.toggleTarget.classList.remove("pinnable-toggle--on")
+    }
+    document.removeEventListener("click", this.onClick, true)
+    document.removeEventListener("mousemove", this.onMove, true)
+    this.clearHighlight()
+  }
+
+  onMove(event) {
+    const el = this.elementUnder(event)
+    if (el === this.highlighted) return
+    this.clearHighlight()
+    if (el) { this.highlighted = el; this.prevOutline = el.style.outline; el.style.outline = "2px solid #6366f1" }
+  }
+
+  clearHighlight() {
+    if (!this.highlighted) return
+    this.highlighted.style.outline = this.prevOutline || ""
+    this.highlighted = null
+  }
+
+  onClick(event) {
+    const el = this.elementUnder(event)
+    if (!el) return
+    event.preventDefault()
+    event.stopPropagation()
+    this.clearHighlight()
+    this.openComposer(el, event)
+  }
+
+  elementUnder(event) {
+    const el = event.target
+    if (!el || el.closest(".pinnable, .pinnable-composer, .pinnable-pop, .pinnable-tray, .pinnable-marker")) return null
+    return el
+  }
+
+  openComposer(el, event) {
+    this.closeComposer()
+    const anchor = captureAnchor(el, event)
+    const box = document.createElement("div")
+    box.className = "pinnable-composer"
+    box.style.left = `${event.pageX}px`
+    box.style.top = `${event.pageY}px`
+    box.innerHTML = `<textarea class="pinnable-composer__text" placeholder="Leave feedback…"></textarea>
+      <div class="pinnable-composer__actions">
+        <button type="button" class="pinnable-composer__cancel">Cancel</button>
+        <button type="button" class="pinnable-composer__save">Save</button>
+      </div>`
+    document.body.appendChild(box)
+    this.composer = box
+    box.querySelector(".pinnable-composer__text").focus()
+    box.querySelector(".pinnable-composer__cancel").addEventListener("click", () => this.closeComposer())
+    box.querySelector(".pinnable-composer__save").addEventListener("click", () => this.save(anchor, box))
+  }
+
+  closeComposer() { if (this.composer) { this.composer.remove(); this.composer = null } }
+
+  async save(anchor, box) {
+    const body = box.querySelector(".pinnable-composer__text").value.trim()
+    if (!body) return
+    const res = await this.post(this.pinsUrlValue, { pin: { url: this.currentUrlValue, body, anchor } })
+    if (!res.ok) return
+    const { public_id } = await res.json()
+    this.closeComposer()
+    this.addMarker({ public_id, body, anchor })
+  }
+
+  async loadMarkers() {
+    const res = await fetch(`${this.markersUrlValue}?url=${encodeURIComponent(this.currentUrlValue)}`, {
+      headers: { "Accept": "application/json" }
+    })
+    if (!res.ok) return
+    const pins = await res.json()
+    pins.forEach(pin => this.addMarker(pin))
+    if (this.focusValue) this.focusPin(this.focusValue)
+  }
+
+  addMarker(pin) {
+    const el = resolveAnchor(pin.anchor)
+    if (!el) return this.addUnanchored(pin)
+    const r = el.getBoundingClientRect()
+    const dot = document.createElement("button")
+    dot.type = "button"
+    dot.className = "pinnable-marker"
+    dot.dataset.pinId = pin.public_id
+    dot.style.left = `${window.scrollX + r.left + (pin.anchor.x_pct || 0) * r.width}px`
+    dot.style.top = `${window.scrollY + r.top + (pin.anchor.y_pct || 0) * r.height}px`
+    dot.textContent = "📌"
+    dot.title = pin.body
+    dot.addEventListener("click", (e) => { e.preventDefault(); this.openPopover(dot, pin) })
+    document.body.appendChild(dot)
+  }
+
+  addUnanchored(pin) {
+    let tray = document.querySelector(".pinnable-tray")
+    if (!tray) {
+      tray = document.createElement("div")
+      tray.className = "pinnable-tray"
+      tray.innerHTML = "<strong>Unanchored here</strong>"
+      document.body.appendChild(tray)
+    }
+    const item = document.createElement("button")
+    item.type = "button"
+    item.className = "pinnable-tray__item"
+    item.dataset.pinId = pin.public_id
+    item.textContent = pin.body
+    tray.appendChild(item)
+  }
+
+  openPopover(dot, pin) {
+    this.closePopover()
+    pin.comments = pin.comments || []
+    const pop = document.createElement("div")
+    pop.className = "pinnable-pop"
+    pop.style.left = dot.style.left
+    pop.style.top = `${parseFloat(dot.style.top) + 22}px`
+    pop.innerHTML = `
+      <p class="pinnable-pop__body"></p>
+      <div class="pinnable-pop__thread"></div>
+      <form class="pinnable-pop__reply">
+        <input type="text" class="pinnable-pop__input" placeholder="Reply…">
+      </form>
+      <button type="button" class="pinnable-pop__resolve">Resolve</button>`
+    pop.querySelector(".pinnable-pop__body").textContent = pin.body
+    document.body.appendChild(pop)
+    this.pop = pop
+    this.renderThread(pop, pin)
+    pop.querySelector(".pinnable-pop__resolve").addEventListener("click", () => this.resolve(pin, dot))
+    pop.querySelector(".pinnable-pop__reply").addEventListener("submit", (e) => { e.preventDefault(); this.reply(pin, pop) })
+  }
+
+  renderThread(pop, pin) {
+    const thread = pop.querySelector(".pinnable-pop__thread")
+    thread.innerHTML = ""
+    pin.comments.forEach((c) => {
+      const row = document.createElement("div")
+      row.className = "pinnable-pop__comment"
+      const who = document.createElement("span")
+      who.className = "pinnable-pop__author"
+      who.textContent = c.author_label
+      const text = document.createElement("span")
+      text.textContent = c.body
+      row.append(who, text)
+      thread.appendChild(row)
+    })
+  }
+
+  async reply(pin, pop) {
+    const input = pop.querySelector(".pinnable-pop__input")
+    const body = input.value.trim()
+    if (!body) return
+    const res = await this.post(`${this.pinsUrlValue}/${pin.public_id}/comments`, { comment: { body } })
+    if (!res.ok) return
+    const comment = await res.json()
+    pin.comments.push({ author_label: comment.author_label, body: comment.body })
+    this.renderThread(pop, pin)
+    input.value = ""
+  }
+
+  closePopover() { if (this.pop) { this.pop.remove(); this.pop = null } }
+
+  async resolve(pin, dot) {
+    const res = await this.post(`${this.pinsUrlValue}/${pin.public_id}`, { pin: { status: "resolved" } }, "PATCH")
+    if (!res.ok) return
+    this.closePopover()
+    dot.remove()
+  }
+
+  focusPin(publicId) {
+    const dot = document.querySelector(`.pinnable-marker[data-pin-id="${publicId}"]`)
+    if (!dot) return
+    dot.scrollIntoView({ block: "center", behavior: "smooth" })
+    dot.classList.add("pinnable-marker--flash")
+  }
+
+  post(url, payload, method = "POST") {
+    return fetch(url, {
+      method,
+      headers: { "Content-Type": "application/json", "Accept": "application/json", "X-CSRF-Token": this.csrfValue },
+      body: JSON.stringify(payload)
+    })
+  }
+}
+
+const application = Application.start()
+application.register("pinnable", PinnableController)

data/app/assets/stylesheets/pinnable/application.css

@@ -0,0 +1,83 @@
+/* Pinnable inbox — self-contained default styling. No framework, no host CSS.
+   Hosts override this stylesheet or the view to match their own brand. */
+
+:root {
+  --pin-accent: #6366f1;
+  --pin-ink: #0f172a;
+  --pin-muted: #64748b;
+  --pin-line: #e2e8f0;
+  --pin-bg: #f8fafc;
+}
+
+.pinnable-body {
+  margin: 0;
+  background: var(--pin-bg);
+  color: var(--pin-ink);
+  font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+}
+
+.pinnable-topbar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 14px 24px;
+  background: #fff;
+  border-bottom: 1px solid var(--pin-line);
+  font-weight: 600;
+}
+.pinnable-topbar__dot { color: var(--pin-accent); }
+
+.pinnable-wrap { max-width: 1080px; margin: 0 auto; padding: 32px 24px; }
+
+.pinnable-head { margin-bottom: 20px; }
+.pinnable-head h1 { margin: 0; font-size: 22px; font-weight: 700; }
+.pinnable-head p { margin: 4px 0 0; color: var(--pin-muted); font-size: 13px; }
+.pinnable-count {
+  display: inline-block; margin-left: 8px; padding: 1px 8px; border-radius: 999px;
+  background: #eef2ff; color: var(--pin-accent); font-size: 12px; font-weight: 600; vertical-align: middle;
+}
+
+.pinnable-flash {
+  margin-bottom: 16px; padding: 10px 14px; border-radius: 8px;
+  background: #dcfce7; color: #166534; font-size: 13px; font-weight: 500;
+}
+
+.pinnable-card {
+  background: #fff; border: 1px solid var(--pin-line); border-radius: 12px;
+  overflow: hidden; box-shadow: 0 1px 2px rgba(15, 23, 42, .04);
+}
+
+.pinnable-table { width: 100%; border-collapse: collapse; }
+.pinnable-table thead th {
+  text-align: left; padding: 11px 16px; font-size: 11px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: .04em; color: var(--pin-muted);
+  background: #f8fafc; border-bottom: 1px solid var(--pin-line);
+}
+.pinnable-table tbody td { padding: 12px 16px; border-top: 1px solid #f1f5f9; vertical-align: middle; }
+.pinnable-table tbody tr:first-child td { border-top: 0; }
+.pinnable-table tbody tr.is-done { opacity: .6; }
+.pinnable-cell-body { font-weight: 500; }
+.pinnable-replies { margin-left: 6px; font-size: 11px; font-weight: 600; color: var(--pin-muted); }
+.pinnable-cell-muted { color: var(--pin-muted); }
+.pinnable-actions { display: flex; gap: 8px; justify-content: flex-end; }
+
+.pinnable-status {
+  display: inline-block; padding: 2px 9px; border-radius: 999px;
+  font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .03em;
+}
+.pinnable-status--open { background: #fef3c7; color: #92400e; }
+.pinnable-status--resolved { background: #dcfce7; color: #166534; }
+.pinnable-status--wont_fix { background: #f1f5f9; color: #64748b; }
+
+.pinnable-btn {
+  display: inline-block; padding: 5px 12px; border-radius: 7px; cursor: pointer;
+  font-size: 12px; font-weight: 600; text-decoration: none; border: 1px solid var(--pin-line);
+  background: #fff; color: #334155;
+}
+.pinnable-btn:hover { background: #f8fafc; }
+.pinnable-btn--primary { background: var(--pin-accent); border-color: var(--pin-accent); color: #fff; }
+.pinnable-btn--primary:hover { opacity: .92; background: var(--pin-accent); }
+.pinnable-resolve { display: inline; margin: 0; }
+
+.pinnable-empty { padding: 56px 24px; text-align: center; color: var(--pin-muted); }
+.pinnable-empty strong { display: block; color: var(--pin-ink); font-size: 15px; margin-bottom: 4px; }

data/app/controllers/pinnable/application_controller.rb

@@ -0,0 +1,20 @@
+# Inherits the host's controller (via config) so it picks up the host's auth, CSRF, and
+# layout. Every Pinnable request is gated by the host-supplied `enabled_for` predicate.
+class Pinnable::ApplicationController < Pinnable.config.parent_controller.constantize
+  layout -> { Pinnable.config.layout }
+
+  before_action :require_pinnable_enabled
+
+  private
+
+  def pinnable_user = @pinnable_user ||= Pinnable.config.current_user.call(self)
+  def pinnable_tenant = @pinnable_tenant ||= Pinnable.config.tenant_scope.call(self)
+
+  # Every query starts here: pins are isolated to the host-supplied tenant (a nil tenant
+  # means single-tenant — its pins share a null scope and never leak across hosts).
+  def pinnable_pins = Pinnable::Pin.where(tenant: pinnable_tenant)
+
+  def require_pinnable_enabled
+    head :not_found unless Pinnable.config.enabled_for.call(pinnable_user)
+  end
+end

data/app/controllers/pinnable/comments_controller.rb

@@ -0,0 +1,16 @@
+module Pinnable
+  class CommentsController < ApplicationController
+    def create
+      render json: { public_id: comment.public_id, author_label: comment.author_label, body: comment.body }, status: :created
+    end
+
+    private
+
+    def comment
+      @comment ||= AddComment.new(pin:, author: pinnable_user, params: comment_params).call
+    end
+
+    def pin = pinnable_pins.find_by!(public_id: params[:pin_public_id])
+    def comment_params = params.require(:comment).permit(:body)
+  end
+end

data/app/controllers/pinnable/markers_controller.rb

@@ -0,0 +1,12 @@
+module Pinnable
+  class MarkersController < ApplicationController
+    def index
+      render json: markers
+    end
+
+    private
+
+    def markers = pins.map { |pin| MarkerSerializer.new(pin).call }
+    def pins = pinnable_pins.for_url(params[:url]).open.recent
+  end
+end

data/app/controllers/pinnable/pins_controller.rb

@@ -0,0 +1,34 @@
+module Pinnable
+  class PinsController < ApplicationController
+    def index
+      @pins = pinnable_pins.recent.includes(:comments)
+    end
+
+    def show
+      redirect_to "#{pin.url}?pinnable=#{pin.public_id}"
+    end
+
+    def create
+      render json: { public_id: captured_pin.public_id }, status: :created
+    end
+
+    def update
+      ResolvePin.new(pin:, by: pinnable_user, status: status_param).call
+      respond_to do |format|
+        format.json { head :no_content }                                  # the on-page widget
+        format.html { redirect_to pins_path, notice: "Feedback updated." } # the inbox
+      end
+    end
+
+    private
+
+    def captured_pin
+      @captured_pin ||= CapturePin.new(author: pinnable_user, tenant: pinnable_tenant, params: pin_params).call
+    end
+
+    def pin = @pin ||= pinnable_pins.find_by!(public_id: params[:public_id])
+
+    def pin_params = params.require(:pin).permit(:url, :body, anchor: {})
+    def status_param = params.require(:pin).permit(:status).fetch(:status)
+  end
+end

data/app/helpers/pinnable/application_helper.rb

@@ -0,0 +1,4 @@
+module Pinnable
+  module ApplicationHelper
+  end
+end

data/app/helpers/pinnable/widget_helper.rb

@@ -0,0 +1,11 @@
+module Pinnable
+  # The single host-facing entry point: drop `<%= pinnable_widget %>` in the layout.
+  # Renders nothing unless the host's gate says this user may give feedback.
+  module WidgetHelper
+    def pinnable_widget
+      return unless Pinnable.config.enabled_for.call(Pinnable.config.current_user.call(controller))
+
+      render "pinnable/widget"
+    end
+  end
+end

data/app/jobs/pinnable/application_job.rb

@@ -0,0 +1,4 @@
+module Pinnable
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/pinnable/application_mailer.rb

@@ -0,0 +1,6 @@
+module Pinnable
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/pinnable/application_record.rb

@@ -0,0 +1,5 @@
+module Pinnable
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end