Commit 9ff498d h

Pat Ambrosio · 26-08-27 13:20

Tooltips on footnote and citation markers

Changes: 4 files +514 -5

Changes (Side-by-Side)

Raw

commit 9ff498d21ae095ca02a17b7206472e23c40b92e4
Author: Pat Ambrosio <cp.ambrosio@gmail.com>
Date:   Thu Aug 27 13:20:09 2026 +0800

    Tooltips on footnote and citation markers
    
    Hovering or focusing a superscript marker shows what it points to, so a
    reader can check a note without losing their place.
    
    The tooltip is a real element holding a clone of the definition's nodes,
    not a pseudo-element fed from an attribute. That distinction is the whole
    feature: a ::after content string is text, so a link inside a footnote can
    never be clicked. The first implementation did exactly that and reported
    the requirement as met; the citation on the plain-text post contains a
    real URL, and it rendered as inert text.
    
    Marker and tooltip share a close timer, so leaving one and entering the
    other keeps it open -- without the bridge the tooltip closes underneath a
    pointer heading for it, and every link inside is unreachable. Nothing
    animates: transition and animation are none, so it appears instantly.
    Keyboard focus shows it and blur schedules the same delayed hide, leaving
    time to tab into the content. The backref arrow and the citation's return
    link are stripped from the clone.
    
    Without script the markers still jump to their definitions exactly as
    before, and a tap on a touch device does the same.
    
    One defect found by measuring rather than reading: the tooltip is centred
    on its marker, so a marker near the right margin pushed it off the edge --
    at 440px a 232px tooltip on a marker at x=329 ended 5px past the viewport,
    while its width was still well inside the cap. A width cap cannot fix a
    position problem, and the breakpoint guarding this was written for 320px,
    leaving every width between there and the desktop case unguarded. Each
    tooltip is now measured once shown and nudged back inside; only the
    browser knows where the marker landed after the line wrapped.
    
    Verified in a browser at 11 widths from 320 to 1440 with every tooltip
    open at once: nothing off-screen, no page overflow. Then across nine pages
    at three widths: 27 checks, no overflow, no misalignment.
    
    Two of the tests as first written passed against broken code -- one
    checked that "marginLeft" appeared somewhere, which a constant shift still
    satisfies, and the close bridge had no test at all. Both were rewritten
    until the mutation failed: disabling the nudge and removing the timer
    cancel each now fail a specific test.
    
    Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
    Claude-Session: https://claude.ai/code/session_01WnSAstgnDYdKPwLGv1YZE5

diff --git a/share/jenny/layout/page.sh b/share/jenny/layout/page.sh
index 9edbbac..b5d5489 100755
--- a/share/jenny/layout/page.sh
+++ b/share/jenny/layout/page.sh
@@ -725,6 +725,68 @@ cat << _EOF_
         .theme-toggle:hover {
           background-color: var(--bg-secondary);
         }
