@module-federation/observability-plugin 0.0.0-alpha.0 → 0.0.0-codex-node24-dev-node20-compat-ci-20260713063237

package/dist/README.md

@@ -15,21 +15,19 @@ Node file output, and no raw error stack in console output.
 import { createInstance } from '@module-federation/runtime';
 import { ObservabilityPlugin } from '@module-federation/observability-plugin';
 
-const observability = ObservabilityPlugin({
-  level: 'verbose',
-  browser: {
-    enabled: true,
-    scope: 'host',
-  },
-});
-
 createInstance({
   name: 'host',
-  plugins: [observability.plugin],
+  plugins: [
+    ObservabilityPlugin({
+      level: 'verbose',
+      browser: {
+        enabled: true,
+        scope: 'host',
+      },
+    }),
+  ],
   remotes: [],
 });
-
-const report = observability.getLatestReport();
 ```
 
 The plugin does not upload data or expose a browser global by default. Reports
@@ -44,6 +42,11 @@ Enable only the output channels that match the environment:
 
 - Browser dev: use `browser.enabled: true` with a scoped reader such as
   `window.__FEDERATION__.__OBSERVABILITY__.host`.
+- Chrome DevTools integration: use `devtools: true` together with browser
+  output so a browser extension can receive loading events through
+  `window.postMessage`.
+- Agent-led browser dev: use `collector: true` to POST reports to the local
+  skill collector on `127.0.0.1:17891`.
 - Browser prod: set `browser.mode: "production"` so console output stays limited
   to `traceId` and known `errorCode`; export full reports only through explicit
   app-owned flows such as `exportReport()` or `onReport`.
@@ -68,7 +71,13 @@ Failure hints are printed with `console.error` so browser DevTools, CDP-based
 agents, Node logs, and log collection systems can detect that a Module
 Federation load failed and then use the printed `traceId` to fetch the full
 report. Successful or recovered reports are still available through the reader
-APIs and callbacks, but they are not promoted to console errors.
+APIs and callbacks, but they are not promoted to console errors. When the
+browser reader is enabled in development mode, the plugin prints a small
+`console.info` line by default when a `loadRemote` or `loadShare` trace starts.
+The line includes the `traceId` and read command so an agent can inspect pending
+loading state before a timeout or error happens. In production browser mode,
+start logs are disabled by default; set `trace.printStart: true` only when you
+explicitly want them.
 
 The runtime only exposes the loading lifecycle hooks needed to know whether the
 main flow started, succeeded, or failed. This plugin listens to those hooks,
@@ -76,11 +85,22 @@ derives detailed reasons like shared version mismatch or eager boundary issues,
 and exposes the final loading state through a small `summary` object:
 
 - `runtime-loaded`: Module Federation finished loading the remote module.
-- `component-loaded`: business code called `markComponentLoaded`.
+- `component-loaded`: business code called `markComponentLoaded`, or a producer
+  called the injected `onMFRemoteLoaded` callback.
+- `preloaded`: `preloadRemote` finished loading the selected resources.
 - `failed`: the load failed and `failedPhase` points to the first specific
   failing phase.
 - `recovered`: loading hit an error but a fallback/recovery path returned a
-  result.
+  result. For shared loading, the `custom-share-info-unmatched` reason means
+  build-time `customShareInfo` did not match a registered provider, but the
+  runtime handled it as a non-fatal result instead of a loading failure.
+
+`summary.componentLoaded: false` only means no component-level ready signal was
+observed. If `react.injectLoadedCallback: true` is enabled but this field is
+still false, check whether the producer actually calls
+`props.onMFRemoteLoaded?.(...)`. Without that producer call, the report can only
+confirm that the remote resource loaded; it cannot prove whether the React
+component reached the producer's business-ready point.
 
 For remote loading, the plugin listens to runtime lifecycle hooks such as
 `beforeRequest`, `afterMatchRemote`, `onLoad`, `afterLoadRemote`,
@@ -95,6 +115,20 @@ manifest, remoteEntry load, remoteEntry init, expose resolution, module factory
 execution, and final load completion. When a stage has matching start and end
 events, the end event includes a bounded `duration` value.
 
+Preload reports include resource-level results from `preloadRemote`. Each
+result records the resource URL, `resourceType`, `initiator`, preload `id`, and
+status: `success`, `error`, `timeout`, or `cached`. Calls without `exposes` use
+`remoteName/*` as the preload `id`. Calls with `exposes` are recorded per
+expose as `remoteName/expose`. The plugin does not change the existing
+`generatePreloadAssets` return shape; preload resources are still plain URL
+arrays.
+
+Runtime resource hooks also receive a `resourceContext` object on manifest,
+remoteEntry, preload JS, and preload CSS resource loads. It contains
+`initiator`, `id`, `resourceType`, and `url`, so custom loaders can tell whether
+the resource was requested by `loadRemote` or `preloadRemote` without parsing
+the URL.
+
 The report also keeps compact loading state under `summary`. It contains the
 final outcome, per-phase status and duration under `summary.phases`, safe
 cache/recovery markers under `summary.flags`, and the last resolved shared
@@ -110,20 +144,50 @@ a known runtime error code is present, and a short list of next checks. This is
 the field a person or AI coding agent should read first before falling back to
 the raw `events` timeline.
 
-For a stable report-reading and fixing workflow, see
-[`AI_TROUBLESHOOTING.md`](./AI_TROUBLESHOOTING.md). Codex-style agents can also
-use the repository's single `mf` skill entry with the `observability`
-sub-command.
+For agent-led debugging, use the repository's single `mf` skill entry with the
+`observability` sub-command. The skill is the maintained guide for reading
+reports and deciding the next debugging step.
 
 `errorLoadShare` is used only for observation. Shared dependency miss, version
 mismatch, and eager boundary errors are not retried by the retry plugin by
 default because they are usually configuration or availability problems instead
-of transient network failures.
+of transient network failures. When a build plugin supplies `customShareInfo`
+and the runtime reports a handled miss, the observability report uses a
+recovered outcome instead of marking the trace as failed.
+The Chrome extension entry skips shared events for older or preview runtime
+versions because those runtimes do not expose the same shared lifecycle
+contract.
+
+Business code can mark its own success condition with a fixed event. When React
+callback injection is explicitly enabled, the wrapper injects an
+`onMFRemoteLoaded` prop into the remote component. The producer can call it when
+the component's own ready condition is met:
+
+```tsx
+import { useEffect } from 'react';
+import type { OnMFRemoteLoaded } from '@module-federation/observability-plugin';
+
+export default function RemotePanel({ onMFRemoteLoaded }: { onMFRemoteLoaded?: OnMFRemoteLoaded }) {
+  useEffect(() => {
+    onMFRemoteLoaded?.({
+      metadata: {
+        dataReady: true,
+      },
+    });
+  }, [onMFRemoteLoaded]);
+
+  return <section>Remote panel</section>;
+}
+```
 
-Business code can mark its own success condition with a fixed event:
+If the app wants to mark readiness from the consumer side, it can still call the
+instance method directly:
 
 ```ts
-observability.markComponentLoaded({
+import { getInstance } from '@module-federation/runtime';
+import '@module-federation/observability-plugin';
+
+getInstance()?.markComponentLoaded({
   requestId: 'remote/Button',
   componentName: 'Button',
   metadata: {
@@ -132,9 +196,42 @@ observability.markComponentLoaded({
 });
 ```
 
-This records `component:business-loaded` on the same trace when possible.
+Both paths record `component:business-loaded` on the same trace when possible.
 Business metadata is optional. String values keep their original details and are
-only length-limited, so user-provided metadata remains trustworthy.
+only length-limited, so user-provided metadata remains trustworthy. The instance
+method is attached when the observability plugin is registered. If an
+application uses multiple runtime instances, call it on the instance that
+registered this plugin.
+
+React callback injection is available only when explicitly enabled:
+
+```ts
+ObservabilityPlugin({
+  level: 'verbose',
+  react: {
+    injectLoadedCallback: true,
+    remoteIds: ['remote/Button'],
+  },
+});
+```
+
+When this option is enabled, the plugin tries to wrap remote function components
+returned by `loadRemote`. The wrapper does not add DOM nodes. It injects the
+`onMFRemoteLoaded` prop only. It does not observe React mount, render lifecycle,
+or timeout. When the producer calls the callback, the report records
+`component:business-loaded`. This option changes the component reference because
+it returns a wrapper component, so use it as a temporary debugging switch and
+remove it after the production issue is fixed.
+
+If `summary.componentLoaded` is still `false` after enabling this option, inspect
+the producer first. If the producer has not called `onMFRemoteLoaded`, the report
+only proves remote runtime loading, not component business readiness. If the
+producer source is unavailable, ask the producer owner to confirm whether the
+callback was added.
+
+Use `react.remoteIds` to limit this behavior to the remote requests you are
+actively debugging. If `remoteIds` is empty, the plugin wraps detected React
+function components loaded by the runtime instance that registered it.
 
 Browser output is available only when the plugin option explicitly enables it.
 When browser output is enabled, the report can be read from:
@@ -147,11 +244,84 @@ window.__FEDERATION__.__OBSERVABILITY__.host.findReports({ remote: 'remote1' });
 window.__FEDERATION__.__OBSERVABILITY__.host.exportReport('mf-trace-id');
 ```
 
-The same methods are available on the observability controller returned by
-`ObservabilityPlugin()`. `getReports({ limit })` returns recent reports newest
-first. `findReports()` can filter by `traceId`, `remote`, `expose`, `shared`,
-`status`, or `outcome`. `exportReport()` returns a copied report object, using
-the latest report when no `traceId` is provided.
+Chrome DevTools panels can opt in to event delivery without polling the page:
+
+```ts
+ObservabilityPlugin({
+  level: 'verbose',
+  browser: {
+    enabled: true,
+    scope: 'host',
+    mode: 'development',
+  },
+  trace: {
+    printStart: true,
+  },
+  devtools: true,
+});
+```
+
+This posts structured event/report snapshots to the page with
+`window.postMessage`. Browser extensions can forward those messages from their
+content script to the panel. The channel is disabled by default.
+
+`getReports({ limit })` returns recent reports newest first. `findReports()` can
+filter by `traceId`, `remote`, `expose`, `shared`, `status`, or `outcome`.
+`exportReport()` returns a copied report object, using the latest report when no
+`traceId` is provided.
+
+For agent-led development debugging where a page may stay in a loading state,
+enable the browser reader. Development browser mode prints start traces by
+default:
+
+```ts
+ObservabilityPlugin({
+  level: 'verbose',
+  browser: {
+    enabled: true,
+    scope: 'host',
+  },
+});
+```
+
+This prints only `loadRemote` and `loadShare` start lines. It does not print a
+line for every internal phase. Set `trace.printStart: false` to disable it in
+development browser mode. In production browser mode, set
+`trace.printStart: true` to opt in.
+
+If the agent cannot execute JavaScript in the browser page, enable the local
+collector and start the collector from the MF skill:
+
+```ts
+ObservabilityPlugin({
+  level: 'verbose',
+  collector: true,
+});
+```
+
+`collector: true` posts event/report snapshots to:
+
+```text
+http://127.0.0.1:17891/__mf_observability
+```
+
+Use a custom local port only when the default port is occupied:
+
+```ts
+ObservabilityPlugin({
+  collector: {
+    enabled: true,
+    port: 17892,
+  },
+});
+```
+
+The runtime plugin does not create a server. The MF skill starts a temporary
+local Node collector, writes reports under `.mf/observability/collector`, and
+the agent reads those files. The collector path is local-only and does not
+execute code or control the page. Collector delivery is controlled by the
+`collector` option; debug mode only decides whether a failed collector request
+prints a debug log.
 
 For browser production use, set `browser.mode: "production"` when the runtime
 console must stay minimal:
@@ -169,10 +339,10 @@ ObservabilityPlugin({
 In production browser mode, the `console.error` hint only includes the `traceId`
 and known `errorCode`. It does not print the report body, raw stack, request
 URL, or `read:` command. Full reports are still available only through explicit
-user choices such as the observability controller, `exportReport()`, or an
-application-owned `onReport` upload. Production applications that want richer
-observability should prefer `onReport` / `onEvent` to forward reports to their
-own telemetry system instead of exposing a public browser global.
+user choices such as `exportReport()` or an application-owned `onReport` upload.
+Production applications that want richer observability should prefer
+`onReport` / `onEvent` to forward reports to their own telemetry system instead
+of exposing a public browser global.
 
 Node file output is provided by the Node-specific entry:
 
@@ -180,15 +350,15 @@ Node file output is provided by the Node-specific entry:
 import { createInstance } from '@module-federation/runtime';
 import { ObservabilityPlugin } from '@module-federation/observability-plugin/node';
 
-const observability = ObservabilityPlugin({
-  level: 'verbose',
-  fileOutput: true,
-  directory: '.mf/observability',
-});
-
 createInstance({
   name: 'host',
-  plugins: [observability.plugin],
+  plugins: [
+    ObservabilityPlugin({
+      level: 'verbose',
+      fileOutput: true,
+      directory: '.mf/observability',
+    }),
+  ],
   remotes: [],
 });
 ```
@@ -293,3 +463,13 @@ Shared dependency reports include only evidence fields such as package name,
 share scope, requested version, available versions, selected provider, and a
 reason like `missing-provider`, `version-mismatch`, or `sync-async-boundary`.
 They do not include shared factories, module values, source, or business data.
+
+Shared observability is intentionally scoped to the Module Federation instance
+that resolved the shared dependency. It can answer which MF instance loaded a
+shared package, which registered provider/version was selected, and the related
+scope/version/eager configuration. It does not guarantee a causal link from that
+shared dependency back to a specific remote or expose, because shared resolution
+can be triggered later by the bundler runtime while chunks and module factories
+execute. When multiple shared dependencies are involved, read all
+`phase: "shared"` events. `summary.shared` is only a compact last-observed
+summary.

package/dist/browser.d.ts

@@ -0,0 +1,6 @@
+import { L as ObservabilityRuntimePlugin, T as ObservabilityPluginOptions } from "./core-Db-z5jD3.js";
+
+//#region src/browser.d.ts
+declare function ObservabilityPlugin(options?: ObservabilityPluginOptions): ObservabilityRuntimePlugin;
+//#endregion
+export { ObservabilityPlugin, ObservabilityPlugin as default, type ObservabilityPluginOptions };

package/dist/browser.js

@@ -0,0 +1,11 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+const require_core = require('./core--1ofIHU9.js');
+
+//#region src/browser.ts
+function ObservabilityPlugin(options = {}) {
+	return require_core.createObservability(options).plugin;
+}
+
+//#endregion
+exports.ObservabilityPlugin = ObservabilityPlugin;
+exports.default = ObservabilityPlugin;

package/dist/build.js

@@ -26,11 +26,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+let _module_federation_sdk = require("@module-federation/sdk");
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
 let node_path = require("node:path");
 node_path = __toESM(node_path);
-let _module_federation_sdk = require("@module-federation/sdk");
 
 //#region src/build.ts
 const PLUGIN_NAME = "ObservabilityBuildPlugin";
@@ -707,4 +707,5 @@ var ObservabilityBuildPlugin = class {
 
 //#endregion
 exports.ObservabilityBuildPlugin = ObservabilityBuildPlugin;
+exports.__toESM = __toESM;
 exports.createObservabilityBuildInfo = createObservabilityBuildInfo;

package/dist/chrome-devtool.d.ts

@@ -0,0 +1,6 @@
+import { L as ObservabilityRuntimePlugin, T as ObservabilityPluginOptions } from "./core-Db-z5jD3.js";
+
+//#region src/chrome-devtool.d.ts
+declare function ChromeObservabilityPlugin(options?: ObservabilityPluginOptions): ObservabilityRuntimePlugin;
+//#endregion
+export { ChromeObservabilityPlugin, ChromeObservabilityPlugin as default, type ObservabilityPluginOptions };

package/dist/chrome-devtool.js

@@ -0,0 +1,20 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+const require_core = require('./core--1ofIHU9.js');
+
+//#region src/chrome-devtool.ts
+function ChromeObservabilityPlugin(options = {}) {
+	return require_core.createObservability(options, {
+		pluginName: "observability-plugin:chrome-extension",
+		fixedBrowserScope: "chrome_extension",
+		attachInstanceApi: false,
+		guardSharedHooksByRuntimeVersion: true,
+		guardRuntimeHooksByRuntimeVersion: true,
+		disablePreloadHooks: true,
+		returnHookArgs: true,
+		forceDevelopmentChannels: true
+	}).plugin;
+}
+
+//#endregion
+exports.ChromeObservabilityPlugin = ChromeObservabilityPlugin;
+exports.default = ChromeObservabilityPlugin;