@bytebrand/fe-ui-core-autobahn 1.0.127 → 1.0.129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/fe-ui-core-autobahn",
-  "version": "1.0.127",
+  "version": "1.0.129",
   "description": "auto.de md3 (Autobahn) design system — UI primitives, cards, chrome, VDP modules, theme CSS and locales. Ships raw TypeScript source (like fe-ui-core before it); each consumer's bundler compiles it.",
   "main": "index.ts",
   "license": "UNLICENSED",

package/ui/CardCarousel.tsx

@@ -1,4 +1,22 @@
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+// Spring constants for the track's slide animation — critically damped (damping = 2·√stiffness,
+// so it approaches the target with no overshoot/bounce, matching what sampling mobile.de's own
+// VDP gallery showed — see the spring loop's doc comment below) and tuned so a single ±1 move
+// settles in ~800-850ms, matching mobile.de's measured settle time for the same move.
+const SPRING_STIFFNESS = 64;
+const SPRING_DAMPING = 16;
+// Below these thresholds the spring is considered "arrived": stop stepping it (saves CPU while
+// idle instead of running a rAF loop forever) and snap the last fractional pixel so the resting
+// position is exact, not just "close enough". Both are small enough that the final snap is
+// sub-perceptible (0.015 of a slide's width is single-digit pixels at any real card size, at a
+// point where residual velocity is already crawling) — chosen by MEASURING actual settle time
+// live and tuning until it landed at mobile.de's own measured ~800-850ms, rather than picking
+// numbers that merely looked reasonable: 0.001/0.01 both measured over 1s to hit in practice
+// (VELOCITY decays slower than position for a critically damped spring, so it — not position —
+// ends up the binding constraint), well past the ~800ms the motion is already imperceptible.
+const SETTLE_POS_EPS = 0.015;
+const SETTLE_VEL_EPS = 0.09;
 
 export interface CardCarouselProps {
   /** ready-to-use image URLs (already resolved by the caller — no asset/window lookup here). */
@@ -34,7 +52,6 @@ const CardCarousel: React.FunctionComponent<CardCarouselProps> = ({
   fit = 'cover',
   padded = true,
 }) => {
-  const [i, setI] = useState(0);
   const n = images.length;
   // MOBX-CQ-2: reset to the first slide whenever the caller hands us a
   // DIFFERENT gallery (this instance reused for another car) — otherwise a
@@ -44,17 +61,242 @@ const CardCarousel: React.FunctionComponent<CardCarouselProps> = ({
   // every arrow click whose onChange triggered a parent re-render (the
   // counter advanced while the track snapped back to slide 0).
   const gallerySignature = images.join('|');
-  useEffect(() => {
-    setI(0);
+  // Loop-wrap (last→first / first→last): the flex row gets one extra CLONE slide at each
+  // end — clone of the LAST photo before the first, clone of the FIRST photo after the last
+  // — so a swipe/click past either edge keeps animating in the SAME direction into a
+  // real-looking next photo (mobile.de's own VDP gallery does the same) instead of jump-
+  // cutting or animating backward through every photo in between.
+  const extendedImages = n > 1 ? [images[n - 1], ...images, images[0]] : images;
+  // `trackIndex` (0..n+1, extended-array units; real slides live at 1..n) is the spring's
+  // TARGET and the only piece of animation state React itself renders from — used below to
+  // derive `i` (0..n-1, the "real" active slide for dots/onChange/the photo-count pill).
+  const [trackIndex, setTrackIndex] = useState(n > 1 ? 1 : 0);
+  // Mirrors `trackIndex`, updated SYNCHRONOUSLY inside go()/drag itself — not via React state,
+  // which only becomes readable to the NEXT interaction after a render has committed. Reading
+  // this (not the closured `trackIndex` state, and not a functional setState updater) is what
+  // makes go() correct no matter how soon after the last call it runs — see go()'s doc comment.
+  const trackIndexRef = useRef(trackIndex);
+  // The ANIMATED position, same 0..n+1 units as trackIndex but a continuous float — a ref, not
+  // state: the spring loop below writes it up to 60×/sec straight into the DOM via trackRef,
+  // never through React's render cycle (far too slow for smooth 60fps motion, and it would
+  // fight with the loop's own direct writes if React re-rendered the same style prop).
+  const visualPosRef = useRef(trackIndex);
+  const velocityRef = useRef(0);
+  const trackRef = useRef<HTMLDivElement>(null);
+  const rafIdRef = useRef<number | null>(null);
+  // `n` read fresh inside the spring loop's closure would go stale if the gallery changes while
+  // a loop iteration is still in flight (a reused SRP card instance recycled mid-animation) —
+  // the gallery-reset effect below already forces a fresh start in that case, but mirroring `n`
+  // into a ref too costs nothing and removes the edge case outright.
+  const nRef = useRef(n);
+  nRef.current = n;
+
+  // Plain modulo, not clamped into [0, n+1] first: trackIndex is intentionally UNBOUNDED (see
+  // go()'s doc comment) — several rapid clicks can leave it well past a single clone-width
+  // before the spring loop's own rebase (below) has had a chance to catch up, and modulo maps
+  // ANY integer straight to the right real slide regardless, so `i`/the dots/the photo-count
+  // pill are correct the instant a click fires, never waiting on the animation to catch up.
+  const i = n > 1 ? (((trackIndex - 1) % n) + n) % n : 0;
+
+  const writeTransform = (pos: number) => {
+    const el = trackRef.current;
+    if (el) el.style.transform = `translateX(${(-pos * 100).toFixed(4)}%)`;
+  };
+
+  // The spring loop: steps visualPosRef toward trackIndexRef every frame via real spring-damper
+  // physics (F = -k·x - c·v), not a fixed-duration easing curve. That's the whole reason this
+  // component moved off a CSS transition: a CSS transition RESTARTS from zero velocity on every
+  // RETARGET (a new target set before the old transition finishes — arrows don't debounce, so
+  // this happens on anything faster than one click per ~800ms), and this curve's fast start
+  // meant every retarget produced a visible little "kick" of re-acceleration — read as jitter,
+  // a wrong-direction flicker, or an uneven stutter under fast repeat clicking (confirmed live:
+  // sampling the track's transform frame-by-frame during a burst of real clicks showed exactly
+  // this). A spring's velocity is a real, continuous state variable carried across retargets —
+  // clicking again before the previous move settles blends smoothly into the new target instead
+  // of restarting. This also matches mobile.de's own gallery: sampling ITS transform earlier
+  // showed a front-loaded, no-overshoot, ~800-900ms settle that a fixed-duration bezier curve
+  // could only approximate for an ISOLATED move — under retargeting a spring is what actually
+  // reproduces it, not just the single-move numbers.
+  const stepLoop = (lastT: number) => {
+    rafIdRef.current = requestAnimationFrame((now) => {
+      const dt = Math.min((now - lastT) / 1000, 1 / 30); // cap dt so a lag spike can't overshoot
+      const n2 = nRef.current;
+      const accel = SPRING_STIFFNESS * (trackIndexRef.current - visualPosRef.current) - SPRING_DAMPING * velocityRef.current;
+      velocityRef.current += accel * dt;
+      visualPosRef.current += velocityRef.current * dt;
+
+      // Loop-wrap rebase: whenever the ANIMATED position itself crosses a clone boundary,
+      // invisibly shift BOTH trackIndex and visualPos by ∓n into the matching REAL position —
+      // same photo either side, so each shift is imperceptible — keeping visualPos inside the
+      // single-clone-wide extended array this exact frame. Triggered by visualPos crossing 0 /
+      // n+1, NOT by trackIndex reaching them: trackIndex (the spring's TARGET) is intentionally
+      // UNBOUNDED — go() below no longer clamps it — so several clicks landing faster than the
+      // spring can visually catch up leave it arbitrarily far past a single clone-width. An
+      // earlier version rebased the moment the TARGET reached a boundary, shifting visualPos by
+      // the same ∓n regardless of where it actually was — correct ONLY if visualPos had already
+      // caught up to that boundary too; under a rapid-click burst it usually hadn't (confirmed
+      // live: sampling mid-burst caught visualPos at position ~2.9 of 4 getting yanked to ~-0.1
+      // by a rebase meant for position 4), producing exactly the kind of jarring cross-carousel
+      // jump this whole rewrite exists to eliminate. Rebasing on visualPos's own crossing avoids
+      // that by construction: it only ever fires within one frame's worth of motion of the
+      // boundary, however far past it trackIndex itself has drifted. A `while`, not `if`, so an
+      // extreme burst (or a large dt from a lag spike) rebases as many times in one frame as
+      // visualPos has actually crossed — real motion the array can only render one clone-width
+      // of at a time, not something to skip over in a single jump.
+      while (n2 > 1 && visualPosRef.current >= n2 + 1) {
+        trackIndexRef.current -= n2;
+        visualPosRef.current -= n2;
+        setTrackIndex(trackIndexRef.current);
+      }
+      while (n2 > 1 && visualPosRef.current <= 0) {
+        trackIndexRef.current += n2;
+        visualPosRef.current += n2;
+        setTrackIndex(trackIndexRef.current);
+      }
+
+      writeTransform(visualPosRef.current);
+
+      const atRest = Math.abs(trackIndexRef.current - visualPosRef.current) < SETTLE_POS_EPS && Math.abs(velocityRef.current) < SETTLE_VEL_EPS;
+      if (atRest) {
+        visualPosRef.current = trackIndexRef.current;
+        velocityRef.current = 0;
+        writeTransform(visualPosRef.current);
+        rafIdRef.current = null;
+        return;
+      }
+      stepLoop(now);
+    });
+  };
+  const ensureLoopRunning = () => {
+    if (rafIdRef.current == null) stepLoop(performance.now());
+  };
+  useEffect(
+    () => () => {
+      if (rafIdRef.current != null) cancelAnimationFrame(rafIdRef.current);
+    },
+    [],
+  );
+
+  // Gallery-swap reset — instant, no spring: jump straight to slide 0 with zero velocity so a
+  // reused instance (SRP list) never slides through a stale gallery's photos. useLayoutEffect
+  // (not useEffect) so the DOM is corrected before paint — no one-frame flash of the old
+  // position with the new gallery's images already swapped in underneath it.
+  useLayoutEffect(() => {
+    if (rafIdRef.current != null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+    const start = n > 1 ? 1 : 0;
+    trackIndexRef.current = start;
+    visualPosRef.current = start;
+    velocityRef.current = 0;
+    setTrackIndex(start);
+    writeTransform(start);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [gallerySignature]);
-  const jump = (nx: number, e?: React.SyntheticEvent) => {
+  // Fires onChange whenever the DERIVED active slide actually changes — not on every
+  // trackIndex change, so the loop-wrap's snap-back (n+1→1 / 0→n, same photo either side)
+  // doesn't re-fire it. Reads onChange through a ref instead of listing it as a dependency:
+  // the VDP hands in a fresh inline arrow function every render, and depending on it directly
+  // would re-fire this effect (with the SAME `i`) on every unrelated parent re-render instead
+  // of only on an actual slide change.
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  });
+  const isFirstRender = useRef(true);
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+    onChangeRef.current && onChangeRef.current(i);
+  }, [i]);
+  // Every ±1 move goes through here, whether from a click or a released drag past the
+  // threshold. Reads/writes trackIndexRef synchronously (see its own doc comment above) so two
+  // calls landing back to back — realistic under fast repeat clicking — never race. Deliberately
+  // does NOT clamp/rebase trackIndex to stay within the single clone this component renders on
+  // either end — see the spring loop's rebase, which handles that (correctly: only once
+  // visualPos itself has actually caught up to a boundary, not the instant the discrete target
+  // passes one) — so several rapid clicks just keep pushing the target further out, and the
+  // spring keeps chasing it, rebasing its own coordinate system as needed along the way.
+  const go = (d: number, e?: React.SyntheticEvent) => {
+    if (n <= 1) return;
     e && e.stopPropagation();
-    setI(nx);
-    onChange && onChange(nx);
+    trackIndexRef.current += d;
+    setTrackIndex(trackIndexRef.current);
+    ensureLoopRunning();
+  };
+  // Pointer Events (not separate touch/mouse handlers) so mouse-drag on desktop works the exact
+  // same way touch-swipe already did — same pattern as VdpViewer's onStagePointer* handlers.
+  // Live-follow: visualPosRef tracks the pointer 1:1 while the gesture is in progress — same
+  // feel as mobile.de's / most gallery sliders' drag, instead of only reacting on release. The
+  // spring loop is paused for the duration (grabbing mid-flight kills any residual velocity —
+  // picking the track up should stop it dead, not have it keep drifting under your finger) and
+  // resumes on release, either toward a new target (go(), past the 40px threshold) or back to
+  // the unchanged one (springing back into place — also covers a plain click/tap, dx never
+  // moves, which still bubbles to the card as before since stopPropagation only happens in go()).
+  const dragRef = useRef<{ x: number; startPos: number } | null>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  // Set for one tick after a drag that crossed the 40px threshold — see onClick below for why.
+  const justSwipedRef = useRef(false);
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (n <= 1 || (e.target as HTMLElement).closest('button')) return;
+    dragRef.current = { x: e.clientX, startPos: visualPosRef.current };
+    velocityRef.current = 0;
+    if (rafIdRef.current != null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+    setIsDragging(true);
+    try {
+      e.currentTarget.setPointerCapture(e.pointerId);
+    } catch {
+      // same "nice to have" as VdpViewer's stage capture — safe to ignore if rejected.
+    }
+  };
+  const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const start = dragRef.current;
+    if (!start) return;
+    const width = e.currentTarget.clientWidth || 1;
+    visualPosRef.current = start.startPos - (e.clientX - start.x) / width;
+    writeTransform(visualPosRef.current);
+  };
+  const onPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const start = dragRef.current;
+    dragRef.current = null;
+    setIsDragging(false);
+    if (!start) return;
+    const dx = e.clientX - start.x;
+    if (Math.abs(dx) > 40) {
+      justSwipedRef.current = true;
+      go(dx > 0 ? -1 : 1, e);
+    } else {
+      ensureLoopRunning(); // spring back to the unchanged trackIndex
+    }
+  };
+  const onPointerCancel = () => {
+    dragRef.current = null;
+    setIsDragging(false);
+    ensureLoopRunning();
+  };
+  // A completed drag/swipe (mousedown-move-up or touchstart-move-end, all on this same element)
+  // makes the browser fire a `click` right after pointerup REGARDLESS of how far the pointer
+  // moved in between — go()'s own e.stopPropagation() (called from onPointerUp, above) only
+  // stops THAT pointerup event; it can't reach forward to stop a separate click the browser
+  // hasn't dispatched yet. Left unguarded, that click still bubbles to a card this carousel
+  // lives inside (CarCard/CarRow wrap it in an onClick-to-navigate `<article>`) — swiping
+  // through a "similar cars" card's photos was navigating to that car's own page on release.
+  // Catching it here, one bubble-phase step before it would reach the card, and swallowing it
+  // ONLY when justSwipedRef says a real swipe (not a plain tap, which should still navigate —
+  // matches the click/tap-bubbles-through behavior noted in onPointerUp's own doc comment)
+  // just happened fixes it without the card needing to know anything about drag state itself.
+  const onClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (justSwipedRef.current) {
+      justSwipedRef.current = false;
+      e.stopPropagation();
+    }
   };
-  const go = (d: number, e?: React.SyntheticEvent) => jump((i + d + n) % n, e);
-  const trackRef = useRef<HTMLDivElement>(null);
-  const tx = useRef<number | null>(null);
 
   // 'auto' mode only diverges from plain 'contain' at desktop widths — below 601px it resolves
   // to 'contain' unconditionally, so mobile's existing rendering is untouched either way.
@@ -73,33 +315,53 @@ const CardCarousel: React.FunctionComponent<CardCarouselProps> = ({
   return (
     <div
       className="cardcar"
-      style={{ position: 'relative', height, overflow: 'hidden', borderRadius: radius }}
-      onTouchStart={(e) => {
-        tx.current = e.touches[0].clientX;
-      }}
-      onTouchEnd={(e) => {
-        if (tx.current == null) return;
-        const dx = e.changedTouches[0].clientX - tx.current;
-        tx.current = null;
-        if (Math.abs(dx) > 40) go(dx > 0 ? -1 : 1);
+      style={{
+        position: 'relative',
+        height,
+        overflow: 'hidden',
+        borderRadius: radius,
+        cursor: n > 1 ? (isDragging ? 'grabbing' : 'grab') : undefined,
+        // Without this, mobile browsers treat a horizontal touch-drag on this element as an
+        // ambiguous gesture and can hand it to their OWN native scroll/pan handling before our
+        // onPointerMove ever sees it (a pointercancel fires instead) — swipe-to-flip silently
+        // does nothing on a real touch device even though desktop mouse-drag (unaffected by
+        // touch-action) works fine. 'pan-y', not 'none': tells the browser only HORIZONTAL
+        // panning is ours to handle, so a mostly-vertical drag that starts on the photo still
+        // scrolls the page normally instead of getting swallowed. VdpViewer's full-screen stage
+        // already sets this (as `none` — no page scroll to preserve there); this was the one
+        // carousel surface that never got it.
+        touchAction: n > 1 ? 'pan-y' : undefined,
       }}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+      onPointerCancel={onPointerCancel}
+      onClick={onClick}
     >
+      {/* transform is intentionally NOT part of this style object — it's owned entirely by
+          writeTransform() (the spring loop + drag handlers above), written straight to the DOM
+          node via trackRef. Letting React manage it here too, even with matching values, would
+          mean every trackIndex-driven re-render (a click, a rebase) re-applies React's own
+          understanding of the style — fighting the loop's per-frame writes for the same
+          property. The useLayoutEffect above sets the correct INITIAL value before first paint. */}
       <div
         ref={trackRef}
         style={{
           display: 'flex',
           height: '100%',
-          transform: `translateX(-${i * 100}%)`,
-          transition: 'transform var(--dur-3) var(--ease-emphasized)',
         }}
       >
-        {images.map((src, k) => (
+        {extendedImages.map((src, k) => (
           <img
             key={k}
             src={src}
             alt=""
             loading="lazy"
             decoding="async"
+            // otherwise the browser's own native image-drag (ghost preview + a dragstart
+            // that swallows the following pointer events) hijacks the gesture instead of
+            // our onPointerMove/onPointerUp swipe logic above.
+            draggable={false}
             style={
               autoDesktop
                 ? {

package/vdp/VdpViewer.tsx

@@ -51,6 +51,24 @@ import logoUrl from '../assets/autode-logo.svg';
 const ZOOM_MIN = 1;
 const ZOOM_MAX = 3;
 const ZOOM_STEP = 0.5;
+// Spring constants for the slide-to-neighbor-photo animation, shared by the desktop AND mobile
+// (portrait/landscape) stages below — same physics, same tuning, just two separate refs/loops
+// per stage (each only ever mounts one at a time, but the constants don't need duplicating).
+// Critically damped (damping = 2·√stiffness, so it approaches with no overshoot/bounce) and
+// tuned so a single ±1 move settles in ~800-850ms — matches mobile.de's own gallery, measured by
+// sampling ITS transform frame-by-frame; see ui/CardCarousel.tsx's spring loop doc comment (the
+// first place this pattern was built) for the full derivation and why a spring instead of a CSS
+// transition at all: a fixed-duration curve restarts from zero velocity on every retarget (a new
+// swipe/click before the previous one settles), which reads as jitter under fast repeat use — a
+// spring's velocity carries continuously across retargets instead.
+const SPRING_STIFFNESS = 64;
+const SPRING_DAMPING = 16;
+// Below these thresholds the spring is considered "arrived": stop stepping it (saves CPU while
+// idle) and snap the last fractional pixel so the resting position is exact, not just "close
+// enough" — see CardCarousel's own copy of these same two constants for the measured reasoning
+// behind the specific numbers (velocity, not position, turned out to be the binding constraint).
+const SETTLE_POS_EPS = 0.015;
+const SETTLE_VEL_EPS = 0.09;
 const THUMB_W = 64;
 const THUMB_H = 50;
 const THUMB_GAP = 8;
@@ -540,9 +558,161 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
   const [zoom, setZoom] = useState(ZOOM_MIN);
   const [pan, setPan] = useState({ x: 0, y: 0 });
   const n = images.length;
-  const go = (d: number) => setI((p) => (p + d + n) % n);
   const stageRef = useRef<HTMLDivElement | null>(null);
 
+  // Desktop layout's photo-to-photo animation — a live-drag + spring slide between the current
+  // photo and its neighbor, matching CardCarousel's (ui/CardCarousel.tsx) carousels elsewhere in
+  // the app. Before this, a desktop swipe/arrow-click just swapped `images[i]` outright (only the
+  // zoom `scale()` had a transition) — no slide motion at all, and mouse-drag didn't even exist
+  // (the old mechanism was touch-only, on the whole overlay, not this stage). Mobile (portrait/
+  // landscape) gets the identical treatment further below (`mobileTrack*`), folded into its
+  // EXISTING single pointer-drag gesture instead of a separate handler set — see that block's
+  // own doc comment for why. Kept as two parallel sets of refs/handlers (`desktopTrack*` /
+  // `mobileTrack*`), not one shared implementation: only one of the two stages is ever actually
+  // mounted at a time (layout is either 'desktop' or portrait/landscape), and desktop's simpler
+  // gesture (always a swipe, zoom never pans — see clampPan's own doc comment) doesn't need
+  // threading through mobile's zoom-gated pan/pinch/swipe branch, or vice versa.
+  //
+  // Structural difference from CardCarousel: that one renders ALL n images in one extended
+  // [clone-last, ...images, clone-first] track and walks a single persistent index through it.
+  // Here there's already a single `i` (0..n-1) as the source of truth (arrows/keyboard/thumbnails/
+  // the "all photos" sheet all set it), so instead the track always renders exactly 3 images —
+  // [prev, current, next], RECOMPUTED every time `i` changes — with the spring's target FIXED at
+  // 1 (the center slot, i.e. "showing `images[i]`") rather than walking to a new target each time.
+  // A ±1 step (arrow/drag-release, both go through go() below) doesn't move the target — it moves
+  // the WINDOW: `i` advances and visualPos is compensated by the same ∓1 so the two together
+  // still describe the exact same on-screen position the instant `i` changes (old-current becomes
+  // new-prev or new-next, so a `visualPos` that was e.g. 30% of the way toward old-next reads as
+  // exactly 30% of the way FROM new-prev toward new-current) — the spring then keeps animating,
+  // uninterrupted, toward the same fixed target 1 it always had.
+  const desktopTrackRef = useRef<HTMLDivElement | null>(null);
+  const desktopVisualPosRef = useRef(1);
+  const desktopVelocityRef = useRef(0);
+  const desktopRafIdRef = useRef<number | null>(null);
+  const writeDesktopTransform = (pos: number) => {
+    const el = desktopTrackRef.current;
+    if (el) el.style.transform = `translateX(${(-pos * 100).toFixed(4)}%)`;
+  };
+  const stepDesktopLoop = (lastT: number) => {
+    desktopRafIdRef.current = requestAnimationFrame((now) => {
+      const dt = Math.min((now - lastT) / 1000, 1 / 30); // cap dt so a lag spike can't overshoot
+      const accel = SPRING_STIFFNESS * (1 - desktopVisualPosRef.current) - SPRING_DAMPING * desktopVelocityRef.current;
+      desktopVelocityRef.current += accel * dt;
+      desktopVisualPosRef.current += desktopVelocityRef.current * dt;
+      writeDesktopTransform(desktopVisualPosRef.current);
+      const atRest = Math.abs(1 - desktopVisualPosRef.current) < SETTLE_POS_EPS && Math.abs(desktopVelocityRef.current) < SETTLE_VEL_EPS;
+      if (atRest) {
+        desktopVisualPosRef.current = 1;
+        desktopVelocityRef.current = 0;
+        writeDesktopTransform(1);
+        desktopRafIdRef.current = null;
+        return;
+      }
+      stepDesktopLoop(now);
+    });
+  };
+  const ensureDesktopLoopRunning = () => {
+    if (desktopRafIdRef.current == null) stepDesktopLoop(performance.now());
+  };
+  useEffect(
+    () => () => {
+      if (desktopRafIdRef.current != null) cancelAnimationFrame(desktopRafIdRef.current);
+    },
+    [],
+  );
+  // Safety net: Chrome fully SUSPENDS requestAnimationFrame while the tab is hidden and does NOT
+  // auto-resume it on its own once the tab is visible again (confirmed empirically — a spring
+  // mid-flight when visibility is lost is left frozen exactly where it was, forever, with no
+  // further frames ever requested). A swipe released right before the tab backgrounds — e.g.
+  // switching apps mid-gesture, an everyday mobile habit — would otherwise strand the photo
+  // between two slides indefinitely. Nudges the loop back on if it's stuck mid-animation
+  // (rafIdRef null, i.e. no frame currently scheduled, AND not yet at the target) the moment the
+  // tab becomes visible again.
+  useEffect(() => {
+    const onVisibilityChange = () => {
+      if (document.visibilityState !== 'visible') return;
+      if (desktopRafIdRef.current == null && Math.abs(1 - desktopVisualPosRef.current) > SETTLE_POS_EPS) {
+        ensureDesktopLoopRunning();
+      }
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  // Every ±1 step — arrow click OR a released drag past the threshold (desktopOnPointerUp
+  // below) — goes through here; keyboard nav already calls this too (goRef.current(±1) further
+  // down), so it gets the same animation for free. Thumbnail clicks and the "all photos" sheet
+  // deliberately DON'T (they call setI(k) directly) — an arbitrary jump has no single "slide
+  // direction" to animate, so the effect below just snaps the track for those instead.
+  const changedViaGoRef = useRef(false);
+  const go = (d: number) => {
+    changedViaGoRef.current = true;
+    desktopVisualPosRef.current -= d;
+    mobileVisualPosRef.current -= d;
+    setI((p) => (p + d + n) % n);
+    if (desktopTrackRef.current) ensureDesktopLoopRunning();
+    if (mobileTrackRef.current) ensureMobileLoopRunning();
+  };
+  useEffect(() => {
+    if (changedViaGoRef.current) {
+      changedViaGoRef.current = false;
+      return;
+    }
+    if (desktopRafIdRef.current != null) {
+      cancelAnimationFrame(desktopRafIdRef.current);
+      desktopRafIdRef.current = null;
+    }
+    desktopVisualPosRef.current = 1;
+    desktopVelocityRef.current = 0;
+    writeDesktopTransform(1);
+    if (mobileRafIdRef.current != null) {
+      cancelAnimationFrame(mobileRafIdRef.current);
+      mobileRafIdRef.current = null;
+    }
+    mobileVisualPosRef.current = 1;
+    mobileVelocityRef.current = 0;
+    writeMobileTransform(1);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [i]);
+  const desktopDragRef = useRef<{ x: number; startPos: number } | null>(null);
+  const [isDesktopDragging, setIsDesktopDragging] = useState(false);
+  const desktopOnPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (n <= 1 || (e.target as HTMLElement).closest('button')) return;
+    desktopDragRef.current = { x: e.clientX, startPos: desktopVisualPosRef.current };
+    desktopVelocityRef.current = 0;
+    if (desktopRafIdRef.current != null) {
+      cancelAnimationFrame(desktopRafIdRef.current);
+      desktopRafIdRef.current = null;
+    }
+    setIsDesktopDragging(true);
+    try {
+      e.currentTarget.setPointerCapture(e.pointerId);
+    } catch {
+      // same "nice to have" as the mobile stage's own capture below — safe to ignore if rejected.
+    }
+  };
+  const desktopOnPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const start = desktopDragRef.current;
+    if (!start) return;
+    const width = e.currentTarget.clientWidth || 1;
+    desktopVisualPosRef.current = start.startPos - (e.clientX - start.x) / width;
+    writeDesktopTransform(desktopVisualPosRef.current);
+  };
+  const desktopOnPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const start = desktopDragRef.current;
+    desktopDragRef.current = null;
+    setIsDesktopDragging(false);
+    if (!start) return;
+    const dx = e.clientX - start.x;
+    if (Math.abs(dx) > 40) go(dx > 0 ? -1 : 1);
+    else ensureDesktopLoopRunning(); // spring back to the unchanged photo
+  };
+  const desktopOnPointerCancel = () => {
+    desktopDragRef.current = null;
+    setIsDesktopDragging(false);
+    ensureDesktopLoopRunning();
+  };
+
   // "Alle Fotos" bottom sheet (mobile only — see PhotoSheet above). Opened from the "+N" thumbnail
   // tile in portrait/landscape; picking a photo in it just reuses `i`/`setI`, so the counter and
   // main image update for free. Read via a ref inside the keydown handler below (registered once
@@ -560,9 +730,7 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
   // open. Both 'resize' (fires on rotation in every current mobile browser) and 'orientationchange'
   // are listened for: some browsers deliver 'orientationchange' a tick before window.innerWidth
   // has actually updated to the new orientation's value, so that handler re-reads it on the next
-  // frame rather than trusting the value at event-fire time. `isMobile` (both portrait and
-  // landscape) is kept as a derived boolean for the one spot that still needs it: the desktop-only
-  // whole-overlay touch-swipe guard below.
+  // frame rather than trusting the value at event-fire time.
   const [layout, setLayout] = useState<Layout>(() => (typeof window !== 'undefined' ? layoutForWidth(window.innerWidth) : 'portrait'));
   useEffect(() => {
     const onResize = (): void => setLayout(layoutForWidth(window.innerWidth));
@@ -576,7 +744,6 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
       window.removeEventListener('orientationchange', onOrientationChange);
     };
   }, []);
-  const isMobile = layout !== 'desktop';
 
   // Reset zoom (and pan) on every slide change — a lingering zoom/pan from the previous photo
   // reads as a stuck/broken control on the new one.
@@ -634,15 +801,63 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
   const zoomOut = () => setZoom((z) => Math.max(ZOOM_MIN, +(z - ZOOM_STEP).toFixed(2)));
   const zoomIn = () => setZoom((z) => Math.min(ZOOM_MAX, +(z + ZOOM_STEP).toFixed(2)));
 
-  // Desktop swipe-to-navigate — the original behaviour, unchanged: a plain touch delta on the
-  // whole overlay, no pan.
-  const tx = useRef<number | null>(null);
-
-  // Mobile: one pointer-drag gesture serves two purposes depending on zoom level: at 1x it's a
-  // left/right swipe to change photo (mouse OR touch); zoomed in, it pans the enlarged photo
-  // around instead (that's the whole point of zooming in — being able to look at every part of
-  // it, not just the centered crop). Pointer Events cover mouse + touch + pen in one handler set.
-  const dragRef = useRef<{ x: number; y: number; panStart: { x: number; y: number } } | null>(null);
+  // Mobile (portrait/landscape) photo-to-photo animation — same live-drag + spring slide as the
+  // desktop stage above (see its own doc comment for the full "why a spring" reasoning), just
+  // sharing this stage's SINGLE pointer-drag gesture with pan-when-zoomed and pinch instead of
+  // having its own separate handlers: at zoom<=1 a drag is a swipe (this loop), zoomed in it
+  // pans the enlarged photo around instead (the existing setPan branch, untouched) — the two
+  // are mutually exclusive per-gesture (checked at move/up time), so there's nothing to
+  // reconcile between them beyond that branch.
+  const mobileTrackRef = useRef<HTMLDivElement | null>(null);
+  const mobileVisualPosRef = useRef(1);
+  const mobileVelocityRef = useRef(0);
+  const mobileRafIdRef = useRef<number | null>(null);
+  const writeMobileTransform = (pos: number) => {
+    const el = mobileTrackRef.current;
+    if (el) el.style.transform = `translateX(${(-pos * 100).toFixed(4)}%)`;
+  };
+  const stepMobileLoop = (lastT: number) => {
+    mobileRafIdRef.current = requestAnimationFrame((now) => {
+      const dt = Math.min((now - lastT) / 1000, 1 / 30); // cap dt so a lag spike can't overshoot
+      const accel = SPRING_STIFFNESS * (1 - mobileVisualPosRef.current) - SPRING_DAMPING * mobileVelocityRef.current;
+      mobileVelocityRef.current += accel * dt;
+      mobileVisualPosRef.current += mobileVelocityRef.current * dt;
+      writeMobileTransform(mobileVisualPosRef.current);
+      const atRest = Math.abs(1 - mobileVisualPosRef.current) < SETTLE_POS_EPS && Math.abs(mobileVelocityRef.current) < SETTLE_VEL_EPS;
+      if (atRest) {
+        mobileVisualPosRef.current = 1;
+        mobileVelocityRef.current = 0;
+        writeMobileTransform(1);
+        mobileRafIdRef.current = null;
+        return;
+      }
+      stepMobileLoop(now);
+    });
+  };
+  const ensureMobileLoopRunning = () => {
+    if (mobileRafIdRef.current == null) stepMobileLoop(performance.now());
+  };
+  useEffect(
+    () => () => {
+      if (mobileRafIdRef.current != null) cancelAnimationFrame(mobileRafIdRef.current);
+    },
+    [],
+  );
+  // Same rAF-suspended-while-hidden safety net as the desktop stage's own copy above — see its
+  // doc comment for why (a swipe released right before the tab backgrounds, e.g. switching apps
+  // mid-gesture, would otherwise strand the photo frozen mid-slide forever).
+  useEffect(() => {
+    const onVisibilityChange = () => {
+      if (document.visibilityState !== 'visible') return;
+      if (mobileRafIdRef.current == null && Math.abs(1 - mobileVisualPosRef.current) > SETTLE_POS_EPS) {
+        ensureMobileLoopRunning();
+      }
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const dragRef = useRef<{ x: number; y: number; panStart: { x: number; y: number }; startPos: number } | null>(null);
   // Pinch-to-zoom: every active pointer is tracked by id so a genuine 2nd finger landing can be
   // told apart from the single-pointer pan/swipe drag above and switch into pinch mode instead.
   // The ratio between the CURRENT and STARTING distance between the two touch points scales zoom
@@ -672,7 +887,14 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
       return;
     }
     if (pointersRef.current.size === 1) {
-      dragRef.current = { x: e.clientX, y: e.clientY, panStart: pan };
+      dragRef.current = { x: e.clientX, y: e.clientY, panStart: pan, startPos: mobileVisualPosRef.current };
+      if (zoom <= ZOOM_MIN) {
+        mobileVelocityRef.current = 0;
+        if (mobileRafIdRef.current != null) {
+          cancelAnimationFrame(mobileRafIdRef.current);
+          mobileRafIdRef.current = null;
+        }
+      }
     }
   };
   const onStagePointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
@@ -703,7 +925,13 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
       return;
     }
     const start = dragRef.current;
-    if (!start || zoom <= ZOOM_MIN) return;
+    if (!start) return;
+    if (zoom <= ZOOM_MIN) {
+      const width = e.currentTarget.clientWidth || 1;
+      mobileVisualPosRef.current = start.startPos - (e.clientX - start.x) / width;
+      writeMobileTransform(mobileVisualPosRef.current);
+      return;
+    }
     const dx = e.clientX - start.x;
     const dy = e.clientY - start.y;
     setPan(clampPan({ x: start.panStart.x + dx, y: start.panStart.y + dy }, zoom));
@@ -720,6 +948,7 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
     if (zoom <= ZOOM_MIN) {
       const dx = e.clientX - start.x;
       if (Math.abs(dx) > 40) go(dx > 0 ? -1 : 1);
+      else ensureMobileLoopRunning(); // spring back to the unchanged photo
     }
   };
 
@@ -773,16 +1002,6 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
           display: 'flex',
           flexDirection: 'column',
         }}
-        onTouchStart={(e) => {
-          if (isMobile) return; // mobile pans/swipes via the stage's own pointer handlers instead.
-          tx.current = e.touches[0].clientX;
-        }}
-        onTouchEnd={(e) => {
-          if (isMobile || tx.current == null) return;
-          const dx = e.changedTouches[0].clientX - tx.current;
-          tx.current = null;
-          if (Math.abs(dx) > 40) go(dx > 0 ? -1 : 1);
-        }}
       >
         {layout === 'portrait' ? (
           <>
@@ -836,25 +1055,38 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
               onPointerUp={onStagePointerUp}
               onPointerCancel={onStagePointerUp}
             >
-              <img
-                src={images[i]}
-                alt=""
-                draggable={false}
-                style={{
-                  position: 'absolute',
-                  inset: 0,
-                  width: '100%',
-                  height: '100%',
-                  objectFit: 'contain',
-                  transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
-                  // pinchRef too, not just dragRef — without it every pinch pointermove still
-                  // kicked off a 200ms eased transition toward a target that moves again before
-                  // it finishes, which reads as the image flickering/jittering bigger-smaller
-                  // instead of tracking the fingers 1:1 (drag already had this right).
-                  transition: (dragRef.current || pinchRef.current) ? 'none' : 'transform var(--dur-2, 200ms) var(--ease-standard, ease)',
-                  cursor: zoom > ZOOM_MIN ? 'grab' : undefined,
-                }}
-              />
+              {/* mobileTrackRef's transform is owned entirely by writeMobileTransform() (the
+                  spring loop + the swipe branch of onStagePointerMove above) — same reasoning as
+                  the desktop track: React re-applying a matching value here on every `i`-driven
+                  re-render would fight the loop's own per-frame writes to this same property. */}
+              <div ref={mobileTrackRef} style={{ position: 'absolute', inset: 0, display: 'flex', height: '100%' }}>
+                {[images[(i - 1 + n) % n], images[i], images[(i + 1) % n]].map((src, k) => (
+                  <img
+                    key={k}
+                    src={src}
+                    alt=""
+                    draggable={false}
+                    style={{
+                      flex: '0 0 100%',
+                      width: '100%',
+                      height: '100%',
+                      objectFit: 'contain',
+                      // Zoom/pan only ever apply to the CENTER slot (k===1, the actually-
+                      // displayed photo) — prev/next are only ever visible mid-slide, and both
+                      // reset on every `i` change anyway (see the effect above), so by the time
+                      // either could become the new center they're already back to 1x/centered.
+                      transform: k === 1 ? `translate(${pan.x}px, ${pan.y}px) scale(${zoom})` : undefined,
+                      // pinchRef too, not just dragRef — without it every pinch pointermove still
+                      // kicked off a 200ms eased transition toward a target that moves again before
+                      // it finishes, which reads as the image flickering/jittering bigger-smaller
+                      // instead of tracking the fingers 1:1 (drag already had this right).
+                      transition:
+                        k === 1 ? ((dragRef.current || pinchRef.current) ? 'none' : 'transform var(--dur-2, 200ms) var(--ease-standard, ease)') : undefined,
+                      cursor: k === 1 && zoom > ZOOM_MIN ? 'grab' : undefined,
+                    }}
+                  />
+                ))}
+              </div>
 
               <div style={{ ...pillStyle, left: 12 }} aria-label={t('autobahn:viewer.counterLabel', { current: i + 1, total: n })}>
                 <span className="num viewer-counter-num">
@@ -1118,25 +1350,34 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
               onPointerUp={onStagePointerUp}
               onPointerCancel={onStagePointerUp}
             >
-              <img
-                src={images[i]}
-                alt=""
-                draggable={false}
-                style={{
-                  position: 'absolute',
-                  inset: 0,
-                  width: '100%',
-                  height: '100%',
-                  objectFit: 'cover',
-                  transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
-                  // pinchRef too, not just dragRef — without it every pinch pointermove still
-                  // kicked off a 200ms eased transition toward a target that moves again before
-                  // it finishes, which reads as the image flickering/jittering bigger-smaller
-                  // instead of tracking the fingers 1:1 (drag already had this right).
-                  transition: (dragRef.current || pinchRef.current) ? 'none' : 'transform var(--dur-2, 200ms) var(--ease-standard, ease)',
-                  cursor: zoom > ZOOM_MIN ? 'grab' : undefined,
-                }}
-              />
+              {/* mobileTrackRef is SHARED with portrait above (same ref, same spring loop, same
+                  onStagePointer* handlers) — only one of portrait/landscape is ever mounted at a
+                  time, so there's no conflict; see portrait's copy of this comment for why
+                  transform isn't set here directly. */}
+              <div ref={mobileTrackRef} style={{ position: 'absolute', inset: 0, display: 'flex', height: '100%' }}>
+                {[images[(i - 1 + n) % n], images[i], images[(i + 1) % n]].map((src, k) => (
+                  <img
+                    key={k}
+                    src={src}
+                    alt=""
+                    draggable={false}
+                    style={{
+                      flex: '0 0 100%',
+                      width: '100%',
+                      height: '100%',
+                      objectFit: 'cover',
+                      transform: k === 1 ? `translate(${pan.x}px, ${pan.y}px) scale(${zoom})` : undefined,
+                      // pinchRef too, not just dragRef — without it every pinch pointermove still
+                      // kicked off a 200ms eased transition toward a target that moves again before
+                      // it finishes, which reads as the image flickering/jittering bigger-smaller
+                      // instead of tracking the fingers 1:1 (drag already had this right).
+                      transition:
+                        k === 1 ? ((dragRef.current || pinchRef.current) ? 'none' : 'transform var(--dur-2, 200ms) var(--ease-standard, ease)') : undefined,
+                      cursor: k === 1 && zoom > ZOOM_MIN ? 'grab' : undefined,
+                    }}
+                  />
+                ))}
+              </div>
             </div>
 
             {/* logo — Figma node 424:9330 "auto-de_RGB (2) 1": the actual asset there is the
@@ -1529,20 +1770,52 @@ const VdpViewer: React.FunctionComponent<VdpViewerProps> = ({ images, start = 0,
                 <IconButton name="x" size={24} className="vdp-viewer-light" label={t('autobahn:viewer.closeLabel')} onClick={onClose} />
               </div>
             </div>
-            <div style={{ flex: 1, position: 'relative', minHeight: 0, background: '#fff', overflow: 'hidden' }}>
-              <img
-                src={images[i]}
-                alt=""
-                style={{
-                  position: 'absolute',
-                  inset: 0,
-                  width: '100%',
-                  height: '100%',
-                  objectFit: 'contain',
-                  transform: `scale(${zoom})`,
-                  transition: 'transform var(--dur-2, 200ms) var(--ease-standard, ease)',
-                }}
-              />
+            <div
+              style={{
+                flex: 1,
+                position: 'relative',
+                minHeight: 0,
+                background: '#fff',
+                overflow: 'hidden',
+                cursor: n > 1 ? (isDesktopDragging ? 'grabbing' : 'grab') : undefined,
+                // Without this, a touch-capable desktop (a tablet reporting >860px, or Chrome's
+                // own device toolbar) hands a horizontal drag to the browser's native scroll/pan
+                // handling before onPointerMove ever sees it — same fix as CardCarousel's
+                // touch-action (see its own doc comment) applied here for the same reason.
+                touchAction: n > 1 ? 'pan-y' : undefined,
+              }}
+              onPointerDown={desktopOnPointerDown}
+              onPointerMove={desktopOnPointerMove}
+              onPointerUp={desktopOnPointerUp}
+              onPointerCancel={desktopOnPointerCancel}
+            >
+              {/* transform is NOT set here — desktopTrackRef's owned entirely by
+                  writeDesktopTransform() (the spring loop + drag handlers above), written
+                  straight to the DOM node. Same reasoning as CardCarousel's own track: letting
+                  React re-apply a matching value here too would fight the loop's per-frame
+                  writes for the same property. */}
+              <div ref={desktopTrackRef} style={{ display: 'flex', height: '100%' }}>
+                {[images[(i - 1 + n) % n], images[i], images[(i + 1) % n]].map((src, k) => (
+                  <img
+                    key={k}
+                    src={src}
+                    alt=""
+                    draggable={false}
+                    style={{
+                      flex: '0 0 100%',
+                      width: '100%',
+                      height: '100%',
+                      objectFit: 'contain',
+                      // Zoom only ever applies to the CENTER slot (the actually-displayed photo,
+                      // k===1) — prev/next are only ever visible mid-slide, and zoom always
+                      // resets to 1x on every `i` change anyway (see the effect above), so by the
+                      // time either of them could become the new center they're back to unzoomed.
+                      transform: k === 1 ? `scale(${zoom})` : undefined,
+                      transition: k === 1 ? 'transform var(--dur-2, 200ms) var(--ease-standard, ease)' : undefined,
+                    }}
+                  />
+                ))}
+              </div>
               <button
                 className="car-arrow car-arrow--l hide-mobile"
                 style={{ opacity: 1 }}