@withl5e/l5e 1.0.1 → 1.1.0-alpha.1

package/src/core/chunking.ts

@@ -0,0 +1,256 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import type { CodeSplittingGroup, ModuleInfo, OutputBundle } from 'rolldown';
+
+export interface SharedChunkGroup {
+  name: string;
+  /** Exact package names, including their subpath imports. */
+  packages?: string[];
+  /** Module specifiers resolved by Vite, including aliases. */
+  modules?: string[];
+  priority?: number;
+  /** Approximate uncompressed maximum; not a hard network byte budget. */
+  maxSize?: number;
+}
+
+export interface ChunkingOptions {
+  /**
+   * Opt in to at most one global, one page bundle and one canonical shared file.
+   * State that must retain identity across page bundles must be listed in `shared`.
+   */
+  mode?: 'compact';
+  shared?: SharedChunkGroup[];
+}
+
+export interface CoreViteOptions {
+  /** false leaves chunk placement to Vite; runtime identity protection stays enabled. */
+  chunking?: ChunkingOptions | false;
+}
+
+const normalize = (id: string) => id.replace(/\\/g, '/');
+const digest = (value: string) => createHash('sha256').update(value).digest('hex').slice(0, 8);
+
+/** The last node_modules segment also handles pnpm's nested package layout. */
+function packageName(id: string): string | undefined {
+  const suffix = normalize(id).split('/node_modules/').at(-1);
+  if (suffix === normalize(id)) return undefined;
+  const parts = suffix!.split('/');
+  return parts[0].startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+type Decision = { group: string | null; rule?: string; consumers: string[]; reason: string };
+
+/** One build-time plan drives placement and the diagnostic report. Runtime reads Vite's manifest. */
+export function createChunkPlanner(options: ChunkingOptions = {}) {
+  const rules = options.shared || [];
+  if (options.mode === 'compact' && rules.length > 1) {
+    throw new Error('[l5e chunking] Compact mode accepts one canonical shared group.');
+  }
+  const names = new Set<string>();
+  for (const rule of rules) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(rule.name) || names.has(rule.name)) {
+      throw new Error(`[l5e chunking] Invalid or duplicate shared group: ${rule.name}`);
+    }
+    if (!rule.packages?.length && !rule.modules?.length) {
+      throw new Error(`[l5e chunking] Group ${rule.name} needs packages or modules.`);
+    }
+    if (rule.maxSize !== undefined && (!Number.isFinite(rule.maxSize) || rule.maxSize <= 0)) {
+      throw new Error(`[l5e chunking] Invalid maxSize for ${rule.name}`);
+    }
+    if (options.mode === 'compact' && rule.maxSize !== undefined) {
+      throw new Error(
+        `[l5e chunking] Compact mode cannot use maxSize for ${rule.name}; it would split the canonical shared file.`,
+      );
+    }
+    names.add(rule.name);
+  }
+  let root = '';
+  const resolvedRules = new Map<SharedChunkGroup, Set<string>>();
+  const decisions = new Map<string, Decision>();
+  const warnings = new Set<string>();
+  const portable = (id: string) => {
+    const pkg = packageName(id);
+    if (pkg) return `npm:${normalize(id).split('/node_modules/').at(-1)}`;
+    return normalize(path.relative(root, id));
+  };
+
+  return {
+    async resolve(
+      projectRoot: string,
+      resolveId: (id: string, importer: string) => Promise<string | null>,
+    ) {
+      root = projectRoot;
+      resolvedRules.clear();
+      decisions.clear();
+      warnings.clear();
+      for (const rule of rules) {
+        const ids = new Set<string>();
+        for (const specifier of rule.modules || []) {
+          const id = await resolveId(specifier, path.join(root, 'index.html'));
+          if (!id) throw new Error(`[l5e chunking] Cannot resolve ${specifier} in ${rule.name}`);
+          ids.add(id);
+        }
+        resolvedRules.set(rule, ids);
+      }
+    },
+    analyze(modules: ModuleInfo[]) {
+      decisions.clear();
+      const graph = new Map(modules.map((mod) => [mod.id, mod]));
+      if (options.mode === 'compact') {
+        const reachability = new Map<string, Map<string, boolean>>();
+        for (const entry of modules.filter((mod) => mod.isEntry)) {
+          const visit = (id: string, lazy: boolean) => {
+            const owners = reachability.get(id) || new Map<string, boolean>();
+            const previous = owners.get(entry.id);
+            if (previous === false || previous === lazy) return;
+            owners.set(entry.id, lazy);
+            reachability.set(id, owners);
+            const module = graph.get(id);
+            if (!module) return;
+            module.importedIds.forEach((dependency) => visit(dependency, lazy));
+            module.dynamicallyImportedIds.forEach((dependency) => visit(dependency, true));
+          };
+          visit(entry.id, false);
+        }
+        const globalEntry = modules.find(
+          (mod) => mod.isEntry && normalize(mod.id).endsWith('/src/client.global.ts'),
+        );
+        if (globalEntry) {
+          for (const [id, owners] of reachability) {
+            if (
+              !/\.css(?:\?|$)/.test(normalize(id)) &&
+              owners.get(globalEntry.id) === true &&
+              [...owners.keys()].some((owner) => owner !== globalEntry.id)
+            ) {
+              throw new Error(
+                `[l5e chunking] Compact mode cannot bridge a dynamic-only global overlap: ${portable(id)}. Import it statically from global or place state behind an explicit shared root.`,
+              );
+            }
+          }
+        }
+      }
+      const roots = modules.filter((mod) => mod.isEntry || mod.dynamicImporters.length > 0);
+      const consumers = new Map<string, Set<string>>();
+      for (const entry of roots) {
+        const visited = new Set<string>();
+        const visit = (id: string) => {
+          if (visited.has(id)) return;
+          visited.add(id);
+          const mod = graph.get(id);
+          if (!mod) return;
+          const users = consumers.get(id) || new Set<string>();
+          users.add(entry.id);
+          consumers.set(id, users);
+          mod.importedIds.forEach(visit);
+        };
+        visit(entry.id);
+      }
+      const rank = (id: string) => {
+        const mod = graph.get(id)!;
+        if (!mod.isEntry) return 3;
+        if (normalize(id).endsWith('/src/client.global.ts')) return 0;
+        if (/\/react\//.test(normalize(id)) && !packageName(id)) return 2;
+        return 1;
+      };
+      const matched = new Set<SharedChunkGroup>();
+      for (const mod of modules) {
+        const users = [...(consumers.get(mod.id) || [])].sort();
+        const labels = users.map(portable).sort();
+        const matches = rules
+          .filter(
+            (rule) =>
+              resolvedRules.get(rule)?.has(mod.id) ||
+              rule.packages?.includes(packageName(mod.id) || ''),
+          )
+          .sort((a, b) => (b.priority || 0) - (a.priority || 0));
+        matches.forEach((rule) => matched.add(rule));
+        if (matches.length > 1)
+          warnings.add(
+            `${portable(mod.id)} matches ${matches.map((r) => r.name).join(', ')}; using ${matches[0].name}.`,
+          );
+        let group: string | null = null;
+        let reason = 'Private dependency stays with its entry or dynamic import.';
+        if (!mod.isEntry && users.length && matches.length) {
+          // Explicit groups can combine consumers at the same activation tier.
+          // Never promote island-only code into global/page, or dynamic-only code
+          // into a static entry. Distinct dynamic roots remain separate as well.
+          const tier = Math.min(...users.map(rank));
+          const activation =
+            tier === 3
+              ? `lazy-${digest(JSON.stringify(labels))}`
+              : ['global', 'page', 'island'][tier];
+          group = options.mode === 'compact' ? 'shared' : `shared-${matches[0].name}-${activation}`;
+          reason = `Configured group ${matches[0].name}; activation ${activation}.`;
+        } else if (
+          options.mode === 'compact' &&
+          !mod.isEntry &&
+          users.some((id) => rank(id) === 0) &&
+          users.some((id) => rank(id) > 0)
+        ) {
+          group = 'global-owner';
+          reason = 'Static global/page overlap is exported by the canonical global artifact.';
+        } else if (options.mode !== 'compact' && !mod.isEntry && users.length > 1) {
+          group = `shared-auto-${digest(JSON.stringify(labels))}`;
+          reason = 'Shared by the same static consumers; preserves dynamic import roots.';
+        }
+        decisions.set(mod.id, { group, rule: matches[0]?.name, consumers: labels, reason });
+      }
+      for (const rule of rules) {
+        if (!matched.has(rule))
+          warnings.add(`Group ${rule.name} matched no modules in this client build.`);
+      }
+      return [...warnings];
+    },
+    groups(): CodeSplittingGroup[] {
+      return [
+        ...rules.map((rule) => ({
+          name: (id: string) => {
+            const decision = decisions.get(id);
+            return decision?.rule === rule.name ? decision.group : null;
+          },
+          maxSize: rule.maxSize,
+          includeDependenciesRecursively: options.mode === 'compact',
+        })),
+        {
+          name: (id: string) => decisions.get(id)?.group || null,
+          includeDependenciesRecursively: false,
+        },
+      ];
+    },
+    report(bundle: OutputBundle) {
+      return {
+        version: 2,
+        mode: options.mode || 'default',
+        warnings: [...warnings],
+        chunks: Object.values(bundle).flatMap((chunk) => {
+          if (chunk.type !== 'chunk') return [];
+          const source = chunk.facadeModuleId ? portable(chunk.facadeModuleId) : null;
+          const kind =
+            source === 'src/client.global.ts'
+              ? 'global'
+              : source && /(?:^|\/)react\//.test(source)
+                ? 'island'
+                : chunk.isEntry || chunk.isDynamicEntry
+                  ? 'page'
+                  : 'shared';
+          return [
+            {
+              file: chunk.fileName,
+              kind,
+              canonicalShared: options.mode === 'compact' && chunk.name === 'shared',
+              canonicalGlobal: options.mode === 'compact' && chunk.name === 'global-owner',
+              source,
+              bytes: Buffer.byteLength(chunk.code),
+              imports: chunk.imports,
+              dynamicImports: chunk.dynamicImports,
+              modules: Object.keys(chunk.modules).map((id) => ({
+                id: portable(id),
+                ...decisions.get(id),
+              })),
+            },
+          ];
+        }),
+      };
+    },
+  };
+}

