From 383806325a0dca99ad4b4fa3f257c868600ff0ab Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Tue, 4 Mar 2025 10:00:12 +0000
Subject: [PATCH 1/9] Add shallow character load mode

---
 public/index.html             |  7 ++++++
 public/script.js              | 38 ++++++++++++++++++++++++++++++++-
 public/scripts/group-chats.js | 37 ++++++++++++++++++++++++++++----
 public/scripts/power-user.js  |  8 +++++++
 public/scripts/st-context.js  |  5 ++++-
 src/endpoints/characters.js   | 40 +++++++++++++++++++++++++++++++----
 6 files changed, 125 insertions(+), 10 deletions(-)

diff --git a/public/index.html b/public/index.html
index 8d86a76ce..0261c09c5 100644
--- a/public/index.html
+++ b/public/index.html
@@ -4424,6 +4424,13 @@
                                     <option data-i18n="tag_import_existing" value="4">Existing</option>
                                 </select>
                             </div>
+                            <label class="checkbox_label" for="shallow_characters" data-i18n="[title]Experimental feature. May behave unstable and have compatibility issues." title="Experimental feature. May behave unstable and have compatibility issues.">
+                                <input id="shallow_characters" type="checkbox" />
+                                <small data-i18n="Lazy Load Characters">
+                                    Lazy Load Characters
+                                </small>
+                                <i class="fa-solid fa-flask"></i>
+                            </label>
                             <label class="checkbox_label" for="fuzzy_search_checkbox" title="Use fuzzy matching, and search characters in the list by all data fields, not just by a name substring." data-i18n="[title]Use fuzzy matching, and search characters in the list by all data fields, not just by a name substring">
                                 <input id="fuzzy_search_checkbox" type="checkbox" />
                                 <small data-i18n="Advanced Character Search">Advanced Character Search</small>
