@bleedingdev/modern-js-renderer-octane 3.9.3-ultramodern.7 → 3.9.3-ultramodern.9

package/src/client.ts

@@ -24,6 +24,11 @@ import {
   FederationApplication,
   type OctaneFederationScope,
 } from './federation-context';
+import {
+  type OctaneWorkerFederationFactory,
+  type OctaneWorkerFederationScope,
+  WorkerFederationApplication,
+} from './worker-federation-context';
 
 export type { OctaneDocumentBootstrap } from './bootstrap';
 export { readOctaneDocumentBootstrap } from './bootstrap';
@@ -50,9 +55,14 @@ export interface OctaneApplicationOptions {
   readonly signal?: AbortSignal;
   /** Hydration installs the native signal bridge before invoking this importer. */
   readonly load: () => Promise<OctaneApplicationModule>;
-  readonly options?: Omit<RootOptions, 'signalOwner'>;
+  readonly options?: Omit<RootOptions, 'signalOwner' | 'externalSnapshots'>;
   /** This browser compilation's native Module Federation runtime. */
   readonly federation?: NativeFederationBinding;
+  readonly workerFederation?:
+    | OctaneWorkerFederationScope
+    | OctaneWorkerFederationFactory;
+  /** Trusted document bootstrap identity, also present for a CSR document. */
+  readonly documentId?: string;
 }
 
 export interface OctaneHydrationOptions extends OctaneApplicationOptions {
@@ -296,6 +306,8 @@ function createHandle(input: {
   signal?: AbortSignal;
   onCleanupError?: (error: unknown) => void;
   federation?: OctaneFederationScope;
+  workerFederation?: OctaneWorkerFederationScope;
+  retireWorkerFederation?: () => void;
 }): OctaneApplicationHandle {
   let releaseModule = input.releaseModule;
   let disposed = false;
@@ -310,12 +322,18 @@ function createHandle(input: {
       const nextRelease = claimModuleResources(next);
       releaseModule = nextRelease;
       try {
-        input.federation
-          ? input.root.render(FederationApplication, {
-              scope: input.federation,
+        input.workerFederation
+          ? input.root.render(WorkerFederationApplication, {
+              scope: input.workerFederation,
+              federation: input.federation,
               application: next,
             })
-          : input.root.render(next.default, next.props);
+          : input.federation
+            ? input.root.render(FederationApplication, {
+                scope: input.federation,
+                application: next,
+              })
+            : input.root.render(next.default, next.props);
         previousRelease();
       } catch (error) {
         cleanupResources([previousRelease, () => handle.dispose()]);
@@ -327,6 +345,7 @@ function createHandle(input: {
       disposed = true;
       input.signal?.removeEventListener('abort', onAbort);
       cleanupResources([
+        () => input.retireWorkerFederation?.(),
         () => input.root.unmount(),
         () => releaseModule(),
         () => input.bridge?.dispose(),
@@ -356,6 +375,21 @@ async function startApplication(
   hydration?: { document: Document; documentId: string },
 ): Promise<OctaneApplicationHandle> {
   const errors = observeRootErrors(input.options);
+  const workerController = input.workerFederation
+    ? new AbortController()
+    : undefined;
+  let workerFederation: OctaneWorkerFederationScope | undefined;
+  const retireWorkerFederation = () =>
+    cleanupResources([
+      () =>
+        workerController?.abort(
+          new DOMException(
+            'The Worker federation document was disposed',
+            'AbortError',
+          ),
+        ),
+      () => workerFederation?.transport.dispose(),
+    ]);
   let bridge: StreamedSignalHydration | undefined;
   let root: Root | undefined;
   let releaseModule: (() => void) | undefined;
@@ -369,6 +403,7 @@ async function startApplication(
     if (cleaned) return;
     cleaned = true;
     cleanupResources([
+      retireWorkerFederation,
       () => root?.unmount(),
       () => releaseModule?.(),
       () => bridge?.dispose(),
@@ -376,10 +411,30 @@ async function startApplication(
     ]);
   };
   try {
-    // Capture the selected host before asynchronous application imports.
-    const federation = input.federation
-      ? createFederationScope(input.federation, false)
-      : undefined;
+    if (input.workerFederation && workerController) {
+      const signal = AbortSignal.any([
+        workerController.signal,
+        ...(input.signal ? [input.signal] : []),
+      ]);
+      const scope =
+        typeof input.workerFederation === 'function'
+          ? input.workerFederation(signal)
+          : input.workerFederation;
+      workerFederation = {
+        ...scope,
+        signal: scope.signal ? AbortSignal.any([signal, scope.signal]) : signal,
+      };
+    }
+    if (workerFederation && !hydration && !input.documentId)
+      throw new Error(
+        'Worker federation requires the trusted document identity before application loading',
+      );
+    // Capture the host before imports and retain Worker SSR's provider ranges
+    // even when no regular Module Federation binding is configured.
+    const federation =
+      input.federation || workerFederation
+        ? createFederationScope(input.federation, false)
+        : undefined;
     if (hydration) {
       const { document, documentId } = hydration;
       bridge = bootstrapStreamedSignalHydration({
@@ -402,15 +457,41 @@ async function startApplication(
     if (bridge) {
       root = hydrateRoot(
         input.container,
-        federation ? FederationApplication : application.default,
-        federation ? { scope: federation, application } : application.props,
-        { ...errors.options, signalOwner: bridge.signalOwner },
+        workerFederation
+          ? WorkerFederationApplication
+          : federation
+            ? FederationApplication
+            : application.default,
+        workerFederation
+          ? { scope: workerFederation, federation, application }
+          : federation
+            ? { scope: federation, application }
+            : application.props,
+        {
+          ...errors.options,
+          signalOwner: bridge.signalOwner,
+          externalSnapshots: { documentId: hydration!.documentId },
+        },
       );
     } else {
-      root = createRoot(input.container, errors.options);
-      federation
-        ? root.render(FederationApplication, { scope: federation, application })
-        : root.render(application.default, application.props);
+      root = createRoot(input.container, {
+        ...errors.options,
+        ...(input.documentId
+          ? { externalSnapshots: { documentId: input.documentId } }
+          : {}),
+      });
+      workerFederation
+        ? root.render(WorkerFederationApplication, {
+            scope: workerFederation,
+            federation,
+            application,
+          })
+        : federation
+          ? root.render(FederationApplication, {
+              scope: federation,
+              application,
+            })
+          : root.render(application.default, application.props);
     }
     errors.assertInitialRender();
     input.signal?.throwIfAborted();
@@ -421,6 +502,8 @@ async function startApplication(
       release,
       bridge,
       federation,
+      workerFederation,
+      retireWorkerFederation,
       ...(input.signal === undefined ? {} : { signal: input.signal }),
       onCleanupError: error => reportCleanupError(input, error),
     });

package/src/entry-application.ts

@@ -10,6 +10,7 @@ import {
 import { type ComponentBody, createElement } from 'octane';
 import { I18nProvider } from './i18n/I18nProvider';
 import type { I18nInstanceLike } from './i18n/types';
+import { associateOctaneFileRouteSnapshot } from './router-external-snapshot';
 import {
   createFileSystemRouteTree,
   type FileSystemRouteModule,
@@ -41,8 +42,8 @@ export const octaneRouterFactory: NativeRouterFactory<AnyRoute, AnyRouter> = {
       modules as Readonly<Record<string, FileSystemRouteModule>>,
       options,
     ),
-  router: ({ location, ...options }) =>
-    createRouter({
+  router: ({ location, ...options }) => {
+    const router = createRouter({
       ...options,
       ...(location
         ? {
@@ -50,7 +51,10 @@ export const octaneRouterFactory: NativeRouterFactory<AnyRoute, AnyRouter> = {
             history: createMemoryHistory({ initialEntries: [location.href] }),
           }
         : {}),
-    }),
+    });
+    associateOctaneFileRouteSnapshot(router);
+    return router;
+  },
 };
 
 interface LocalizedRouterProps {

package/src/entry-client.ts

@@ -21,11 +21,18 @@ import {
   OctaneRouterRoot,
   prepareOctaneRouterHydration,
 } from './router-client';
+import type {
+  OctaneWorkerFederationFactory,
+  OctaneWorkerFederationScope,
+} from './worker-federation-context';
 
 export interface OctaneClientEntryOptions
   extends NativeClientEntryOptions<NativeI18nInstance, LocalisedUrlsOption> {
   /** The native client compilation hash, `__webpack_hash__`. */
   readonly nativeHydrationBuildId: string;
+  readonly workerFederation?:
+    | OctaneWorkerFederationScope
+    | OctaneWorkerFederationFactory;
 }
 
 const LocalizedRouterRoot = localizedRouterRoot(OctaneRouterRoot);
@@ -38,6 +45,7 @@ export function startNativeClient(options: OctaneClientEntryOptions): void {
       readOctaneDocumentBootstrap(document, identity, nativeHydrationBuildId),
     createRouter: (application, routerOptions) =>
       createNativeRouter(application, routerOptions, octaneRouterFactory),
+    disposeRouter: router => router.history.destroy(),
     async prepareRouter(router, hydrating, signal) {
       // Hydration adopts the server's matches; a fresh mount loads its own.
       if (hydrating) await prepareOctaneRouterHydration(router, { signal });
@@ -49,6 +57,8 @@ export function startNativeClient(options: OctaneClientEntryOptions): void {
         identity,
         nativeHydrationBuildId,
         federation: options.federation,
+        workerFederation: options.workerFederation,
+        documentId: bootstrap?.documentId,
         signal,
         // Hydration installs the native signal bridge before this importer runs.
         load: async (): Promise<OctaneApplicationModule> => {

package/src/entry-server.ts

@@ -23,8 +23,8 @@ import {
 import { validateOctaneModuleManifest } from './manifest';
 import {
   createOctaneRequestHandler,
-  createOctaneRouterInjection,
   createSsrStreamResponse,
+  getSsrStatus,
   OctaneRouterServer,
 } from './router-server';
 import { renderOctaneApplication, renderOctaneCSRDocument } from './server';
@@ -52,10 +52,12 @@ export function withOctaneDocumentFields(
     : policy;
 }
 
-export type OctaneServerEntryOptions = NativeServerEntryOptions<
-  NativeI18nInstance,
-  LocalisedUrlsOption
->;
+export { createNativeWorkerFederationRuntime } from './worker-federation';
+
+export interface OctaneServerEntryOptions
+  extends NativeServerEntryOptions<NativeI18nInstance, LocalisedUrlsOption> {
+  readonly workerFederationLocale?: string;
+}
 
 const LocalizedRouterServer = localizedRouterRoot(OctaneRouterServer);
 
@@ -77,16 +79,23 @@ export function createNativeServerEntry(
       createNativeRouter(application, routerOptions, octaneRouterFactory),
     renderCSR: ({ session }, document) =>
       renderOctaneCSRDocument({ session, document }),
-    renderComponent: ({ session }, component, document, i18n) =>
+    renderComponent: (
+      { session, workerFederation },
+      component,
+      document,
+      i18n,
+    ) =>
       renderOctaneApplication({
         session,
         App: componentView(component, i18n) as ServerRenderNode,
         document,
         federation: options.federation,
+        workerFederation,
+        workerFederationLocale: options.workerFederationLocale,
       }),
     async renderRoutes({
       request,
-      context: { session },
+      context: { session, workerFederation },
       router,
       outcomes,
       document,
@@ -100,7 +109,7 @@ export function createNativeServerEntry(
         serialization: { forbiddenValues },
       })(async ({ router, responseHeaders }) => {
         const metadata = mergeDataResponseMetadata(outcomes, {
-          status: router.state.statusCode ?? 200,
+          status: getSsrStatus(router),
         });
         // Route headers() take precedence over loader singleton fields; list
         // fields keep both.
@@ -127,7 +136,9 @@ export function createNativeServerEntry(
               }),
           document,
           federation: options.federation,
-          injection: createOctaneRouterInjection(router, session),
+          workerFederation,
+          workerFederationLocale: options.workerFederationLocale,
+          router,
         });
         return createSsrStreamResponse(router, rendered);
       });

package/src/federation.ts

@@ -1,21 +1,31 @@
-import {
-  loadFederatedModule,
-  remoteBrowserAssets,
-} from '@modern-js/renderer-core/federation';
+import { loadFederatedModule } from '@modern-js/renderer-core/federation';
 import {
   type ComponentBody,
   createElement,
+  decodeExternalSnapshot,
+  externalSnapshotBoundary,
+  hookSlots,
   lazy,
   type OctaneNode,
   preinit,
+  publisherBoundary,
   Suspense,
+  serializeExternalSnapshotRequest,
   useContext,
+  useEffect,
 } from 'octane';
 import {
   FederationContext,
   type OctaneFederationScope,
 } from './federation-context';
 
+import { I18nContext } from './i18n/context';
+import {
+  type OctaneWorkerFederationScope,
+  WorkerFederationContext,
+} from './worker-federation-context';
+import { useOctaneWorkerContextKeys } from './worker-federation-contexts';
+
 /** The native component shape exposed by a same-renderer Octane remote. */
 export interface FederatedModule<P extends object> {
   readonly default: ComponentBody<P>;
@@ -26,6 +36,8 @@ export interface FederatedComponentOptions {
   readonly fallback?: () => OctaneNode;
   /** A positive load limit; the server defaults to 3000ms. */
   readonly timeout?: number;
+  /** Explicit registered server projections required by an application remote. */
+  readonly contextKeys?: readonly string[];
 }
 
 function withTimeout<T>(
@@ -56,6 +68,9 @@ function withTimeout<T>(
   });
 }
 
+// This library wrapper is published as plain JavaScript, outside app compilation.
+const publisherRegistrationEffectSlot = Symbol(hookSlots(1));
+
 /**
  * Render a native Octane remote by its `remote/Expose` id or a browser loader.
  * Native Suspense owns server fallbacks, streamed styles and hydration adoption;
@@ -90,11 +105,33 @@ export function federatedComponent<P extends object = Record<string, never>>(
   };
   // Native lazy caches its module. Scope the cache to one application/response,
   // so two hosts using the same component definition cannot share a remote.
-  const components = new WeakMap<OctaneFederationScope, ComponentBody<P>>();
+  const components = new WeakMap<object, ComponentBody<P>>();
+  const workerOwners = new WeakMap<
+    OctaneFederationScope,
+    WeakMap<OctaneWorkerFederationScope, Map<string, object>>
+  >();
 
   return props => {
     const context = useContext(FederationContext) ?? standalone;
-    let Remote = components.get(context);
+    const worker = useContext(WorkerFederationContext);
+    const language = worker
+      ? (useContext(I18nContext)?.language ?? worker.locale)
+      : undefined;
+    const contextKeys = worker
+      ? useOctaneWorkerContextKeys(options.contextKeys)
+      : undefined;
+    let owner: object = context;
+    if (worker) {
+      let scopes = workerOwners.get(context);
+      if (!scopes) workerOwners.set(context, (scopes = new WeakMap()));
+      let variants = scopes.get(worker);
+      if (!variants) scopes.set(worker, (variants = new Map()));
+      const key = JSON.stringify([language, contextKeys]);
+      let variant = variants.get(key);
+      if (!variant) variants.set(key, (variant = {}));
+      owner = variant;
+    }
+    let Remote = components.get(owner);
     if (!Remote) {
       Remote = lazy(async () => {
         try {
@@ -103,11 +140,101 @@ export function federatedComponent<P extends object = Record<string, never>>(
               'A federatedComponent loader renders in the browser only; use a remote id to server-render it',
             );
           }
-          const module = await withTimeout(
+          if (worker) {
+            if (!id || !language) {
+              throw new Error(
+                'Worker federation requires a remote id and the owning entry locale',
+              );
+            }
+            const separator = id.indexOf('/');
+            const remoteName = id.slice(0, separator);
+            const expose = `./${id.slice(separator + 1)}`;
+            const controller = new AbortController();
+            const signal = worker.signal
+              ? AbortSignal.any([worker.signal, controller.signal])
+              : controller.signal;
+            const timeout =
+              options.timeout ?? (context.server ? 3000 : undefined);
+            let admitted;
+            try {
+              admitted = await withTimeout(
+                worker.transport.admit({
+                  remote: remoteName,
+                  expose,
+                  locale: language,
+                  signal,
+                }),
+                timeout,
+                id,
+              );
+            } finally {
+              // Release this admission waiter, including after its own deadline.
+              controller.abort();
+            }
+            const BrowserRemote = lazy(async () => {
+              const { module, assets } = await loadFederatedModule<
+                FederatedModule<P>
+              >(context.instance, id);
+              if (typeof module?.default !== 'function') {
+                throw new TypeError(
+                  'A federated Octane module must default-export a native component',
+                );
+              }
+              const component = module.default;
+              const Loaded: ComponentBody<P> = (props, scope, extra) => {
+                for (const href of assets?.css ?? []) {
+                  preinit(href, {
+                    as: 'style',
+                    precedence: 'federated',
+                    ...(context.nonce === undefined
+                      ? {}
+                      : { nonce: context.nonce }),
+                  });
+                }
+                return component(props, scope, extra);
+              };
+              return { default: Loaded };
+            });
+            const boundary = externalSnapshotBoundary({
+              authority: admitted.coordinate.native,
+              component: BrowserRemote,
+              contextKeys,
+              timeoutMs: timeout,
+              async snapshot(request, signal) {
+                const response = await worker.transport.request({
+                  remote: remoteName,
+                  expose,
+                  locale: language,
+                  payload: serializeExternalSnapshotRequest(request),
+                  signal,
+                });
+                return decodeExternalSnapshot(response.payload);
+              },
+            });
+            const Loaded: ComponentBody<P> = props => {
+              // A Worker server does not execute BrowserRemote. Register the
+              // exact admitted expose's extracted CSS in this active native
+              // render; nested snapshots carry these hints through native head.
+              for (const href of admitted.styles) {
+                preinit(href, {
+                  as: 'style',
+                  precedence: 'federated',
+                  ...(context.nonce === undefined
+                    ? {}
+                    : { nonce: context.nonce }),
+                });
+              }
+              return createElement(boundary, props);
+            };
+            return { default: Loaded };
+          }
+          const { module, assets } = await withTimeout(
             Promise.resolve().then(() =>
               id
                 ? loadFederatedModule<FederatedModule<P>>(context.instance, id)
-                : (remote as () => Promise<FederatedModule<P>>)(),
+                : (remote as () => Promise<FederatedModule<P>>)().then(
+                    module => ({ module, assets: undefined }),
+                  ),
             ),
             options.timeout ?? (context.server ? 3000 : undefined),
             id ?? 'loader',
@@ -117,17 +244,34 @@ export function federatedComponent<P extends object = Record<string, never>>(
               'A federated Octane module must default-export a native component',
             );
           }
-          const assets =
-            id && context.instance
-              ? remoteBrowserAssets(context.instance, id)
-              : undefined;
           if (context.server && !assets) {
             throw new Error(
               `Cannot server-render ${id}: the host has no browser assets for this remote`,
             );
           }
-          const component = module.default;
+          // Native publisher ownership admits this exact compiled component's
+          // signal generations. Keep the boundary in the context-scoped lazy
+          // cache so props and compatible hot updates retain its live owner.
+          const component = publisherBoundary(module.default, {
+            publisherKey: id ?? 'ultramodern:browser-loader',
+          });
           const Loaded: ComponentBody<P> = props => {
+            // A development runtime installs this hook on the actual owning
+            // host. Registration follows the native mounted lifetime; routing
+            // alone grants no replacement authority to a remote name.
+            useEffect(
+              () => {
+                if (context.server || !id || !context.instance) return;
+                const register = Reflect.get(
+                  context.instance,
+                  Symbol.for('ultramodern.federation.browser-dev-boundary.v1'),
+                );
+                if (typeof register !== 'function') return;
+                return register(id, module.default, component);
+              },
+              [],
+              publisherRegistrationEffectSlot,
+            );
             // Resource APIs require an active native render. Late styles travel
             // in Octane's resource carrier ahead of the remote's HTML segment.
             for (const href of assets?.css ?? []) {
@@ -144,11 +288,11 @@ export function federatedComponent<P extends object = Record<string, never>>(
           return { default: Loaded };
         } catch (error) {
           // A later mount or ErrorBoundary reset may retry a failed load.
-          if (!context.server) components.delete(context);
+          if (!context.server) components.delete(owner);
           throw error;
         }
       });
-      components.set(context, Remote);
+      components.set(owner, Remote);
     }
     return createElement(Suspense, {
       fallback: options.fallback,

package/src/i18n/I18nProvider.ts

@@ -1,6 +1,6 @@
-import { createElement, hookSlots, useEffect, useState } from 'octane';
+import { createElement, hookSlots, useSyncExternalStore } from 'octane';
 import { I18nContext } from './context';
-import type { I18nContextValue, I18nInstanceLike } from './types';
+import type { I18nContextValue } from './types';
 
 export interface I18nProviderProps extends Omit<I18nContextValue, 'language'> {
   children?: unknown;
@@ -22,27 +22,18 @@ export interface I18nProviderProps extends Omit<I18nContextValue, 'language'> {
  */
 // Plain TypeScript is not rewritten by the Octane compiler, so each hook call
 // site carries its own stable slot, like `OctaneRouterRoot`.
-const languageStateSlot = Symbol(hookSlots(1));
-const languageSubscriptionSlot = Symbol(hookSlots(1));
+const languageStoreSlot = Symbol(hookSlots(1));
 
 export function I18nProvider(props: I18nProviderProps) {
-  const [language, setLanguage] = useState(
-    () => props.instance.language,
-    languageStateSlot,
-  );
-
-  useEffect(
-    () => {
-      const instance: I18nInstanceLike = props.instance;
-      setLanguage(instance.language);
-      const handleLanguageChanged = (lng: string) => setLanguage(lng);
-      instance.on?.('languageChanged', handleLanguageChanged);
-      return () => {
-        instance.off?.('languageChanged', handleLanguageChanged);
-      };
+  const instance = props.instance;
+  const language = useSyncExternalStore(
+    notify => {
+      instance.on?.('languageChanged', notify);
+      return () => instance.off?.('languageChanged', notify);
     },
-    [props.instance],
-    languageSubscriptionSlot,
+    () => instance.language,
+    () => instance.language,
+    languageStoreSlot,
   );
 
   const value: I18nContextValue = {