docs: full UX polish pass — copy-link anchors, back-to-top, scrollspy

Three coordinated additions to the /docs surface, finishing the
docs UX polish thread.

1. Copy-link on `.docs-anchor` clicks
   The `#` next to every h2 was a dead navigation link.  Now a
   delegated click handler at DocsPage level intercepts every click
   on `.docs-anchor`:
   - copies `window.location.origin + pathname + href` to the
     clipboard via navigator.clipboard.writeText
   - updates the URL bar via history.pushState so the deep-link is
     shareable from the address bar too
   - smooth-scrolls the target heading into view
   - fires a toast confirmation
   Single handler instead of touching 19 individual section files.
   Cursor now pointer + accent-green hover so the affordance is
   discoverable.

2. Back-to-top floating button
   New BackToTopButton component fixed bottom-right.  Hidden until
   `window.scrollY > 600`, then fades in with a small upward slide.
   Smooth-scrolls to top on click.  Circular accent-green chip with
   hover lift.  Mobile-safe inset via clamp().  z-index 50 so it
   sits above body content but below modals.

3. Sidebar scrollspy
   useScrollspy hook backed by IntersectionObserver, observing every
   section id in DOC_SECTIONS.  Active section is the topmost one
   whose `boundingClientRect.top` is <= 80px (i.e. the heading just
   crossed the page-top zone).  Falls back to the first intersecting
   section when scrolled to the very top of the page.  Uses both IO
   boundary events AND a passive scroll listener to recompute, since
   IO alone misses slow scrolls between two co-intersecting sections.
   Active state in CSS: stronger background + bold + 3px inset
   accent-green left bar so the active group is visible from
   peripheral vision.

