block
diff --git a/‎engine/app/assets/stylesheets/coplan/application.css‎
Lines changed: 292 additions & 44 deletions b/‎engine/app/assets/stylesheets/coplan/application.css‎
Lines changed: 292 additions & 44 deletions
diff --git a/‎engine/app/controllers/coplan/plans_controller.rb‎
Lines changed: 3 additions & 0 deletions b/‎engine/app/controllers/coplan/plans_controller.rb‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎engine/app/controllers/coplan/references_controller.rb‎
Lines changed: 15 additions & 3 deletions b/‎engine/app/controllers/coplan/references_controller.rb‎
Lines changed: 15 additions & 3 deletions
diff --git a/‎engine/app/helpers/coplan/markdown_helper.rb‎
Lines changed: 101 additions & 4 deletions b/‎engine/app/helpers/coplan/markdown_helper.rb‎
Lines changed: 101 additions & 4 deletions
diff --git a/‎engine/app/helpers/coplan/references_helper.rb‎
Lines changed: 139 additions & 6 deletions b/‎engine/app/helpers/coplan/references_helper.rb‎
Lines changed: 139 additions & 6 deletions
@@ -149,6 +149,9 @@ def show
         .order(:created_at)
       @my_folders = current_user.library.folders.order(:name).to_a
       @threads = @plan.comment_threads.with_kept_comments.includes(:comments, :created_by_user).order(:created_at)
+      # The reader view joins auto-extracted resources to their Markdown
+      # citations by URL, then lists the remaining resources in the same
+      # References section.
       @references = @plan.references.order(reference_type: :asc, created_at: :desc)
       @attachments = @plan.attachments_attachments.includes(:blob).order(created_at: :desc)
       # Order matters: compute the one-time "changed since you last looked"
 
@@ -79,21 +79,33 @@ def set_plan
 
     def render_references_stream
       references = @plan.references.reload.order(reference_type: :asc, created_at: :desc)
+      back_matter = helpers.plan_citation_back_matter(@plan, references)
+      listed_references = helpers.listed_plan_references(references, back_matter[:cited_urls])
+      reference_count = back_matter[:count] + listed_references.size
       render turbo_stream: [
+        turbo_stream.replace(
+          "plan-citations",
+          partial: "coplan/plans/citations",
+          locals: { plan: @plan, back_matter: back_matter }
+        ),
         turbo_stream.replace(
           "plan-references",
           partial: "coplan/plans/references",
-          locals: { references: references, plan: @plan }
+          locals: {
+            references: listed_references,
+            plan: @plan,
+            has_citations: back_matter[:count].positive?
+          }
         ),
         turbo_stream.replace(
           "references-count",
-          html: helpers.content_tag(:span, references.size, class: "section-count", id: "references-count")
+          html: helpers.content_tag(:span, reference_count, class: "section-count", id: "references-count")
         ),
         # The document outline shows the same count; without this it goes
         # stale the moment a reference is added or removed.
         turbo_stream.replace(
           "nav-references-count",
-          html: helpers.content_tag(:span, references.size, class: "section-count", id: "nav-references-count")
+          html: helpers.content_tag(:span, reference_count, class: "section-count", id: "nav-references-count")
         )
       ]
     end
 
@@ -16,7 +16,7 @@ module MarkdownHelper
       section
     ].freeze
 
-    ALLOWED_ATTRIBUTES = %w[id class lang href src alt title type checked disabled open aria-label data-line data-line-text data-action data-mention-username data-sourcepos data-footnotes data-footnote-ref data-footnote-backref data-footnote-backref-idx].freeze
+    ALLOWED_ATTRIBUTES = %w[id class lang href src alt title target rel type checked disabled open aria-label aria-haspopup aria-expanded data-line data-line-text data-action data-mention-username data-sourcepos data-reference-type data-footnotes data-footnote-ref data-footnote-backref data-footnote-backref-idx].freeze
 
     # Commonmarker extensions beyond the gem defaults (tables, tasklist,
     # strikethrough, autolink stay on). Footnotes: `[^1]` in text plus a
