Merge branch 'main' into pr8-unified-api

Author: ScriptedAlchemy

.gitignore

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

INCREMENTAL_PR_PLAN_REVISED.md

@@ -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.
+
+:::