From ac7f11976040f3975215d77a254d48c04a3b151b Mon Sep 17 00:00:00 2001
From: Luan Nguyen <luannn010@gmail.com>
Date: Thu, 12 Nov 2026 01:50:09 +1100
Subject: [PATCH] feat(notes): match sidebar selection geometry and motion

---
 docs/architecture.md                          |  22 ++
 web/src/styles/app.css                        |  47 +++
 web/src/ui/SidebarSelection.tsx               | 288 ++++++++++++++++++
 web/src/ui/Workspace.tsx                      | 112 ++++++-
 .../integration/sidebar-selection-browser.mjs | 176 +++++++++++
 web/tests/ui/sidebar-selection.test.tsx       | 254 +++++++++++++++
 6 files changed, 893 insertions(+), 6 deletions(-)
 create mode 100644 web/src/ui/SidebarSelection.tsx
 create mode 100644 web/tests/integration/sidebar-selection-browser.mjs
 create mode 100644 web/tests/ui/sidebar-selection.test.tsx

diff --git a/docs/architecture.md b/docs/architecture.md
index a393094..c31caf5 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -268,3 +268,25 @@ is deduplicated into the library, then navigation guards are checked again befor
 opening it. If new work blocks navigation, the created note remains in the
 library with a truthful notice; it is not automatically opened later. Account,
 store, unmount and observed epoch invalidations retire result/focus tickets.