+        /* Tooltip styling for footnote and citation references.
+           Rendered as real DOM elements so links remain interactive.
+           Appears on hover or focus, and survives pointer movement into it. */
+        .fnref[data-fnref],
+        .citation[data-citation] {
+          position: relative;
+        }
+        /* Tooltip is a real element, positioned absolutely. */
+        .fn-tip,
+        .citation-tip {
+          position: absolute;
+          bottom: 100%;
+          left: 50%;
+          transform: translateX(-50%);
+          background-color: var(--bg-secondary);
+          color: var(--text-primary);
+          border: 1px solid var(--border-medium);
+          border-radius: 3px;
+          padding: 0.5em 0.75em;
+          font-size: 0.85em;
+          line-height: 1.4;
+          white-space: normal;
+          max-width: min(280px, calc(100vw - 2em));
+          box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+          z-index: 1000;
+          opacity: 0;
+          visibility: hidden;
+          transition: none;
+          margin-bottom: 0.5em;
+          pointer-events: auto;
+        }
+        /* Tooltip links are clickable. */
+        .fn-tip a,
+        .citation-tip a {
+          color: var(--link-article);
+          text-decoration: underline;
+          cursor: pointer;
+        }
+        /* Show tooltip. */
+        .fn-tip.visible,
+        .citation-tip.visible {
+          opacity: 1;
+          visibility: visible;
+        }
+        /* The tooltip is centred on its marker, so a marker near the right
+           margin pushes it past the edge -- at 440px a 232px tooltip on a
+           marker at x=329 ended 5px off-screen. Capping the width cannot fix
+           that: the box was already well inside its limit and the problem is
+           where it sits, not how wide it is.
+           
+           The script measures each tooltip after showing it and nudges it back
+           inside, because only the browser knows where the marker landed after
+           the line wrapped. The CSS keeps the centring as the starting point;
+           anything that fits is left alone. */
+        @media (max-width: 380px) {
+          .fn-tip,
+          .citation-tip {
+            left: auto;
+            right: auto;
+            transform: none;
+          }
+        }
 
       </style>
       <script>
@@ -805,6 +867,125 @@ cat << _EOF_
             applyTheme(newTheme);
             localStorage.setItem('theme', newTheme);
           });
+
+          // Initialize footnote and citation tooltips
+          function initTooltips() {
+            // Footnotes: create tooltip elements with cloned content
+            var fnMarkers = document.querySelectorAll('.fnref[data-fnref]');
+            fnMarkers.forEach(function(marker) {
+              var fnId = marker.getAttribute('data-fnref');
+              var fnItem = document.getElementById('fn-' + fnId);
+              if (fnItem) {
+                // Extract content from .fn-text, but exclude the backref link
+                var fnText = fnItem.querySelector('.fn-text');
+                if (fnText) {
+                  // Clone and remove the backref
+                  var clone = fnText.cloneNode(true);
+                  var backref = clone.querySelector('.fn-backref');
+                  if (backref) {
+                    backref.parentNode.removeChild(backref);
+                  }
+                  // Create tooltip element with cloned content
+                  var tooltip = document.createElement('div');
+                  tooltip.className = 'fn-tip';
+                  tooltip.setAttribute('role', 'tooltip');
+                  // Move cloned children into tooltip
+                  while (clone.firstChild) {
+                    tooltip.appendChild(clone.firstChild);
+                  }
+                  marker.appendChild(tooltip);
+                }
+              }
+            });
+
+            // Citations: create tooltip elements with cloned content
+            var citationMarkers = document.querySelectorAll('.citation[data-citation]');
+            citationMarkers.forEach(function(marker) {
+              var cid = marker.getAttribute('data-citation');
+              var cnNum = marker.getAttribute('href').replace('#cn:', '');
+              var citItem = document.getElementById('cn:' + cnNum);
+              if (citItem) {
+                // Extract content from the paragraph, but exclude the reversecitation link
+                var citP = citItem.querySelector('p');
+                if (citP) {
+                  // Clone and remove the reversecitation link
+                  var clone = citP.cloneNode(true);
+                  var reverselink = clone.querySelector('.reversecitation');
+                  if (reverselink) {
+                    reverselink.parentNode.removeChild(reverselink);
+                  }
+                  // Create tooltip element with cloned content
+                  var tooltip = document.createElement('div');
+                  tooltip.className = 'citation-tip';
+                  tooltip.setAttribute('role', 'tooltip');
+                  // Move cloned children into tooltip
+                  while (clone.firstChild) {
+                    tooltip.appendChild(clone.firstChild);
+                  }
+                  marker.appendChild(tooltip);
+                }
+              }
+            });
+
+            // Shared close timer: on mouseleave, start timer; on mouseenter, cancel it.
+            // This allows the pointer to move from marker to tooltip without closing.
+            function attachTooltipHandlers(markers, tooltipClass) {
+              markers.forEach(function(marker) {
+                var tooltip = marker.querySelector('.' + tooltipClass);
+                if (!tooltip) return;
+                var closeTimer;
+
+                var showTooltip = function() {
+                  clearTimeout(closeTimer);
+                  // Reset before measuring: a previous nudge would otherwise be
+                  // measured as if it were the natural position.
+                  tooltip.style.marginLeft = '';
+                  tooltip.classList.add('visible');
+                  // Centred on its marker, a tooltip near a margin hangs off
+                  // the edge -- how far depends on where the marker landed
+                  // after the line wrapped, which only the browser knows. Shift
+                  // it back inside; anything that already fits is untouched.
+                  var box = tooltip.getBoundingClientRect();
+                  var edge = 8;
+                  var over = box.right - (document.documentElement.clientWidth - edge);
+                  var under = edge - box.left;
+                  if (over > 0) {
+                    tooltip.style.marginLeft = (-over) + 'px';
+                  } else if (under > 0) {
+                    tooltip.style.marginLeft = under + 'px';
+                  }
+                };
+
+                var scheduleHideTooltip = function() {
+                  closeTimer = setTimeout(function() {
+                    tooltip.classList.remove('visible');
+                  }, 150);
+                };
+
+                // Show on marker hover
+                marker.addEventListener('mouseenter', showTooltip);
+                marker.addEventListener('mouseleave', scheduleHideTooltip);
+
+                // Show on marker focus
+                marker.addEventListener('focusin', showTooltip);
+                marker.addEventListener('focusout', scheduleHideTooltip);
+
+                // Keep open while pointer is over tooltip
+                tooltip.addEventListener('mouseenter', showTooltip);
+                tooltip.addEventListener('mouseleave', scheduleHideTooltip);
+              });
+            }
+
+            attachTooltipHandlers(fnMarkers, 'fn-tip');
+            attachTooltipHandlers(citationMarkers, 'citation-tip');
+          }
+
+          // Run after DOM is ready
+          if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', initTooltips);
+          } else {
+            initTooltips();
+          }
         })();
       </script>
     </head>
