tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/webTemplates/vite/7.3/plugins/TinyVitePwaPlugin.d.mts

@@ -0,0 +1,67 @@
+export type TinyWebWorkerConfig = {
+    /**
+     * - The source file path for the Web Worker (e.g., 'src/workers/myWorker.mjs').
+     */
+    entry: string;
+    /**
+     * - The output filename for the Web Worker (e.g., 'myWorker.js').
+     */
+    filename: string;
+};
+export type TinyVitePwaOptions = {
+    /**
+     * - The Web App Manifest object.
+     */
+    manifest: Record<any, any>;
+    /**
+     * - The URL path where the manifest should be served.
+     */
+    manifestPath: string;
+    /**
+     * - The source directory containing the Service Worker.
+     */
+    srcDir: string;
+    /**
+     * - The name of the Service Worker file.
+     */
+    filename: string;
+    /**
+     * - Optional. Whether to automatically inject the SW registration script into the HTML <head>.
+     */
+    injectRegister?: boolean;
+    /**
+     * - Optional. Whether to inject the manifest into the global scope via Vite's `define`.
+     */
+    injectManifestToGlobal?: boolean;
+    /**
+     * - Optional. Registration options for the Service Worker.
+     */
+    swRegistrationOptions?: RegistrationOptions;
+    /**
+     * - Optional. A list of Web Workers to be bundled and served alongside the PWA.
+     */
+    webWorkers?: TinyWebWorkerConfig[];
+};
+/**
+ * Custom PWA Plugin.
+ * Resolves Manifest, Dev HMR, Service Worker, and multiple Web Workers bundling.
+ *
+ * NOTE: The Service Worker and Web Worker files are always served from the root directory of the website.
+ *
+ * TypeScript Support: To enable IntelliSense and avoid type errors when using
+ * the injected '__TINY_PWA_MANIFEST__' global variable, add the following to your `env.d.ts` file:
+ *
+ * ```typescript
+ * declare global {
+ *   interface Window {
+ *     __TINY_PWA_MANIFEST__: Record<string, any>;
+ *   }
+ * }
+ * ```
+ *
+ * @param {TinyVitePwaOptions} options - The configuration options for the plugin.
+ * @returns {import('vite').Plugin} The Vite plugin object.
+ */
+declare const TinyVitePwaPlugin: (options: TinyVitePwaOptions) => import('vite').Plugin;
+export default TinyVitePwaPlugin;
+//# sourceMappingURL=TinyVitePwaPlugin.d.mts.map

package/dist/v1/webTemplates/vite/7.3/plugins/TinyVitePwaPlugin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyVitePwaPlugin.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/webTemplates/vite/7.3/plugins/TinyVitePwaPlugin.mjs"],"names":[],"mappings":"AAIG,YAAkB,mBAAmB,GACrC;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACnB;CAAA,CAAA;AAGE,YAAkB,kBAAkB,GACpC;;;;IAA6B,QAAQ,EAA1B,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAC3B;;;;IAAmB,YAAY,EAApB,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAqB,cAAc,AAAnC,CACA,EADW,OAAO,CAClB;;;;IAAqB,sBAAsB,AAA3C,CACA,EADW,OAAO,CAClB;;;;IAAiC,qBAAqB,AAAtD,CACA,EADW,mBAAmB,CAC9B;;;;IAAmC,UAAU,AAA7C,CACF,EADa,mBAAmB,EAAE,CAClC;CAAA,CAAA;AAmCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAA,MAAM,iBAAiB,YAHZ,kBAAkB,KAChB,OAAO,MAAM,EAAE,MAia3B,CAAC;eAEa,iBAAiB"}

package/dist/v1/webTemplates/vite/7.3/plugins/TinyVitePwaPlugin.mjs

