RubyGems - redpen-rails - Versions diffs - 0.1.0 - Mend

redpen-rails 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +5 -0
data/MIT-LICENSE +20 -0
data/README.md +89 -0
data/Rakefile +6 -0
data/app/assets/javascripts/redpen.js +200 -0
data/app/assets/stylesheets/redpen.css +117 -0
data/app/controllers/redpen/application_controller.rb +23 -0
data/app/controllers/redpen/notes_controller.rb +37 -0
data/app/controllers/redpen/resolutions_controller.rb +24 -0
data/app/helpers/redpen/rail_helper.rb +21 -0
data/app/models/redpen/application_record.rb +5 -0
data/app/models/redpen/current.rb +6 -0
data/app/models/redpen/note.rb +28 -0
data/app/views/redpen/notes/_form.html.erb +15 -0
data/app/views/redpen/notes/_note.html.erb +26 -0
data/app/views/redpen/notes/_rail.html.erb +9 -0
data/app/views/redpen/notes/_standalone.html.erb +6 -0
data/app/views/redpen/notes/index.html.erb +22 -0
data/config/importmap.rb +2 -0
data/config/routes.rb +6 -0
data/db/migrate/20260915000001_create_redpen_notes.rb +17 -0
data/lib/generators/redpen/install/install_generator.rb +34 -0
data/lib/generators/redpen/install/templates/initializer.rb +12 -0
data/lib/generators/redpen/views/views_generator.rb +15 -0
data/lib/redpen/engine.rb +33 -0
data/lib/redpen/host_route_helpers.rb +34 -0
data/lib/redpen/version.rb +3 -0
data/lib/redpen-rails.rb +1 -0
data/lib/redpen.rb +29 -0
metadata +133 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39dd26115a7ab4e0acfeda34e39d2a3f663d441d3f7301985df839bc1bef8889
+  data.tar.gz: be286165894bce577539b1ab7438f2b9041d8c90771a9cc535b310a5616f1552
+SHA512:
+  metadata.gz: 9db7f16ee197699140d766ea670df403bc51c24065e3ba1d618a92a2bd052df93c77158eaaf4e5d5dd6332f64d6ed9dd86a4ed215cbf15443570b89a389baecf
+  data.tar.gz: 1ca4e0ff51280541db1c08eb9928f32890acee01d177b6492f18ac5ed80ecb7ad692e2506cda6f96a583577f584977514fce5d95c77f82cee1d7a168345d8e6a

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,5 @@
+# Changelog
+## 0.1.0 — 2026-09-16
+First extraction, from nityesh.com. Notes pinned to elements by path + CSS selector, a pen UI as one Stimulus controller, resolve/reopen as a resolution resource, `redpen_rail` and `redpen_inject` helpers, `redpen:install` and `redpen:views` generators. Sprockets and Propshaft, import maps only.

data/MIT-LICENSE ADDED Viewed

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+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 ADDED Viewed