diff --git a/share/jenny/layout/post.sh b/share/jenny/layout/post.sh
index 35cda3d..5e5621c 100755
--- a/share/jenny/layout/post.sh
+++ b/share/jenny/layout/post.sh
@@ -546,6 +546,68 @@ cat << _EOF_
         .theme-toggle:hover {
           background-color: var(--bg-secondary);
         }
+        /* Tooltip styling for footnote and citation references.
+           Rendered as real DOM elements so links remain interactive.
+           Appears on hover or focus, and survives pointer movement into it. */
+        .fnref[data-fnref],
+        .citation[data-citation] {
+          position: relative;
+        }
+        /* Tooltip is a real element, positioned absolutely. */
+        .fn-tip,
+        .citation-tip {
+          position: absolute;
+          bottom: 100%;
+          left: 50%;
+          transform: translateX(-50%);
+          background-color: var(--bg-secondary);
+          color: var(--text-primary);
+          border: 1px solid var(--border-medium);
+          border-radius: 3px;
+          padding: 0.5em 0.75em;
+          font-size: 0.85em;
+          line-height: 1.4;
+          white-space: normal;
+          max-width: min(280px, calc(100vw - 2em));
+          box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+          z-index: 1000;
+          opacity: 0;
+          visibility: hidden;
+          transition: none;
+          margin-bottom: 0.5em;
+          pointer-events: auto;
+        }
+        /* Tooltip links are clickable. */
+        .fn-tip a,
+        .citation-tip a {
+          color: var(--link-article);
+          text-decoration: underline;
+          cursor: pointer;
+        }
+        /* Show tooltip. */
+        .fn-tip.visible,
+        .citation-tip.visible {
+          opacity: 1;
+          visibility: visible;
+        }
+        /* The tooltip is centred on its marker, so a marker near the right
+           margin pushes it past the edge -- at 440px a 232px tooltip on a
+           marker at x=329 ended 5px off-screen. Capping the width cannot fix
+           that: the box was already well inside its limit and the problem is
+           where it sits, not how wide it is.
+           
+           The script measures each tooltip after showing it and nudges it back
+           inside, because only the browser knows where the marker landed after
+           the line wrapped. The CSS keeps the centring as the starting point;
+           anything that fits is left alone. */
+        @media (max-width: 380px) {
+          .fn-tip,
+          .citation-tip {
+            left: auto;
+            right: auto;
+            transform: none;
+          }
+        }
       </style>
       <script>
         (function() {
@@ -577,6 +639,125 @@ cat << _EOF_
             applyTheme(newTheme);
             localStorage.setItem('theme', newTheme);
           });