@@ -0,0 +1,399 @@
+import { resolve, relative } from 'path';
+import { build } from 'vite';
+/**
+ * @typedef {Object} TinyWebWorkerConfig
+ * @property {string} entry - The source file path for the Web Worker (e.g., 'src/workers/myWorker.mjs').
+ * @property {string} filename - The output filename for the Web Worker (e.g., 'myWorker.js').
+ */
+/**
+ * @typedef {Object} TinyVitePwaOptions
+ * @property {Record<any, any>} manifest - The Web App Manifest object.
+ * @property {string} manifestPath - The URL path where the manifest should be served.
+ * @property {string} srcDir - The source directory containing the Service Worker.
+ * @property {string} filename - The name of the Service Worker file.
+ * @property {boolean} [injectRegister=true] - Optional. Whether to automatically inject the SW registration script into the HTML <head>.
+ * @property {boolean} [injectManifestToGlobal=true] - Optional. Whether to inject the manifest into the global scope via Vite's `define`.
+ * @property {RegistrationOptions} [swRegistrationOptions] - Optional. Registration options for the Service Worker.
+ * @property {TinyWebWorkerConfig[]} [webWorkers] - Optional. A list of Web Workers to be bundled and served alongside the PWA.
+ */
+// ANSI Color Codes
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+};
+/**
+ * Internal logger to maintain consistent plugin output formatting using ANSI colors.
+ */
+const logger = {
+    prefix: `${colors.cyan}[tiny-vite-pwa]${colors.reset}`,
+    info: (/** @type {string} */ msg) => console.log(`${logger.prefix} ${colors.blue}[INFO]${colors.reset} ${msg}`),
+    success: (/** @type {string} */ msg) => console.log(`${logger.prefix} ${colors.green}[SUCCESS]${colors.reset} ${msg}${colors.reset}`),
+    warn: (/** @type {string} */ msg) => console.warn(`${logger.prefix} ${colors.yellow}[WARN]${colors.reset} ${msg}${colors.reset}`),
+    error: (/** @type {string} */ msg, /** @type {Error} */ err) => console.error(`${logger.prefix} ${colors.red}[ERROR]${colors.reset} ${msg}${colors.reset}`, err || ''),
+    log: (/** @type {string} */ msg) => console.log(msg),
+    dim: (/** @type {string} */ msg) => console.log(`${colors.dim}${msg}${colors.reset}`),
+};
+/**
+ * Custom PWA Plugin.
+ * Resolves Manifest, Dev HMR, Service Worker, and multiple Web Workers bundling.
+ *
+ * NOTE: The Service Worker and Web Worker files are always served from the root directory of the website.
+ *
+ * TypeScript Support: To enable IntelliSense and avoid type errors when using
+ * the injected '__TINY_PWA_MANIFEST__' global variable, add the following to your `env.d.ts` file:
+ *
+ * ```typescript
+ * declare global {
+ *   interface Window {
+ *     __TINY_PWA_MANIFEST__: Record<string, any>;
+ *   }
+ * }
+ * ```
+ *
+ * @param {TinyVitePwaOptions} options - The configuration options for the plugin.
+ * @returns {import('vite').Plugin} The Vite plugin object.
+ */
+const TinyVitePwaPlugin = (options) => {
+    // --- Strict Runtime Validation ---
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError('The "options" argument must be a non-null object.');
+    }
+    if (typeof options.manifest !== 'object' || options.manifest === null) {
+        throw new TypeError('The "manifest" property must be an object.');
+    }
+    if (typeof options.manifestPath !== 'string') {
+        throw new TypeError('The "manifestPath" property must be a string.');
+    }
+    if (typeof options.srcDir !== 'string') {
+        throw new TypeError('The "srcDir" property must be a string.');
+    }
+    if (typeof options.filename !== 'string') {
+        throw new TypeError('The "filename" property must be a string.');
+    }
+    if (options.injectRegister !== undefined && typeof options.injectRegister !== 'boolean') {
+        throw new TypeError('The "injectRegister" property must be a boolean.');
+    }
+    if (options.injectManifestToGlobal !== undefined &&
+        typeof options.injectManifestToGlobal !== 'boolean') {
+        throw new TypeError('The "injectManifestToGlobal" property must be a boolean.');
+    }
+    if (options.swRegistrationOptions !== undefined &&
+        (typeof options.swRegistrationOptions !== 'object' ||
+            options.swRegistrationOptions === null ||
+            Array.isArray(options.swRegistrationOptions))) {
+        throw new TypeError('The "swRegistrationOptions" property must be an object.');
+    }
+    const filenamePattern = /^[a-zA-Z0-9._-]+$/;
+    if (!filenamePattern.test(options.filename)) {
+        throw new RangeError('The "filename" property contains invalid characters. To prevent injection, only alphanumeric characters, dots (.), underscores (_), and hyphens (-) are allowed.');
+    }
+    // Validate Web Workers Array if provided
+    if (options.webWorkers !== undefined) {
+        if (!Array.isArray(options.webWorkers)) {
+            throw new TypeError('The "webWorkers" property must be an array.');
+        }
+        options.webWorkers.forEach((ww, index) => {
+            if (typeof ww !== 'object' || ww === null) {
+                throw new TypeError(`webWorkers[${index}] must be a non-null object.`);
+            }
+            if (typeof ww.entry !== 'string') {
+                throw new TypeError(`webWorkers[${index}].entry must be a string.`);
+            }
+            if (typeof ww.filename !== 'string') {
+                throw new TypeError(`webWorkers[${index}].filename must be a string.`);
+            }
+            if (!filenamePattern.test(ww.filename)) {
+                throw new RangeError(`webWorkers[${index}].filename contains invalid characters.`);
+            }
+        });
+    }
+    const { manifest, manifestPath, srcDir, filename, swRegistrationOptions, webWorkers = [], } = options;
+    const injectRegister = options.injectRegister ?? true;
+    const injectManifestToGlobal = options.injectManifestToGlobal ?? true;
+    /** @type {string} */
+    let swSourcePath;
+    /** @type {Array<{ entryPath: string, filename: string }>} */
+    let resolvedWebWorkers = [];
+    /** @type {import('vite').ResolvedConfig} */
+    let viteConfig;
+    return {
+        name: 'tiny-vite-pwa',
+        // Capture Vite configuration to use during build mode
+        configResolved(config) {
+            viteConfig = config;
+            swSourcePath = resolve(config.root, srcDir, filename);
+            // Resolve absolute paths for Web Workers
+            resolvedWebWorkers = webWorkers.map((ww) => ({
+                entryPath: resolve(config.root, ww.entry, ww.filename),
+                filename: ww.filename,
+            }));
+        },
+        config(config) {
+            const define = { ...config.define };
+            if (injectManifestToGlobal)
+                define.__TINY_PWA_MANIFEST__ = JSON.stringify(manifest);
+            return { ...config, define };
+        },
+        // REQUIREMENTS 1 & 4 (DEV Mode): Serve the manifest, Service Worker, and Web Workers
+        configureServer(server) {
+            // Extract server info to build a clickable URL
+            const serverConfig = server.config.server || {};
+            let host = serverConfig.host;
+            if (host === true) {
+                host = '0.0.0.0';
+            }
+            else if (typeof host !== 'string') {
+                host = 'localhost';
+            }
+            const port = serverConfig.port;
+            const isHttps = serverConfig.https ? true : false;
+            const protocol = isHttps ? 'https' : 'http';
+            // If host is 0.0.0.0, use localhost so the link is clickable in the terminal
+            const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+            const baseUrl = `${protocol}://${displayHost}:${port}`;
+            const normalizedManifestPath = manifestPath.startsWith('/')
+                ? manifestPath
+                : `/${manifestPath}`;
+            const swUrl = `/${filename}`;
+            server.middlewares.use(async (req, res, next) => {
+                // We parse the incoming request URL to extract only the pathname.
+                // This ensures that requests with query parameters (e.g., /sw.js?v=123)
+                // are correctly matched to the file paths.
+                const requestUrl = new URL(req.url ?? '', 'http://localhost');
+                const pathname = requestUrl.pathname;
+                // Serve manifest.json dynamically
+                if (pathname === normalizedManifestPath) {
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify(manifest, null, 2));
+                    return;
+                }
+                // Serve the Service Worker in Dev mode using Vite's transformer
+                if (pathname === swUrl) {
+                    try {
+                        const transformed = await server.transformRequest(swSourcePath);
+                        if (transformed) {
+                            res.setHeader('Content-Type', 'application/javascript');
+                            res.end(transformed.code);
+                            return;
+                        }
+                    }
+                    catch (e) {
+                        logger.error('Error transforming the SW in dev:', e instanceof Error ? e : new Error('Unknown Error'));
+                    }
+                }
+                // Serve Web Workers in Dev mode
+                for (const ww of resolvedWebWorkers) {
+                    if (pathname === `/${ww.filename}`) {
+                        try {
+                            const transformed = await server.transformRequest(ww.entryPath);
+                            if (transformed) {
+                                res.setHeader('Content-Type', 'application/javascript');
+                                res.end(transformed.code);
+                                return;
+                            }
+                        }
+                        catch (e) {
+                            logger.error(`Error transforming Web Worker (${ww.filename}) in dev:`, e instanceof Error ? e : new Error('Unknown Error'));
+                        }
+                    }
+                }
+                next();
+            });
+            logger.success(`Manifest available at: ${baseUrl}${normalizedManifestPath}`);
+            logger.success(`Service Worker available at: ${baseUrl}${swUrl}`);
+            resolvedWebWorkers.forEach((ww) => {
+                logger.success(`Web Worker available at: ${baseUrl}/${ww.filename}`);
+            });
+            logger.warn(`NOTE: If your Service Worker implements client-side routing, ensure it is configured to bypass interception for the manifest, SW, and WW files.`);
+        },
+        // REQUIREMENT 3: Monitor SW and WW changes and notify the frontend
+        handleHotUpdate({ file, server }) {
+            // Check for Service Worker updates
+            if (file.startsWith(resolve(viteConfig.root, srcDir))) {
+                logger.info('Service Worker change detected. Notifying frontend...');
+                // Send a custom event via Vite's WebSocket
+                server.ws.send({
+                    type: 'custom',
+                    event: 'pwa:sw-updated',
+                    data: { message: 'The Service Worker file has been changed.' },
+                });
+                // Return an empty array so Vite does not attempt a full page reload automatically
+                return [];
+            }
+            // Check for Web Worker updates
+            for (const ww of resolvedWebWorkers) {
+                if (file === ww.entryPath) {
+                    logger.info(`Web Worker change detected (${ww.filename}). Notifying frontend...`);
+                    server.ws.send({
+                        type: 'custom',
+                        event: 'pwa:ww-updated',
+                        data: {
+                            message: `The Web Worker file ${ww.filename} has been changed.`,
+                            filename: ww.filename,
+                        },
+                    });
+                    return [];
+                }
+            }
+        },
+        // INJECT HTML SCRIPT: Inject the SW registration code and the Manifest link into the output HTML
+        transformIndexHtml() {
+            // In production mode, we append a timestamp to the URL to force cache busting.
+            // In development mode, we omit the timestamp to avoid generating unnecessary logs on every reload.
+            const isBuild = viteConfig && viteConfig.command === 'build';
+            /**
+             * Safely appends a cache-busting timestamp to a URL string.
+             * @param {string} urlStr - The base URL path.
+             * @returns {string} The URL path with the 'v' parameter appended correctly.
+             */
+            const getVersionedUrl = (urlStr) => {
+                // We use a dummy base ('http://localhost') because the URL constructor
+                // requires an absolute URL to parse relative paths correctly.
+                const url = new URL(urlStr, 'http://localhost');
+                // .set() is smart: it uses '?' if no params exist, or '&' if they do.
+                url.searchParams.set('v', Date.now().toString());
+                // We return only the pathname and search (e.g., "/sw.js?v=123")
+                // to keep the injection relative for the HTML.
+                return url.pathname + url.search;
+            };
+            const swUrl = getVersionedUrl(`/${filename}`);
+            // Prepare the manifest URL with cache busting for production
+            const normalizedManifestHref = manifestPath.startsWith('/')
+                ? manifestPath
+                : `/${manifestPath}`;
+            const manifestUrl = getVersionedUrl(normalizedManifestHref);
+            /** @type {import('vite').HtmlTagDescriptor[]} */
+            const insertData = [];
+            // Manifest
+            logger.info(`Injecting Manifest into HTML: ${manifestUrl}`);
+            insertData.push({
+                tag: 'link',
+                injectTo: 'head',
+                attrs: {
+                    rel: 'manifest',
+                    href: manifestUrl,
+                },
+            });
+            // SW
+            if (injectRegister) {
+                logger.info(`Injecting Service Worker into HTML: ${swUrl}`);
+                // Prepare the registration options string safely using JSON.stringify
+                // If no options are provided, swOptionsString remains an empty string.
+                const swOptionsString = swRegistrationOptions
+                    ? `, ${JSON.stringify(swRegistrationOptions)}`
+                    : '';
+                insertData.push({
+                    tag: 'script',
+                    injectTo: 'head',
+                    children: `
+          if ('serviceWorker' in navigator) { 
+            window.addEventListener('load', () => { 
+              navigator.serviceWorker.register('${swUrl}'${swOptionsString})${!isBuild ? `.then(() => console.log('[tiny-vite-pwa] SW registered.')).catch(err => console.error('[tiny-vite-pwa] SW error:', err))` : ''}; 
+            }); 
+          };`
+                        .replace(/\n/g, '')
+                        .replace(/  /g, '')
+                        .trim(),
+                });
+            }
+            return insertData;
+        },
+        // REQUIREMENT 1 (PROD Mode): Save the manifest to the dist directory
+        generateBundle() {
+            // Remove the leading slash from the path to prevent Rollup errors
+            const emitPath = manifestPath.replace(/^\//, '');
+            this.emitFile({
+                type: 'asset',
+                fileName: emitPath,
+                source: JSON.stringify(manifest),
+            });
+        },
+        // REQUIREMENT 4 (PROD Mode): Bundle the Service Worker and Web Workers separately
+        async closeBundle() {
+            // Only run this during the build command (production)
+            if (viteConfig.command === 'build') {
+                const projectRoot = viteConfig.root || process.cwd();
+                logger.dim('--------------------------------------------------');
+                logger.log(` Mode:       ${colors.bright}${viteConfig.mode}${colors.reset}`);
+                // --- Build Service Worker ---
+                const relativeSourceSW = relative(projectRoot, swSourcePath);
+                const relativeDestSW = relative(projectRoot, resolve(viteConfig.build.outDir, filename));
+                const manifestDestPath = resolve(viteConfig.build.outDir, manifestPath.replace(/^\//, ''));
+                const relativeDestManifest = relative(projectRoot, manifestDestPath);
+                logger.info('Initiating Service Worker bundling process...');
+                // Manifest Info
+                logger.log(` Manifest:   ${colors.cyan}${relativeDestManifest}${colors.reset}`);
+                // Service Worker Info
+                logger.log(` SW Source:  ${colors.cyan}${relativeSourceSW}${colors.reset}`);
+                logger.log(` SW Dest:    ${colors.cyan}${relativeDestSW}${colors.reset}`);
+                try {
+                    await build({
+                        configFile: false, // Ignore the main vite.config.js to prevent infinite loops
+                        mode: viteConfig.mode,
+                        build: {
+                            outDir: viteConfig.build.outDir,
+                            emptyOutDir: false, // IMPORTANT: Do not delete the React build that was just completed
+                            lib: {
+                                entry: swSourcePath,
+                                name: 'ServiceWorker',
+                                formats: ['iife'], // IIFE bundles all imports into a single file (classic SW standard)
+                                fileName: () => filename,
+                            },
+                            rollupOptions: {
+                                // Ensures no hashes are added to the SW filename
+                                output: { entryFileNames: filename },
+                            },
+                        },
+                    });
+                    logger.success('Service Worker bundled successfully.');
+                }
+                catch (e) {
+                    logger.error('Failed to bundle the Service Worker.', e instanceof Error ? e : new Error('Unknown Error'));
+                }
+                // --- Build Web Workers ---
+                if (resolvedWebWorkers.length > 0) {
+                    logger.dim('--------------------------------------------------');
+                    logger.info('Initiating Web Workers bundling process...');
+                    for (const ww of resolvedWebWorkers) {
+                        const relativeSourceWW = relative(projectRoot, ww.entryPath);
+                        const relativeDestWW = relative(projectRoot, resolve(viteConfig.build.outDir, ww.filename));
+                        logger.log(` WW Source:  ${colors.cyan}${relativeSourceWW}${colors.reset}`);
+                        logger.log(` WW Dest:    ${colors.cyan}${relativeDestWW}${colors.reset}`);
+                        try {
+                            await build({
+                                configFile: false,
+                                mode: viteConfig.mode,
+                                build: {
+                                    outDir: viteConfig.build.outDir,
+                                    emptyOutDir: false,
+                                    lib: {
+                                        entry: ww.entryPath,
+                                        name: ww.filename.replace(/\.[^/.]+$/, ''),
+                                        formats: ['iife'],
+                                        fileName: () => ww.filename,
+                                    },
+                                    rollupOptions: {
+                                        output: { entryFileNames: ww.filename },
+                                    },
+                                },
+                            });
+                            logger.success(`Web Worker (${ww.filename}) bundled successfully.`);
+                        }
+                        catch (e) {
+                            logger.error(`Failed to bundle the Web Worker (${ww.filename}).`, e instanceof Error ? e : new Error('Unknown Error'));
+                        }
+                    }
+                }
+                logger.dim('--------------------------------------------------');
+            }
+        },
+    };
+};
+export default TinyVitePwaPlugin;

package/dist/v1/webTemplates/vite/7.3/plugins/githubUtils.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+var path = require('path');
+var fs = require('fs');
+
+/**
+ * Plugin to copy index.html to 404.html for GitHub Pages compatibility.
+ * @returns {import('vite').Plugin}
+ */
+const CopyIndexToGithub404 = () => {
+  /**
+   * Variable to store the output directory captured from Vite
+   * @type {string}
+   */
+  let outDir;
+
+  return {
+    name: 'github-copy-index-to-404',
+    // Capture Vite configuration to know the actual output directory
+    configResolved(config) {
+      outDir = config.build.outDir;
+    },
+    closeBundle() {
+      if (!outDir) return;
+      const indexPath = path.resolve(outDir, 'index.html');
+      const targetPath = path.resolve(outDir, '404.html');
+
+      if (fs.existsSync(indexPath)) {
+        fs.copyFileSync(indexPath, targetPath);
+      }
+    },
+  };
+};
+
+exports.CopyIndexToGithub404 = CopyIndexToGithub404;

package/dist/v1/webTemplates/vite/7.3/plugins/githubUtils.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Plugin to copy index.html to 404.html for GitHub Pages compatibility.
+ * @returns {import('vite').Plugin}
+ */
+export declare const CopyIndexToGithub404: () => import('vite').Plugin;
+//# sourceMappingURL=githubUtils.d.mts.map

package/dist/v1/webTemplates/vite/7.3/plugins/githubUtils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubUtils.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/webTemplates/vite/7.3/plugins/githubUtils.mjs"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAFpB,OAAO,MAAM,EAAE,MAyB3B,CAAC"}

