pinmark 0.1.0

data/lib/pinmark/stylesheets.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Pinmark
+  # Inline CSS used by the engine's UI partials. Kept in Ruby so the partials
+  # stay free of large heredoc blocks and the styles can be reused across
+  # render contexts without depending on the asset pipeline.
+  module Stylesheets
+    ACTIVATOR = <<~CSS
+      .pinmark-activator {
+        position: fixed;
+        bottom: 12px;
+        left: 12px;
+        z-index: 99999;
+        padding: 6px 10px;
+        background: #1f2937;
+        color: #fff;
+        border: 1px solid #374151;
+        border-radius: 6px;
+        font: 12px sans-serif;
+        cursor: pointer;
+        box-shadow: 0 2px 6px rgba(0, 0, 0, 0.25);
+      }
+      .pinmark-activator:hover { background: #374151; }
+      .pinmark-activator.is-on { background: #f97316; color: #111; border-color: #f97316; }
+      .pinmark-activator.is-on:hover { background: #ea580c; }
+    CSS
+
+    ACTIVATOR_SCRIPT = <<~JS
+      (function() {
+        var btn = document.getElementById('pinmark-activator');
+        if (!btn) return;
+        btn.addEventListener('click', function() {
+          var on = document.cookie.split('; ').some(function(c) { return c.indexOf('pinmark=1') === 0; });
+          if (on) {
+            document.cookie = 'pinmark=; path=/; max-age=0';
+          } else {
+            document.cookie = 'pinmark=1; path=/; max-age=2592000';
+          }
+          window.location.reload();
+        });
+      })();
+    JS
+
+    OVERLAY = <<~CSS
+      .pinmark-toggle { position: fixed; bottom: 12px; right: 12px; z-index: 99999; padding: 6px 10px; background: #111; color: #fff; border: 0; border-radius: 6px; font: 12px sans-serif; cursor: pointer; }
+      .pinmark-toggle.is-active { background: #f97316; color: #111; }
+      .pinmark-mode { position: fixed; bottom: 12px; right: 124px; z-index: 99999; padding: 6px 10px; background: #1f2937; color: #fff; border: 0; border-radius: 6px; font: 12px sans-serif; cursor: pointer; }
+      .pinmark-mode.is-element { background: #38bdf8; color: #0c1f2e; }
+      .pinmark-panel { position: fixed; top: 12px; right: 12px; max-width: 320px; max-height: 70vh; overflow: auto; background: rgba(17,17,17,.92); color: #fff; padding: 12px; border-radius: 8px; font: 12px/1.4 sans-serif; z-index: 99999; display: none; }
+      .pinmark-panel.is-open { display: block; }
+      .pinmark-highlight { outline: 2px solid #f97316 !important; outline-offset: -2px; cursor: crosshair; }
+      .pinmark-highlight-tag { outline: 2px dashed #38bdf8 !important; }
+      .pinmark-highlight-context { outline: 2px dotted rgba(249,115,22,.55) !important; outline-offset: -2px; }
+      .pinmark-popover { position: fixed; z-index: 99999; background: #111; color: #fff; padding: 8px; border-radius: 6px; min-width: 220px; }
+      .pinmark-popover textarea { width: 100%; min-height: 60px; box-sizing: border-box; background: #1f2937; color: #fff; border: 1px solid #374151; border-radius: 4px; padding: 6px; font: 12px/1.4 sans-serif; resize: vertical; }
+      .pinmark-popover textarea::placeholder { color: #9ca3af; }
+      .pinmark-popover textarea:focus { outline: none; border-color: #38bdf8; }
+      .pinmark-popover-actions { display: flex; gap: 6px; margin-top: 6px; }
+      .pinmark-popover-actions button { padding: 4px 10px; background: #1f2937; color: #fff; border: 1px solid #374151; border-radius: 4px; font: 12px sans-serif; cursor: pointer; }
+      .pinmark-popover-actions button:hover { background: #374151; }
+      .pinmark-popover-actions button:first-child { background: #f97316; border-color: #f97316; color: #111; }
+      .pinmark-popover-actions button:first-child:hover { background: #ea580c; }
+      .pinmark-popover-header { font: 600 12px sans-serif; color: #fff; margin-bottom: 6px; line-height: 1.3; word-break: break-word; }
+      .pinmark-popover-header .mcp-source { display: block; font-weight: 400; opacity: .75; font-size: 11px; }
+      .pinmark-popover-header .mcp-selector { display: block; font-weight: 400; color: #38bdf8; font-size: 11px; word-break: break-all; }
+      .pinmark-popover-debug { margin-top: 6px; color: #ddd; font: 11px sans-serif; }
+      .pinmark-popover-debug summary { cursor: pointer; user-select: none; opacity: .7; }
+      .pinmark-popover-debug summary:hover { opacity: 1; }
+      .pinmark-popover-debug pre { margin: 6px 0 0; padding: 6px; background: rgba(255,255,255,.05); border-radius: 4px; white-space: pre-wrap; word-break: break-word; max-height: 160px; overflow: auto; font: 10px/1.4 ui-monospace, monospace; }
+      .pinmark-label { position: fixed; z-index: 99999; padding: 2px 6px; background: #111; color: #fff; font: 11px sans-serif; border-radius: 4px; pointer-events: none; max-width: 360px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+      .pinmark-label.is-tag { background: #38bdf8; color: #0c1f2e; }
+      .pinmark-markers { position: absolute; top: 0; left: 0; pointer-events: none; z-index: 99998; }
+      .pinmark-marker { position: absolute; pointer-events: auto; transform: translate(-50%, -50%); width: 22px; height: 22px; border-radius: 50%; background: #f97316; color: #111; border: 2px solid #fff; box-shadow: 0 1px 4px rgba(0,0,0,.4); font: 600 11px sans-serif; cursor: pointer; display: inline-flex; align-items: center; justify-content: center; padding: 0; }
+      .pinmark-marker:hover { transform: translate(-50%, -50%) scale(1.15); }
+      .pinmark-marker.is-resolved { background: #34d399; opacity: .75; }
+      .pinmark-marquee { position: absolute; z-index: 99998; border: 1.5px dashed #f97316; background: rgba(249,115,22,.12); pointer-events: none; }
+      .pinmark-panel-header { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 4px; }
+      .pinmark-panel-collapse { background: transparent; color: #fff; border: 0; cursor: pointer; padding: 0 6px; font: 14px sans-serif; opacity: .6; }
+      .pinmark-panel-collapse:hover { opacity: 1; }
+      .pinmark-panel.is-collapsed { max-height: none; padding: 8px 12px; overflow: hidden; }
+    CSS
+  end
+end

data/lib/pinmark/tracker.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Pinmark
+  class Tracker
+    class StackUnderflowError < StandardError
+    end
+
+    attr_reader :nodes
+
+    def initialize
+      @nodes = []
+      @stack = []
+      @counter = 0
+    end
+
+    def push(component:, source:)
+      @counter += 1
+      id = "pm-#{@counter}"
+      parent_id = @stack.last
+      @nodes << { id:, component:, source:, parent_id: }
+      @stack.push(id)
+      id
+    end
+
+    def pop
+      raise StackUnderflowError, "pinmark stack underflow" if @stack.empty?
+
+      @stack.pop
+    end
+
+    def tree
+      by_parent = @nodes.group_by { |node| node[:parent_id] }
+      build = lambda { |parent_id|
+        (by_parent[parent_id] || []).map do |node|
+          node.merge(children: build.call(node[:id]))
+        end
+      }
+      build.call(nil)
+    end
+  end
+end

data/lib/pinmark/version.rb

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

data/lib/pinmark/wrapper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Pinmark
+  module Wrapper
+    module_function
+
+    # Wrap a block's HTML output in pinmark begin/end markers, pushing
+    # and popping the per-request tracker. When annotations are inactive (non-dev,
+    # or no tracker) the block is invoked verbatim and its return value passes
+    # through unchanged.
+    #
+    # The block must return a String (or something coercible via #to_s).
+    def wrap(component:, source:)
+      tracker = Pinmark.tracker if Rails.env.development?
+      return yield unless tracker
+
+      id = tracker.push(component:, source:)
+      parent_id = tracker.nodes.last[:parent_id]
+
+      id_attr = escape(id)
+      class_attr = escape(component)
+      src_attr = escape(source)
+      parent_attr = escape(parent_id)
+
+      begin_marker = %(<!-- pinmark:begin id="#{id_attr}" class="#{class_attr}" src="#{src_attr}" parent="#{parent_attr}" -->)
+      end_marker = %(<!-- pinmark:end id="#{id_attr}" -->)
+
+      content = yield.to_s
+      "#{begin_marker}#{content}#{end_marker}".html_safe
+    ensure
+      tracker&.pop if id
+    end
+
+    def escape(value)
+      CGI.escapeHTML(value.to_s).gsub("--", "&#45;&#45;")
+    end
+  end
+end

data/lib/pinmark.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "pinmark/version"
+require "pinmark/engine"
+require "pinmark/stylesheets"
+require "pinmark/tracker"
+require "pinmark/source_locator"
+require "pinmark/wrapper"
+require "pinmark/phlex"
+require "pinmark/hooks/erb_partial"
+require "pinmark/hooks/view_component"
+require "pinmark/mcp/queue"
+require "pinmark/mcp/tools/list_pending"
+require "pinmark/mcp/tools/list_resolved"
+require "pinmark/mcp/tools/mark_addressed"
+require "pinmark/mcp/tools/clear_addressed"
+require "pinmark/mcp/server"
+require "pinmark/mcp/rack_app"
+
+module Pinmark
+  # Whether the pinmark hooks should be active for the current request.
+  # The host app sets Pinmark.tracker (typically per-request via the
+  # Session concern) when the dev cookie / param toggles annotations on.
+  #
+  # We intentionally keep the predicate cheap so the wrapper / hooks can call it
+  # on every render in development without measurable overhead.
+  def self.active?
+    Rails.env.development? && tracker.present?
+  end
+
+  def self.tracker
+    return nil unless defined?(::Current) && ::Current.respond_to?(:pinmark)
+
+    ::Current.pinmark
+  end
+end

data/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "pinmark",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Stimulus controller for the pinmark Rails engine. Consumed by webpack-based host apps via a `file:` dependency.",
+  "main": "app/javascript/pinmark/pinmark_controller.js",
+  "files": [
+    "app/javascript/pinmark/pinmark_controller.js"
+  ],
+  "exports": {
+    ".": "./app/javascript/pinmark/pinmark_controller.js",
+    "./pinmark_controller": "./app/javascript/pinmark/pinmark_controller.js"
+  }
+}

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: pinmark
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Przemyslaw Lusar
+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: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: phlex-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Pinmark adds a dev-only floating overlay to any Rails app. Click a component
+  or any element on the page, leave a comment, and Claude Code consumes the queue
+  via MCP — closing the loop between visual feedback and source edits. Works with
+  Phlex, ViewComponent, and ERB partials.
+email:
+- lluzak@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/controllers/concerns/pinmark/session.rb
+- app/controllers/pinmark/annotations_controller.rb
+- app/controllers/pinmark/application_controller.rb
+- app/javascript/pinmark/pinmark_controller.js
+- app/views/pinmark/_activator.html.erb
+- app/views/pinmark/_overlay.html.erb
+- config/importmap.rb
+- config/routes.rb
+- lib/generators/pinmark/install/install_generator.rb
+- lib/pinmark.rb
+- lib/pinmark/engine.rb
+- lib/pinmark/hooks/erb_partial.rb
+- lib/pinmark/hooks/view_component.rb
+- lib/pinmark/mcp/queue.rb
+- lib/pinmark/mcp/rack_app.rb
+- lib/pinmark/mcp/server.rb
+- lib/pinmark/mcp/tools/clear_addressed.rb
+- lib/pinmark/mcp/tools/list_pending.rb
+- lib/pinmark/mcp/tools/list_resolved.rb
+- lib/pinmark/mcp/tools/mark_addressed.rb
+- lib/pinmark/phlex.rb
+- lib/pinmark/source_locator.rb
+- lib/pinmark/stylesheets.rb
+- lib/pinmark/tracker.rb
+- lib/pinmark/version.rb
+- lib/pinmark/wrapper.rb
+- package.json
+homepage: https://github.com/lluzak/pinmark
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lluzak/pinmark
+  source_code_uri: https://github.com/lluzak/pinmark
+  changelog_uri: https://github.com/lluzak/pinmark/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.7.2
+specification_version: 4
+summary: Pin-style UI annotations that flow into Claude Code via MCP.
+test_files: []