Merge branch 'pr8-unified-api' into pr9-implementation

Resolved conflict in strip-claude-coauthor.sh by keeping the more robust
implementation from pr9-implementation that checks both email AND name for
author verification, while maintaining the detailed logging and safety features.

Author: ScriptedAlchemy

.gitignore

@@ -88,3 +88,4 @@ vitest.config.*.timestamp*
 .rsbuild
 ssg
 .claude
+__mocks__/

apps/website-new/docs/en/configure/shareStrategy.mdx

@@ -2,10 +2,48 @@
 
 - Type: `'version-first' | 'loaded-first'`
 - Required: No
-- Default: `'version-first'`
+- Default: `'version-first'` (set by webpack plugin/bundler runtime)
 
 Control the loading strategy of shared dependencies:
 
-- `'version-first'`: Version priority, ensuring that the highest version of shared dependencies is used. After setting, all *remotes* entry files will be automatically loaded and **register** the corresponding shared dependencies to ensure that all shared dependency versions can be obtained. This strategy is recommended when there are strict version requirements.
+- `'version-first'`: Version priority, ensuring that the highest version of shared dependencies is used. **All remotes entry files will be automatically loaded during initialization** to register shared dependencies and ensure version compatibility. This strategy is recommended when there are strict version requirements.
 
-- `'loaded-first'`: Prioritize reuse, greatly reducing redundant dependency requests. After setting, the *remotes* entry file will not be automatically loaded (it will only be loaded when needed), and the loaded shared dependencies will be reused first. This strategy is recommended when there are no strict requirements on the version and performance is required.
+- `'loaded-first'`: Prioritize reuse of already loaded shared dependencies. Remotes are loaded on-demand rather than during initialization. This strategy is recommended when you want to reuse loaded dependencies for performance.
+
+:::warning Offline Remote Considerations
+
+The `'version-first'` strategy automatically loads remote entry files during application startup to initialize shared dependencies. If any remote is offline or unreachable, this will trigger the `errorLoadRemote` hook with `lifecycle: 'beforeLoadShare'` during startup. Without proper error handling, this can cause application initialization failures.
+
+The `'loaded-first'` strategy defers remote loading until modules are actually requested, which means offline remotes only cause failures when those specific remotes are accessed, not during application startup.
+
+**What happens with version-first and offline remotes:**
+1. During initialization, remotes are loaded via `initializeSharing()`
+2. If remote manifest/entry is offline, `module.getEntry()` fails
+3. `errorLoadRemote` hook is called with `lifecycle: 'beforeLoadShare'`
+4. If no fallback is provided, the initialization may hang or fail
+
+**Required error handling for version-first:**
+```ts
+const plugin = {
+  name: 'offline-resilient-plugin',
+  errorLoadRemote(args) {
+    if (args.lifecycle === 'beforeLoadShare') {
+      // Handle version-first offline remote during startup
+      return {
+        init: () => Promise.resolve(),
+        get: (module) => () => Promise.resolve(() => 'Offline Fallback')
+      };
+    }
+  }
+};
+```
+
+For production applications with potential network issues, consider:
+- Using `'loaded-first'` strategy for better resilience
+- Implementing comprehensive error handling for `'beforeLoadShare'` lifecycle
+- Adding retry mechanisms via plugins
+- Using proper error boundaries and fallback components
+
+See [Error Load Remote Solutions](../blog/error-load-remote) for detailed offline handling strategies.
+
+:::

apps/website-new/docs/en/guide/basic/runtime/runtime-hooks.mdx

@@ -159,29 +159,80 @@ async function errorLoadRemote(args: ErrorLoadRemoteOptions): Promise<void | unk
 type ErrorLoadRemoteOptions ={
   id: string;
   error: unknown;
+  options?: any;
   from: 'build' | 'runtime';
+  lifecycle: 'beforeRequest' | 'beforeLoadShare' | 'afterResolve' | 'onLoad';
   origin: ModuleFederation;
 }
 ```
+
+The `lifecycle` parameter indicates the stage where the error occurred:
+
+- `beforeRequest`: Error during initial request processing
+- `afterResolve`: Error during manifest loading (most common for network failures)
+- `onLoad`: Error during module loading and execution
+- `beforeLoadShare`: Error during shared dependency loading
+ 
 * example
 
 ```ts
 import { createInstance, loadRemote } from '@module-federation/enhanced/runtime'
