refactor: Update AssetGrid to wrap new timeline

- Update asset-grid.svelte to wrap Timeline component - Map old AssetGrid props to new Timeline props - Convert onThumbnailClick to onAssetOpen callback - Update change-date component to support icon and confirmText props This allows existing code to continue using AssetGrid API while internally using the new Timeline implementation.
refactor: new timeline component
2025-12-14 16:50:45 -08:00 · 2025-09-17 00:53:30 +00:00 · 2025-09-17 00:53:30 +00:00
23 changed files with 2670 additions and 976 deletions
--- a/i18n/en.json
+++ b/i18n/en.json
@@ -1337,6 +1337,8 @@
  "my_albums": "My albums",
  "name": "Name",
  "name_or_nickname": "Name or nickname",
  "navigate": "Navigate",
  "navigate_to_time": "Navigate to Time",
  "network_requirement_photos_upload": "Use cellular data to backup photos",
  "network_requirement_videos_upload": "Use cellular data to backup videos",
  "network_requirements_updated": "Network requirements changed, resetting backup queue",
--- a/web/src/lib/components/photos-page/asset-grid.svelte
+++ b/web/src/lib/components/photos-page/asset-grid.svelte
@@ -1,44 +1,12 @@
 <script lang="ts">
-  import { afterNavigate, beforeNavigate, goto } from '$app/navigation';
+  import Timeline from '$lib/components/timeline/timeline.svelte';
-  import { page } from '$app/stores';
+  import type { AssetAction } from '$lib/constants';
  import { resizeObserver, type OnResizeCallback } from '$lib/actions/resize-observer';
  import { shortcuts, type ShortcutOptions } from '$lib/actions/shortcut';
  import type { Action } from '$lib/components/asset-viewer/actions/action';
  import {
    setFocusToAsset as setFocusAssetInit,
    setFocusTo as setFocusToInit,
  } from '$lib/components/photos-page/actions/focus-actions';
  import Skeleton from '$lib/components/photos-page/skeleton.svelte';
  import ChangeDate from '$lib/components/shared-components/change-date.svelte';
  import Scrubber from '$lib/components/shared-components/scrubber/scrubber.svelte';
  import { AppRoute, AssetAction } from '$lib/constants';
  import { authManager } from '$lib/managers/auth-manager.svelte';
  import type { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
-  import type { MonthGroup } from '$lib/managers/timeline-manager/month-group.svelte';
+  import type { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import { assetsSnapshot } from '$lib/managers/timeline-manager/utils.svelte';
  import ShortcutsModal from '$lib/modals/ShortcutsModal.svelte';
  import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
-  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
+  import type { AlbumResponseDto, PersonResponseDto } from '@immich/sdk';
-  import { isSelectingAllAssets } from '$lib/stores/assets-store.svelte';
+  import type { Snippet } from 'svelte';
  import { mobileDevice } from '$lib/stores/mobile-device.svelte';
  import { showDeleteModal } from '$lib/stores/preferences.store';
  import { searchStore } from '$lib/stores/search.svelte';
  import { featureFlags } from '$lib/stores/server-config.store';
  import { handlePromiseError } from '$lib/utils';
  import { deleteAssets, updateStackedAssetInTimeline, updateUnstackedAssetInTimeline } from '$lib/utils/actions';
  import { archiveAssets, cancelMultiselect, selectAllAssets, stackAssets } from '$lib/utils/asset-utils';
  import { navigate } from '$lib/utils/navigation';
  import { getTimes, toTimelineAsset, type ScrubberListener, type TimelineYearMonth } from '$lib/utils/timeline-util';
  import { AssetVisibility, getAssetInfo, type AlbumResponseDto, type PersonResponseDto } from '@immich/sdk';
  import { modalManager } from '@immich/ui';
  import { DateTime } from 'luxon';
  import { onMount, type Snippet } from 'svelte';
  import type { UpdatePayload } from 'vite';
  import Portal from '../shared-components/portal/portal.svelte';
  import AssetDateGroup from './asset-date-group.svelte';
  import DeleteAssetDialog from './delete-asset-dialog.svelte';
  interface Props {
    isSelectionMode?: boolean;
@@ -86,7 +54,7 @@
    enableRouting,
    timelineManager = $bindable(),
    assetInteraction,
-    removeAction = null,
+    removeAction,
    withStacked = false,
    showArchiveIcon = false,
    isShared = false,
@@ -101,908 +69,34 @@
    onThumbnailClick,
  }: Props = $props();
-  let { isViewing: showAssetViewer, asset: viewingAsset, preloadAssets, gridScrollTarget, mutex } = assetViewingStore;
+  const onAssetOpen = (dayGroup: DayGroup, asset: TimelineAsset, defaultAssetOpen: () => void) => {
-
+    if (onThumbnailClick) {
-  let element: HTMLElement | undefined = $state();
+      onThumbnailClick(asset, timelineManager, dayGroup, () => defaultAssetOpen());
  let timelineElement: HTMLElement | undefined = $state();
  let showSkeleton = $state(true);
  let isShowSelectDate = $state(false);
  let scrubberMonthPercent = $state(0);
  let scrubberMonth: { year: number; month: number } | undefined = $state(undefined);
  let scrubOverallPercent: number = $state(0);
  let scrubberWidth = $state(0);
  // 60 is the bottom spacer element at 60px
  let bottomSectionHeight = 60;
  let leadout = $state(false);
  const maxMd = $derived(mobileDevice.maxMd);
  const usingMobileDevice = $derived(mobileDevice.pointerCoarse);
  $effect(() => {
    const layoutOptions = maxMd
      ? {
          rowHeight: 100,
          headerHeight: 32,
        }
      : {
          rowHeight: 235,
          headerHeight: 48,
        };
    timelineManager.setLayoutOptions(layoutOptions);
  });
  const scrollTo = (top: number) => {
    if (element) {
      element.scrollTo({ top });
    }
  };
  const scrollTop = (top: number) => {
    if (element) {
      element.scrollTop = top;
    }
  };
  const scrollBy = (y: number) => {
    if (element) {
      element.scrollBy(0, y);
    }
  };
  const scrollToTop = () => {
    scrollTo(0);
  };
  const getAssetHeight = (assetId: string, monthGroup: MonthGroup) => {
    // the following method may trigger any layouts, so need to
    // handle any scroll compensation that may have been set
    const height = monthGroup!.findAssetAbsolutePosition(assetId);
    while (timelineManager.scrollCompensation.monthGroup) {
      handleScrollCompensation(timelineManager.scrollCompensation);
      timelineManager.clearScrollCompensation();
    }
    return height;
  };
  const assetIsVisible = (assetTop: number): boolean => {
    if (!element) {
      return false;
    }
    const { clientHeight, scrollTop } = element;
    return assetTop >= scrollTop && assetTop < scrollTop + clientHeight;
  };
  const scrollToAssetId = async (assetId: string) => {
    const monthGroup = await timelineManager.findMonthGroupForAsset(assetId);
    if (!monthGroup) {
      return false;
    }
    const height = getAssetHeight(assetId, monthGroup);
    // If the asset is already visible, then don't scroll.
    if (assetIsVisible(height)) {
      return true;
    }
    scrollTo(height);
    updateSlidingWindow();
    return true;
  };
  const scrollToAsset = (asset: TimelineAsset) => {
    const monthGroup = timelineManager.getMonthGroupByAssetId(asset.id);
    if (!monthGroup) {
      return false;
    }
    const height = getAssetHeight(asset.id, monthGroup);
    scrollTo(height);
    updateSlidingWindow();
    return true;
  };
  const completeNav = async () => {
    const scrollTarget = $gridScrollTarget?.at;
    let scrolled = false;
    if (scrollTarget) {
      scrolled = await scrollToAssetId(scrollTarget);
    }
    if (!scrolled) {
      // if the asset is not found, scroll to the top
      scrollToTop();
    }
    showSkeleton = false;
  };
  beforeNavigate(() => (timelineManager.suspendTransitions = true));
  afterNavigate((nav) => {
    const { complete } = nav;
    complete.then(completeNav, completeNav);
  });
  const hmrSupport = () => {
    // when hmr happens, skeleton is initialized to true by default
    // normally, loading asset-grid is part of a navigation event, and the completion of
    // that event triggers a scroll-to-asset, if necessary, when then clears the skeleton.
    // this handler will run the navigation/scroll-to-asset handler when hmr is performed,
    // preventing skeleton from showing after hmr
    if (import.meta && import.meta.hot) {
      const afterApdate = (payload: UpdatePayload) => {
        const assetGridUpdate = payload.updates.some(
          (update) => update.path.endsWith('asset-grid.svelte') || update.path.endsWith('assets-store.ts'),
        );
        if (assetGridUpdate) {
          setTimeout(() => {
            const asset = $page.url.searchParams.get('at');
            if (asset) {
              $gridScrollTarget = { at: asset };
              void navigate(
                { targetRoute: 'current', assetId: null, assetGridRouteSearchParams: $gridScrollTarget },
                { replaceState: true, forceNavigate: true },
              );
            } else {
              scrollToTop();
            }
            showSkeleton = false;
          }, 500);
        }
      };
      import.meta.hot?.on('vite:afterUpdate', afterApdate);
      import.meta.hot?.on('vite:beforeUpdate', (payload) => {
        const assetGridUpdate = payload.updates.some((update) => update.path.endsWith('asset-grid.svelte'));
        if (assetGridUpdate) {
          timelineManager.destroy();
        }
      });
      return () => import.meta.hot?.off('vite:afterUpdate', afterApdate);
    }
    return () => void 0;
  };
  const updateIsScrolling = () => (timelineManager.scrolling = true);
  // note: don't throttle, debounch, or otherwise do this function async - it causes flicker
  const updateSlidingWindow = () => timelineManager.updateSlidingWindow(element?.scrollTop || 0);
  const handleScrollCompensation = ({ heightDelta, scrollTop }: { heightDelta?: number; scrollTop?: number }) => {
    if (heightDelta !== undefined) {
      scrollBy(heightDelta);
    } else if (scrollTop !== undefined) {
      scrollTo(scrollTop);
    }
    // Yes, updateSlideWindow() is called by the onScroll event triggered as a result of
    // the above calls. However, this delay is enough time to set the intersecting property
    // of the monthGroup to false, then true, which causes the DOM nodes to be recreated,
    // causing bad perf, and also, disrupting focus of those elements.
    updateSlidingWindow();
  };
  const topSectionResizeObserver: OnResizeCallback = ({ height }) => (timelineManager.topSectionHeight = height);
  onMount(() => {
    if (!enableRouting) {
      showSkeleton = false;
    }
    const disposeHmr = hmrSupport();
    return () => {
      disposeHmr();
    };
  });
  const getMaxScrollPercent = () => {
    const totalHeight = timelineManager.timelineHeight + bottomSectionHeight + timelineManager.topSectionHeight;
    return (totalHeight - timelineManager.viewportHeight) / totalHeight;
  };
  const getMaxScroll = () => {
    if (!element || !timelineElement) {
      return 0;
    }
    return (
      timelineManager.topSectionHeight + bottomSectionHeight + (timelineElement.clientHeight - element.clientHeight)
    );
  };
  const scrollToMonthGroupAndOffset = (monthGroup: MonthGroup, monthGroupScrollPercent: number) => {
    const topOffset = monthGroup.top;
    const maxScrollPercent = getMaxScrollPercent();
    const delta = monthGroup.height * monthGroupScrollPercent;
    const scrollToTop = (topOffset + delta) * maxScrollPercent;
    scrollTop(scrollToTop);
  };
  // note: don't throttle, debounch, or otherwise make this function async - it causes flicker
  const onScrub: ScrubberListener = (
    scrubMonth: { year: number; month: number },
    overallScrollPercent: number,
    scrubberMonthScrollPercent: number,
  ) => {
    if (!scrubMonth || timelineManager.timelineHeight < timelineManager.viewportHeight * 2) {
      // edge case - scroll limited due to size of content, must adjust - use use the overall percent instead
      const maxScroll = getMaxScroll();
      const offset = maxScroll * overallScrollPercent;
      scrollTop(offset);
    } else {
      const monthGroup = timelineManager.months.find(
        ({ yearMonth: { year, month } }) => year === scrubMonth.year && month === scrubMonth.month,
      );
      if (!monthGroup) {
      return;
    }
-      scrollToMonthGroupAndOffset(monthGroup, scrubberMonthScrollPercent);
+    defaultAssetOpen();
    }
  };
  // note: don't throttle, debounch, or otherwise make this function async - it causes flicker
  const handleTimelineScroll = () => {
    leadout = false;
    if (!element) {
      return;
    }
    if (timelineManager.timelineHeight < timelineManager.viewportHeight * 2) {
      // edge case - scroll limited due to size of content, must adjust -  use the overall percent instead
      const maxScroll = getMaxScroll();
      scrubOverallPercent = Math.min(1, element.scrollTop / maxScroll);
      scrubberMonth = undefined;
      scrubberMonthPercent = 0;
    } else {
      let top = element.scrollTop;
      if (top < timelineManager.topSectionHeight) {
        // in the lead-in area
        scrubberMonth = undefined;
        scrubberMonthPercent = 0;
        const maxScroll = getMaxScroll();
        scrubOverallPercent = Math.min(1, element.scrollTop / maxScroll);
        return;
      }
      let maxScrollPercent = getMaxScrollPercent();
      let found = false;
      const monthsLength = timelineManager.months.length;
      for (let i = -1; i < monthsLength + 1; i++) {
        let monthGroup: TimelineYearMonth | undefined;
        let monthGroupHeight = 0;
        if (i === -1) {
          // lead-in
          monthGroupHeight = timelineManager.topSectionHeight;
        } else if (i === monthsLength) {
          // lead-out
          monthGroupHeight = bottomSectionHeight;
        } else {
          monthGroup = timelineManager.months[i].yearMonth;
          monthGroupHeight = timelineManager.months[i].height;
        }
        let next = top - monthGroupHeight * maxScrollPercent;
        // instead of checking for < 0, add a little wiggle room for subpixel resolution
        if (next < -1 && monthGroup) {
          scrubberMonth = monthGroup;
          // allowing next to be at least 1 may cause percent to go negative, so ensure positive percentage
          scrubberMonthPercent = Math.max(0, top / (monthGroupHeight * maxScrollPercent));
          // compensate for lost precision/rounding errors advance to the next bucket, if present
          if (scrubberMonthPercent > 0.9999 && i + 1 < monthsLength - 1) {
            scrubberMonth = timelineManager.months[i + 1].yearMonth;
            scrubberMonthPercent = 0;
          }
          found = true;
          break;
        }
        top = next;
      }
      if (!found) {
        leadout = true;
        scrubberMonth = undefined;
        scrubberMonthPercent = 0;
        scrubOverallPercent = 1;
      }
    }
  };
  const trashOrDelete = async (force: boolean = false) => {
    isShowDeleteConfirmation = false;
    await deleteAssets(
      !(isTrashEnabled && !force),
      (assetIds) => timelineManager.removeAssets(assetIds),
      assetInteraction.selectedAssets,
      !isTrashEnabled || force ? undefined : (assets) => timelineManager.addAssets(assets),
    );
    assetInteraction.clearMultiselect();
  };
  const onDelete = () => {
    const hasTrashedAsset = assetInteraction.selectedAssets.some((asset) => asset.isTrashed);
    if ($showDeleteModal && (!isTrashEnabled || hasTrashedAsset)) {
      isShowDeleteConfirmation = true;
      return;
    }
    handlePromiseError(trashOrDelete(hasTrashedAsset));
  };
  const onForceDelete = () => {
    if ($showDeleteModal) {
      isShowDeleteConfirmation = true;
      return;
    }
    handlePromiseError(trashOrDelete(true));
  };
  const onStackAssets = async () => {
    const result = await stackAssets(assetInteraction.selectedAssets);
    updateStackedAssetInTimeline(timelineManager, result);
    onEscape();
  };
  const toggleArchive = async () => {
    const visibility = assetInteraction.isAllArchived ? AssetVisibility.Timeline : AssetVisibility.Archive;
    const ids = await archiveAssets(assetInteraction.selectedAssets, visibility);
    timelineManager.updateAssetOperation(ids, (asset) => {
      asset.visibility = visibility;
      return { remove: false };
    });
    deselectAllAssets();
  };
  const handleSelectAsset = (asset: TimelineAsset) => {
    if (!timelineManager.albumAssets.has(asset.id)) {
      assetInteraction.selectAsset(asset);
    }
  };
  const handlePrevious = async () => {
    const release = await mutex.acquire();
    const laterAsset = await timelineManager.getLaterAsset($viewingAsset);
    if (laterAsset) {
      const preloadAsset = await timelineManager.getLaterAsset(laterAsset);
      const asset = await getAssetInfo({ ...authManager.params, id: laterAsset.id });
      assetViewingStore.setAsset(asset, preloadAsset ? [preloadAsset] : []);
      await navigate({ targetRoute: 'current', assetId: laterAsset.id });
    }
    release();
    return !!laterAsset;
  };
  const handleNext = async () => {
    const release = await mutex.acquire();
    const earlierAsset = await timelineManager.getEarlierAsset($viewingAsset);
    if (earlierAsset) {
      const preloadAsset = await timelineManager.getEarlierAsset(earlierAsset);
      const asset = await getAssetInfo({ ...authManager.params, id: earlierAsset.id });
      assetViewingStore.setAsset(asset, preloadAsset ? [preloadAsset] : []);
      await navigate({ targetRoute: 'current', assetId: earlierAsset.id });
    }
    release();
    return !!earlierAsset;
  };
  const handleRandom = async () => {
    const randomAsset = await timelineManager.getRandomAsset();
    if (randomAsset) {
      const asset = await getAssetInfo({ ...authManager.params, id: randomAsset.id });
      assetViewingStore.setAsset(asset);
      await navigate({ targetRoute: 'current', assetId: randomAsset.id });
      return asset;
    }
  };
  const handleClose = async (asset: { id: string }) => {
    assetViewingStore.showAssetViewer(false);
    showSkeleton = true;
    $gridScrollTarget = { at: asset.id };
    await navigate({ targetRoute: 'current', assetId: null, assetGridRouteSearchParams: $gridScrollTarget });
  };
  const handlePreAction = async (action: Action) => {
    switch (action.type) {
      case removeAction:
      case AssetAction.TRASH:
      case AssetAction.RESTORE:
      case AssetAction.DELETE:
      case AssetAction.ARCHIVE:
      case AssetAction.SET_VISIBILITY_LOCKED:
      case AssetAction.SET_VISIBILITY_TIMELINE: {
        // find the next asset to show or close the viewer
        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
        (await handleNext()) || (await handlePrevious()) || (await handleClose(action.asset));
        // delete after find the next one
        timelineManager.removeAssets([action.asset.id]);
        break;
      }
    }
  };
  const handleAction = (action: Action) => {
    switch (action.type) {
      case AssetAction.ARCHIVE:
      case AssetAction.UNARCHIVE:
      case AssetAction.FAVORITE:
      case AssetAction.UNFAVORITE: {
        timelineManager.updateAssets([action.asset]);
        break;
      }
      case AssetAction.ADD: {
        timelineManager.addAssets([action.asset]);
        break;
      }
      case AssetAction.UNSTACK: {
        updateUnstackedAssetInTimeline(timelineManager, action.assets);
        break;
      }
      case AssetAction.REMOVE_ASSET_FROM_STACK: {
        timelineManager.addAssets([toTimelineAsset(action.asset)]);
        if (action.stack) {
          //Have to unstack then restack assets in timeline in order to update the stack count in the timeline.
          updateUnstackedAssetInTimeline(
            timelineManager,
            action.stack.assets.map((asset) => toTimelineAsset(asset)),
          );
          updateStackedAssetInTimeline(timelineManager, {
            stack: action.stack,
            toDeleteIds: action.stack.assets
              .filter((asset) => asset.id !== action.stack?.primaryAssetId)
              .map((asset) => asset.id),
          });
        }
        break;
      }
      case AssetAction.SET_STACK_PRIMARY_ASSET: {
        //Have to unstack then restack assets in timeline in order for the currently removed new primary asset to be made visible.
        updateUnstackedAssetInTimeline(
          timelineManager,
          action.stack.assets.map((asset) => toTimelineAsset(asset)),
        );
        updateStackedAssetInTimeline(timelineManager, {
          stack: action.stack,
          toDeleteIds: action.stack.assets
            .filter((asset) => asset.id !== action.stack.primaryAssetId)
            .map((asset) => asset.id),
        });
        break;
      }
    }
  };
  let lastAssetMouseEvent: TimelineAsset | null = $state(null);
  let shiftKeyIsDown = $state(false);
  const deselectAllAssets = () => {
    cancelMultiselect(assetInteraction);
  };
  const onKeyDown = (event: KeyboardEvent) => {
    if (searchStore.isSearchEnabled) {
      return;
    }
    if (event.key === 'Shift') {
      event.preventDefault();
      shiftKeyIsDown = true;
    }
  };
  const onKeyUp = (event: KeyboardEvent) => {
    if (searchStore.isSearchEnabled) {
      return;
    }
    if (event.key === 'Shift') {
      event.preventDefault();
      shiftKeyIsDown = false;
    }
  };
  const handleSelectAssetCandidates = (asset: TimelineAsset | null) => {
    if (asset) {
      void selectAssetCandidates(asset);
    }
    lastAssetMouseEvent = asset;
  };
  const handleGroupSelect = (timelineManager: TimelineManager, group: string, assets: TimelineAsset[]) => {
    if (assetInteraction.selectedGroup.has(group)) {
      assetInteraction.removeGroupFromMultiselectGroup(group);
      for (const asset of assets) {
        assetInteraction.removeAssetFromMultiselectGroup(asset.id);
      }
    } else {
      assetInteraction.addGroupToMultiselectGroup(group);
      for (const asset of assets) {
        handleSelectAsset(asset);
      }
    }
    if (timelineManager.assetCount == assetInteraction.selectedAssets.length) {
      isSelectingAllAssets.set(true);
    } else {
      isSelectingAllAssets.set(false);
    }
  };
  const handleSelectAssets = async (asset: TimelineAsset) => {
    if (!asset) {
      return;
    }
    onSelect(asset);
    if (singleSelect) {
      scrollTop(0);
      return;
    }
    const rangeSelection = assetInteraction.assetSelectionCandidates.length > 0;
    const deselect = assetInteraction.hasSelectedAsset(asset.id);
    // Select/deselect already loaded assets
    if (deselect) {
      for (const candidate of assetInteraction.assetSelectionCandidates) {
        assetInteraction.removeAssetFromMultiselectGroup(candidate.id);
      }
      assetInteraction.removeAssetFromMultiselectGroup(asset.id);
    } else {
      for (const candidate of assetInteraction.assetSelectionCandidates) {
        handleSelectAsset(candidate);
      }
      handleSelectAsset(asset);
    }
    assetInteraction.clearAssetSelectionCandidates();
    if (assetInteraction.assetSelectionStart && rangeSelection) {
      let startBucket = timelineManager.getMonthGroupByAssetId(assetInteraction.assetSelectionStart.id);
      let endBucket = timelineManager.getMonthGroupByAssetId(asset.id);
      if (startBucket === null || endBucket === null) {
        return;
      }
      // Select/deselect assets in range (start,end)
      let started = false;
      for (const monthGroup of timelineManager.months) {
        if (monthGroup === endBucket) {
          break;
        }
        if (started) {
          await timelineManager.loadMonthGroup(monthGroup.yearMonth);
          for (const asset of monthGroup.assetsIterator()) {
            if (deselect) {
              assetInteraction.removeAssetFromMultiselectGroup(asset.id);
            } else {
              handleSelectAsset(asset);
            }
          }
        }
        if (monthGroup === startBucket) {
          started = true;
        }
      }
      // Update date group selection in range [start,end]
      started = false;
      for (const monthGroup of timelineManager.months) {
        if (monthGroup === startBucket) {
          started = true;
        }
        if (started) {
          // Split month group into day groups and check each group
          for (const dayGroup of monthGroup.dayGroups) {
            const dayGroupTitle = dayGroup.groupTitle;
            if (dayGroup.getAssets().every((a) => assetInteraction.hasSelectedAsset(a.id))) {
              assetInteraction.addGroupToMultiselectGroup(dayGroupTitle);
            } else {
              assetInteraction.removeGroupFromMultiselectGroup(dayGroupTitle);
            }
          }
        }
        if (monthGroup === endBucket) {
          break;
        }
      }
    }
    assetInteraction.setAssetSelectionStart(deselect ? null : asset);
  };
  const selectAssetCandidates = async (endAsset: TimelineAsset) => {
    if (!shiftKeyIsDown) {
      return;
    }
    const startAsset = assetInteraction.assetSelectionStart;
    if (!startAsset) {
      return;
    }
    const assets = assetsSnapshot(await timelineManager.retrieveRange(startAsset, endAsset));
    assetInteraction.setAssetSelectionCandidates(assets);
  };
  const onSelectStart = (e: Event) => {
    if (assetInteraction.selectionActive && shiftKeyIsDown) {
      e.preventDefault();
    }
  };
  let isTrashEnabled = $derived($featureFlags.loaded && $featureFlags.trash);
  let isEmpty = $derived(timelineManager.isInitialized && timelineManager.months.length === 0);
  let idsSelectedAssets = $derived(assetInteraction.selectedAssets.map(({ id }) => id));
  let isShortcutModalOpen = false;
  const handleOpenShortcutModal = async () => {
    if (isShortcutModalOpen) {
      return;
    }
    isShortcutModalOpen = true;
    await modalManager.show(ShortcutsModal, {});
    isShortcutModalOpen = false;
  };
  $effect(() => {
    if (isEmpty) {
      assetInteraction.clearMultiselect();
    }
  });
  const setFocusTo = setFocusToInit.bind(undefined, scrollToAsset, timelineManager);
  const setFocusAsset = setFocusAssetInit.bind(undefined, scrollToAsset);
  let shortcutList = $derived(
    (() => {
      if (searchStore.isSearchEnabled || $showAssetViewer) {
        return [];
      }
      const shortcuts: ShortcutOptions[] = [
        { shortcut: { key: 'Escape' }, onShortcut: onEscape },
        { shortcut: { key: '?', shift: true }, onShortcut: handleOpenShortcutModal },
        { shortcut: { key: '/' }, onShortcut: () => goto(AppRoute.EXPLORE) },
        { shortcut: { key: 'A', ctrl: true }, onShortcut: () => selectAllAssets(timelineManager, assetInteraction) },
        { shortcut: { key: 'ArrowRight' }, onShortcut: () => setFocusTo('earlier', 'asset') },
        { shortcut: { key: 'ArrowLeft' }, onShortcut: () => setFocusTo('later', 'asset') },
        { shortcut: { key: 'D' }, onShortcut: () => setFocusTo('earlier', 'day') },
        { shortcut: { key: 'D', shift: true }, onShortcut: () => setFocusTo('later', 'day') },
        { shortcut: { key: 'M' }, onShortcut: () => setFocusTo('earlier', 'month') },
        { shortcut: { key: 'M', shift: true }, onShortcut: () => setFocusTo('later', 'month') },
        { shortcut: { key: 'Y' }, onShortcut: () => setFocusTo('earlier', 'year') },
        { shortcut: { key: 'Y', shift: true }, onShortcut: () => setFocusTo('later', 'year') },
        { shortcut: { key: 'G' }, onShortcut: () => (isShowSelectDate = true) },
      ];
      if (assetInteraction.selectionActive) {
        shortcuts.push(
          { shortcut: { key: 'Delete' }, onShortcut: onDelete },
          { shortcut: { key: 'Delete', shift: true }, onShortcut: onForceDelete },
          { shortcut: { key: 'D', ctrl: true }, onShortcut: () => deselectAllAssets() },
          { shortcut: { key: 's' }, onShortcut: () => onStackAssets() },
          { shortcut: { key: 'a', shift: true }, onShortcut: toggleArchive },
        );
      }
      return shortcuts;
    })(),
  );
  $effect(() => {
    if (!lastAssetMouseEvent) {
      assetInteraction.clearAssetSelectionCandidates();
    }
  });
  $effect(() => {
    if (!shiftKeyIsDown) {
      assetInteraction.clearAssetSelectionCandidates();
    }
  });
  $effect(() => {
    if (shiftKeyIsDown && lastAssetMouseEvent) {
      void selectAssetCandidates(lastAssetMouseEvent);
    }
  });
  $effect(() => {
    if ($showAssetViewer) {
      const { localDateTime } = getTimes($viewingAsset.fileCreatedAt, DateTime.local().offset / 60);
      void timelineManager.loadMonthGroup({ year: localDateTime.year, month: localDateTime.month });
    }
  });
 </script>
-<svelte:document onkeydown={onKeyDown} onkeyup={onKeyUp} onselectstart={onSelectStart} use:shortcuts={shortcutList} />
+<!-- AssetGrid Adapter: This is a compatibility layer that wraps the new Timeline component -->
-
+<!-- It maintains the old AssetGrid API while using the new Timeline implementation underneath -->
-{#if isShowDeleteConfirmation}
+<Timeline
  <DeleteAssetDialog
    size={idsSelectedAssets.length}
    onCancel={() => (isShowDeleteConfirmation = false)}
    onConfirm={() => handlePromiseError(trashOrDelete(true))}
  />
 {/if}
 {#if isShowSelectDate}
  <ChangeDate
    title="Navigate to Time"
    initialDate={DateTime.now()}
    timezoneInput={false}
    onConfirm={async (dateString: string) => {
      isShowSelectDate = false;
      const asset = await timelineManager.getClosestAssetToDate(
        (DateTime.fromISO(dateString) as DateTime<true>).toObject(),
      );
      if (asset) {
        setFocusAsset(asset);
      }
    }}
    onCancel={() => (isShowSelectDate = false)}
  />
 {/if}
 {#if timelineManager.months.length > 0}
  <Scrubber
    {timelineManager}
    height={timelineManager.viewportHeight}
    timelineTopOffset={timelineManager.topSectionHeight}
    timelineBottomOffset={bottomSectionHeight}
    {leadout}
    {scrubOverallPercent}
    {scrubberMonthPercent}
    {scrubberMonth}
    {onScrub}
    bind:scrubberWidth
    onScrubKeyDown={(evt) => {
      evt.preventDefault();
      let amount = 50;
      if (shiftKeyIsDown) {
        amount = 500;
      }
      if (evt.key === 'ArrowUp') {
        amount = -amount;
        if (shiftKeyIsDown) {
          element?.scrollBy({ top: amount, behavior: 'smooth' });
        }
      } else if (evt.key === 'ArrowDown') {
        element?.scrollBy({ top: amount, behavior: 'smooth' });
      }
    }}
  />
 {/if}
 <!-- Right margin MUST be equal to the width of scrubber -->
 <section
  id="asset-grid"
  class={['scrollbar-hidden h-full overflow-y-auto outline-none', { 'm-0': isEmpty }, { 'ms-0': !isEmpty }]}
  style:margin-right={(usingMobileDevice ? 0 : scrubberWidth) + 'px'}
  tabindex="-1"
  bind:clientHeight={timelineManager.viewportHeight}
  bind:clientWidth={null, (v: number) => ((timelineManager.viewportWidth = v), updateSlidingWindow())}
  bind:this={element}
  onscroll={() => (handleTimelineScroll(), updateSlidingWindow(), updateIsScrolling())}
 >
  <section
    bind:this={timelineElement}
    id="virtual-timeline"
    class:invisible={showSkeleton}
    style:height={timelineManager.timelineHeight + 'px'}
  >
    <section
      use:resizeObserver={topSectionResizeObserver}
      class:invisible={showSkeleton}
      style:position="absolute"
      style:left="0"
      style:right="0"
    >
      {@render children?.()}
      {#if isEmpty}
        <!-- (optional) empty placeholder -->
        {@render empty?.()}
      {/if}
    </section>
    {#each timelineManager.months as monthGroup (monthGroup.viewId)}
      {@const display = monthGroup.intersecting}
      {@const absoluteHeight = monthGroup.top}
      {#if !monthGroup.isLoaded}
        <div
          style:height={monthGroup.height + 'px'}
          style:position="absolute"
          style:transform={`translate3d(0,${absoluteHeight}px,0)`}
          style:width="100%"
        >
          <Skeleton
            height={monthGroup.height - monthGroup.timelineManager.headerHeight}
            title={monthGroup.monthGroupTitle}
          />
        </div>
      {:else if display}
        <div
          class="month-group"
          style:height={monthGroup.height + 'px'}
          style:position="absolute"
          style:transform={`translate3d(0,${absoluteHeight}px,0)`}
          style:width="100%"
        >
          <AssetDateGroup
            {withStacked}
            {showArchiveIcon}
            {assetInteraction}
            {timelineManager}
  {isSelectionMode}
  {singleSelect}
-            {monthGroup}
+  {enableRouting}
-            onSelect={({ title, assets }) => handleGroupSelect(timelineManager, title, assets)}
+  bind:timelineManager
-            onSelectAssetCandidates={handleSelectAssetCandidates}
+  {assetInteraction}
-            onSelectAssets={handleSelectAssets}
+  {removeAction}
            onScrollCompensation={handleScrollCompensation}
            {customLayout}
            {onThumbnailClick}
          />
        </div>
      {/if}
    {/each}
    <!-- spacer for leadout -->
    <div
      class="h-[60px]"
      style:position="absolute"
      style:left="0"
      style:right="0"
      style:transform={`translate3d(0,${timelineManager.timelineHeight}px,0)`}
    ></div>
  </section>
 </section>
 <Portal target="body">
  {#if $showAssetViewer}
    {#await import('../asset-viewer/asset-viewer.svelte') then { default: AssetViewer }}
      <AssetViewer
  {withStacked}
-        asset={$viewingAsset}
+  {showArchiveIcon}
        preloadAssets={$preloadAssets}
  {isShared}
  {album}
  {person}
-        preAction={handlePreAction}
+  bind:isShowDeleteConfirmation
-        onAction={handleAction}
+  {onAssetOpen}
-        onPrevious={handlePrevious}
+  {onSelect}
-        onNext={handleNext}
+  {onEscape}
-        onRandom={handleRandom}
+  {children}
-        onClose={handleClose}
+  {empty}
  customThumbnailLayout={customLayout}
 />
    {/await}
  {/if}
 </Portal>
 <style>
  #asset-grid {
    contain: strict;
    scrollbar-width: none;
  }
  .month-group {
    contain: layout size paint;
    transform-style: flat;
    backface-visibility: hidden;
    transform-origin: center center;
  }
 </style>
--- a/web/src/lib/components/photos-page/asset-viewer-actions.svelte
+++ b/web/src/lib/components/photos-page/asset-viewer-actions.svelte
@@ -0,0 +1,162 @@
 <script lang="ts">
  import type { Action } from '$lib/components/asset-viewer/actions/action';
  import { AssetAction } from '$lib/constants';
  import { authManager } from '$lib/managers/auth-manager.svelte';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import { updateStackedAssetInTimeline, updateUnstackedAssetInTimeline } from '$lib/utils/actions';
  import { navigate } from '$lib/utils/navigation';
  import { toTimelineAsset } from '$lib/utils/timeline-util';
  import { getAssetInfo, type AssetResponseDto } from '@immich/sdk';
  let { asset: viewingAsset, gridScrollTarget, mutex } = assetViewingStore;
  interface Props {
    timelineManager: TimelineManager;
    showSkeleton: boolean;
    removeAction?:
      | AssetAction.UNARCHIVE
      | AssetAction.ARCHIVE
      | AssetAction.FAVORITE
      | AssetAction.UNFAVORITE
      | AssetAction.SET_VISIBILITY_TIMELINE;
    handlePreAction?: (action: Action) => Promise<void>;
    handleAction?: (action: Action) => void;
    handleNext?: () => Promise<boolean>;
    handlePrevious?: () => Promise<boolean>;
    handleRandom?: () => Promise<AssetResponseDto | undefined>;
    handleClose?: (asset: { id: string }) => Promise<void>;
  }
  let {
    timelineManager = $bindable(),
    showSkeleton = $bindable(false),
    removeAction,
    handlePreAction = $bindable(),
    handleAction = $bindable(),
    handleNext = $bindable(),
    handlePrevious = $bindable(),
    handleRandom = $bindable(),
    handleClose = $bindable(),
  }: Props = $props();
  handlePrevious = async () => {
    const release = await mutex.acquire();
    const laterAsset = await timelineManager.getLaterAsset($viewingAsset);
    if (laterAsset) {
      const preloadAsset = await timelineManager.getLaterAsset(laterAsset);
      const asset = await getAssetInfo({ ...authManager.params, id: laterAsset.id });
      assetViewingStore.setAsset(asset, preloadAsset ? [preloadAsset] : []);
      await navigate({ targetRoute: 'current', assetId: laterAsset.id });
    }
    release();
    return !!laterAsset;
  };
  handleNext = async () => {
    const release = await mutex.acquire();
    const earlierAsset = await timelineManager.getEarlierAsset($viewingAsset);
    if (earlierAsset) {
      const preloadAsset = await timelineManager.getEarlierAsset(earlierAsset);
      const asset = await getAssetInfo({ ...authManager.params, id: earlierAsset.id });
      assetViewingStore.setAsset(asset, preloadAsset ? [preloadAsset] : []);
      await navigate({ targetRoute: 'current', assetId: earlierAsset.id });
    }
    release();
    return !!earlierAsset;
  };
  handleRandom = async () => {
    const randomAsset = await timelineManager.getRandomAsset();
    if (randomAsset) {
      const asset = await getAssetInfo({ ...authManager.params, id: randomAsset.id });
      assetViewingStore.setAsset(asset);
      await navigate({ targetRoute: 'current', assetId: randomAsset.id });
      return asset;
    }
  };
  handleClose = async (asset: { id: string }) => {
    assetViewingStore.showAssetViewer(false);
    showSkeleton = true;
    $gridScrollTarget = { at: asset.id };
    await navigate({ targetRoute: 'current', assetId: null, assetGridRouteSearchParams: $gridScrollTarget });
  };
  handlePreAction = async (action: Action) => {
    switch (action.type) {
      case removeAction:
      case AssetAction.TRASH:
      case AssetAction.RESTORE:
      case AssetAction.DELETE:
      case AssetAction.ARCHIVE:
      case AssetAction.SET_VISIBILITY_LOCKED:
      case AssetAction.SET_VISIBILITY_TIMELINE: {
        // find the next asset to show or close the viewer
        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
        (await handleNext()) || (await handlePrevious()) || (await handleClose(action.asset));
        // delete after find the next one
        timelineManager.removeAssets([action.asset.id]);
        break;
      }
    }
  };
  handleAction = (action: Action) => {
    switch (action.type) {
      case AssetAction.ARCHIVE:
      case AssetAction.UNARCHIVE:
      case AssetAction.FAVORITE:
      case AssetAction.UNFAVORITE: {
        timelineManager.updateAssets([action.asset]);
        break;
      }
      case AssetAction.ADD: {
        timelineManager.addAssets([action.asset]);
        break;
      }
      case AssetAction.UNSTACK: {
        updateUnstackedAssetInTimeline(timelineManager, action.assets);
        break;
      }
      case AssetAction.REMOVE_ASSET_FROM_STACK: {
        timelineManager.addAssets([toTimelineAsset(action.asset)]);
        if (action.stack) {
          //Have to unstack then restack assets in timeline in order to update the stack count in the timeline.
          updateUnstackedAssetInTimeline(
            timelineManager,
            action.stack.assets.map((asset) => toTimelineAsset(asset)),
          );
          updateStackedAssetInTimeline(timelineManager, {
            stack: action.stack,
            toDeleteIds: action.stack.assets
              .filter((asset) => asset.id !== action.stack?.primaryAssetId)
              .map((asset) => asset.id),
          });
        }
        break;
      }
      case AssetAction.SET_STACK_PRIMARY_ASSET: {
        //Have to unstack then restack assets in timeline in order for the currently removed new primary asset to be made visible.
        updateUnstackedAssetInTimeline(
          timelineManager,
          action.stack.assets.map((asset) => toTimelineAsset(asset)),
        );
        updateStackedAssetInTimeline(timelineManager, {
          stack: action.stack,
          toDeleteIds: action.stack.assets
            .filter((asset) => asset.id !== action.stack.primaryAssetId)
            .map((asset) => asset.id),
        });
        break;
      }
    }
  };
 </script>
--- a/web/src/lib/components/photos-page/asset-viewer-and-actions.svelte
+++ b/web/src/lib/components/photos-page/asset-viewer-and-actions.svelte
@@ -0,0 +1,73 @@
 <script lang="ts">
  import type { Action } from '$lib/components/asset-viewer/actions/action';
  import AssetViewerActions from '$lib/components/photos-page/asset-viewer-actions.svelte';
  import { AssetAction } from '$lib/constants';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import { type AlbumResponseDto, type AssetResponseDto, type PersonResponseDto } from '@immich/sdk';
  let { asset: viewingAsset, preloadAssets } = assetViewingStore;
  interface Props {
    timelineManager: TimelineManager;
    showSkeleton: boolean;
    removeAction?:
      | AssetAction.UNARCHIVE
      | AssetAction.ARCHIVE
      | AssetAction.FAVORITE
      | AssetAction.UNFAVORITE
      | AssetAction.SET_VISIBILITY_TIMELINE;
    withStacked?: boolean;
    isShared?: boolean;
    album?: AlbumResponseDto | null;
    person?: PersonResponseDto | null;
    isShowDeleteConfirmation?: boolean;
  }
  let {
    timelineManager = $bindable(),
    showSkeleton = $bindable(false),
    removeAction,
    withStacked = false,
    isShared = false,
    album = null,
    person = null,
    isShowDeleteConfirmation = $bindable(false),
  }: Props = $props();
  let handlePreAction = <(action: Action) => Promise<void>>$state();
  let handleAction = <(action: Action) => void>$state();
  let handleNext = <() => Promise<boolean>>$state();
  let handlePrevious = <() => Promise<boolean>>$state();
  let handleRandom = <() => Promise<AssetResponseDto | undefined>>$state();
  let handleClose = <(asset: { id: string }) => Promise<void>>$state();
 </script>
 <AssetViewerActions
  {timelineManager}
  {removeAction}
  bind:showSkeleton
  bind:handlePreAction
  bind:handleAction
  bind:handleNext
  bind:handlePrevious
  bind:handleRandom
  bind:handleClose
 ></AssetViewerActions>
 {#await import('../asset-viewer/asset-viewer.svelte') then { default: AssetViewer }}
  <AssetViewer
    {withStacked}
    asset={$viewingAsset}
    preloadAssets={$preloadAssets}
    {isShared}
    {album}
    {person}
    preAction={handlePreAction}
    onAction={handleAction}
    onPrevious={handlePrevious}
    onNext={handleNext}
    onRandom={handleRandom}
    onClose={handleClose}
  />
 {/await}
--- a/web/src/lib/components/shared-components/change-date.spec.ts
+++ b/web/src/lib/components/shared-components/change-date.spec.ts
@@ -8,6 +8,9 @@ import ChangeDate from './change-date.svelte';
 describe('ChangeDate component', () => {
  const initialDate = DateTime.fromISO('2024-01-01');
  const initialTimeZone = 'Europe/Berlin';
  const targetDate = DateTime.fromISO('2024-01-01').setZone('UTC+1', {
    keepLocalTime: true,
  });
  const currentInterval = {
    start: DateTime.fromISO('2000-02-01T14:00:00+01:00'),
    end: DateTime.fromISO('2001-02-01T14:00:00+01:00'),
@@ -43,7 +46,11 @@ describe('ChangeDate component', () => {
    await fireEvent.click(getConfirmButton());
-    expect(onConfirm).toHaveBeenCalledWith({ mode: 'absolute', date: '2024-01-01T00:00:00.000+01:00' });
+    expect(onConfirm).toHaveBeenCalledWith({
      mode: 'absolute',
      date: '2024-01-01T00:00:00.000+01:00',
      dateTime: targetDate,
    });
  });
  test('calls onCancel on cancel', async () => {
@@ -58,7 +65,9 @@ describe('ChangeDate component', () => {
  describe('when date is in daylight saving time', () => {
    const dstDate = DateTime.fromISO('2024-07-01');
-
+    const targetDate = DateTime.fromISO('2024-07-01').setZone('UTC+2', {
      keepLocalTime: true,
    });
    test('should render correct timezone with offset', () => {
      render(ChangeDate, { initialDate: dstDate, initialTimeZone, onCancel, onConfirm });
@@ -72,7 +81,11 @@ describe('ChangeDate component', () => {
      await fireEvent.click(getConfirmButton());
-      expect(onConfirm).toHaveBeenCalledWith({ mode: 'absolute', date: '2024-07-01T00:00:00.000+02:00' });
+      expect(onConfirm).toHaveBeenCalledWith({
        mode: 'absolute',
        date: '2024-07-01T00:00:00.000+02:00',
        dateTime: targetDate,
      });
    });
  });
--- a/web/src/lib/components/shared-components/change-date.svelte
+++ b/web/src/lib/components/shared-components/change-date.svelte
@@ -1,15 +1,14 @@
 <script lang="ts">
-  import { ConfirmModal } from '@immich/ui';
+  import { locale } from '$lib/stores/preferences.store';
-  import { mdiCalendarEditOutline } from '@mdi/js';
+  import { getDateTimeOffsetLocaleString } from '$lib/utils/timeline-util.js';
  import { ConfirmModal, Field, Switch } from '@immich/ui';
  import { mdiCalendarEdit } from '@mdi/js';
  import { DateTime, Duration } from 'luxon';
  import { t } from 'svelte-i18n';
  import DateInput from '../elements/date-input.svelte';
  import Combobox, { type ComboBoxOption } from './combobox.svelte';
  import DurationInput from '../elements/duration-input.svelte';
  import { Field, Switch } from '@immich/ui';
  import { getDateTimeOffsetLocaleString } from '$lib/utils/timeline-util.js';
  import { locale } from '$lib/stores/preferences.store';
  import { get } from 'svelte/store';
  import DateInput from '../elements/date-input.svelte';
  import DurationInput from '../elements/duration-input.svelte';
  import Combobox, { type ComboBoxOption } from './combobox.svelte';
  interface Props {
    title?: string;
@@ -18,6 +17,8 @@
    timezoneInput?: boolean;
    withDuration?: boolean;
    currentInterval?: { start: DateTime; end: DateTime };
    icon?: string;
    confirmText?: string;
    onCancel: () => void;
    onConfirm: (result: AbsoluteResult | RelativeResult) => void;
  }
@@ -29,6 +30,8 @@
    timezoneInput = true,
    withDuration = true,
    currentInterval = undefined,
    icon = mdiCalendarEdit,
    confirmText,
    onCancel,
    onConfirm,
  }: Props = $props();
@@ -36,6 +39,7 @@
  export type AbsoluteResult = {
    mode: 'absolute';
    date: string;
    dateTime: DateTime<true>;
  };
  export type RelativeResult = {
@@ -192,9 +196,13 @@
      const fixedOffsetZone = `UTC${offsetMinutes >= 0 ? '+' : ''}${Duration.fromObject({ minutes: offsetMinutes }).toFormat('hh:mm')}`;
      // Create a DateTime object in this fixed-offset zone, preserving the local time.
-      const finalDateTime = DateTime.fromObject(dtComponents.toObject(), { zone: fixedOffsetZone });
+      const finalDateTime = DateTime.fromObject(dtComponents.toObject(), { zone: fixedOffsetZone }) as DateTime<true>;
-      onConfirm({ mode: 'absolute', date: finalDateTime.toISO({ includeOffset: true })! });
+      onConfirm({
        mode: 'absolute',
        date: finalDateTime.toISO({ includeOffset: true }),
        dateTime: finalDateTime,
      });
    }
    if (showRelative && (selectedDuration || selectedRelativeOption)) {
@@ -238,7 +246,8 @@
 <ConfirmModal
  confirmColor="primary"
  {title}
-  icon={mdiCalendarEditOutline}
+  {icon}
  {confirmText}
  prompt="Please select a new date:"
  disabled={!date.isValid}
  onClose={(confirmed) => (confirmed ? handleConfirm() : onCancel())}
--- a/web/src/lib/components/shared-components/scrubber/scrubber.svelte
+++ b/web/src/lib/components/shared-components/scrubber/scrubber.svelte
@@ -4,25 +4,38 @@
  import type { ScrubberMonth } from '$lib/managers/timeline-manager/types';
  import { mobileDevice } from '$lib/stores/mobile-device.svelte';
  import { getTabbable } from '$lib/utils/focus-util';
-  import { type ScrubberListener } from '$lib/utils/timeline-util';
+  import { type ScrubberListener, type TimelineYearMonth } from '$lib/utils/timeline-util';
  import { mdiPlay } from '@mdi/js';
  import { clamp } from 'lodash-es';
  import { onMount } from 'svelte';
  import { fade, fly } from 'svelte/transition';
  interface Props {
    /** Offset from the top of the timeline (e.g., for headers) */
    timelineTopOffset?: number;
    /** Offset from the bottom of the timeline (e.g., for footers) */
    timelineBottomOffset?: number;
    /** Total height of the scrubber component */
    height?: number;
    /** Timeline manager instance that controls the timeline state */
    timelineManager: TimelineManager;
-    scrubOverallPercent?: number;
+    /** Overall scroll percentage through the entire timeline (0-1), used when no specific month is targeted */
-    scrubberMonthPercent?: number;
+    timelineScrollPercent?: number;
-    scrubberMonth?: { year: number; month: number };
+    /** The percentage of scroll through the month that is currently intersecting the top boundary of the viewport */
-    leadout?: boolean;
+    viewportTopMonthScrollPercent?: number;
    /** The year/month of the timeline month at the top of the viewport */
    viewportTopMonth?: TimelineYearMonth;
    /** Indicates whether the viewport is currently in the lead-out section (after all months) */
    isInLeadOutSection?: boolean;
    /** Width of the scrubber component in pixels (bindable for parent component margin adjustments) */
    scrubberWidth?: number;
    /** Callback fired when user interacts with the scrubber to navigate */
    onScrub?: ScrubberListener;
    /** Callback fired when keyboard events occur on the scrubber */
    onScrubKeyDown?: (event: KeyboardEvent, element: HTMLElement) => void;
    /** Callback fired when scrubbing starts */
    startScrub?: ScrubberListener;
    /** Callback fired when scrubbing stops */
    stopScrub?: ScrubberListener;
  }
@@ -31,10 +44,10 @@
    timelineBottomOffset = 0,
    height = 0,
    timelineManager,
-    scrubOverallPercent = 0,
+    timelineScrollPercent = 0,
-    scrubberMonthPercent = 0,
+    viewportTopMonthScrollPercent = 0,
-    scrubberMonth = undefined,
+    viewportTopMonth = undefined,
-    leadout = false,
+    isInLeadOutSection = false,
    onScrub = undefined,
    onScrubKeyDown = undefined,
    startScrub = undefined,
@@ -100,7 +113,7 @@
        offset += scrubberMonthPercent * relativeBottomOffset;
      }
      return offset;
-    } else if (leadout) {
+    } else if (isInLeadOutSection) {
      let offset = relativeTopOffset;
      for (const segment of segments) {
        offset += segment.height;
@@ -111,7 +124,9 @@
      return scrubOverallPercent * (height - (PADDING_TOP + PADDING_BOTTOM));
    }
  };
-  let scrollY = $derived(toScrollFromMonthGroupPercentage(scrubberMonth, scrubberMonthPercent, scrubOverallPercent));
+  let scrollY = $derived(
    toScrollFromMonthGroupPercentage(viewportTopMonth, viewportTopMonthScrollPercent, timelineScrollPercent),
  );
  let timelineFullHeight = $derived(timelineManager.scrubberTimelineHeight + timelineTopOffset + timelineBottomOffset);
  let relativeTopOffset = $derived(toScrollY(timelineTopOffset / timelineFullHeight));
  let relativeBottomOffset = $derived(toScrollY(timelineBottomOffset / timelineFullHeight));
@@ -295,12 +310,24 @@
    const scrollPercent = toTimelineY(hoverY);
    if (wasDragging === false && isDragging) {
-      void startScrub?.(segmentDate!, scrollPercent, monthGroupPercentY);
+      void startScrub?.({
-      void onScrub?.(segmentDate!, scrollPercent, monthGroupPercentY);
+        scrubberMonth: segmentDate!,
        overallScrollPercent: scrollPercent,
        scrubberMonthScrollPercent: monthGroupPercentY,
      });
      void onScrub?.({
        scrubberMonth: segmentDate!,
        overallScrollPercent: scrollPercent,
        scrubberMonthScrollPercent: monthGroupPercentY,
      });
    }
    if (wasDragging && !isDragging) {
-      void stopScrub?.(segmentDate!, scrollPercent, monthGroupPercentY);
+      void stopScrub?.({
        scrubberMonth: segmentDate!,
        overallScrollPercent: scrollPercent,
        scrubberMonthScrollPercent: monthGroupPercentY,
      });
      return;
    }
@@ -308,7 +335,11 @@
      return;
    }
-    void onScrub?.(segmentDate!, scrollPercent, monthGroupPercentY);
+    void onScrub?.({
      scrubberMonth: segmentDate!,
      overallScrollPercent: scrollPercent,
      scrubberMonthScrollPercent: monthGroupPercentY,
    });
  };
  /* eslint-disable tscompat/tscompat */
  const getTouch = (event: TouchEvent) => {
@@ -412,7 +443,11 @@
      }
      if (next) {
        event.preventDefault();
-        void onScrub?.({ year: next.year, month: next.month }, -1, 0);
+        void onScrub?.({
          scrubberMonth: { year: next.year, month: next.month },
          overallScrollPercent: -1,
          scrubberMonthScrollPercent: 0,
        });
        return true;
      }
    }
@@ -422,7 +457,11 @@
        const next = segments[idx + 1];
        if (next) {
          event.preventDefault();
-          void onScrub?.({ year: next.year, month: next.month }, -1, 0);
+          void onScrub?.({
            scrubberMonth: { year: next.year, month: next.month },
            overallScrollPercent: -1,
            scrubberMonthScrollPercent: 0,
          });
          return true;
        }
      }
--- a/web/src/lib/components/timeline/actions/delete-asset-dialog.svelte
+++ b/web/src/lib/components/timeline/actions/delete-asset-dialog.svelte
@@ -0,0 +1,47 @@
 <script lang="ts">
  import FormatMessage from '$lib/components/i18n/format-message.svelte';
  import { showDeleteModal } from '$lib/stores/preferences.store';
  import { Checkbox, ConfirmModal, Label } from '@immich/ui';
  import { mdiDeleteForeverOutline } from '@mdi/js';
  import { t } from 'svelte-i18n';
  interface Props {
    size: number;
    onConfirm: () => void;
    onCancel: () => void;
  }
  let { size, onConfirm, onCancel }: Props = $props();
  let checked = $state(false);
  const handleConfirm = () => {
    if (checked) {
      $showDeleteModal = false;
    }
    onConfirm();
  };
 </script>
 <ConfirmModal
  title={$t('permanently_delete_assets_count', { values: { count: size } })}
  confirmText={$t('delete')}
  icon={mdiDeleteForeverOutline}
  onClose={(confirmed) => (confirmed ? handleConfirm() : onCancel())}
 >
  {#snippet promptSnippet()}
    <p>
      <FormatMessage key="permanently_delete_assets_prompt" values={{ count: size }}>
        {#snippet children({ message })}
          <b>{message}</b>
        {/snippet}
      </FormatMessage>
    </p>
    <p><b>{$t('cannot_undo_this_action')}</b></p>
    <div class="pt-4 flex justify-center items-center gap-2">
      <Checkbox id="confirm-deletion-input" bind:checked color="secondary" />
      <Label label={$t('do_not_show_again')} for="confirm-deletion-input" />
    </div>
  {/snippet}
 </ConfirmModal>
--- a/web/src/lib/components/timeline/actions/timeline-keyboard-actions.svelte
+++ b/web/src/lib/components/timeline/actions/timeline-keyboard-actions.svelte
@@ -0,0 +1,225 @@
 <script lang="ts">
  import { goto } from '$app/navigation';
  import { shortcuts, type ShortcutOptions } from '$lib/actions/shortcut';
  import {
    setFocusToAsset as setFocusAssetInit,
    setFocusTo as setFocusToInit,
  } from '$lib/components/photos-page/actions/focus-actions';
  import ChangeDate, {
    type AbsoluteResult,
    type RelativeResult,
  } from '$lib/components/shared-components/change-date.svelte';
  import { AppRoute } from '$lib/constants';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import ShortcutsModal from '$lib/modals/ShortcutsModal.svelte';
  import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import { showDeleteModal } from '$lib/stores/preferences.store';
  import { searchStore } from '$lib/stores/search.svelte';
  import { featureFlags } from '$lib/stores/server-config.store';
  import { handlePromiseError } from '$lib/utils';
  import { deleteAssets, updateStackedAssetInTimeline } from '$lib/utils/actions';
  import { archiveAssets, cancelMultiselect, selectAllAssets, stackAssets } from '$lib/utils/asset-utils';
  import { AssetVisibility } from '@immich/sdk';
  import { modalManager } from '@immich/ui';
  import { mdiCalendarBlankOutline } from '@mdi/js';
  import { DateTime } from 'luxon';
  import { t } from 'svelte-i18n';
  import DeleteAssetDialog from './delete-asset-dialog.svelte';
  let { isViewing: showAssetViewer } = assetViewingStore;
  interface Props {
    timelineManager: TimelineManager;
    assetInteraction: AssetInteraction;
    isShowDeleteConfirmation: boolean;
    onEscape?: () => void;
    scrollToAsset: (asset: TimelineAsset) => boolean;
  }
  let {
    timelineManager = $bindable(),
    assetInteraction,
    isShowDeleteConfirmation = $bindable(false),
    onEscape,
    scrollToAsset,
  }: Props = $props();
  let isShowSelectDate = $state(false);
  const trashOrDelete = async (force: boolean = false) => {
    isShowDeleteConfirmation = false;
    await deleteAssets(
      !(isTrashEnabled && !force),
      (assetIds) => timelineManager.removeAssets(assetIds),
      assetInteraction.selectedAssets,
      !isTrashEnabled || force ? undefined : (assets) => timelineManager.addAssets(assets),
    );
    assetInteraction.clearMultiselect();
  };
  const onDelete = () => {
    const hasTrashedAsset = assetInteraction.selectedAssets.some((asset) => asset.isTrashed);
    if ($showDeleteModal && (!isTrashEnabled || hasTrashedAsset)) {
      isShowDeleteConfirmation = true;
      return;
    }
    handlePromiseError(trashOrDelete(hasTrashedAsset));
  };
  const onForceDelete = () => {
    if ($showDeleteModal) {
      isShowDeleteConfirmation = true;
      return;
    }
    handlePromiseError(trashOrDelete(true));
  };
  const onStackAssets = async () => {
    const result = await stackAssets(assetInteraction.selectedAssets);
    updateStackedAssetInTimeline(timelineManager, result);
    onEscape?.();
  };
  const toggleArchive = async () => {
    const visibility = assetInteraction.isAllArchived ? AssetVisibility.Timeline : AssetVisibility.Archive;
    const ids = await archiveAssets(assetInteraction.selectedAssets, visibility);
    timelineManager.updateAssetOperation(ids, (asset) => {
      asset.visibility = visibility;
      return { remove: false };
    });
    deselectAllAssets();
  };
  let shiftKeyIsDown = $state(false);
  const deselectAllAssets = () => {
    cancelMultiselect(assetInteraction);
  };
  const onKeyDown = (event: KeyboardEvent) => {
    if (searchStore.isSearchEnabled) {
      return;
    }
    if (event.key === 'Shift') {
      event.preventDefault();
      shiftKeyIsDown = true;
    }
  };
  const onKeyUp = (event: KeyboardEvent) => {
    if (searchStore.isSearchEnabled) {
      return;
    }
    if (event.key === 'Shift') {
      event.preventDefault();
      shiftKeyIsDown = false;
    }
  };
  const onSelectStart = (e: Event) => {
    if (assetInteraction.selectionActive && shiftKeyIsDown) {
      e.preventDefault();
    }
  };
  const isTrashEnabled = $derived($featureFlags.loaded && $featureFlags.trash);
  const isEmpty = $derived(timelineManager.isInitialized && timelineManager.months.length === 0);
  const idsSelectedAssets = $derived(assetInteraction.selectedAssets.map(({ id }) => id));
  let isShortcutModalOpen = false;
  const handleOpenShortcutModal = async () => {
    if (isShortcutModalOpen) {
      return;
    }
    isShortcutModalOpen = true;
    await modalManager.show(ShortcutsModal, {});
    isShortcutModalOpen = false;
  };
  $effect(() => {
    if (isEmpty) {
      assetInteraction.clearMultiselect();
    }
  });
  const setFocusTo = setFocusToInit.bind(undefined, scrollToAsset, timelineManager);
  const setFocusAsset = setFocusAssetInit.bind(undefined, scrollToAsset);
  let shortcutList = $derived(
    (() => {
      if (searchStore.isSearchEnabled || $showAssetViewer) {
        return [];
      }
      const shortcuts: ShortcutOptions[] = [
        { shortcut: { key: '?', shift: true }, onShortcut: handleOpenShortcutModal },
        { shortcut: { key: '/' }, onShortcut: () => goto(AppRoute.EXPLORE) },
        { shortcut: { key: 'A', ctrl: true }, onShortcut: () => selectAllAssets(timelineManager, assetInteraction) },
        { shortcut: { key: 'ArrowRight' }, onShortcut: () => setFocusTo('earlier', 'asset') },
        { shortcut: { key: 'ArrowLeft' }, onShortcut: () => setFocusTo('later', 'asset') },
        { shortcut: { key: 'D' }, onShortcut: () => setFocusTo('earlier', 'day') },
        { shortcut: { key: 'D', shift: true }, onShortcut: () => setFocusTo('later', 'day') },
        { shortcut: { key: 'M' }, onShortcut: () => setFocusTo('earlier', 'month') },
        { shortcut: { key: 'M', shift: true }, onShortcut: () => setFocusTo('later', 'month') },
        { shortcut: { key: 'Y' }, onShortcut: () => setFocusTo('earlier', 'year') },
        { shortcut: { key: 'Y', shift: true }, onShortcut: () => setFocusTo('later', 'year') },
        { shortcut: { key: 'G' }, onShortcut: () => (isShowSelectDate = true) },
      ];
      if (onEscape) {
        shortcuts.push({ shortcut: { key: 'Escape' }, onShortcut: onEscape });
      }
      if (assetInteraction.selectionActive) {
        shortcuts.push(
          { shortcut: { key: 'Delete' }, onShortcut: onDelete },
          { shortcut: { key: 'Delete', shift: true }, onShortcut: onForceDelete },
          { shortcut: { key: 'D', ctrl: true }, onShortcut: () => deselectAllAssets() },
          { shortcut: { key: 's' }, onShortcut: () => onStackAssets() },
          { shortcut: { key: 'a', shift: true }, onShortcut: toggleArchive },
        );
      }
      return shortcuts;
    })(),
  );
 </script>
 <svelte:document onkeydown={onKeyDown} onkeyup={onKeyUp} onselectstart={onSelectStart} use:shortcuts={shortcutList} />
 {#if isShowDeleteConfirmation}
  <DeleteAssetDialog
    size={idsSelectedAssets.length}
    onCancel={() => (isShowDeleteConfirmation = false)}
    onConfirm={() => handlePromiseError(trashOrDelete(true))}
  />
 {/if}
 {#if isShowSelectDate}
  <ChangeDate
    withDuration={false}
    icon={mdiCalendarBlankOutline}
    confirmText={$t('navigate')}
    title={$t('navigate_to_time')}
    initialDate={DateTime.now()}
    timezoneInput={false}
    onConfirm={async (result: AbsoluteResult | RelativeResult) => {
      isShowSelectDate = false;
      if (result.mode === 'absolute') {
        const asset = await timelineManager.getClosestAssetToDate(
          (DateTime.fromISO(result.date) as DateTime<true>).toObject(),
        );
        if (asset) {
          setFocusAsset(asset);
        }
      }
    }}
    onCancel={() => (isShowSelectDate = false)}
  />
 {/if}
--- a/web/src/lib/components/timeline/base-components/base-timeline-viewer.svelte
+++ b/web/src/lib/components/timeline/base-components/base-timeline-viewer.svelte
@@ -0,0 +1,318 @@
 <script lang="ts">
  import { afterNavigate, beforeNavigate } from '$app/navigation';
  import { page } from '$app/stores';
  import { resizeObserver, type OnResizeCallback } from '$lib/actions/resize-observer';
  import Hmr from '$lib/components/timeline/base-components/hmr.svelte';
  import Skeleton from '$lib/components/timeline/base-components/skeleton.svelte';
  import SelectableTimelineMonth from '$lib/components/timeline/internal-components/selectable-timeline-month.svelte';
  import type { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
  import type { MonthGroup } from '$lib/managers/timeline-manager/month-group.svelte';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import { mobileDevice } from '$lib/stores/mobile-device.svelte';
  import { onMount, type Snippet } from 'svelte';
  import type { UpdatePayload } from 'vite';
  interface Props {
    customThumbnailLayout?: Snippet<[TimelineAsset]>;
    isSelectionMode?: boolean;
    singleSelect?: boolean;
    /** `true` if this asset grid responds to navigation events; if `true`, then look at the
     `AssetViewingStore.gridScrollTarget` and load and scroll to the asset specified, and
     additionally, update the page location/url with the asset as the asset-grid is scrolled */
    enableRouting: boolean;
    timelineManager: TimelineManager;
    assetInteraction: AssetInteraction;
    withStacked?: boolean;
    showArchiveIcon?: boolean;
    showSkeleton?: boolean;
    isShowDeleteConfirmation?: boolean;
    styleMarginRightOverride?: string;
    onAssetOpen?: (dayGroup: DayGroup, asset: TimelineAsset, defaultAssetOpen: () => void) => void;
    onSelect?: (asset: TimelineAsset) => void;
    header?: Snippet<[scrollToFunction: (top: number) => void]>;
    children?: Snippet;
    empty?: Snippet;
    handleTimelineScroll?: () => void;
  }
  let {
    customThumbnailLayout,
    isSelectionMode = false,
    singleSelect = false,
    enableRouting,
    timelineManager = $bindable(),
    assetInteraction,
    withStacked = false,
    showSkeleton = $bindable(true),
    showArchiveIcon = false,
    styleMarginRightOverride,
    isShowDeleteConfirmation = $bindable(false),
    onAssetOpen,
    onSelect,
    children,
    empty,
    header,
    handleTimelineScroll = () => {},
  }: Props = $props();
  let { gridScrollTarget } = assetViewingStore;
  let element: HTMLElement | undefined = $state();
  let timelineElement: HTMLElement | undefined = $state();
  const maxMd = $derived(mobileDevice.maxMd);
  const isEmpty = $derived(timelineManager.isInitialized && timelineManager.months.length === 0);
  $effect(() => {
    const layoutOptions = maxMd
      ? {
          rowHeight: 100,
          headerHeight: 32,
        }
      : {
          rowHeight: 235,
          headerHeight: 48,
        };
    timelineManager.setLayoutOptions(layoutOptions);
  });
  const scrollTo = (top: number) => {
    if (element) {
      element.scrollTo({ top });
    }
    updateSlidingWindow();
  };
  const scrollBy = (y: number) => {
    if (element) {
      element.scrollBy(0, y);
    }
    updateSlidingWindow();
  };
  const scrollCompensation = (compensation: { heightDelta?: number; scrollTop?: number }) => {
    const { heightDelta, scrollTop } = compensation;
    if (heightDelta !== undefined) {
      scrollBy(heightDelta);
    } else if (scrollTop !== undefined) {
      scrollTo(scrollTop);
    }
    timelineManager.clearScrollCompensation();
  };
  const getAssetHeight = (assetId: string, monthGroup: MonthGroup) => {
    // the following method may trigger any layouts, so need to
    // handle any scroll compensation that may have been set
    const height = monthGroup!.findAssetAbsolutePosition(assetId);
    // this is in a while loop, since scrollCompensations invoke scrolls
    // which may load months, triggering more scrollCompensations. Call
    // this in a loop, until no more layouts occur.
    while (timelineManager.scrollCompensation.monthGroup) {
      scrollCompensation(timelineManager.scrollCompensation);
    }
    return height;
  };
  const assetIsVisible = (assetTop: number): boolean => {
    if (!element) {
      return false;
    }
    const { clientHeight, scrollTop } = element;
    return assetTop >= scrollTop && assetTop < scrollTop + clientHeight;
  };
  const scrollToAssetId = async (assetId: string) => {
    const monthGroup = await timelineManager.findMonthGroupForAsset(assetId);
    if (!monthGroup) {
      return false;
    }
    const height = getAssetHeight(assetId, monthGroup);
    // If the asset is already visible, then don't scroll.
    if (assetIsVisible(height)) {
      return true;
    }
    scrollTo(height);
    return true;
  };
  export const scrollToAsset = (asset: TimelineAsset) => {
    const monthGroup = timelineManager.getMonthGroupByAssetId(asset.id);
    if (!monthGroup) {
      return false;
    }
    const height = getAssetHeight(asset.id, monthGroup);
    scrollTo(height);
    return true;
  };
  const completeNav = async () => {
    const scrollTarget = $gridScrollTarget?.at;
    let scrolled = false;
    if (scrollTarget) {
      scrolled = await scrollToAssetId(scrollTarget);
    }
    if (!scrolled) {
      // if the asset is not found, scroll to the top
      scrollTo(0);
    }
    showSkeleton = false;
  };
  beforeNavigate(() => (timelineManager.suspendTransitions = true));
  afterNavigate((nav) => {
    const { complete } = nav;
    complete.then(completeNav, completeNav);
  });
  const updateIsScrolling = () => (timelineManager.scrolling = true);
  // Yes, updateSlideWindow() is called by the onScroll event. However, if you also just scrolled
  // by explicitly invoking element.scrollX functions, there may be a delay with enough time to
  // set the intersecting property of the monthGroup to false, then true, which causes the DOM
  // nodes to be recreated, causing bad perf, and also, disrupting focus of those elements.
  // Also note: don't throttle, debounce, or otherwise do this function async - it causes flicker
  const updateSlidingWindow = () => timelineManager.updateSlidingWindow(element?.scrollTop || 0);
  const topSectionResizeObserver: OnResizeCallback = ({ height }) => (timelineManager.topSectionHeight = height);
  onMount(() => {
    if (!enableRouting) {
      showSkeleton = false;
    }
  });
 </script>
 <Hmr
  onAfterUpdate={(payload: UpdatePayload) => {
    // when hmr happens, skeleton is initialized to true by default
    // normally, loading asset-grid is part of a navigation event, and the completion of
    // that event triggers a scroll-to-asset, if necessary, when then clears the skeleton.
    // this handler will run the navigation/scroll-to-asset handler when hmr is performed,
    // preventing skeleton from showing after hmr
    const finishHmr = () => {
      const asset = $page.url.searchParams.get('at');
      if (asset) {
        $gridScrollTarget = { at: asset };
      }
      void completeNav();
    };
    const assetGridUpdate = payload.updates.some((update) => update.path.endsWith('base-timeline-viewer.svelte'));
    if (assetGridUpdate) {
      // wait 500ms for the update to be fully swapped in
      setTimeout(finishHmr, 500);
    }
  }}
 />
 {@render header?.(scrollTo)}
 <!-- Right margin MUST be equal to the width of scrubber -->
 <section
  id="asset-grid"
  class={['scrollbar-hidden h-full overflow-y-auto outline-none', { 'm-0': isEmpty }, { 'ms-0': !isEmpty }]}
  style:margin-right={styleMarginRightOverride}
  tabindex="-1"
  bind:clientHeight={timelineManager.viewportHeight}
  bind:clientWidth={null, (v: number) => ((timelineManager.viewportWidth = v), updateSlidingWindow())}
  bind:this={element}
  onscroll={() => (handleTimelineScroll(), updateSlidingWindow(), updateIsScrolling())}
 >
  <section
    bind:this={timelineElement}
    id="virtual-timeline"
    class:invisible={showSkeleton}
    style:height={timelineManager.timelineHeight + 'px'}
  >
    <section
      use:resizeObserver={topSectionResizeObserver}
      class:invisible={showSkeleton}
      style:position="absolute"
      style:left="0"
      style:right="0"
    >
      {@render children?.()}
      {#if isEmpty}
        <!-- (optional) empty placeholder -->
        {@render empty?.()}
      {/if}
    </section>
    {#each timelineManager.months as monthGroup (monthGroup.viewId)}
      {@const display = monthGroup.intersecting}
      {@const absoluteHeight = monthGroup.top}
      {#if !monthGroup.isLoaded}
        <div
          style:height={monthGroup.height + 'px'}
          style:position="absolute"
          style:transform={`translate3d(0,${absoluteHeight}px,0)`}
          style:width="100%"
        >
          <Skeleton
            height={monthGroup.height - monthGroup.timelineManager.headerHeight}
            title={monthGroup.monthGroupTitle}
          />
        </div>
      {:else if display}
        <div
          class="month-group"
          style:height={monthGroup.height + 'px'}
          style:position="absolute"
          style:transform={`translate3d(0,${absoluteHeight}px,0)`}
          style:width="100%"
        >
          <SelectableTimelineMonth
            {customThumbnailLayout}
            {withStacked}
            {showArchiveIcon}
            {assetInteraction}
            {timelineManager}
            {isSelectionMode}
            {singleSelect}
            {monthGroup}
            {onAssetOpen}
            onSelect={(isSingleSelect: boolean, asset: TimelineAsset) => {
              if (isSingleSelect) {
                scrollTo(0);
              }
              onSelect?.(asset);
            }}
            onScrollCompensationMonthInDOM={scrollCompensation}
          />
        </div>
      {/if}
    {/each}
    <!-- spacer for lead-out -->
    <div
      class="h-[60px]"
      style:position="absolute"
      style:left="0"
      style:right="0"
      style:transform={`translate3d(0,${timelineManager.timelineHeight}px,0)`}
    ></div>
  </section>
 </section>
 <style>
  #asset-grid {
    contain: strict;
    scrollbar-width: none;
  }
  .month-group {
    contain: layout size paint;
    transform-style: flat;
    backface-visibility: hidden;
    transform-origin: center center;
  }
 </style>
--- a/web/src/lib/components/timeline/base-components/base-timeline.svelte
+++ b/web/src/lib/components/timeline/base-components/base-timeline.svelte
@@ -0,0 +1,201 @@
 <script lang="ts">
  import BaseTimelineViewer from '$lib/components/timeline/base-components/base-timeline-viewer.svelte';
  import type { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
  import type { MonthGroup } from '$lib/managers/timeline-manager/month-group.svelte';
  import type { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
  import { findMonthAtScrollPosition, type ScrubberListener, type TimelineYearMonth } from '$lib/utils/timeline-util';
  import type { Snippet } from 'svelte';
  import Scrubber from './scrubber.svelte';
  interface Props {
    customThumbnailLayout?: Snippet<[TimelineAsset]>;
    isSelectionMode?: boolean;
    singleSelect?: boolean;
    /** `true` if this timeline responds to navigation events; if `true`, then look at the
     `AssetViewingStore.gridScrollTarget` and load and scroll to the asset specified, and
     additionally, update the page location/url with the asset as the asset-grid is scrolled */
    enableRouting: boolean;
    timelineManager: TimelineManager;
    assetInteraction: AssetInteraction;
    withStacked?: boolean;
    showArchiveIcon?: boolean;
    showSkeleton?: boolean;
    isShowDeleteConfirmation?: boolean;
    onAssetOpen?: (dayGroup: DayGroup, asset: TimelineAsset, defaultAssetOpen: () => void) => void;
    onSelect?: (asset: TimelineAsset) => void;
    children?: Snippet;
    empty?: Snippet;
  }
  let {
    customThumbnailLayout,
    isSelectionMode = false,
    singleSelect = false,
    enableRouting,
    timelineManager = $bindable(),
    assetInteraction,
    withStacked = false,
    showArchiveIcon = false,
    showSkeleton = $bindable(true),
    isShowDeleteConfirmation = $bindable(false),
    onAssetOpen,
    onSelect = () => {},
    children,
    empty,
  }: Props = $props();
  const VIEWPORT_MULTIPLIER = 2; // Used to determine if timeline is "small"
  // The percentage of scroll through the month that is currently intersecting the top boundary of the viewport.
  // Note: There may be multiple months visible within the viewport at any given time.
  let viewportTopMonthScrollPercent = $state(0);
  // The timeline month intersecting the top position of the viewport
  let viewportTopMonth: TimelineYearMonth | undefined = $state(undefined);
  // Overall scroll percentage through the entire timeline (0-1)
  let timelineScrollPercent: number = $state(0);
  // Indicates whether the viewport is currently in the lead-out section (after all months)
  let isInLeadOutSection = $state(false);
  // Width of the scrubber component in pixels, used to adjust timeline margins
  let scrubberWidth: number = $state(0);
  // note: don't throttle, debounce, or otherwise make this function async - it causes flicker
  // this function updates the scrubber position based on the current scroll position in the timeline
  const handleTimelineScroll = () => {
    isInLeadOutSection = false;
    // Handle edge cases: small timeline (limited scroll) or lead-in area scrolling
    const top = timelineManager.visibleWindow.top;
    if (isSmallTimeline() || top < timelineManager.topSectionHeight) {
      calculateTimelineScrollPercent();
      return;
    }
    // Handle normal month scrolling
    handleMonthScroll();
  };
  const handleMonthScroll = () => {
    const scrollPosition = timelineManager.visibleWindow.top;
    const months = timelineManager.months;
    const maxScrollPercent = timelineManager.getMaxScrollPercent();
    // Find the month at the current scroll position
    const searchResult = findMonthAtScrollPosition(months, scrollPosition, maxScrollPercent);
    if (searchResult) {
      viewportTopMonth = searchResult.month;
      viewportTopMonthScrollPercent = searchResult.monthScrollPercent;
      isInLeadOutSection = false;
      return;
    }
    // We're in lead-out section
    isInLeadOutSection = true;
    timelineScrollPercent = 1;
    resetScrubberMonth();
  };
  const resetScrubberMonth = () => {
    viewportTopMonth = undefined;
    viewportTopMonthScrollPercent = 0;
  };
  const calculateTimelineScrollPercent = () => {
    const maxScroll = timelineManager.getMaxScroll();
    timelineScrollPercent = Math.min(1, timelineManager.visibleWindow.top / maxScroll);
    resetScrubberMonth();
  };
  const handleOverallPercentScroll = (percent: number, scrollTo?: (offset: number) => void) => {
    const maxScroll = timelineManager.getMaxScroll();
    const offset = maxScroll * percent;
    scrollTo?.(offset);
  };
  const findMonthGroup = (target: TimelineYearMonth) => {
    return timelineManager.months.find(
      ({ yearMonth }) => yearMonth.year === target.year && yearMonth.month === target.month,
    );
  };
  const isSmallTimeline = () => {
    return timelineManager.timelineHeight < timelineManager.viewportHeight * VIEWPORT_MULTIPLIER;
  };
  // note: don't throttle, debounce, or otherwise make this function async - it causes flicker
  // this function scrolls the timeline to the specified month group and offset, based on scrubber interaction
  const onScrub: ScrubberListener = (scrubberData) => {
    const { scrubberMonth, overallScrollPercent, scrubberMonthScrollPercent, scrollToFunction } = scrubberData;
    // Handle edge case or no month selected
    if (!scrubberMonth || isSmallTimeline()) {
      handleOverallPercentScroll(overallScrollPercent, scrollToFunction);
      return;
    }
    // Find and scroll to the selected month
    const monthGroup = findMonthGroup(scrubberMonth);
    if (monthGroup) {
      scrollToPositionWithinMonth(monthGroup, scrubberMonthScrollPercent, scrollToFunction);
    }
  };
  const scrollToPositionWithinMonth = (
    monthGroup: MonthGroup,
    monthGroupScrollPercent: number,
    handleScrollTop?: (top: number) => void,
  ) => {
    const topOffset = monthGroup.top;
    const maxScrollPercent = timelineManager.getMaxScrollPercent();
    const delta = monthGroup.height * monthGroupScrollPercent;
    const scrollToTop = (topOffset + delta) * maxScrollPercent;
    handleScrollTop?.(scrollToTop);
  };
  let baseTimelineViewer: BaseTimelineViewer | undefined = $state();
  export const scrollToAsset = (asset: TimelineAsset) => baseTimelineViewer?.scrollToAsset(asset) ?? false;
 </script>
 <BaseTimelineViewer
  bind:this={baseTimelineViewer}
  {customThumbnailLayout}
  {isSelectionMode}
  {singleSelect}
  {enableRouting}
  {timelineManager}
  {assetInteraction}
  {withStacked}
  {showArchiveIcon}
  {showSkeleton}
  {isShowDeleteConfirmation}
  styleMarginRightOverride={scrubberWidth + 'px'}
  {onAssetOpen}
  {onSelect}
  {children}
  {empty}
  {handleTimelineScroll}
 >
  {#snippet header(scrollToFunction)}
    {#if timelineManager.months.length > 0}
      <Scrubber
        {timelineManager}
        height={timelineManager.viewportHeight}
        timelineTopOffset={timelineManager.topSectionHeight}
        timelineBottomOffset={timelineManager.bottomSectionHeight}
        {isInLeadOutSection}
        {timelineScrollPercent}
        {viewportTopMonthScrollPercent}
        {viewportTopMonth}
        onScrub={(scrubberData) => onScrub({ ...scrubberData, scrollToFunction })}
        bind:scrubberWidth
      />
    {/if}
  {/snippet}
 </BaseTimelineViewer>
--- a/web/src/lib/components/timeline/base-components/hmr.svelte
+++ b/web/src/lib/components/timeline/base-components/hmr.svelte
@@ -0,0 +1,18 @@
 <script lang="ts">
  import { onMount } from 'svelte';
  import type { UpdatePayload } from 'vite';
  interface Props {
    onAfterUpdate: (payload: UpdatePayload) => void;
  }
  let { onAfterUpdate }: Props = $props();
  onMount(() => {
    const hot = import.meta.hot;
    if (hot) {
      hot.on('vite:afterUpdate', onAfterUpdate);
      return () => hot.off('vite:afterUpdate', onAfterUpdate);
    }
  });
 </script>
--- a/web/src/lib/components/timeline/base-components/scrubber.svelte
+++ b/web/src/lib/components/timeline/base-components/scrubber.svelte
@@ -0,0 +1,593 @@
 <script lang="ts">
  import Icon from '$lib/components/elements/icon.svelte';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { ScrubberMonth } from '$lib/managers/timeline-manager/types';
  import { mobileDevice } from '$lib/stores/mobile-device.svelte';
  import { getTabbable } from '$lib/utils/focus-util';
  import { type ScrubberListener, type TimelineYearMonth } from '$lib/utils/timeline-util';
  import { mdiPlay } from '@mdi/js';
  import { clamp } from 'lodash-es';
  import { onMount } from 'svelte';
  import { fade, fly } from 'svelte/transition';
  interface Props {
    /** Offset from the top of the timeline (e.g., for headers) */
    timelineTopOffset?: number;
    /** Offset from the bottom of the timeline (e.g., for footers) */
    timelineBottomOffset?: number;
    /** Total height of the scrubber component */
    height?: number;
    /** Timeline manager instance that controls the timeline state */
    timelineManager: TimelineManager;
    /** Overall scroll percentage through the entire timeline (0-1), used when no specific month is targeted */
    timelineScrollPercent?: number;
    /** The percentage of scroll through the month that is currently intersecting the top boundary of the viewport */
    viewportTopMonthScrollPercent?: number;
    /** The year/month of the timeline month at the top of the viewport */
    viewportTopMonth?: TimelineYearMonth;
    /** Indicates whether the viewport is currently in the lead-out section (after all months) */
    isInLeadOutSection?: boolean;
    /** Width of the scrubber component in pixels (bindable for parent component margin adjustments) */
    scrubberWidth?: number;
    /** Callback fired when user interacts with the scrubber to navigate */
    onScrub?: ScrubberListener;
    /** Callback fired when keyboard events occur on the scrubber */
    onScrubKeyDown?: (event: KeyboardEvent, element: HTMLElement) => void;
    /** Callback fired when scrubbing starts */
    startScrub?: ScrubberListener;
    /** Callback fired when scrubbing stops */
    stopScrub?: ScrubberListener;
  }
  let {
    timelineTopOffset = 0,
    timelineBottomOffset = 0,
    height = 0,
    timelineManager,
    timelineScrollPercent = 0,
    viewportTopMonthScrollPercent = 0,
    viewportTopMonth = undefined,
    isInLeadOutSection = false,
    onScrub = undefined,
    onScrubKeyDown = undefined,
    startScrub = undefined,
    stopScrub = undefined,
    scrubberWidth = $bindable(),
  }: Props = $props();
  let isHover = $state(false);
  let isDragging = $state(false);
  let isHoverOnPaddingTop = $state(false);
  let isHoverOnPaddingBottom = $state(false);
  let hoverY = $state(0);
  let clientY = 0;
  let windowHeight = $state(0);
  let scrollBar: HTMLElement | undefined = $state();
  const toScrollY = (percent: number) => percent * (height - (PADDING_TOP + PADDING_BOTTOM));
  const toTimelineY = (scrollY: number) => scrollY / (height - (PADDING_TOP + PADDING_BOTTOM));
  const usingMobileDevice = $derived(mobileDevice.pointerCoarse);
  const MOBILE_WIDTH = 20;
  const DESKTOP_WIDTH = 60;
  const HOVER_DATE_HEIGHT = 31.75;
  const PADDING_TOP = $derived(usingMobileDevice ? 25 : HOVER_DATE_HEIGHT);
  const PADDING_BOTTOM = $derived(usingMobileDevice ? 25 : 10);
  const MIN_YEAR_LABEL_DISTANCE = 16;
  const MIN_DOT_DISTANCE = 8;
  const width = $derived.by(() => {
    if (isDragging) {
      return '100vw';
    }
    if (usingMobileDevice) {
      if (timelineManager.scrolling) {
        return MOBILE_WIDTH + 'px';
      }
      return '0px';
    }
    return DESKTOP_WIDTH + 'px';
  });
  $effect(() => {
    scrubberWidth = usingMobileDevice ? MOBILE_WIDTH : DESKTOP_WIDTH;
  });
  const toScrollFromMonthGroupPercentage = (
    scrubberMonth: { year: number; month: number } | undefined,
    scrubberMonthPercent: number,
    scrubOverallPercent: number,
  ) => {
    if (scrubberMonth) {
      let offset = relativeTopOffset;
      let match = false;
      for (const segment of segments) {
        if (segment.month === scrubberMonth.month && segment.year === scrubberMonth.year) {
          offset += scrubberMonthPercent * segment.height;
          match = true;
          break;
        }
        offset += segment.height;
      }
      if (!match) {
        offset += scrubberMonthPercent * relativeBottomOffset;
      }
      return offset;
    } else if (isInLeadOutSection) {
      let offset = relativeTopOffset;
      for (const segment of segments) {
        offset += segment.height;
      }
      offset += scrubOverallPercent * relativeBottomOffset;
      return offset;
    } else {
      return scrubOverallPercent * (height - (PADDING_TOP + PADDING_BOTTOM));
    }
  };
  let scrollY = $derived(
    toScrollFromMonthGroupPercentage(viewportTopMonth, viewportTopMonthScrollPercent, timelineScrollPercent),
  );
  let timelineFullHeight = $derived(timelineManager.scrubberTimelineHeight + timelineTopOffset + timelineBottomOffset);
  let relativeTopOffset = $derived(toScrollY(timelineTopOffset / timelineFullHeight));
  let relativeBottomOffset = $derived(toScrollY(timelineBottomOffset / timelineFullHeight));
  type Segment = {
    count: number;
    height: number;
    dateFormatted: string;
    year: number;
    month: number;
    hasLabel: boolean;
    hasDot: boolean;
  };
  const calculateSegments = (months: ScrubberMonth[]) => {
    let height = 0;
    let dotHeight = 0;
    let segments: Segment[] = [];
    let previousLabeledSegment: Segment | undefined;
    let top = 0;
    for (const [i, scrubMonth] of months.entries()) {
      const scrollBarPercentage = scrubMonth.height / timelineFullHeight;
      const segment = {
        top,
        count: scrubMonth.assetCount,
        height: toScrollY(scrollBarPercentage),
        dateFormatted: scrubMonth.title,
        year: scrubMonth.year,
        month: scrubMonth.month,
        hasLabel: false,
        hasDot: false,
      };
      top += segment.height;
      if (i === 0) {
        segment.hasDot = true;
        segment.hasLabel = true;
        previousLabeledSegment = segment;
      } else {
        if (previousLabeledSegment?.year !== segment.year && height > MIN_YEAR_LABEL_DISTANCE) {
          height = 0;
          segment.hasLabel = true;
          previousLabeledSegment = segment;
        }
        if (i !== 1 && segment.height > 5 && dotHeight > MIN_DOT_DISTANCE) {
          segment.hasDot = true;
          dotHeight = 0;
        }
        height += segment.height;
        dotHeight += segment.height;
      }
      segments.push(segment);
    }
    return segments;
  };
  let activeSegment: HTMLElement | undefined = $state();
  const segments = $derived(calculateSegments(timelineManager.scrubberMonths));
  const hoverLabel = $derived.by(() => {
    if (isHoverOnPaddingTop) {
      return segments.at(0)?.dateFormatted;
    }
    if (isHoverOnPaddingBottom) {
      return segments.at(-1)?.dateFormatted;
    }
    return activeSegment?.dataset.label;
  });
  const segmentDate = $derived.by(() => {
    if (!activeSegment?.dataset.segmentYearMonth) {
      return undefined;
    }
    const [year, month] = activeSegment.dataset.segmentYearMonth.split('-').map(Number);
    return { year, month };
  });
  const scrollSegment = $derived.by(() => {
    const y = scrollY;
    let cur = relativeTopOffset;
    for (const segment of segments) {
      if (y < cur + segment.height) {
        return segment;
      }
      cur += segment.height;
    }
    return null;
  });
  const scrollHoverLabel = $derived(scrollSegment?.dateFormatted || '');
  const findElementBestY = (elements: Element[], y: number, ...ids: string[]) => {
    if (ids.length === 0) {
      return undefined;
    }
    const filtered = elements.filter((element) => {
      if (element instanceof HTMLElement && element.dataset.id) {
        return ids.includes(element.dataset.id);
      }
      return false;
    }) as HTMLElement[];
    const imperfect = [];
    for (const element of filtered) {
      const boundingClientRect = element.getBoundingClientRect();
      if (boundingClientRect.y > y) {
        imperfect.push({
          element,
          boundingClientRect,
        });
        continue;
      }
      if (y <= boundingClientRect.y + boundingClientRect.height) {
        return {
          element,
          boundingClientRect,
        };
      }
    }
    return imperfect.at(0);
  };
  const getActive = (x: number, y: number) => {
    const elements = document.elementsFromPoint(x, y);
    const bestElement = findElementBestY(elements, y, 'time-segment', 'lead-in', 'lead-out');
    if (bestElement) {
      const segment = bestElement.element;
      const boundingClientRect = bestElement.boundingClientRect;
      const sy = boundingClientRect.y;
      const relativeY = y - sy;
      const monthGroupPercentY = relativeY / boundingClientRect.height;
      return {
        isOnPaddingTop: false,
        isOnPaddingBottom: false,
        segment,
        monthGroupPercentY,
      };
    }
    // check if padding
    const bar = findElementBestY(elements, 0, 'scrubber');
    let isOnPaddingTop = false;
    let isOnPaddingBottom = false;
    if (bar) {
      const sr = bar.boundingClientRect;
      if (y < sr.top + PADDING_TOP) {
        isOnPaddingTop = true;
      }
      if (y > sr.bottom - PADDING_BOTTOM - 1) {
        isOnPaddingBottom = true;
      }
    }
    return {
      isOnPaddingTop,
      isOnPaddingBottom,
      segment: undefined,
      monthGroupPercentY: 0,
    };
  };
  const handleMouseEvent = (event: { clientY: number; isDragging?: boolean }) => {
    const wasDragging = isDragging;
    isDragging = event.isDragging ?? isDragging;
    clientY = event.clientY;
    if (!scrollBar) {
      return;
    }
    const rect = scrollBar.getBoundingClientRect()!;
    const lower = 0;
    const upper = rect?.height - (PADDING_TOP + PADDING_BOTTOM);
    hoverY = clamp(clientY - rect?.top - PADDING_TOP, lower, upper);
    const x = rect!.left + rect!.width / 2;
    const { segment, monthGroupPercentY, isOnPaddingTop, isOnPaddingBottom } = getActive(x, clientY);
    activeSegment = segment;
    isHoverOnPaddingTop = isOnPaddingTop;
    isHoverOnPaddingBottom = isOnPaddingBottom;
    const scrollPercent = toTimelineY(hoverY);
    if (wasDragging === false && isDragging) {
      void startScrub?.({
        scrubberMonth: segmentDate!,
        overallScrollPercent: scrollPercent,
        scrubberMonthScrollPercent: monthGroupPercentY,
      });
      void onScrub?.({
        scrubberMonth: segmentDate!,
        overallScrollPercent: scrollPercent,
        scrubberMonthScrollPercent: monthGroupPercentY,
      });
    }
    if (wasDragging && !isDragging) {
      void stopScrub?.({
        scrubberMonth: segmentDate!,
        overallScrollPercent: scrollPercent,
        scrubberMonthScrollPercent: monthGroupPercentY,
      });
      return;
    }
    if (!isDragging) {
      return;
    }
    void onScrub?.({
      scrubberMonth: segmentDate!,
      overallScrollPercent: scrollPercent,
      scrubberMonthScrollPercent: monthGroupPercentY,
    });
  };
  /* eslint-disable tscompat/tscompat */
  const getTouch = (event: TouchEvent) => {
    if (event.touches.length === 1) {
      return event.touches[0];
    }
    return null;
  };
  const onTouchStart = (event: TouchEvent) => {
    const touch = getTouch(event);
    if (!touch) {
      isHover = false;
      return;
    }
    const elements = document.elementsFromPoint(touch.clientX, touch.clientY);
    const isHoverScrollbar =
      findElementBestY(elements, 0, 'scrubber', 'time-label', 'lead-in', 'lead-out') !== undefined;
    isHover = isHoverScrollbar;
    if (isHoverScrollbar) {
      handleMouseEvent({
        clientY: touch.clientY,
        isDragging: true,
      });
    }
  };
  const onTouchEnd = () => {
    if (isHover) {
      isHover = false;
    }
    handleMouseEvent({
      clientY,
      isDragging: false,
    });
  };
  const onTouchMove = (event: TouchEvent) => {
    const touch = getTouch(event);
    if (touch && isDragging) {
      handleMouseEvent({
        clientY: touch.clientY,
      });
    } else {
      isHover = false;
    }
  };
  /* eslint-enable tscompat/tscompat */
  onMount(() => {
    document.addEventListener('touchmove', onTouchMove, { capture: true, passive: true });
    return () => {
      document.removeEventListener('touchmove', onTouchMove, true);
    };
  });
  onMount(() => {
    document.addEventListener('touchstart', onTouchStart, { capture: true, passive: true });
    document.addEventListener('touchend', onTouchEnd, { capture: true, passive: true });
    return () => {
      document.removeEventListener('touchstart', onTouchStart, true);
      document.removeEventListener('touchend', onTouchEnd, true);
    };
  });
  const isTabEvent = (event: KeyboardEvent) => event?.key === 'Tab';
  const isTabForward = (event: KeyboardEvent) => isTabEvent(event) && !event.shiftKey;
  const isTabBackward = (event: KeyboardEvent) => isTabEvent(event) && event.shiftKey;
  const isArrowUp = (event: KeyboardEvent) => event?.key === 'ArrowUp';
  const isArrowDown = (event: KeyboardEvent) => event?.key === 'ArrowDown';
  const handleFocus = (event: KeyboardEvent) => {
    const forward = isTabForward(event);
    const backward = isTabBackward(event);
    if (forward || backward) {
      event.preventDefault();
      const focusable = getTabbable(document.body);
      if (scrollBar) {
        const index = focusable.indexOf(scrollBar);
        if (index !== -1) {
          let next: HTMLElement;
          next = forward
            ? (focusable[(index + 1) % focusable.length] as HTMLElement)
            : (focusable[(index - 1) % focusable.length] as HTMLElement);
          next.focus();
        }
      }
    }
  };
  const handleAccessibility = (event: KeyboardEvent) => {
    if (isTabEvent(event)) {
      handleFocus(event);
      return true;
    }
    if (isArrowUp(event)) {
      let next;
      if (scrollSegment) {
        const idx = segments.indexOf(scrollSegment);
        next = idx === -1 ? segments.at(-2) : segments[idx - 1];
      } else {
        next = segments.at(-2);
      }
      if (next) {
        event.preventDefault();
        void onScrub?.({
          scrubberMonth: { year: next.year, month: next.month },
          overallScrollPercent: -1,
          scrubberMonthScrollPercent: 0,
        });
        return true;
      }
    }
    if (isArrowDown(event) && scrollSegment) {
      const idx = segments.indexOf(scrollSegment);
      if (idx !== -1) {
        const next = segments[idx + 1];
        if (next) {
          event.preventDefault();
          void onScrub?.({
            scrubberMonth: { year: next.year, month: next.month },
            overallScrollPercent: -1,
            scrubberMonthScrollPercent: 0,
          });
          return true;
        }
      }
    }
    return false;
  };
  const keydown = (event: KeyboardEvent) => {
    let handled = handleAccessibility(event);
    if (!handled) {
      onScrubKeyDown?.(event, event.currentTarget as HTMLElement);
    }
  };
 </script>
 <svelte:window
  bind:innerHeight={windowHeight}
  onmousemove={({ clientY }) => (isDragging || isHover) && handleMouseEvent({ clientY })}
  onmousedown={({ clientY }) => isHover && handleMouseEvent({ clientY, isDragging: true })}
  onmouseup={({ clientY }) => handleMouseEvent({ clientY, isDragging: false })}
 />
 <div
  transition:fly={{ x: 50, duration: 250 }}
  tabindex="0"
  role="scrollbar"
  aria-controls="time-label"
  aria-valuetext={hoverLabel}
  aria-valuenow={scrollY + PADDING_TOP}
  aria-valuemax={toScrollY(1)}
  aria-valuemin={toScrollY(0)}
  data-id="scrubber"
  class="absolute end-0 z-1 select-none hover:cursor-row-resize"
  style:padding-top={PADDING_TOP + 'px'}
  style:padding-bottom={PADDING_BOTTOM + 'px'}
  style:width
  style:height={height + 'px'}
  style:background-color={isDragging ? 'transparent' : 'transparent'}
  bind:this={scrollBar}
  onmouseenter={() => (isHover = true)}
  onmouseleave={() => (isHover = false)}
  onkeydown={keydown}
  draggable="false"
 >
  {#if !usingMobileDevice && hoverLabel && (isHover || isDragging)}
    <div
      id="time-label"
      class={[
        { 'border-b-2': isDragging },
        { 'rounded-bl-md': !isDragging },
        'bg-light truncate opacity-85 pointer-events-none absolute end-0 min-w-20 max-w-64 w-fit rounded-ss-md  border-immich-primary py-1 px-1 text-sm font-medium shadow-[0_0_8px_rgba(0,0,0,0.25)] dark:border-immich-dark-primary dark:text-immich-dark-fg z-1',
      ]}
      style:top="{hoverY + 2}px"
    >
      {hoverLabel}
    </div>
  {/if}
  {#if usingMobileDevice && ((timelineManager.scrolling && scrollHoverLabel) || isHover || isDragging)}
    <div
      id="time-label"
      class="rounded-s-full w-[32px] ps-2 text-white bg-immich-primary dark:bg-gray-600 hover:cursor-pointer select-none"
      style:top="{PADDING_TOP + (scrollY - 50 / 2)}px"
      style:height="50px"
      style:right="0"
      style:position="absolute"
      in:fade={{ duration: 200 }}
      out:fade={{ duration: 200 }}
    >
      <Icon path={mdiPlay} size="20" class="-rotate-90 relative top-[9px] -end-[2px]" />
      <Icon path={mdiPlay} size="20" class="rotate-90 relative top-px -end-[2px]" />
      {#if (timelineManager.scrolling && scrollHoverLabel) || isHover || isDragging}
        <p
          transition:fade={{ duration: 200 }}
          style:bottom={50 / 2 - 30 / 2 + 'px'}
          style:right="36px"
          style:width="fit-content"
          class="truncate pointer-events-none absolute text-sm rounded-full w-[32px] py-2 px-4 text-white bg-immich-primary/90 dark:bg-gray-500 hover:cursor-pointer select-none font-semibold"
        >
          {scrollHoverLabel}
        </p>
      {/if}
    </div>
  {/if}
  <!-- Scroll Position Indicator Line -->
  {#if !usingMobileDevice && !isDragging}
    <div class="absolute end-0 h-[2px] w-10 bg-primary" style:top="{scrollY + PADDING_TOP - 2}px">
      {#if timelineManager.scrolling && scrollHoverLabel && !isHover}
        <p
          transition:fade={{ duration: 200 }}
          class="truncate pointer-events-none absolute end-0 bottom-0 min-w-20 max-w-64 w-fit rounded-tl-md border-b-2 border-immich-primary bg-subtle/90 z-1 py-1 px-1 text-sm font-medium shadow-[0_0_8px_rgba(0,0,0,0.25)] dark:border-immich-dark-primary dark:text-immich-dark-fg"
        >
          {scrollHoverLabel}
        </p>
      {/if}
    </div>
  {/if}
  <div
    class="relative"
    style:height={relativeTopOffset + 'px'}
    data-id="lead-in"
    data-segment-year-month={segments.at(0)?.year + '-' + segments.at(0)?.month}
    data-label={segments.at(0)?.dateFormatted}
  >
    {#if relativeTopOffset > 6}
      <div class="absolute end-3 h-[4px] w-[4px] rounded-full bg-gray-300"></div>
    {/if}
  </div>
  <!-- Time Segment -->
  {#each segments as segment (segment.year + '-' + segment.month)}
    <div
      class="relative"
      data-id="time-segment"
      data-segment-year-month={segment.year + '-' + segment.month}
      data-label={segment.dateFormatted}
      style:height={segment.height + 'px'}
    >
      {#if !usingMobileDevice}
        {#if segment.hasLabel}
          <div class="absolute end-5 top-[-16px] text-[12px] dark:text-immich-dark-fg font-immich-mono">
            {segment.year}
          </div>
        {/if}
        {#if segment.hasDot}
          <div class="absolute end-3 bottom-0 h-[4px] w-[4px] rounded-full bg-gray-300"></div>
        {/if}
      {/if}
    </div>
  {/each}
  <div data-id="lead-out" class="relative" style:height={relativeBottomOffset + 'px'}></div>
 </div>
--- a/web/src/lib/components/timeline/base-components/skeleton.svelte
+++ b/web/src/lib/components/timeline/base-components/skeleton.svelte
@@ -0,0 +1,44 @@
 <script lang="ts">
  interface Props {
    height: number;
    title: string;
  }
  let { height = 0, title }: Props = $props();
 </script>
 <div class="overflow-clip" style:height={height + 'px'}>
  <div
    class="flex pt-7 pb-5 h-6 place-items-center text-xs font-medium text-immich-fg bg-light dark:text-immich-dark-fg md:text-sm"
  >
    {title}
  </div>
  <div class="animate-pulse absolute h-full w-full" data-skeleton="true"></div>
 </div>
 <style>
  [data-skeleton] {
    background-image: url('/light_skeleton.png');
    background-repeat: repeat;
    background-size: 235px, 235px;
  }
  @media (max-width: 767px) {
    [data-skeleton] {
      background-size: 100px, 100px;
    }
  }
  :global(.dark) [data-skeleton] {
    background-image: url('/dark_skeleton.png');
  }
  @keyframes delayedVisibility {
    to {
      visibility: visible;
    }
  }
  [data-skeleton] {
    visibility: hidden;
    animation:
      0s linear 0.1s forwards delayedVisibility,
      pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
  }
 </style>
--- a/web/src/lib/components/timeline/base-components/timeline-month.svelte
+++ b/web/src/lib/components/timeline/base-components/timeline-month.svelte
@@ -0,0 +1,181 @@
 <script lang="ts">
  import Thumbnail from '$lib/components/assets/thumbnail/thumbnail.svelte';
  import Icon from '$lib/components/elements/icon.svelte';
  import type { MonthGroup } from '$lib/managers/timeline-manager/month-group.svelte';
  import type { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import { assetSnapshot, assetsSnapshot } from '$lib/managers/timeline-manager/utils.svelte';
  import { uploadAssetsStore } from '$lib/stores/upload';
  import { mdiCheckCircle, mdiCircleOutline } from '@mdi/js';
  import { flip } from 'svelte/animate';
  import { fly, scale } from 'svelte/transition';
  import { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
  import type { Snippet } from 'svelte';
  let { isUploading } = uploadAssetsStore;
  interface Props {
    customThumbnailLayout?: Snippet<[TimelineAsset]>;
    singleSelect: boolean;
    withStacked: boolean;
    showArchiveIcon: boolean;
    monthGroup: MonthGroup;
    timelineManager: TimelineManager;
    onScrollCompensationMonthInDOM: (compensation: { heightDelta?: number; scrollTop?: number }) => void;
    onHover: (dayGroup: DayGroup, asset: TimelineAsset) => void;
    onAssetOpen?: (dayGroup: DayGroup, asset: TimelineAsset) => void;
    onAssetSelect: (dayGroup: DayGroup, asset: TimelineAsset) => void;
    onDayGroupSelect: (dayGroup: DayGroup, assets: TimelineAsset[]) => void;
    // these should be replaced with reactive properties in timeline-manager.svelte.ts
    isDayGroupSelected: (dayGroup: DayGroup) => boolean;
    isAssetSelected: (asset: TimelineAsset) => boolean;
    isAssetSelectionCandidate: (asset: TimelineAsset) => boolean;
    isAssetDisabled: (asset: TimelineAsset) => boolean;
  }
  let {
    customThumbnailLayout,
    singleSelect,
    withStacked,
    showArchiveIcon,
    monthGroup,
    timelineManager,
    onScrollCompensationMonthInDOM,
    onHover,
    onAssetOpen,
    onAssetSelect,
    onDayGroupSelect,
    isDayGroupSelected,
    isAssetSelected,
    isAssetSelectionCandidate,
    isAssetDisabled,
  }: Props = $props();
  let isMouseOverGroup = $state(false);
  let hoveredDayGroup = $state();
  const transitionDuration = $derived.by(() =>
    monthGroup.timelineManager.suspendTransitions && !$isUploading ? 0 : 150,
  );
  const scaleDuration = $derived(transitionDuration === 0 ? 0 : transitionDuration + 100);
  function filterIntersecting<R extends { intersecting: boolean }>(intersectables: R[]) {
    return intersectables.filter((intersectable) => intersectable.intersecting);
  }
  $effect.root(() => {
    if (timelineManager.scrollCompensation.monthGroup === monthGroup) {
      onScrollCompensationMonthInDOM(timelineManager.scrollCompensation);
    }
  });
 </script>
 {#each filterIntersecting(monthGroup.dayGroups) as dayGroup, groupIndex (dayGroup.day)}
  {@const absoluteWidth = dayGroup.left}
  <!-- svelte-ignore a11y_no_static_element_interactions -->
  <section
    class={[
      { 'transition-all': !monthGroup.timelineManager.suspendTransitions },
      !monthGroup.timelineManager.suspendTransitions && `delay-${transitionDuration}`,
    ]}
    data-group
    style:position="absolute"
    style:transform={`translate3d(${absoluteWidth}px,${dayGroup.top}px,0)`}
    onmouseenter={() => {
      isMouseOverGroup = true;
      hoveredDayGroup = dayGroup.groupTitle;
    }}
    onmouseleave={() => {
      isMouseOverGroup = false;
      hoveredDayGroup = null;
    }}
  >
    <!-- Date group title -->
    <div
      class="flex pt-7 pb-5 max-md:pt-5 max-md:pb-3 h-6 place-items-center text-xs font-medium text-immich-fg dark:text-immich-dark-fg md:text-sm"
      style:width={dayGroup.width + 'px'}
    >
      {#if !singleSelect && ((hoveredDayGroup === dayGroup.groupTitle && isMouseOverGroup) || isDayGroupSelected(dayGroup))}
        <div
          transition:fly={{ x: -24, duration: 200, opacity: 0.5 }}
          class="inline-block pe-2 hover:cursor-pointer"
          onclick={() => onDayGroupSelect(dayGroup, assetsSnapshot(dayGroup.getAssets()))}
          onkeydown={() => onDayGroupSelect(dayGroup, assetsSnapshot(dayGroup.getAssets()))}
        >
          {#if isDayGroupSelected(dayGroup)}
            <Icon path={mdiCheckCircle} size="24" class="text-primary" />
          {:else}
            <Icon path={mdiCircleOutline} size="24" color="#757575" />
          {/if}
        </div>
      {/if}
      <span class="w-full truncate first-letter:capitalize" title={dayGroup.groupTitleFull}>
        {dayGroup.groupTitle}
      </span>
    </div>
    <!-- Image grid -->
    <div
      data-image-grid
      class="relative overflow-clip"
      style:height={dayGroup.height + 'px'}
      style:width={dayGroup.width + 'px'}
    >
      {#each filterIntersecting(dayGroup.viewerAssets) as viewerAsset (viewerAsset.id)}
        {@const position = viewerAsset.position!}
        {@const asset = viewerAsset.asset!}
        <!-- note: don't remove data-asset-id - its used by web e2e tests -->
        <div
          data-asset-id={asset.id}
          class="absolute"
          style:top={position.top + 'px'}
          style:left={position.left + 'px'}
          style:width={position.width + 'px'}
          style:height={position.height + 'px'}
          out:scale|global={{ start: 0.1, duration: scaleDuration }}
          animate:flip={{ duration: transitionDuration }}
        >
          <Thumbnail
            showStackedIcon={withStacked}
            {showArchiveIcon}
            {asset}
            {groupIndex}
            onClick={() => onAssetOpen?.(dayGroup, assetSnapshot(asset))}
            onSelect={() => onAssetSelect(dayGroup, assetSnapshot(asset))}
            onMouseEvent={() => onHover(dayGroup, assetSnapshot(asset))}
            selected={isAssetSelected(asset)}
            selectionCandidate={isAssetSelectionCandidate(asset)}
            disabled={isAssetDisabled(asset)}
            thumbnailWidth={position.width}
            thumbnailHeight={position.height}
          />
          {#if customThumbnailLayout}
            {@render customThumbnailLayout(asset)}
          {/if}
        </div>
      {/each}
    </div>
  </section>
 {/each}
 <style>
  section {
    contain: layout paint style;
  }
  [data-image-grid] {
    user-select: none;
  }
 </style>
--- a/web/src/lib/components/timeline/internal-components/selectable-timeline-month.svelte
+++ b/web/src/lib/components/timeline/internal-components/selectable-timeline-month.svelte
@@ -0,0 +1,276 @@
 <script lang="ts">
  import type { MonthGroup } from '$lib/managers/timeline-manager/month-group.svelte';
  import type { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
  import { isSelectingAllAssets } from '$lib/stores/assets-store.svelte';
  import { navigate } from '$lib/utils/navigation';
  import TimelineMonth from '$lib/components/timeline/base-components/timeline-month.svelte';
  import { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
  import { assetsSnapshot } from '$lib/managers/timeline-manager/utils.svelte';
  import { searchStore } from '$lib/stores/search.svelte';
  import type { Snippet } from 'svelte';
  interface Props {
    customThumbnailLayout?: Snippet<[TimelineAsset]>;
    isSelectionMode: boolean;
    singleSelect: boolean;
    withStacked: boolean;
    showArchiveIcon: boolean;
    monthGroup: MonthGroup;
    timelineManager: TimelineManager;
    assetInteraction: AssetInteraction;
    onAssetOpen?: (dayGroup: DayGroup, asset: TimelineAsset, defaultAssetOpen: () => void) => void;
    onSelect?: (isSingleSelect: boolean, asset: TimelineAsset) => void;
    onScrollCompensationMonthInDOM: (compensation: { heightDelta?: number; scrollTop?: number }) => void;
  }
  let {
    customThumbnailLayout,
    isSelectionMode,
    singleSelect,
    withStacked,
    showArchiveIcon,
    monthGroup = $bindable(),
    assetInteraction,
    timelineManager,
    onAssetOpen,
    onSelect,
    onScrollCompensationMonthInDOM,
  }: Props = $props();
  let lastAssetMouseEvent: TimelineAsset | null = $state(null);
  let shiftKeyIsDown = $state(false);
  let isEmpty = $derived(timelineManager.isInitialized && timelineManager.months.length === 0);
  $effect(() => {
    if (!lastAssetMouseEvent || !lastAssetMouseEvent) {
      assetInteraction.clearAssetSelectionCandidates();
    }
    if (shiftKeyIsDown && lastAssetMouseEvent) {
      void selectAssetCandidates(lastAssetMouseEvent);
    }
    if (isEmpty) {
      assetInteraction.clearMultiselect();
    }
  });
  const defaultAssetOpen = (dayGroup: DayGroup, asset: TimelineAsset) => {
    if (isSelectionMode || assetInteraction.selectionActive) {
      handleAssetSelect(dayGroup, asset);
      return;
    }
    void navigate({ targetRoute: 'current', assetId: asset.id });
  };
  const handleOnAssetOpen = (dayGroup: DayGroup, asset: TimelineAsset) => {
    if (onAssetOpen) {
      onAssetOpen(dayGroup, asset, () => defaultAssetOpen(dayGroup, asset));
      return;
    }
    defaultAssetOpen(dayGroup, asset);
  };
  // called when clicking asset with shift key pressed or with mouse
  const handleAssetSelect = (dayGroup: DayGroup, asset: TimelineAsset) => {
    void onSelectAssets(asset);
    const assetsInDayGroup = dayGroup.getAssets();
    const groupTitle = dayGroup.groupTitle;
    // Check if all assets are selected in a group to toggle the group selection's icon
    let selectedAssetsInGroupCount = assetsInDayGroup.filter((asset) =>
      assetInteraction.hasSelectedAsset(asset.id),
    ).length;
    // if all assets are selected in a group, add the group to selected group
    if (selectedAssetsInGroupCount == assetsInDayGroup.length) {
      assetInteraction.addGroupToMultiselectGroup(groupTitle);
    } else {
      assetInteraction.removeGroupFromMultiselectGroup(groupTitle);
    }
    if (timelineManager.assetCount == assetInteraction.selectedAssets.length) {
      isSelectingAllAssets.set(true);
    } else {
      isSelectingAllAssets.set(false);
    }
  };
  const handleSelectAsset = (asset: TimelineAsset) => {
    if (!timelineManager.albumAssets.has(asset.id)) {
      assetInteraction.selectAsset(asset);
    }
  };
  const onKeyDown = (event: KeyboardEvent) => {
    if (searchStore.isSearchEnabled) {
      return;
    }
    if (event.key === 'Shift') {
      event.preventDefault();
      shiftKeyIsDown = true;
    }
  };
  const onKeyUp = (event: KeyboardEvent) => {
    if (searchStore.isSearchEnabled) {
      return;
    }
    if (event.key === 'Shift') {
      event.preventDefault();
      shiftKeyIsDown = false;
    }
  };
  const handleOnHover = (dayGroup: DayGroup, asset: TimelineAsset) => {
    if (assetInteraction.selectionActive) {
      void selectAssetCandidates(asset);
    }
    lastAssetMouseEvent = asset;
  };
  const handleDayGroupSelect = (dayGroup: DayGroup, assets: TimelineAsset[]) => {
    const group = dayGroup.groupTitle;
    if (assetInteraction.selectedGroup.has(group)) {
      assetInteraction.removeGroupFromMultiselectGroup(group);
      for (const asset of assets) {
        assetInteraction.removeAssetFromMultiselectGroup(asset.id);
      }
    } else {
      assetInteraction.addGroupToMultiselectGroup(group);
      for (const asset of assets) {
        handleSelectAsset(asset);
      }
    }
    if (timelineManager.assetCount == assetInteraction.selectedAssets.length) {
      isSelectingAllAssets.set(true);
    } else {
      isSelectingAllAssets.set(false);
    }
  };
  const onSelectAssets = async (asset: TimelineAsset) => {
    if (!asset) {
      return;
    }
    onSelect?.(singleSelect, asset);
    if (singleSelect) {
      // onScrollToTop();
      return;
    }
    const rangeSelection = assetInteraction.assetSelectionCandidates.length > 0;
    const deselect = assetInteraction.hasSelectedAsset(asset.id);
    // Select/deselect already loaded assets
    if (deselect) {
      for (const candidate of assetInteraction.assetSelectionCandidates) {
        assetInteraction.removeAssetFromMultiselectGroup(candidate.id);
      }
      assetInteraction.removeAssetFromMultiselectGroup(asset.id);
    } else {
      for (const candidate of assetInteraction.assetSelectionCandidates) {
        handleSelectAsset(candidate);
      }
      handleSelectAsset(asset);
    }
    assetInteraction.clearAssetSelectionCandidates();
    if (assetInteraction.assetSelectionStart && rangeSelection) {
      let startBucket = timelineManager.getMonthGroupByAssetId(assetInteraction.assetSelectionStart.id);
      let endBucket = timelineManager.getMonthGroupByAssetId(asset.id);
      if (startBucket === null || endBucket === null) {
        return;
      }
      // Select/deselect assets in range (start,end)
      let started = false;
      for (const monthGroup of timelineManager.months) {
        if (monthGroup === endBucket) {
          break;
        }
        if (started) {
          await timelineManager.loadMonthGroup(monthGroup.yearMonth);
          for (const asset of monthGroup.assetsIterator()) {
            if (deselect) {
              assetInteraction.removeAssetFromMultiselectGroup(asset.id);
            } else {
              handleSelectAsset(asset);
            }
          }
        }
        if (monthGroup === startBucket) {
          started = true;
        }
      }
      // Update date group selection in range [start,end]
      started = false;
      for (const monthGroup of timelineManager.months) {
        if (monthGroup === startBucket) {
          started = true;
        }
        if (started) {
          // Split month group into day groups and check each group
          for (const dayGroup of monthGroup.dayGroups) {
            const dayGroupTitle = dayGroup.groupTitle;
            if (dayGroup.getAssets().every((a) => assetInteraction.hasSelectedAsset(a.id))) {
              assetInteraction.addGroupToMultiselectGroup(dayGroupTitle);
            } else {
              assetInteraction.removeGroupFromMultiselectGroup(dayGroupTitle);
            }
          }
        }
        if (monthGroup === endBucket) {
          break;
        }
      }
    }
    assetInteraction.setAssetSelectionStart(deselect ? null : asset);
  };
  const selectAssetCandidates = async (endAsset: TimelineAsset) => {
    if (!shiftKeyIsDown) {
      return;
    }
    const startAsset = assetInteraction.assetSelectionStart;
    if (!startAsset) {
      return;
    }
    const assets = assetsSnapshot(await timelineManager.retrieveRange(startAsset, endAsset));
    assetInteraction.setAssetSelectionCandidates(assets);
  };
 </script>
 <svelte:document onkeydown={onKeyDown} onkeyup={onKeyUp} />
 <TimelineMonth
  {customThumbnailLayout}
  {singleSelect}
  {withStacked}
  {showArchiveIcon}
  {monthGroup}
  {timelineManager}
  {onScrollCompensationMonthInDOM}
  onHover={handleOnHover}
  onAssetOpen={handleOnAssetOpen}
  onAssetSelect={handleAssetSelect}
  onDayGroupSelect={handleDayGroupSelect}
  isDayGroupSelected={(dayGroup: DayGroup) => assetInteraction.selectedGroup.has(dayGroup.groupTitle)}
  isAssetSelected={(asset) => assetInteraction.hasSelectedAsset(asset.id) || timelineManager.albumAssets.has(asset.id)}
  isAssetSelectionCandidate={(asset) => assetInteraction.hasSelectionCandidate(asset.id)}
  isAssetDisabled={(asset) => timelineManager.albumAssets.has(asset.id)}
 />
--- a/web/src/lib/components/timeline/internal-components/timeline-asset-viewer.svelte
+++ b/web/src/lib/components/timeline/internal-components/timeline-asset-viewer.svelte
@@ -0,0 +1,177 @@
 <script lang="ts">
  import type { Action } from '$lib/components/asset-viewer/actions/action';
  import { AssetAction } from '$lib/constants';
  import { authManager } from '$lib/managers/auth-manager.svelte';
  import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import { updateStackedAssetInTimeline, updateUnstackedAssetInTimeline } from '$lib/utils/actions';
  import { navigate } from '$lib/utils/navigation';
  import { toTimelineAsset } from '$lib/utils/timeline-util';
  import { getAssetInfo, type AlbumResponseDto, type PersonResponseDto } from '@immich/sdk';
  let { asset: viewingAsset, gridScrollTarget, mutex, preloadAssets } = assetViewingStore;
  interface Props {
    timelineManager: TimelineManager;
    showSkeleton: boolean;
    withStacked?: boolean;
    isShared?: boolean;
    album?: AlbumResponseDto | null;
    person?: PersonResponseDto | null;
    removeAction?:
      | AssetAction.UNARCHIVE
      | AssetAction.ARCHIVE
      | AssetAction.FAVORITE
      | AssetAction.UNFAVORITE
      | AssetAction.SET_VISIBILITY_TIMELINE
      | null;
  }
  let {
    timelineManager,
    showSkeleton = $bindable(false),
    removeAction,
    withStacked = false,
    isShared = false,
    album = null,
    person = null,
  }: Props = $props();
  const handlePrevious = async () => {
    const release = await mutex.acquire();
    const laterAsset = await timelineManager.getLaterAsset($viewingAsset);
    if (laterAsset) {
      const preloadAsset = await timelineManager.getLaterAsset(laterAsset);
      const asset = await getAssetInfo({ ...authManager.params, id: laterAsset.id });
      assetViewingStore.setAsset(asset, preloadAsset ? [preloadAsset] : []);
      await navigate({ targetRoute: 'current', assetId: laterAsset.id });
    }
    release();
    return !!laterAsset;
  };
  const handleNext = async () => {
    const release = await mutex.acquire();
    const earlierAsset = await timelineManager.getEarlierAsset($viewingAsset);
    if (earlierAsset) {
      const preloadAsset = await timelineManager.getEarlierAsset(earlierAsset);
      const asset = await getAssetInfo({ ...authManager.params, id: earlierAsset.id });
      assetViewingStore.setAsset(asset, preloadAsset ? [preloadAsset] : []);
      await navigate({ targetRoute: 'current', assetId: earlierAsset.id });
    }
    release();
    return !!earlierAsset;
  };
  const handleRandom = async () => {
    const randomAsset = await timelineManager.getRandomAsset();
    if (randomAsset) {
      const asset = await getAssetInfo({ ...authManager.params, id: randomAsset.id });
      assetViewingStore.setAsset(asset);
      await navigate({ targetRoute: 'current', assetId: randomAsset.id });
      return asset;
    }
  };
  const handleClose = async (asset: { id: string }) => {
    assetViewingStore.showAssetViewer(false);
    showSkeleton = true;
    $gridScrollTarget = { at: asset.id };
    await navigate({ targetRoute: 'current', assetId: null, assetGridRouteSearchParams: $gridScrollTarget });
  };
  const handlePreAction = async (action: Action) => {
    switch (action.type) {
      case removeAction:
      case AssetAction.TRASH:
      case AssetAction.RESTORE:
      case AssetAction.DELETE:
      case AssetAction.ARCHIVE:
      case AssetAction.SET_VISIBILITY_LOCKED:
      case AssetAction.SET_VISIBILITY_TIMELINE: {
        // find the next asset to show or close the viewer
        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
        (await handleNext()) || (await handlePrevious()) || (await handleClose(action.asset));
        // delete after find the next one
        timelineManager.removeAssets([action.asset.id]);
        break;
      }
    }
  };
  const handleAction = (action: Action) => {
    switch (action.type) {
      case AssetAction.ARCHIVE:
      case AssetAction.UNARCHIVE:
      case AssetAction.FAVORITE:
      case AssetAction.UNFAVORITE: {
        timelineManager.updateAssets([action.asset]);
        break;
      }
      case AssetAction.ADD: {
        timelineManager.addAssets([action.asset]);
        break;
      }
      case AssetAction.UNSTACK: {
        updateUnstackedAssetInTimeline(timelineManager, action.assets);
        break;
      }
      case AssetAction.REMOVE_ASSET_FROM_STACK: {
        timelineManager.addAssets([toTimelineAsset(action.asset)]);
        if (action.stack) {
          //Have to unstack then restack assets in timeline in order to update the stack count in the timeline.
          updateUnstackedAssetInTimeline(
            timelineManager,
            action.stack.assets.map((asset) => toTimelineAsset(asset)),
          );
          updateStackedAssetInTimeline(timelineManager, {
            stack: action.stack,
            toDeleteIds: action.stack.assets
              .filter((asset) => asset.id !== action.stack?.primaryAssetId)
              .map((asset) => asset.id),
          });
        }
        break;
      }
      case AssetAction.SET_STACK_PRIMARY_ASSET: {
        //Have to unstack then restack assets in timeline in order for the currently removed new primary asset to be made visible.
        updateUnstackedAssetInTimeline(
          timelineManager,
          action.stack.assets.map((asset) => toTimelineAsset(asset)),
        );
        updateStackedAssetInTimeline(timelineManager, {
          stack: action.stack,
          toDeleteIds: action.stack.assets
            .filter((asset) => asset.id !== action.stack.primaryAssetId)
            .map((asset) => asset.id),
        });
        break;
      }
    }
  };
 </script>
 {#await import('../../asset-viewer/asset-viewer.svelte') then { default: AssetViewer }}
  <AssetViewer
    {withStacked}
    asset={$viewingAsset}
    preloadAssets={$preloadAssets}
    {isShared}
    {album}
    {person}
    preAction={handlePreAction}
    onAction={handleAction}
    onPrevious={handlePrevious}
    onNext={handleNext}
    onRandom={handleRandom}
    onClose={handleClose}
  />
 {/await}
--- a/web/src/lib/components/timeline/timeline.svelte
+++ b/web/src/lib/components/timeline/timeline.svelte
@@ -0,0 +1,102 @@
 <script lang="ts">
  import Portal from '$lib/components/shared-components/portal/portal.svelte';
  import TimelineKeyboardActions from '$lib/components/timeline/actions/timeline-keyboard-actions.svelte';
  import BaseTimeline from '$lib/components/timeline/base-components/base-timeline.svelte';
  import TimelineAssetViewer from '$lib/components/timeline/internal-components/timeline-asset-viewer.svelte';
  import type { AssetAction } from '$lib/constants';
  import type { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
  import type { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
  import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
  import { assetViewingStore } from '$lib/stores/asset-viewing.store';
  import type { AlbumResponseDto, PersonResponseDto } from '@immich/sdk';
  import type { Snippet } from 'svelte';
  let { isViewing: showAssetViewer } = assetViewingStore;
  interface Props {
    customThumbnailLayout?: Snippet<[TimelineAsset]>;
    isSelectionMode?: boolean;
    singleSelect?: boolean;
    /** `true` if this asset grid is responds to navigation events; if `true`, then look at the
     `AssetViewingStore.gridScrollTarget` and load and scroll to the asset specified, and
     additionally, update the page location/url with the asset as the asset-grid is scrolled */
    enableRouting: boolean;
    timelineManager: TimelineManager;
    assetInteraction: AssetInteraction;
    removeAction?:
      | AssetAction.UNARCHIVE
      | AssetAction.ARCHIVE
      | AssetAction.FAVORITE
      | AssetAction.UNFAVORITE
      | AssetAction.SET_VISIBILITY_TIMELINE
      | null;
    withStacked?: boolean;
    showArchiveIcon?: boolean;
    isShared?: boolean;
    album?: AlbumResponseDto | null;
    person?: PersonResponseDto | null;
    isShowDeleteConfirmation?: boolean;
    onAssetOpen?: (dayGroup: DayGroup, asset: TimelineAsset, defaultAssetOpen: () => void) => void;
    onSelect?: (asset: TimelineAsset) => void;
    onEscape?: () => void;
    children?: Snippet;
    empty?: Snippet;
  }
  let {
    customThumbnailLayout,
    isSelectionMode = false,
    singleSelect = false,
    enableRouting,
    timelineManager = $bindable(),
    assetInteraction,
    removeAction,
    withStacked = false,
    showArchiveIcon = false,
    isShared = false,
    album = null,
    person = null,
    isShowDeleteConfirmation = $bindable(false),
    onAssetOpen,
    onSelect = () => {},
    onEscape = () => {},
    children,
    empty,
  }: Props = $props();
  let viewer: BaseTimeline | undefined = $state();
  let showSkeleton: boolean = $state(true);
 </script>
 <BaseTimeline
  bind:this={viewer}
  {customThumbnailLayout}
  {isSelectionMode}
  {singleSelect}
  {enableRouting}
  {timelineManager}
  {assetInteraction}
  {withStacked}
  {showArchiveIcon}
  {isShowDeleteConfirmation}
  {showSkeleton}
  {onAssetOpen}
  {onSelect}
  {children}
  {empty}
 />
 <TimelineKeyboardActions
  scrollToAsset={(asset) => viewer?.scrollToAsset(asset) ?? false}
  {timelineManager}
  {assetInteraction}
  bind:isShowDeleteConfirmation
  {onEscape}
 />
 <Portal target="body">
  {#if $showAssetViewer}
    <TimelineAssetViewer bind:showSkeleton {timelineManager} {removeAction} {withStacked} {isShared} {album} {person} />
  {/if}
 </Portal>
--- a/web/src/lib/managers/timeline-manager/day-group.svelte.ts
+++ b/web/src/lib/managers/timeline-manager/day-group.svelte.ts
@@ -13,6 +13,7 @@ export class DayGroup {
  readonly monthGroup: MonthGroup;
  readonly index: number;
  readonly groupTitle: string;
  readonly groupTitleFull: string;
  readonly day: number;
  viewerAssets: ViewerAsset[] = $state([]);
@@ -26,11 +27,12 @@ export class DayGroup {
  #col = $state(0);
  #deferredLayout = false;
-  constructor(monthGroup: MonthGroup, index: number, day: number, groupTitle: string) {
+  constructor(monthGroup: MonthGroup, index: number, day: number, groupTitle: string, groupTitleFull: string) {
    this.index = index;
    this.monthGroup = monthGroup;
    this.day = day;
    this.groupTitle = groupTitle;
    this.groupTitleFull = groupTitleFull;
  }
  get top() {
--- a/web/src/lib/managers/timeline-manager/internal/search-support.svelte.ts
+++ b/web/src/lib/managers/timeline-manager/internal/search-support.svelte.ts
@@ -143,3 +143,24 @@ export function findMonthGroupForDate(timelineManager: TimelineManager, targetYe
    }
  }
 }
 export function findClosestGroupForDate(timelineManager: TimelineManager, targetYearMonth: TimelineYearMonth) {
  let closestMonth: MonthGroup | undefined;
  let minDifference = Number.MAX_SAFE_INTEGER;
  for (const month of timelineManager.months) {
    const { year, month: monthNum } = month.yearMonth;
    // Calculate the absolute difference in months
    const yearDiff = Math.abs(year - targetYearMonth.year);
    const monthDiff = Math.abs(monthNum - targetYearMonth.month);
    const totalDiff = yearDiff * 12 + monthDiff;
    if (totalDiff < minDifference) {
      minDifference = totalDiff;
      closestMonth = month;
    }
  }
  return closestMonth;
 }
--- a/web/src/lib/managers/timeline-manager/month-group.svelte.ts
+++ b/web/src/lib/managers/timeline-manager/month-group.svelte.ts
@@ -4,6 +4,7 @@ import { CancellableTask } from '$lib/utils/cancellable-task';
 import { handleError } from '$lib/utils/handle-error';
 import {
  formatGroupTitle,
  formatGroupTitleFull,
  formatMonthGroupTitle,
  fromTimelinePlainDate,
  fromTimelinePlainDateTime,
@@ -222,7 +223,8 @@ export class MonthGroup {
      addContext.setDayGroup(dayGroup, localDateTime);
    } else {
      const groupTitle = formatGroupTitle(fromTimelinePlainDate(localDateTime));
-      dayGroup = new DayGroup(this, this.dayGroups.length, localDateTime.day, groupTitle);
+      const groupTitleFull = formatGroupTitleFull(fromTimelinePlainDate(localDateTime));
      dayGroup = new DayGroup(this, this.dayGroups.length, localDateTime.day, groupTitle, groupTitleFull);
      this.dayGroups.push(dayGroup);
      addContext.setDayGroup(dayGroup, localDateTime);
      addContext.newDayGroups.add(dayGroup);
--- a/web/src/lib/managers/timeline-manager/timeline-manager.svelte.ts
+++ b/web/src/lib/managers/timeline-manager/timeline-manager.svelte.ts
@@ -41,6 +41,7 @@ export class TimelineManager {
  isInitialized = $state(false);
  months: MonthGroup[] = $state([]);
  topSectionHeight = $state(0);
  bottomSectionHeight = $state(60);
  timelineHeight = $derived(this.months.reduce((accumulator, b) => accumulator + b.height, 0) + this.topSectionHeight);
  assetCount = $derived(this.months.reduce((accumulator, b) => accumulator + b.assetsCount, 0));
@@ -552,4 +553,13 @@ export class TimelineManager {
  getAssetOrder() {
    return this.#options.order ?? AssetOrder.Desc;
  }
  getMaxScrollPercent() {
    const totalHeight = this.timelineHeight + this.bottomSectionHeight + this.topSectionHeight;
    return (totalHeight - this.viewportHeight) / totalHeight;
  }
  getMaxScroll() {
    return this.topSectionHeight + this.bottomSectionHeight + (this.timelineHeight - this.viewportHeight);
  }
 }
--- a/web/src/lib/utils/timeline-util.ts
+++ b/web/src/lib/utils/timeline-util.ts
@@ -23,11 +23,12 @@ export type TimelineDateTime = TimelineDate & {
  millisecond: number;
 };
-export type ScrubberListener = (
+export type ScrubberListener = (scrubberData: {
-  scrubberMonth: { year: number; month: number },
+  scrubberMonth: { year: number; month: number };
-  overallScrollPercent: number,
+  overallScrollPercent: number;
-  scrubberMonthScrollPercent: number,
+  scrubberMonthScrollPercent: number;
-) => void | Promise<void>;
+  scrollToFunction?: (top: number) => void;
 }) => void | Promise<void>;
 // used for AssetResponseDto.dateTimeOriginal, amongst others
 export const fromISODateTime = (isoDateTime: string, timeZone: string): DateTime<true> =>
@@ -151,6 +152,14 @@ export function formatGroupTitle(_date: DateTime): string {
  return getDateLocaleString(date, { locale: get(locale) });
 }
 export const formatGroupTitleFull = (_date: DateTime): string => {
  if (!_date.isValid) {
    return _date.toString();
  }
  const date = _date as DateTime<true>;
  return getDateLocaleString(date);
 };
 export const getDateLocaleString = (date: DateTime, opts?: LocaleOptions): string =>
  date.toLocaleString(DateTime.DATE_MED_WITH_WEEKDAY, opts);
@@ -234,3 +243,79 @@ export function setDifference<T>(setA: Set<T>, setB: Set<T>): SvelteSet<T> {
  }
  return result;
 }
 export interface MonthGroupForSearch {
  yearMonth: TimelineYearMonth;
  top: number;
  height: number;
 }
 export interface BinarySearchResult {
  month: TimelineYearMonth;
  monthScrollPercent: number;
 }
 export function findMonthAtScrollPosition(
  months: MonthGroupForSearch[],
  scrollPosition: number,
  maxScrollPercent: number,
 ): BinarySearchResult | null {
  const SUBPIXEL_TOLERANCE = -1; // Tolerance for scroll position checks
  const NEAR_END_THRESHOLD = 0.9999; // Threshold for detecting near-end of month
  if (months.length === 0) {
    return null;
  }
  // Check if we're before the first month
  const firstMonthTop = months[0].top * maxScrollPercent;
  if (scrollPosition < firstMonthTop - SUBPIXEL_TOLERANCE) {
    return null;
  }
  // Check if we're after the last month
  const lastMonth = months.at(-1)!;
  const lastMonthBottom = (lastMonth.top + lastMonth.height) * maxScrollPercent;
  if (scrollPosition >= lastMonthBottom - SUBPIXEL_TOLERANCE) {
    return null;
  }
  // Binary search to find the month containing the scroll position
  let left = 0;
  let right = months.length - 1;
  while (left <= right) {
    const mid = Math.floor((left + right) / 2);
    const month = months[mid];
    const monthTop = month.top * maxScrollPercent;
    const monthBottom = monthTop + month.height * maxScrollPercent;
    if (scrollPosition >= monthTop - SUBPIXEL_TOLERANCE && scrollPosition < monthBottom - SUBPIXEL_TOLERANCE) {
      // Found the month containing the scroll position
      const distanceIntoMonth = scrollPosition - monthTop;
      const monthScrollPercent = Math.max(0, distanceIntoMonth / (month.height * maxScrollPercent));
      // Handle month boundary edge case
      if (monthScrollPercent > NEAR_END_THRESHOLD && mid < months.length - 1) {
        return {
          month: months[mid + 1].yearMonth,
          monthScrollPercent: 0,
        };
      }
      return {
        month: month.yearMonth,
        monthScrollPercent,
      };
    }
    if (scrollPosition < monthTop) {
      right = mid - 1;
    } else {
      left = mid + 1;
    }
  }
  // Shouldn't reach here, but return null if we do
  return null;
 }