floatable-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9d58deb57c87c0e5dff62513689456adfe23791b234088e485b729963f4a504
+  data.tar.gz: 285d4e4a29c62d97cf9cfe7cbc37c8131b2d56e0954ad7230dc98ce3ba051ea3
+SHA512:
+  metadata.gz: 1198026452a8ff26ea48063bf4a7c9ba5b4886ebad8fb6dde9a5c1d5615f0a364f187e225936ba2303643d1cf08bca2fcb0632f152ff08efd288e1a329205720
+  data.tar.gz: 2acbbbb919b62d4b3134edd4147e603b5d68462ae2dd4ee400b65897538c600bd4406d7c85d0c1921e2a159b50aba204376c1f6b5b4c1a3a45fa053589a1b4f7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Tobias Almstrand
+
+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,71 @@
+# Floatable::Rails
+
+Rails integration for Floatable Toolbar. It instruments HTML output with
+metadata and injects the Floatable script so your UI can be inspected and
+annotated in the browser.
+
+## Usage
+
+Add the helper to your layout if you want explicit control:
+
+```erb
+<%= floatable_tag %>
+```
+
+The middleware also injects the script automatically for HTML responses when
+Floatable is enabled, so the helper is optional.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "floatable-rails"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install floatable-rails
+```
+
+## Configuration
+
+Create an initializer (for example, `config/initializers/floatable.rb`):
+
+```ruby
+Floatable::Rails.configure do |config|
+  # Enable Floatable per-request.
+  # Default: enabled in development, or when FLOATABLE_ENABLED=1
+  config.enabled = lambda do |request|
+    Rails.env.development? || ENV["FLOATABLE_ENABLED"] == "1"
+  end
+
+  # Metadata passed as data attributes on the script tag.
+  config.script_workspace = "your-floatable-workspace"
+  config.script_repository = "your-floatable-repo"
+  config.script_branch = "main"
+  config.script_agent_tools_mode = "remote|local"
+end
+```
+
+## Release
+
+1. Bump the version in `lib/floatable/rails/version.rb`.
+2. Update `CHANGELOG.md`.
+3. Build the gem: `rake build` (outputs to `pkg/`).
+4. Push the gem: `rake release` or `gem push pkg/floatable-rails-<version>.gem`.
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/floatable/rails/engine.rb

@@ -0,0 +1,47 @@
+require "rails"
+require "floatable/rails/helpers"
+require "floatable/rails/tag_instrumentation"
+require "floatable/rails/erb_line_instrumentation"
+require "floatable/rails/slim_line_instrumentation"
+require "floatable/rails/response_middleware"
+
+module Floatable
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Floatable::Rails
+
+      initializer "floatable.rails.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include ::Floatable::Rails::Helpers
+          prepend ::Floatable::Rails::TagInstrumentation
+        end
+      end
+
+      initializer "floatable.rails.erb_line_instrumentation" do
+        ActiveSupport.on_load(:action_view) do
+          ::ActionView::Template::Handlers::ERB.prepend(::Floatable::Rails::ErbHandlerPatch)
+          ::ActionView::Template::Handlers::ERB.erb_implementation = ::Floatable::Rails::ErubiWithFloatableLines
+        end
+      end
+
+      initializer "floatable.rails.slim_line_instrumentation" do
+        ActiveSupport.on_load(:action_view) do
+          next unless defined?(::Slim::RailsTemplate)
+
+          ::Slim::RailsTemplate.prepend(::Floatable::Rails::SlimHandlerPatch)
+        end
+      end
+
+
+      initializer "floatable.rails.controller_helpers" do
+        ActiveSupport.on_load(:action_controller_base) do
+          helper ::Floatable::Rails::Helpers
+        end
+      end
+
+      initializer "floatable.rails.middleware" do |app|
+        app.middleware.use ::Floatable::Rails::ResponseMiddleware
+      end
+    end
+  end
+end

data/lib/floatable/rails/erb_line_instrumentation.rb

@@ -0,0 +1,164 @@
+require "pathname"
+
+module Floatable
+  module Rails
+    module ErbLineInstrumentation
+      LINE_MARKER_PREFIX = "FLOATABLE_LINE:".freeze
+      EXPR_LINE_MARKER_PREFIX = "FLOATABLE_EXPR_LINE:".freeze
+    end
+
+    module ErbHandlerPatch
+      def call(template, source)
+        source ||= template.source
+        template_source = source.b
+
+        erb = template_source.gsub(self.class::ENCODING_TAG, "")
+        encoding = $2
+
+        erb.force_encoding valid_encoding(source.dup, encoding)
+        erb.encode!
+        erb.chomp! if strip_trailing_newlines
+
+        options = {
+          escape: (self.class.escape_ignore_list.include? template.type),
+          trim: (self.class.erb_trim_mode == "-"),
+          filename: template.identifier
+        }
+
+        if ActionView::Base.annotate_rendered_view_with_filenames && template.format == :html
+          options[:preamble] = "@output_buffer.safe_append='<!-- BEGIN #{template.short_identifier}\n-->';"
+          options[:postamble] = "@output_buffer.safe_append='<!-- END #{template.short_identifier} -->';@output_buffer"
+        end
+
+        self.class.erb_implementation.new(erb, options).src
+      end
+    end
+
+    class ErubiWithFloatableLines < ::ActionView::Template::Handlers::ERB::Erubi
+      LINE_MARKER_PREFIX = ErbLineInstrumentation::LINE_MARKER_PREFIX
+      EXPR_LINE_MARKER_PREFIX = ErbLineInstrumentation::EXPR_LINE_MARKER_PREFIX
+
+      def initialize(input, properties = {})
+        @floatable_line = 1
+        @floatable_view_path = floatable_views_path(properties[:filename])
+        @floatable_in_views = @floatable_view_path.present?
+        if @floatable_in_views
+          properties = properties.dup
+          bufvar = properties[:bufvar] || "@output_buffer"
+          postamble = properties[:postamble] || bufvar
+          properties[:preamble] = "#{properties[:preamble]}@output_buffer.safe_append='<!-- BEGIN #{@floatable_view_path} -->' if Thread.current[:floatable_enabled];"
+          properties[:postamble] = "@output_buffer.safe_append='<!-- END #{@floatable_view_path} -->' if Thread.current[:floatable_enabled];#{postamble}"
+        end
+        super
+      end
+
+      private
+
+      def add_text(text)
+        return if text.empty?
+
+        if text == "\n"
+          @newline_pending += 1
+          return
+        end
+
+        full_text = ("\n" * @newline_pending) + text
+        with_buffer do
+          src << ".safe_append="
+          if @floatable_in_views
+            src << "(Thread.current[:floatable_enabled] ? "
+            src << floatable_text_literal(full_text)
+            src << " : "
+            src << plain_text_literal(full_text)
+            src << ")"
+          else
+            src << plain_text_literal(full_text)
+          end
+        end
+        @newline_pending = 0
+        @floatable_line += full_text.count("\n")
+      end
+
+      def add_expression(indicator, code)
+        flush_newline_if_pending(src)
+        if @floatable_in_views
+          with_buffer do
+            src << ".safe_append='#{expr_line_marker(@floatable_line)}' if Thread.current[:floatable_enabled];"
+          end
+        end
+        super
+        @floatable_line += code.count("\n")
+      end
+
+      def add_code(code)
+        flush_newline_if_pending(src)
+        super
+        @floatable_line += code.count("\n")
+      end
+
+      def flush_newline_if_pending(src)
+        return if @newline_pending <= 0
+
+        full_text = "\n" * @newline_pending
+        with_buffer do
+          src << ".safe_append="
+          if @floatable_in_views
+            src << "(Thread.current[:floatable_enabled] ? "
+            src << floatable_text_literal(full_text)
+            src << " : "
+            src << plain_text_literal(full_text)
+            src << ")"
+          else
+            src << plain_text_literal(full_text)
+          end
+        end
+        @floatable_line += @newline_pending
+        @newline_pending = 0
+      end
+
+      def line_marker(line)
+        "<!--#{LINE_MARKER_PREFIX}#{line}-->"
+      end
+
+      def expr_line_marker(line)
+        "<!--#{EXPR_LINE_MARKER_PREFIX}#{line}-->"
+      end
+
+      def floatable_text_literal(text)
+        marked = add_line_markers(text, @floatable_line)
+        plain_text_literal(marked)
+      end
+
+      def plain_text_literal(text)
+        "'" + text.gsub(/['\\]/, '\\\\\&') + @text_end
+      end
+
+      def add_line_markers(text, start_line)
+        lines = text.split("\n", -1)
+        out = +""
+        lines.each_with_index do |line_text, idx|
+          out << line_marker(start_line + idx) << line_text
+          out << "\n" if idx < lines.length - 1
+        end
+        out
+      end
+
+      def floatable_views_path(filename)
+        return nil if filename.nil?
+
+        str = filename.to_s
+        if str.include?("/app/views/") || str.start_with?("app/views/")
+          return str if str.start_with?("app/views/")
+
+          app_root = ::Rails.root.to_s
+          return str unless app_root.present?
+
+          return Pathname.new(str).relative_path_from(Pathname.new(app_root)).to_s
+        end
+        nil
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/floatable/rails/helpers.rb

@@ -0,0 +1,25 @@
+module Floatable
+  module Rails
+    module Helpers
+      def floatable_enabled?
+        return false unless respond_to?(:request)
+
+        ::Floatable::Rails.enabled_for?(request)
+      end
+
+      def floatable_tag
+        return unless floatable_enabled?
+
+        src = ::Floatable::Rails.script_src
+        return if src.blank?
+
+        javascript_include_tag(
+          src,
+          type: "module",
+          defer: false,
+          data: ::Floatable::Rails.script_data_attributes
+        )
+      end
+    end
+  end
+end

data/lib/floatable/rails/response_middleware.rb

@@ -0,0 +1,223 @@
+require "nokogiri"
+require "erb"
+require "json"
+require "floatable/rails/erb_line_instrumentation"
+
+module Floatable
+  module Rails
+    class ResponseMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        enabled = floatable_enabled?(env)
+        Thread.current[:floatable_enabled] = enabled
+        status = headers = body = nil
+        begin
+          status, headers, body = @app.call(env)
+        ensure
+          Thread.current[:floatable_enabled] = nil
+        end
+
+        return [ status, headers, body ] unless html_response?(status, headers)
+        return [ status, headers, body ] unless enabled
+
+        raw = +""
+        body.each { |chunk| raw << chunk.to_s }
+        body.close if body.respond_to?(:close)
+
+        instrumented = instrument_html(raw, env)
+        final_html = inject_script(instrumented)
+
+        headers["Content-Length"] = final_html.bytesize.to_s if headers["Content-Length"]
+
+        [ status, headers, [ final_html ] ]
+      rescue => e
+        ::Rails.logger.error("[Floatable::Rails::ResponseMiddleware] failed: #{e.class} - #{e.message}")
+        [ status, headers, body ]
+      end
+
+      private
+
+      def html_response?(status, headers)
+        return false unless status == 200
+        ct = headers["Content-Type"] || headers["content-type"]
+        ct && ct.include?("text/html")
+      end
+
+      def floatable_enabled?(env)
+        req = ::Rack::Request.new(env)
+        ::Floatable::Rails.enabled_for?(req)
+      rescue => e
+        ::Rails.logger.error("[Floatable::Rails::ResponseMiddleware] enabled? failed: #{e.class} - #{e.message}")
+        false
+      end
+
+      def instrument_html(html, env)
+        return html if html.strip.empty?
+
+        doctype = html[/\A\s*<!DOCTYPE[^>]*>/i]
+        doc = Nokogiri::HTML.parse(html)
+        doc.css("*").each do |node|
+          name = node.name.to_s.downcase
+          next if %w[script style].include?(name)
+
+          # Don't override helper-provided metadata
+          has_path = node["data-floatable-path"].present?
+
+          unless node["data-floatable-content"].present?
+            data = {
+              name:  node.name,
+              text:  node.text.to_s.strip.presence,
+              class: node["class"].to_s.presence,
+              id:    node["id"].to_s.presence
+            }.compact
+
+            if data.any?
+              encoded = ERB::Util.url_encode(JSON.generate(data)) rescue nil
+              node["data-floatable-content"] = encoded if encoded
+            end
+          end
+
+          next if has_path
+        end
+
+        apply_view_annotations(doc)
+        # Top → down: let descendants inherit path from ancestors when safe
+        propagate_file_metadata_down(doc)
+        # Ensure ids are present and consistent once paths are known
+        assign_floatable_ids(doc)
+
+        rendered = doc.to_html
+        return rendered if doctype.nil? || rendered.lstrip.start_with?("<!DOCTYPE")
+
+        "#{doctype}\n#{rendered}"
+      rescue => e
+        ::Rails.logger.debug("[Floatable::Rails] HTML instrumentation failed: #{e.class} - #{e.message}")
+        html
+      end
+
+      # Top → down: walk the tree and carry the closest ancestor's path
+      # down to all descendants that don't have their own.
+      def propagate_file_metadata_down(doc)
+        doc.children.each do |child|
+          next unless child.element?
+          propagate_file_metadata_down_from_node(child, current_path: nil)
+        end
+      rescue => e
+        ::Rails.logger.debug("[Floatable::Rails] propagate_file_metadata_down failed: #{e.class} - #{e.message}")
+      end
+
+      def propagate_file_metadata_down_from_node(node, current_path:)
+        # Update context with this node's path if it has it
+        node_path = node["data-floatable-path"].presence || current_path
+
+        # If this node doesn't have path but context does, inherit it
+        if node_path && node["data-floatable-path"].blank?
+          node["data-floatable-path"] = node_path
+        end
+
+        next_path = layout_path?(node_path) ? nil : node_path
+
+        node.element_children.each do |child|
+          propagate_file_metadata_down_from_node(child, current_path: next_path)
+        end
+      end
+
+      def inject_script(html)
+        src = ::Floatable::Rails.script_src
+        return html if src.blank?
+
+        if html.match?(/<script\b[^>]*\bsrc=["']#{Regexp.escape(src)}["'][^>]*>/)
+          return html
+        end
+
+        data_attrs = ::Floatable::Rails.script_data_attributes_html
+        snippet = %(<script type="module" src="#{ERB::Util.html_escape(src)}"#{data_attrs}></script>)
+
+        if html.include?("</body>")
+          html.sub("</body>", "#{snippet}\n</body>")
+        else
+          html + snippet
+        end
+      rescue => e
+        ::Rails.logger.error("[Floatable::Rails::ResponseMiddleware] inject_script failed: #{e.class} - #{e.message}")
+        html
+      end
+
+      def assign_floatable_ids(doc)
+        doc.css("*[data-floatable-path]").each do |node|
+          line = node["data-floatable-line"].presence
+          next unless line
+
+          desired = "#{node["data-floatable-path"]}:#{line}"
+          node["data-floatable-id"] = desired if node["data-floatable-id"] != desired
+        end
+      rescue => e
+        ::Rails.logger.debug("[Floatable::Rails] assign_floatable_ids failed: #{e.class} - #{e.message}")
+      end
+
+      def layout_path?(path)
+        str = path.to_s
+        str.include?("/app/views/layouts/") || str.start_with?("app/views/layouts/")
+      end
+
+      def app_views_path?(path)
+        str = path.to_s
+        str.include?("/app/views/") || str.start_with?("app/views/")
+      end
+
+      def apply_view_annotations(doc)
+        view_stack = []
+        line_prefix = ::Floatable::Rails::ErbLineInstrumentation::LINE_MARKER_PREFIX
+        expr_line_prefix = ::Floatable::Rails::ErbLineInstrumentation::EXPR_LINE_MARKER_PREFIX
+        line_comment_re = /\A#{Regexp.escape(line_prefix)}\d+\z/
+        expr_comment_re = /\A#{Regexp.escape(expr_line_prefix)}\d+\z/
+        doc.traverse do |node|
+          if node.comment?
+            content = node.content.to_s.strip
+            if content.start_with?("BEGIN ")
+              path = content.delete_prefix("BEGIN ").strip
+              view_stack << path if app_views_path?(path)
+              next
+            end
+
+            if content.start_with?("END ")
+              path = content.delete_prefix("END ").strip
+              view_stack.pop if view_stack.last == path
+              next
+            end
+
+            next
+          end
+
+          next unless node.element?
+
+          current_path = view_stack.last
+          node["data-floatable-path"] ||= current_path if current_path.present?
+
+          line = floatable_line_from_previous_siblings(node, line_prefix, expr_line_prefix, line_comment_re, expr_comment_re)
+          node["data-floatable-line"] = line if line.to_i > 0 && current_path.present?
+        end
+
+        doc.xpath("//comment()").remove
+      rescue => e
+        ::Rails.logger.debug("[Floatable::Rails] apply_view_annotations failed: #{e.class} - #{e.message}")
+      end
+
+      def floatable_line_from_previous_siblings(node, line_prefix, expr_line_prefix, line_comment_re, expr_comment_re)
+        prev = node.previous_sibling
+        while prev
+          if prev.comment?
+            content = prev.content.to_s.strip
+            return content.delete_prefix(expr_line_prefix).to_i if content.match?(expr_comment_re)
+            return content.delete_prefix(line_prefix).to_i if content.match?(line_comment_re)
+          end
+          prev = prev.previous_sibling
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/floatable/rails/slim_line_instrumentation.rb

@@ -0,0 +1,52 @@
+require "pathname"
+
+module Floatable
+  module Rails
+    module SlimLineInstrumenter
+      def self.instrument(source, view_path)
+        lines = source.to_s.split("\n", -1)
+        out = []
+        out << "- @output_buffer.safe_concat('<!-- BEGIN #{view_path} -->') if Thread.current[:floatable_enabled] && defined?(@output_buffer)"
+
+        lines.each_with_index do |line, idx|
+          indent = line[/\A[ \t]*/] || ""
+          out << "#{indent}- @output_buffer.safe_concat('<!--#{ErbLineInstrumentation::LINE_MARKER_PREFIX}#{idx + 1}-->') if Thread.current[:floatable_enabled] && defined?(@output_buffer)"
+          out << line
+        end
+
+        out << "- @output_buffer.safe_concat('<!-- END #{view_path} -->') if Thread.current[:floatable_enabled] && defined?(@output_buffer)"
+        out.join("\n")
+      end
+    end
+
+    module SlimHandlerPatch
+      def call(template, source = nil)
+        return super unless template.format == :html
+
+        view_path = floatable_views_path(template.identifier)
+        return super if view_path.nil?
+
+        instrumented = SlimLineInstrumenter.instrument(source || template.source, view_path)
+        super(template, instrumented)
+      end
+
+      private
+
+      def floatable_views_path(filename)
+        return nil if filename.nil?
+
+        str = filename.to_s
+        return nil unless str.include?("/app/views/") || str.start_with?("app/views/")
+
+        return str if str.start_with?("app/views/")
+
+        app_root = ::Rails.root.to_s
+        return str unless app_root.present?
+
+        Pathname.new(str).relative_path_from(Pathname.new(app_root)).to_s
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/floatable/rails/tag_instrumentation.rb

@@ -0,0 +1,209 @@
+require "pathname"
+require "json"
+require "erb"
+
+module Floatable
+  module Rails
+    module TagInstrumentation
+      def content_tag(name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+        if floatable_enabled_for_view?
+          options = ensure_options_hash(content_or_options_with_block, options)
+          file, line = floatable_callsite
+
+          if file
+            options[:"data-floatable-path"] ||= floatable_relative_path(file)
+            if line
+              options[:"data-floatable-line"] ||= line
+              options[:"data-floatable-id"] ||= "#{options[:"data-floatable-path"]}:#{options[:"data-floatable-line"]}"
+            end
+          end
+
+          options[:"data-floatable-content"] ||= floatable_content_attr(
+            tag_name: name,
+            options: options,
+            content_text: block_given? ? nil : content_or_options_with_block
+          )
+
+          # Re-shape args for super if we mutated them
+          if content_or_options_with_block.is_a?(Hash) && options
+            content_or_options_with_block = options
+            options = nil
+          end
+        end
+
+        super
+      end
+
+      def tag(name = nil, options = nil, open = false, escape = true)
+        if floatable_enabled_for_view? && name
+          options = (options || {}).dup
+          file, line = floatable_callsite
+
+          if file
+            options[:"data-floatable-path"] ||= floatable_relative_path(file)
+            if line
+              options[:"data-floatable-line"] ||= line
+              options[:"data-floatable-id"] ||= "#{options[:"data-floatable-path"]}:#{options[:"data-floatable-line"]}"
+            end
+          end
+
+          options[:"data-floatable-content"] ||= floatable_content_attr(
+            tag_name: name,
+            options: options,
+            content_text: nil
+          )
+
+          return super(name, options, open, escape)
+        end
+
+        super
+      end
+
+      private
+
+      def floatable_enabled_for_view?
+        return false unless respond_to?(:request)
+
+        ::Floatable::Rails.enabled_for?(request)
+      rescue => e
+        ::Rails.logger.error("[Floatable::Rails::TagInstrumentation] enabled? failed: #{e.class} - #{e.message}")
+        false
+      end
+
+      def floatable_content_attr(tag_name:, options:, content_text:)
+        data = {
+          name: tag_name.to_s,
+          text: content_text.to_s.presence,
+          class: options[:class].to_s.presence,
+          id: options[:id].to_s.presence
+        }.compact
+
+        return if data.empty?
+
+        ERB::Util.url_encode(JSON.generate(data))
+      rescue
+        nil
+      end
+
+      def ensure_options_hash(content_or_options_with_block, options)
+        if content_or_options_with_block.is_a?(Hash) && options.nil?
+          content_or_options_with_block
+        else
+          options || {}
+        end
+      end
+
+      # Callsite detection
+      #
+      # We want the *template* or app file (e.g. app/views/posts/index.html.erb),
+      # not ActionView's gem helpers.
+      #
+      # Strategy:
+      #   - Walk the call stack.
+      #   - Pick the first frame whose path starts with Rails.root
+      #     (so we ignore anything under ~/.rbenv, /gems/, etc).
+      #   - Prefer files under app/views, but accept any app file as fallback.
+      #
+      def floatable_callsite
+        app_root = ::Rails.root.to_s
+        return [ nil, nil ] if app_root.blank?
+
+        locations = caller_locations(2, 200) || []
+
+        template_path = floatable_current_template_path
+        if template_path
+          loc = locations.find { |loc_item| loc_item.path.to_s == template_path }
+          return [ template_path, loc.lineno ] if loc
+        end
+
+        # First pass: prefer app/views templates, excluding layouts when possible.
+        view_locs = locations.select do |loc|
+          path = loc.path.to_s
+          path.start_with?(app_root) && path.include?("/app/views/") && path.end_with?(".erb")
+        end
+
+        unless view_locs.empty?
+          non_layout = view_locs.reverse.find { |loc| !loc.path.to_s.include?("/app/views/layouts/") }
+          chosen = non_layout || view_locs.last
+          return [ chosen.path, chosen.lineno ]
+        end
+
+        # Second pass: any file under Rails.root (app/models, app/controllers, etc)
+        app_loc = locations.find do |loc|
+          path = loc.path.to_s
+          path.start_with?(app_root)
+        end
+
+        if app_loc
+          return [ app_loc.path, app_loc.lineno ]
+        end
+
+        # If nothing inside the app, we give up and return nil
+        [ nil, nil ]
+      rescue => e
+        ::Rails.logger.debug("[Floatable::Rails::TagInstrumentation] floatable_callsite failed: #{e.class} - #{e.message}")
+        [ nil, nil ]
+      end
+
+      def floatable_current_template_path
+        return nil unless respond_to?(:lookup_context)
+
+        current_template = floatable_current_template_identifier
+        return current_template if current_template.present?
+
+        vpath = floatable_virtual_path
+        return nil if vpath.empty?
+
+        templates = lookup_context.find_all(vpath, [], true)
+        template = templates.first || lookup_context.find_all(vpath, [], false).first
+        identifier = template&.identifier.to_s
+        identifier.presence
+      rescue
+        nil
+      end
+
+      def floatable_current_template_identifier
+        return nil unless instance_variable_defined?(:@current_template)
+
+        template = instance_variable_get(:@current_template)
+        identifier = template&.identifier.to_s
+        identifier.presence
+      rescue
+        nil
+      end
+
+      def floatable_virtual_path
+        vpath = nil
+        vpath = virtual_path.to_s if respond_to?(:virtual_path)
+
+        if vpath.to_s.empty?
+          vpath = instance_variable_get(:@virtual_path).to_s if instance_variable_defined?(:@virtual_path)
+        end
+
+        if vpath.to_s.empty?
+          vpath = instance_variable_get(:@_virtual_path).to_s if instance_variable_defined?(:@_virtual_path)
+        end
+
+        vpath.to_s
+      rescue
+        ""
+      end
+
+      def floatable_relative_path(file)
+        return nil if file.blank?
+
+        app_root = ::Rails.root.to_s
+        return file unless app_root.present?
+
+        # Only record paths inside the app root; ignore gems/rbenv/etc.
+        unless file.start_with?(app_root)
+          return nil
+        end
+
+        Pathname.new(file).relative_path_from(Pathname.new(app_root)).to_s
+      rescue
+        file
+      end
+    end
+  end
+end

data/lib/floatable/rails/version.rb

@@ -0,0 +1,5 @@
+module Floatable
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/floatable/rails.rb

@@ -0,0 +1,90 @@
+require "erb"
+require "floatable/rails/version"
+require "floatable/rails/engine"
+
+# lib/floatable/rails.rb
+module Floatable
+  module Rails
+    # Avoid namespace resolution issues for apps that define module Floatable.
+    # In that case, `Rails::Application` resolves to `Floatable::Rails::Application`,
+    # so provide a compatible alias.
+    Application = ::Rails::Application if defined?(::Rails::Application) && !const_defined?(:Application)
+
+    class Configuration
+      # Proc: ->(request) { true/false }
+      attr_accessor :enabled
+      # URL for the Floatable toolbar script
+      attr_accessor :script_src
+      # Metadata
+      attr_accessor :script_workspace
+      attr_accessor :script_repository
+      attr_accessor :script_repository_name
+      attr_accessor :script_branch
+      attr_accessor :script_agent_tools_mode
+
+      def initialize
+        # Default: enabled in development or when FLOATABLE_ENABLED=1
+        @enabled = lambda do |_request|
+          ::Rails.env.development? || ENV["FLOATABLE_ENABLED"] == "1"
+        end
+
+        # Default script for dev; override in host app
+        @script_src = "https://assets.floatable.dev/js/toolbar.js"
+
+        @script_workspace = nil
+        @script_repository = nil
+        @script_repository_name = nil
+        @script_branch = nil
+        @script_agent_tools_mode = nil
+      end
+    end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield(config)
+      end
+
+      # Central predicate for "is Floatable active for this request?"
+      def enabled_for?(request)
+        predicate = config.enabled
+        return false unless predicate.respond_to?(:call)
+
+        !!predicate.call(request)
+      rescue => e
+        ::Rails.logger.error("[Floatable::Rails] enabled_for? failed: #{e.class} - #{e.message}")
+        false
+      end
+
+      def script_src
+        config.script_src
+      end
+
+      def script_data
+        {
+          workspace: config.script_workspace,
+          repository: config.script_repository,
+          repository_name: config.script_repository_name,
+          branch: config.script_branch,
+          agent_tools_mode: config.script_agent_tools_mode
+        }.reject { |_key, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
+      end
+
+      def script_data_attributes
+        script_data.transform_keys { |key| :"floatable_#{key}" }
+      end
+
+      def script_data_attributes_html
+        data = script_data
+        return "" if data.empty?
+
+        data.map do |key, value|
+          %( data-floatable-#{key.to_s.tr("_", "-")}="#{ERB::Util.html_escape(value.to_s)}")
+        end.join
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: floatable-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tobias Almstrand
+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.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.1
+description: Instruments HTML output with metadata and injects the Floatable script
+  so your UI can be inspected and annotated in the browser.
+email:
+- tobias@almstrand.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/floatable/rails.rb
+- lib/floatable/rails/engine.rb
+- lib/floatable/rails/erb_line_instrumentation.rb
+- lib/floatable/rails/helpers.rb
+- lib/floatable/rails/response_middleware.rb
+- lib/floatable/rails/slim_line_instrumentation.rb
+- lib/floatable/rails/tag_instrumentation.rb
+- lib/floatable/rails/version.rb
+homepage: https://floatable.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://floatable.dev
+  source_code_uri: https://floatable.dev
+  changelog_uri: https://floatable.dev/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails integration for the Floatable Toolbar.
+test_files: []