@@ -0,0 +1,89 @@
+# Red pen
+Click any element of a page, say what should change. The feedback layer for AI-made pages, as a Rails engine.
+A note is not a chat message. It carries **where** on the page (the path and a CSS selector), **what was there** (a text snippet), and **what should change** (the note). That is exactly what a model, or a person, needs to make a surgical edit without seeing the page. The host app reads open notes, does the work, and resolves each with one line that shows up under the note on the page.
+The gem captures. The app decides. No auth, no AI, no page model.
+## Install
+```ruby
+# Gemfile
+gem "redpen-rails"
+```
+```sh
+bin/rails generate redpen:install   # migration, initializer, mount line
+bin/rails db:migrate
+```
+```ruby
+# config/initializers/redpen.rb
+Redpen.author = -> { Current.user }                      # or current_user with Devise
+Redpen.annotatable = ->(path, author) { true }           # who may pen which path
+```
+```erb
+<%# app/views/layouts/application.html.erb, last child of <body> %>
+<%= redpen_rail if signed_in? %>
+```
+That's the install. Signed in, every page has a "Red pen" pill bottom-right. Click it, click an element, type, save. A numbered pin lands on the element. Click a pin to read the note, resolve it, reopen it, or delete it. Readers get nothing: no markup, no stylesheet, no JavaScript.
+## The two questions
+Both lambdas run inside the engine's controller, so anything a controller can see works in them.
+| | Asked | Default |
+|---|---|---|
+| `Redpen.author` | Who is holding the pen? Becomes every note's author. Nil means 403. | `-> { nil }` |
+| `Redpen.annotatable` | May this author pen this path? Asked once per request, about that path. | `->(path, author) { true }` |
+Notes are read **by path**, not by author. Two admins of one page see the same notes; the author column is attribution.
+`Redpen.parent_controller` (default `"ApplicationController"`) is what the engine's controllers inherit from, so your authentication runs first.
+## Reading notes back
+```ruby
+Redpen::Note.open.on("/communities/42/")   # path, selector, snippet, body
+note.resolve("Cut the headline to six words.")
+note.reopen
+```
+If the host has an agent or an MCP server, it writes its own tool over these two verbs. Scope it through whatever owns the page, never `Redpen::Note.all`: in a multi-tenant app that would hand one tenant every other tenant's notes.
+## Documents served verbatim
+For a page with its own `<head>` and no layout, splice the rail in at serve time:
+```ruby
+render html: helpers.redpen_inject(document).html_safe, layout: false
+```
+## Restyling
+Every colour and font is a CSS variable (`--rp-paper`, `--rp-red`, `--rp-mono`, …). Set them on `:root` in your own stylesheet; the gem's defaults sit in a cascade layer, so yours win whatever the load order. For deeper changes, `bin/rails generate redpen:views` copies the templates into `app/views/redpen/notes`, where they take precedence.
+## Pins that survive rewrites
+A pin follows its selector, and the selector short-circuits at the nearest ancestor with an `id`. If a generator stamps ids on block elements and preserves them on revision, pins survive a full rewrite. When a selector no longer matches, the snippet re-anchors the note to the same kind of element whose text still starts the same way. When nothing matches, the note lands in an "Element gone" panel with its snippet, still readable and resolvable.
+## Requirements and non-goals
+Rails 8.0+, import maps (importmap-rails), Turbo and Stimulus. Sprockets and Propshaft both work. Not in v1: esbuild/webpack hosts, threads on notes, visitor comments, generating or hosting pages.
+## Development
+```sh
+bundle install
+bin/rails db:migrate
+bin/rails test                                          # models, controllers, integration
+bin/rails test test/system                              # a headless Chrome clicks the pen
+BUNDLE_GEMFILE=gemfiles/sprockets.gemfile bin/rails test
+```
+## License
+MIT. Extracted from [nityesh.com](https://nityesh.com), first hosted for real by [Curated Connections](https://curatedconnections.io).

data/Rakefile ADDED Viewed

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

data/app/assets/javascripts/redpen.js ADDED Viewed

@@ -0,0 +1,200 @@
+// The red pen, in one module. Pulled in by the rail alone, so a page without the rail never
+// asks for it. Imports Turbo because on a verbatim document the host's own entry never runs;
+// on a page that already has Turbo the import map hands back the same module.
+//
+// The controller knows nothing about notes: it pins whatever carries a data-note-selector,
+// captures a clicked element into two hidden fields, and submits a form. Everything the
+// server needs travels in the form; everything the page needs to show comes back as HTML.
+// Pin coordinates are never stored. They're measured from the element on every pin().
+import "@hotwired/turbo-rails"
+import { Application, Controller } from "@hotwired/stimulus"
+class RedpenController extends Controller {
+  static targets = [ "toggle", "toggleLabel", "highlight", "layer", "notes", "note", "orphans",
+                     "composer", "composerTarget", "selector", "snippet", "body" ]
+  connect() {
+    this.hover = this.hover.bind(this)
+    this.capture = this.capture.bind(this)
+  }
+  disconnect() {
+    this.deactivate()
+  }
+  // ---- pins -------------------------------------------------------------------------
+  pin() {
+    if (!this.hasLayerTarget) return
+    this.layerTarget.querySelectorAll(".redpen-pin").forEach(pin => pin.remove())
+    const orphanList = this.orphansTarget.querySelector("ol")
+    orphanList.replaceChildren()
+    let number = 0
+    for (const note of this.noteTargets) {
+      const element = this.resolve(note.dataset.noteSelector, note.dataset.noteSnippet)
+      note.querySelector(".redpen-note__number").textContent = ++number
+      if (element) {
+        this.notesTarget.appendChild(note)
+        this.layerTarget.appendChild(this.pinFor(note, element, number))
+      } else {
+        orphanList.appendChild(note)
+      }
+    }
+    this.orphansTarget.toggleAttribute("data-populated", orphanList.children.length > 0)
+  }
+  pinFor(note, element, number) {
+    const pin = document.createElement("button")
+    pin.type = "button"
+    pin.className = "redpen-pin"
+    pin.textContent = number
+    pin.title = note.querySelector(".redpen-note__body").textContent
+    if (note.classList.contains("redpen-note--resolved")) pin.classList.add("redpen-pin--resolved")
+    const { x, y } = this.documentPoint(element.getBoundingClientRect())
+    pin.style.left = `${x - 12}px`
+    pin.style.top = `${y - 12}px`
+    pin.addEventListener("click", event => { event.stopPropagation(); this.open(note, pin) })
+    return pin
+  }
+  // The selector first. When the page has been rewritten under the note, the snippet:
+  // the same kind of element whose text still starts the way it did.
+  resolve(selector, snippet) {
+    try { const element = document.querySelector(selector); if (element) return element } catch {}
+    if (!snippet || snippet.length < 12) return null
+    const tag = selector.split(">").pop().trim().split(":")[0]
+    const candidates = document.querySelectorAll(tag.startsWith("#") ? "*" : tag)
+    let match = null
+    for (const element of candidates) {
+      if (element.closest(".redpen") || !this.textOf(element).startsWith(snippet)) continue
+      if (!match || element.textContent.length < match.textContent.length) match = element
+    }
+    return match
+  }
+  open(note, anchor) {
+    this.close()
+    const rect = anchor.getBoundingClientRect()
+    this.place(note, rect.right + 8, rect.top)
+  }
+  // ---- pen mode ---------------------------------------------------------------------
+  toggle() {
+    this.element.hasAttribute("data-redpen-active") ? this.deactivate() : this.activate()
+  }
+  activate() {
+    this.close()
+    this.element.setAttribute("data-redpen-active", "")
+    this.toggleLabelTarget.textContent = "Click an element"
+    document.addEventListener("pointermove", this.hover, true)
+    document.addEventListener("click", this.capture, true)
+  }
+  deactivate() {
+    this.element.removeAttribute("data-redpen-active")
+    if (this.hasToggleLabelTarget) this.toggleLabelTarget.textContent = "Red pen"
+    if (this.hasHighlightTarget) this.highlightTarget.removeAttribute("data-visible")
+    document.removeEventListener("pointermove", this.hover, true)
+    document.removeEventListener("click", this.capture, true)
+  }
+  hover(event) {
+    const element = this.targetOf(event)
+    if (!element) { this.highlightTarget.removeAttribute("data-visible"); return }
+    const rect = element.getBoundingClientRect()
+    Object.assign(this.highlightTarget.style, {
+      left: `${rect.left}px`, top: `${rect.top}px`, width: `${rect.width}px`, height: `${rect.height}px`
+    })
+    this.highlightTarget.setAttribute("data-visible", "")
+  }
+  capture(event) {
+    const element = this.targetOf(event)
+    if (!element) return
+    event.preventDefault()
+    event.stopPropagation()
+    this.deactivate()
+    const snippet = this.textOf(element).slice(0, 120)
+    this.selectorTarget.value = this.cssPath(element)
+    this.snippetTarget.value = snippet
+    this.composerTargetTarget.textContent = snippet || `<${element.tagName.toLowerCase()}>`
+    this.bodyTarget.value = ""
+    this.place(this.composerTarget, event.clientX + 12, event.clientY + 12)
+    this.bodyTarget.focus()
+  }
+  // The page's own elements only, never our UI. The body counts: a note on the body is
+  // a note on the whole page ("add a testimonials section").
+  targetOf(event) {
+    const element = event.target
+    if (!(element instanceof Element)) return null
+    if (element.closest(".redpen")) return null
+    if (element === document.documentElement) return null
+    return element
+  }
+  submit(event) {
+    event.preventDefault()
+    this.composerTarget.requestSubmit()
+  }
+  close() {
+    for (const open of this.element.querySelectorAll("[data-open]")) open.removeAttribute("data-open")
+  }
+  stop(event) {
+    event.stopPropagation()
+  }
+  keydown(event) {
+    if (event.key === "Escape") { this.deactivate(); this.close() }
+  }
+  // ---- geometry ---------------------------------------------------------------------
+  // Viewport point → coordinates inside the layer, whatever positions the layer.
+  documentPoint({ left, top }) {
+    const origin = this.layerTarget.getBoundingClientRect()
+    return { x: left - origin.left, y: top - origin.top }
+  }
+  place(box, clientX, clientY) {
+    box.setAttribute("data-open", "")
+    const width = box.offsetWidth, height = box.offsetHeight
+    const clientLeft = Math.max(8, Math.min(clientX, window.innerWidth - width - 8))
+    const clientTop = Math.max(8, Math.min(clientY, window.innerHeight - height - 8))
+    const { x, y } = this.documentPoint({ left: clientLeft, top: clientTop })
+    box.style.left = `${x}px`
+    box.style.top = `${y}px`
+  }
+  // ---- text and selector ------------------------------------------------------------
+  textOf(element) {
+    return (element.textContent || "").replace(/\s+/g, " ").trim()
+  }
+  // Up from the element to the nearest id, or to the body. An id short-circuits the
+  // chain, which is what lets a pin survive a rewrite of everything around it.
+  cssPath(element) {
+    const parts = []
+    let node = element
+    while (node && node.nodeType === 1 && node !== document.body && node !== document.documentElement) {
+      if (node.id) { parts.unshift(`#${CSS.escape(node.id)}`); break }
+      const siblings = Array.from(node.parentNode?.children || []).filter(sibling => sibling.tagName === node.tagName)
+      const index = siblings.indexOf(node) + 1
+      parts.unshift(`${node.tagName.toLowerCase()}:nth-of-type(${index})`)
+      node = node.parentNode
+    }
+    if (!parts.length || !parts[0].startsWith("#")) parts.unshift("body")
+    return parts.join(" > ")
+  }
+}
+// The pen's own Stimulus application. A host's application, if any, ignores the
+// "redpen" identifier the way this one ignores the host's.
+Application.start().register("redpen", RedpenController)

data/app/assets/stylesheets/redpen.css ADDED Viewed

@@ -0,0 +1,117 @@
+/* The red pen. Carries its own tokens and never leans on the host's stylesheet. The
+   defaults live in a cascade layer, so a host's own `:root { --rp-red: ... }` wins no
+   matter which stylesheet loads last. Everything sits above the page (z-index) and
+   outside its flow (display: contents on the frame). */
+@layer redpen {
+  :root {
+    --rp-paper: #fbf6ea;
+    --rp-paper-deep: #efe6d2;
+    --rp-ink: #2b2620;
+    --rp-ink-soft: #5c5347;
+    --rp-line: #d9cdb4;
+    --rp-red: #b05c34;
+    --rp-red-deep: #96491f;
+    --rp-mono: ui-monospace, Menlo, Consolas, monospace;
+    --rp-shadow: 0 6px 24px rgba(43, 38, 32, .22);
+    --rp-radius: 8px;
+  }
+}
+.redpen { display: contents; }
+.redpen *, .redpen *::before, .redpen *::after { box-sizing: border-box; }
+html:has(.redpen[data-redpen-active]) body { cursor: crosshair; }
+/* Toggle pill, bottom-right. */
+.redpen-toggle {
+  position: fixed; right: 18px; bottom: 18px; z-index: 2147483001;
+  display: inline-flex; align-items: center; gap: 8px;
+  padding: 9px 14px; border-radius: 999px;
+  border: 1px solid var(--rp-red-deep); background: var(--rp-paper); color: var(--rp-red-deep);
+  font: 500 12px/1 var(--rp-mono); letter-spacing: .04em; text-transform: uppercase;
+  cursor: pointer; box-shadow: var(--rp-shadow);
+}
+.redpen-toggle:hover { background: var(--rp-paper-deep); }
+.redpen[data-redpen-active] .redpen-toggle { background: var(--rp-red); border-color: var(--rp-red); color: var(--rp-paper); }
+.redpen-toggle__dot { width: 8px; height: 8px; border-radius: 50%; background: currentColor; }
+/* Hover box while picking an element. */
+.redpen-highlight {
+  position: fixed; z-index: 2147482900; pointer-events: none; display: none;
+  border: 2px solid var(--rp-red); border-radius: 3px; background: color-mix(in srgb, var(--rp-red) 10%, transparent);
+}
+.redpen-highlight[data-visible] { display: block; }
+/* Document-coordinate layer for pins, popovers and the composer. */
+.redpen-layer { position: absolute; top: 0; left: 0; width: 0; height: 0; overflow: visible; z-index: 2147482950; }
+.redpen-notes { list-style: none; margin: 0; padding: 0; }
+.redpen-pin {
+  position: absolute; width: 24px; height: 24px; padding: 0;
+  border-radius: 50% 50% 50% 2px; border: 1px solid var(--rp-red-deep);
+  background: var(--rp-red); color: var(--rp-paper);
+  font: 700 11px/1 var(--rp-mono); display: flex; align-items: center; justify-content: center;
+  cursor: pointer; box-shadow: 0 1px 6px rgba(43, 38, 32, .35);
+}
+.redpen-pin:hover { background: var(--rp-red-deep); }
+.redpen-pin--resolved { background: var(--rp-paper-deep); color: var(--rp-ink-soft); border-color: var(--rp-line); }
+/* A note: hidden until a pin opens it (popover) or it lands in the orphans panel (row). */
+.redpen-note {
+  display: none; width: 280px; max-width: calc(100vw - 16px);
+  padding: 12px; border: 1px solid var(--rp-line); border-radius: var(--rp-radius);
+  background: var(--rp-paper); color: var(--rp-ink); box-shadow: var(--rp-shadow);
+  font: 400 13px/1.5 var(--rp-mono);
+}
+.redpen-layer .redpen-note[data-open] { display: block; position: absolute; z-index: 2147483002; }
+.redpen-note__head { display: flex; gap: 8px; align-items: baseline; margin-bottom: 8px; color: var(--rp-ink-soft); font-size: 11px; }
+.redpen-note__number { flex: none; color: var(--rp-red-deep); font-weight: 700; }
+.redpen-note__number::before { content: "#"; }
+.redpen-note__snippet { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; font-style: italic; }
+.redpen-note__body { margin: 0 0 8px; white-space: pre-wrap; word-break: break-word; }
+.redpen-note__resolution { margin: 0 0 8px; padding: 8px; border-radius: 5px; background: var(--rp-paper-deep); font-size: 12px; }
+.redpen-note__label { display: block; color: var(--rp-red-deep); font-size: 10px; letter-spacing: .06em; text-transform: uppercase; margin-bottom: 3px; }
+.redpen-note__meta { font-size: 10px; color: var(--rp-ink-soft); }
+.redpen-note--resolved .redpen-note__body { color: var(--rp-ink-soft); }
+.redpen-note__actions { display: flex; gap: 6px; justify-content: flex-end; margin-top: 8px; }
+.redpen-note__actions form { margin: 0; }
+.redpen-btn {
+  padding: 5px 10px; border-radius: 5px; border: 1px solid var(--rp-line);
+  background: var(--rp-paper); color: var(--rp-ink); font: 500 11px/1 var(--rp-mono); cursor: pointer;
+}
+.redpen-btn:hover { background: var(--rp-paper-deep); }
+.redpen-btn--primary { background: var(--rp-red); border-color: var(--rp-red-deep); color: var(--rp-paper); }
+.redpen-btn--primary:hover { background: var(--rp-red-deep); }
+.redpen-btn--quiet { border-color: transparent; color: var(--rp-ink-soft); }
+/* Composer: the new-note form, placed where the author clicked. */
+.redpen-composer {
+  display: none; position: absolute; z-index: 2147483002; width: 280px; max-width: calc(100vw - 16px);
+  padding: 12px; border: 1px solid var(--rp-line); border-radius: var(--rp-radius);
+  background: var(--rp-paper); box-shadow: var(--rp-shadow); font: 400 13px/1.5 var(--rp-mono);
+}
+.redpen-composer[data-open] { display: block; }
+.redpen-composer__target { margin-bottom: 8px; color: var(--rp-ink-soft); font-size: 11px; font-style: italic; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.redpen-composer textarea {
+  display: block; width: 100%; resize: vertical; margin: 0; padding: 8px;
+  border: 1px solid var(--rp-line); border-radius: 5px; background: #fff; color: var(--rp-ink);
+  font: 400 13px/1.5 var(--rp-mono); outline: none;
+}
+.redpen-composer textarea:focus { border-color: var(--rp-red); }
+/* Orphans: notes whose element no longer exists. Visible only when populated. */
+.redpen-orphans {
+  display: none; position: fixed; right: 18px; bottom: 64px; z-index: 2147483001;
+  width: 300px; max-height: 50vh; overflow: auto; padding: 10px;
+  border: 1px solid var(--rp-line); border-radius: var(--rp-radius); background: var(--rp-paper); box-shadow: var(--rp-shadow);
+}
+.redpen-orphans[data-populated] { display: block; }
+.redpen-orphans__title { margin: 0 0 8px; color: var(--rp-red-deep); font: 700 10px/1 var(--rp-mono); letter-spacing: .08em; text-transform: uppercase; }
+.redpen-orphans .redpen-note { display: block; width: auto; box-shadow: none; margin-bottom: 8px; }
+@media (max-width: 640px) {
+  .redpen-toggle { right: 12px; bottom: 12px; }
+  .redpen-orphans { right: 12px; left: 12px; width: auto; }
+}

data/app/controllers/redpen/application_controller.rb ADDED Viewed

@@ -0,0 +1,23 @@
+module Redpen
+  # Inherits from the host's controller so its before_actions run first; then asks the
+  # host the two questions. Every request here is about one path, and the gate is asked
+  # once, about that path. Reads are by path, never by author: two admins of one page
+  # see the same notes.
+  class ApplicationController < Redpen.parent_controller.constantize
+    include HostRouteHelpers
+    # The index answers a <turbo-frame> inside the host's page; a layout would nest one.
+    layout false
+    before_action :set_author, :authorize_path
+    private
+      def set_author
+        Current.author = instance_exec(&Redpen.author)
+      end
+      def authorize_path
+        head :forbidden unless Current.author && instance_exec(path, Current.author, &Redpen.annotatable)
+      end
+  end
+end

data/app/controllers/redpen/notes_controller.rb ADDED Viewed

@@ -0,0 +1,37 @@
+module Redpen
+  # The notes on one page. Every write redirects back to the index, which is the whole
+  # rail: pins, popovers, the composer. One renderer, so a note looks the same whether
+  # it arrived with the page or a second ago.
+  class NotesController < ApplicationController
+    def index
+      @notes = notes.ordered
+    end
+    def create
+      notes.create!(note_params)
+      redirect_to notes_path(path: path), status: :see_other
+    end
+    def destroy
+      note.destroy
+      redirect_to notes_path(path: path), status: :see_other
+    end
+    private
+      def notes
+        Note.on(path)
+      end
+      def note
+        @note ||= Note.find(params[:id])
+      end
+      def path
+        @path ||= params[:path].presence || params.dig(:note, :path).presence || note.path
+      end
+      def note_params
+        params.expect(note: %i[ path selector snippet body ])
+      end
+  end
+end

data/app/controllers/redpen/resolutions_controller.rb ADDED Viewed

@@ -0,0 +1,24 @@
+module Redpen
+  # Resolving a note is a noun with a lifecycle, not a verb on the note: create resolves,
+  # destroy reopens. A host's agent calls the same model verb.
+  class ResolutionsController < ApplicationController
+    def create
+      note.resolve(params[:resolution])
+      redirect_to notes_path(path: path), status: :see_other
+    end
+    def destroy
+      note.reopen
+      redirect_to notes_path(path: path), status: :see_other
+    end
+    private
+      def note
+        @note ||= Note.find(params[:note_id])
+      end
+      def path
+        note.path
+      end
+  end
+end

data/app/helpers/redpen/rail_helper.rb ADDED Viewed

@@ -0,0 +1,21 @@
+module Redpen
+  module RailHelper
+    # The pen on a page the host lays out. One line in the layout, for whoever may pen:
+    #
+    #   <%= redpen_rail if signed_in? %>
+    #
+    # Render it as the last child of <body>: an ancestor with transform or overflow
+    # would clip the pins.
+    def redpen_rail(path: request.path)
+      render "redpen/notes/rail", path: path
+    end
+    # The pen on a document the host serves verbatim, with its own <head> and no layout.
+    # Splices the rail before </body>, or appends it when the document has none. From a
+    # controller: `render html: helpers.redpen_inject(document).html_safe, layout: false`.
+    def redpen_inject(document, path: request.path)
+      rail = render("redpen/notes/standalone", path: path)
+      document.match?(%r{</body>}i) ? document.sub(%r{</body>}i) { "#{rail}</body>" } : document + rail
+    end
+  end
+end

data/app/models/redpen/application_record.rb ADDED Viewed

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

data/app/models/redpen/current.rb ADDED Viewed

@@ -0,0 +1,6 @@
+module Redpen
+  # Who is holding the pen this request, answered once by Redpen.author.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :author
+  end
+end

data/app/models/redpen/note.rb ADDED Viewed

@@ -0,0 +1,28 @@
+module Redpen
+  # A note pinned to one element of one page: "this runs long", "swap this image". The
+  # page is its path and the element is a CSS selector, nothing else identifies them, so
+  # the same table serves any page a host renders and the pin lands wherever the element
+  # is when the page next paints. The snippet is what the element said at the time, for
+  # re-anchoring and for whoever reads the note without the page in front of them.
+  class Note < ApplicationRecord
+    belongs_to :author, polymorphic: true, default: -> { Current.author }
+    validates :path, :selector, :body, presence: true
+    validates :path, format: { with: %r{\A/\S*\z}, message: "must be a site path" }
+    scope :open,     -> { where(resolved_at: nil) }
+    scope :resolved, -> { where.not(resolved_at: nil) }
+    scope :on,       ->(path) { where(path: path) }
+    scope :ordered,  -> { order(:created_at) }
+    def resolve(resolution = nil)
+      update!(resolved_at: Time.current, resolution: resolution.presence)
+    end
+    def reopen
+      update!(resolved_at: nil, resolution: nil)
+    end
+    def resolved? = resolved_at.present?
+  end
+end

data/app/views/redpen/notes/_form.html.erb ADDED Viewed

@@ -0,0 +1,15 @@
+<%# The composer. Hidden until the controller captures a click, which fills the selector
+    and snippet fields; the author only ever types the body. A plain Rails form: Turbo
+    submits it and the redirect repaints the frame. %>
+<%= form_with model: note, class: "redpen-composer", data: { redpen_target: "composer" } do |form| %>
+  <%= form.hidden_field :path %>
+  <%= form.hidden_field :selector, data: { redpen_target: "selector" } %>
+  <%= form.hidden_field :snippet,  data: { redpen_target: "snippet" } %>
+  <div class="redpen-composer__target" data-redpen-target="composerTarget"></div>
+  <%= form.text_area :body, required: true, rows: 3, placeholder: "What should change here?",
+        data: { redpen_target: "body", action: "keydown.meta+enter->redpen#submit keydown.ctrl+enter->redpen#submit" } %>
+  <div class="redpen-note__actions">
+    <button type="button" class="redpen-btn redpen-btn--quiet" data-action="redpen#close">Cancel</button>
+    <%= form.submit "Save", class: "redpen-btn redpen-btn--primary" %>
+  </div>
+<% end %>

data/app/views/redpen/notes/_note.html.erb ADDED Viewed

@@ -0,0 +1,26 @@
+<%# One note: the popover a pin opens, and the row an orphan shows as. The selector and
+    snippet on the element are what the controller pins by: the DOM attribute is the state. %>
+<li id="<%= dom_id note %>" class="redpen-note <%= "redpen-note--resolved" if note.resolved? %>"
+    data-redpen-target="note" data-note-selector="<%= note.selector %>" data-note-snippet="<%= note.snippet %>"
+    data-action="click->redpen#stop">
+  <div class="redpen-note__head">
+    <span class="redpen-note__number"></span>
+    <span class="redpen-note__snippet" title="<%= note.snippet %>"><%= note.snippet.presence || note.selector %></span>
+  </div>
+  <p class="redpen-note__body"><%= note.body %></p>
+  <% if note.resolved? %>
+    <p class="redpen-note__resolution">
+      <span class="redpen-note__label">Resolved <%= time_ago_in_words(note.resolved_at) %> ago</span>
+      <% if note.resolution.present? %><span><%= note.resolution %></span><% end %>
+    </p>
+  <% end %>
+  <div class="redpen-note__meta"><%= note.created_at.strftime("%-d %b %Y, %H:%M") %></div>
+  <div class="redpen-note__actions">
+    <%= button_to "Delete", note_path(note), method: :delete, class: "redpen-btn redpen-btn--quiet", form: { data: { turbo_confirm: "Delete this note?" } } %>
+    <% if note.resolved? %>
+      <%= button_to "Reopen", note_resolution_path(note), method: :delete, class: "redpen-btn" %>
+    <% else %>
+      <%= button_to "Resolve", note_resolution_path(note), method: :post, class: "redpen-btn redpen-btn--primary" %>
+    <% end %>
+  </div>
+</li>

data/app/views/redpen/notes/_rail.html.erb ADDED Viewed

@@ -0,0 +1,9 @@
+<%# The red pen. The frame pulls the page's notes after the page paints, so the page
+    itself carries only this: a stylesheet link, a module tag, an empty frame. The
+    controller lives on the frame, which survives every re-render of its contents. %>
+<%= stylesheet_link_tag "redpen" %>
+<%= javascript_import_module_tag "redpen" %>
+<turbo-frame id="redpen_notes" src="<%= redpen.notes_path(path: path) %>" class="redpen"
+             data-controller="redpen"
+             data-action="turbo:frame-load->redpen#pin resize@window->redpen#pin keydown@document->redpen#keydown">
+</turbo-frame>

data/app/views/redpen/notes/_standalone.html.erb ADDED Viewed

@@ -0,0 +1,6 @@
+<%# Spliced before </body> of a verbatim document. It has no head of ours, so the rail
+    brings the import map along, and Turbo Drive is switched off: the document's links
+    and scripts were written for a plain browser, and the frame works without Drive. %>
+<%= javascript_inline_importmap_tag %>
+<script type="module">import { Turbo } from "@hotwired/turbo-rails"; Turbo.session.drive = false</script>
+<%= render "redpen/notes/rail", path: path %>

data/app/views/redpen/notes/index.html.erb ADDED Viewed

@@ -0,0 +1,22 @@
+<turbo-frame id="redpen_notes">
+  <button type="button" class="redpen-toggle" data-action="redpen#toggle" data-redpen-target="toggle">
+    <span class="redpen-toggle__dot"></span>
+    <span data-redpen-target="toggleLabel">Red pen</span>
+  </button>
+  <div class="redpen-highlight" data-redpen-target="highlight" aria-hidden="true"></div>
+  <%# Document-coordinate layer: pins, open popovers and the composer are positioned in here. %>
+  <div class="redpen-layer" data-redpen-target="layer">
+    <ol class="redpen-notes" data-redpen-target="notes">
+      <%= render partial: "redpen/notes/note", collection: @notes %>
+    </ol>
+    <%= render "redpen/notes/form", note: Redpen::Note.new(path: @path) %>
+  </div>
+  <%# Notes whose element is gone from the page. Filled by the controller at pin time. %>
+  <aside class="redpen-orphans" data-redpen-target="orphans">
+    <h3 class="redpen-orphans__title">Element gone</h3>
+    <ol class="redpen-notes"></ol>
+  </aside>
+</turbo-frame>

data/config/importmap.rb ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ # The rail imports the entry; no page preloads it, so a reader's <head> never mentions it.
2	+ pin "redpen", to: "redpen.js", preload: false

data/config/routes.rb ADDED Viewed

@@ -0,0 +1,6 @@
+Redpen::Engine.routes.draw do
+  # Notes on a page, and resolving one: create resolves, destroy reopens. No verbs.
+  resources :notes, only: %i[ index create destroy ] do
+    resource :resolution, only: %i[ create destroy ]
+  end
+end

data/db/migrate/20260915000001_create_redpen_notes.rb ADDED Viewed

@@ -0,0 +1,17 @@
+class CreateRedpenNotes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :redpen_notes do |t|
+      # Attribution only: who left the note. Polymorphic so any host user class fits,
+      # and no foreign key so the engine never assumes a table name.
+      t.references :author, polymorphic: true, null: false
+      # The page is its path; the element is a CSS selector into it.
+      t.string :path, null: false, index: true
+      t.string :selector, null: false
+      t.string :snippet
+      t.text :body, null: false
+      t.datetime :resolved_at
+      t.text :resolution
+      t.timestamps
+    end
+  end
+end

data/lib/generators/redpen/install/install_generator.rb ADDED Viewed

@@ -0,0 +1,34 @@
+module Redpen
+  module Generators
+    # bin/rails generate redpen:install
+    #
+    # Migration, initializer, mount line. Idempotent: run it twice and nothing doubles.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      def copy_migrations
+        rake "redpen:install:migrations"
+      end
+      def create_initializer
+        template "initializer.rb", "config/initializers/redpen.rb"
+      end
+      def mount_engine
+        route 'mount Redpen::Engine, at: "/redpen"' unless File.read("config/routes.rb").include?("Redpen::Engine")
+      end
+      def show_next_steps
+        say <<~MSG
+          Red pen is installed. Three things left:
+            1. bin/rails db:migrate
+            2. Open config/initializers/redpen.rb and say who holds the pen.
+            3. Put <%= redpen_rail if signed_in? %> as the last line of <body> in your layout.
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/redpen/install/templates/initializer.rb ADDED Viewed

@@ -0,0 +1,12 @@
+# Who is holding the pen. Evaluated inside the engine's controller, so anything a
+# controller can see works here: Current.user, current_user (Devise), a session lookup.
+# Nil means nobody is signed in, and the pen answers 403.
+Redpen.author = -> { Current.user }
+# May this author pen this path? Called with the page path and the author. Default: any
+# signed-in author, on any path. Narrow it to whoever owns the page:
+#
+#   Redpen.annotatable = ->(path, author) { Community.at(path)&.administered_by?(author) }
+# The engine's controllers inherit from this, so your authentication runs first.
+# Redpen.parent_controller = "ApplicationController"

data/lib/generators/redpen/views/views_generator.rb ADDED Viewed

@@ -0,0 +1,15 @@
+module Redpen
+  module Generators
+    # bin/rails generate redpen:views
+    #
+    # Copies the pen's templates into app/views/redpen/notes, where they take precedence
+    # over the engine's. For colours and fonts, override the --rp-* variables instead.
+    class ViewsGenerator < Rails::Generators::Base
+      source_root Redpen::Engine.root.join("app/views")
+      def copy_views
+        directory "redpen/notes", "app/views/redpen/notes"
+      end
+    end
+  end
+end

data/lib/redpen/engine.rb ADDED Viewed

@@ -0,0 +1,33 @@
+module Redpen
+  class Engine < ::Rails::Engine
+    isolate_namespace Redpen
+    # One prebuilt module and one stylesheet. Sprockets needs telling; Propshaft
+    # already serves everything on its paths.
+    initializer "redpen.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.precompile += %w[ redpen.js redpen.css ]
+      end
+    end
+    # `pin "redpen"` lands in the host's import map without the host editing anything.
+    initializer "redpen.importmap", before: "importmap" do |app|
+      if 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
+    # The host's own route helpers keep working inside the engine's controllers.
+    initializer "redpen.host_route_helpers" do |app|
+      ActiveSupport.on_load(:after_routes_loaded) do
+        Redpen::HostRouteHelpers.define_from(app.routes, Redpen::Engine.routes)
+      end
+    end
+    # `redpen_rail` and `redpen_inject` in every host view and controller.
+    initializer "redpen.helpers" do
+      ActiveSupport.on_load(:action_controller_base) { helper Redpen::RailHelper }
+    end
+  end
+end

data/lib/redpen/host_route_helpers.rb ADDED Viewed

@@ -0,0 +1,34 @@
+module Redpen
+  # Route helpers of the host app that the engine doesn't define itself, routed through main_app.
+  #
+  # The engine's controllers inherit from the host's (see Redpen.parent_controller), so host
+  # code such as a before_action redirecting to new_session_path runs inside the engine, where
+  # route helpers resolve against the engine's routes and raise UrlGenerationError. For every
+  # helper the host has and the engine doesn't, this defines a method delegating to the host's
+  # routes, so that code keeps working unchanged. The pattern is Mission Control Jobs' (MIT,
+  # 37signals).
+  #
+  # Helpers both define, like root_path, keep resolving to the engine's; use main_app.root_path.
+  module HostRouteHelpers
+    class << self
+      def define_from(host_routes, engine_routes)
+        undefine_all
+        (host_routes.named_routes.helper_names - engine_routes.named_routes.helper_names).each do |name|
+          define_method(name) { |*args| main_app.public_send(name, *args) }
+          defined_helpers << name
+        end
+      end
+      private
+        def undefine_all
+          defined_helpers.each { |name| remove_method(name) }
+          defined_helpers.clear
+        end
+        def defined_helpers
+          @defined_helpers ||= []
+        end
+    end
+  end
+end

data/lib/redpen/version.rb ADDED Viewed

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

data/lib/redpen-rails.rb ADDED Viewed

	@@ -0,0 +1 @@
1	+ require "redpen"

data/lib/redpen.rb ADDED Viewed

@@ -0,0 +1,29 @@
+require "importmap-rails"
+require "turbo-rails"
+require "stimulus-rails"
+require "redpen/version"
+require "redpen/host_route_helpers"
+require "redpen/engine"
+# The red pen asks the host app two questions and nothing else. Both lambdas run inside
+# the engine's controller, so anything a controller can see works in them: Current.user,
+# Devise's current_user, a session lookup.
+module Redpen
+  # Who is holding the pen. Its answer becomes every note's author and is handed to
+  # `annotatable`. Nil means nobody is signed in, and the engine answers 403.
+  #
+  #   Redpen.author = -> { Current.user }
+  #   Redpen.author = -> { current_user }        # Devise
+  mattr_accessor :author, default: -> { nil }
+  # May this author pen this path? Called with the page path and the author for every
+  # request that reads or writes notes on that path. Default: any signed-in author, anywhere.
+  #
+  #   Redpen.annotatable = ->(path, author) { Community.at(path)&.administered_by?(author) }
+  mattr_accessor :annotatable, default: ->(path, author) { true }
+  # The engine's controllers inherit from this, so the host's own before_actions
+  # (authentication, Current.session, locale) run before the pen looks at a request.
+  mattr_accessor :parent_controller, default: "ApplicationController"
+end

metadata ADDED Viewed

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: redpen-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nityesh Agarwal
+- Luo Ji
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: 'A Rails engine that lets a signed-in person pin notes to elements of
+  any page: where on the page, what was there, what should change. Notes are read
+  back by the host app (or its agent), resolved with one line, and the line shows
+  up on the page.'
+email:
+- nityeshagarwal@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/redpen.js
+- app/assets/stylesheets/redpen.css
+- app/controllers/redpen/application_controller.rb
+- app/controllers/redpen/notes_controller.rb
+- app/controllers/redpen/resolutions_controller.rb
+- app/helpers/redpen/rail_helper.rb
+- app/models/redpen/application_record.rb
+- app/models/redpen/current.rb
+- app/models/redpen/note.rb
+- app/views/redpen/notes/_form.html.erb
+- app/views/redpen/notes/_note.html.erb
+- app/views/redpen/notes/_rail.html.erb
+- app/views/redpen/notes/_standalone.html.erb
+- app/views/redpen/notes/index.html.erb
+- config/importmap.rb
+- config/routes.rb
+- db/migrate/20260915000001_create_redpen_notes.rb
+- lib/generators/redpen/install/install_generator.rb
+- lib/generators/redpen/install/templates/initializer.rb
+- lib/generators/redpen/views/views_generator.rb
+- lib/redpen-rails.rb
+- lib/redpen.rb
+- lib/redpen/engine.rb
+- lib/redpen/host_route_helpers.rb
+- lib/redpen/version.rb
+homepage: https://github.com/nityeshaga/redpen
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nityeshaga/redpen
+  source_code_uri: https://github.com/nityeshaga/redpen
+  changelog_uri: https://github.com/nityeshaga/redpen/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Click any element of a page, leave a note. The feedback layer for AI-made
+  pages.
+test_files: []