plumbo 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e37ee057af091dc00bb62836449ce4cd80c903ca6153507c68825efbf589a4c4
-  data.tar.gz: 773e4b2b5def7b84992e3fa0a09517c619f39f1dd8548c3c1d587d8597289c50
+  metadata.gz: a9d835f22037aca3f59bd7784b5b53f0df96d6f357058f7fee0feb2960fdd2dc
+  data.tar.gz: 046c9e808514912b46a1db902f5b4eaee0cc24505161461bf2f8a70559ce15c0
 SHA512:
-  metadata.gz: 86bd0dccd19d772f0c31e313d3858ed9a9b923f6fd66bf18908a9a6614d307c2adb3825d632bbb51168bd398cdcec275dce7abf00d6cd894d2c2f71503e082a2
-  data.tar.gz: eee1962f2bff1cb3f1a6a02921c4e2d4d1f1285b43e952dcde62218c8018c8b380ad2321a1a78c9ec9b7342bc057342082748a65b79f89f816957fd5ad376ecf
+  metadata.gz: b7e38789548920e3de8e6a02bb461cba040a68440e71b133049ca6761df508a00d4aa6287f59dc73cb19e7064a1ac14b9ed1db7cb821055338559caccf4364a4
+  data.tar.gz: c4ec8aa1b0181cef27a1955dc220aa9051bdd59c71cfc8fb131d6c08bda3147392eec9bd3da1a7018aa60092636cd79f2caa7b475a2bdefeb0fe376b23af80f0

data/README.md

@@ -31,6 +31,9 @@ showing how many files rendered the current page.
   and Stimulus controllers nested (and color-coded) under their parent.
 - **Collapse or expand** a parent by clicking its row; **copy** a single path with
   its copy icon, or **Copy All** for the whole (filtered) list.
+- **Hover a row** to highlight the part of the page that file rendered — a partial
+  used in a loop lights up every instance. Rows with no on-page output (controllers,
+  helpers, JavaScript) simply don't highlight.
 - **Filter** by typing in the search box, or click a type chip — Controllers,
   Views, Partials, Stimulus, … — to show just one kind.
 - **Clear All** empties the list so you can watch fresh files appear as you click
@@ -49,6 +52,7 @@ Plumbo.configure do |c|
   c.max_files        = 500                     # safety cap on listed files
   c.include_stimulus = true                    # list Stimulus controllers
   c.javascript_root  = "app/javascript"        # source dir Stimulus paths map into