+
+          // Initialize footnote and citation tooltips
+          function initTooltips() {
+            // Footnotes: create tooltip elements with cloned content
+            var fnMarkers = document.querySelectorAll('.fnref[data-fnref]');
+            fnMarkers.forEach(function(marker) {
+              var fnId = marker.getAttribute('data-fnref');
+              var fnItem = document.getElementById('fn-' + fnId);
+              if (fnItem) {
+                // Extract content from .fn-text, but exclude the backref link
+                var fnText = fnItem.querySelector('.fn-text');
+                if (fnText) {
+                  // Clone and remove the backref
+                  var clone = fnText.cloneNode(true);
+                  var backref = clone.querySelector('.fn-backref');
+                  if (backref) {
+                    backref.parentNode.removeChild(backref);
+                  }
+                  // Create tooltip element with cloned content
+                  var tooltip = document.createElement('div');
+                  tooltip.className = 'fn-tip';
+                  tooltip.setAttribute('role', 'tooltip');
+                  // Move cloned children into tooltip
+                  while (clone.firstChild) {
+                    tooltip.appendChild(clone.firstChild);
+                  }
+                  marker.appendChild(tooltip);
+                }
+              }
+            });
+
+            // Citations: create tooltip elements with cloned content
+            var citationMarkers = document.querySelectorAll('.citation[data-citation]');
+            citationMarkers.forEach(function(marker) {
+              var cid = marker.getAttribute('data-citation');
+              var cnNum = marker.getAttribute('href').replace('#cn:', '');
+              var citItem = document.getElementById('cn:' + cnNum);
+              if (citItem) {
+                // Extract content from the paragraph, but exclude the reversecitation link
+                var citP = citItem.querySelector('p');
+                if (citP) {
+                  // Clone and remove the reversecitation link
+                  var clone = citP.cloneNode(true);
+                  var reverselink = clone.querySelector('.reversecitation');
+                  if (reverselink) {
+                    reverselink.parentNode.removeChild(reverselink);
+                  }
+                  // Create tooltip element with cloned content
+                  var tooltip = document.createElement('div');
+                  tooltip.className = 'citation-tip';
+                  tooltip.setAttribute('role', 'tooltip');
+                  // Move cloned children into tooltip
+                  while (clone.firstChild) {
+                    tooltip.appendChild(clone.firstChild);
+                  }
+                  marker.appendChild(tooltip);
+                }
+              }
+            });
+
+            // Shared close timer: on mouseleave, start timer; on mouseenter, cancel it.
+            // This allows the pointer to move from marker to tooltip without closing.
+            function attachTooltipHandlers(markers, tooltipClass) {
+              markers.forEach(function(marker) {
+                var tooltip = marker.querySelector('.' + tooltipClass);
+                if (!tooltip) return;
+                var closeTimer;
+
+                var showTooltip = function() {
+                  clearTimeout(closeTimer);
+                  // Reset before measuring: a previous nudge would otherwise be
+                  // measured as if it were the natural position.
+                  tooltip.style.marginLeft = '';
+                  tooltip.classList.add('visible');
+                  // Centred on its marker, a tooltip near a margin hangs off
+                  // the edge -- how far depends on where the marker landed
+                  // after the line wrapped, which only the browser knows. Shift
+                  // it back inside; anything that already fits is untouched.
+                  var box = tooltip.getBoundingClientRect();
+                  var edge = 8;
+                  var over = box.right - (document.documentElement.clientWidth - edge);
+                  var under = edge - box.left;
+                  if (over > 0) {
+                    tooltip.style.marginLeft = (-over) + 'px';
+                  } else if (under > 0) {
+                    tooltip.style.marginLeft = under + 'px';
+                  }
+                };
+
+                var scheduleHideTooltip = function() {
+                  closeTimer = setTimeout(function() {
+                    tooltip.classList.remove('visible');
+                  }, 150);
+                };
+
+                // Show on marker hover
+                marker.addEventListener('mouseenter', showTooltip);
+                marker.addEventListener('mouseleave', scheduleHideTooltip);
+
+                // Show on marker focus
+                marker.addEventListener('focusin', showTooltip);
+                marker.addEventListener('focusout', scheduleHideTooltip);
+
+                // Keep open while pointer is over tooltip
+                tooltip.addEventListener('mouseenter', showTooltip);
+                tooltip.addEventListener('mouseleave', scheduleHideTooltip);
+              });
+            }
+
+            attachTooltipHandlers(fnMarkers, 'fn-tip');
+            attachTooltipHandlers(citationMarkers, 'citation-tip');
+          }
+
+          // Run after DOM is ready
+          if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', initTooltips);
+          } else {
+            initTooltips();
+          }
         })();
       </script>
     </head>
