feat: add AssetBatchSize and client persist options

[Zaida-3dO]

Summary

Add AssetBatchSize config option to control how many assets are fetched per batch (default: 25)

Rationale: Currently this is hardcoded to 25 but that means after 25 images you get a new batch of random assets where there could be collisions, making this configurable allows the user to determine how long they want to go before possible seeing duplicate assets.

Add ClientPersistAssetQueue to persist current and upcoming assets in localStorage across browser restarts

Add ClientPersistAssetHistory to persist asset history in localStorage for back button functionality after refresh

Rationale: Currently if the client restarts (e.g. due to a power cycle on the TV or the app gets unintentionally closed, all viewed items and the current queue gets reset. This means

1. You can go back to view history anymore
2. You get a fresh batch of assets that might again, be duplicates of those you already viewed recently
   This makes it configurable to choose for all clients to persist the history and queue so you don't loose your place just because the app got closed.

Open questions/considerations

• This should maybe be a client side config - Ideally I actually think this should be a config on the client side especially for the android app, but I don't have much experience with android dev so this was the next best thing
• Should these be the same config - I can see arguments for both my current solution and for this being one config option instead of 2, but I figured it's never a bad idea to have more configurability. I'm happy to change this if maintainers think otherwise.
• Assets stored might become stale (i.e. no longer supposed to be server by the server) - This is valid and so i added a warning in the config to flag this, setting the config to false will also clear the state for any user who runs into this.

Summary by CodeRabbit

• New Features

  • Configurable asset batch size (default: 25) used for asset loading.
  • Optional client-side persistence for asset queue and viewing history.
  • Client persistence restores displayed assets and resumes viewing state on load; fetches continue when no restoration available.
  • Asset requests now include a client identifier for improved client-specific behavior.

• Documentation

  • Configuration guide updated with the new settings and usage notes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Add three new general settings (AssetBatchSize, ClientPersistAssetQueue, ClientPersistAssetHistory); propagate them through backend models, DTOs, and API types; make GetAssets use AssetBatchSize; add frontend persisted stores and restoration/persistence logic for asset backlog, displaying assets, and history.

Changes

Cohort / File(s)	Summary
Backend Interface & Models ImmichFrame.Core/Interfaces/IServerSettings.cs, ImmichFrame.WebApi/Models/ServerSettings.cs, ImmichFrame.WebApi/Helpers/Config/ServerSettingsV1.cs	Added three IGeneralSettings properties: AssetBatchSize (int), ClientPersistAssetQueue (bool), ClientPersistAssetHistory (bool). Implemented defaults and validation (AssetBatchSize >= 1).
Backend Logic ImmichFrame.Core/Logic/PooledImmichFrameLogic.cs	Replaced hardcoded batch size with generalSettings.AssetBatchSize when requesting asset batches.
Backend → Frontend DTO ImmichFrame.WebApi/Models/ClientSettingsDto.cs	Added DTO properties AssetBatchSize, ClientPersistAssetQueue, ClientPersistAssetHistory and map them from generalSettings.
Frontend API Types immichFrame.Web/src/lib/immichFrameApi.ts	Extended client settings type with assetBatchSize?: number, clientPersistAssetQueue?: boolean, clientPersistAssetHistory?: boolean.
Frontend Persisted Stores immichFrame.Web/src/lib/stores/persist.store.ts	Added persistArrayStore<T> and clearPersistedStore; exported assetBacklogStore, assetHistoryStore, displayingAssetsStore persisted in localStorage.
Frontend Component Logic immichFrame.Web/src/lib/components/home-page/home-page.svelte	Added persistence helpers (persistBacklog, persistHistory, persistDisplaying), showAssets flow, restoration on mount conditional on server flags, pass clientIdentifier to asset fetches, and integrate persistence into navigation/load flows.
Documentation docs/docs/getting-started/configuration.md	Documented three new general configuration keys with defaults and notes.

Sequence Diagram

sequenceDiagram
    participant Browser as Client (Browser)
    participant API as Server (API)
    participant LS as LocalStorage
    participant Pool as Asset Pool

    Browser->>API: GET /client-settings
    API-->>Browser: ClientSettings (assetBatchSize, persist flags)

    alt clientPersistAssetQueue or clientPersistAssetHistory enabled
        Browser->>LS: load `assetBacklog`, `displayingAssets`, `assetHistory`
        alt persisted data found
            LS-->>Browser: return persisted arrays
            Browser->>Pool: render persisted displayingAssets
            Browser->>Browser: restore image promises
        else no persisted data
            Browser->>API: Fetch assets (include clientIdentifier, batchSize)
            API-->>Browser: return asset batch
            Browser->>Pool: render fetched assets
            Browser->>LS: persist backlog & displaying
        end
    else persistence disabled
        Browser->>LS: clear persisted keys
        Browser->>API: Fetch assets (include clientIdentifier, batchSize)
        API-->>Browser: return asset batch
        Browser->>Pool: render fetched assets
    end

    loop user navigates (next/previous)
        Browser->>Browser: compute next/previous sets
        Browser->>LS: persist backlog & history
        Browser->>Pool: render updated displayingAssets
    end

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I nibble configs, count batches by light,
I tuck asset queues safe through day and night,
Backlogs remembered, history kept near,
With hops and a twitch, the gallery's here! 🥕✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add AssetBatchSize and client persist options' accurately and concisely summarizes the main changes: adding a configurable batch size setting and client-side persistence options across multiple layers.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

immichFrame.Web/src/lib/components/home-page/home-page.svelte (1)

344-387: Fix persistence key scoping to prevent cross-client data leakage.

Persistence keys (assetBacklog, assetHistory, displayingAssets) are hardcoded without client identifier. Switching ?client= will restore the previous client's queue and history. Include the client identifier in the persistence keys or clear these stores when the client parameter changes.

🤖 Fix all issues with AI agents

In `@ImmichFrame.WebApi/Models/ServerSettings.cs`:
- Around line 73-75: ServerSettings.AssetBatchSize can be zero/negative and must
be validated in ServerSettings.Validate(); update Validate() to clamp or enforce
a minimum (e.g., if AssetBatchSize < 1 then set AssetBatchSize = 1 or throw) so
downstream logic never sees non-positive batch sizes—locate the ServerSettings
class and its Validate() method and add this check (use Math.Max(1,
AssetBatchSize) or equivalent).

🧹 Nitpick comments (1)

ImmichFrame.WebApi/Helpers/Config/ServerSettingsV1.cs (1)

129-131: Avoid default drift between V1 adapter and GeneralSettings.

These hard-coded defaults can diverge from GeneralSettings over time. Consider referencing a shared constant/default source to keep them in sync.