@withl5e/l5e 1.1.0-alpha.0 → 1.1.0-alpha.2

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.
@@ -13,6 +28,7 @@ export function createScriptBundlePolicy(manifest: Manifest, distClientDir: stri
   const files = new Set<string>();
   const preserved = new Set<string>();
   const staticImports = new Map<string, string[]>();
+  const lazy = new Set<string>();
   const jsEntries = Object.entries(manifest).filter(([, entry]) => /\.[cm]?js$/.test(entry.file));
 
   function absoluteFile(file: string) {
@@ -29,6 +45,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);
@@ -57,21 +84,91 @@ export function createScriptBundlePolicy(manifest: Manifest, distClientDir: stri
     );
   }
 
+
+  // A runtime page bundle keeps dynamic roots and their static closure as emitted
+  // assets. This preserves download/init boundaries while allowing the page's
+  // transformed preload helper to start the known closure in parallel.
+  const staticallyInitial = new Set<string>();
+  const visitInitial = (key: string) => {
+    const entry = manifest[key];
+    if (!entry || !/\.[cm]?js$/.test(entry.file)) return;
+    const file = absoluteFile(entry.file);
+    if (staticallyInitial.has(file)) return;
+    staticallyInitial.add(file);
+    for (const dependency of entry.imports || []) visitInitial(dependency);
+  };
+  for (const [key, entry] of jsEntries) {
+    if (entry.isEntry && !entry.isDynamicEntry) visitInitial(key);
+  }
+  const visitLazy = (key: string) => {
+    const entry = manifest[key];
+    if (!entry || !/\.[cm]?js$/.test(entry.file)) return;
+    const file = absoluteFile(entry.file);
+    if (lazy.has(file) || staticallyInitial.has(file)) return;
+    lazy.add(file);
+    for (const dependency of entry.imports || []) visitLazy(dependency);
+  };
+  for (const [, entry] of jsEntries) {
+    for (const key of entry.dynamicImports || []) visitLazy(key);
+  }
+
   const cacheKey = createHash('sha256')
     .update(JSON.stringify([directory, assetDirectory, base, manifest]))
     .digest('hex');
 
   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);
