feat: timeline e2e tests (#23895)

* feat: timeline e2e tests * Fix flakiness, mock all apis, allow parallel tests * Upload playwright reports * wrong report path * Add CI=true, disable flaky/failing tests * Re-enable tests, fix worker thread config * fix maintance e2e test * increase retries
2025-12-29 17:25:00 +03:00 · 2025-11-18 22:08:55 -05:00
parent 2a281e7906
commit d9fd52ea18
18 changed files with 2919 additions and 18 deletions
--- a/e2e/src/generators/timeline.ts
+++ b/e2e/src/generators/timeline.ts
@@ -0,0 +1,37 @@
+export { generateTimelineData } from './timeline/model-objects';
+
+export { createDefaultTimelineConfig, validateTimelineConfig } from './timeline/timeline-config';
+
+export type {
+  MockAlbum,
+  MonthSpec,
+  SerializedTimelineData,
+  MockTimelineAsset as TimelineAssetConfig,
+  TimelineConfig,
+  MockTimelineData as TimelineData,
+} from './timeline/timeline-config';
+
+export {
+  getAlbum,
+  getAsset,
+  getTimeBucket,
+  getTimeBuckets,
+  toAssetResponseDto,
+  toColumnarFormat,
+} from './timeline/rest-response';
+
+export type { Changes } from './timeline/rest-response';
+
+export { randomImage, randomImageFromString, randomPreview, randomThumbnail } from './timeline/images';
+
+export {
+  SeededRandom,
+  getMockAsset,
+  parseTimeBucketKey,
+  selectRandom,
+  selectRandomDays,
+  selectRandomMultiple,
+} from './timeline/utils';
+
+export { ASSET_DISTRIBUTION, DAY_DISTRIBUTION } from './timeline/distribution-patterns';
+export type { DayPattern, MonthDistribution } from './timeline/distribution-patterns';
--- a/e2e/src/generators/timeline/distribution-patterns.ts
+++ b/e2e/src/generators/timeline/distribution-patterns.ts
@@ -0,0 +1,183 @@
+import { generateConsecutiveDays, generateDayAssets } from 'src/generators/timeline/model-objects';
+import { SeededRandom, selectRandomDays } from 'src/generators/timeline/utils';
+import type { MockTimelineAsset } from './timeline-config';
+import { GENERATION_CONSTANTS } from './timeline-config';
+
+type AssetDistributionStrategy = (rng: SeededRandom) => number;
+
+type DayDistributionStrategy = (
+  year: number,
+  month: number,
+  daysInMonth: number,
+  totalAssets: number,
+  ownerId: string,
+  rng: SeededRandom,
+) => MockTimelineAsset[];
+
+/**
+ * Strategies for determining total asset count per month
+ */
+export const ASSET_DISTRIBUTION: Record<MonthDistribution, AssetDistributionStrategy | null> = {
+  empty: null, // Special case - handled separately
+  sparse: (rng) => rng.nextInt(3, 9), // 3-8 assets
+  medium: (rng) => rng.nextInt(15, 31), // 15-30 assets
+  dense: (rng) => rng.nextInt(50, 81), // 50-80 assets
+  'very-dense': (rng) => rng.nextInt(80, 151), // 80-150 assets
+};
+
+/**
+ * Strategies for distributing assets across days within a month
+ */
+export const DAY_DISTRIBUTION: Record<DayPattern, DayDistributionStrategy> = {
+  'single-day': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // All assets on one day in the middle of the month
+    const day = Math.floor(daysInMonth / 2);
+    return generateDayAssets(year, month, day, totalAssets, ownerId, rng);
+  },
+
+  'consecutive-large': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // 3-5 consecutive days with evenly distributed assets
+    const numDays = Math.min(5, Math.floor(totalAssets / 15));
+    const startDay = rng.nextInt(1, daysInMonth - numDays + 2);
+    return generateConsecutiveDays(year, month, startDay, numDays, totalAssets, ownerId, rng);
+  },
+
+  'consecutive-small': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // Multiple consecutive days with 1-3 assets each (side-by-side layout)
+    const assets: MockTimelineAsset[] = [];
+    const numDays = Math.min(totalAssets, Math.floor(daysInMonth / 2));
+    const startDay = rng.nextInt(1, daysInMonth - numDays + 2);
+    let assetIndex = 0;
+
+    for (let i = 0; i < numDays && assetIndex < totalAssets; i++) {
+      const dayAssets = Math.min(3, rng.nextInt(1, 4));
+      const actualAssets = Math.min(dayAssets, totalAssets - assetIndex);
+      // Create a new RNG for this day
+      const dayRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, startDay + i, actualAssets, ownerId, dayRng));
+      assetIndex += actualAssets;
+    }
+    return assets;
+  },
+
+  alternating: (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // Alternate between large (15-25) and small (1-3) days
+    const assets: MockTimelineAsset[] = [];
+    let day = 1;
+    let isLarge = true;
+    let assetIndex = 0;
+
+    while (assetIndex < totalAssets && day <= daysInMonth) {
+      const dayAssets = isLarge ? Math.min(25, rng.nextInt(15, 26)) : rng.nextInt(1, 4);
+
+      const actualAssets = Math.min(dayAssets, totalAssets - assetIndex);
+      // Create a new RNG for this day
+      const dayRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, day, actualAssets, ownerId, dayRng));
+      assetIndex += actualAssets;
+
+      day += isLarge ? 1 : 1; // Could add gaps here
+      isLarge = !isLarge;
+    }
+    return assets;
+  },
+
+  'sparse-scattered': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // Spread assets across random days with gaps
+    const assets: MockTimelineAsset[] = [];
+    const numDays = Math.min(totalAssets, Math.floor(daysInMonth * GENERATION_CONSTANTS.SPARSE_DAY_COVERAGE));
+    const daysWithPhotos = selectRandomDays(daysInMonth, numDays, rng);
+    let assetIndex = 0;
+
+    for (let i = 0; i < daysWithPhotos.length && assetIndex < totalAssets; i++) {
+      const dayAssets =
+        Math.floor(totalAssets / numDays) + (i === daysWithPhotos.length - 1 ? totalAssets % numDays : 0);
+      // Create a new RNG for this day
+      const dayRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, daysWithPhotos[i], dayAssets, ownerId, dayRng));
+      assetIndex += dayAssets;
+    }
+    return assets;
+  },
+
+  'start-heavy': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // Most assets in first week
+    const assets: MockTimelineAsset[] = [];
+    const firstWeekAssets = Math.floor(totalAssets * 0.7);
+    const remainingAssets = totalAssets - firstWeekAssets;
+
+    // First 7 days
+    assets.push(...generateConsecutiveDays(year, month, 1, 7, firstWeekAssets, ownerId, rng));
+
+    // Remaining scattered
+    if (remainingAssets > 0) {
+      const midDay = Math.floor(daysInMonth / 2);
+      // Create a new RNG for the remaining assets
+      const remainingRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, midDay, remainingAssets, ownerId, remainingRng));
+    }
+    return assets;
+  },
+
+  'end-heavy': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // Most assets in last week
+    const assets: MockTimelineAsset[] = [];
+    const lastWeekAssets = Math.floor(totalAssets * 0.7);
+    const remainingAssets = totalAssets - lastWeekAssets;
+
+    // Remaining at start
+    if (remainingAssets > 0) {
+      // Create a new RNG for the start assets
+      const startRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, 2, remainingAssets, ownerId, startRng));
+    }
+
+    // Last 7 days
+    const startDay = daysInMonth - 6;
+    assets.push(...generateConsecutiveDays(year, month, startDay, 7, lastWeekAssets, ownerId, rng));
+    return assets;
+  },
+
+  'mid-heavy': (year, month, daysInMonth, totalAssets, ownerId, rng) => {
+    // Most assets in middle of month
+    const assets: MockTimelineAsset[] = [];
+    const midAssets = Math.floor(totalAssets * 0.7);
+    const sideAssets = Math.floor((totalAssets - midAssets) / 2);
+
+    // Start
+    if (sideAssets > 0) {
+      // Create a new RNG for the start assets
+      const startRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, 2, sideAssets, ownerId, startRng));
+    }
+
+    // Middle
+    const midStart = Math.floor(daysInMonth / 2) - 3;
+    assets.push(...generateConsecutiveDays(year, month, midStart, 7, midAssets, ownerId, rng));
+
+    // End
+    const endAssets = totalAssets - midAssets - sideAssets;
+    if (endAssets > 0) {
+      // Create a new RNG for the end assets
+      const endRng = new SeededRandom(rng.nextInt(0, 1_000_000));
+      assets.push(...generateDayAssets(year, month, daysInMonth - 1, endAssets, ownerId, endRng));
+    }
+    return assets;
+  },
+};
+export type MonthDistribution =
+  | 'empty' // 0 assets
+  | 'sparse' // 3-8 assets
+  | 'medium' // 15-30 assets
+  | 'dense' // 50-80 assets
+  | 'very-dense'; // 80-150 assets
+
+export type DayPattern =
+  | 'single-day' // All images in one day
+  | 'consecutive-large' // Multiple days with 15-25 images each
+  | 'consecutive-small' // Multiple days with 1-3 images each (side-by-side)
+  | 'alternating' // Alternating large/small days
+  | 'sparse-scattered' // Few images scattered across month
+  | 'start-heavy' // Most images at start of month
+  | 'end-heavy' // Most images at end of month
+  | 'mid-heavy'; // Most images in middle of month
--- a/e2e/src/generators/timeline/images.ts
+++ b/e2e/src/generators/timeline/images.ts
@@ -0,0 +1,111 @@
+import sharp from 'sharp';
+import { SeededRandom } from 'src/generators/timeline/utils';
+
+export const randomThumbnail = async (seed: string, ratio: number) => {
+  const height = 235;
+  const width = Math.round(height * ratio);
+  return randomImageFromString(seed, { width, height });
+};
+
+export const randomPreview = async (seed: string, ratio: number) => {
+  const height = 500;
+  const width = Math.round(height * ratio);
+  return randomImageFromString(seed, { width, height });
+};
+
+export const randomImageFromString = async (
+  seed: string = '',
+  { width = 100, height = 100 }: { width: number; height: number },
+) => {
+  // Convert string to number for seeding
+  let seedNumber = 0;
+  for (let i = 0; i < seed.length; i++) {
+    seedNumber = (seedNumber << 5) - seedNumber + (seed.codePointAt(i) ?? 0);
+    seedNumber = seedNumber & seedNumber; // Convert to 32bit integer
+  }
+  return randomImage(new SeededRandom(Math.abs(seedNumber)), { width, height });
+};
+
+export const randomImage = async (rng: SeededRandom, { width, height }: { width: number; height: number }) => {
+  const r1 = rng.nextInt(0, 256);
+  const g1 = rng.nextInt(0, 256);
+  const b1 = rng.nextInt(0, 256);
+  const r2 = rng.nextInt(0, 256);
+  const g2 = rng.nextInt(0, 256);
+  const b2 = rng.nextInt(0, 256);
+  const patternType = rng.nextInt(0, 5);
+
+  let svgPattern = '';
+
+  switch (patternType) {
+    case 0: {
+      // Solid color
+      svgPattern = `<svg width="${width}" height="${height}">
+        <rect x="0" y="0" width="${width}" height="${height}" fill="rgb(${r1},${g1},${b1})"/>
+      </svg>`;
+      break;
+    }
+
+    case 1: {
+      // Horizontal stripes
+      const stripeHeight = 10;
+      svgPattern = `<svg width="${width}" height="${height}">
+        ${Array.from(
+          { length: height / stripeHeight },
+          (_, i) =>
+            `<rect x="0" y="${i * stripeHeight}" width="${width}" height="${stripeHeight}"
+            fill="rgb(${i % 2 ? r1 : r2},${i % 2 ? g1 : g2},${i % 2 ? b1 : b2})"/>`,
+        ).join('')}
+      </svg>`;
+      break;
+    }
+
+    case 2: {
+      // Vertical stripes
+      const stripeWidth = 10;
+      svgPattern = `<svg width="${width}" height="${height}">
+        ${Array.from(
+          { length: width / stripeWidth },
+          (_, i) =>
+            `<rect x="${i * stripeWidth}" y="0" width="${stripeWidth}" height="${height}"
+            fill="rgb(${i % 2 ? r1 : r2},${i % 2 ? g1 : g2},${i % 2 ? b1 : b2})"/>`,
+        ).join('')}
+      </svg>`;
+      break;
+    }
+
+    case 3: {
+      // Checkerboard
+      const squareSize = 10;
+      svgPattern = `<svg width="${width}" height="${height}">
+        ${Array.from({ length: height / squareSize }, (_, row) =>
+          Array.from({ length: width / squareSize }, (_, col) => {
+            const isEven = (row + col) % 2 === 0;
+            return `<rect x="${col * squareSize}" y="${row * squareSize}"
+              width="${squareSize}" height="${squareSize}"
+              fill="rgb(${isEven ? r1 : r2},${isEven ? g1 : g2},${isEven ? b1 : b2})"/>`;
+          }).join(''),
+        ).join('')}
+      </svg>`;
+      break;
+    }
+
+    case 4: {
+      // Diagonal stripes
+      svgPattern = `<svg width="${width}" height="${height}">
+        <defs>
+          <pattern id="diagonal" x="0" y="0" width="20" height="20" patternUnits="userSpaceOnUse">
+            <rect x="0" y="0" width="10" height="20" fill="rgb(${r1},${g1},${b1})"/>
+            <rect x="10" y="0" width="10" height="20" fill="rgb(${r2},${g2},${b2})"/>
+          </pattern>
+        </defs>
+        <rect x="0" y="0" width="${width}" height="${height}" fill="url(#diagonal)" transform="rotate(45 50 50)"/>
+      </svg>`;
+      break;
+    }
+  }
+
+  const svgBuffer = Buffer.from(svgPattern);
+  const jpegData = await sharp(svgBuffer).jpeg({ quality: 50 }).toBuffer();
+  return jpegData;
+};
--- a/e2e/src/generators/timeline/model-objects.ts
+++ b/e2e/src/generators/timeline/model-objects.ts
@@ -0,0 +1,265 @@
+/**
+ * Generator functions for timeline model objects
+ */
+
+import { faker } from '@faker-js/faker';
+import { AssetVisibility } from '@immich/sdk';
+import { DateTime } from 'luxon';
+import { writeFileSync } from 'node:fs';
+import { SeededRandom } from 'src/generators/timeline/utils';
+import type { DayPattern, MonthDistribution } from './distribution-patterns';
+import { ASSET_DISTRIBUTION, DAY_DISTRIBUTION } from './distribution-patterns';
+import type { MockTimelineAsset, MockTimelineData, SerializedTimelineData, TimelineConfig } from './timeline-config';
+import { ASPECT_RATIO_WEIGHTS, GENERATION_CONSTANTS, validateTimelineConfig } from './timeline-config';
+
+/**
+ * Generate a random aspect ratio based on weighted probabilities
+ */
+export function generateAspectRatio(rng: SeededRandom): string {
+  const random = rng.next();
+  let cumulative = 0;
+
+  for (const [ratio, weight] of Object.entries(ASPECT_RATIO_WEIGHTS)) {
+    cumulative += weight;
+    if (random < cumulative) {
+      return ratio;
+    }
+  }
+  return '16:9'; // Default fallback
+}
+
+export function generateThumbhash(rng: SeededRandom): string {
+  return Array.from({ length: 10 }, () => rng.nextInt(0, 256).toString(16).padStart(2, '0')).join('');
+}
+
+export function generateDuration(rng: SeededRandom): string {
+  return `${rng.nextInt(GENERATION_CONSTANTS.MIN_VIDEO_DURATION_SECONDS, GENERATION_CONSTANTS.MAX_VIDEO_DURATION_SECONDS)}.${rng.nextInt(0, 1000).toString().padStart(3, '0')}`;
+}
+
+export function generateUUID(): string {
+  return faker.string.uuid();
+}
+
+export function generateAsset(
+  year: number,
+  month: number,
+  day: number,
+  ownerId: string,
+  rng: SeededRandom,
+): MockTimelineAsset {
+  const from = DateTime.fromObject({ year, month, day }).setZone('UTC');
+  const to = from.endOf('day');
+  const date = faker.date.between({ from: from.toJSDate(), to: to.toJSDate() });
+  const isVideo = rng.next() < GENERATION_CONSTANTS.VIDEO_PROBABILITY;
+
+  const assetId = generateUUID();
+  const hasGPS = rng.next() < GENERATION_CONSTANTS.GPS_PERCENTAGE;
+
+  const ratio = generateAspectRatio(rng);
+
+  const asset: MockTimelineAsset = {
+    id: assetId,
+    ownerId,
+    ratio: Number.parseFloat(ratio.split(':')[0]) / Number.parseFloat(ratio.split(':')[1]),
+    thumbhash: generateThumbhash(rng),
+    localDateTime: date.toISOString(),
+    fileCreatedAt: date.toISOString(),
+    isFavorite: rng.next() < GENERATION_CONSTANTS.FAVORITE_PROBABILITY,
+    isTrashed: false,
+    isVideo,
+    isImage: !isVideo,
+    duration: isVideo ? generateDuration(rng) : null,
+    projectionType: null,
+    livePhotoVideoId: null,
+    city: hasGPS ? faker.location.city() : null,
+    country: hasGPS ? faker.location.country() : null,
+    people: null,
+    latitude: hasGPS ? faker.location.latitude() : null,
+    longitude: hasGPS ? faker.location.longitude() : null,
+    visibility: AssetVisibility.Timeline,
+    stack: null,
+    fileSizeInByte: faker.number.int({ min: 510, max: 5_000_000 }),
+    checksum: faker.string.alphanumeric({ length: 5 }),
+  };
+
+  return asset;
+}
+
+/**
+ * Generate assets for a specific day
+ */
+export function generateDayAssets(
+  year: number,
+  month: number,
+  day: number,
+  assetCount: number,
+  ownerId: string,
+  rng: SeededRandom,
+): MockTimelineAsset[] {
+  return Array.from({ length: assetCount }, () => generateAsset(year, month, day, ownerId, rng));
+}
+
+/**
+ * Distribute assets evenly across consecutive days
+ *
+ * @returns Array of generated timeline assets
+ */
+export function generateConsecutiveDays(
+  year: number,
+  month: number,
+  startDay: number,
+  numDays: number,
+  totalAssets: number,
+  ownerId: string,
+  rng: SeededRandom,
+): MockTimelineAsset[] {
+  const assets: MockTimelineAsset[] = [];
+  const assetsPerDay = Math.floor(totalAssets / numDays);
+
+  for (let i = 0; i < numDays; i++) {
+    const dayAssets =
+      i === numDays - 1
+        ? totalAssets - assetsPerDay * (numDays - 1) // Remainder on last day
+        : assetsPerDay;
+    // Create a new RNG with a different seed for each day
+    const dayRng = new SeededRandom(rng.nextInt(0, 1_000_000) + i * 100);
+    assets.push(...generateDayAssets(year, month, startDay + i, dayAssets, ownerId, dayRng));
+  }
+
+  return assets;
+}
+
+/**
+ * Generate assets for a month with specified distribution pattern
+ */
+export function generateMonthAssets(
+  year: number,
+  month: number,
+  ownerId: string,
+  distribution: MonthDistribution = 'medium',
+  pattern: DayPattern = 'consecutive-large',
+  rng: SeededRandom,
+): MockTimelineAsset[] {
+  const daysInMonth = new Date(year, month, 0).getDate();
+
+  if (distribution === 'empty') {
+    return [];
+  }
+
+  const distributionStrategy = ASSET_DISTRIBUTION[distribution];
+  if (!distributionStrategy) {
+    console.warn(`Unknown distribution: ${distribution}, defaulting to medium`);
+    return [];
+  }
+  const totalAssets = distributionStrategy(rng);
+
+  const dayStrategy = DAY_DISTRIBUTION[pattern];
+  if (!dayStrategy) {
+    console.warn(`Unknown pattern: ${pattern}, defaulting to consecutive-large`);
+    // Fallback to consecutive-large pattern
+    const numDays = Math.min(5, Math.floor(totalAssets / 15));
+    const startDay = rng.nextInt(1, daysInMonth - numDays + 2);
+    const assets = generateConsecutiveDays(year, month, startDay, numDays, totalAssets, ownerId, rng);
+    assets.sort((a, b) => DateTime.fromISO(b.localDateTime).diff(DateTime.fromISO(a.localDateTime)).milliseconds);
+    return assets;
+  }
+
+  const assets = dayStrategy(year, month, daysInMonth, totalAssets, ownerId, rng);
+  assets.sort((a, b) => DateTime.fromISO(b.localDateTime).diff(DateTime.fromISO(a.localDateTime)).milliseconds);
+  return assets;
+}
+
+/**
+ * Main generator function for timeline data
+ */
+export function generateTimelineData(config: TimelineConfig): MockTimelineData {
+  validateTimelineConfig(config);
+
+  const buckets = new Map<string, MockTimelineAsset[]>();
+  const monthStats: Record<string, { count: number; distribution: MonthDistribution; pattern: DayPattern }> = {};
+
+  const globalRng = new SeededRandom(config.seed || GENERATION_CONSTANTS.DEFAULT_SEED);
+  faker.seed(globalRng.nextInt(0, 1_000_000));
+  for (const monthConfig of config.months) {
+    const { year, month, distribution, pattern } = monthConfig;
+
+    const monthSeed = globalRng.nextInt(0, 1_000_000);
+    const monthRng = new SeededRandom(monthSeed);
+
+    const monthAssets = generateMonthAssets(
+      year,
+      month,
+      config.ownerId || generateUUID(),
+      distribution,
+      pattern,
+      monthRng,
+    );
+
+    if (monthAssets.length > 0) {
+      const monthKey = `${year}-${month.toString().padStart(2, '0')}`;
+      monthStats[monthKey] = {
+        count: monthAssets.length,
+        distribution,
+        pattern,
+      };
+
+      // Create bucket key (YYYY-MM-01)
+      const bucketKey = `${year}-${month.toString().padStart(2, '0')}-01`;
+      buckets.set(bucketKey, monthAssets);
+    }
+  }
+
+  // Create a mock album from random assets
+  const allAssets = [...buckets.values()].flat();
+
+  // Select 10-30 random assets for the album (or all assets if less than 10)
+  const albumSize = Math.min(allAssets.length, globalRng.nextInt(10, 31));
+  const selectedAssetConfigs: MockTimelineAsset[] = [];
+  const usedIndices = new Set<number>();
+
+  while (selectedAssetConfigs.length < albumSize && usedIndices.size < allAssets.length) {
+    const randomIndex = globalRng.nextInt(0, allAssets.length);
+    if (!usedIndices.has(randomIndex)) {
+      usedIndices.add(randomIndex);
+      selectedAssetConfigs.push(allAssets[randomIndex]);
+    }
+  }
+
+  // Sort selected assets by date (newest first)
+  selectedAssetConfigs.sort(
+    (a, b) => DateTime.fromISO(b.localDateTime).diff(DateTime.fromISO(a.localDateTime)).milliseconds,
+  );
+
+  const selectedAssets = selectedAssetConfigs.map((asset) => asset.id);
+
+  const now = new Date().toISOString();
+  const album = {
+    id: generateUUID(),
+    albumName: 'Test Album',
+    description: 'A mock album for testing',
+    assetIds: selectedAssets,
+    thumbnailAssetId: selectedAssets.length > 0 ? selectedAssets[0] : null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  // Write to file if configured
+  if (config.writeToFile) {
+    const outputPath = config.outputPath || '/tmp/timeline-data.json';
+
+    // Convert Map to object for serialization
+    const serializedData: SerializedTimelineData = {
+      buckets: Object.fromEntries(buckets),
+      album,
+    };
+
+    try {
+      writeFileSync(outputPath, JSON.stringify(serializedData, null, 2));
+      console.log(`Timeline data written to ${outputPath}`);
+    } catch (error) {
+      console.error(`Failed to write timeline data to ${outputPath}:`, error);
+    }
+  }
+
+  return { buckets, album };
+}
--- a/e2e/src/generators/timeline/rest-response.ts
+++ b/e2e/src/generators/timeline/rest-response.ts
@@ -0,0 +1,436 @@
+/**
+ * REST API output functions for converting timeline data to API response formats
+ */
+
+import {
+  AssetTypeEnum,
+  AssetVisibility,
+  UserAvatarColor,
+  type AlbumResponseDto,
+  type AssetResponseDto,
+  type ExifResponseDto,
+  type TimeBucketAssetResponseDto,
+  type TimeBucketsResponseDto,
+  type UserResponseDto,
+} from '@immich/sdk';
+import { DateTime } from 'luxon';
+import { signupDto } from 'src/fixtures';
+import { parseTimeBucketKey } from 'src/generators/timeline/utils';
+import type { MockTimelineAsset, MockTimelineData } from './timeline-config';
+
+/**
+ * Convert timeline/asset models to columnar format (parallel arrays)
+ */
+export function toColumnarFormat(assets: MockTimelineAsset[]): TimeBucketAssetResponseDto {
+  const result: TimeBucketAssetResponseDto = {
+    id: [],
+    ownerId: [],
+    ratio: [],
+    thumbhash: [],
+    fileCreatedAt: [],
+    localOffsetHours: [],
+    isFavorite: [],
+    isTrashed: [],
+    isImage: [],
+    duration: [],
+    projectionType: [],
+    livePhotoVideoId: [],
+    city: [],
+    country: [],
+    visibility: [],
+  };
+
+  for (const asset of assets) {
+    result.id.push(asset.id);
+    result.ownerId.push(asset.ownerId);
+    result.ratio.push(asset.ratio);
+    result.thumbhash.push(asset.thumbhash);
+    result.fileCreatedAt.push(asset.fileCreatedAt);
+    result.localOffsetHours.push(0); // Assuming UTC for mocks
+    result.isFavorite.push(asset.isFavorite);
+    result.isTrashed.push(asset.isTrashed);
+    result.isImage.push(asset.isImage);
+    result.duration.push(asset.duration);
+    result.projectionType.push(asset.projectionType);
+    result.livePhotoVideoId.push(asset.livePhotoVideoId);
+    result.city.push(asset.city);
+    result.country.push(asset.country);
+    result.visibility.push(asset.visibility);
+  }
+
+  if (assets.some((a) => a.latitude !== null || a.longitude !== null)) {
+    result.latitude = assets.map((a) => a.latitude);
+    result.longitude = assets.map((a) => a.longitude);
+  }
+
+  result.stack = assets.map(() => null);
+  return result;
+}
+
+/**
+ * Extract a single bucket from timeline data (mimics getTimeBucket API)
+ * Automatically handles both ISO timestamp and simple month formats
+ * Returns data in columnar format matching the actual API
+ * When albumId is provided, only returns assets from that album
+ */
+export function getTimeBucket(
+  timelineData: MockTimelineData,
+  timeBucket: string,
+  isTrashed: boolean | undefined,
+  isArchived: boolean | undefined,
+  isFavorite: boolean | undefined,
+  albumId: string | undefined,
+  changes: Changes,
+): TimeBucketAssetResponseDto {
+  const bucketKey = parseTimeBucketKey(timeBucket);
+  let assets = timelineData.buckets.get(bucketKey);
+
+  if (!assets) {
+    return toColumnarFormat([]);
+  }
+
+  // Create sets for quick lookups
+  const deletedAssetIds = new Set(changes.assetDeletions);
+  const archivedAssetIds = new Set(changes.assetArchivals);
+  const favoritedAssetIds = new Set(changes.assetFavorites);
+
+  // Filter assets based on trashed/archived status
+  assets = assets.filter((asset) =>
+    shouldIncludeAsset(asset, isTrashed, isArchived, isFavorite, deletedAssetIds, archivedAssetIds, favoritedAssetIds),
+  );
+
+  // Filter to only include assets from the specified album
+  if (albumId) {
+    const album = timelineData.album;
+    if (!album || album.id !== albumId) {
+      return toColumnarFormat([]);
+    }
+
+    // Create a Set for faster lookup
+    const albumAssetIds = new Set([...album.assetIds, ...changes.albumAdditions]);
+    assets = assets.filter((asset) => albumAssetIds.has(asset.id));
+  }
+
+  // Override properties for assets in changes arrays
+  const assetsWithOverrides = assets.map((asset) => {
+    if (deletedAssetIds.has(asset.id) || archivedAssetIds.has(asset.id) || favoritedAssetIds.has(asset.id)) {
+      return {
+        ...asset,
+        isFavorite: favoritedAssetIds.has(asset.id) ? true : asset.isFavorite,
+        isTrashed: deletedAssetIds.has(asset.id) ? true : asset.isTrashed,
+        visibility: archivedAssetIds.has(asset.id) ? AssetVisibility.Archive : asset.visibility,
+      };
+    }
+    return asset;
+  });
+
+  return toColumnarFormat(assetsWithOverrides);
+}
+
+export type Changes = {
+  // ids of assets that are newly added to the album
+  albumAdditions: string[];
+  // ids of assets that are newly deleted
+  assetDeletions: string[];
+  // ids of assets that are newly archived
+  assetArchivals: string[];
+  // ids of assets that are newly favorited
+  assetFavorites: string[];
+};
+
+/**
+ * Helper function to determine if an asset should be included based on filter criteria
+ * @param asset - The asset to check
+ * @param isTrashed - Filter for trashed status (undefined means no filter)
+ * @param isArchived - Filter for archived status (undefined means no filter)
+ * @param isFavorite - Filter for favorite status (undefined means no filter)
+ * @param deletedAssetIds - Set of IDs for assets that have been deleted
+ * @param archivedAssetIds - Set of IDs for assets that have been archived
+ * @param favoritedAssetIds - Set of IDs for assets that have been favorited
+ * @returns true if the asset matches all filter criteria
+ */
+function shouldIncludeAsset(
+  asset: MockTimelineAsset,
+  isTrashed: boolean | undefined,
+  isArchived: boolean | undefined,
+  isFavorite: boolean | undefined,
+  deletedAssetIds: Set<string>,
+  archivedAssetIds: Set<string>,
+  favoritedAssetIds: Set<string>,
+): boolean {
+  // Determine actual status (property or in changes)
+  const actuallyTrashed = asset.isTrashed || deletedAssetIds.has(asset.id);
+  const actuallyArchived = asset.visibility === 'archive' || archivedAssetIds.has(asset.id);
+  const actuallyFavorited = asset.isFavorite || favoritedAssetIds.has(asset.id);
+
+  // Apply filters
+  if (isTrashed !== undefined && actuallyTrashed !== isTrashed) {
+    return false;
+  }
+  if (isArchived !== undefined && actuallyArchived !== isArchived) {
+    return false;
+  }
+  if (isFavorite !== undefined && actuallyFavorited !== isFavorite) {
+    return false;
+  }
+
+  return true;
+}
+/**
+ * Get summary for all buckets (mimics getTimeBuckets API)
+ * When albumId is provided, only includes buckets that contain assets from that album
+ */
+export function getTimeBuckets(
+  timelineData: MockTimelineData,
+  isTrashed: boolean | undefined,
+  isArchived: boolean | undefined,
+  isFavorite: boolean | undefined,
+  albumId: string | undefined,
+  changes: Changes,
+): TimeBucketsResponseDto[] {
+  const summary: TimeBucketsResponseDto[] = [];
+
+  // Create sets for quick lookups
+  const deletedAssetIds = new Set(changes.assetDeletions);
+  const archivedAssetIds = new Set(changes.assetArchivals);
+  const favoritedAssetIds = new Set(changes.assetFavorites);
+
+  // If no albumId is specified, return summary for all assets
+  if (albumId) {
+    // Filter to only include buckets with assets from the specified album
+    const album = timelineData.album;
+    if (!album || album.id !== albumId) {
+      return [];
+    }
+
+    // Create a Set for faster lookup
+    const albumAssetIds = new Set([...album.assetIds, ...changes.albumAdditions]);
+    for (const removed of changes.assetDeletions) {
+      albumAssetIds.delete(removed);
+    }
+    for (const [bucketKey, assets] of timelineData.buckets) {
+      // Count how many assets in this bucket are in the album and match trashed/archived filters
+      const albumAssetsInBucket = assets.filter((asset) => {
+        // Must be in the album
+        if (!albumAssetIds.has(asset.id)) {
+          return false;
+        }
+
+        return shouldIncludeAsset(
+          asset,
+          isTrashed,
+          isArchived,
+          isFavorite,
+          deletedAssetIds,
+          archivedAssetIds,
+          favoritedAssetIds,
+        );
+      });
+
+      if (albumAssetsInBucket.length > 0) {
+        summary.push({
+          timeBucket: bucketKey,
+          count: albumAssetsInBucket.length,
+        });
+      }
+    }
+  } else {
+    for (const [bucketKey, assets] of timelineData.buckets) {
+      // Filter assets based on trashed/archived status
+      const filteredAssets = assets.filter((asset) =>
+        shouldIncludeAsset(
+          asset,
+          isTrashed,
+          isArchived,
+          isFavorite,
+          deletedAssetIds,
+          archivedAssetIds,
+          favoritedAssetIds,
+        ),
+      );
+
+      if (filteredAssets.length > 0) {
+        summary.push({
+          timeBucket: bucketKey,
+          count: filteredAssets.length,
+        });
+      }
+    }
+  }
+
+  // Sort summary by date (newest first) using luxon
+  summary.sort((a, b) => {
+    const dateA = DateTime.fromISO(a.timeBucket);
+    const dateB = DateTime.fromISO(b.timeBucket);
+    return dateB.diff(dateA).milliseconds;
+  });
+
+  return summary;
+}
+
+const createDefaultOwner = (ownerId: string) => {
+  const defaultOwner: UserResponseDto = {
+    id: ownerId,
+    email: signupDto.admin.email,
+    name: signupDto.admin.name,
+    profileImagePath: '',
+    profileChangedAt: new Date().toISOString(),
+    avatarColor: UserAvatarColor.Blue,
+  };
+  return defaultOwner;
+};
+
+/**
+ * Convert a TimelineAssetConfig to a full AssetResponseDto
+ * This matches the response from GET /api/assets/:id
+ */
+export function toAssetResponseDto(asset: MockTimelineAsset, owner?: UserResponseDto): AssetResponseDto {
+  const now = new Date().toISOString();
+
+  // Default owner if not provided
+  const defaultOwner = createDefaultOwner(asset.ownerId);
+
+  const exifInfo: ExifResponseDto = {
+    make: null,
+    model: null,
+    exifImageWidth: asset.ratio > 1 ? 4000 : 3000,
+    exifImageHeight: asset.ratio > 1 ? Math.round(4000 / asset.ratio) : Math.round(3000 * asset.ratio),
+    fileSizeInByte: asset.fileSizeInByte,
+    orientation: '1',
+    dateTimeOriginal: asset.fileCreatedAt,
+    modifyDate: asset.fileCreatedAt,
+    timeZone: asset.latitude === null ? null : 'UTC',
+    lensModel: null,
+    fNumber: null,
+    focalLength: null,
+    iso: null,
+    exposureTime: null,
+    latitude: asset.latitude,
+    longitude: asset.longitude,
+    city: asset.city,
+    country: asset.country,
+    state: null,
+    description: null,
+  };
+
+  return {
+    id: asset.id,
+    deviceAssetId: `device-${asset.id}`,
+    ownerId: asset.ownerId,
+    owner: owner || defaultOwner,
+    libraryId: `library-${asset.ownerId}`,
+    deviceId: `device-${asset.ownerId}`,
+    type: asset.isVideo ? AssetTypeEnum.Video : AssetTypeEnum.Image,
+    originalPath: `/original/${asset.id}.${asset.isVideo ? 'mp4' : 'jpg'}`,
+    originalFileName: `${asset.id}.${asset.isVideo ? 'mp4' : 'jpg'}`,
+    originalMimeType: asset.isVideo ? 'video/mp4' : 'image/jpeg',
+    thumbhash: asset.thumbhash,
+    fileCreatedAt: asset.fileCreatedAt,
+    fileModifiedAt: asset.fileCreatedAt,
+    localDateTime: asset.localDateTime,
+    updatedAt: now,
+    createdAt: asset.fileCreatedAt,
+    isFavorite: asset.isFavorite,
+    isArchived: false,
+    isTrashed: asset.isTrashed,
+    visibility: asset.visibility,
+    duration: asset.duration || '0:00:00.00000',
+    exifInfo,
+    livePhotoVideoId: asset.livePhotoVideoId,
+    tags: [],
+    people: [],
+    unassignedFaces: [],
+    stack: asset.stack,
+    isOffline: false,
+    hasMetadata: true,
+    duplicateId: null,
+    resized: true,
+    checksum: asset.checksum,
+  };
+}
+
+/**
+ * Get a single asset by ID from timeline data
+ * This matches the response from GET /api/assets/:id
+ */
+export function getAsset(
+  timelineData: MockTimelineData,
+  assetId: string,
+  owner?: UserResponseDto,
+): AssetResponseDto | undefined {
+  // Search through all buckets for the asset
+  const buckets = [...timelineData.buckets.values()];
+  for (const assets of buckets) {
+    const asset = assets.find((a) => a.id === assetId);
+    if (asset) {
+      return toAssetResponseDto(asset, owner);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Get a mock album from timeline data
+ * This matches the response from GET /api/albums/:id
+ */
+export function getAlbum(
+  timelineData: MockTimelineData,
+  ownerId: string,
+  albumId: string | undefined,
+  changes: Changes,
+): AlbumResponseDto | undefined {
+  if (!timelineData.album) {
+    return undefined;
+  }
+
+  // If albumId is provided and doesn't match, return undefined
+  if (albumId && albumId !== timelineData.album.id) {
+    return undefined;
+  }
+
+  const album = timelineData.album;
+  const albumOwner = createDefaultOwner(ownerId);
+
+  // Get the actual asset objects from the timeline data
+  const albumAssets: AssetResponseDto[] = [];
+  const allAssets = [...timelineData.buckets.values()].flat();
+
+  for (const assetId of album.assetIds) {
+    const assetConfig = allAssets.find((a) => a.id === assetId);
+    if (assetConfig) {
+      albumAssets.push(toAssetResponseDto(assetConfig, albumOwner));
+    }
+  }
+  for (const assetId of changes.albumAdditions ?? []) {
+    const assetConfig = allAssets.find((a) => a.id === assetId);
+    if (assetConfig) {
+      albumAssets.push(toAssetResponseDto(assetConfig, albumOwner));
+    }
+  }
+
+  albumAssets.sort((a, b) => DateTime.fromISO(b.localDateTime).diff(DateTime.fromISO(a.localDateTime)).milliseconds);
+
+  // For a basic mock album, we don't include any albumUsers (shared users)
+  // The owner is represented by the owner field, not in albumUsers
+  const response: AlbumResponseDto = {
+    id: album.id,
+    albumName: album.albumName,
+    description: album.description,
+    albumThumbnailAssetId: album.thumbnailAssetId,
+    createdAt: album.createdAt,
+    updatedAt: album.updatedAt,
+    ownerId: albumOwner.id,
+    owner: albumOwner,
+    albumUsers: [], // Empty array for non-shared album
+    shared: false,
+    hasSharedLink: false,
+    isActivityEnabled: true,
+    assetCount: albumAssets.length,
+    assets: albumAssets,
+    startDate: albumAssets.length > 0 ? albumAssets.at(-1)?.fileCreatedAt : undefined,
+    endDate: albumAssets.length > 0 ? albumAssets[0].fileCreatedAt : undefined,
+    lastModifiedAssetTimestamp: albumAssets.length > 0 ? albumAssets[0].fileCreatedAt : undefined,
+  };
+
+  return response;
+}
--- a/e2e/src/generators/timeline/timeline-config.ts
+++ b/e2e/src/generators/timeline/timeline-config.ts
@@ -0,0 +1,200 @@
+import type { AssetVisibility } from '@immich/sdk';
+import { DayPattern, MonthDistribution } from 'src/generators/timeline/distribution-patterns';
+
+// Constants for generation parameters
+export const GENERATION_CONSTANTS = {
+  VIDEO_PROBABILITY: 0.15, // 15% of assets are videos
+  GPS_PERCENTAGE: 0.7, // 70% of assets have GPS data
+  FAVORITE_PROBABILITY: 0.1, // 10% of assets are favorited
+  MIN_VIDEO_DURATION_SECONDS: 5,
+  MAX_VIDEO_DURATION_SECONDS: 300,
+  DEFAULT_SEED: 12_345,
+  DEFAULT_OWNER_ID: 'user-1',
+  MAX_SELECT_ATTEMPTS: 10,
+  SPARSE_DAY_COVERAGE: 0.4, // 40% of days have photos in sparse pattern
+} as const;
+
+// Aspect ratio distribution weights (must sum to 1)
+export const ASPECT_RATIO_WEIGHTS = {
+  '4:3': 0.35, // 35% 4:3 landscape
+  '3:2': 0.25, // 25% 3:2 landscape
+  '16:9': 0.2, // 20% 16:9 landscape
+  '2:3': 0.1, // 10% 2:3 portrait
+  '1:1': 0.09, // 9% 1:1 square
+  '3:1': 0.01, // 1% 3:1 panorama
+} as const;
+
+export type AspectRatio = {
+  width: number;
+  height: number;
+  ratio: number;
+  name: string;
+};
+
+// Mock configuration for asset generation - will be transformed to API response formats
+export type MockTimelineAsset = {
+  id: string;
+  ownerId: string;
+  ratio: number;
+  thumbhash: string | null;
+  localDateTime: string;
+  fileCreatedAt: string;
+  isFavorite: boolean;
+  isTrashed: boolean;
+  isVideo: boolean;
+  isImage: boolean;
+  duration: string | null;
+  projectionType: string | null;
+  livePhotoVideoId: string | null;
+  city: string | null;
+  country: string | null;
+  people: string[] | null;
+  latitude: number | null;
+  longitude: number | null;
+  visibility: AssetVisibility;
+  stack: null;
+  checksum: string;
+  fileSizeInByte: number;
+};
+
+export type MonthSpec = {
+  year: number;
+  month: number; // 1-12
+  distribution: MonthDistribution;
+  pattern: DayPattern;
+};
+
+/**
+ * Configuration for timeline data generation
+ */
+export type TimelineConfig = {
+  ownerId?: string;
+  months: MonthSpec[];
+  seed?: number;
+  writeToFile?: boolean;
+  outputPath?: string;
+};
+
+export type MockAlbum = {
+  id: string;
+  albumName: string;
+  description: string;
+  assetIds: string[]; // IDs of assets in the album
+  thumbnailAssetId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type MockTimelineData = {
+  buckets: Map<string, MockTimelineAsset[]>;
+  album: MockAlbum; // Mock album created from random assets
+};
+
+export type SerializedTimelineData = {
+  buckets: Record<string, MockTimelineAsset[]>;
+  album: MockAlbum;
+};
+
+/**
+ * Validates a TimelineConfig object to ensure all values are within expected ranges
+ */
+export function validateTimelineConfig(config: TimelineConfig): void {
+  if (!config.months || config.months.length === 0) {
+    throw new Error('TimelineConfig must contain at least one month');
+  }
+
+  const seenMonths = new Set<string>();
+
+  for (const month of config.months) {
+    if (month.month < 1 || month.month > 12) {
+      throw new Error(`Invalid month: ${month.month}. Must be between 1 and 12`);
+    }
+
+    if (month.year < 1900 || month.year > 2100) {
+      throw new Error(`Invalid year: ${month.year}. Must be between 1900 and 2100`);
+    }
+
+    const monthKey = `${month.year}-${month.month}`;
+    if (seenMonths.has(monthKey)) {
+      throw new Error(`Duplicate month found: ${monthKey}`);
+    }
+    seenMonths.add(monthKey);
+
+    // Validate distribution if provided
+    if (month.distribution && !['empty', 'sparse', 'medium', 'dense', 'very-dense'].includes(month.distribution)) {
+      throw new Error(
+        `Invalid distribution: ${month.distribution}. Must be one of: empty, sparse, medium, dense, very-dense`,
+      );
+    }
+
+    const validPatterns = [
+      'single-day',
+      'consecutive-large',
+      'consecutive-small',
+      'alternating',
+      'sparse-scattered',
+      'start-heavy',
+      'end-heavy',
+      'mid-heavy',
+    ];
+    if (month.pattern && !validPatterns.includes(month.pattern)) {
+      throw new Error(`Invalid pattern: ${month.pattern}. Must be one of: ${validPatterns.join(', ')}`);
+    }
+  }
+
+  // Validate seed if provided
+  if (config.seed !== undefined && (config.seed < 0 || !Number.isInteger(config.seed))) {
+    throw new Error('Seed must be a non-negative integer');
+  }
+
+  // Validate ownerId if provided
+  if (config.ownerId !== undefined && config.ownerId.trim() === '') {
+    throw new Error('Owner ID cannot be an empty string');
+  }
+}
+
+/**
+ * Create a default timeline configuration
+ */
+export function createDefaultTimelineConfig(): TimelineConfig {
+  const months: MonthSpec[] = [
+    // 2024 - Mix of patterns
+    { year: 2024, month: 12, distribution: 'very-dense', pattern: 'alternating' },
+    { year: 2024, month: 11, distribution: 'dense', pattern: 'consecutive-large' },
+    { year: 2024, month: 10, distribution: 'medium', pattern: 'mid-heavy' },
+    { year: 2024, month: 9, distribution: 'sparse', pattern: 'consecutive-small' },
+    { year: 2024, month: 8, distribution: 'empty', pattern: 'single-day' },
+    { year: 2024, month: 7, distribution: 'dense', pattern: 'start-heavy' },
+    { year: 2024, month: 6, distribution: 'medium', pattern: 'sparse-scattered' },
+    { year: 2024, month: 5, distribution: 'sparse', pattern: 'single-day' },
+    { year: 2024, month: 4, distribution: 'very-dense', pattern: 'consecutive-large' },
+    { year: 2024, month: 3, distribution: 'empty', pattern: 'single-day' },
+    { year: 2024, month: 2, distribution: 'medium', pattern: 'end-heavy' },
+    { year: 2024, month: 1, distribution: 'dense', pattern: 'alternating' },
+
+    // 2023 - Testing year boundaries and more patterns
+    { year: 2023, month: 12, distribution: 'very-dense', pattern: 'end-heavy' },
+    { year: 2023, month: 11, distribution: 'sparse', pattern: 'consecutive-small' },
+    { year: 2023, month: 10, distribution: 'empty', pattern: 'single-day' },
+    { year: 2023, month: 9, distribution: 'medium', pattern: 'alternating' },
+    { year: 2023, month: 8, distribution: 'dense', pattern: 'mid-heavy' },
+    { year: 2023, month: 7, distribution: 'sparse', pattern: 'sparse-scattered' },
+    { year: 2023, month: 6, distribution: 'medium', pattern: 'consecutive-large' },
+    { year: 2023, month: 5, distribution: 'empty', pattern: 'single-day' },
+    { year: 2023, month: 4, distribution: 'sparse', pattern: 'single-day' },
+    { year: 2023, month: 3, distribution: 'dense', pattern: 'start-heavy' },
+    { year: 2023, month: 2, distribution: 'medium', pattern: 'alternating' },
+    { year: 2023, month: 1, distribution: 'very-dense', pattern: 'consecutive-large' },
+  ];
+
+  for (let year = 2022; year >= 2000; year--) {
+    for (let month = 12; month >= 1; month--) {
+      months.push({ year, month, distribution: 'medium', pattern: 'sparse-scattered' });
+    }
+  }
+
+  return {
+    months,
+    seed: 42,
+  };
+}
--- a/e2e/src/generators/timeline/utils.ts
+++ b/e2e/src/generators/timeline/utils.ts
@@ -0,0 +1,186 @@
+import { DateTime } from 'luxon';
+import { GENERATION_CONSTANTS, MockTimelineAsset } from 'src/generators/timeline/timeline-config';
+
+/**
+ * Linear Congruential Generator for deterministic pseudo-random numbers
+ */
+export class SeededRandom {
+  private seed: number;
+
+  constructor(seed: number) {
+    this.seed = seed;
+  }
+
+  /**
+   * Generate next random number in range [0, 1)
+   */
+  next(): number {
+    // LCG parameters from Numerical Recipes
+    this.seed = (this.seed * 1_664_525 + 1_013_904_223) % 2_147_483_647;
+    return this.seed / 2_147_483_647;
+  }
+
+  /**
+   * Generate random integer in range [min, max)
+   */
+  nextInt(min: number, max: number): number {
+    return Math.floor(this.next() * (max - min)) + min;
+  }
+
+  /**
+   * Generate random boolean with given probability
+   */
+  nextBoolean(probability = 0.5): boolean {
+    return this.next() < probability;
+  }
+}
+
+/**
+ * Select random days using seed variation to avoid collisions.
+ *
+ * @param daysInMonth - Total number of days in the month
+ * @param numDays - Number of days to select
+ * @param rng - Random number generator instance
+ * @returns Array of selected day numbers, sorted in descending order
+ */
+export function selectRandomDays(daysInMonth: number, numDays: number, rng: SeededRandom): number[] {
+  const selectedDays = new Set<number>();
+  const maxAttempts = numDays * GENERATION_CONSTANTS.MAX_SELECT_ATTEMPTS; // Safety limit
+  let attempts = 0;
+
+  while (selectedDays.size < numDays && attempts < maxAttempts) {
+    const day = rng.nextInt(1, daysInMonth + 1);
+    selectedDays.add(day);
+    attempts++;
+  }
+
+  // Fallback: if we couldn't select enough random days, fill with sequential days
+  if (selectedDays.size < numDays) {
+    for (let day = 1; day <= daysInMonth && selectedDays.size < numDays; day++) {
+      selectedDays.add(day);
+    }
+  }
+
+  return [...selectedDays].sort((a, b) => b - a);
+}
+
+/**
+ * Select item from array using seeded random
+ */
+export function selectRandom<T>(arr: T[], rng: SeededRandom): T {
+  if (arr.length === 0) {
+    throw new Error('Cannot select from empty array');
+  }
+  const index = rng.nextInt(0, arr.length);
+  return arr[index];
+}
+
+/**
+ * Select multiple random items from array using seeded random without duplicates
+ */
+export function selectRandomMultiple<T>(arr: T[], count: number, rng: SeededRandom): T[] {
+  if (arr.length === 0) {
+    throw new Error('Cannot select from empty array');
+  }
+  if (count < 0) {
+    throw new Error('Count must be non-negative');
+  }
+  if (count > arr.length) {
+    throw new Error('Count cannot exceed array length');
+  }
+
+  const result: T[] = [];
+  const selectedIndices = new Set<number>();
+
+  while (result.length < count) {
+    const index = rng.nextInt(0, arr.length);
+    if (!selectedIndices.has(index)) {
+      selectedIndices.add(index);
+      result.push(arr[index]);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse timeBucket parameter to extract year-month key
+ * Handles both formats:
+ * - ISO timestamp: "2024-12-01T00:00:00.000Z" -> "2024-12-01"
+ * - Simple format: "2024-12-01" -> "2024-12-01"
+ */
+export function parseTimeBucketKey(timeBucket: string): string {
+  if (!timeBucket) {
+    throw new Error('timeBucket parameter cannot be empty');
+  }
+
+  const dt = DateTime.fromISO(timeBucket, { zone: 'utc' });
+
+  if (!dt.isValid) {
+    // Fallback to regex if not a valid ISO string
+    const match = timeBucket.match(/^(\d{4}-\d{2}-\d{2})/);
+    return match ? match[1] : timeBucket;
+  }
+
+  // Format as YYYY-MM-01 (first day of month)
+  return `${dt.year}-${String(dt.month).padStart(2, '0')}-01`;
+}
+
+export function getMockAsset(
+  asset: MockTimelineAsset,
+  sortedDescendingAssets: MockTimelineAsset[],
+  direction: 'next' | 'previous',
+  unit: 'day' | 'month' | 'year' = 'day',
+): MockTimelineAsset | null {
+  const currentDateTime = DateTime.fromISO(asset.localDateTime, { zone: 'utc' });
+
+  const currentIndex = sortedDescendingAssets.findIndex((a) => a.id === asset.id);
+
+  if (currentIndex === -1) {
+    return null;
+  }
+
+  const step = direction === 'next' ? 1 : -1;
+  const startIndex = currentIndex + step;
+
+  if (direction === 'next' && currentIndex >= sortedDescendingAssets.length - 1) {
+    return null;
+  }
+  if (direction === 'previous' && currentIndex <= 0) {
+    return null;
+  }
+
+  const isInDifferentPeriod = (date1: DateTime, date2: DateTime): boolean => {
+    if (unit === 'day') {
+      return !date1.startOf('day').equals(date2.startOf('day'));
+    } else if (unit === 'month') {
+      return date1.year !== date2.year || date1.month !== date2.month;
+    } else {
+      return date1.year !== date2.year;
+    }
+  };
+
+  if (direction === 'next') {
+    // Search forward in array (backwards in time)
+    for (let i = startIndex; i < sortedDescendingAssets.length; i++) {
+      const nextAsset = sortedDescendingAssets[i];
+      const nextDate = DateTime.fromISO(nextAsset.localDateTime, { zone: 'utc' });
+
+      if (isInDifferentPeriod(nextDate, currentDateTime)) {
+        return nextAsset;
+      }
+    }
+  } else {
+    // Search backward in array (forwards in time)
+    for (let i = startIndex; i >= 0; i--) {
+      const prevAsset = sortedDescendingAssets[i];
+      const prevDate = DateTime.fromISO(prevAsset.localDateTime, { zone: 'utc' });
+
+      if (isInDifferentPeriod(prevDate, currentDateTime)) {
+        return prevAsset;
+      }
+    }
+  }
+
+  return null;
+}