-
 import type { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
 
 const fallbackPlugin: () => ModuleFederationRuntimePlugin =
   function () {
     return {
       name: 'fallback-plugin',
       errorLoadRemote(args) {
-        const fallback = 'fallback'
-        return fallback;
+        const { lifecycle, id, error } = args;
+        
+        // Log error details safely
+        if (error) {
+          console.warn(`Failed to load remote ${id} at ${lifecycle}:`, error?.message || error);
+        }
+        
+        // Handle different error types based on lifecycle
+        switch (lifecycle) {
+          case 'afterResolve':
+            // Manifest loading failed - provide fallback manifest or alternative URL
+            return {
+              id: id || 'fallback',
+              name: id || 'fallback',
+              metaData: { /* fallback manifest */ },
+              shared: [],
+              remotes: [],
+              exposes: []
+            };
+          
+          case 'beforeRequest':
+            // Request processing failed - can return modified args or void
+            console.warn(`Request processing failed for ${id}`);
+            return void 0;
+          
+          case 'onLoad':
+            // Module loading failed - provide fallback component
+            return () => ({
+              __esModule: true,
+              default: () => 'Fallback Component'
+            });
+          
+          case 'beforeLoadShare':
+            // Shared dependency loading failed - return fallback shared module
+            console.warn(`Shared dependency loading failed for ${id}`);
+            return () => ({
+              __esModule: true,
+              default: {}
+            });
+          
+          default:
+            // Unknown lifecycle - log and return void
+            console.warn(`Unknown lifecycle ${lifecycle} for ${id}`);
+            return void 0;
+        }
       },
     };
   };
 
-
 const mf = createInstance({
     name: 'mf_host',
     remotes: [
@@ -196,7 +247,7 @@ const mf = createInstance({
 
 mf.loadRemote('app1/un-existed-module').then(mod=>{
   expect(mod).toEqual('fallback');
-})
+});
 ```
 
 ## beforeLoadShare
@@ -242,7 +293,7 @@ type ResolveShareOptions ={
 * example
 
 ```ts
-import { ModuleFederation, loadRemote } from '@module-federation/enhanced/runtime'
+import { createInstance, loadRemote } from '@module-federation/enhanced/runtime'
 
 import type { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
 
@@ -337,8 +388,6 @@ interface PreloadAssets {
 }
 ```
 
-## loaderHook
-
 ## createScript
 
 `SyncHook`
@@ -365,9 +414,9 @@ const changeScriptAttributePlugin: () => ModuleFederationRuntimePlugin =
     return {
       name: 'change-script-attribute',
       createScript({ url }) {
-        if (url === testRemoteEntry) {
+        if (url === 'http://localhost:3001/remoteEntry.js') {
           let script = document.createElement('script');
-          script.src = testRemoteEntry;
+          script.src = url;
           script.setAttribute('loader-hooks', 'isTrue');
           script.setAttribute('crossorigin', 'anonymous');
           return script;

apps/website-new/docs/en/guide/troubleshooting/runtime/RUNTIME-003.mdx

@@ -4,9 +4,94 @@ import ErrorCodeTitle from '@components/ErrorCodeTitle';
 
 ## Reasons
 
-Failed to load the manifest, the manifest url may be wrong
+Failed to load the manifest, which can occur due to:
+
+1. The manifest URL may be wrong or unreachable
+2. Network connectivity issues
+3. CORS (Cross-Origin Resource Sharing) restrictions
+4. Remote service is offline or not yet deployed
+5. DNS resolution failures
 
 ## Solutions
 
-1. Check whether manifestUrl can be accessed normally alone
-2. Check manifestUrl for cross-domain issues
+### Basic Troubleshooting
+1. Check whether manifestUrl can be accessed directly in browser
+2. Verify the manifest URL format and path correctness
+3. Check network connectivity and DNS resolution
+4. Review CORS configuration on the remote server
+
+### Advanced Solutions
+
+#### 1. Implement Error Handling with Runtime Plugins
+
+Use the `errorLoadRemote` hook to handle manifest loading failures gracefully:
+
+```ts
+import type { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
+
+const offlineHandlingPlugin: () => ModuleFederationRuntimePlugin = () => ({
+  name: 'offline-handling-plugin',
+  errorLoadRemote(args) {
+    const { lifecycle, id, error } = args;
+    
+    // Handle different error scenarios based on lifecycle stage
+    if (lifecycle === 'afterResolve') {
+      // Manifest loading failure during normal remote loading
+      console.warn(`Failed to load manifest for remote ${id}:`, error);
+      // Provide fallback manifest or backup URL
+      return {
+        id: 'fallback',
+        name: 'fallback',
+        metaData: { /* fallback configuration */ },
+        shared: [],
+        remotes: [],
+        exposes: []
+      };
+    }
+    
+    if (lifecycle === 'beforeLoadShare') {
+      // Remote loading failure during version-first initialization
+      console.warn(`Remote ${id} is offline during startup (version-first):`, error);
+      // Return mock RemoteEntryExports to allow app to continue
+      return {
+        init: () => Promise.resolve(),
+        get: (moduleName) => () => Promise.resolve(() => 'Fallback Component')
+      };
+    }
+  },
+});
+```
+
+#### 2. Use Retry Plugin
+
+Add automatic retry mechanism for transient network failures:
+
+```ts
+import { RetryPlugin } from '@module-federation/retry-plugin';
+
+// In your Module Federation configuration
+runtimePlugins: [
+  () => RetryPlugin({
+    fetch: {
+      retryTimes: 3,
+      retryDelay: 1000,
+    },
+  }),
+],
+```
+
+#### 3. Environment-Specific Handling
+
+For different environments, consider:
+- **Development**: Log detailed error information
+- **Production**: Provide graceful fallbacks without exposing internal errors
+- **Staging**: Use backup servers or cached manifests
+
+### ShareStrategy Impact
+
+The shareStrategy affects when manifest loading occurs:
+
+- `shareStrategy: 'version-first'` - Triggers manifest loading during application initialization for all remotes. Offline remotes will cause startup failures.
+- `shareStrategy: 'loaded-first'` - Defers manifest loading until remotes are actually used. Offline remotes only cause failures when accessing those specific remotes.
+
+For resilience against offline remotes, consider using `'loaded-first'` strategy combined with proper error handling.

apps/website-new/docs/en/plugin/plugins/_meta.json

@@ -1 +1 @@
-["index", "retry-plugin"]
+["index", "retry-plugin", "building-custom-retry-plugin"]