diff --git a/public/script.js b/public/script.js
index 2ed1110df..27fa1eda8 100644
--- a/public/script.js
+++ b/public/script.js
@@ -1781,7 +1781,7 @@ export async function getCharacters() {
         method: 'POST',
         headers: getRequestHeaders(),
         body: JSON.stringify({
-            '': '',
+            shallow: power_user.shallow_characters,
         }),
     });
     if (response.ok === true) {
@@ -3658,6 +3658,9 @@ export async function Generate(type, { automatic_trigger, force_name2, quiet_pro
     setGenerationProgress(0);
     generation_started = new Date();
 
+    // Prevent generation from shallow characters
+    await unshallowCharacter(this_chid);
+
     // Occurs every time, even if the generation is aborted due to slash commands execution
     await eventSource.emit(event_types.GENERATION_STARTED, type, { automatic_trigger, force_name2, quiet_prompt, quietToLoud, skipWIAN, force_chid, signal, quietImage }, dryRun);
 
@@ -6704,9 +6707,42 @@ export function buildAvatarList(block, entities, { templateId = 'inline_avatar_t
     }
 }
 
+/**
+ * Loads all the data of a shallow character.
+ * @param {string|undefined} characterId Array index
+ * @returns {Promise<void>} Promise that resolves when the character is unshallowed
+ */
+export async function unshallowCharacter(characterId) {
+    if (characterId === undefined) {
+        console.warn('Undefined character cannot be unshallowed');
+        return;
+    }
+
+    const character = characters[characterId];
+    if (!character) {
+        console.warn('Character not found:', characterId);
+        return;
+    }
+
+    // Character is not shallow
+    if (!character.shallow) {
+        return;
+    }
+
+    const avatar = character.avatar;
+    if (!avatar) {
+        console.warn('Character has no avatar field:', characterId);
+        return;
+    }
+
+    await getOneCharacter(avatar);
+}
+
 export async function getChat() {
     //console.log('/api/chats/get -- entered for -- ' + characters[this_chid].name);
     try {
+        await unshallowCharacter(this_chid);
+
         const response = await $.ajax({
             type: 'POST',
             url: '/api/chats/get',
diff --git a/public/scripts/group-chats.js b/public/scripts/group-chats.js
index d1431d74f..0fbd5b543 100644
--- a/public/scripts/group-chats.js
+++ b/public/scripts/group-chats.js
@@ -72,6 +72,7 @@ import {
     animation_duration,
     depth_prompt_role_default,
     shouldAutoContinue,
+    unshallowCharacter,
 } from '../script.js';
 import { printTagList, createTagMapFromList, applyTagsOnCharacterSelect, tag_map, applyTagsOnGroupSelect } from './tags.js';
 import { FILTER_TYPES, FilterHelper } from './filters.js';
@@ -216,6 +217,7 @@ export async function getGroupChat(groupId, reload = false) {
 
     // Run validation before any loading
     validateGroup(group);
+    await unshallowGroupMembers(groupId);
 
     const chat_id = group.chat_id;
     const data = await loadGroupChat(chat_id);
@@ -824,6 +826,8 @@ async function generateGroupWrapper(by_auto_mode, type = null, params = {}) {
     }
 
     try {
+        await unshallowGroupMembers(selected_group);
+
         throwIfAborted();
         hideSwipeButtons();
         is_group_generating = true;
@@ -1137,6 +1141,29 @@ export async function editGroup(id, immediately, reload = true) {
     saveGroupDebounced(group, reload);
 }
 
+/**
+ * Unshallows all definitions of group members.
+ * @param {string} groupId Id of the group
+ * @returns {Promise<void>} Promise that resolves when all group members are unshallowed
+ */
+export async function unshallowGroupMembers(groupId) {
+    const group = groups.find(x => x.id == groupId);
+    if (!group) {
+        return;
+    }
+    const members = group.members;
+    if (!Array.isArray(members)) {
+        return;
+    }
+    for (const member of members) {
+        const index = characters.findIndex(x => x.avatar === member);
+        if (index === -1) {
+            continue;
+        }
+        await unshallowCharacter(String(index));
+    }
+}
+
 let groupAutoModeAbortController = null;
 
 async function groupChatAutoModeWorker() {
@@ -1158,9 +1185,9 @@ async function groupChatAutoModeWorker() {
     await generateGroupWrapper(true, 'auto', { signal: groupAutoModeAbortController.signal });
 }
 
-async function modifyGroupMember(chat_id, groupMember, isDelete) {
+async function modifyGroupMember(groupId, groupMember, isDelete) {
     const id = groupMember.data('id');
-    const thisGroup = groups.find((x) => x.id == chat_id);
+    const thisGroup = groups.find((x) => x.id == groupId);
     const membersArray = thisGroup?.members ?? newGroupMembers;
 
     if (isDelete) {
@@ -1173,6 +1200,7 @@ async function modifyGroupMember(chat_id, groupMember, isDelete) {
     }
 
     if (openGroupId) {
+        await unshallowGroupMembers(openGroupId);
         await editGroup(openGroupId, false, false);
         updateGroupAvatar(thisGroup);
     }
@@ -1638,7 +1666,7 @@ async function onGroupActionClick(event) {
     }
 
     if (action === 'view') {
-        openCharacterDefinition(member);
+        await openCharacterDefinition(member);
     }
 
     if (action === 'speak') {
@@ -1690,7 +1718,7 @@ export async function openGroupById(groupId) {
     return false;
 }
 
-function openCharacterDefinition(characterSelect) {
+async function openCharacterDefinition(characterSelect) {
     if (is_group_generating) {
         toastr.warning(t`Can't peek a character while group reply is being generated`);
         console.warn('Can\'t peek a character def while group reply is being generated');
@@ -1703,6 +1731,7 @@ function openCharacterDefinition(characterSelect) {
         return;
     }
 
+    await unshallowCharacter(chid);
     setCharacterId(chid);
     select_selected_character(chid);
     // Gentle nudge to recalculate tokens
diff --git a/public/scripts/power-user.js b/public/scripts/power-user.js
index b06b2dacd..b1959a207 100644
--- a/public/scripts/power-user.js
+++ b/public/scripts/power-user.js
@@ -314,6 +314,7 @@ let power_user = {
     forbid_external_media: true,
     external_media_allowed_overrides: [],
     external_media_forbidden_overrides: [],
+    shallow_characters: false,
 };
 
 let themes = [];
@@ -1595,6 +1596,7 @@ async function loadPowerUserSettings(settings, data) {
     $('#auto-connect-checkbox').prop('checked', power_user.auto_connect);
     $('#auto-load-chat-checkbox').prop('checked', power_user.auto_load_chat);
     $('#forbid_external_media').prop('checked', power_user.forbid_external_media);
+    $('#shallow_characters').prop('checked', power_user.shallow_characters);
 
     for (const theme of themes) {
         const option = document.createElement('option');
@@ -3888,6 +3890,12 @@ $(document).ready(() => {
         await exportTheme();
     });
 
+    $('#shallow_characters').on('input', function () {
+        power_user.shallow_characters = !!$(this).prop('checked');
+        saveSettingsDebounced();
+        toastr.info('Reload the page for this setting to take effect');
+    });
+
     $(document).on('click', '#debug_table [data-debug-function]', function () {
         const functionId = $(this).data('debug-function');
         const functionRecord = debug_functions.find(f => f.functionId === functionId);
diff --git a/public/scripts/st-context.js b/public/scripts/st-context.js
index 5278e7591..cfe55d379 100644
--- a/public/scripts/st-context.js
+++ b/public/scripts/st-context.js
@@ -47,6 +47,7 @@ import {
     updateMessageBlock,
     printMessages,
     clearChat,
+    unshallowCharacter,
 } from '../script.js';
 import {
     extension_settings,
@@ -55,7 +56,7 @@ import {
     renderExtensionTemplateAsync,
     writeExtensionField,
 } from './extensions.js';
-import { groups, openGroupChat, selected_group } from './group-chats.js';
+import { groups, openGroupChat, selected_group, unshallowGroupMembers } from './group-chats.js';
 import { addLocaleData, getCurrentLocale, t, translate } from './i18n.js';
 import { hideLoader, showLoader } from './loader.js';
 import { MacrosParser } from './macros.js';
@@ -210,6 +211,8 @@ export function getContext() {
         clearChat,
         ChatCompletionService,
         TextCompletionService,
+        unshallowCharacter,
+        unshallowGroupMembers,
     };
 }
 
diff --git a/src/endpoints/characters.js b/src/endpoints/characters.js
index f4a7307a5..db6e6a0c0 100644
--- a/src/endpoints/characters.js
+++ b/src/endpoints/characters.js
@@ -200,14 +200,45 @@ const calculateDataSize = (data) => {
     return typeof data === 'object' ? Object.values(data).reduce((acc, val) => acc + String(val).length, 0) : 0;
 };
 
+/**
+ * Only get fields that are used to display the character list.
+ * @param {object} character Character object
+ * @returns {{shallow: true, [key: string]: any}} Shallow character
+ */
+const toShallow = (character) => {
+    return {
+        name: character.name,
+        avatar: character.avatar,
+        chat: character.chat,
+        fav: character.fav,
+        date_added: character.date_added,
+        create_date: character.create_date,
+        date_last_chat: character.date_last_chat,
+        chat_size: character.chat_size,
+        data_size: character.data_size,
+        data: {
+            name: _.get(character, 'data.name', ''),
+            character_version: _.get(character, 'data.character_version', ''),
+            creator: _.get(character, 'data.creator', ''),
+            creator_notes: _.get(character, 'data.creator_notes', ''),
+            extensions: {
+                fav: _.get(character, 'data.extensions.fav', false),
+            },
+        },
+        shallow: true,
+    };
+};
+
 /**
  * processCharacter - Process a given character, read its data and calculate its statistics.
  *
  * @param  {string} item The name of the character.
  * @param  {import('../users.js').UserDirectoryList} directories User directories
+ * @param  {object} options Options for the character processing
+ * @param  {boolean} options.shallow If true, only return the core character's metadata
  * @return {Promise<object>}     A Promise that resolves when the character processing is done.
  */
-const processCharacter = async (item, directories) => {
+const processCharacter = async (item, directories, { shallow }) => {
     try {
         const imgFile = path.join(directories.characters, item);
         const imgData = await readCharacterData(imgFile);
@@ -226,7 +257,7 @@ const processCharacter = async (item, directories) => {
         character['chat_size'] = chatSize;
         character['date_last_chat'] = dateLastChat;
         character['data_size'] = calculateDataSize(jsonObject?.data);
-        return character;
+        return shallow ? toShallow(character) : character;
     }
     catch (err) {
         console.error(`Could not process character: ${item}`);
@@ -991,9 +1022,10 @@ router.post('/delete', jsonParser, validateAvatarUrlMiddleware, async function (
  */
 router.post('/all', jsonParser, async function (request, response) {
     try {
+        const shallow = !!request.body.shallow;
         const files = fs.readdirSync(request.user.directories.characters);
         const pngFiles = files.filter(file => file.endsWith('.png'));
-        const processingPromises = pngFiles.map(file => processCharacter(file, request.user.directories));
+        const processingPromises = pngFiles.map(file => processCharacter(file, request.user.directories, { shallow }));
         const data = (await Promise.all(processingPromises)).filter(c => c.name);
         return response.send(data);
     } catch (err) {
@@ -1012,7 +1044,7 @@ router.post('/get', jsonParser, validateAvatarUrlMiddleware, async function (req
             return response.sendStatus(404);
         }
 
-        const data = await processCharacter(item, request.user.directories);
+        const data = await processCharacter(item, request.user.directories, { shallow: false });
 
         return response.send(data);
     } catch (err) {

From 3d813e4ef6e0d09998a55bf074c8d8d68fabfd4f Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Tue, 4 Mar 2025 23:32:42 +0200
Subject: [PATCH 2/9] Move shallow toggle to config.yaml

---
 default/config.yaml          | 10 ++++++++--
 post-install.js              |  5 +++++
 public/index.html            |  7 -------
 public/script.js             |  5 ++---
 public/scripts/char-data.js  |  1 +
 public/scripts/power-user.js |  8 --------
 src/endpoints/characters.js  |  9 +++++----
 7 files changed, 21 insertions(+), 24 deletions(-)

diff --git a/default/config.yaml b/default/config.yaml
index 16248ef83..559e34638 100644
--- a/default/config.yaml
+++ b/default/config.yaml
@@ -1,8 +1,6 @@
 # -- DATA CONFIGURATION --
 # Root directory for user data storage
 dataRoot: ./data
-# The maximum amount of memory that parsed character cards can use in MB
-cardsCacheCapacity: 100
 # -- SERVER CONFIGURATION --
 # Listen for incoming connections
 listen: false
@@ -135,6 +133,14 @@ thumbnails:
   # Maximum thumbnail dimensions per type [width, height]
   dimensions: { 'bg': [160, 90], 'avatar': [96, 144] }
 
+# PERFORMANCE-RELATED CONFIGURATION
+performance:
+  # Enables lazy loading of character cards. Improves performances with large card libraries.
+  # May have compatibility issues with some extensions.
+  lazyLoadCharacters: false
+  # The maximum amount of memory that parsed character cards can use in MB
+  cardsCacheCapacity: 100
+
 # Allow secret keys exposure via API
 allowKeysExposure: false
 # Skip new default content checks
diff --git a/post-install.js b/post-install.js
index 1989b61aa..3ff1fc080 100644
--- a/post-install.js
+++ b/post-install.js
@@ -96,6 +96,11 @@ const keyMigrationMap = [
         newKey: 'logging.minLogLevel',
         migrate: (value) => value,
     },
+    {
+        oldKey: 'cardsCacheCapacity',
+        newKey: 'performance.cardsCacheCapacity',
+        migrate: (value) => value,
+    },
     // uncomment one release after 1.12.13
     /*
     {
diff --git a/public/index.html b/public/index.html
index 0261c09c5..8d86a76ce 100644
--- a/public/index.html
+++ b/public/index.html
@@ -4424,13 +4424,6 @@
                                     <option data-i18n="tag_import_existing" value="4">Existing</option>
                                 </select>
                             </div>
-                            <label class="checkbox_label" for="shallow_characters" data-i18n="[title]Experimental feature. May behave unstable and have compatibility issues." title="Experimental feature. May behave unstable and have compatibility issues.">
-                                <input id="shallow_characters" type="checkbox" />
-                                <small data-i18n="Lazy Load Characters">
-                                    Lazy Load Characters
-                                </small>
-                                <i class="fa-solid fa-flask"></i>
-                            </label>
                             <label class="checkbox_label" for="fuzzy_search_checkbox" title="Use fuzzy matching, and search characters in the list by all data fields, not just by a name substring." data-i18n="[title]Use fuzzy matching, and search characters in the list by all data fields, not just by a name substring">
                                 <input id="fuzzy_search_checkbox" type="checkbox" />
                                 <small data-i18n="Advanced Character Search">Advanced Character Search</small>
diff --git a/public/script.js b/public/script.js
index 27fa1eda8..127679c29 100644
--- a/public/script.js
+++ b/public/script.js
@@ -1780,9 +1780,7 @@ export async function getCharacters() {
     const response = await fetch('/api/characters/all', {
         method: 'POST',
         headers: getRequestHeaders(),
-        body: JSON.stringify({
-            shallow: power_user.shallow_characters,
-        }),
+        body: JSON.stringify({}),
     });
     if (response.ok === true) {
         characters.splice(0, characters.length);
@@ -6718,6 +6716,7 @@ export async function unshallowCharacter(characterId) {
         return;
     }
 
+    /** @type {import('./scripts/char-data.js').v1CharData} */
     const character = characters[characterId];
     if (!character) {
         console.warn('Character not found:', characterId);
diff --git a/public/scripts/char-data.js b/public/scripts/char-data.js
index be28d8172..51e85722c 100644
--- a/public/scripts/char-data.js
+++ b/public/scripts/char-data.js
@@ -113,5 +113,6 @@
  * @property {string} chat - name of the current chat file chat
  * @property {string} avatar - file name of the avatar image (acts as a unique identifier)
  * @property {string} json_data - the full raw JSON data of the character
+ * @property {boolean?} shallow - if the data is shallow (lazy-loaded)
  */
 export default 0;// now this file is a module
diff --git a/public/scripts/power-user.js b/public/scripts/power-user.js
index b1959a207..b06b2dacd 100644
--- a/public/scripts/power-user.js
+++ b/public/scripts/power-user.js
@@ -314,7 +314,6 @@ let power_user = {
     forbid_external_media: true,
     external_media_allowed_overrides: [],
     external_media_forbidden_overrides: [],
-    shallow_characters: false,
 };
 
 let themes = [];
@@ -1596,7 +1595,6 @@ async function loadPowerUserSettings(settings, data) {
     $('#auto-connect-checkbox').prop('checked', power_user.auto_connect);
     $('#auto-load-chat-checkbox').prop('checked', power_user.auto_load_chat);
     $('#forbid_external_media').prop('checked', power_user.forbid_external_media);
-    $('#shallow_characters').prop('checked', power_user.shallow_characters);
 
     for (const theme of themes) {
         const option = document.createElement('option');
@@ -3890,12 +3888,6 @@ $(document).ready(() => {
         await exportTheme();
     });
 
-    $('#shallow_characters').on('input', function () {
-        power_user.shallow_characters = !!$(this).prop('checked');
-        saveSettingsDebounced();
-        toastr.info('Reload the page for this setting to take effect');
-    });
-
     $(document).on('click', '#debug_table [data-debug-function]', function () {
         const functionId = $(this).data('debug-function');
         const functionRecord = debug_functions.find(f => f.functionId === functionId);
diff --git a/src/endpoints/characters.js b/src/endpoints/characters.js
index db6e6a0c0..f70e6d9c1 100644
--- a/src/endpoints/characters.js
+++ b/src/endpoints/characters.js
@@ -24,11 +24,13 @@ import { importRisuSprites } from './sprites.js';
 const defaultAvatarPath = './public/img/ai4.png';
 
 // KV-store for parsed character data
-const cacheCapacity = Number(getConfigValue('cardsCacheCapacity', 100, 'number')); // MB
+const cacheCapacity = Number(getConfigValue('performance.cardsCacheCapacity', 100, 'number')); // MB
 // With 100 MB limit it would take roughly 3000 characters to reach this limit
 const characterDataCache = new MemoryLimitedMap(1024 * 1024 * cacheCapacity);
 // Some Android devices require tighter memory management
 const isAndroid = process.platform === 'android';
+// Use shallow character data for the character list
+const useShallowCharacters = !!getConfigValue('performance.lazyLoadCharacters', false, 'boolean');
 
 /**
  * Reads the character card from the specified image file.
@@ -207,6 +209,7 @@ const calculateDataSize = (data) => {
  */
 const toShallow = (character) => {
     return {
+        shallow: true,
         name: character.name,
         avatar: character.avatar,
         chat: character.chat,
@@ -225,7 +228,6 @@ const toShallow = (character) => {
                 fav: _.get(character, 'data.extensions.fav', false),
             },
         },
-        shallow: true,
     };
 };
 
@@ -1022,10 +1024,9 @@ router.post('/delete', jsonParser, validateAvatarUrlMiddleware, async function (
  */
 router.post('/all', jsonParser, async function (request, response) {
     try {
-        const shallow = !!request.body.shallow;
         const files = fs.readdirSync(request.user.directories.characters);
         const pngFiles = files.filter(file => file.endsWith('.png'));
-        const processingPromises = pngFiles.map(file => processCharacter(file, request.user.directories, { shallow }));
+        const processingPromises = pngFiles.map(file => processCharacter(file, request.user.directories, { shallow: useShallowCharacters }));
         const data = (await Promise.all(processingPromises)).filter(c => c.name);
         return response.send(data);
     } catch (err) {

From 5d69189f8fbe237c97835af74d3100ff66befcd5 Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Tue, 4 Mar 2025 23:49:32 +0200
Subject: [PATCH 3/9] Hard limit hotswaps to 25 entries

---
 public/scripts/RossAscends-mods.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/public/scripts/RossAscends-mods.js b/public/scripts/RossAscends-mods.js
index d7fcb1c5a..fc845fcbc 100644
--- a/public/scripts/RossAscends-mods.js
+++ b/public/scripts/RossAscends-mods.js
@@ -316,7 +316,7 @@ export async function favsToHotswap() {
     const entities = getEntitiesList({ doFilter: false });
     const container = $('#right-nav-panel .hotswap');
 
-    const favs = entities.filter(x => x.item.fav || x.item.fav == 'true');
+    const favs = entities.filter(x => x.item.fav || x.item.fav == 'true').slice(0, 25);
 
     //helpful instruction message if no characters are favorited
     if (favs.length == 0) {

From 13cfe1650f2d4f2c54062f0d6d619d3caec6b49e Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Wed, 5 Mar 2025 00:40:20 +0200
Subject: [PATCH 4/9] Add bytes parser lib

---
 package-lock.json | 8 ++++++++
 package.json      | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index 49994110d..24ac745b6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,11 +16,13 @@
                 "@iconfu/svg-inject": "^1.2.3",
                 "@mozilla/readability": "^0.5.0",
                 "@popperjs/core": "^2.11.8",
+                "@types/bytes": "^3.1.5",
                 "@zeldafan0225/ai_horde": "^5.2.0",
                 "archiver": "^7.0.1",
                 "bing-translate-api": "^4.0.2",
                 "body-parser": "^1.20.2",
                 "bowser": "^2.11.0",
+                "bytes": "^3.1.2",
                 "chalk": "^5.4.1",
                 "command-exists": "^1.2.9",
                 "compression": "^1.8.0",
@@ -1105,6 +1107,12 @@
                 "@types/node": "*"
             }
         },
+        "node_modules/@types/bytes": {
+            "version": "3.1.5",
+            "resolved": "https://registry.npmjs.org/@types/bytes/-/bytes-3.1.5.tgz",
+            "integrity": "sha512-VgZkrJckypj85YxEsEavcMmmSOIzkUHqWmM4CCyia5dc54YwsXzJ5uT4fYxBQNEXx+oF1krlhgCbvfubXqZYsQ==",
+            "license": "MIT"
+        },
         "node_modules/@types/cacheable-request": {
             "version": "6.0.3",
             "resolved": "https://registry.npmjs.org/@types/cacheable-request/-/cacheable-request-6.0.3.tgz",
diff --git a/package.json b/package.json
index 5ba2f8cc7..4df94fa6b 100644
--- a/package.json
+++ b/package.json
@@ -6,11 +6,13 @@
         "@iconfu/svg-inject": "^1.2.3",
         "@mozilla/readability": "^0.5.0",
         "@popperjs/core": "^2.11.8",
+        "@types/bytes": "^3.1.5",
         "@zeldafan0225/ai_horde": "^5.2.0",
         "archiver": "^7.0.1",
         "bing-translate-api": "^4.0.2",
         "body-parser": "^1.20.2",
         "bowser": "^2.11.0",
+        "bytes": "^3.1.2",
         "chalk": "^5.4.1",
         "command-exists": "^1.2.9",
         "compression": "^1.8.0",

From 28bad6479cafba8fa1effe94b30528e26b26518b Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Wed, 5 Mar 2025 00:45:34 +0200
Subject: [PATCH 5/9] Use human-readable memory cache capacity in config

---
 default/config.yaml         |  4 ++--
 post-install.js             |  4 ++--
 src/endpoints/characters.js | 15 +++++++--------
 src/util.js                 | 15 ++++++++-------
 4 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/default/config.yaml b/default/config.yaml
index 559e34638..f4bacf9ff 100644
--- a/default/config.yaml
+++ b/default/config.yaml
@@ -138,8 +138,8 @@ performance:
   # Enables lazy loading of character cards. Improves performances with large card libraries.
   # May have compatibility issues with some extensions.
   lazyLoadCharacters: false
-  # The maximum amount of memory that parsed character cards can use in MB
-  cardsCacheCapacity: 100
+  # The maximum amount of memory that parsed character cards can use. Set to 0 to disable memory caching.
+  memoryCacheCapacity: '100mb'
 
 # Allow secret keys exposure via API
 allowKeysExposure: false
diff --git a/post-install.js b/post-install.js
index 3ff1fc080..0048d9c6f 100644
--- a/post-install.js
+++ b/post-install.js
@@ -98,8 +98,8 @@ const keyMigrationMap = [
     },
     {
         oldKey: 'cardsCacheCapacity',
-        newKey: 'performance.cardsCacheCapacity',
-        migrate: (value) => value,
+        newKey: 'performance.memoryCacheCapacity',
+        migrate: (value) => `${value}mb`,
     },
     // uncomment one release after 1.12.13
     /*
diff --git a/src/endpoints/characters.js b/src/endpoints/characters.js
index f70e6d9c1..eb73b8db8 100644
--- a/src/endpoints/characters.js
+++ b/src/endpoints/characters.js
@@ -23,10 +23,9 @@ import { invalidateThumbnail } from './thumbnails.js';
 import { importRisuSprites } from './sprites.js';
 const defaultAvatarPath = './public/img/ai4.png';
 
-// KV-store for parsed character data
-const cacheCapacity = Number(getConfigValue('performance.cardsCacheCapacity', 100, 'number')); // MB
 // With 100 MB limit it would take roughly 3000 characters to reach this limit
-const characterDataCache = new MemoryLimitedMap(1024 * 1024 * cacheCapacity);
+const memoryCacheCapacity = getConfigValue('performance.memoryCacheCapacity', '100mb');
+const memoryCache = new MemoryLimitedMap(memoryCacheCapacity);
 // Some Android devices require tighter memory management
 const isAndroid = process.platform === 'android';
 // Use shallow character data for the character list
@@ -41,12 +40,12 @@ const useShallowCharacters = !!getConfigValue('performance.lazyLoadCharacters',
 async function readCharacterData(inputFile, inputFormat = 'png') {
     const stat = fs.statSync(inputFile);
     const cacheKey = `${inputFile}-${stat.mtimeMs}`;
-    if (characterDataCache.has(cacheKey)) {
-        return characterDataCache.get(cacheKey);
+    if (memoryCache.has(cacheKey)) {
+        return memoryCache.get(cacheKey);
     }
 
     const result = parse(inputFile, inputFormat);
-    !isAndroid && characterDataCache.set(cacheKey, result);
+    !isAndroid && memoryCache.set(cacheKey, result);
     return result;
 }
 
@@ -62,12 +61,12 @@ async function readCharacterData(inputFile, inputFormat = 'png') {
 async function writeCharacterData(inputFile, data, outputFile, request, crop = undefined) {
     try {
         // Reset the cache
-        for (const key of characterDataCache.keys()) {
+        for (const key of memoryCache.keys()) {
             if (Buffer.isBuffer(inputFile)) {
                 break;
             }
             if (key.startsWith(inputFile)) {
-                characterDataCache.delete(key);
+                memoryCache.delete(key);
                 break;
             }
         }
diff --git a/src/util.js b/src/util.js
index e6246b5d2..1dec2b466 100644
--- a/src/util.js
+++ b/src/util.js
@@ -16,6 +16,7 @@ import mime from 'mime-types';
 import { default as simpleGit } from 'simple-git';
 import chalk from 'chalk';
 import { LOG_LEVELS } from './constants.js';
+import bytes from 'bytes';
 
 /**
  * Parsed config object.
@@ -856,14 +857,10 @@ export function setupLogLevel() {
 export class MemoryLimitedMap {
     /**
      * Creates an instance of MemoryLimitedMap.
-     * @param {number} maxMemoryInBytes - The maximum allowed memory in bytes for string values.
+     * @param {string} cacheCapacity - Maximum memory usage in human-readable format (e.g., '1 GB').
      */
-    constructor(maxMemoryInBytes) {
-        if (typeof maxMemoryInBytes !== 'number' || maxMemoryInBytes <= 0 || isNaN(maxMemoryInBytes)) {
-            console.warn('Invalid maxMemoryInBytes, using a fallback value of 1 GB.');
-            maxMemoryInBytes = 1024 * 1024 * 1024; // 1 GB
-        }
-        this.maxMemory = maxMemoryInBytes;
+    constructor(cacheCapacity) {
+        this.maxMemory = bytes.parse(cacheCapacity) ?? 0;
         this.currentMemory = 0;
         this.map = new Map();
         this.queue = [];
@@ -886,6 +883,10 @@ export class MemoryLimitedMap {
      * @param {string} value
      */
     set(key, value) {
+        if (this.maxMemory <= 0) {
+            return;
+        }
+
         if (typeof key !== 'string' || typeof value !== 'string') {
             return;
         }

From 507ce78c2732f6544f2eddd38e8d87aa43b881de Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Wed, 5 Mar 2025 00:51:54 +0200
Subject: [PATCH 6/9] Fix crash on undefined url in /chats

---
 src/endpoints/characters.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/endpoints/characters.js b/src/endpoints/characters.js
index eb73b8db8..a4ec7b34d 100644
--- a/src/endpoints/characters.js
+++ b/src/endpoints/characters.js
@@ -1054,11 +1054,11 @@ router.post('/get', jsonParser, validateAvatarUrlMiddleware, async function (req
 });
 
 router.post('/chats', jsonParser, validateAvatarUrlMiddleware, async function (request, response) {
-    if (!request.body) return response.sendStatus(400);
-
-    const characterDirectory = (request.body.avatar_url).replace('.png', '');
-
     try {
+        if (!request.body) return response.sendStatus(400);
+
+        const characterDirectory = (request.body.avatar_url).replace('.png', '');
+
         const chatsDirectory = path.join(request.user.directories.chats, characterDirectory);
 
         if (!fs.existsSync(chatsDirectory)) {

From 49db89fef030910a121baed415c1f3b62484f3ab Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Wed, 5 Mar 2025 00:57:57 +0200
Subject: [PATCH 7/9] package.json: Fix debug script

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 4df94fa6b..f2594ec93 100644
--- a/package.json
+++ b/package.json
@@ -94,7 +94,7 @@
     "version": "1.12.12",
     "scripts": {
         "start": "node server.js",
-        "debug": "node server.js --inspect",
+        "debug": "node --inspect server.js",
         "start:deno": "deno run --allow-run --allow-net --allow-read --allow-write --allow-sys --allow-env server.js",
         "start:bun": "bun server.js",
         "start:no-csrf": "node server.js --disableCsrf",

From f1b50caf1a0c2362662f3a80b298df2b6d124d02 Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Wed, 5 Mar 2025 09:09:33 +0000
Subject: [PATCH 8/9] Move types/bytes to devDependencies

---
 package-lock.json | 3 ++-
 package.json      | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 24ac745b6..782eaa0d3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,7 +16,6 @@
                 "@iconfu/svg-inject": "^1.2.3",
                 "@mozilla/readability": "^0.5.0",
                 "@popperjs/core": "^2.11.8",
-                "@types/bytes": "^3.1.5",
                 "@zeldafan0225/ai_horde": "^5.2.0",
                 "archiver": "^7.0.1",
                 "bing-translate-api": "^4.0.2",
@@ -85,6 +84,7 @@
             },
             "devDependencies": {
                 "@types/archiver": "^6.0.3",
+                "@types/bytes": "^3.1.5",
                 "@types/command-exists": "^1.2.3",
                 "@types/compression": "^1.7.5",
                 "@types/cookie-parser": "^1.4.8",
@@ -1111,6 +1111,7 @@
             "version": "3.1.5",
             "resolved": "https://registry.npmjs.org/@types/bytes/-/bytes-3.1.5.tgz",
             "integrity": "sha512-VgZkrJckypj85YxEsEavcMmmSOIzkUHqWmM4CCyia5dc54YwsXzJ5uT4fYxBQNEXx+oF1krlhgCbvfubXqZYsQ==",
+            "dev": true,
             "license": "MIT"
         },
         "node_modules/@types/cacheable-request": {
diff --git a/package.json b/package.json
index f2594ec93..01fbf08b6 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,6 @@
         "@iconfu/svg-inject": "^1.2.3",
         "@mozilla/readability": "^0.5.0",
         "@popperjs/core": "^2.11.8",
-        "@types/bytes": "^3.1.5",
         "@zeldafan0225/ai_horde": "^5.2.0",
         "archiver": "^7.0.1",
         "bing-translate-api": "^4.0.2",
@@ -114,6 +113,7 @@
     "main": "server.js",
     "devDependencies": {
         "@types/archiver": "^6.0.3",
+        "@types/bytes": "^3.1.5",
         "@types/command-exists": "^1.2.3",
         "@types/compression": "^1.7.5",
         "@types/cookie-parser": "^1.4.8",

From 858b7503462e190c7a69490b1a62859f1cf6d859 Mon Sep 17 00:00:00 2001
From: Cohee <18619528+Cohee1207@users.noreply.github.com>
Date: Wed, 5 Mar 2025 09:26:16 +0000
Subject: [PATCH 9/9] Document the magic number for future generations

---
 public/scripts/RossAscends-mods.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/public/scripts/RossAscends-mods.js b/public/scripts/RossAscends-mods.js
index fc845fcbc..0a2581e5f 100644
--- a/public/scripts/RossAscends-mods.js
+++ b/public/scripts/RossAscends-mods.js
@@ -316,7 +316,10 @@ export async function favsToHotswap() {
     const entities = getEntitiesList({ doFilter: false });
     const container = $('#right-nav-panel .hotswap');
 
-    const favs = entities.filter(x => x.item.fav || x.item.fav == 'true').slice(0, 25);
+    // Hard limit is required because even if all hotswaps don't fit the screen, their images would still be loaded
+    // 25 is roughly calculated as the maximum number of favs that can fit an ultrawide monitor with the default theme
+    const FAVS_LIMIT = 25;
+    const favs = entities.filter(x => x.item.fav || x.item.fav == 'true').slice(0, FAVS_LIMIT);
 
     //helpful instruction message if no characters are favorited
     if (favs.length == 0) {