docs: add runtime api and runtime hooks part (#4658)

Author: 2heal1

apps/website-new/docs/en/guide/runtime/runtime-api.mdx

@@ -20,7 +20,7 @@ Used to create ModuleFederation instance.
   - Multiple ModuleFederation instances need to be created with different configurations for each instance
   - You want to use ModuleFederation's partitioning feature to encapsulate corresponding APIs for use in other projects
 
-* `createInstance` will not overwrite an existing instance. Each call will create a new instance.
+* `createInstance` always creates a fresh `ModuleFederation` instance and registers it in the global instance registry. It does not look up an existing instance by `name` / `version`, and it does not merge options into an existing instance.
 
 ```ts
 import { createInstance } from '@module-federation/enhanced/runtime';
@@ -38,17 +38,19 @@ const mf = createInstance({
 mf.loadRemote('sub1/util').then((m) => m.add(1, 2, 3));
 ```
 
-## init <Badge type='danger'>Deprecated</Badge>
+## init <Badge type='warning'>Use with caution</Badge>
 
 :::warning Warning
 
-This API will be deprecated. If you need to get an existing instance, you can use [getInstance](#getinstance) to retrieve the created instance.
+`init` is still supported, but choose it based on how you want instances to be managed.
 
-If you need to create a new instance, please use the [createInstance](#createinstance).
+Unlike [createInstance](#createinstance), `init` does not always create a fresh instance. It first looks up an existing instance by `name` and `version`. If a matching instance is found, it reuses that instance and merges the new options by calling `instance.initOptions(options)`. If no matching instance exists, it falls back to creating one.
+
+Use `init` when you want repeated calls for the same host to reuse and extend a single runtime instance. Use [createInstance](#createinstance) when you need guaranteed isolation and a brand-new instance every time. If you only need the instance created by the build plugin, use [getInstance](#getinstance).
 
 :::
 
-- Type: `init(options: InitOptions): void`
+- Type: `init(options: InitOptions): ModuleFederation`
 - Used for dynamically registering `Vmok` modules at runtime.
 - InitOptions:
 
@@ -137,7 +139,7 @@ init({
 ```
 </Collapse>
 
-### How to Migrate
+### Recommended alternatives
 
 #### Build Plugin(Use build plugin)
 
@@ -226,7 +228,7 @@ plugins: [mfRuntimePlugin()]
 });
 ```
 
-If you are not using the build plugin, you can replace `init` with [createInstance](#createinstance), which has exactly the same parameters.
+If you are not using the build plugin, you can switch from `init` to [createInstance](#createinstance) because the option shape is the same. However, the instance semantics are different: `createInstance` always creates a fresh instance, while `init` may reuse an existing one with the same `name` / `version` and merge the new options into it.
 
 ## getInstance
 

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

@@ -130,7 +130,7 @@ interface RemoteInfo {
 
 `AsyncWaterfallHook`
 
-Triggered before the host calls `remoteEntry.init(...)`. Useful for dynamically rewriting the share-scope alignment for this initialization (shareScopeKeys/shareScopeMap) and the `remoteEntryInitOptions` passed to the remote.
+Triggered before the host calls `remoteEntry.init(...)`. Useful for dynamically rewriting the `shareScope` / `initScope` used in this initialization and the `remoteEntryInitOptions` passed to the remote.
 
 * type
 
@@ -146,6 +146,29 @@ type BeforeInitContainerOptions ={
 }
 ```
 
+## initContainer
+
+`AsyncWaterfallHook`
+
+Triggered after `remoteEntry.init(...)` completes successfully. Useful for metrics, observability, or post-initialization customization.
+
+* type
+
+```ts
+async function initContainer(args: InitContainerOptions): Promise<InitContainerOptions>
+
+type InitContainerOptions ={
+  shareScope: ShareScopeMap[string];
+  initScope: InitScope;
+  remoteEntryInitOptions: RemoteEntryInitOptions;
+  remoteInfo: RemoteInfo;
+  remoteEntryExports: RemoteEntryExports;
+  origin: ModuleFederation;
+  id?: string;
+  remoteSnapshot?: ModuleInfo;
+}
+```
+
 ## handlePreloadModule
 
 `SyncHook`
@@ -160,8 +183,10 @@ function handlePreloadModule(args: HandlePreloadModuleOptions): void
 type HandlePreloadModuleOptions ={
   id: string;
   name: string;
+  remote: Remote;
   remoteSnapshot: ModuleInfo;
   preloadConfig: PreloadRemoteArgs;
+  origin: ModuleFederation;
 }
 ```
 
@@ -394,7 +419,7 @@ Called before the preload handler executes any preload logic.
 * type
 
 ```ts
-async function beforePreloadRemote(args: BeforePreloadRemoteOptions): BeforePreloadRemoteOptions
+async function beforePreloadRemote(args: BeforePreloadRemoteOptions): Promise<void>
 
 type BeforePreloadRemoteOptions ={
   preloadOps: Array<PreloadRemoteArgs>;
@@ -430,6 +455,10 @@ interface PreloadAssets {
 }
 ```
 
+## loaderHook
+
+`loaderHook` is used to intercept resource loading and module-factory resolution.
+
 ## createScript
 
 `SyncHook`
@@ -439,10 +468,11 @@ Used to modify the script when loading resources.
 * type
 
 ```ts
-function createScript(args: CreateScriptOptions): HTMLScriptElement | void
+function createScript(args: CreateScriptOptions): CreateScriptHookReturn
 
 type CreateScriptOptions ={
   url: string;
+  attrs?: Record<string, any>;
 }
 ```
 
@@ -498,6 +528,62 @@ export default function (): FederationRuntimePlugin {
 };
 ```
 
+## createLink
+
+`SyncHook`
+
+Used to customize the link element created for preload/style loading.
+
+* type
+
+```ts
+function createLink(args: CreateLinkOptions): HTMLLinkElement | void
+
+type CreateLinkOptions ={
+  url: string;
+  attrs?: Record<string, any>;
+}
+```
+
+## loadEntryError
+
+`AsyncHook`
+
+Triggered when loading remoteEntry fails (typically script loading errors). Useful for retries or custom fallback strategies.
+
+* type
+
+```ts
+async function loadEntryError(args: LoadEntryErrorOptions): Promise<Promise<RemoteEntryExports | undefined> | undefined>
+
+type LoadEntryErrorOptions ={
+  getRemoteEntry: typeof getRemoteEntry;
+  origin: ModuleFederation;
+  remoteInfo: RemoteInfo;
+  remoteEntryExports?: RemoteEntryExports;
+  globalLoading: Record<string, Promise<void | RemoteEntryExports> | undefined>;
+  uniqueKey: string;
+}
+```
+
+## getModuleFactory
+
+`AsyncHook`
+
+Triggered before calling `remoteEntry.get(expose)`, allowing custom module-factory resolution.
+
+* type
+
+```ts
+async function getModuleFactory(args: GetModuleFactoryOptions): Promise<(() => Promise<Module>) | undefined>
+
+type GetModuleFactoryOptions ={
+  remoteEntryExports: RemoteEntryExports;
+  expose: string;
+  moduleInfo: RemoteInfo;
+}
+```
+
 ## loadEntry
 The `loadEntry` function allows for full customization of remotes, enabling you to extend and create new remote types. The following two simple examples demonstrate loading JSON data and module delegation.
 
@@ -631,3 +717,55 @@ import test2 from "delegateModulesA/test2"
 test1 // "test1 value"
 test2 // "test2 value"
 ```
+
+## bridgeHook
+
+`bridgeHook` is defined in `runtime-core/src/core.ts` and is used to extend context across bridge render/destroy stages (for example, React/Vue bridge).
+
+## beforeBridgeRender
+
+`SyncHook`
+
+Triggered before bridge rendering. You can return an object to augment render arguments (for example, `extraProps`).
+
+* type
+
+```ts
+function beforeBridgeRender(args: Record<string, any>): void | Record<string, any>
+```
+
+## afterBridgeRender
+
+`SyncHook`
+
+Triggered after bridge rendering.
+
+* type
+
+```ts
+function afterBridgeRender(args: Record<string, any>): void | Record<string, any>
+```
+
+## beforeBridgeDestroy
+
+`SyncHook`
+
+Triggered before bridge teardown.
+
+* type
+
+```ts
+function beforeBridgeDestroy(args: Record<string, any>): void | Record<string, any>
+```
+
+## afterBridgeDestroy
+
+`SyncHook`
+
+Triggered after bridge teardown.
+
+* type
+
+```ts
+function afterBridgeDestroy(args: Record<string, any>): void | Record<string, any>
+```

apps/website-new/docs/zh/guide/runtime/runtime-api.mdx

@@ -21,7 +21,7 @@ import Runtime from '@components/zh/runtime/index';
   - 希望使用 ModuleFederation 分治特性，封装相应的 API 提供给其他项目使用
 
 
-* `createInstance` 不会对已存在的实例进行覆盖，每次调用都会创建一个新的实例。
+* `createInstance` 每次都会创建一个全新的 `ModuleFederation` 实例，并将其注册到全局实例列表中。它不会根据 `name` / `version` 查找已有实例，也不会把新配置合并到已有实例上。
 
 ```ts
 import { createInstance } from '@module-federation/enhanced/runtime';
@@ -39,17 +39,19 @@ const mf = createInstance({
 mf.loadRemote('sub1/util').then((m) => m.add(1, 2, 3));
 ```
 
-## init <Badge type='danger'>废弃</Badge>
+## init <Badge type='warning'>谨慎使用</Badge>
 
 :::warning Warning
 
-此 API 将被废弃。如果需要获取已创建的实例，可以使用 [getInstance](#getinstance) 获取已创建的实例。
+`init` 仍然受支持，但需要根据你希望如何管理实例来选择是否使用它。
 
-如果需要创建新的实例，请使用 [createInstance](#createinstance)。
+它与 [createInstance](#createinstance) 的核心区别在于：`init` 不会每次都创建新实例，而是会先根据 `name` 和 `version` 查找已有实例。如果找到了匹配实例，就复用该实例，并通过 `instance.initOptions(options)` 合并新的配置；只有在找不到匹配实例时，才会退回到创建新实例。
+
+当你希望同一个 host 的多次调用复用并扩展同一个运行时实例时，适合使用 `init`。当你需要严格隔离、确保每次都拿到全新实例时，请使用 [createInstance](#createinstance)。如果你只是想获取构建插件创建的实例，请使用 [getInstance](#getinstance)。
 
 :::
 
-- Type: `init(options: InitOptions): void`
+- Type: `init(options: InitOptions): ModuleFederation`
 - 用于运行时动态注册 `Vmok` 模块
 - InitOptions:
 
@@ -138,7 +140,7 @@ init({
 ```
 </Collapse>
 
-### 如何迁移
+### 推荐替代方式
 
 #### Build Plugin（使用构建插件）
 
@@ -229,7 +231,7 @@ plugins: [mfRuntimePlugin()]
 ```
 
 
-如果没有使用构建插件，你可以使用 [createInstance](#createinstance)替换 `init` ，其参数完全一致。
+如果没有使用构建插件，你可以从 `init` 切换到 [createInstance](#createinstance)，因为两者接收的配置形状是一致的。但要注意实例语义不同：`createInstance` 总是创建新实例，而 `init` 可能会复用同一个 `name` / `version` 对应的已有实例，并把新配置合并进去。
 
 ## getInstance