package/src/core/script-bundle-policy.ts

@@ -5,7 +5,22 @@ import type { Manifest } from 'vite';
 import { withAssetBase } from './global-style';
 
 /** Preserve the emitted module boundaries chosen by the application's build. */
-export function createScriptBundlePolicy(manifest: Manifest, distClientDir: string, base = '/') {
+export interface ChunkingReport {
+  mode?: string;
+  chunks?: Array<{
+    file: string;
+    kind: string;
+    canonicalShared?: boolean;
+    canonicalGlobal?: boolean;
+  }>;
+}
+
+export function createScriptBundlePolicy(
+  manifest: Manifest,
+  distClientDir: string,
+  base = '/',
+  report?: ChunkingReport,
+) {
   const directory = path.resolve(distClientDir);
   // Rolldown resolves entry importers through symlinks/junctions. Use the same
   // physical directory for identity while retaining the caller's output scope.
@@ -29,6 +44,17 @@ export function createScriptBundlePolicy(manifest: Manifest, distClientDir: stri
     return absolute;
   }
 
+  const shared = new Set(
+    (report?.chunks || [])
+      .filter((chunk) => report?.mode === 'compact' && chunk.canonicalShared)
+      .map((chunk) => absoluteFile(chunk.file)),
+  );
+  const globalOwned = new Set(
+    (report?.chunks || [])
+      .filter((chunk) => report?.mode === 'compact' && chunk.canonicalGlobal)
+      .map((chunk) => absoluteFile(chunk.file)),
+  );
+
   for (const [key, entry] of jsEntries) {
     const file = absoluteFile(entry.file);
     files.add(file);
@@ -63,15 +89,44 @@ export function createScriptBundlePolicy(manifest: Manifest, distClientDir: stri
 
   return {
     cacheKey,
+    compact: report?.mode === 'compact',
     directory,
     fileForScript(script: string) {
-      const file = absoluteFile(script.replace(/^\/+/, ''));
+      const normalizedBase = base === '/' ? '/' : `/${base.replace(/^\/+|\/+$/g, '')}/`;
+      const relative = script.startsWith(normalizedBase)
+        ? script.slice(normalizedBase.length)
+        : script.replace(/^\/+/, '');
+      const file = absoluteFile(relative);
       if (!files.has(file)) throw new Error(`[bundler] Script is missing from manifest: ${script}`);
       return file;
     },
+    fileForAssetUrl(url: string) {
+      const normalizedBase = base === '/' ? '/' : `/${base.replace(/^\/+|\/+$/g, '')}/`;
+      const relative = url.startsWith(normalizedBase)
+        ? url.slice(normalizedBase.length)
+        : url.replace(/^\/+/, '');
+      const file = absoluteFile(relative);
+      return files.has(file) ? file : undefined;
+    },
     isPreserved(file: string) {
       return preserved.has(file);
     },
+    isShared(file: string) {
+      return shared.has(file);
+    },
+    isGlobalOwned(file: string) {
+      return globalOwned.has(file);
+    },
+    sharedScripts() {
+      return [...shared].map((file) =>
+        withAssetBase(base, path.relative(assetDirectory, file).replace(/\\/g, '/')),
+      );
+    },
+    globalOwnedScripts() {
+      return [...globalOwned].map((file) =>
+        withAssetBase(base, path.relative(assetDirectory, file).replace(/\\/g, '/')),
+      );
+    },
     inlineableRoots(roots: string[]) {
       // External ESM imports execute before any inlined body. Isolate prefix
       // roots in runtime chunks when a later root introduces a dependency effect;

package/src/core/server.ts

@@ -10,7 +10,11 @@ import { createContext, type MiddlewareHandler, type RewritePayload } from '../m
 import { bundleCss, bundleScripts, getBundledFile } from './bundler';
 import type { RenderResult, RequestInfo } from './entry-server';
 import { resolveGlobalStyleHref, withAssetBase } from './global-style';
-import { createScriptBundlePolicy, type ScriptBundlePolicy } from './script-bundle-policy';
+import {
+  createScriptBundlePolicy,
+  type ChunkingReport,
+  type ScriptBundlePolicy,
+} from './script-bundle-policy';
 import type { Manifest } from 'vite';
 import { escapeProp } from './render';
 import { createHeadersFromExpressRequest, parseCookies } from './request';
@@ -281,6 +285,43 @@ async function createPageResponse({
   }
 
   if (isProduction && manifest) {
+    let compactSharedUrl: string | undefined;
+    let compactGlobalUrl: string | undefined;
+    if (scriptPolicy?.compact) {
+      const sharedScripts = scriptPolicy.sharedScripts();
+      if (sharedScripts.length > 1) {
+        throw new Error('[l5e chunking] Compact build has more than one canonical shared root.');
+      }
+      if (sharedScripts.length === 1) {
+        const bundledShared = await bundleScripts(sharedScripts, distClientDir, scriptPolicy, {
+          compact: true,
+          name: 'shared',
+        });
+        if (!bundledShared.filename) {
+          throw new Error('[l5e chunking] Compact shared bundle failed.');
+        }
+        compactSharedUrl = withAssetBase(assetBase, bundledShared.filename);
+      }
+      const compactGlobalEntry = manifest['src/client.global.ts'];
+      if (compactGlobalEntry?.file) {
+        const bundledGlobal = await bundleScripts(
+          [`/${compactGlobalEntry.file}`],
+          distClientDir,
+          scriptPolicy,
+          {
+            compact: true,
+            name: 'global',
+            sharedUrl: compactSharedUrl,
+            exportScripts: scriptPolicy.globalOwnedScripts(),
+          },
+        );
+        if (!bundledGlobal.filename) {
+          throw new Error('[l5e chunking] Compact global bundle failed.');
+        }
+        compactGlobalUrl = withAssetBase(assetBase, bundledGlobal.filename);
+        globalScripts.push(compactGlobalUrl);
+      }
+    }
     scriptSrcList = scriptSrcList.filter(
       (src) => src.replace(/^\//, '') !== 'src/client.global.ts',
     );
@@ -289,28 +330,18 @@ async function createPageResponse({
     const cssFiles = new Set<string>();
     const preloadFiles = new Set<string>();
 
+    const visitedEntries = new Set<string>();
     function collectFromEntry(entryKey: string): { file: string | null } {
       const entry = manifest![entryKey];
       if (!entry) return { file: null };
-
-      if (entry.css) entry.css.forEach((css: string) => cssFiles.add(css));
-      if (entry.imports) {
-        entry.imports.forEach((importKey: string) => {
-          const importedChunk = manifest![importKey];
-          if (importedChunk?.file) preloadFiles.add(importedChunk.file);
-          if (importedChunk?.css) {
-            importedChunk.css.forEach((css: string) => cssFiles.add(css));
-          }
-          if (importedChunk?.imports) {
-            importedChunk.imports.forEach((key: string) => {
-              const chunk = manifest![key];
-              if (chunk?.file) preloadFiles.add(chunk.file);
-              if (chunk?.css) chunk.css.forEach((css: string) => cssFiles.add(css));
-            });
-          }
-        });
+      if (!visitedEntries.has(entryKey)) {
+        visitedEntries.add(entryKey);
+        for (const css of entry.css || []) cssFiles.add(css);
+        for (const key of entry.imports || []) {
+          const dependency = collectFromEntry(key);
+          if (dependency.file) preloadFiles.add(dependency.file);
+        }
       }
-
       return { file: entry.file };
     }
 
@@ -331,21 +362,47 @@ async function createPageResponse({
       }
     }
 
-    if (mappedScripts.length > 0) {
-      const bundledScript = await bundleScripts(mappedScripts, distClientDir, scriptPolicy);
+    if (mappedScripts.length > 0 || (scriptPolicy?.compact && islandEntries.length > 0)) {
+      const compactIslands = scriptPolicy?.compact
+        ? islandEntries.flatMap((island) => {
+            const entry = manifest[island.src];
+            return entry?.file ? [{ key: island.key, script: `/${entry.file}` }] : [];
+          })
+        : [];
+      const compactRenderer = scriptPolicy?.compact
+        ? Object.entries(manifest).find(([key]) => key.includes('l5e-compact-renderer'))?.[1]
+            ?.file
+        : undefined;
+      if (scriptPolicy?.compact && compactIslands.length > 0 && !compactRenderer) {
+        throw new Error('[l5e chunking] Compact renderer entry is missing from the manifest.');
+      }
+      const bundledScript = await bundleScripts(mappedScripts, distClientDir, scriptPolicy, {
+        compact: scriptPolicy?.compact,
+        islands: compactIslands,
+        name: 'bundle',
+        sharedUrl: compactSharedUrl,
+        renderer: compactRenderer ? `/${compactRenderer}` : undefined,
+        globalUrl: compactGlobalUrl,
+      });
       scriptSrcList = bundledScript.filename
         ? [withAssetBase(assetBase, bundledScript.filename)]
         : mappedScripts.map((file) => withAssetBase(assetBase, file));
     }
 
-    if (mappedCssFiles.length > 0) {
-      const bundledCss = await bundleCss(mappedCssFiles, distClientDir);
+    if (cssFiles.size > 0) {
+      const bundledCss = await bundleCss(
+        [...cssFiles].map((file) => `/${file}`),
+        distClientDir,
+      );
       if (bundledCss.filename) {
         cssSrcList = [withAssetBase(assetBase, bundledCss.filename)];
       }
     }
 
+    cssFiles.clear();
     const globalEntry = manifest['src/client.global.ts'];
+    collectFromEntry('src/client.global.ts');
+    for (const cssFile of cssFiles) appendStylesheet(withAssetBase(assetBase, cssFile), true);
     if (globalEntry) {
       if (globalEntry.css && globalEntry.css.length > 0) {
         globalEntry.css.forEach((cssFile: string) => {
@@ -353,11 +410,20 @@ async function createPageResponse({
         });
       }
       if (globalEntry.file) {
-        globalScripts.push(withAssetBase(assetBase, globalEntry.file));
+        if (scriptPolicy?.compact) {
+          // The compact global is built before the page bundle so page imports
+          // can target its live export bridge.
+        } else {
+          globalScripts.push(withAssetBase(assetBase, globalEntry.file));
+        }
       }
     }
 
-    if (islandEntries.length > 0) {
+    for (const file of scriptPolicy?.compact ? [] : preloadFiles) {
+      extraHead += `<link rel="modulepreload" crossorigin href="${escapeProp(withAssetBase(assetBase, file))}">`;
+    }
+
+    if (islandEntries.length > 0 && !scriptPolicy?.compact) {
       const islandMap: Record<string, string> = {};
       for (const island of islandEntries) {
         const entry = manifest[island.src];
@@ -497,7 +563,17 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
   let scriptPolicy: ScriptBundlePolicy | undefined;
   if (productionManifest) {
     try {
-      scriptPolicy = createScriptBundlePolicy(productionManifest, distClientDir, base);
+      let chunkingReport: ChunkingReport | undefined;
+      const reportPath = path.join(distClientDir, '.vite/l5e-chunks.json');
+      if (existsSync(reportPath)) {
+        chunkingReport = JSON.parse(await fs.readFile(reportPath, 'utf-8'));
+      }
+      scriptPolicy = createScriptBundlePolicy(
+        productionManifest,
+        distClientDir,
+        base,
+        chunkingReport,
+      );
     } catch (error) {
       console.warn('[bundler] Invalid build manifest; serving original script entries.', error);
     }
@@ -536,11 +612,16 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
     // Route để serve bundled files từ memory map
     // Đặt route này trước route HTML để catch request trước
     app.get(
-      withAssetBase(base, 'bundle-:hash.:ext'),
+      [
+        withAssetBase(base, 'global-:hash.:ext'),
+        withAssetBase(base, 'bundle-:hash.:ext'),
+        withAssetBase(base, 'shared-:hash.:ext'),
+      ],
       async (req: ExpressRequest, res: ExpressResponse) => {
         try {
           const { hash, ext } = req.params;
-          const filename = `bundle-${hash}.${ext}`;
+          const kind = path.basename(req.path).split('-', 1)[0];
+          const filename = `${kind}-${hash}.${ext}`;
           const bundledFile = getBundledFile(filename);
 
           if (!bundledFile) {