Polish dev tool trigger

Author: Developing-Gamer

.claude/CLAUDE-KNOWLEDGE.md

@@ -366,3 +366,15 @@ A: The `/api/v1/internal/metrics` response now intentionally includes `analytics
 
 ## Q: Why can environment config override writes fail with a product/product-line customer type warning after creating a preview project?
 A: The environment override endpoint validates the new environment override against the rendered branch config. Preview dummy payments data must therefore be internally coherent: products assigned to a product line need the same `customerType` as that product line, otherwise unrelated environment patches can fail with warnings like `Product "growth" has customer type "user" but its product line "workspace" has customer type "team"`.
+
+## Q: How do you keep the Stack Auth dev tool from reopening automatically after navigation or reload?
+A: Treat `isOpen` as mount-local state in `packages/template/src/dev-tool/dev-tool-core.ts`: load persisted preferences with `isOpen: false`, and save state back to localStorage with `isOpen: false` so tab/size preferences persist without reopening the panel on the next mount.
+
+## Q: How should the Stack Auth dev tool indicator avoid being hidden by other dev indicators?
+A: Do not dynamically reflow around framework indicators; that makes pointer interaction brittle. Keep the trigger anchored to its saved corner and give `.sdt-trigger` a max practical z-index (`2147483647`) so the Stack indicator renders above Next/Turbo overlays.
+
+## Q: How should Stack Auth dev tool trigger movement feel?
+A: Dragging should remain instant/direct, but programmatic moves like snap-to-corner after drag, resize reposition, and post-measurement correction should use a short snappy left/top transition. In `dev-tool-core.ts`, toggle a dedicated animation class only for those programmatic updates and remove it shortly after.
+
+## Q: How do you prevent duplicate Stack Auth dev tool indicators from multiple package/module instances?
+A: `createDevTool` in `packages/template/src/dev-tool/dev-tool-core.ts` should register a browser-wide singleton instance on `window` with an idempotent cleanup function, call any previous global cleanup before mounting, and remove leftover `#__stack-dev-tool-root` nodes as a fallback for older instances that did not register cleanup.

packages/template/src/dev-tool/dev-tool-core.ts

@@ -420,13 +420,35 @@ function createTrigger(onClick: () => void): { element: HTMLElement; cleanup: ()
     } catch {}
   }
 
-  function applyPos(nextPos: Position) {
+  let animationTimeout: number | null = null;
+
+  function setPositionAnimation(isAnimated: boolean) {
+    if (animationTimeout !== null) {
+      window.clearTimeout(animationTimeout);
+      animationTimeout = null;
+    }
+    btn.classList.toggle('sdt-trigger-position-animated', isAnimated);
+    if (isAnimated) {
+      animationTimeout = window.setTimeout(() => {
+        animationTimeout = null;
+        btn.classList.remove('sdt-trigger-position-animated');
+      }, 180);
+    }
+  }
+
+  function applyPos(nextPos: Position, options?: { animate?: boolean }) {
+    setPositionAnimation(options?.animate === true);
     pos = nextPos;
     btn.style.left = pos.left + 'px';
     btn.style.top = pos.top + 'px';
   }
 
-  const btn = h('button', { className: 'sdt-trigger', 'aria-label': 'Toggle Stack Auth Dev Tools', title: 'Stack Auth Dev Tools' });
+  const btn = h('button', {
+    className: 'sdt-trigger',
+    'aria-label': 'Toggle Stack Auth Dev Tools',
+    'data-stack-devtool-trigger': 'true',
+    title: 'Stack Auth Dev Tools',
+  });
   const logoSpan = h('span', { className: 'sdt-trigger-logo' });
   setHtml(logoSpan, STACK_LOGO_SVG);
   btn.appendChild(logoSpan);
@@ -435,22 +457,23 @@ function createTrigger(onClick: () => void): { element: HTMLElement; cleanup: ()
   let pos = resolveTriggerPosition(placement, triggerSize, { width: window.innerWidth, height: window.innerHeight });
   applyPos(pos);
 
+  let dragState: { startX: number; startY: number; startLeft: number; startTop: number; didDrag: boolean } | null = null;
+
   // After mount, measure the actual rendered size and re-snap if needed.
   requestAnimationFrame(() => {
     const rect = btn.getBoundingClientRect();
     if (rect.width > 0 && rect.height > 0) {
       triggerSize = { width: rect.width, height: rect.height };
       const measured = resolveTriggerPosition(placement, triggerSize, { width: window.innerWidth, height: window.innerHeight });
       if (measured.left !== pos.left || measured.top !== pos.top) {
-        applyPos(measured);
+        applyPos(measured, { animate: true });
       }
     }
   });
 
-  let dragState: { startX: number; startY: number; startLeft: number; startTop: number; didDrag: boolean } | null = null;
-
   btn.addEventListener('pointerdown', (e) => {
     e.preventDefault();
+    setPositionAnimation(false);
     btn.setPointerCapture(e.pointerId);
     dragState = { startX: e.clientX, startY: e.clientY, startLeft: pos.left, startTop: pos.top, didDrag: false };
   });
@@ -475,7 +498,7 @@ function createTrigger(onClick: () => void): { element: HTMLElement; cleanup: ()
     btn.releasePointerCapture(e.pointerId);
     if (ds.didDrag) {
       placement = getSnappedTriggerPlacement(pos, triggerSize, { width: window.innerWidth, height: window.innerHeight });
-      applyPos(resolveTriggerPosition(placement, triggerSize, { width: window.innerWidth, height: window.innerHeight }));
+      applyPos(resolveTriggerPosition(placement, triggerSize, { width: window.innerWidth, height: window.innerHeight }), { animate: true });
       savePlacement(placement);
     } else {
       onClick();
@@ -487,7 +510,7 @@ function createTrigger(onClick: () => void): { element: HTMLElement; cleanup: ()
   function onResize() {
     const resizedPos = resolveTriggerPosition(placement, triggerSize, { width: window.innerWidth, height: window.innerHeight });
     if (resizedPos.left !== pos.left || resizedPos.top !== pos.top) {
-      applyPos(resizedPos);
+      applyPos(resizedPos, { animate: true });
     }
   }
 
@@ -496,6 +519,9 @@ function createTrigger(onClick: () => void): { element: HTMLElement; cleanup: ()
   return {
     element: btn,
     cleanup: () => {
+      if (animationTimeout !== null) {
+        window.clearTimeout(animationTimeout);
+      }
       window.removeEventListener('resize', onResize);
     },
   };

packages/template/src/dev-tool/dev-tool-styles.ts

@@ -50,7 +50,7 @@ export const devToolCSS = `
   /* Trigger pill */
   .stack-devtool .sdt-trigger {
     position: fixed;
-    z-index: 99999;
+    z-index: 2147483647;
     display: flex;
     align-items: center;
     justify-content: center;
@@ -67,6 +67,10 @@ export const devToolCSS = `
     touch-action: none;
   }
 
+  .stack-devtool .sdt-trigger-position-animated {
+    transition: left 0.14s cubic-bezier(0.2, 0.8, 0.2, 1), top 0.14s cubic-bezier(0.2, 0.8, 0.2, 1), background 0.2s ease, border-color 0.2s ease, box-shadow 0.2s ease;
+  }
+
   .stack-devtool .sdt-trigger:hover {
     background: var(--sdt-bg-hover);
     border-color: var(--sdt-accent);