+
+
+## Sidebar selection presentation
+
+Notes sidebar rows use 29px boxes with 1px gaps. A single pointer-inert,
+aria-hidden highlight follows the actual admitted route row, using checked
+untransformed layout offsets rather than a row index or the pressed button's
+scaled rectangle. Same-layout selection moves 200ms; label color changes 150ms.
+Reduced motion jumps the highlight while retaining the label-color fade.
+Geometry/order/width/scroll/show changes settle immediately.
+
+Workspace registers concrete buttons with content-free route keys or opaque
+catalog IDs/current-only symbols. The controller retains DOM handles and scalar
+geometry only. Owner invalidation synchronously hides and latches the controller,
+clears handles/previous geometry and retires callbacks before projection clearing.
+Only a successful current-owner library/list read admits a fresh ref generation;
+a generic rerender cannot revive the old target. Ordinary same-scope reads do not
+reset movement. ResizeObserver initial delivery does not cancel an unchanged move.
+No route admission depends on motion completion and no heading/label snapshot is
+cloned. Current-heading opacity remains a separately owned qualification gap.
+Design revision f610ced1da443b04699137333c1309925092fffa: Notes `layout-desktop`
+and Motion `sidenav` (Notes/Motion blobs unchanged from 95bd47e).
diff --git a/web/src/styles/app.css b/web/src/styles/app.css
index 51287a1..dad07ff 100644
--- a/web/src/styles/app.css
+++ b/web/src/styles/app.css
@@ -1073,3 +1073,50 @@ dialog p {
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+
+/* Notes706a8d07 geometry; Motionaed675f3 #sidenav. */
+.sidebar {
+  position: relative;
+  isolation: isolate;
+  gap: 1px;
+}
+.sidebar > nav {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.sidebar .nav {
+  position: relative;
+  z-index: 1;
+  height: 29px;
+  min-height: 29px;
+  flex-shrink: 0;
+  margin-bottom: 0;
+  transition: background-color 150ms cubic-bezier(.4,0,.2,1), box-shadow 150ms cubic-bezier(.4,0,.2,1), transform 150ms cubic-bezier(.4,0,.2,1), color 150ms cubic-bezier(.4,0,.2,1);
+}
+.sidebar .search { margin-bottom: 4px; }
+.sidebar .tag-swatch { width: 8px; height: 8px; border-radius: 3px; margin-right: 0; }
+.sidebar footer { display: flex; flex-direction: column; gap: 6px; padding-top: 0; flex-shrink: 0; }
+.sidebar footer p { margin: 0; }
+.sidebar-selection-highlight {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 0;
+  border-radius: 8px;
+  background: var(--sel);
+  pointer-events: none;
+  transition: none;
+}
+.sidebar-selection-highlight[data-animate="true"] { transition: transform 200ms cubic-bezier(.2,.8,.2,1); }
+.sidebar[data-sidebar-selection-ready="true"] .nav.active { background: transparent; }
+@media (prefers-reduced-motion: reduce) {
+  :root:not([data-motion="on"]) .sidebar-selection-highlight { transition: none !important; }
+  :root:not([data-motion="on"]) .sidebar .nav {
+    transition: color 150ms cubic-bezier(.4,0,.2,1), background-color 150ms cubic-bezier(.4,0,.2,1), box-shadow 150ms cubic-bezier(.4,0,.2,1) !important;
+  }
+}
+:root[data-motion="reduced"] .sidebar-selection-highlight { transition: none !important; }
+:root[data-motion="reduced"] .sidebar .nav {
+  transition: color 150ms cubic-bezier(.4,0,.2,1), background-color 150ms cubic-bezier(.4,0,.2,1), box-shadow 150ms cubic-bezier(.4,0,.2,1) !important;
+}
diff --git a/web/src/ui/SidebarSelection.tsx b/web/src/ui/SidebarSelection.tsx
new file mode 100644
index 0000000..da87aa5
--- /dev/null
+++ b/web/src/ui/SidebarSelection.tsx
@@ -0,0 +1,288 @@
+import { useLayoutEffect, useRef, type RefCallback } from "react";
+
+export type SidebarSelectionKey = string | symbol;
+export type SidebarSelectionController = {
+  readonly rootRef: RefCallback<HTMLElement>;
+  rowRef: (key: SidebarSelectionKey) => RefCallback<HTMLButtonElement>;
+  invalidate: () => void;
+  admit: () => void;
+};
+type Input = {
+  controller: SidebarSelectionController;
+  activeKey: SidebarSelectionKey | null;
+  layoutVersion: number | string;
+  visible: boolean;
+  privacyRevision: number;
+};
+type Box = { x: number; y: number; width: number; height: number };
+type Position = Box & {
+  key: SidebarSelectionKey;
+  node: HTMLElement;
+  layout: Input["layoutVersion"];
+  privacy: number;
+  registration: number;
+  rootWidth: number;
+  rootHeight: number;
+};
+const sameBox = (a: Box, b: Box) =>
+  a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+const owners = new WeakMap<SidebarSelectionController, SelectionOwner>();
+
+class SelectionOwner {
+  generation = 0;
+  registration = 0;
+  latched = false;
+  root: HTMLElement | null = null;
+  layer: HTMLElement | null = null;
+  rows = new Map<SidebarSelectionKey, Set<HTMLButtonElement>>();
+  callbacks = new Map<SidebarSelectionKey, RefCallback<HTMLButtonElement>>();
+  previous: Position | null = null;
+  input: Input | null = null;
+  observer: ResizeObserver | null = null;
+  observedRow: HTMLElement | null = null;
+  observedRoot: HTMLElement | null = null;
+  rootRef: RefCallback<HTMLElement> = () => {};
+  layerRef: RefCallback<HTMLElement> = () => {};
+  controller: SidebarSelectionController;
+
+  constructor() {
+    const owner = this;
+    this.controller = {
+      get rootRef() {
+        return owner.rootRef;
+      },
+      rowRef: (key) => owner.rowRef(key),
+      invalidate: () => owner.invalidate(),
+      admit: () => {
+        if (owner.latched) {
+          owner.latched = false;
+          owner.rotate();
+        }
+      },
+    };
+    owners.set(this.controller, this);
+    this.rotate();
+  }
+  rotate() {
+    const generation = ++this.generation;
+    this.callbacks.clear();
+    this.rootRef = (node) => {
+      if (generation !== this.generation || this.latched) return;
+      this.root = node;
+      this.registration++;
+      if (!node) this.pause();
+      else this.measure();
+    };
+    this.layerRef = (node) => {
+      if (generation !== this.generation || this.latched) return;
+      this.layer = node;
+      if (node) node.hidden = true;
+    };
+  }
+  rowRef(key: SidebarSelectionKey): RefCallback<HTMLButtonElement> {
+    const existing = this.callbacks.get(key);
+    if (existing) return existing;
+    const generation = this.generation;
+    const callback: RefCallback<HTMLButtonElement> = (node) => {
+      if (generation !== this.generation || this.latched) return;
+      if (!node) {
+        this.rows.delete(key);
+        this.registration++;
+        return;
+      }
+      let nodes = this.rows.get(key);
+      if (!nodes) this.rows.set(key, (nodes = new Set()));
+      const registered = nodes;
+      registered.add(node);
+      this.registration++;
+      return () => {
+        if (generation !== this.generation) return;
+        registered.delete(node);
+        if (!registered.size) this.rows.delete(key);
+        this.registration++;
+        if (this.previous?.node === node) this.hide();
+      };
+    };
+    this.callbacks.set(key, callback);
+    return callback;
+  }
+  hide() {
+    this.root?.removeAttribute("data-sidebar-selection-ready");
+    if (this.layer) {
+      this.layer.hidden = true;
+      this.layer.dataset.animate = "false";
+      this.layer.style.transition = "none";
+      this.layer.style.transform = "none";
+    }
+    this.previous = null;
+  }
+  pause() {
+    this.hide();
+    this.observer?.disconnect();
+    this.observer = null;
+    this.observedRoot = this.observedRow = null;
+  }
+  invalidate() {
+    this.pause();
+    this.latched = true;
+    this.root = this.layer = null;
+    for (const nodes of this.rows.values()) nodes.clear();
+    this.rows.clear();
+    this.input = null;
+    this.rotate();
+  }
+  box(node: HTMLElement): Box | null {
+    const root = this.root;
+    if (
+      !root ||
+      !root.isConnected ||
+      !node.isConnected ||
+      !root.contains(node) ||
+      node.offsetParent !== root
+    )
+      return null;
+    const box = {
+      x: node.offsetLeft,
+      y: node.offsetTop,
+      width: node.offsetWidth,
+      height: node.offsetHeight,
+    };
+    if (
+      box.width <= 0 ||
+      box.height <= 0 ||
+      !Object.values(box).every(Number.isFinite)
+    )
+      return null;
+    return box;
+  }
+  measure(layoutChange = false) {
+    const input = this.input,
+      root = this.root,
+      layer = this.layer;
+    if (
+      this.latched ||
+      !input?.visible ||
+      !root ||
+      !layer ||
+      input.activeKey === null
+    ) {
+      this.hide();
+      return;
+    }
+    const nodes = this.rows.get(input.activeKey);
+    const node = nodes?.size === 1 ? nodes.values().next().value : null;
+    const box = node ? this.box(node) : null;
+    if (!node || !box) {
+      this.hide();
+      return;
+    }
+    const old = this.previous;
+    const oldBox = old && this.box(old.node);
+    const stable =
+      old &&
+      oldBox &&
+      sameBox(old, oldBox) &&
+      old.layout === input.layoutVersion &&
+      old.privacy === input.privacyRevision &&
+      old.registration === this.registration &&
+      old.rootWidth === root.clientWidth &&
+      old.rootHeight === root.clientHeight;
+    const changed = old && old.key !== input.activeKey;
+    const animate = !!(stable && changed && !layoutChange);
+    // A resize/scroll/DOM reflow settles even an already running transition.
+    if (layoutChange || !stable) {
+      layer.style.transition = "none";
+      layer.style.transform = `translate(${box.x}px, ${box.y}px)`;
+      void layer.offsetWidth;
+    }
+    if (changed || layoutChange || !stable) {
+      layer.dataset.animate = String(animate);
+      layer.style.transition = "";
+      layer.style.width = `${box.width}px`;
+      layer.style.height = `${box.height}px`;
+      layer.style.transform = `translate(${box.x}px, ${box.y}px)`;
+    }
+    layer.hidden = false;
+    root.dataset.sidebarSelectionReady = "true";
+    this.previous = {
+      ...box,
+      key: input.activeKey,
+      node,
+      layout: input.layoutVersion,
+      privacy: input.privacyRevision,
+      registration: this.registration,
+      rootWidth: root.clientWidth,
+      rootHeight: root.clientHeight,
+    };
+    this.observe(node);
+  }
+  observe(node: HTMLElement) {
+    const root = this.root;
+    if (!root || (this.observedRoot === root && this.observedRow === node))
+      return;
+    this.observer?.disconnect();
+    this.observedRoot = root;
+    this.observedRow = node;
+    if (typeof ResizeObserver === "undefined") return;
+    const generation = this.generation;
+    this.observer = new ResizeObserver(() => {
+      if (generation !== this.generation || this.latched) return;
+      const previous = this.previous;
+      const box = previous && this.box(previous.node);
+      if (
+        !previous ||
+        !box ||
+        !sameBox(previous, box) ||
+        previous.rootWidth !== root.clientWidth ||
+        previous.rootHeight !== root.clientHeight
+      )
+        this.measure(true);
+    });
+    this.observer.observe(root);
+    this.observer.observe(node);
+  }
+}
+
+export function useSidebarSelection(): SidebarSelectionController {
+  const owner = useRef<SelectionOwner | null>(null);
+  if (!owner.current) owner.current = new SelectionOwner();
+  useLayoutEffect(() => () => owner.current?.invalidate(), []);
+  return owner.current.controller;
+}
+
+export function SidebarSelection(props: Input) {
+  const owner = owners.get(props.controller);
+  useLayoutEffect(() => {
+    if (!owner) return;
+    owner.input = props;
+    owner.measure();
+  });
+  useLayoutEffect(() => {
+    if (!owner) return;
+    const onScroll = (event: Event) => {
+      const root = owner.root,
+        target = event.target;
+      if (
+        root &&
+        (target === document ||
+          target === window ||
+          (target instanceof HTMLElement &&
+            (target === root || target.contains(root))))
+      )
+        owner.measure(true);
+    };
+    window.addEventListener("scroll", onScroll, true);
+    return () => {
+      window.removeEventListener("scroll", onScroll, true);
+      owner.pause();
+    };
+  }, [owner]);
+  return (
+    <i
+      ref={owner?.layerRef}
+      className="sidebar-selection-highlight"
+      aria-hidden="true"
+      hidden
+    />
+  );
+}
diff --git a/web/src/ui/Workspace.tsx b/web/src/ui/Workspace.tsx
index 7a70db8..2231210 100644
--- a/web/src/ui/Workspace.tsx
+++ b/web/src/ui/Workspace.tsx
@@ -32,6 +32,11 @@ import { projectNotes, plainText, message } from "./model";
 import { Dialog, usePreferences } from "./primitives";
 import { SettingsView } from "./SettingsView";
 import { SidebarResize, useSidebarWidth } from "./SidebarResize";
+import {
+  SidebarSelection,
+  useSidebarSelection,
+  type SidebarSelectionKey,
+} from "./SidebarSelection";
 import type { SettingsLeaveGuard } from "./studySettingsTypes";
 import { NoteEditor } from "./NoteEditor";
 import { buildDownload } from "./download";
@@ -125,6 +130,31 @@ export function Workspace({
   session: AccountSession;
   onSignOut: () => Promise<void>;
 }) {
+  const sidebarSelection = useSidebarSelection();
+  const [sidebarPrivacy, setSidebarPrivacy] = useState(0);
+  const fallbackSidebarTags = useRef<symbol[]>([]);
+  const sidebarLayout = useRef<{
+    keys: SidebarSelectionKey[];
+    shape: string;
+    version: number;
+  }>({ keys: [], shape: "", version: 0 });
+  function invalidateSidebarSelection() {
+    sidebarSelection.invalidate();
+    readSequence.current++;
+    fallbackSidebarTags.current = [];
+    sidebarLayout.current.keys = [];
+    sidebarLayout.current.version++;
+    setSidebarPrivacy((value) => value + 1);
+  }
+  useLayoutEffect(
+    () => () => {
+      sidebarSelection.invalidate();
+      fallbackSidebarTags.current = [];
+      sidebarLayout.current.keys = [];
+      readSequence.current++;
+    },
+    [sidebarSelection, store, sourceOwner, session.accountId, session.deviceId],
+  );
   const [creatingNote, setCreatingNote] = useState(false);
   const createGeneration = useRef(0);
   const createInFlight = useRef<number | null>(null);
@@ -191,6 +221,7 @@ export function Workspace({
     null,
   );
   const links = useNoteLinkOwner(sourceOwner, (reason) => {
+    invalidateSidebarSelection();
     retireCreate();
     try {
       onNoteLinkScopeRevoked?.();
@@ -281,6 +312,7 @@ export function Workspace({
     setSourceUnavailable(null);
   }
   const sourceOwners = useStudySourceOwners(sourceOwner, session, () => {
+    invalidateSidebarSelection();
     retireCreate();
     revokeSearchScope();
     sourceRequest.current++;
@@ -326,6 +358,7 @@ export function Workspace({
     if (result.mode === "ready") {
       const nextEpoch = result.snapshot.token.epoch;
       if (adoptedEpoch.current && adoptedEpoch.current !== nextEpoch) {
+        invalidateSidebarSelection();
         retireCreate();
         selectedSnapshot.current = undefined;
         setSelected(null);
@@ -476,6 +509,14 @@ export function Workspace({
   const menuRef = useRef<HTMLButtonElement>(null);
   const settingsReturnFocus = useRef<HTMLElement | null>(null);
   const drawerRef = useRef<HTMLElement>(null);
+  const selectionRootRef = sidebarSelection.rootRef;
+  const sidebarRootRef = useMemo(
+    () => (node: HTMLElement | null) => {
+      drawerRef.current = node;
+      selectionRootRef(node);
+    },
+    [selectionRootRef],
+  );
   const drawerWasOpen = useRef(false);
   useEffect(() => {
     const input = fileRef.current;
@@ -543,10 +584,16 @@ export function Workspace({
     const sequence = ++readSequence.current;
     if (library) {
       const value = await library.read();
-      if (sequence === readSequence.current) adoptLibrary(value);
+      if (sequence === readSequence.current) {
+        adoptLibrary(value);
+        sidebarSelection.admit();
+      }
     } else {
       const value = await store.list();
-      if (sequence === readSequence.current) setNotes(value);
+      if (sequence === readSequence.current) {
+        sidebarSelection.admit();
+        setNotes(value);
+      }
     }
   }
   async function refresh() {
@@ -556,9 +603,11 @@ export function Workspace({
         const result = await library.read();
         if (sequence !== readSequence.current) return;
         adoptLibrary(result);
+        sidebarSelection.admit();
       } else {
         const result = await store.list();
         if (sequence !== readSequence.current) return;
+        sidebarSelection.admit();
         setNotes(result);
       }
       setLoaded(true);
@@ -578,8 +627,13 @@ export function Workspace({
             : result.notes
           : await store.list();
         if (active && sequence === readSequence.current) {
-          if (result) adoptLibrary(result);
-          else setNotes(list);
+          if (result) {
+            adoptLibrary(result);
+            sidebarSelection.admit();
+          } else {
+            sidebarSelection.admit();
+            setNotes(list);
+          }
           setLoaded(true);
         }
       } catch (e) {
@@ -687,6 +741,35 @@ export function Workspace({
     : [
         ...new Set(notes.filter((n) => !n.trashedAt).flatMap((n) => n.tags)),
       ].sort();
+  fallbackSidebarTags.current.length = tags.length;
+  const sidebarTagKeys: SidebarSelectionKey[] = tags.map((name, index) => {
+    const id = snapshot?.tags.find(
+      (value) => value.state === "active" && value.name === name,
+    )?.id;
+    return id ? `tag:${id}` : (fallbackSidebarTags.current[index] ??= Symbol());
+  });
+  const sidebarKeys: SidebarSelectionKey[] = [
+    "notes", "journal", "study", "clips",
+    ...(library ? ["pinned", ...(links.service ? ["linked"] : []), "tags"] : []),
+    ...sidebarTagKeys, "trash",
+  ];
+  const sidebarShape = `${sidebarWidth}:${wide}:${drawer}:${sidebarHidden}`;
+  if (
+    sidebarLayout.current.shape !== sidebarShape ||
+    sidebarLayout.current.keys.length !== sidebarKeys.length ||
+    sidebarKeys.some((key, index) => key !== sidebarLayout.current.keys[index])
+  ) {
+    sidebarLayout.current = {
+      keys: sidebarKeys,
+      shape: sidebarShape,
+      version: sidebarLayout.current.version + 1,
+    };
+  }
+  const sidebarActiveKey: SidebarSelectionKey | null = module !== "notes"
+    ? module
+    : trash ? "trash"
+      : tag ? sidebarTagKeys[tags.indexOf(tag)] ?? null
+        : pinnedOnly ? "pinned" : linkedOnly ? "linked" : "notes";
   const editing = selected !== null && current;
   const noteActors = Array.from(
     new Set(
@@ -1631,12 +1714,19 @@ export function Workspace({
       )}
       <aside
         id="notes-sidebar"
-        ref={drawerRef}
+        ref={sidebarRootRef}
         role={drawer ? "dialog" : undefined}
         aria-modal={drawer ? true : undefined}
         className={drawer ? "sidebar open" : "sidebar"}
         aria-label="Notes navigation"
       >
+        <SidebarSelection
+          controller={sidebarSelection}
+          activeKey={sidebarActiveKey}
+          layoutVersion={sidebarLayout.current.version}
+          privacyRevision={sidebarPrivacy}
+          visible={loaded && (wide ? !(desktop && sidebarHidden) : drawer)}
+        />
         <div className="sidebar-account" role="group" aria-label="Account">
           <span className="sidebar-account-avatar" aria-hidden="true">
             {accountInitial}
@@ -1685,6 +1775,7 @@ export function Workspace({
         )}
         <nav>
           <button
+            ref={sidebarSelection.rowRef("notes")}
             className={
               module === "notes" && !trash && !tag && !pinnedOnly && !linkedOnly
                 ? "nav active"
@@ -1697,6 +1788,7 @@ export function Workspace({
             <span>{notes.filter((n) => !n.trashedAt).length}</span>
           </button>
           <button
+            ref={sidebarSelection.rowRef("journal")}
             className={module === "journal" ? "nav active" : "nav"}
             onClick={() => {
               if (!canNavigate()) return;
@@ -1722,6 +1814,7 @@ export function Workspace({
             <span className="nav-label">Journal</span>
           </button>
           <button
+            ref={sidebarSelection.rowRef("study")}
             className={module === "study" ? "nav active" : "nav"}
             onClick={() => {
               if (!canNavigate()) return;
@@ -1747,6 +1840,7 @@ export function Workspace({
             <span className="nav-label">Study</span>
           </button>
           <button
+            ref={sidebarSelection.rowRef("clips")}
             className={module === "clips" ? "nav active" : "nav"}
             onClick={() => {
               if (!canNavigate()) return;
@@ -1761,6 +1855,7 @@ export function Workspace({
           {library && (
             <>
               <button
+                ref={sidebarSelection.rowRef("pinned")}
                 className={
                   module === "notes" && pinnedOnly ? "nav active" : "nav"
                 }
@@ -1790,6 +1885,7 @@ export function Workspace({
               </button>
               {links.service && (
                 <button
+                  ref={sidebarSelection.rowRef("linked")}
                   className={
                     module === "notes" && linkedOnly ? "nav active" : "nav"
                   }
@@ -1809,6 +1905,7 @@ export function Workspace({
                 </button>
               )}
               <button
+                ref={sidebarSelection.rowRef("tags")}
                 className={module === "tags" ? "nav active" : "nav"}
                 disabled={readOnly}
                 onClick={() => {
@@ -1824,13 +1921,14 @@ export function Workspace({
             </>
           )}
           <p className="group">Tags</p>
-          {tags.map((t) => {
+          {tags.map((t, index) => {
             const count = notes.filter(
               (note) => !note.trashedAt && note.tags.includes(t),
             ).length;
             return (
               <button
                 key={t}
+                ref={sidebarSelection.rowRef(sidebarTagKeys[index]!)}
                 aria-label={`${t}, ${count} ${count === 1 ? "note" : "notes"}`}
                 className={
                   module === "notes" && tag === t ? "nav active" : "nav"
@@ -1861,6 +1959,7 @@ export function Workspace({
             );
           })}
           <button
+            ref={sidebarSelection.rowRef("trash")}
             className={module === "notes" && trash ? "nav active" : "nav"}
             onClick={() => navigate(true)}
           >
@@ -2125,6 +2224,7 @@ export function Workspace({
                     onSearchReaderResult={searchReaderResult}
                     view={view}
                     onEpochChange={() => {
+                      invalidateSidebarSelection();
                       retireCreate();
                       selectedSnapshot.current = undefined;
                       setSelected(null);
diff --git a/web/tests/integration/sidebar-selection-browser.mjs b/web/tests/integration/sidebar-selection-browser.mjs
new file mode 100644
index 0000000..f927430
--- /dev/null
+++ b/web/tests/integration/sidebar-selection-browser.mjs
@@ -0,0 +1,176 @@
+import { chromium, expect } from "@playwright/test";
+import { mkdir, writeFile } from "node:fs/promises";
+
+const output = process.env.NOTES_UI_OUTPUT ?? "test-results/sidebar-selection";
+const base = process.env.NOTES_PREVIEW_URL ?? "http://127.0.0.1:5187";
+await mkdir(output, { recursive: true });
+const browser = await chromium.launch({ channel: "chrome", headless: true });
+const results = [];
+try {
+  for (const [policy, os, moving] of [
+    ["system", "no-preference", true],
+    ["system", "reduce", false],
+    ["on", "reduce", true],
+    ["reduced", "no-preference", false],
+  ]) {
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 850 },
+      reducedMotion: os,
+    });
+    const page = await context.newPage();
+    const errors = [];
+    page.on("pageerror", (error) => errors.push(error.message));
+    await context.addInitScript(
+      (policy) => localStorage.setItem("notes.motion", policy),
+      policy,
+    );
+    await context.route(/\/src\/desktop\/window\.ts(?:\?|$)/, (route) =>
+      route.fulfill({
+        contentType: "application/javascript",
+        body: `export const isDesktop=()=>true; export async function connectWindow(){return{minimize:async()=>{},toggleMaximize:async()=>{},isMaximized:async()=>false,close:async()=>{},startDragging:async()=>{},showSystemMenu:async()=>{},finishClose:async()=>{},dispose:()=>{}}}`,
+      }),
+    );
+    try {
+      await page.goto(
+        `${base}/tests/integration/library-browser.html?desktop-shell=1`,
+      );
+      const setup = page.getByRole("dialog", { name: "Set up Orbyn Notes" });
+      await expect(setup).toBeVisible();
+      await setup.getByRole("button", { name: "Skip", exact: true }).click();
+      await setup.getByRole("button", { name: "Skip", exact: true }).click();
+      const sidebar = page.getByLabel("Notes navigation", { exact: true });
+      const layer = sidebar.locator(".sidebar-selection-highlight");
+      const notes = sidebar.getByRole("button", {
+        name: "All notes",
+        exact: false,
+      });
+      const study = sidebar.getByRole("button", { name: "Study", exact: true });
+      await expect(layer).toBeVisible();
+      await expect(layer).toHaveAttribute("aria-hidden", "true");
+      await expect(layer).toHaveCSS("pointer-events", "none");
+      await expect(study).toHaveCSS("height", "29px");
+      const rows = sidebar.locator("nav > .nav");
+      const geometry = await rows.evaluateAll((elements) =>
+        elements.map((element) => ({
+          y: element.offsetTop,
+          h: element.offsetHeight,
+        })),
+      );
+      expect(geometry[1].y - geometry[0].y).toBe(30);
+      for (const theme of ["light", "dark", "dim"]) {
+        await page.evaluate(
+          (theme) => (document.documentElement.dataset.theme = theme),
+          theme,
+        );
+        await expect(layer).toHaveCSS("border-radius", "8px");
+        await expect(study).toHaveCSS("transition-duration", /0.15s/);
+      }
+      await page.evaluate(
+        () => (document.documentElement.dataset.theme = "light"),
+      );
+      const before = await layer.boundingBox();
+      await layer.evaluate((element) => {
+        window.__sidebarMotionSamples = [];
+        window.__sidebarMotionDone = false;
+        const start = performance.now();
+        const sample = (now) => {
+          window.__sidebarMotionSamples.push({
+            t: now - start,
+            y: element.getBoundingClientRect().y,
+            animations: element.getAnimations().map((animation) => ({
+              property: animation.transitionProperty,
+              state: animation.playState,
+            })),
+          });
+          if (now - start < 450) requestAnimationFrame(sample);
+          else window.__sidebarMotionDone = true;
+        };
+        requestAnimationFrame(sample);
+      });
+      await study.click();
+      await expect(
+        page.getByRole("heading", { name: "Study", exact: true }),
+      ).toBeVisible();
+      await expect(layer).toHaveAttribute("data-animate", "true");
+      const transition = await layer.evaluate((element) => ({
+        duration: getComputedStyle(element).transitionDuration,
+        easing: getComputedStyle(element).transitionTimingFunction,
+      }));
+      expect(transition.duration).toBe(moving ? "0.2s" : "0s");
+      if (moving)
+        expect(transition.easing).toBe("cubic-bezier(0.2, 0.8, 0.2, 1)");
+      await expect
+        .poll(async () => Math.round((await layer.boundingBox()).y))
+        .toBe(Math.round((await study.boundingBox()).y));
+      const after = await layer.boundingBox();
+      expect(after.y - before.y).toBe(60);
+      await page.waitForFunction(() => window.__sidebarMotionDone);
+      const samples = await page.evaluate(() => window.__sidebarMotionSamples);
+      const between = samples.filter(
+        (sample) => sample.y > before.y + 0.1 && sample.y < after.y - 0.1,
+      );
+      const running = samples.some((sample) =>
+        sample.animations.some(
+          (animation) =>
+            animation.property === "transform" && animation.state === "running",
+        ),
+      );
+      expect(between.length > 0).toBe(moving);
+      expect(running).toBe(moving);
+      // Layout-only width changes settle; they never animate to a stale row.
+      const rail = page.getByRole("separator", { name: "Resize sidebar" });
+      await rail.focus();
+      await page.keyboard.press("ArrowRight");
+      await expect(layer).toHaveAttribute("data-animate", "false");
+      expect(Math.round((await layer.boundingBox()).width)).toBe(
+        Math.round((await study.boundingBox()).width),
+      );
+      await notes.click();
+      await sidebar
+        .getByRole("group", { name: "Account", exact: true })
+        .getByRole("button", { name: "New note", exact: true })
+        .click();
+      await expect(
+        page.getByLabel("Note title", { exact: true }),
+      ).toBeVisible();
+      await page
+        .getByLabel("New tag", { exact: true })
+        .fill("Unsaved navigation guard");
+      const guardedPosition = await layer.getAttribute("style");
+      await study.click();
+      await expect(page.getByLabel("New tag", { exact: true })).toHaveValue(
+        "Unsaved navigation guard",
+      );
+      await expect(study).not.toHaveClass(/active/);
+      await expect(layer).toHaveAttribute("style", guardedPosition);
+      await page.screenshot({ path: `${output}/${policy}-${os}.png` });
+      expect(errors).toEqual([]);
+      results.push({
+        policy,
+        os,
+        moving,
+        geometry,
+        transition,
+        samples,
+        guardedNavigation: true,
+        errors,
+      });
+    } finally {
+      await context.close();
+    }
+  }
+  await writeFile(
+    `${output}/result.json`,
+    JSON.stringify(
+      {
+        scope:
+          "Synthetic account/native bridge; genuine WASM and IndexedDB. Geometry, motion policy and actual draft guard. No native FPS or account-server qualification.",
+        results,
+      },
+      null,
+      2,
+    ),
+  );
+} finally {
+  await browser.close();
+}
diff --git a/web/tests/ui/sidebar-selection.test.tsx b/web/tests/ui/sidebar-selection.test.tsx
new file mode 100644
index 0000000..6e31cfa
--- /dev/null
+++ b/web/tests/ui/sidebar-selection.test.tsx
@@ -0,0 +1,254 @@
+import { act, render, screen } from "@testing-library/react";
+import { StrictMode } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  SidebarSelection,
+  useSidebarSelection,
+  type SidebarSelectionController,
+  type SidebarSelectionKey,
+} from "../../src/ui/SidebarSelection";
+
+let controller: SidebarSelectionController;
+let observerCallbacks: ResizeObserverCallback[];
+let observers: {
+  observe: ReturnType<typeof vi.fn>;
+  disconnect: ReturnType<typeof vi.fn>;
+}[];
+
+function Harness({
+  active = "one",
+  visible = true,
+  layout = 0,
+  privacy = 0,
+  first = true,
+  tick = 0,
+}: {
+  active?: SidebarSelectionKey | null;
+  visible?: boolean;
+  layout?: number;
+  privacy?: number;
+  first?: boolean;
+  tick?: number;
+}) {
+  controller = useSidebarSelection();
+  return (
+    <aside ref={controller.rootRef} data-testid="root" data-tick={tick}>
+      <SidebarSelection
+        controller={controller}
+        activeKey={active}
+        visible={visible}
+        layoutVersion={layout}
+        privacyRevision={privacy}
+      />
+      {first && (
+        <button
+          ref={controller.rowRef("one")}
+          data-x="8"
+          data-y="20"
+          data-width="200"
+          data-height="29"
+        >
+          One
+        </button>
+      )}
+      <button
+        ref={controller.rowRef("two")}
+        data-x="8"
+        data-y="50"
+        data-width="200"
+        data-height="29"
+      >
+        Two
+      </button>
+    </aside>
+  );
+}
+
+beforeEach(() => {
+  observerCallbacks = [];
+  observers = [];
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe = vi.fn();
+      disconnect = vi.fn();
+      constructor(callback: ResizeObserverCallback) {
+        observerCallbacks.push(callback);
+        observers.push(this);
+      }
+    },
+  );
+  for (const [property, key] of [
+    ["offsetLeft", "x"],
+    ["offsetTop", "y"],
+    ["offsetWidth", "width"],
+    ["offsetHeight", "height"],
+  ] as const) {
+    vi.spyOn(HTMLElement.prototype, property, "get").mockImplementation(
+      function (this: HTMLElement) {
+        return Number(this.dataset[key] ?? 0);
+      },
+    );
+  }
+  vi.spyOn(HTMLElement.prototype, "offsetParent", "get").mockImplementation(
+    function (this: HTMLElement) {
+      return this.matches("button") ? this.parentElement : null;
+    },
+  );
+  vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockReturnValue(224);
+  vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(800);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+function layer() {
+  return screen
+    .getByTestId("root")
+    .querySelector<HTMLElement>(".sidebar-selection-highlight")!;
+}
+function expectAt(y: number, animate: boolean) {
+  expect(layer()).not.toHaveAttribute("hidden");
+  expect(layer()).toHaveAttribute("aria-hidden", "true");
+  expect(layer()).toHaveAttribute("data-animate", String(animate));
+  expect(layer().style.transform).toBe(`translate(8px, ${y}px)`);
+  expect(layer().style.width).toBe("200px");
+  expect(layer().style.height).toBe("29px");
+  expect(screen.getByTestId("root")).toHaveAttribute(
+    "data-sidebar-selection-ready",
+    "true",
+  );
+}
+
+describe("sidebar selection presentation", () => {
+  it("uses untransformed offset geometry and immediately places the first admitted row", () => {
+    const rect = vi
+      .spyOn(HTMLElement.prototype, "getBoundingClientRect")
+      .mockImplementation(() => {
+        throw new Error("scaled rect must not be used");
+      });
+    render(<Harness />);
+    expectAt(20, false);
+    expect(rect).not.toHaveBeenCalled();
+  });
+  it("animates only an admitted selection change with stable geometry", () => {
+    const { rerender } = render(<Harness />);
+    rerender(<Harness tick={1} />);
+    expectAt(20, false);
+    rerender(<Harness active="two" />);
+    expectAt(50, true);
+    rerender(<Harness active="one" />);
+    expectAt(20, true);
+  });
+  it("settles without animation on layout version, moved geometry, resize and scroll", () => {
+    const { rerender } = render(<Harness />);
+    rerender(<Harness tick={1} />);
+    rerender(<Harness active="two" layout={1} />);
+    expectAt(50, false);
+    const button = screen.getByRole("button", { name: "Two" });
+    button.dataset.y = "75";
+    act(() => observerCallbacks.at(-1)!([], {} as ResizeObserver));
+    expectAt(75, false);
+    button.dataset.y = "90";
+    act(() => screen.getByTestId("root").dispatchEvent(new Event("scroll")));
+    expectAt(90, false);
+  });
+  it("hides for invisible, absent, removed and invalid geometry; reappears without travel", () => {
+    const { rerender } = render(<Harness />);
+    rerender(<Harness visible={false} />);
+    expect(layer()).toHaveAttribute("hidden");
+    expect(screen.getByTestId("root")).not.toHaveAttribute(
+      "data-sidebar-selection-ready",
+    );
+    rerender(<Harness visible />);
+    expectAt(20, false);
+    rerender(<Harness active={null} />);
+    expect(layer()).toHaveAttribute("hidden");
+    rerender(<Harness active="one" first={false} />);
+    expect(layer()).toHaveAttribute("hidden");
+    rerender(<Harness active="two" first={false} />);
+    expectAt(50, false);
+    screen.getByRole("button", { name: "Two" }).dataset.width = "0";
+    rerender(<Harness active="two" first={false} tick={1} />);
+    expect(layer()).toHaveAttribute("hidden");
+  });
+  it("synchronously invalidates, retires old refs and observer callbacks, then admits fresh rows", () => {
+    const { rerender } = render(<Harness />);
+    rerender(<Harness tick={1} />);
+    const oldRootRef = controller.rootRef,
+      oldRowRef = controller.rowRef("one"),
+      oldObserver = observerCallbacks.at(-1)!;
+    const root = screen.getByTestId("root"),
+      oldRow = screen.getByRole<HTMLButtonElement>("button", { name: "One" });
+    expectAt(20, false);
+    act(() => controller.invalidate());
+    expect(layer()).toHaveAttribute("hidden");
+    expect(root).not.toHaveAttribute("data-sidebar-selection-ready");
+    act(() => {
+      oldRootRef(root);
+      oldRowRef(oldRow);
+      oldObserver([], {} as ResizeObserver);
+    });
+    rerender(<Harness active="two" tick={1} />);
+    expect(layer()).toHaveAttribute("hidden");
+    act(() => controller.admit());
+    rerender(<Harness active="two" tick={2} />);
+    expectAt(50, false);
+    act(() => {
+      oldRootRef(root);
+      oldRowRef(oldRow);
+      oldObserver([], {} as ResizeObserver);
+    });
+    expectAt(50, false);
+  });
+  it("requires fresh admission after Strict Mode cleanup and ignores queued stale measurements", () => {
+    const { rerender } = render(
+      <StrictMode>
+        <Harness />
+      </StrictMode>,
+    );
+    // Strict Mode invokes effect cleanup once during its development replay.
+    // The owner must explicitly admit the current authority after its read.
+    act(() => controller.admit());
+    rerender(
+      <StrictMode>
+        <Harness tick={1} />
+      </StrictMode>,
+    );
+    expectAt(20, false);
+    const stale = observerCallbacks.at(-1)!;
+    act(() => controller.invalidate());
+    expect(layer()).toHaveAttribute("hidden");
+    act(() => stale([], {} as ResizeObserver));
+    rerender(
+      <StrictMode>
+        <Harness active="two" tick={2} />
+      </StrictMode>,
+    );
+    act(() => stale([], {} as ResizeObserver));
+    expect(layer()).toHaveAttribute("hidden");
+    expect(screen.getByTestId("root")).not.toHaveAttribute(
+      "data-sidebar-selection-ready",
+    );
+    act(() => controller.admit());
+    rerender(
+      <StrictMode>
+        <Harness active="two" tick={3} />
+      </StrictMode>,
+    );
+    expectAt(50, false);
+    act(() => stale([], {} as ResizeObserver));
+    expectAt(50, false);
+  });
+  it("disconnects its observer and removes the scroll listener on unmount", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const { unmount, rerender } = render(<Harness />);
+    rerender(<Harness tick={1} />);
+    expect(observers.at(-1)!.observe).toHaveBeenCalledTimes(2);
+    const current = observers.at(-1)!;
+    unmount();
+    expect(current.disconnect).toHaveBeenCalled();
+    expect(remove).toHaveBeenCalledWith("scroll", expect.any(Function), true);
+  });
+});