@vacantthinker/firefox-addon-framework-easy 2026.605.1024 → 2026.606.751

package/.prettierrc.json

@@ -0,0 +1,12 @@
+{
+  "semi": true,
+  "trailingComma": "none",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": true,
+  "plugins": [
+    "prettier-plugin-jsdoc"
+  ],
+  "jsdocVerticalAlignment": true,
+  "jsdocLineWrappingStyle": "balance"
+}

package/README.md

@@ -91,9 +91,9 @@ export class DomainORM extends BaseORM {  }
 
 ### 📄 File: `src/generate.js`
 ```javascript
-export function generateHtmlByUserSettings(
-  userSettings,
-  radioItemClickCallback,
+export async function generateHtmlByUserSettings(
+	userSettings,
+	radioItemClickCallback
 ) {  }
 
 export function generateMkvScriptForSystemWindows({  }
@@ -187,7 +187,7 @@ export function serviceGetCurrentDateYYYYMMDDHHMMSS() {  }
 ```javascript
 export async function serviceCopyContentToClipboard(data) {  }
 
-export function serviceSaveContentToLocal(content, filename, ext = 'txt') {  }
+export function serviceSaveContentToLocal(content, filename, ext = "txt") {  }
 
 export async function serviceGenerateMkvToolNixScript({  }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vacantthinker/firefox-addon-framework-easy",
-  "version": "2026.0605.1024",
+  "version": "2026.0606.0751",
   "description": "",
   "main": "index.js",
   "publishConfig": {
@@ -24,21 +24,7 @@
     "@types/firefox-webext-browser": "^143.0.0"
   },
   "devDependencies": {
-    "prettier": "3.8.3",
-    "prettier-plugin-jsdoc": "1.8.1"
-  },
-  "prettier": {
-    "semi": true,
-    "singleQuote": true,
-    "tabWidth": 2,
-    "useTabs": false,
-    "printWidth": 80,
-    "plugins": [
-      "prettier-plugin-jsdoc"
-    ],
-    "jsdocVerticalizeParams": true,
-    "jsdocLineWrappingStyle": "balance",
-    "jsdocPreferToKeepShortOnOneLine": false,
-    "jsdocKeepUnpublished": false
+    "prettier": "^3.8.3",
+    "prettier-plugin-jsdoc": "^1.8.1"
   }
 }

package/src/browserDownload.js

@@ -10,11 +10,14 @@ export async function browserDownloadByDownlink(
     downlink,
     filename = null,
   }) {
-
-  let url = downlink;
-  let options = {url};
-  if (filename) {
-    Object.assign(options, {filename});
-  }
-  await browser.downloads.download(options);
-}
+		let url = downlink;
+		/** @type {browser.downloads._DownloadOptions} */
+		let options = {
+			url,
+			saveAs: false
+		};
+		if (filename) {
+			Object.assign(options, { filename });
+		}
+		await browser.downloads.download(options);
+	}

package/src/generate.js

@@ -1,215 +1,203 @@
-import {stoOpGet, stoOpSet} from './opStorage.js';
+import { stoOpGet, stoOpSet } from "./opStorage.js";
+
+// [Optimization 1] Introduce a debounce function to prevent triggering storage writes on every keystroke.
+function debounce(func, wait) {
+	let timeout;
+	return function (...args) {
+		clearTimeout(timeout);
+		timeout = setTimeout(() => func.apply(this, args), wait);
+	};
+}
 
 /**
  * Generates HTML elements based on a user settings schema object.
  *
- * @param {Object} userSettings
- * @param {Function} radioItemClickCallback
- * @returns {HTMLFieldSetElement[]}
+ * @param   {Object}                    userSettings
+ * @param   {Function}                  radioItemClickCallback
+ * @returns {Promise<DocumentFragment>}
  */