+  c.highlight        = true                     # highlight a file's region on hover
 end
 ```
 
@@ -65,6 +69,13 @@ every response carries an `X-Plumbo-Files` header that the panel reads on each
 > detected — those emitted by helpers or ViewComponents, and other JavaScript,
 > aren't listed.
 
+Hover highlighting reuses Rails' built-in
+`annotate_rendered_view_with_filenames`, which Plumbo enables in development so each
+rendered template and partial is wrapped in `<!-- BEGIN … -->`/`<!-- END … -->`
+comments. The panel reads those markers to locate a file's output on the page. This
+adds the comments to your development HTML; set `c.highlight = false` to leave the
+markup untouched (the panel still lists files, just without hover highlighting).
+
 ## Notes
 
 - Production-safe: disabled outside development by default.

data/lib/plumbo/configuration.rb

@@ -18,6 +18,13 @@ module Plumbo
     # in the rendered HTML. Defaults to true.
     attr_accessor :include_stimulus
 
+    # Whether hovering a view/partial/layout row highlights its rendered region
+    # on the page. Defaults to true. When on, Plumbo enables Rails' built-in
+    # annotate_rendered_view_with_filenames so the rendered HTML carries the
+    # BEGIN/END comment markers the highlight reads. Turn off to leave the host
+    # app's HTML untouched (highlighting then does nothing).
+    attr_accessor :highlight
+
     # Source directory Stimulus controllers are mapped into. Combined with the
     # "controllers/" subdirectory and the Stimulus identifier to form the path.
     attr_accessor :javascript_root
@@ -29,6 +36,7 @@ module Plumbo
       @max_files = 500
       @path_prefix = "@"
       @include_stimulus = true
+      @highlight = true
       @javascript_root = "app/javascript"
       @root = nil
     end

data/lib/plumbo/panel.rb

@@ -94,8 +94,9 @@ module Plumbo
       #plumbo .plumbo-chip{flex:none;white-space:nowrap;color:#9ca3af;background:rgba(255,255,255,.05);border:1px solid rgba(255,255,255,.1);border-radius:9999px;padding:2px 8px;font-size:10px}
       #plumbo .plumbo-chip:hover{background:rgba(255,255,255,.1);color:#fff}
       #plumbo .plumbo-chip[aria-pressed="true"]{background:#2563eb;border-color:#2563eb;color:#fff}
-      #plumbo .plumbo-list{flex:1;min-height:0;list-style:none;margin:0;padding:0;overflow-y:auto;background:#0b1220}
-      #plumbo .plumbo-row{--d:0;display:flex;align-items:center;gap:8px;width:100%;padding:7px 16px;padding-left:calc(16px + var(--d) * 14px);color:#d1d5db;text-align:left;cursor:default;background-image:repeating-linear-gradient(to right,rgba(255,255,255,.09) 0,rgba(255,255,255,.09) 1px,transparent 1px,transparent 14px);background-repeat:no-repeat;background-position:20px 0;background-size:calc(var(--d) * 14px) 100%}
+      #plumbo .plumbo-list{flex:1;min-height:0;list-style:none;margin:0;padding:0;overflow:auto;background:#0b1220;scrollbar-width:none}
+      #plumbo .plumbo-list::-webkit-scrollbar{display:none}
+      #plumbo .plumbo-row{--d:0;display:flex;align-items:center;gap:8px;width:max-content;min-width:100%;padding:7px 16px;padding-left:calc(16px + var(--d) * 14px);color:#d1d5db;text-align:left;cursor:default;background-image:repeating-linear-gradient(to right,rgba(255,255,255,.09) 0,rgba(255,255,255,.09) 1px,transparent 1px,transparent 14px);background-repeat:no-repeat;background-position:20px 0;background-size:calc(var(--d) * 14px) 100%}
       #plumbo .plumbo-row:hover{background-color:rgba(255,255,255,.05);color:#fff}
       #plumbo .plumbo-row.plumbo-parent{cursor:pointer}
       #plumbo .plumbo-caret{flex:none;width:12px;display:flex;color:#6b7280}
@@ -105,9 +106,9 @@ module Plumbo
       #plumbo .plumbo-row.plumbo-parent:hover .plumbo-caret{color:#fff}
       #plumbo .plumbo-type{flex:none;display:flex;color:#6b7280}
       #plumbo .plumbo-row:hover .plumbo-type{color:#9ca3af}
-      #plumbo .plumbo-path{flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
-      #plumbo .plumbo-copy{margin-left:auto;flex:none;color:#4b5563;display:flex;cursor:pointer}
-      #plumbo .plumbo-row:hover .plumbo-copy{color:#9ca3af}
+      #plumbo .plumbo-path{flex:none;white-space:nowrap}
+      #plumbo .plumbo-copy{position:sticky;right:16px;margin-left:auto;flex:none;color:#4b5563;display:flex;cursor:pointer;padding-left:20px;background:linear-gradient(to right,rgba(11,18,32,0),#0b1220 16px)}
+      #plumbo .plumbo-row:hover .plumbo-copy{color:#9ca3af;background:linear-gradient(to right,rgba(23,30,43,0),#171e2b 16px)}
       #plumbo .plumbo-row[data-depth="1"] .plumbo-path{color:#93c5fd}
       #plumbo .plumbo-row[data-depth="1"] .plumbo-type{color:#60a5fa}
       #plumbo .plumbo-row[data-depth="2"] .plumbo-path{color:#c4b5fd}
@@ -120,6 +121,7 @@ module Plumbo
       #plumbo .plumbo-row[data-depth="5"] .plumbo-type{color:#f472b6}
       #plumbo .plumbo-flash{color:#4ade80}
       #plumbo svg{display:block}
+      .plumbo-hl{position:fixed;z-index:2147482000;pointer-events:none;background:rgba(59,130,246,.18);outline:2px solid #3b82f6;outline-offset:-1px;border-radius:2px}
     CSS
 
     JS = <<~JS.freeze
@@ -163,7 +165,7 @@ module Plumbo
           }
           else if (hit.hasAttribute("data-plumbo-clear")) {
             var emptied = root.querySelector("#plumbo-list");
-            if (emptied) { emptied.innerHTML = ""; refresh(); }
+            if (emptied) { emptied.innerHTML = ""; clearHighlight(); refresh(); }
           }
           else if (hit.hasAttribute("data-plumbo-chip")) {
             var cat = hit.getAttribute("data-category");
@@ -290,6 +292,75 @@ module Plumbo
           if (html) { list.insertAdjacentHTML("beforeend", html); }
           refresh();
         }
+        // Hover-to-highlight: map a panel row back to the region(s) it rendered.
+        // Relies on Rails' annotate_rendered_view_with_filenames, which wraps each
+        // template/partial in `<!-- BEGIN path -->`/`<!-- END path -->` comments
+        // (path relative to Rails.root). Overlays are throwaway, pointer-events:none.
+        var overlays = [];
+        function clearHighlight(){
+          for (var i = 0; i < overlays.length; i++){ if (overlays[i].parentNode) overlays[i].parentNode.removeChild(overlays[i]); }
+          overlays = [];
+        }
+        // Walk every comment node and pair BEGIN/END markers by path using a stack
+        // (markers nest cleanly), returning {path, begin, end} for each pair.
+        function commentPairs(){
+          var pairs = [], stack = [];
+          var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_COMMENT, null, false);
+          var node;
+          while ((node = walker.nextNode())){
+            var m = /^\\s*(BEGIN|END)\\s+(.+?)\\s*$/.exec(node.nodeValue || "");
+            if (!m) continue;
+            if (m[1] === "BEGIN"){ stack.push({ path: m[2], begin: node }); }
+            else {
+              for (var i = stack.length - 1; i >= 0; i--){
+                if (stack[i].path === m[2]){ pairs.push({ path: m[2], begin: stack[i].begin, end: node }); stack.splice(i, 1); break; }
+              }
+            }
+          }
+          return pairs;
+        }
+        // Draw one fixed overlay around the whole region a row rendered — a single
+        // bounding box, not one per line/inline fragment, so nested links and labels
+        // don't each get their own border. A looped partial still yields one box per
+        // instance (one comment pair each). A row's data-path carries the configured
+        // prefix (e.g. "@app/..."); the comment path doesn't — endsWith matches
+        // regardless of prefix. Rows with no rendered region simply match nothing.
+        function highlight(path){
+          clearHighlight();
+          if (!path) return;
+          var pairs = commentPairs();
+          for (var i = 0; i < pairs.length; i++){
+            if (!path.endsWith(pairs[i].path)) continue;
+            var range = document.createRange();
+            try { range.setStartAfter(pairs[i].begin); range.setEndBefore(pairs[i].end); } catch (e) { continue; }
+            var rect = range.getBoundingClientRect();
+            if (rect.width <= 0 && rect.height <= 0) continue;
+            var box = document.createElement("div");
+            box.className = "plumbo-hl";
+            box.style.cssText = "top:" + rect.top + "px;left:" + rect.left + "px;width:" + rect.width + "px;height:" + rect.height + "px";
+            document.body.appendChild(box);
+            overlays.push(box);
+          }
+        }
+        function rowFor(target, root){
+          if (!root || !target || !target.closest) return null;
+          var row = target.closest(".plumbo-row");
+          return (row && root.contains(row)) ? row : null;
+        }
+        // Delegate hover like the click/input handlers. mouseover bubbles, so it
+        // fires for every move; track the row under the cursor and only re-highlight
+        // when it changes (re-paint on row→row, clear when leaving rows). A null
+        // relatedTarget on mouseout means the pointer left the window — clear then.
+        var hoveredRow = null;
+        document.addEventListener("mouseover", function(event){
+          var row = rowFor(event.target, document.getElementById("plumbo"));
+          if (row === hoveredRow) return;
+          hoveredRow = row;
+          highlight(row ? row.getAttribute("data-path") : null);
+        });
+        document.addEventListener("mouseout", function(event){
+          if (!event.relatedTarget && hoveredRow) { hoveredRow = null; clearHighlight(); }
+        });
         refresh();
         // Read the file list off every fetch response (Turbo Drive/Frame/Stream
         // and custom fetch all go through fetch) so the panel keeps up without a
@@ -305,7 +376,7 @@ module Plumbo
         }
         // A full Turbo Drive visit swaps in a fresh panel; reset the filter to
         // match the new page, then rebuild.
-        document.addEventListener("turbo:load", function(){ query = ""; activeCategory = null; refresh(); });
+        document.addEventListener("turbo:load", function(){ query = ""; activeCategory = null; clearHighlight(); refresh(); });
       })();
     JS
 

data/lib/plumbo/railtie.rb

@@ -10,5 +10,16 @@ module Plumbo
     initializer "plumbo.middleware" do |app|
       app.middleware.use Plumbo::Middleware
     end
+
+    # Enable Rails' filename annotations so each rendered template/partial is
+    # wrapped in BEGIN/END HTML comments — the markers the panel's hover-to-
+    # highlight reads to map a row back to its region on the page. Templates bake
+    # the comments in at compile time, so this must be set before Action View is
+    # configured rather than per-request. Only ever switched on (never off) so a
+    # host that enabled it independently keeps it.
+    initializer "plumbo.annotate_views", before: "action_view.setup" do |app|
+      config = Plumbo.config
+      app.config.action_view.annotate_rendered_view_with_filenames = true if config.enabled && config.highlight
+    end
   end
 end

data/lib/plumbo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumbo
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: plumbo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matt Sears
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport