cyberia 3.2.5 → 3.2.9

package/src/server/client-build-docs.js

@@ -324,59 +324,56 @@ const buildApiDocs = async ({
 };
 
 /**
- * Builds JSDoc documentation
+ * Builds API documentation using TypeDoc (generates a modern static site from JSDoc-annotated JS).
+ * Config is read from the base typedoc JSON, merged with runtime values, written to a temporary
+ * file, and deleted after the build — the base config file is never mutated on disk.
  * @function buildJsDocs
  * @memberof clientBuildDocs
- * @param {Object} options - JSDoc build options
+ * @param {Object} options - TypeDoc build options
  * @param {string} options.host - The hostname for the documentation
  * @param {string} options.path - The base path for the documentation
  * @param {Object} options.metadata - Metadata for the documentation
- * @param {string} options.publicClientId - Client ID used to resolve the tutorials/references directory
+ * @param {string} options.publicClientId - Client ID used to resolve the references directory
  * @param {Object} options.docs - Documentation config from server conf
- * @param {string} options.docs.jsJsonPath - Path to the JSDoc JSON config file
+ * @param {string} options.docs.jsJsonPath - Path to the base typedoc JSON config file
+ * @param {string} options.docsDestination - Resolved output path for the generated docs
  */
-const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs }) => {
+const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs, docsDestination }) => {
   const logger = loggerFactory(import.meta);
 
-  const jsDocSourcePath = docs.jsJsonPath;
-  if (!fs.existsSync(jsDocSourcePath)) {
-    logger.warn('jsdoc config not found, skipping', jsDocSourcePath);
+  const typedocConfigPath = docs.jsJsonPath;
+  if (!fs.existsSync(typedocConfigPath)) {
+    logger.warn('typedoc config not found, skipping', typedocConfigPath);
     return;
   }
-  const jsDocsConfig = JSON.parse(fs.readFileSync(jsDocSourcePath, 'utf8'));
-  logger.info('using jsdoc config', jsDocSourcePath);
+  const baseConfig = JSON.parse(fs.readFileSync(typedocConfigPath, 'utf8'));
+  logger.info('using typedoc config', typedocConfigPath);
 
-  jsDocsConfig.opts.destination = `./public/${host}${path === '/' ? path : `${path}/`}docs/`;
-  jsDocsConfig.opts.theme_opts.title = metadata?.title ? metadata.title : undefined;
-  jsDocsConfig.opts.theme_opts.favicon = `./public/${host}${path === '/' ? '/' : `${path}/`}favicon.ico`;
-
-  const tutorialsPath = `./src/client/public/${publicClientId}/docs/references`;
+  // Build runtime config in memory — never mutate the base config file
+  // tsconfig must be absolute so TypeDoc resolves it regardless of where the
+  // tmp config file is located on disk.
+  const runtimeConfig = {
+    ...baseConfig,
+    tsconfig: fs.realpathSync(baseConfig.tsconfig || './tsconfig.docs.json'),
+    out: docsDestination,
+    name: metadata?.title || baseConfig.name,
+    favicon: `./public/${host}${path === '/' ? '/' : `${path}/`}favicon.ico`,
+  };
 
+  // Include extra reference documents as TypeDoc document pages
+  // TypeDoc 0.28+: option is `projectDocuments`, not `documents`
   if (Array.isArray(docs.references) && docs.references.length > 0) {
-    fs.mkdirSync(tutorialsPath, { recursive: true });
-    for (const refPath of docs.references) {
-      if (fs.existsSync(refPath)) {
-        const fileName = refPath.split('/').pop();
-        fs.copySync(refPath, `${tutorialsPath}/${fileName}`);
-        logger.info('copied reference to tutorials', refPath);
-      }
-    }
+    runtimeConfig.projectDocuments = docs.references.filter((p) => fs.existsSync(p));
+    if (runtimeConfig.projectDocuments.length > 0) logger.info('typedoc documents', runtimeConfig.projectDocuments);
   }
 
-  if (fs.existsSync(tutorialsPath) && fs.readdirSync(tutorialsPath).length > 0) {
-    jsDocsConfig.opts.tutorials = tutorialsPath;
-    if (jsDocsConfig.opts.theme_opts.sections && !jsDocsConfig.opts.theme_opts.sections.includes('Tutorials')) {
-      jsDocsConfig.opts.theme_opts.sections.push('Tutorials');
-    }
-    logger.info('build jsdoc tutorials', tutorialsPath);
-  } else {
-    delete jsDocsConfig.opts.tutorials;
-  }
+  const tmpConfigPath = `.typedoc.tmp.json`;
+  fs.writeFileSync(tmpConfigPath, JSON.stringify(runtimeConfig, null, 2), 'utf8');
+  logger.warn('build typedoc view', docsDestination);
 
-  fs.writeFileSync(jsDocSourcePath, JSON.stringify(jsDocsConfig, null, 4), 'utf8');
-  logger.warn('build jsdoc view', jsDocsConfig.opts.destination);
+  shellExec(`node_modules/.bin/typedoc --options ${tmpConfigPath}`, { silent: true });
 
-  shellExec(`npx jsdoc -c ${jsDocSourcePath}`, { silent: true });
+  fs.removeSync(tmpConfigPath);
 };
 
 /**
@@ -384,17 +381,13 @@ const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs })
  * @function buildCoverage
  * @memberof clientBuildDocs
  * @param {Object} options - Coverage build options
- * @param {string} options.host - The hostname for the coverage
- * @param {string} options.path - The base path for the coverage
  * @param {Object} options.docs - Documentation config from server conf
- * @param {string} options.docs.coveragePath - Directory where to run npm run coverage
+ * @param {string} options.docs.coveragePath - Directory where coverage reports are generated
+ * @param {string} options.docsDestination - Resolved output path where docs were built
  */
-const buildCoverage = async ({ host, path, docs }) => {
+const buildCoverage = async ({ docs, docsDestination }) => {
   const logger = loggerFactory(import.meta);
-  const jsDocSourcePath = docs.jsJsonPath;
-  const jsDocsConfig = JSON.parse(fs.readFileSync(jsDocSourcePath, 'utf8'));
-  const coveragePath = docs.coveragePath;
-  const coverageOutputDir = docs.coverageOutputDir || 'coverage';
+  const { coveragePath, coverageOutputDir = 'coverage' } = docs;
 
   const coverageOutputPath = `${coveragePath}/coverage`;
   if (!fs.existsSync(coverageOutputPath)) {
@@ -412,7 +405,7 @@ const buildCoverage = async ({ host, path, docs }) => {
   }
 
   if (fs.existsSync(coverageOutputPath) && fs.readdirSync(coverageOutputPath).length > 0) {
-    const coverageBuildPath = `${jsDocsConfig.opts.destination}${coverageOutputDir}`;
+    const coverageBuildPath = `${docsDestination}${coverageOutputDir}`;
     fs.mkdirSync(coverageBuildPath, { recursive: true });
     // Hardhat 3 outputs HTML to coverage/html/; Hardhat 2 / c8 output directly to coverage/
     const coverageHtmlSubdir = `${coverageOutputPath}/html`;
@@ -453,8 +446,14 @@ const buildDocs = async ({
   packageData,
   docs,
 }) => {
-  await buildJsDocs({ host, path, metadata, publicClientId, docs });
-  await buildCoverage({ host, path, docs });
+  const pathPrefix = path === '/' ? '/' : `${path}/`;
+  // TypeDoc output is versioned: served at /docs/engine/{version}/
+  const version = (packageData?.version || '').replace(/^v/, '');
+  const jsDocsDestination = `./public/${host}${pathPrefix}docs/engine/${version}/`;
+  // Coverage output at /docs/coverage/ (or /docs/{coverageOutputDir}/)
+  const coverageBaseDestination = `./public/${host}${pathPrefix}docs/`;
+  await buildJsDocs({ host, path, metadata, publicClientId, docs, docsDestination: jsDocsDestination });
+  await buildCoverage({ docs, docsDestination: coverageBaseDestination });
   await buildApiDocs({
     host,
     path,

package/src/server/client-build.js

@@ -38,6 +38,8 @@ import { ssrFactory } from './ssr.js';
  * @memberof clientBuild
  */
 const copyNonExistingFiles = (src, dest) => {
+  if (dir.basename(src) === '.git') return;
+
   // Ensure source exists
   if (!fs.existsSync(src)) {
     throw new Error(`Source directory does not exist: ${src}`);
@@ -74,6 +76,224 @@ const copyNonExistingFiles = (src, dest) => {
   }
 };
 
+const splitFileByMb = ({ filePath, partSizeMb, logger }) => {
+  const partSizeBytes = Math.floor(Number(partSizeMb) * 1024 * 1024);
+  if (!Number.isFinite(partSizeBytes) || partSizeBytes <= 0) {
+    throw new Error(`Invalid --split value: ${partSizeMb}`);
+  }
+
+  // Clean ALL stale part files (any naming variant) before writing new ones
+  const zipDir = dir.dirname(filePath);
+  const zipBase = dir.basename(filePath);
+  if (fs.existsSync(zipDir)) {
+    fs.readdirSync(zipDir)
+      .filter((name) => name.startsWith(`${zipBase}.part`) || name.startsWith(`${zipBase}-part`))
+      .forEach((name) => fs.removeSync(dir.join(zipDir, name)));
+  }
+
+  const fileBuffer = fs.readFileSync(filePath);
+  const partPaths = [];
+
+  for (let offset = 0, partIndex = 0; offset < fileBuffer.length; offset += partSizeBytes, partIndex++) {
+    const partBuffer = fileBuffer.subarray(offset, offset + partSizeBytes);
+    const partPath = `${filePath}.part${String(partIndex + 1).padStart(3, '0')}`;
+    fs.writeFileSync(partPath, partBuffer);
+    partPaths.push(partPath);
+  }
+
+  logger.warn('split zip', {
+    filePath,
+    partSizeMb: Number(partSizeMb),
+    parts: partPaths.length,
+  });
+
+  return partPaths;
+};
+
+const getZipPartPaths = (zipPath) => {
+  const zipDir = dir.dirname(zipPath);
+  const zipBase = dir.basename(zipPath);
+  const partPrefixDot = `${zipBase}.part`;
+  const partPrefixDash = `${zipBase}-part`;
+
+  const parsePartIndex = (rawSuffix) => {
+    // Strip optional .zip suffix added by pull/download (e.g. '001.zip' → '001')
+    const digits = rawSuffix.replace(/\.zip$/i, '');
+    return /^\d+$/.test(digits) ? Number(digits) : NaN;
+  };
+
+  const getPartIndex = (name) => {
+    if (name.startsWith(partPrefixDot)) return parsePartIndex(name.slice(partPrefixDot.length));
+    if (name.startsWith(partPrefixDash)) return parsePartIndex(name.slice(partPrefixDash.length));
+    return NaN;
+  };
+
+  return fs
+    .readdirSync(zipDir)
+    .filter((name) => Number.isFinite(getPartIndex(name)))
+    .sort((a, b) => getPartIndex(a) - getPartIndex(b))
+    .map((name) => dir.join(zipDir, name));
+};
+
+const resolveClientBuildZip = (buildPrefix) => {
+  const normalizedPrefix = buildPrefix.replace(/\.zip(?:[.-]part\d+|[.-]part\*)?$/, '').replace(/[.-]part\*$/, '');
+  const candidatePrefixes = uniqueArray([
+    normalizedPrefix,
+    normalizedPrefix.endsWith('-') ? normalizedPrefix : `${normalizedPrefix}-`,
+  ]);
+
+  for (const prefix of candidatePrefixes) {
+    const zipPath = `${prefix}.zip`;
+    if (fs.existsSync(zipPath)) {
+      return {
+        buildPrefix: prefix,
+        zipPath,
+        partPaths: [],
+      };
+    }
+
+    const partPaths = fs.existsSync(dir.dirname(zipPath)) ? getZipPartPaths(zipPath) : [];
+    if (partPaths.length > 0) {
+      return {
+        buildPrefix: prefix,
+        zipPath,
+        partPaths,
+      };
+    }
+  }
+
+  const searchDir = dir.dirname(normalizedPrefix);
+  const prefixBase = dir.basename(normalizedPrefix);
+  if (!fs.existsSync(searchDir)) {
+    throw new Error(`Build directory not found: ${searchDir}`);
+  }
+
+  const matches = uniqueArray(
+    fs
+      .readdirSync(searchDir)
+      .filter((name) => name.startsWith(prefixBase) && /\.zip(?:[.-]part\d+)?$/.test(name))
+      .map((name) => name.replace(/[.-]part\d+$/, '')),
+  );
+
+  if (matches.length === 1) {
+    const zipPath = dir.join(searchDir, matches[0]);
+    const partPaths = getZipPartPaths(zipPath);
+    return {
+      buildPrefix: zipPath.replace(/\.zip$/, ''),
+      zipPath,
+      partPaths,
+    };
+  }
+
+  if (matches.length > 1) {
+    throw new Error(
+      `Multiple build zip matches found for '${buildPrefix}': ${matches.join(', ')}. Use a more specific --unzip path.`,
+    );
+  }
+
+  throw new Error(`No build zip or split parts found for: ${buildPrefix}`);
+};
+
+/**
+ * Merges split ZIP parts back into a single ZIP file.
+ * @param {object} options
+ * @param {string} options.buildPrefix - The build prefix path (e.g. build/underpost.net/underpost.net-).
+ * @param {object} options.logger - Logger instance.
+ * @returns {{ zipPath: string, partPaths: string[], mergedBytes: number }}
+ */
+const mergeClientBuildZip = ({ buildPrefix, logger }) => {
+  // Normalize to get the zip path, then look for parts directly (bypassing resolveClientBuildZip
+  // which prefers an existing monolithic zip over parts).
+  const normalizedPrefix = buildPrefix.replace(/\.zip(?:[.-]part\d+)?$/, '').replace(/[-.]$/, '') + '-';
+  const candidatePrefixes = uniqueArray([buildPrefix, buildPrefix.endsWith('-') ? buildPrefix : `${buildPrefix}-`]);
+
+  let zipPath;
+  let partPaths = [];
+
+  for (const prefix of candidatePrefixes) {
+    const candidate = prefix.endsWith('.zip') ? prefix : `${prefix}.zip`;
+    const parts = getZipPartPaths(candidate);
+    if (parts.length > 0) {
+      zipPath = candidate;
+      partPaths = parts;
+      break;
+    }
+  }
+
+  if (partPaths.length === 0) {
+    // Fall back to resolveClientBuildZip for the zipPath
+    const resolved = resolveClientBuildZip(buildPrefix);
+    zipPath = resolved.zipPath;
+    logger.warn('merge-zip: no split parts found, nothing to merge', { buildPrefix, zipPath });
+    return { zipPath, partPaths, mergedBytes: 0 };
+  }
+
+  // For each part, extract raw bytes: if the part file is a Cloudinary wrapper zip
+  // (downloaded via pull without --omit-unzip or with --omit-unzip keeping the .zip),
+  // extract the inner entry rather than using the wrapper bytes.
+  const readPartBytes = (partPath) => {
+    const rawBytes = fs.readFileSync(partPath);
+    // Check for ZIP magic bytes (PK\x03\x04)
+    if (rawBytes[0] === 0x50 && rawBytes[1] === 0x4b && rawBytes[2] === 0x03 && rawBytes[3] === 0x04) {
+      try {
+        const wrapperZip = new AdmZip(rawBytes);
+        const entries = wrapperZip.getEntries();
+        // The inner entry is the original part file (without the outer .zip wrapper)
+        const partBase = dir.basename(partPath).replace(/\.zip$/i, '');
+        const entry = entries.find((e) => e.entryName === partBase || e.entryName.endsWith('/' + partBase));
+        if (entry) {
+          return entry.getData();
+        }
+        // Fallback: single-entry archive
+        if (entries.length === 1) {
+          return entries[0].getData();
+        }
+      } catch (_) {
+        // Not a valid zip or extraction failed — use raw bytes
+      }
+    }
+    return rawBytes;
+  };
+
+  const mergedBuffer = Buffer.concat(partPaths.map(readPartBytes));
+  fs.writeFileSync(zipPath, mergedBuffer);
+
+  logger.warn('merge-zip: merged split parts into zip', {
+    zipPath,
+    parts: partPaths.length,
+    mergedBytes: mergedBuffer.length,
+  });
+
+  return { zipPath, partPaths, mergedBytes: mergedBuffer.length };
+};
+
+const unzipClientBuild = ({ buildPrefix, logger }) => {
+  const { zipPath, partPaths, buildPrefix: resolvedBuildPrefix } = resolveClientBuildZip(buildPrefix);
+  const outputPath = resolvedBuildPrefix.replace(/-$/, '');
+
+  fs.removeSync(outputPath);
+  fs.mkdirSync(outputPath, { recursive: true });
+
+  const zip =
+    partPaths.length > 0
+      ? new AdmZip(Buffer.concat(partPaths.map((partPath) => fs.readFileSync(partPath))))
+      : new AdmZip(zipPath);
+
+  zip.extractAllTo(outputPath, true);
+
+  logger.warn('unzip build', {
+    source: partPaths.length > 0 ? partPaths : [zipPath],
+    outputPath,
+    splitParts: partPaths.length,
+  });
+
+  return {
+    outputPath,
+    zipPath,
+    partPaths,
+  };
+};
+
 /** @type {string} Default XSL sitemap template used when no `sitemap` source file exists in the public directory. */
 const defaultSitemapXsl = `<?xml version="1.0" encoding="UTF-8"?>
 <xsl:stylesheet version="1.0"
@@ -233,6 +453,7 @@ const defaultSitemapXsl = `<?xml version="1.0" encoding="UTF-8"?>
  * @param {Array} options.liveClientBuildPaths - List of paths to build incrementally.
  * @param {Array} options.instances - List of instances to build.
  * @param {boolean} options.buildZip - Whether to create zip files of the builds.
+ * @param {string|number} options.split - Optional zip split size in MB.
  * @param {boolean} options.fullBuild - Whether to perform a full build.
  * @param {boolean} options.iconsBuild - Whether to build icons.
  * @returns {Promise<void>} - Promise that resolves when the build is complete.
@@ -245,6 +466,7 @@ const buildClient = async (
     liveClientBuildPaths: [],
     instances: [],
     buildZip: false,
+    split: '',
     fullBuild: false,
     iconsBuild: false,
   },
@@ -311,35 +533,18 @@ const buildClient = async (
 
     buildAcmeChallengePath(acmeChallengeFullPath);
 
-    if (publicClientId && publicClientId.startsWith('html-website-templates')) {
-      if (!fs.existsSync(`/home/dd/html-website-templates/`))
-        shellExec(`cd /home/dd && git clone https://github.com/designmodo/html-website-templates.git`);
-      if (!fs.existsSync(`${rootClientPath}/index.php`)) {
-        fs.copySync(`/home/dd/html-website-templates/${publicClientId.split('-publicClientId-')[1]}`, rootClientPath);
-        Underpost.repo.initLocalRepo({ path: rootClientPath });
-        shellExec(`cd ${rootClientPath} && git add . && git commit -m "Base template implementation"`);
-        // git remote add origin git@github.com:<username>/<repo>.git
-        fs.writeFileSync(`${rootClientPath}/.git/.htaccess`, `Deny from all`, 'utf8');
-      }
-      return;
-    }
-
     fs.removeSync(rootClientPath);
 
     if (fs.existsSync(`./src/client/public/${publicClientId}`)) {
       if (iconsBuild === true) await buildIcons({ publicClientId, metadata });
 
-      fs.copySync(
-        `./src/client/public/${publicClientId}`,
-        rootClientPath /* {
-            filter: function (name) {
-              console.log(name);
-              return true;
-            },
-          } */,
-      );
+      fs.copySync(`./src/client/public/${publicClientId}`, rootClientPath, {
+        filter: (sourcePath) => !sourcePath.split(dir.sep).includes('.git'),
+      });
     } else if (fs.existsSync(`./engine-private/src/client/public/${publicClientId}`)) {
-      fs.copySync(`./engine-private/src/client/public/${publicClientId}`, rootClientPath);
+      fs.copySync(`./engine-private/src/client/public/${publicClientId}`, rootClientPath, {
+        filter: (sourcePath) => !sourcePath.split(dir.sep).includes('.git'),
+      });
     }
     if (dists)
       for (const dist of dists) {
@@ -463,28 +668,18 @@ const buildClient = async (
         for (const module of services) {
           if (!fs.existsSync(`${rootClientPath}/services/${module}`))
             fs.mkdirSync(`${rootClientPath}/services/${module}`, { recursive: true });
+          const moduleDir = `./src/client/services/${module}`;
+          if (!fs.existsSync(moduleDir)) continue;
 
-          if (fs.existsSync(`./src/client/services/${module}/${module}.service.js`)) {
-            const jsSrcPath = `./src/client/services/${module}/${module}.service.js`;
-            const jsPublicPath = `${rootClientPath}/services/${module}/${module}.service.js`;
-            if (enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath)) continue;
+          const serviceFiles = fs
+            .readdirSync(moduleDir)
+            .filter((name) => name.endsWith('.service.js') || name.endsWith('.management.js'))
+            .sort();
 
-            const jsSrc = await transformClientJs(jsSrcPath, {
-              dists,
-              proxyPath: path,
-              basePath: 'services',
-              module,
-              baseHost,
-              minify: minifyBuild,
-            });
-            fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
-          }
-        }
+          for (const serviceFile of serviceFiles) {
+            const jsSrcPath = `${moduleDir}/${serviceFile}`;
+            const jsPublicPath = `${rootClientPath}/services/${module}/${serviceFile}`;
 
-        for (const module of services) {
-          if (fs.existsSync(`./src/client/services/${module}/${module}.management.js`)) {
-            const jsSrcPath = `./src/client/services/${module}/${module}.management.js`;
-            const jsPublicPath = `${rootClientPath}/services/${module}/${module}.management.js`;
             if (enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath)) continue;
 
             const jsSrc = await transformClientJs(jsSrcPath, {
@@ -497,6 +692,30 @@ const buildClient = async (
             });
             fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
           }
+
+          // Auto-build guest module files when user module is processed
+          if (module === 'user') {
+            const guestModuleDir = './src/client/services/user';
+            const guestServicePath = `${guestModuleDir}/guest.service.js`;
+            if (fs.existsSync(guestServicePath)) {
+              if (!fs.existsSync(`${rootClientPath}/services/user`))
+                fs.mkdirSync(`${rootClientPath}/services/user`, { recursive: true });
+
+              const guestJsPublicPath = `${rootClientPath}/services/user/guest.service.js`;
+
+              if (!enableLiveRebuild || options.liveClientBuildPaths.find((p) => p.srcBuildPath === guestServicePath)) {
+                const guestJsSrc = await transformClientJs(guestServicePath, {
+                  dists,
+                  proxyPath: path,
+                  basePath: 'services',
+                  module: 'user',
+                  baseHost,
+                  minify: minifyBuild,
+                });
+                fs.writeFileSync(guestJsPublicPath, guestJsSrc, 'utf8');
+              }
+            }
+          }
         }
       }
 
@@ -506,14 +725,18 @@ const buildClient = async (
       const Render = await ssrFactory();
 
       if (views) {
-        const jsSrcPath = fs.existsSync(`./src/client/sw/${publicClientId}.sw.js`)
-          ? `./src/client/sw/${publicClientId}.sw.js`
-          : `./src/client/sw/default.sw.js`;
+        const jsSrcPath = `./src/client/sw/core.sw.js`;
 
         const jsPublicPath = `${rootClientPath}/sw.js`;
 
         if (!(enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath))) {
-          const jsSrc = await transformClientJs(jsSrcPath, { dists, proxyPath: path, baseHost, minify: minifyBuild });
+          const jsSrc = await transformClientJs(jsSrcPath, {
+            dists,
+            proxyPath: path,
+            baseHost,
+            minify: minifyBuild,
+            externalizeBareImports: false,
+          });
 
           fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
         }
@@ -746,16 +969,18 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
       if (client) {
         let PRE_CACHED_RESOURCES = [];
 
-        if (views && fs.existsSync(`${rootClientPath}/sw.js`)) {
-          PRE_CACHED_RESOURCES = await fs.readdir(rootClientPath, { recursive: true });
-          PRE_CACHED_RESOURCES = views
-            .map((view) => `${path === '/' ? '' : path}${view.path}`)
-            .concat(
-              PRE_CACHED_RESOURCES.map((p) => `/${p}`).filter(
-                (p) => p[1] !== '.' && !fs.statSync(`${rootClientPath}${p}`).isDirectory(),
-              ),
-            );
-        }
+        const normalizePrecacheRoutePath = (candidatePath) => {
+          const routePath =
+            typeof candidatePath === 'string' && candidatePath.trim().length > 0 ? candidatePath.trim() : '/offline';
+          const withLeadingSlash = routePath.startsWith('/') ? routePath : `/${routePath}`;
+          const withoutTrailingSlash = withLeadingSlash.replace(/\/+$/, '');
+          return withoutTrailingSlash.length > 0 ? withoutTrailingSlash : '/';
+        };
+
+        const toPrecacheIndexUrl = (routePath) => {
+          const normalizedRoutePath = normalizePrecacheRoutePath(routePath);
+          return `${path === '/' ? '' : path}${normalizedRoutePath === '/' ? '' : normalizedRoutePath}/index.html`;
+        };
 
         for (const pageType of ['offline', 'pages']) {
           if (confSSR[getCapVariableName(client)] && confSSR[getCapVariableName(client)][pageType]) {
@@ -783,7 +1008,11 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
                 rootClientPath[rootClientPath.length - 1] === '/' ? rootClientPath.slice(0, -1) : rootClientPath
               }${page.path === '/' ? page.path : `${page.path}/`}`;
 
-              PRE_CACHED_RESOURCES.push(`${path === '/' ? '' : path}${page.path === '/' ? '' : page.path}/index.html`);
+              // Install-time precache is intentionally restricted to SSR offline pages.
+              // All other routes/assets are loaded lazily at runtime.
+              if (pageType === 'offline') {
+                PRE_CACHED_RESOURCES.push(toPrecacheIndexUrl(page.path));
+              }
 
               if (!fs.existsSync(buildPath)) fs.mkdirSync(buildPath, { recursive: true });
 
@@ -809,13 +1038,47 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
         }
 
         {
+          const cacheScope = path === '/' ? 'root' : path.replaceAll('/', '_');
+          const ssrClientConf = confSSR[getCapVariableName(client)] || {};
+          const ssrOfflinePages = Array.isArray(ssrClientConf.offline) ? ssrClientConf.offline : [];
+          const normalizeSsrRoutePath = (candidatePath, fallbackPath) => {
+            const value =
+              typeof candidatePath === 'string' && candidatePath.trim().length > 0
+                ? candidatePath.trim()
+                : fallbackPath;
+            const withLeadingSlash = value.startsWith('/') ? value : `/${value}`;
+            const withoutTrailingSlash = withLeadingSlash.replace(/\/+$/, '');
+            return withoutTrailingSlash.length > 0 ? withoutTrailingSlash : '/';
+          };
+
+          const offlineSsrPage =
+            ssrOfflinePages.find(
+              (page) =>
+                page?.client === 'NoNetworkConnection' ||
+                /no\s*network|offline/i.test(`${page?.title || ''} ${page?.client || ''} ${page?.path || ''}`),
+            ) || ssrOfflinePages[0];
+
+          const maintenanceSsrPage =
+            ssrOfflinePages.find(
+              (page) =>
+                page?.client === 'Maintenance' ||
+                /maintenance/i.test(`${page?.title || ''} ${page?.client || ''} ${page?.path || ''}`),
+            ) || ssrOfflinePages[1];
+
+          const offlinePath = normalizeSsrRoutePath(offlineSsrPage?.path, '/offline');
+          const maintenancePath = normalizeSsrRoutePath(maintenanceSsrPage?.path, '/maintenance');
+
           const renderPayload = {
             PRE_CACHED_RESOURCES: uniqueArray(PRE_CACHED_RESOURCES),
             PROXY_PATH: path,
+            CACHE_PREFIX: `engine-core-v3-${cacheScope}`,
+            OFFLINE_PATH: offlinePath,
+            MAINTENANCE_PATH: maintenancePath,
           };
           fs.writeFileSync(
             `${rootClientPath}/sw.js`,
             `self.renderPayload = ${JSONweb(renderPayload)};
+self.__WB_DISABLE_DEV_LOGS = true;
 ${fs.readFileSync(`${rootClientPath}/sw.js`, 'utf8')}`,
             'utf8',
           );
@@ -838,13 +1101,24 @@ ${fs.readFileSync(`${rootClientPath}/sw.js`, 'utf8')}`,
         }
 
         const buildId = `${host}-${path.replaceAll('/', '')}`;
+        const zipPath = `./build/${buildId}.zip`;
 
-        logger.warn('write zip', `./build/${buildId}.zip`);
+        logger.warn('write zip', zipPath);
 
-        zip.writeZip(`./build/${buildId}.zip`);
+        zip.writeZip(zipPath);
+
+        if (options.split) {
+          splitFileByMb({
+            filePath: zipPath,
+            partSizeMb: options.split,
+            logger,
+          });
+          fs.removeSync(zipPath);
+          logger.warn('removed original zip after split', { zipPath });
+        }
       }
     }
   }
 };
 
-export { buildClient, copyNonExistingFiles };
+export { buildClient, copyNonExistingFiles, unzipClientBuild, mergeClientBuildZip };