+    },
+    isLazy(file: string) {
+      return lazy.has(file);
+    },
+    staticClosure(roots: string[]) {
+      const closure = new Set<string>();
+      const visit = (file: string) => {
+        if (closure.has(file)) return;
+        closure.add(file);
+        for (const dependency of staticImports.get(file) || []) visit(dependency);
+      };
+      roots.forEach(visit);
+      return closure;
+    },
+    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,55 @@ 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);
+      }
+      const imports: Record<string, string> = {};
+      if (compactSharedUrl) {
+        for (const original of sharedScripts) imports[original] = compactSharedUrl;
+      }
+      if (compactGlobalUrl) {
+        for (const original of scriptPolicy.globalOwnedScripts()) {
+          imports[original] = compactGlobalUrl;
+        }
+      }
+      if (Object.keys(imports).length > 0) {
+        extraHead += `<script type="importmap">${serialize({ imports })}</script>`;
+      }
+    }
     scriptSrcList = scriptSrcList.filter(
       (src) => src.replace(/^\//, '') !== 'src/client.global.ts',
     );
@@ -304,6 +357,28 @@ async function createPageResponse({
       return { file: entry.file };
     }
 
+    function activationPlan(entryKeys: string[], excluded = new Set<string>()) {
+      const js = new Set<string>();
+      const css = new Set<string>();
+      const visited = new Set<string>();
+      const visit = (entryKey: string) => {
+        if (visited.has(entryKey)) return;
+        visited.add(entryKey);
+        const entry = manifest![entryKey];
+        if (!entry) return;
+        for (const file of entry.css || []) css.add(withAssetBase(assetBase, file));
+        if (!excluded.has(entryKey) && entry.file && /\.[cm]?js$/.test(entry.file)) {
+          const absolute = scriptPolicy!.fileForScript(`/${entry.file}`);
+          if (!scriptPolicy!.isShared(absolute) && !scriptPolicy!.isGlobalOwned(absolute)) {
+            js.add(withAssetBase(assetBase, entry.file));
+          }
+        }
+        for (const dependency of entry.imports || []) visit(dependency);
+      };
+      entryKeys.forEach(visit);
+      return { js: [...js], css: [...css] };
+    }
+
     const mappedScripts: string[] = [];
     for (const src of scriptSrcList) {
       const entryKey = src.replace(/^\//, '');
@@ -322,12 +397,97 @@ async function createPageResponse({
     }
 
     if (mappedScripts.length > 0) {
-      const bundledScript = await bundleScripts(mappedScripts, distClientDir, scriptPolicy);
+      const bundledScript = await bundleScripts(mappedScripts, distClientDir, scriptPolicy, {
+        compact: scriptPolicy?.compact,
+        name: 'bundle',
+        sharedUrl: compactSharedUrl,
+        globalUrl: compactGlobalUrl,
+      });
       scriptSrcList = bundledScript.filename
         ? [withAssetBase(assetBase, bundledScript.filename)]
         : mappedScripts.map((file) => withAssetBase(assetBase, file));
     }
 
+    if (scriptPolicy?.compact && islandEntries.length > 0) {
+      const rendererEntry = Object.entries(manifest).find(
+        ([key, entry]) => entry.isEntry && key.includes('l5e-compact-renderer'),
+      );
+      if (!rendererEntry?.[1].file) {
+        throw new Error('[l5e chunking] Compact renderer entry is missing from the manifest.');
+      }
+      const rendererOwnedKeys = new Set<string>();
+      rendererOwnedKeys.add(rendererEntry[0]);
+      const rendererDependencies = (rendererEntry[1].imports || []).filter((dependency: string) =>
+        manifest[dependency]?.file?.includes('compact-renderer'),
+      );
+      if (rendererDependencies.length !== 1) {
+        throw new Error(
+          `[l5e chunking] Compact renderer expected one canonical export chunk; found ${rendererDependencies.length}. Multiple chunks can have colliding emitted export aliases.`,
+        );
+      }
+      rendererOwnedKeys.add(rendererDependencies[0]);
+      const bundledRenderer = await bundleScripts(
+        [`/${rendererEntry[1].file}`],
+        distClientDir,
+        scriptPolicy,
+        {
+          compact: true,
+          name: 'renderer',
+          sharedUrl: compactSharedUrl,
+          globalUrl: compactGlobalUrl,
+          inlineStaticRootClosure: true,
+          exportScripts: [...rendererOwnedKeys]
+            .filter((key) => key !== rendererEntry[0])
+            .map((key) => `/${manifest[key].file}`),
+        },
+      );
+      if (!bundledRenderer.filename) {
+        throw new Error('[l5e chunking] Compact renderer bundle failed.');
+      }
+      const rendererUrl = withAssetBase(assetBase, bundledRenderer.filename);
+      const rendererAliases = Object.fromEntries(
+        [...rendererOwnedKeys]
+          .filter((key) => manifest[key]?.file)
+          .map((key) => [`/${manifest[key].file}`, rendererUrl]),
+      );
+      const rendererImports = Object.fromEntries(
+        [...rendererOwnedKeys]
+          .filter((key) => manifest[key]?.file)
+          .map((key) => [withAssetBase(assetBase, manifest[key].file), rendererUrl]),
+      );
+      if (Object.keys(rendererImports).length > 0) {
+        extraHead += `<script type="importmap">${serialize({ imports: rendererImports })}</script>`;
+      }
+      const islandMap: Record<
+        string,
+        { module: string; renderer: string; js: string[]; css: string[] }
+      > = {};
+      for (const island of islandEntries) {
+        const entry = manifest[island.src];
+        if (!entry?.file) continue;
+        const bundledIsland = await bundleScripts([`/${entry.file}`], distClientDir, scriptPolicy, {
+          compact: true,
+          name: 'island',
+          sharedUrl: compactSharedUrl,
+          globalUrl: compactGlobalUrl,
+          inlineStaticRootClosure: true,
+          externalScripts: rendererAliases,
+        });
+        if (!bundledIsland.filename) {
+          throw new Error(`[l5e chunking] Compact island bundle failed: ${island.src}`);
+        }
+        const islandUrl = withAssetBase(assetBase, bundledIsland.filename);
+        const plan = activationPlan([island.src], rendererOwnedKeys);
+        islandMap[island.key] = {
+          module: islandUrl,
+          renderer: rendererUrl,
+          js: [rendererUrl, islandUrl],
+          css: plan.css,
+        };
+      }
+      islandRegistryScript = `<script>Object.assign(window.__L5E_ISLANDS__||={},${serialize(islandMap)});window.__L5E_BOOT_ISLANDS__?.()</script>`;
+    }
+
     if (cssFiles.size > 0) {
       const bundledCss = await bundleCss(
         [...cssFiles].map((file) => `/${file}`),
@@ -349,15 +509,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));
+        }
       }
     }
 
-    for (const file of preloadFiles) {
+    for (const file of scriptPolicy?.compact ? [] : preloadFiles) {
       extraHead += `<link rel="modulepreload" crossorigin href="${escapeProp(withAssetBase(assetBase, file))}">`;
     }
 
-    if (islandEntries.length > 0) {
+    if (islandEntries.length > 0 && !scriptPolicy?.compact) {
       const islandMap: Record<string, string> = {};
       for (const island of islandEntries) {
         const entry = manifest[island.src];
@@ -497,7 +662,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 +711,18 @@ 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'),
+        withAssetBase(base, 'renderer-:hash.:ext'),
+        withAssetBase(base, 'island-: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) {

package/src/core/vite-plugin.ts

@@ -20,6 +20,7 @@ const VIRTUAL_L5E_SSR_ENTRY = 'virtual:l5e-ssr-entry';
 const VIRTUAL_L5E_GLOBAL_LOADER = 'virtual:l5e-global-loader';
 const VIRTUAL_L5E_ISLAND_STRATEGIES = 'virtual:l5e-island-strategies';
 const VIRTUAL_L5E_ISLANDS = 'virtual:l5e-islands';
+const VIRTUAL_L5E_COMPACT_RENDERER = 'virtual:l5e-compact-renderer';
 const VIRTUAL_L5E_ACTIONS = 'virtual:l5e-actions';
 const VIRTUAL_L5E_MIDDLEWARE = 'virtual:l5e-middleware';
 
@@ -575,9 +576,28 @@ export function coreVite(options: CoreViteOptions = {}): Plugin {
         typeof existingInput === 'object' && !Array.isArray(existingInput)
           ? { ...discovered.input, ...existingInput }
           : discovered.input;
+      if (options.chunking && options.chunking.mode === 'compact') {
+        mergedInput['l5e-compact-renderer'] = VIRTUAL_L5E_COMPACT_RENDERER;
+      }
 
       return {
         build: {
+          ...(options.chunking && options.chunking.mode === 'compact'
+            ? {
+                modulePreload: {
+                  resolveDependencies: (
+                    _filename: string,
+                    dependencies: string[],
+                    context: { hostType: 'html' | 'js' },
+                  ) =>
+                    context.hostType === 'html'
+                      ? dependencies.filter(
+                          (dependency) => !/\.[cm]?js(?:\?|$)/.test(dependency),
+                        )
+                      : dependencies,
+                },
+              }
+            : {}),
           rolldownOptions: {
             ...userConfig.build?.rolldownOptions,
             input: Object.keys(mergedInput).length > 0 ? mergedInput : undefined,
@@ -604,6 +624,10 @@ export function coreVite(options: CoreViteOptions = {}): Plugin {
                     chunkFileNames: (chunk) =>
                       chunk.name.startsWith('shared-')
                         ? 'assets/[name]-[hash].js'
+                        : chunk.name === 'shared'
+                          ? 'assets/shared-[hash].js'
+                          : chunk.name === 'lazy-react-runtime'
+                            ? 'assets/lazy-react-runtime-[hash].js'
                         : chunk.isDynamicEntry
                           ? 'assets/bundle-[name]-[hash].js'
                           : 'assets/shared-[name]-[hash].js',
@@ -634,6 +658,9 @@ export function coreVite(options: CoreViteOptions = {}): Plugin {
       if (id === VIRTUAL_L5E_ISLANDS) {
         return '\0' + VIRTUAL_L5E_ISLANDS;
       }
+      if (id === VIRTUAL_L5E_COMPACT_RENDERER) {
+        return '\0' + VIRTUAL_L5E_COMPACT_RENDERER;
+      }
       if (id === VIRTUAL_L5E_ACTIONS) {
         return '\0' + VIRTUAL_L5E_ACTIONS;
       }
@@ -643,18 +670,18 @@ export function coreVite(options: CoreViteOptions = {}): Plugin {
       return null;
     },
 
-    async transform(code, id, options) {
+    async transform(code, id, transformOptions) {
       // Auto-inject island runtime into client.global.ts so it's always loaded globally
-      if (id.replace(/\\/g, '/').endsWith('src/client.global.ts') && !options?.ssr) {
+      if (id.replace(/\\/g, '/').endsWith('src/client.global.ts') && !transformOptions?.ssr) {
         return {
-          code: `import '@withl5e/l5e/island/runtime';\n${code}`,
+          code: `import '@withl5e/l5e/island/${options.chunking && options.chunking.mode === 'compact' ? 'compact-runtime' : 'runtime'}';\n${code}`,
           map: null,
         };
       }
 
       // Client-side action transform: replace defineAction exports with fetch stubs
       // Supports actions anywhere under src/ (e.g., src/views/*, src/features/*, etc.)
-      if (!options?.ssr) {
+      if (!transformOptions?.ssr) {
         const normalizedId = id.replace(/\\/g, '/');
         const actionMatch = normalizedId.match(/\/src\/(.+)\/actions\.(ts|tsx)$/);
         if (actionMatch) {
@@ -752,7 +779,7 @@ export function coreVite(options: CoreViteOptions = {}): Plugin {
       // Server side có thể access tất cả env variables
       // Client side chỉ access được VITE_ env variables
       // Transform này chạy ở runtime khi module được load trong SSR context
-      if (options?.ssr) {
+      if (transformOptions?.ssr) {
         let transformedCode = code;
         let hasChanges = false;
 
@@ -882,6 +909,9 @@ export async function loadMiddleware() {
       if (id === '\0' + VIRTUAL_L5E_ISLANDS) {
         return `export const islandModules = import.meta.glob('/src/**/react/*.{tsx,jsx}');`;
       }
+      if (id === '\0' + VIRTUAL_L5E_COMPACT_RENDERER) {
+        return `export * as reactDomClient from 'react-dom/client'; export { createElement } from 'react';`;
+      }
 
       // Virtual module: l5e-island-strategies
       if (id === '\0' + VIRTUAL_L5E_ISLAND_STRATEGIES) {

package/src/island/compact-runtime.ts

@@ -0,0 +1,158 @@
+import type { IslandMeta } from './types';
+import { strategies, registerMountStrategy } from './strategy-registry';
+
+registerMountStrategy('load', (mount) => void mount());
+registerMountStrategy('idle', (mount) => {
+  if ('requestIdleCallback' in window) requestIdleCallback(() => mount());
+  else setTimeout(() => mount(), 200);
+});
+registerMountStrategy('visible', (mount, opts, el) => {
+  const observer = new IntersectionObserver(
+    (entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        observer.disconnect();
+        mount();
+      }
+    },
+    { rootMargin: opts || '200px' },
+  );
+  observer.observe(el);
+  return () => observer.disconnect();
+});
+registerMountStrategy('media', (mount, opts) => {
+  if (!opts) {
+    console.error('[l5e-island] Strategy "media" requires mountOpts (media query)');
+    return;
+  }
+  const query = window.matchMedia(opts);
+  if (query.matches) mount();
+  else {
+    const handler = (event: MediaQueryListEvent) => event.matches && mount();
+    query.addEventListener('change', handler, { once: true });
+    return () => query.removeEventListener('change', handler);
+  }
+});
+registerMountStrategy('none', () => {});
+
+import 'virtual:l5e-island-strategies';
+
+type CompactIslandModule = {
+  reactDomClient: typeof import('react-dom/client');
+  createElement: typeof import('react').createElement;
+  module: Record<string, any>;
+};
+type CompactIslandPlan = { module: string; renderer: string; js: string[]; css: string[] };
+const registry: Record<string, CompactIslandPlan> = ((window as any).__L5E_ISLANDS__ ||= {});
+let islandData: unknown[] | null = null;
+const scheduled = new WeakSet<Element>();
+
+function props(element: Element): Record<string, unknown> {
+  const index = element.getAttribute('data-island-idx');
+  if (index === null) return JSON.parse(element.getAttribute('data-island-props') || '{}');
+  if (!islandData) {
+    const store = document.getElementById('_l5e_data_');
+    try {
+      const parsed = JSON.parse(store?.textContent || '[]');
+      islandData = Array.isArray(parsed) ? parsed : [];
+    } catch (error) {
+      console.error('[l5e-island] Failed to parse _l5e_data_ props store:', error);
+      islandData = [];
+    }
+  }
+  return (islandData[Number(index)] as Record<string, unknown>) || {};
+}
+
+function discover(): IslandMeta[] {
+  return Array.from(document.querySelectorAll('[data-island]')).map((element) => ({
+    element: element as HTMLElement,
+    registryKey: element.getAttribute('data-island')!,
+    exportName: element.getAttribute('data-island-name')!,
+    props: props(element),
+    mount: element.getAttribute('data-island-mount') || 'load',
+    mountOpts: element.getAttribute('data-island-opts') || undefined,
+    ssr: element.hasAttribute('data-island-ssr'),
+  }));
+}
+
+function mount(island: IslandMeta) {
+  let mounted = false;
+  return async () => {
+    if (mounted) return;
+    mounted = true;
+    const plan = registry[island.registryKey];
+    if (!plan) {
+      console.error(`[l5e-island] Component "${island.registryKey}" not found in page registry.`);
+      return;
+    }
+    try {
+      // Schedule the complete known static closure before awaiting any response.
+      // Modulepreload fetches without evaluating; native import retains ESM order.
+      for (const href of plan.js) {
+        if (document.querySelector(`link[rel="modulepreload"][href="${CSS.escape(href)}"]`))
+          continue;
+        const link = document.createElement('link');
+        link.rel = 'modulepreload';
+        link.crossOrigin = 'anonymous';
+        link.href = href;
+        document.head.append(link);
+      }
+      await Promise.all(
+        plan.css.map(
+          (href) =>
+            new Promise<void>((resolve, reject) => {
+              const existing = document.querySelector<HTMLLinkElement>(
+                `link[rel="stylesheet"][href="${CSS.escape(href)}"]`,
+              );
+              if (existing?.sheet) return resolve();
+              const link = existing || document.createElement('link');
+              link.rel = 'stylesheet';
+              link.crossOrigin = 'anonymous';
+              link.href = href;
+              link.addEventListener('load', () => resolve(), { once: true });
+              link.addEventListener('error', () => reject(new Error(`Failed to load ${href}`)), {
+                once: true,
+              });
+              if (!existing) document.head.append(link);
+            }),
+        ),
+      );
+      const [renderer, module] = await Promise.all([
+        import(/* @vite-ignore */ plan.renderer),
+        import(/* @vite-ignore */ plan.module),
+      ]);
+      const { reactDomClient, createElement } = renderer as Omit<
+        CompactIslandModule,
+        'module'
+      >;
+      const Component = module.default || module[island.exportName];
+      if (!Component) throw new Error(`No export "default" or "${island.exportName}" in module`);
+      if (island.ssr) {
+        reactDomClient.hydrateRoot(island.element, createElement(Component, island.props));
+      } else {
+        const root = reactDomClient.createRoot(island.element);
+        root.render(createElement(Component, island.props));
+      }
+    } catch (error) {
+      console.error(`[l5e-island] Failed to mount "${island.registryKey}":`, error);
+    }
+  };
+}
+
+function boot() {
+  for (const island of discover()) {
+    if (scheduled.has(island.element)) continue;
+    // A fragment swap can expose an element before its activation plan is installed.
+    if (!registry[island.registryKey]) continue;
+    const strategy = strategies.get(island.mount);
+    if (!strategy) {
+      console.error(`[l5e-island] Strategy "${island.mount}" not found.`);
+      continue;
+    }
+    scheduled.add(island.element);
+    strategy(mount(island), island.mountOpts, island.element);
+  }
+}
+
+(globalThis as any).__L5E_BOOT_ISLANDS__ = boot;
+if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot);
+else boot();