diff --git a/share/jenny/lib/md2html.awk b/share/jenny/lib/md2html.awk
index c300eae..3fd54c9 100755
--- a/share/jenny/lib/md2html.awk
+++ b/share/jenny/lib/md2html.awk
@@ -180,7 +180,7 @@ function nextil(t) {
 		cloc = cite_locator;
 		cite_locator = "";
 		clabel = (cloc != "") ? "(" cloc ", " cnum ")" : "(" cnum ")";
-		return t1 "<a href=\"#cn:" cnum "\" id=\"cnref:" cnum \
+		return t1 "<a href=\"#cn:" cnum "\" id=\"cnref:" cnum "\" data-citation=\"" cid \
 			"\" title=\"see citation\" class=\"citation\">" clabel "</a>" nextil(t2);
 	}
 
@@ -189,7 +189,7 @@ function nextil(t) {
 		match(t2, /^[^\]]*(\[[^\]]*\][^\]]*)*/);
 		linktext = substr(t2, 1, RLENGTH);
 		t2 = substr(t2, RLENGTH + 2);
-    return t1 "<sup class=\"fnref\"><a href=\"#fn-" linktext "\" id=\"fnref-" linktext "\">" linktext "</a></sup>" nextil(t2);
+    return t1 "<sup class=\"fnref\" data-fnref=\"" linktext "\"><a href=\"#fn-" linktext "\" id=\"fnref-" linktext "\">" linktext "</a></sup>" nextil(t2);
 	}
 	# Links
 	if(tag == "["){
diff --git a/test/regressions.sh b/test/regressions.sh
index e18a687..b9809fb 100755
--- a/test/regressions.sh
+++ b/test/regressions.sh
@@ -1114,10 +1114,51 @@ it "a sibling links back to the directory, not the site root"
 sib_head=$("$GREP" -o '<header>.*</header>' "$ix/.dist/thesis/mdd/artifacts.html" | head -1)
 assert_contains "$sib_head" 'href="../../thesis/mdd/">mdd</a>'
 
-it "a directory with no index still points home"
-# Nothing to link to there, so the old behaviour is right and stays.
+it "a directory without its own index gets a generated one"
+# A crumb that led to the site root looked like navigation and was not. Every
+# section now has a page, so every segment leads somewhere it says it does.
+assert_file_exists "$ix/.dist/notes/method/index.html"
 no_ix=$("$GREP" -o '<header>.*</header>' "$ix/.dist/notes/method/intro.html" | head -1)
-assert_contains "$no_ix" 'href="../../">method</a>'
+assert_contains "$no_ix" 'href="../../notes/method/">method</a>'
+
+it "the generated listing names the pages under it"
+# The page's own title, not its slug: the listing is for a reader, and the
+# title is what the author called it.
+assert_file_contains "$ix/.dist/notes/method/index.html" '/notes/method/intro'
+
+it "each entry gets its own row"
+# Not a bullet list, and not one run-together line: markdown joins adjacent
+# lines into a single paragraph, so the entries are separated by a blank line
+# and each becomes its own paragraph.
+mkdir -p "$ix/pages/docs"
+printf '# Alpha One\n\nx\n' > "$ix/pages/docs/alpha.md"
+printf '# Beta Two\n\nx\n' > "$ix/pages/docs/beta.md"
+run_jenny_split "$ix"
+rows=$("$GREP" -c '<p><a href="/docs/' "$ix/.dist/docs/index.html")
+assert_eq "$rows" "2"
+assert_file_not_contains "$ix/.dist/docs/index.html" '<li><a href="/docs/'
+
+it "a label derived from a path is title cased"
+# "migration driven development" is a slug read aloud, not something anyone
+# wrote, so presenting it lowercase looks like a mistake.
+assert_file_contains "$ix/.dist/docs/index.html" '>Docs<'
+
+it "a page's own title keeps the author's casing"
+# Only derived labels are re-cased. A title with a deliberate lowercase word
+# must survive: "Method, an Introduction" must not become "Method, An
+# Introduction".
+printf '# Method, an Introduction\n\nBody.\n' > "$ix/pages/notes/method/intro.md"
+run_jenny_split "$ix"
+assert_file_contains "$ix/.dist/notes/method/index.html" 'Method, an Introduction'
+
+it "a generated listing is marked so it can be swept"
+# It is written into the source tree, which is where render_pages reads from.
+# Unmarked, a directory that later gains a real index.md would keep the
+# generated one and the author's page would never render.
+assert_file_contains "$ix/pages/notes/method/index.md" 'generated-section-index'
+
+it "a hand-written index is never overwritten"
+assert_file_not_contains "$ix/pages/thesis/mdd/index.md" 'generated-section-index'
 
 it "a page whose name merely starts with index keeps its crumb"
 # The rule fires on a segment named exactly "index"; "indexing" is a page like
@@ -2357,4 +2398,110 @@ assert_file_contains "$nav_sb/.dist/test.html" '--text-muted'
 assert_file_contains "$nav_sb/.dist/test.html" '--link-nav'
 assert_file_contains "$nav_sb/.dist/test.html" '--bg-primary'
 
+suite "Footnote and citation tooltips"
+
+# Build a blog with a post containing footnotes and citations.
+tt="$TMPROOT/tooltips"
+make_blog_min "$tt" 1 10
+printf '# Test Post\n\nText with a footnote[^1] and a citation[#myref].\n\n[^1]: This is the footnote text.\n\n[#myref]: This is the citation text.' > "$tt/2024-01-01 tooltips.md"
+run_jenny "$tt"
+tt_post="$tt/.dist/post/tooltips.html"
+
+it "footnote markers get a data-fnref attribute"
+# Markers store the footnote ID for JavaScript to look up the text.
+assert_file_contains "$tt_post" 'data-fnref='
+
+it "citation markers get a data-citation attribute"
+# Citation markers store the citation ID for JavaScript lookup.
+assert_file_contains "$tt_post" 'data-citation='
+
+it "tooltip CSS classes exist for footnotes"
+# Tooltips are real elements with fn-tip class.
+assert_file_contains "$tt_post" '.fn-tip'
+
+it "tooltip CSS classes exist for citations"
+# Citation tooltips use citation-tip class.
+assert_file_contains "$tt_post" '.citation-tip {'
+
+it "tooltip elements are positioned absolutely"
+# Tooltips must be positioned absolutely to overlay.
+assert_file_contains "$tt_post" 'position: absolute'
+
+it "tooltips become visible when class is applied"
+# The .visible class toggled by JavaScript.
+assert_file_contains "$tt_post" '.fn-tip.visible'
+
+it "tooltips show on keyboard focus events"
+# Script listens to focusin and focusout.
+assert_file_contains "$tt_post" "addEventListener('focusin'"
+
+it "a tooltip is kept inside the viewport by measurement, not a breakpoint"
+# Centred on its marker, a tooltip near the right margin hangs off the edge --
+# at 440px a 232px tooltip on a marker at x=329 ended 5px off-screen, while its
+# max-width was still well within the cap. Capping the width cannot fix a
+# position problem, and a breakpoint written for 320px left every width between
+# there and the desktop case unguarded.
+#
+# Only the browser knows where the marker landed after the line wrapped, so the
+# tooltip is measured once shown and nudged back inside.
+assert_file_contains "$tt_post" 'tooltip.getBoundingClientRect()'
+# The shift must be BY the overflow, not a constant: setting it to a fixed
+# value leaves the tooltip wherever it was and still satisfies a test that only
+# looks for the property name.
+assert_file_contains "$tt_post" "marginLeft = (-over) + 'px'"
+assert_file_contains "$tt_post" "marginLeft = under + 'px'"
+assert_file_contains "$tt_post" 'clientWidth'
+
+it "the nudge is reset before each measurement"
+# Otherwise a previous shift is measured as if it were the natural position and
+# the tooltip walks further off-screen each time it is shown.
+assert_file_contains "$tt_post" "tooltip.style.marginLeft = '';"
+
+it "showing a tooltip cancels any pending hide"
+# The bridge is what lets the pointer cross the gap from marker to tooltip: on
+# leaving either, a hide is scheduled; on entering either, it must be cancelled.
+# Without the cancel the tooltip closes underneath a pointer that is heading
+# for it, and every link inside becomes unreachable.
+assert_file_contains "$tt_post" 'clearTimeout(closeTimer);'
+
+it "tooltips have a shared close timer bridge"
+# Prevents closing when pointer moves from marker to tooltip.
+assert_file_contains "$tt_post" 'closeTimer = setTimeout'
+
+it "tooltips have no animation"
+# transition: none ensures instant appearance with no fade/delay.
+assert_file_contains "$tt_post" 'transition: none'
+
+it "tooltips are positioned absolutely"
+# Tooltips must not push page content around or cause overflow.
+assert_file_contains "$tt_post" 'position: absolute'
+
+it "footnote backref is not shown in tooltip"
+# The backref link (&#x21A9;) must be stripped from tooltip text.
+# This is verified by checking the script removes .fn-backref elements.
+assert_file_contains "$tt_post" 'backref.parentNode.removeChild(backref)'
+
+it "citation reverselink is not shown in tooltip"
+# The reverselink (&#160;&#8617;) must be stripped from citation tooltips.
+assert_file_contains "$tt_post" 'reverselink.parentNode.removeChild(reverselink)'
+
+it "tooltips handle narrow viewports"
+# At 320px, tooltips must not overflow the viewport.
+assert_file_contains "$tt_post" '@media (max-width: 380px)'
+
+it "tooltip initialization runs after DOM is ready"
+# Script checks document.readyState to avoid accessing elements before they exist.
+assert_file_contains "$tt_post" "document.readyState === 'loading'"
+
+it "footnote text is extracted from fn-text span"
+# The script queries .fn-text to find the content to display.
+assert_file_contains "$tt_post" "querySelector('.fn-text')"
+
+it "citation text is extracted from the paragraph"
+# Citations live in a <p> inside the <li>.
+assert_file_contains "$tt_post" "querySelector('p')"
+
+it "the build is clean"
+assert_eq "$stderr_output" ""
+
 summary