@@ -34,7 +34,7 @@ module MarkdownHelper
     # version. Bump it whenever the rendering pipeline changes output for the
     # same input (new tags, attribute changes, checkbox wiring, etc.), or
     # stale HTML will be served from cache.
-    RENDER_CACHE_VERSION = 2
+    RENDER_CACHE_VERSION = 8
 
     # Matches `[@username](mention:username)` where the bracket text and link
     # target encode the same username. Username allows letters, digits, dots,
@@ -46,16 +46,20 @@ module MarkdownHelper
     # one markdown fragment (e.g. each comment) — commonmarker numbers
     # footnote ids from #fn-1 per document, so unprefixed fragments collide
     # and reference/backref links jump to the wrong footnote.
-    def render_markdown(content, interactive: true, footnote_prefix: nil)
+    def render_markdown(content, interactive: true, footnote_prefix: nil, footnotes: :inline)
       render_options = { unsafe: true }
       # Sourcepos is only needed to wire checkboxes to their source lines;
       # make_checkboxes_interactive strips it from the final output.
       render_options[:sourcepos] = true if interactive
       html = Commonmarker.to_html(content.to_s.encode("UTF-8"), options: { extension: EXTENSION_OPTIONS, render: render_options }, plugins: { syntax_highlighter: nil })
       with_chips = transform_mention_anchors(html)
-      sanitized = sanitize(with_chips, tags: ALLOWED_TAGS, attributes: ALLOWED_ATTRIBUTES)
+      with_references = transform_reference_anchors(with_chips, numbered_sections: footnote_prefix.nil?)
+      sanitized = sanitize(with_references, tags: ALLOWED_TAGS, attributes: ALLOWED_ATTRIBUTES)
       result = interactive ? make_checkboxes_interactive(sanitized, content) : sanitized
       result = scope_footnote_ids(result, footnote_prefix) if footnote_prefix
+      result = select_footnotes(result, footnotes)
+      return result.html_safe if footnotes == :only
+
       tag.div(result.html_safe, class: "markdown-rendered", data: { controller: "coplan--mermaid coplan--syntax-highlight" })
     end
 
@@ -80,13 +84,106 @@ def transform_mention_anchors(html)
       doc.to_html
     end
 