-export function generateHtmlByUserSettings(
-  userSettings,
-  radioItemClickCallback,
+export async function generateHtmlByUserSettings(
+	userSettings,
+	radioItemClickCallback
 ) {
-  // Keeps track of all generated fieldsets by their storageKey
-  const elementsMap = {};
-
-  const fieldsets = Object.keys(userSettings).map((storageKey) => {
-    const storageValue = userSettings[storageKey];
-    const type = storageValue.type || 'text'; // Default to text if type is not specified
-
-    // Common container wrapper for every configuration item
-    const eleWrap = document.createElement('fieldset');
-    const eleTitle = document.createElement('legend');
-    eleTitle.textContent = storageKey;
-    eleWrap.append(eleTitle);
-
-    // Save a reference to the wrapper element for visibility switching
-    elementsMap[storageKey] = eleWrap;
-
-    // --- CONDITION 1: CHECKBOX & RADIO ---
-    if (type === 'checkbox' || type === 'radio') {
-      /**
-       *
-       * @type {string[]}
-       */
-      const options = storageValue.options || [];
-
-      options.map((option) => {
-        const eleLabel = document.createElement('label');
-        eleLabel.textContent = option;
-
-        const eleInput = document.createElement('input');
-        eleInput.name = storageKey;
-        eleInput.type = type;
-        eleInput.value = option;
-
-        if (type === 'checkbox') {
-          stoOpGet(storageKey).then((v) => {
-            const initialArray = Array.from(v || storageValue.selected || []);
-            const set = new Set(initialArray);
-            eleInput.checked = set.has(option);
-
-            // Initial visibility evaluation
-            triggerVisibility(storageKey, initialArray);
-          });
-
-          eleInput.addEventListener('change', async () => {
-            const optionsCurrent = await stoOpGet(storageKey) ||
-              storageValue.selected || [];
-            const set = new Set(Array.from(optionsCurrent));
-
-            if (eleInput.checked) {
-              set.add(option);
-            }
-            else {
-              set.delete(option);
-            }
-
-            const valueNew = Array.from(set);
-            await stoOpSet(storageKey, valueNew);
-
-            // Dynamic visibility update
-            triggerVisibility(storageKey, valueNew);
-          });
-        }
-        else if (type === 'radio') {
-          stoOpGet(storageKey).then((v) => {
-            const currentSelected = (v !== undefined && v !== null) ?
-              v :
-              storageValue.selected;
-            if (option === currentSelected) {
-              eleInput.checked = true;
-            }
-
-            // Initial visibility evaluation
-            triggerVisibility(storageKey, currentSelected);
-          });
-
-          eleLabel.onclick = function () {
-            stoOpSet(storageKey, option).then(() => {
-              if (typeof radioItemClickCallback === 'function') {
-                radioItemClickCallback(storageKey, option);
-              }
-
-              // Dynamic visibility update
-              triggerVisibility(storageKey, option);
-            });
-          };
-        }
-
-        eleLabel.append(eleInput);
-        return eleLabel;
-      }).forEach((ele) => eleWrap.append(ele));
-    }
-
-    // --- CONDITION 2: TOGGLE BUTTON ---
-    else if (type === 'button') {
-      const eleButton = document.createElement('button');
-      eleButton.type = 'button'; // Prevent accidental form submissions
-
-      stoOpGet(storageKey).then((v) => {
-        // Fallback to default schema configuration if no value is stored yet
-        let currentStatus = (v !== undefined && v !== null) ?
-          (v === true || v === 'true') :
-          storageValue.selected;
-        eleButton.textContent = String(currentStatus);
-
-        // Initial visibility evaluation
-        triggerVisibility(storageKey, currentStatus);
-
-        eleButton.addEventListener('click', async () => {
-          currentStatus = !currentStatus; // Toggle state
-          eleButton.textContent = String(currentStatus);
-          await stoOpSet(storageKey, currentStatus);
-
-          // Dynamic visibility update
-          triggerVisibility(storageKey, currentStatus);
-        });
-      });
-
-      eleWrap.append(eleButton);
-    }
-
-    // --- CONDITION 3: NUMBER & TEXT INPUTS ---
-    else if (type === 'number' || type === 'text') {
-      const eleInput = document.createElement('input');
-      eleInput.type = type;
-      eleInput.name = storageKey;
-
-      stoOpGet(storageKey).then((v) => {
-        const currentVal = (v !== undefined && v !== null) ?
-          v :
-          storageValue.selected;
-        eleInput.value = currentVal;
-
-        // Initial visibility evaluation
-        triggerVisibility(storageKey, currentVal);
-      });
-
-      // Updates storage on every keystroke/change execution
-      eleInput.addEventListener('input', async () => {
-        const rawValue = eleInput.value;
-        const finalizedValue = type === 'number' ? Number(rawValue) : rawValue;
-
-        await stoOpSet(storageKey, finalizedValue);
-
-        // Dynamic visibility update
-        triggerVisibility(storageKey, finalizedValue);
-      });
-
-      eleWrap.append(eleInput);
-    }
-
-    // --- CONDITION 4: SPAN / READ-ONLY TEXT ---
-    else if (type === 'span') {
-      const eleSpan = document.createElement('span');
-      // Optional: Add a class for styling read-only text differently
-      // eleSpan.className = 'read-only-text';
-
-      stoOpGet(storageKey).then((v) => {
-        // Fallback to default schema configuration if no value is stored yet
-        const currentVal = (v !== undefined && v !== null) ?
-          v :
-          storageValue.selected;
-
-        // Render as plain text
-        eleSpan.textContent = String(currentVal);
-
-        // Initial visibility evaluation
-        triggerVisibility(storageKey, currentVal);
-      });
-
-      eleWrap.append(eleSpan);
-    }
-
-    return eleWrap;
-  });
-
-  /**
-   * Evaluates the visibility rules for a given source key based on its current value.
-   */
-  function triggerVisibility(sourceKey, currentValue) {
-    const config = userSettings[sourceKey];
-    if (config && config.visibilityControl) {
-      const {targetField, expectedValue} = config.visibilityControl;
-      const targetElement = elementsMap[targetField];
-
-      if (targetElement) {
-        // String conversion guarantees type safety (e.g., matching boolean true against string "true")
-        const shouldBeVisible = String(currentValue) === String(expectedValue);
-        targetElement.style.display = shouldBeVisible ? '' : 'none';
-      }
-    }
-  }
-
-  return fieldsets;
+	const elementsMap = {};
+
+	// [Optimization 2] Use a DocumentFragment for off-screen DOM construction to improve rendering performance.
+	const fragment = document.createDocumentFragment();
+
+	const keys = Object.keys(userSettings);
+
+	// [Optimization 3] Batch fetch all stored values.
+	// Wait for all queries to complete to prevent async callbacks from interrupting the rendering pipeline.
+	const valuesArray = await Promise.all(keys.map((key) => stoOpGet(key)));
+	const storageData = {};
+	keys.forEach((key, index) => {
+		storageData[key] = valuesArray[index];
+	});
+
+	// First pass: Pre-create all container wrappers.
+	// This ensures all target elements exist in the DOM references before executing triggerVisibility later.
+	keys.forEach((storageKey) => {
+		const eleWrap = document.createElement("fieldset");
+		const eleTitle = document.createElement("legend");
+		eleTitle.textContent = storageKey;
+		eleWrap.append(eleTitle);
+
+		elementsMap[storageKey] = eleWrap;
+		fragment.append(eleWrap);
+	});
+
+	// Second pass: Synchronously populate form content and attach event listeners.
+	keys.forEach((storageKey) => {
+		const storageValue = userSettings[storageKey];
+		const type = storageValue.type || "text";
+		const eleWrap = elementsMap[storageKey];
+
+		// Retrieve pre-loaded value; fallback to the schema's default value if undefined.
+		const storedValue = storageData[storageKey];
+		const initialValue =
+			storedValue !== undefined && storedValue !== null
+				? storedValue
+				: storageValue.selected;
+
+		// --- CONDITION 1: CHECKBOX & RADIO ---
+		if (type === "checkbox" || type === "radio") {
+			/** @type {string[]} */
+			const options = storageValue.options || [];
+
+			options.forEach((option) => {
+				const eleLabel = document.createElement("label");
+				eleLabel.textContent = option;
+				const eleInput = document.createElement("input");
+				eleInput.name = storageKey;
+				eleInput.type = type;
+				eleInput.value = option;
+
+				if (type === "checkbox") {
+					const initialArray = Array.from(initialValue || []);
+					const set = new Set(initialArray);
+					eleInput.checked = set.has(option); // Apply state synchronously
+
+					eleInput.addEventListener("change", async () => {
+						// Derive state in real-time from the DOM (faster than reading from storage again)
+						const allCheckboxes = eleWrap.querySelectorAll(
+							'input[type="checkbox"]'
+						);
+						const valueNew = Array.from(allCheckboxes)
+							.filter((cb) => cb.checked)
+							.map((cb) => cb.value);
+
+						await stoOpSet(storageKey, valueNew);
+						triggerVisibility(storageKey, valueNew);
+					});
+				} else if (type === "radio") {
+					if (option === initialValue) {
+						eleInput.checked = true; // Apply state synchronously
+					}
+
+					// It is recommended to bind the 'change' event to the input rather than 'onclick' to the label
+					eleInput.addEventListener("change", () => {
+						stoOpSet(storageKey, option).then(() => {
+							if (typeof radioItemClickCallback === "function") {
+								radioItemClickCallback(storageKey, option);
+							}
+							triggerVisibility(storageKey, option);
+						});
+					});
+				}
+
+				// Fix: Native HTML typically places the input element before the text node inside a label.
+				eleLabel.prepend(eleInput);
+				eleWrap.append(eleLabel);
+			});
+		}
+
+		// --- CONDITION 2: TOGGLE BUTTON ---
+		else if (type === "button") {
+			const eleButton = document.createElement("button");
+			eleButton.type = "button";
+
+			let currentStatus = initialValue === true || initialValue === "true";
+			eleButton.textContent = String(currentStatus); // Apply state synchronously
+
+			eleButton.addEventListener("click", async () => {
+				currentStatus = !currentStatus;
+				eleButton.textContent = String(currentStatus);
+				await stoOpSet(storageKey, currentStatus);
+				triggerVisibility(storageKey, currentStatus);
+			});
+
+			eleWrap.append(eleButton);
+		}
+
+		// --- CONDITION 3: NUMBER & TEXT INPUTS ---
+		else if (type === "number" || type === "text") {
+			const eleInput = document.createElement("input");
+			eleInput.type = type;
+			eleInput.name = storageKey;
+			eleInput.value = initialValue !== undefined ? initialValue : ""; // Apply state synchronously
+
+			// [Optimization 4] Wrap the write operation with debounce, delaying storage writes by 500ms.
+			// This eliminates UI freezing regardless of typing speed.
+			const debouncedSave = debounce(async (val) => {
+				const finalizedValue = type === "number" ? Number(val) : val;
+				await stoOpSet(storageKey, finalizedValue);
+			}, 500);
+
+			eleInput.addEventListener("input", () => {
+				const rawValue = eleInput.value;
+				debouncedSave(rawValue);
+				triggerVisibility(storageKey, rawValue); // Visual UI updates do not require a delay
+			});
+
+			eleWrap.append(eleInput);
+		}
+
+		// --- CONDITION 4: SPAN / READ-ONLY TEXT ---
+		else if (type === "span") {
+			const eleSpan = document.createElement("span");
+			eleSpan.textContent = String(initialValue); // Apply state synchronously
+			eleWrap.append(eleSpan);
+		}
+	});
+
+	// [Optimization 5] Third pass: Globally trigger a single visibility check.
+	// At this point, all DOM elements exist and all initialValues are fully derived,
+	// preventing undefined errors or invalid target hiding.
+	keys.forEach((storageKey) => {
+		const storedValue = storageData[storageKey];
+		const initialValue =
+			storedValue !== undefined && storedValue !== null
+				? storedValue
+				: userSettings[storageKey].selected;
+
+		triggerVisibility(storageKey, initialValue);
+	});
+
+	/**
+	 * Evaluates the visibility rules for a given source key based on its current
+	 * value.
+	 */
+	function triggerVisibility(sourceKey, currentValue) {
+		const config = userSettings[sourceKey];
+		if (config && config.visibilityControl) {
+			const { targetField, expectedValue } = config.visibilityControl;
+			const targetElement = elementsMap[targetField];
+
+			if (targetElement) {
+				const shouldBeVisible = String(currentValue) === String(expectedValue);
+				targetElement.style.display = shouldBeVisible ? "" : "none";
+			}
+		}
+	}
+
+	return fragment;
 }
 
-export function generateMkvScriptForSystemWindows({vid, title}) {
-  let args = {vid, title};
+export function generateMkvScriptForSystemWindows({ vid, title }) {
+	let args = { vid, title };
 
-  return `if (true) {
+	return `if (true) {
   const path = require('path');
   const fs = require('fs');
   const {execSync, exec} = require('node:child_process');
@@ -294,11 +282,11 @@ export function generateMkvScriptForSystemWindows({vid, title}) {
   `;
 }
 
-export function generateMkvScriptForSystemFedora({vid, title}) {
-  let args = {vid, title};
+export function generateMkvScriptForSystemFedora({ vid, title }) {
+	let args = { vid, title };
 
-  // We wrap the Node.js script inside a Linux Shell script block
-  return `#!/usr/bin/env bash
+	// We wrap the Node.js script inside a Linux Shell script block
+	return `#!/usr/bin/env bash
 # This header tells Fedora to treat this file as a runnable bash script
 
 # Open a terminal window if not already running inside one
@@ -373,4 +361,3 @@ read unused_input
 rm -- "$0"
 `;
 }
-

package/src/serviceOpContent.js

@@ -1,80 +1,82 @@
-import {browserRuntimePlatformInfo} from './browserRuntime.js';
-import {generateMkvScriptForSystemFedora, generateMkvScriptForSystemWindows,} from './generate.js';
+import { browserRuntimePlatformInfo } from "./browserRuntime.js";
+import {
+	generateMkvScriptForSystemFedora,
+	generateMkvScriptForSystemWindows
+} from "./generate.js";
 
 /**
- *
- * @param data
+ * @param   data
  * @returns {Promise<void>}
  */
 export async function serviceCopyContentToClipboard(data) {
-  return await window.navigator.clipboard.writeText(data);
+	return await window.navigator.clipboard.writeText(data);
 }
 
 /**
- * eg: fnName('this is content', 'this is a filename without ext', 'txt')
+ * Eg: fnName('this is content', 'this is a filename without ext', 'txt')
+ *
  * @param {string} content
- * @param {string} filename eg: abc
- * @param {string} ext txt json
+ * @param {string} filename Eg: abc
+ * @param {string} ext      Txt json
  */
-export function serviceSaveContentToLocal(content, filename, ext = 'txt') {
-  const eleBtn = document.createElement('button');
-  eleBtn.addEventListener(
-    'click',
-    function () {
-      const eleA = document.createElement('a');
+export function serviceSaveContentToLocal(content, filename, ext = "txt") {
+	const eleBtn = document.createElement("button");
+	eleBtn.addEventListener(
+		"click",
+		function () {
+			const eleA = document.createElement("a");
 
-      const extObj = {
-        txt: 'text/plain',
-        json: 'application/json',
-      };
-      const type = extObj[ext];
+			const extObj = {
+				txt: "text/plain",
+				json: "application/json"
+			};
+			const type = extObj[ext];
 
-      const file = new Blob([content], {type});
-      eleA.href = URL.createObjectURL(file);
-      eleA.download = [filename, ext].join('.');
-      eleA.click();
-      URL.revokeObjectURL(eleA.href);
-    },
-    false,
-  );
-  eleBtn.click();
-  // eleBtn.previousElementSibling
+			const file = new Blob([content], { type });
+			eleA.href = URL.createObjectURL(file);
+			eleA.download = [filename, ext].join(".");
+			eleA.click();
+			URL.revokeObjectURL(eleA.href);
+		},
+		false
+	);
+	eleBtn.click();
+	// eleBtn.previousElementSibling
 }
 
 /**
- * need install nodejs mkvtoolnix
- * @param message{{
- *      vid, title,
- * }}
+ * Need install nodejs mkvtoolnix
+ *
+ * @param   message{{               Vid, title,
+ *   }}
  * @returns {Promise<void>}
  */
-export async function serviceGenerateMkvToolNixScript({vid, title}) {
-  let message = {vid, title};
-  const platformInfo = await browserRuntimePlatformInfo();
-  if (platformInfo.os === 'win') {
-    let content = generateMkvScriptForSystemWindows(message);
-    serviceSaveContentToLocal(content, title, 'js');
-  }
-  else if (platformInfo.os === 'linux') {
-    let content = generateMkvScriptForSystemFedora(message);
-    serviceSaveContentToLocal(content, title, 'sh');
-  }
+export async function serviceGenerateMkvToolNixScript({ vid, title }) {
+	let message = { vid, title };
+	const platformInfo = await browserRuntimePlatformInfo();
+	if (platformInfo.os === "win") {
+		let content = generateMkvScriptForSystemWindows(message);
+		serviceSaveContentToLocal(content, title, "js");
+	} else if (platformInfo.os === "linux") {
+		let content = generateMkvScriptForSystemFedora(message);
+		serviceSaveContentToLocal(content, title, "sh");
+	}
 }
 
 /**
- * @param {string} value -
- * @returns {string} -
+ * @param   {string} value -
+ * @returns {string}       -
  */
 export function serviceRemoveIllegalWord(value) {
-  if (!value) return '';
+	if (!value) return "";
 
-  let name = value.trim().split(/\r?\n/).shift();
+	let name = value.trim().split(/\r?\n/).shift();
 
-  name = name.replace(/[\p{P}\p{S}\p{C}]/gu, ' ');
+	name = name.replace(/[\p{P}\p{S}\p{C}]/gu, " ");
 
-  name = name.replace(/[~"#%&*:<>?/\\{|}]/g, ' ');
+	name = name.replace(/[~"#%&*:<>?/\\{|}]/g, " ");
 
-  name = name.replace(/[\s\u3000]+/g, ' ').trim();
+	name = name.replace(/[\s\u3000]+/g, " ").trim();
 
-  return name.replace(/^[-.]+|[-.]+$/g, '');
-}
+	return name.replace(/^[-.]+|[-.]+$/g, "");
+}

package/src/serviceOpJavascript.js

@@ -109,8 +109,7 @@ export async function serviceElementPicker(message) {
             selector += '#' + el.id;
             path.unshift(selector);
             break;
-          }
-          else {
+          } else {
             let sib = el, nth = 1;
             while (sib = sib.previousElementSibling) {
               if (sib.nodeName.toLowerCase() === selector) nth++;
@@ -330,16 +329,13 @@ export async function serviceDealWithMagnetLink(message) {
 
     if (handleOption === 'clipboard') {
       await serviceCopyContentToClipboard(content);
-    }
-    else if (handleOption === 'txt') {
+    } else if (handleOption === 'txt') {
       serviceSaveContentToLocal(content, filename);
-    }
-    else if (handleOption === 'clipboardAndTxt') {
+    } else if (handleOption === 'clipboardAndTxt') {
       await serviceCopyContentToClipboard(content);
       serviceSaveContentToLocal(content, filename);
     }
-  }
-  else {
+  } else {
     // todo notification => magnet link not found!
     await browserNotificationCreate('magnet link not found!');
   }