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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 ScriptedAlchemy LLC (Zack Jackson) Zhou Shaw (zhouxiao)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/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/CHANGELOG.md

@@ -0,0 +1,43 @@
+# @module-federation/observability-plugin
+
+## 0.0.0-codex-node24-dev-node20-compat-ci-20260713063237
+
+### Patch Changes
+
+- @module-federation/sdk@0.0.0-codex-node24-dev-node20-compat-ci-20260713063237
+
+## 2.5.3
+
+### Patch Changes
+
+- Updated dependencies [dcc640b]
+- Updated dependencies [9958086]
+  - @module-federation/sdk@2.7.0
+
+## 2.5.2
+
+### Patch Changes
+
+- @module-federation/sdk@2.6.0
+
+## 2.5.1
+
+### Patch Changes
+
+- Updated dependencies [b9b3b8c]
+  - @module-federation/sdk@2.5.1
+
+## 2.5.0
+
+### Minor Changes
+
+- 41281f4: Add a Loading Trace panel that can configure and inject the observability plugin, reload the inspected page, stream loading events, and export collected reports.
+- 41281f4: Add an opt-in observability plugin, a Chrome-extension-safe observability plugin entry with an independent name and fixed browser scope, a direct runtime plugin API with instance-bound component loaded marks, explicit temporary React `onMFRemoteLoaded` callback injection for matched remotes, opt-in start console traces for `loadRemote` and `loadShare`, a local collector mode for AI-assisted browser debugging, a Node-specific export for file reports, a build-specific export for build summaries and build error reports, remote and shared lifecycle hooks, console trace hints, safe browser/Node report outputs, configurable error stack capture with explicit console raw-stack opt-ins, shared/eager loading evidence gated to stable runtime `2.5.0+` for Chrome-extension compatibility, final loading outcome summaries for Module Federation loading reports including resolved shared dependencies, deterministic fact reports for runtime and build failures, no-op return handling for observer hooks, detailed remote match/init/expose/factory phase events with phase durations, compact phase summaries, cache/fallback markers, loaded-before evidence from existing federation instances when a remote load fails, length-limited business component metadata, clipped moduleInfo evidence with preserved deployment locator fields for snapshot-dependent failures, normalized runtime error summaries with error codes, owner hints, retryability, and safe context, dedicated runtime error codes for invalid manifests, missing exposes, and remote container init failures, plus MF skill guidance for reading and fixing observability reports.
+
+### Patch Changes
+
+- 0716c11: Track preload resource results and expose resource context to loader hooks.
+- 328542c: Send configured local collector events outside debug mode while keeping failures quiet unless debug logging is enabled.
+- Updated dependencies [5d4095d]
+- Updated dependencies [0716c11]
+  - @module-federation/sdk@2.5.0