+    # Numbered headings get stable fragments so agents can write explicit,
+    # unambiguous same-document references such as
+    # `[§3.1](#section-3-1)`. Plain `§3.1` text is deliberately not linked:
+    # research plans also cite external laws as `RKSV §3.1`, where guessing
+    # that the target is a CoPlan heading would create incorrect links.
+    #
+    # Footnote citations and valid numbered-section links opt into the shared
+    # reference-preview controller. It reads their already-rendered targets,
+    # so previews require no duplicate citation data or network request.
+    def transform_reference_anchors(html, numbered_sections: true)
+      doc = Nokogiri::HTML::DocumentFragment.parse(html)
+      used_ids = doc.css("[id]").filter_map { |node| node["id"].presence }.to_set
+      section_ids = Set.new
+
+      doc.css("a[href]").each do |anchor|
+        next unless anchor["href"].match?(%r{\Ahttps?://}i)
+
+        anchor["target"] = "_blank"
+        anchor["rel"] = "noopener noreferrer"
+        anchor["data-reference-type"] = Reference.classify_url(anchor["href"])
+      end
+
+      if numbered_sections
+        doc.css("h1, h2, h3, h4, h5, h6").each do |heading|
+          section_number = heading.text.squish[/\A(\d+(?:\.\d+)*)\b/, 1]
+          next unless section_number
+
+          heading["id"] ||= unique_dom_id("section-#{section_number.tr('.', '-')}", used_ids)
+          used_ids << heading["id"]
+          section_ids << heading["id"]
+        end
+      end
+
+      doc.css("a[data-footnote-ref]").each do |anchor|
+        enhance_reference_anchor(anchor, type: "footnote")
+      end
+
+      doc.css('a[href^="#"]').each do |anchor|
+        next if anchor["data-footnote-ref"] || anchor["data-footnote-backref"]
+
+        target_id = anchor["href"].delete_prefix("#")
+        enhance_reference_anchor(anchor, type: "section") if section_ids.include?(target_id)
+      end
+
+      doc.css("section[data-footnotes]").each do |section|
+        heading = Nokogiri::XML::Node.new("h2", doc)
+        heading["class"] = "footnotes-title"
+        heading.content = "References"
+        section.prepend_child(heading)
+      end
+
+      doc.to_html
+    end
+
     def markdown_to_plain_text(content)
       html = Commonmarker.to_html(content.to_s.encode("UTF-8"), options: { extension: EXTENSION_OPTIONS }, plugins: { syntax_highlighter: nil })
       Nokogiri::HTML::DocumentFragment.parse(html).text.squish
     end
 
     private
 
+    REFERENCE_PREVIEW_ACTIONS = [
+      "mouseenter->coplan--reference-preview#enter",
+      "mouseleave->coplan--reference-preview#leave",
+      "focus->coplan--reference-preview#enter",
+      "blur->coplan--reference-preview#leave",
+      "click->coplan--reference-preview#follow"
+    ].join(" ").freeze
+
+    def unique_dom_id(base, used_ids)
+      return base unless used_ids.include?(base)
+
+      suffix = 2
+      suffix += 1 while used_ids.include?("#{base}-#{suffix}")
+      "#{base}-#{suffix}"
+    end
+
+    def enhance_reference_anchor(anchor, type:)
+      anchor.add_class("reference-anchor")
+      anchor.add_class("reference-anchor--#{type}")
+      anchor["aria-haspopup"] = "dialog"
+      anchor["aria-expanded"] = "false"
+      anchor["data-action"] = [ anchor["data-action"], REFERENCE_PREVIEW_ACTIONS ].compact.join(" ")
+    end
+
+    def select_footnotes(html, mode)
+      return html if mode == :inline
+
+      doc = Nokogiri::HTML::DocumentFragment.parse(html)
+      sections = doc.css("section[data-footnotes]")
+      if mode == :only
+        sections.map(&:to_html).join
+      elsif mode == :exclude
+        sections.remove
+        doc.to_html
+      else
+        raise ArgumentError, "unknown footnote mode: #{mode.inspect}"
+      end
+    end
+
     # Wires rendered task checkboxes to their source lines via Commonmarker's
     # sourcepos metadata, so the parser that decides what renders as a
     # checkbox is also the authority on which line it came from. A checkbox
 
@@ -1,12 +1,145 @@
 module CoPlan
   module ReferencesHelper
-    def reference_icon(reference_type)
+    include MarkdownHelper
+
+    def reference_domain(url)
+      URI.parse(url).host&.delete_prefix("www.")
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def reference_type_label(reference_type, url)
+      domain = reference_domain(url)
+
       case reference_type
-      when "plan" then "📋"
-      when "repository" then "📦"
-      when "pull_request" then "🔀"
-      when "document" then "📄"
-      else "🔗"
+      when "plan" then "CoPlan plan"
+      when "repository" then "GitHub repository"
+      when "pull_request" then "GitHub pull request"
+      when "document"
+        return "Google Sheet" if domain == "docs.google.com" && URI.parse(url).path.start_with?("/spreadsheets/")
+        return "Google Slides" if domain == "docs.google.com" && URI.parse(url).path.start_with?("/presentation/")
+        return "Google Doc" if domain == "docs.google.com"
+        return "Google Drive" if domain == "drive.google.com"
+        return "Notion" if domain&.end_with?("notion.so", "notion.site")
+        return "Confluence" if domain&.include?("confluence")
+
+        "Document"
+      else
+        domain&.match?(/(^|\.)gov(\.|$)/) ? "Government website" : "Website"
+      end
+    rescue URI::InvalidURIError
+      reference_type.humanize
+    end
+
+    # Markdown owns a citation's placement and explanatory text; Reference
+    # owns the linked resource's durable identity. Join those two projections
+    # by URL for one reader-facing References section without duplicating the
+    # versioned plan content in another model.
+    def plan_citation_back_matter(plan, references)
+      references = references.to_a
+      reference_digest = Digest::SHA256.hexdigest(
+        references.map { |reference| "#{reference.id}:#{reference.updated_at&.to_f}" }.join("|")
+      )
+      signature = [ plan.current_revision, reference_digest ]
+      cached = Rails.cache.fetch([
+        "coplan/plan-citation-back-matter",
+        MarkdownHelper::RENDER_CACHE_VERSION,
+        plan.id,
+        *signature
+      ]) do
+        result = build_plan_citation_back_matter(plan, references)
+        [ result[:html].to_s, result[:cited_urls].to_a, result[:count] ]
+      end
+
+      {
+        html: cached[0].html_safe,
+        cited_urls: cached[1].to_set.freeze,
+        count: cached[2]
+      }
+    end
+
+    def listed_plan_references(references, cited_urls)
+      references.reject { |reference| cited_urls.include?(reference.url) }
+    end
+
+    def plan_reference_count(plan, references)
+      back_matter = plan_citation_back_matter(plan, references)
+      back_matter[:count] + listed_plan_references(references, back_matter[:cited_urls]).size
+    end
+
+    private
+
+    def build_plan_citation_back_matter(plan, references)
+      html = render_markdown(plan.current_content, footnotes: :only)
+      doc = Nokogiri::HTML::DocumentFragment.parse(html)
+      sections = doc.css("section[data-footnotes]")
+      return { html: "".html_safe, cited_urls: Set.new.freeze, count: 0 } if sections.empty?
+
+      references_by_url = references.index_by(&:url)
+      cited_urls = Set.new
+
+      sections.each do |section|
+        section["class"] = "reference-citations"
+        section.css(".footnotes-title").remove
+        section.css('a[href^="http://"], a[href^="https://"]').each do |anchor|
+          reference = references_by_url[anchor["href"]]
+          cited_urls << anchor["href"]
+          decorate_citation_source(anchor, reference)
+        end
+      end
+
+      {
+        html: sections.map(&:to_html).join.html_safe,
+        cited_urls: cited_urls.freeze,
+        count: sections.sum { |section| section.xpath("./ol/li").size }
+      }
+    end
+
+    def decorate_citation_source(anchor, reference)
+      type = reference&.reference_type || anchor["data-reference-type"] || Reference.classify_url(anchor["href"])
+      domain = reference_domain(anchor["href"])
+      title = reference&.title.presence || anchor.text.squish.presence || domain || anchor["href"]
+      metadata = [ reference_type_label(type, anchor["href"]), domain ].compact.join(" · ")
+
+      anchor.add_class("citation-source")
+      anchor["aria-label"] = "Open source: #{title} in a new tab (#{metadata})"
+      unless terminal_citation_source?(anchor)
+        anchor.add_class("citation-source--inline")
+        anchor["title"] = metadata
+        return
+      end
+
+      anchor.add_class("citation-source--block")
+      anchor.children.remove
+
+      content = Nokogiri::XML::Node.new("span", anchor.document)
+      content["class"] = "citation-source__content"
+
+      title_node = Nokogiri::XML::Node.new("span", anchor.document)
+      title_node["class"] = "citation-source__title"
+      title_node.content = title
+
+      metadata_node = Nokogiri::XML::Node.new("span", anchor.document)
+      metadata_node["class"] = "citation-source__meta"
+      metadata_node.content = "#{metadata} ↗"
+
+      content.add_child(title_node)
+      content.add_child(metadata_node)
+      anchor.add_child(content)
+
+      punctuation = anchor.next_sibling
+      if punctuation&.text? && punctuation.text.match?(/\A\s*[.,;:]\s*\z/)
+        punctuation.remove
+      end
+    end
+
+    def terminal_citation_source?(anchor)
+      anchor.xpath("following-sibling::node()").all? do |sibling|
+        if sibling.text?
+          sibling.text.match?(/\A\s*[.,;:]*\s*\z/)
+        else
+          sibling.attribute("data-footnote-backref").present?
+        end
       end
     end
   end