package/dist/v1/webTemplates/vite/7.3/plugins/githubUtils.mjs

@@ -0,0 +1,29 @@
+import { resolve } from 'path';
+import { existsSync, copyFileSync } from 'fs';
+/**
+ * Plugin to copy index.html to 404.html for GitHub Pages compatibility.
+ * @returns {import('vite').Plugin}
+ */
+export const CopyIndexToGithub404 = () => {
+    /**
+     * Variable to store the output directory captured from Vite
+     * @type {string}
+     */
+    let outDir;
+    return {
+        name: 'github-copy-index-to-404',
+        // Capture Vite configuration to know the actual output directory
+        configResolved(config) {
+            outDir = config.build.outDir;
+        },
+        closeBundle() {
+            if (!outDir)
+                return;
+            const indexPath = resolve(outDir, 'index.html');
+            const targetPath = resolve(outDir, '404.html');
+            if (existsSync(indexPath)) {
+                copyFileSync(indexPath, targetPath);
+            }
+        },
+    };
+};

package/docs/info/RegExp.md

@@ -0,0 +1,74 @@
+# JavaScript RegExp: Reuse vs. Re-instantiation
+
+This document serves as a guide for professional developers on when it is efficient and safe to reuse a `RegExp` object in JavaScript, and when doing so can lead to critical bugs.
+
+## 1. When to Reuse a RegExp
+
+Reusing a `RegExp` object (storing it in a `const` outside of a function or loop) is a best practice in several scenarios.
+
+### A. Static Patterns (Single Source of Truth)
+If you have a pattern that never changes, such as an email validation pattern, a phone number format, or a specific error code format, you should define it once.
+*   **Why:** It ensures consistency across your entire application. If the validation rule changes, you only update it in one location.
+
+### B. Performance Optimization (Pre-compilation)
+When you define a regex using the literal syntax (e.g., `/pattern/`) or the `new RegExp()` constructor, the JavaScript engine must compile that pattern into an internal format.
+*   **Why:** If you are performing a regex operation inside a loop that runs thousands of times, defining the regex *inside* the loop forces the engine to re-compile the pattern on every iteration. Defining it *outside* the loop performs the compilation only once.
+
+### Example: Efficient Reuse
+```javascript
+// GOOD: Compiled once, reused many times
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function validateEmails(emailList) {
+  return emailList.map(email => EMAIL_PATTERN.test(email));
+}
+```
+
+---
+
+## 2. When NEVER to Reuse a RegExp
+
+There are specific technical reasons why reusing a regex can cause your application to fail.
+
+### A. The `lastIndex` Trap (Stateful Regex)
+This is the most critical reason to avoid reuse. When a `RegExp` has the global (`g`) or sticky (`y`) flag, it becomes **stateful**. It maintains a property called `lastIndex`, which tracks the position where the next match should begin.
+
+*   **The Problem:** If you use `.test()` or `.exec()` on a global regex, the `lastIndex` is updated after every match. If you reuse that same regex instance later, it will start searching from the *previous* position rather than the beginning of the string, often leading to false negatives.
+
+### Example: The `lastIndex` Bug
+```javascript
+// BAD: Reusing a global regex leads to unpredictable results
+const SEARCH_PATTERN = /abc/g;
+const str = "abcabc";
+
+console.log(SEARCH_PATTERN.test(str)); // true (lastIndex is now 3)
+console.log(SEARCH_PATTERN.test(str)); // false! (Starts searching at index 3, finds nothing)
+
+// FIX: Either do not use the 'g' flag if you only need to test once, 
+// or reset the index manually:
+SEARCH_PATTERN.lastIndex = 0; 
+console.log(SEARCH_PATTERN.test(str)); // true
+```
+
+### B. Dynamic Patterns
+If the pattern itself depends on a variable (e.g., searching for a user-provided string), you cannot use a static constant.
+*   **Why:** A constant is immutable. If the search criteria change, you must instantiate a new `RegExp` using the `new RegExp(patternString)` constructor.
+
+### Example: Dynamic Pattern
+```javascript
+// GOOD: Creating a new instance because the pattern changes
+function findUser(userName) {
+  // We must create a new instance because 'userName' is dynamic
+  const dynamicPattern = new RegExp(userName, 'i'); 
+  return dynamicPattern.test(currentData);
+}
+```
+
+## Summary Table
+
+| Scenario | Action | Reason |
+| :--- | :--- | :--- |
+| **Static Pattern (e.g., Email)** | **Reuse** | Consistency and Performance. |
+| **Inside a Loop (Static Pattern)** | **Reuse** | Avoids repeated compilation overhead. |
+| **Regex with `g` or `y` flags** | **Avoid Reuse** | Prevents `lastIndex` state bugs. |
+| **Pattern depends on variables** | **Do Not Reuse** | The pattern is not constant. |