chore(webapp): tighten the side menu code comments

Shorten the explanatory comments added across the resizable side menu and org
menu work to the essentials. Comment-only, no behaviour change.

Author: samejr

apps/webapp/app/assets/icons/LeftSideMenuIcon.tsx

@@ -6,10 +6,7 @@ export function LeftSideMenuIcon({
   hovered: controlledHovered,
 }: {
   className?: string;
-  /**
-   * When provided, the shape animation is driven by this prop (e.g. from a
-   * parent button's hover). When omitted, the icon animates on its own hover.
-   */
+  /** Drives the animation when provided (e.g. parent hover); otherwise the icon uses its own hover. */
   hovered?: boolean;
 }) {
   const [internalHovered, setInternalHovered] = useState(false);
@@ -28,10 +25,8 @@ export function LeftSideMenuIcon({
       onMouseLeave={isControlled ? undefined : () => setInternalHovered(false)}
     >
       <rect x="4" y="4" width="16" height="16" rx="2" stroke="currentColor" strokeWidth="2" />
-      {/* Animate a transform (scaleX) rather than the SVG `width` attribute:
-          framer snaps the first animation of an SVG geometry attribute after it
-          has been idle, whereas transforms animate reliably. Anchoring the origin
-          to the left edge collapses the panel from right to left. */}
+      {/* Animate a transform (scaleX), not the SVG `width` attr — framer snaps the first animation
+          of an idle SVG geometry attribute. Left origin collapses the panel right-to-left. */}
       <motion.rect
         x="6"
         y="6"

apps/webapp/app/components/AskAI.tsx

@@ -77,11 +77,10 @@ function useAskAIState() {
 }
 
 /**
- * Hosts Ask AI for a menu that renders its own trigger (the side menu's Help & Feedback popover):
- * the Kapa provider, the global ⌘I shortcut, and the dialog all live here, and `children`
- * receives the open function to render a trigger with. Wrap this around the popover rather than
- * inside its content so the dialog and shortcut survive the popover closing. `children` receives
- * undefined when Ask AI is unavailable (self-hosted, no Kapa website id, or during SSR).
+ * Hosts Ask AI (Kapa provider, ⌘I shortcut, dialog) for a menu that renders its own trigger. Wrap
+ * it around the popover, not inside, so the dialog and shortcut survive the popover closing.
+ * `children` receives the open function, or undefined when Ask AI is unavailable (self-hosted, no
+ * Kapa website id, or SSR).
  */
 export function AskAIRoot({
   children,

apps/webapp/app/components/GlobalShortcuts.tsx

@@ -3,10 +3,7 @@ import { useEffect } from "react";
 import { useOptionalUser } from "~/hooks/useUser";
 import { adminPath } from "~/utils/pathBuilder";
 
-/**
- * App-wide keyboard shortcuts, mounted once at the root so they work on every page regardless of
- * which side menu (if any) is rendered. Renders nothing.
- */
+/** App-wide keyboard shortcuts, mounted once at the root so they work everywhere. Renders nothing. */
 export function GlobalShortcuts() {
   const user = useOptionalUser();
   const navigate = useNavigate();
@@ -19,15 +16,10 @@ export function GlobalShortcuts() {
     if (!isAdmin) return;
 
     const onKeyDown = (event: KeyboardEvent) => {
-      // Admin-only escape hatch: Cmd+Option+A (Ctrl+Alt+A on Windows) opens the admin dashboard, or
-      // stops impersonating while impersonating. Two modifiers keep it clear of every user-facing
-      // shortcut, and it deliberately avoids Escape (Chrome/macOS never delivers a keydown for
-      // Escape while a modifier is held, which is why the old Cmd+Esc did nothing).
-      //
-      // Matched on `event.code` (the physical key) rather than `event.key`, because holding Option
-      // on macOS makes the "A" key report an alternate character ("å"); the physical code stays
-      // `KeyA` regardless. This is why it's a raw listener and not the `useShortcutKeys` hook, which
-      // matches on `event.key`.
+      // Admin escape hatch: Cmd+Option+A (Ctrl+Alt+A on Windows) opens the admin dashboard, or stops
+      // impersonating. Avoids Escape — Chrome/macOS never delivers a keydown for Escape+modifier (why
+      // the old Cmd+Esc did nothing). Matched on `event.code`, not `event.key`, because Option makes
+      // "A" report "å" (so a raw listener, not the `event.key`-based useShortcutKeys hook).
       if (event.code !== "KeyA" || !event.altKey || !(event.metaKey || event.ctrlKey)) {
         return;
       }

apps/webapp/app/components/environments/EnvironmentLabel.tsx

@@ -88,8 +88,7 @@ export function EnvironmentLabel({
   tooltipSideOffset?: number;
   tooltipSide?: "top" | "right" | "bottom" | "left";
   disableTooltip?: boolean;
-  /** When false, the label clips without an ellipsis (used by the resizable side menu so the label
-   * fades out in place while dragging instead of truncating). Defaults to true everywhere else. */
+  /** When false, the label clips without an ellipsis (side menu fades it in place). Defaults true. */
   truncate?: boolean;
 }) {
   const spanRef = useRef<HTMLSpanElement>(null);

apps/webapp/app/components/navigation/EnvironmentSelector.tsx

@@ -35,9 +35,8 @@ import { V4Badge } from "../V4Badge";
 import { type SideMenuEnvironment, type SideMenuProject } from "./SideMenu";
 import { Badge } from "../primitives/Badge";
 
-// Size this Env popover's items to match the Project popover menu items
-// (SIDE_MENU_POPOVER_ITEM_* in SideMenu.tsx). Applied only at these call sites so the
-// shared EnvironmentLabel/EnvironmentCombo defaults used elsewhere in the app stay unchanged.
+// Size this Env popover's items to match the Project popover (SIDE_MENU_POPOVER_ITEM_* in
+// SideMenu.tsx). Only at these call sites, so shared EnvironmentLabel/EnvironmentCombo defaults stay.
 const ENV_POPOVER_ITEM_ICON = "size-5";
 const ENV_POPOVER_ITEM_LABEL = "text-[0.90625rem] font-medium tracking-[-0.01em]";
 
@@ -83,23 +82,17 @@ export function EnvironmentSelector({
           <PopoverTrigger
             className={cn(
               "group flex h-8 items-center rounded pl-1.75 hover:bg-background-hover focus-custom",
-              // The expanded row arrangement applies while dragging too — the resting classes only
-              // flip on release, and the label reveal mid-drag needs the expanded layout.
+              // Expanded arrangement also applies mid-drag (resting classes flip only on release).
               isDragging || !isCollapsed ? "justify-between pr-1" : "justify-center pr-0.5",
               className
             )}
           >
             <span className="flex min-w-0 flex-1 items-center gap-1.5 overflow-hidden">
               <EnvironmentIcon environment={environment} className="size-5 shrink-0" />
               {/*
-                Opacity is driven by the resizable SideMenu's `--sm-label-opacity` variable so the
-                label fades frame-by-frame in both directions (gating on isCollapsed, which only flips
-                on release, made the label pop in after a drag-open). The max-width cap is generous
-                (far wider than any env name) so the visible fade is driven purely by opacity — the
-                text stays full and fades out in place instead of truncating as the row narrows —
-                while still reaching 0 as the label finishes fading so it never holds layout width.
-                Unset in the other places this selector is used (blank-state panels, Limits page)
-                → falls back to fully visible.
+                Opacity follows --sm-label-opacity to fade both directions without popping in on
+                drag-open; the generous max-width cap fades the text in place (not truncated) but
+                scales to 0 so it never holds width. Unset elsewhere → fully visible.
               */}
               <span
                 className="flex min-w-0 items-center overflow-hidden"
@@ -117,9 +110,8 @@ export function EnvironmentSelector({
               </span>
             </span>
             {/*
-              The chevron's 16px of width follows the SideMenu drag variable (falls back to full
-              width elsewhere): an invisible span that holds its width mid-drag pushes the row's
-              clip edge into the environment icon.
+              Chevron's 16px width follows --sm-label-opacity so an invisible span never holds width
+              mid-drag and pushes the row's clip edge into the icon.
             */}
             <span
               className="overflow-hidden opacity-0 group-hover:opacity-100"
@@ -132,9 +124,8 @@ export function EnvironmentSelector({
         content={`${environmentFullTitle(environment)} environment`}
         side="right"
         sideOffset={8}
-        // Only surface the tooltip on the collapsed rail (instant), matching the Org and Project
-        // selectors: when expanded the label is already visible, and this selector is also reused
-        // outside the side menu (blank-state panels, Limits page) where a hover tooltip is unwanted.
+        // Tooltip only on the collapsed rail (expanded shows the label; this selector is also reused
+        // outside the side menu, where a hover tooltip is unwanted).
         hidden={!isCollapsed}
         delayDuration={0}
         buttonClassName="h-8!"
@@ -316,9 +307,8 @@ function Branches({
 }
 
 /**
- * The inner content of the branches popover (branch list, empty states, and the
- * "Manage branches" footer). Shared by the dropdown's hover submenu (`Branches`)
- * and the side-menu segmented control's Preview popover.
+ * Inner content of the branches popover (list, empty states, "Manage branches" footer). Shared by
+ * the `Branches` hover submenu and the side-menu Preview popover.
  */
 export function BranchesPopoverContent({
   parentEnvironment,
@@ -342,10 +332,8 @@ export function BranchesPopoverContent({
         ? "no-active-branches"
         : "has-branches";
 
-  // Only surface the active environment's archived-branch item in the submenu it
-  // actually belongs to. Both Development and Preview render this component, so
-  // without the parent check an archived dev branch would leak into the Preview
-  // submenu (and vice-versa).
+  // Show the archived-branch item only in the submenu it belongs to: both Development and Preview
+  // render this, so without the parent check an archived dev branch leaks into Preview (and vice-versa).
   const currentBranchIsArchived =
     environment.archivedAt !== null && environment.parentEnvironmentId === parentEnvironment.id;
 

apps/webapp/app/components/navigation/HelpAndFeedbackPopover.tsx

@@ -53,10 +53,8 @@ export function HelpAndFeedback({
       transition={{ duration: 0.2, ease: "easeInOut" }}
       className={isCollapsed ? undefined : "min-w-0 flex-1"}
     >
-      {/*
-        AskAIRoot hosts the Ask AI dialog and its ⌘I shortcut outside the popover content, so
-        both keep working when the popover closes; the popover just renders the trigger item.
-      */}
+      {/* AskAIRoot hosts the Ask AI dialog + ⌘I shortcut outside the popover, so both survive the
+          popover closing; the popover just renders the trigger. */}
       <AskAIRoot>
         {(openAskAI) => (
           <Popover open={isHelpMenuOpen} onOpenChange={setHelpMenuOpen}>
@@ -71,12 +69,9 @@ export function HelpAndFeedback({
                   <span className="flex min-w-0 items-center gap-1.5 overflow-hidden">
                     <QuestionMarkIcon className="size-5 min-w-5 shrink-0 text-success" />
                     {/*
-                  Width and opacity follow the resizable side menu's `--sm-label-opacity` variable
-                  (falls back to fully visible when unset) so the label tracks a drag frame-by-frame
-                  in both directions, matching the nav items — gating the width on isCollapsed,
-                  which only flips on release, made the label pop in after a drag-open. No CSS
-                  transitions: they would lag the per-frame variable writes.
-                */}
+                      Width + opacity follow --sm-label-opacity so the label tracks a drag both
+                      directions (no CSS transition — it would lag the per-frame writes).
+                    */}
                     <span
                       className="min-w-0 overflow-hidden whitespace-nowrap text-[0.90625rem] font-medium tracking-[-0.01em] text-text-dimmed group-hover:text-text-bright"
                       style={{
@@ -88,11 +83,8 @@ export function HelpAndFeedback({
                     </span>
                   </span>
                   {/*
-                    Up/down chevron revealed on hover, matching the Project menu button. Only
-                    rendered when expanded (it is a hover affordance that has no meaning
-                    collapsed), and its 16px of width follows the SideMenu drag variable so an
-                    invisible chevron can never hold width mid-drag and push the row's clip edge
-                    into the help icon.
+                    Hover chevron, only when expanded. Its 16px width follows --sm-label-opacity so
+                    an invisible chevron never holds width mid-drag and clips the help icon.
                   */}
                   {!isCollapsed && (
                     <span