useToasts hook reused from existing infrastructure.  No new deps,
no new state-management surface.  All three features are progressive
enhancement — page works fully without JS (copy-link falls back to
URL-bar visibility, back-to-top simply doesn't render, scrollspy
just doesn't highlight).

Author: Sbussiso

frontend/src/pages/DocsPage.jsx

@@ -1,6 +1,8 @@
+import { useEffect, useState } from "react"
 import { Link } from "react-router-dom"
 
 import { DocsProvider } from "./docs/context"
+import { useToasts } from "../hooks/useToasts.jsx"
 
 // One file per <section>. Each component is self-contained — sections that
 // need shared state (the OS-tabs choice, the Copy-button toast) pull it from
@@ -27,7 +29,133 @@ import ApiRateLimits from "./docs/ApiRateLimits"
 import Resources from "./docs/Resources"
 
 
-function DocsSidebar() {
+// Order matches the sidebar order — drives the scrollspy's "topmost
+// visible section" calculation.  Each entry is the section's id.
+const DOC_SECTIONS = [
+  "getting-started",
+  "architecture",
+  "cloudnode-setup",
+  "configuration",
+  "deployment",
+  "motion-detection",
+  "terminal-dashboard",
+  "dashboard",
+  "recording",
+  "camera-groups",
+  "notifications",
+  "mcp",
+  "sentinel",
+  "plans",
+  "security-procedures",
+  "troubleshooting",
+  "faq",
+  "api-reference",
+  "api-rate-limits",
+]
+
+
+/**
+ * Highlights the sidebar link matching whichever section is currently
+ * topmost-visible in the viewport.  Uses a single IntersectionObserver
+ * scoped to the section IDs in DOC_SECTIONS.
+ *
+ * The "active" section is the one with the smallest non-negative
+ * `boundingClientRect.top` — i.e. the one that just entered (or is
+ * about to enter) the top of the viewport.  Falls back to the
+ * highest-positioned section among the currently-intersecting set
+ * when nothing has entered yet (e.g. when the page loads scrolled
+ * mid-document).
+ */
+function useScrollspy(sectionIds) {
+  const [activeId, setActiveId] = useState(sectionIds[0] || "")
+
+  useEffect(() => {
+    if (typeof IntersectionObserver === "undefined") return
+
+    const visible = new Map()
+
+    const recompute = () => {
+      // Pick the section whose top is closest to (but not far below)
+      // the viewport top.  Sections above the fold have negative top
+      // values; we want the largest of those (closest to zero).
+      let bestId = null
+      let bestTop = -Infinity
+      for (const [id, top] of visible) {
+        if (top <= 80 && top > bestTop) {
+          bestTop = top
+          bestId = id
+        }
+      }
+      // If nothing is above the fold (we're at the top of the page),
+      // pick the topmost intersecting section.
+      if (!bestId) {
+        let lowestTop = Infinity
+        for (const [id, top] of visible) {
+          if (top < lowestTop) {
+            lowestTop = top
+            bestId = id
+          }
+        }
+      }
+      if (bestId) setActiveId(bestId)
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const id = entry.target.id
+          if (entry.isIntersecting) {
+            visible.set(id, entry.boundingClientRect.top)
+          } else {
+            visible.delete(id)
+          }
+        }
+        recompute()
+      },
+      {
+        // rootMargin top -80px so a section is considered "active" once
+        // its heading scrolls under the page's sticky chrome (the docs
+        // page has no sticky bar today, but this leaves headroom for
+        // future "back to top" / breadcrumb additions).
+        rootMargin: "-80px 0px -60% 0px",
+        threshold: [0, 1],
+      },
+    )
+
+    const elements = sectionIds
+      .map((id) => document.getElementById(id))
+      .filter(Boolean)
+    elements.forEach((el) => observer.observe(el))
+
+    // Recompute on plain scroll too — IntersectionObserver only fires on
+    // boundary crossings, so a slow scroll between two intersecting
+    // sections wouldn't update the active state otherwise.
+    const onScroll = () => {
+      for (const el of elements) {
+        const rect = el.getBoundingClientRect()
+        visible.set(el.id, rect.top)
+      }
+      recompute()
+    }
+    window.addEventListener("scroll", onScroll, { passive: true })
+
+    return () => {
+      observer.disconnect()
+      window.removeEventListener("scroll", onScroll)
+    }
+  }, [sectionIds])
+
+  return activeId
+}
+
+
+function DocsSidebar({ activeId }) {
+  // Render each link with an active class when its href matches the
+  // currently-spied section.  className is computed at render time so
+  // React doesn't have to re-mount the <a>s on every active change.
+  const linkClass = (id) =>
+    `docs-sidebar-link${activeId === id ? " active" : ""}`
+
   return (
     <aside className="docs-sidebar">
       <div className="docs-sidebar-header">
@@ -37,46 +165,46 @@ function DocsSidebar() {
       <nav className="docs-sidebar-nav">
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">Introduction</div>
-          <a href="#getting-started" className="docs-sidebar-link">Getting Started</a>
-          <a href="#architecture" className="docs-sidebar-link">Architecture</a>
+          <a href="#getting-started" className={linkClass("getting-started")}>Getting Started</a>
+          <a href="#architecture" className={linkClass("architecture")}>Architecture</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">CloudNode</div>
-          <a href="#cloudnode-setup" className="docs-sidebar-link">Setup</a>
-          <a href="#configuration" className="docs-sidebar-link">Configuration</a>
-          <a href="#deployment" className="docs-sidebar-link">Deployment</a>
-          <a href="#motion-detection" className="docs-sidebar-link">Motion Detection</a>
-          <a href="#terminal-dashboard" className="docs-sidebar-link">Terminal Dashboard</a>
+          <a href="#cloudnode-setup" className={linkClass("cloudnode-setup")}>Setup</a>
+          <a href="#configuration" className={linkClass("configuration")}>Configuration</a>
+          <a href="#deployment" className={linkClass("deployment")}>Deployment</a>
+          <a href="#motion-detection" className={linkClass("motion-detection")}>Motion Detection</a>
+          <a href="#terminal-dashboard" className={linkClass("terminal-dashboard")}>Terminal Dashboard</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">Command Center</div>
-          <a href="#dashboard" className="docs-sidebar-link">Dashboard & Features</a>
-          <a href="#recording" className="docs-sidebar-link">Recording & Retention</a>
-          <a href="#camera-groups" className="docs-sidebar-link">Camera Groups</a>
-          <a href="#notifications" className="docs-sidebar-link">Notifications</a>
+          <a href="#dashboard" className={linkClass("dashboard")}>Dashboard & Features</a>
+          <a href="#recording" className={linkClass("recording")}>Recording & Retention</a>
+          <a href="#camera-groups" className={linkClass("camera-groups")}>Camera Groups</a>
+          <a href="#notifications" className={linkClass("notifications")}>Notifications</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">Integrations</div>
-          <a href="#mcp" className="docs-sidebar-link">MCP Integration</a>
+          <a href="#mcp" className={linkClass("mcp")}>MCP Integration</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">AI Agent</div>
-          <a href="#sentinel" className="docs-sidebar-link">Sentinel</a>
+          <a href="#sentinel" className={linkClass("sentinel")}>Sentinel</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">Account & Security</div>
-          <a href="#plans" className="docs-sidebar-link">Plans & Limits</a>
-          <a href="#security-procedures" className="docs-sidebar-link">Security Procedures</a>
+          <a href="#plans" className={linkClass("plans")}>Plans & Limits</a>
+          <a href="#security-procedures" className={linkClass("security-procedures")}>Security Procedures</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">Help</div>
-          <a href="#troubleshooting" className="docs-sidebar-link">Troubleshooting</a>
-          <a href="#faq" className="docs-sidebar-link">FAQ</a>
+          <a href="#troubleshooting" className={linkClass("troubleshooting")}>Troubleshooting</a>
+          <a href="#faq" className={linkClass("faq")}>FAQ</a>
         </div>
         <div className="docs-sidebar-group">
           <div className="docs-sidebar-group-label">Reference</div>
-          <a href="#api-reference" className="docs-sidebar-link">API Reference</a>
-          <a href="#api-rate-limits" className="docs-sidebar-link">API Rate Limits</a>
+          <a href="#api-reference" className={linkClass("api-reference")}>API Reference</a>
+          <a href="#api-rate-limits" className={linkClass("api-rate-limits")}>API Rate Limits</a>
         </div>
       </nav>
       <div className="docs-sidebar-footer">
@@ -89,11 +217,95 @@ function DocsSidebar() {
 }
 
 
+/**
+ * Floating Back-to-top button.  Fades in once the page is scrolled
+ * past ~600px; smooth-scrolls back on click.  Position is fixed
+ * bottom-right with a generous mobile-safe inset.  Single instance
+ * mounted by DocsPage — not shared across the app, since other pages
+ * are short enough not to need it.
+ */
+function BackToTopButton() {
+  const [visible, setVisible] = useState(false)
+
+  useEffect(() => {
+    const onScroll = () => setVisible(window.scrollY > 600)
+    onScroll()
+    window.addEventListener("scroll", onScroll, { passive: true })
+    return () => window.removeEventListener("scroll", onScroll)
+  }, [])
+
+  return (
+    <button
+      type="button"
+      className={`docs-back-to-top${visible ? " visible" : ""}`}
+      onClick={() => window.scrollTo({ top: 0, behavior: "smooth" })}
+      aria-label="Back to top"
+      title="Back to top"
+    >
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+        <line x1="12" y1="19" x2="12" y2="5" />
+        <polyline points="5 12 12 5 19 12" />
+      </svg>
+    </button>
+  )
+}
+
+
 function DocsPage() {
+  const { showToast } = useToasts()
+  const activeId = useScrollspy(DOC_SECTIONS)
+
+  // Delegated click handler for any `.docs-anchor` link inside a docs
+  // heading.  Three things on click:
+  //   1. Copy the full URL+hash to the clipboard.
+  //   2. Update the URL bar via history.pushState (so the link IS
+  //      shareable from the address bar too).
+  //   3. Smooth-scroll the target heading into view.
+  // Single handler bound to the document instead of touching 19
+  // individual section files.
+  useEffect(() => {
+    const handler = (event) => {
+      const anchor = event.target.closest(".docs-anchor")
+      if (!anchor) return
+      event.preventDefault()
+      const href = anchor.getAttribute("href") || ""
+      const targetId = href.startsWith("#") ? href.slice(1) : ""
+      const fullUrl = `${window.location.origin}${window.location.pathname}${href}`
+
+      // Update history first so the URL bar shows the deep-link.  We
+      // use pushState rather than assigning location.hash because the
+      // latter triggers a default scroll-jump that competes with our
+      // smooth-scroll.
+      window.history.pushState(null, "", href)
+
+      // Smooth-scroll to the target.  Falls back silently if the
+      // element doesn't exist (shouldn't happen — every `.docs-anchor`
+      // we render points at its parent section's id).
+      if (targetId) {
+        const target = document.getElementById(targetId)
+        if (target) target.scrollIntoView({ behavior: "smooth", block: "start" })
+      }
+
+      // Copy to clipboard + toast.  Clipboard API requires a secure
+      // context; if we don't have it (rare — local file:// preview),
+      // we silently skip the copy and rely on the URL bar update.
+      if (navigator.clipboard?.writeText) {
+        navigator.clipboard.writeText(fullUrl).then(
+          () => showToast("Link copied to clipboard", "success"),
+          () => showToast("Couldn't copy — clipboard blocked", "error"),
+        )
+      } else {
+        showToast("Link in URL bar — copy manually", "info")
+      }
+    }
+    document.addEventListener("click", handler)
+    return () => document.removeEventListener("click", handler)
+  }, [showToast])
+
   return (
     <DocsProvider>
       <div className="docs-layout">
-        <DocsSidebar />
+        <DocsSidebar activeId={activeId} />
         <main className="docs-content">
           <div className="docs-content-inner">
             <div className="docs-hero-banner" aria-hidden="true">
@@ -142,6 +354,7 @@ function DocsPage() {
             </div>
           </div>
         </main>
+        <BackToTopButton />
       </div>
     </DocsProvider>
   )

frontend/src/styles/landing.css

@@ -993,6 +993,77 @@
   color: var(--accent-green);
 }
 
+/* Scrollspy active state — applied by useScrollspy() to whichever
+   sidebar link matches the topmost-visible section in the viewport.
+   Stronger visual than :hover so the user can find their place at
+   a glance.  Left-edge accent bar makes the active group visible
+   from peripheral vision. */
+.docs-sidebar-link.active {
+  background: rgba(34, 197, 94, 0.16);
+  color: var(--accent-green);
+  font-weight: 600;
+  box-shadow: inset 3px 0 0 var(--accent-green);
+}
+
+.docs-sidebar-link.active:hover {
+  background: rgba(34, 197, 94, 0.22);
+}
+
+/* Floating Back-to-top button — DocsPage only.  Fades in once the
+   page is scrolled past ~600px, fades out near the top.  Bottom-right
+   with a generous mobile-safe inset; circular, accent-green, with a
+   subtle elevation shadow that lifts on hover. */
+.docs-back-to-top {
+  position: fixed;
+  right: clamp(1rem, 4vw, 2rem);
+  bottom: clamp(1rem, 4vw, 2rem);
+  width: 44px;
+  height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  border: 1px solid rgba(34, 197, 94, 0.4);
+  background: var(--bg-card);
+  color: var(--accent-green);
+  cursor: pointer;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.35);
+  opacity: 0;
+  transform: translateY(8px);
+  pointer-events: none;
+  transition: opacity 0.2s ease, transform 0.2s ease, box-shadow 0.2s ease, background 0.15s ease;
+  z-index: 50;
+}
+
+.docs-back-to-top.visible {
+  opacity: 1;
+  transform: translateY(0);
+  pointer-events: auto;
+}
+
+.docs-back-to-top:hover {
+  background: rgba(34, 197, 94, 0.16);
+  box-shadow: 0 6px 22px rgba(34, 197, 94, 0.28);
+}
+
+.docs-back-to-top:focus-visible {
+  outline: 2px solid var(--accent-green);
+  outline-offset: 3px;
+}
+
+/* Anchor `#` next to docs headings — make it clearly clickable.
+   Was opacity:0 by default and revealed on h2 hover only; now
+   reveals on h2/h3 hover AND has cursor:pointer so the click-to-
+   copy affordance is discoverable.  Hover state on the anchor
+   itself shifts to the accent color. */
+.docs-anchor {
+  cursor: pointer;
+}
+
+.docs-anchor:hover {
+  color: var(--accent-green) !important;
+}
+
 .docs-concepts-grid {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));