@bleedingdev/modern-js-renderer-octane 0.0.0-bootstrap → 3.9.3-ultramodern.1

package/src/client.ts

@@ -0,0 +1,485 @@
+import type { NativeFederationBinding } from '@modern-js/renderer-core/federation';
+import {
+  assertRendererIdentity,
+  type RendererIdentity,
+} from '@modern-js/renderer-core/identity';
+import {
+  type ComponentBody,
+  createRoot,
+  hydrateRoot,
+  type Root,
+  type RootContainer,
+  type RootOptions,
+} from 'octane';
+import {
+  bootstrapStreamedSignalHydration,
+  type StreamedSignalHydration,
+} from 'octane/hydration/streamed-signals';
+import {
+  assertNativeHydrationBuildId,
+  assertOctaneIdentity,
+} from './bootstrap';
+import {
+  createFederationScope,
+  FederationApplication,
+  type OctaneFederationScope,
+} from './federation-context';
+
+export type { OctaneDocumentBootstrap } from './bootstrap';
+export { readOctaneDocumentBootstrap } from './bootstrap';
+
+export interface OctaneApplicationModule {
+  readonly default: ComponentBody;
+  readonly props?: Record<string, unknown>;
+  /** Request-independent resources owned by this browser application module. */
+  readonly dispose?: () => void;
+}
+
+export interface OctaneApplicationHandle {
+  readonly root: Root;
+  readonly identity: Readonly<RendererIdentity>;
+  update(application: OctaneApplicationModule): void;
+  dispose(): void;
+}
+
+export interface OctaneApplicationOptions {
+  readonly container: Exclude<RootContainer, Document>;
+  readonly identity: RendererIdentity;
+  readonly nativeHydrationBuildId: string;
+  /** Cancels startup ownership and retires an active application. */
+  readonly signal?: AbortSignal;
+  /** Hydration installs the native signal bridge before invoking this importer. */
+  readonly load: () => Promise<OctaneApplicationModule>;
+  readonly options?: Omit<RootOptions, 'signalOwner'>;
+  /** This browser compilation's native Module Federation runtime. */
+  readonly federation?: NativeFederationBinding;
+}
+
+export interface OctaneHydrationOptions extends OctaneApplicationOptions {
+  readonly documentIdentity: RendererIdentity;
+  readonly documentNativeHydrationBuildId: string;
+  readonly documentId: string;
+}
+
+const roots = new WeakMap<RootContainer, symbol>();
+const documents = new WeakMap<Document, symbol>();
+const moduleResources = new WeakMap<
+  () => void,
+  { users: number; retired: boolean }
+>();
+
+function claimModuleResources(
+  application: OctaneApplicationModule,
+): () => void {
+  const dispose = application.dispose;
+  if (!dispose) return () => {};
+  let resources = moduleResources.get(dispose);
+  if (resources?.retired) {
+    throw new Error(
+      'A retired Octane application requires a fresh module resource instance.',
+    );
+  }
+  if (!resources) {
+    resources = { users: 0, retired: false };
+    moduleResources.set(dispose, resources);
+  }
+  resources.users++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    resources.users--;
+    if (resources.users === 0 && !resources.retired) {
+      resources.retired = true;
+      dispose();
+    }
+  };
+}
+
+function retireAbandonedModule(application: OctaneApplicationModule): void {
+  if (application.dispose && moduleResources.get(application.dispose)?.users)
+    return;
+  if (application.dispose && moduleResources.get(application.dispose)?.retired)
+    return;
+  claimModuleResources(application)();
+}
+
+function observeRootErrors(options: OctaneApplicationOptions['options']) {
+  let failed = false;
+  let failure: unknown;
+  let handle: OctaneApplicationHandle | undefined;
+  return {
+    options: {
+      ...options,
+      onUncaughtError(error: unknown) {
+        if (failed) return;
+        failed = true;
+        failure = error;
+        if (handle) {
+          // Native reporting can occur inside a flush. Retire the application
+          // after that flush so unmount does not reenter the native renderer.
+          const failedHandle = handle;
+          queueMicrotask(() => {
+            try {
+              failedHandle.dispose();
+            } catch (cleanupError) {
+              failure = new AggregateError(
+                [error, cleanupError],
+                'Octane rendering and cleanup failed.',
+              );
+            }
+            if (options?.onUncaughtError) options.onUncaughtError(failure);
+            else throw failure;
+          });
+        }
+      },
+    },
+    attach(next: OctaneApplicationHandle) {
+      handle = next;
+    },
+    assertInitialRender() {
+      if (failed) {
+        options?.onUncaughtError?.(failure);
+        throw failure;
+      }
+    },
+  };
+}
+
+function claimRoot(container: RootContainer): () => void {
+  if (container.nodeType === 9) {
+    throw new Error(
+      'An Octane application requires a subtree root in its framework-owned document.',
+    );
+  }
+  if (roots.has(container)) {
+    throw new Error('An Octane application already owns this root container.');
+  }
+  const owner = Symbol('Octane root owner');
+  roots.set(container, owner);
+  return () => {
+    if (roots.get(container) === owner) roots.delete(container);
+  };
+}
+
+function cleanupResources(cleanups: (() => void)[]): void {
+  const errors: unknown[] = [];
+  for (const cleanup of cleanups) {
+    try {
+      cleanup();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length) {
+    throw new AggregateError(errors, 'Octane application cleanup failed.');
+  }
+}
+
+function reportCleanupError(
+  input: OctaneApplicationOptions,
+  error: unknown,
+): void {
+  if (input.options?.onUncaughtError) input.options.onUncaughtError(error);
+  else
+    queueMicrotask(() => {
+      throw error;
+    });
+}
+
+/** An import cannot be aborted, but its root and bridge leases can be. */
+function loadApplication(
+  input: OctaneApplicationOptions,
+  abandon: () => void,
+): Promise<{
+  application: OctaneApplicationModule;
+  releaseModule: () => void;
+}> {
+  const acquire = (application: OctaneApplicationModule) => {
+    try {
+      validateModule(application);
+    } catch (error) {
+      if (application && typeof application.dispose === 'function')
+        retireAbandonedModule(application);
+      throw error;
+    }
+    return { application, releaseModule: claimModuleResources(application) };
+  };
+  const { signal } = input;
+  if (!signal) return input.load().then(acquire);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let abandoned = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      abandoned = true;
+      signal.removeEventListener('abort', onAbort);
+      try {
+        abandon();
+        reject(signal.reason);
+      } catch (cleanupError) {
+        reject(
+          new AggregateError(
+            [signal.reason, cleanupError],
+            'Octane startup cancellation failed.',
+          ),
+        );
+      }
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    let loading: Promise<OctaneApplicationModule>;
+    try {
+      loading = input.load();
+    } catch (error) {
+      settled = true;
+      signal.removeEventListener('abort', onAbort);
+      reject(error);
+      return;
+    }
+    loading.then(
+      application => {
+        if (abandoned) {
+          // Other consumers of the same import reserve resources in their
+          // resolution callbacks before an abandoned consumer can retire them.
+          queueMicrotask(() => {
+            try {
+              retireAbandonedModule(application);
+            } catch (error) {
+              reportCleanupError(input, error);
+            }
+          });
+          return;
+        }
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        try {
+          resolve(acquire(application));
+        } catch (error) {
+          reject(error);
+        }
+      },
+      error => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function validateModule(application: OctaneApplicationModule): void {
+  if (!application || typeof application.default !== 'function') {
+    throw new TypeError(
+      'An Octane application module must default-export a native component.',
+    );
+  }
+  if (
+    application.dispose !== undefined &&
+    typeof application.dispose !== 'function'
+  ) {
+    throw new TypeError('An Octane application disposer must be a function.');
+  }
+}
+
+function createHandle(input: {
+  root: Root;
+  identity: RendererIdentity;
+  releaseModule: () => void;
+  release: () => void;
+  bridge?: StreamedSignalHydration;
+  signal?: AbortSignal;
+  onCleanupError?: (error: unknown) => void;
+  federation?: OctaneFederationScope;
+}): OctaneApplicationHandle {
+  let releaseModule = input.releaseModule;
+  let disposed = false;
+  const handle: OctaneApplicationHandle = {
+    root: input.root,
+    identity: Object.freeze({ ...input.identity }),
+    update(next) {
+      if (disposed)
+        throw new Error('Cannot update a disposed Octane application.');
+      validateModule(next);
+      const previousRelease = releaseModule;
+      const nextRelease = claimModuleResources(next);
+      releaseModule = nextRelease;
+      try {
+        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()]);
+        throw error;
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      input.signal?.removeEventListener('abort', onAbort);
+      cleanupResources([
+        () => input.root.unmount(),
+        () => releaseModule(),
+        () => input.bridge?.dispose(),
+        input.release,
+      ]);
+    },
+  };
+  function onAbort() {
+    // An abort can originate in a native render/layout effect. Retire after
+    // the current flush, matching the native error retirement path.
+    queueMicrotask(() => {
+      try {
+        handle.dispose();
+      } catch (error) {
+        input.onCleanupError?.(error);
+      }
+    });
+  }
+  // Callers check the signal synchronously before constructing the handle.
+  input.signal?.addEventListener('abort', onAbort, { once: true });
+  return handle;
+}
+
+async function startApplication(
+  input: OctaneApplicationOptions,
+  release: () => void,
+  hydration?: { document: Document; documentId: string },
+): Promise<OctaneApplicationHandle> {
+  const errors = observeRootErrors(input.options);
+  let bridge: StreamedSignalHydration | undefined;
+  let root: Root | undefined;
+  let releaseModule: (() => void) | undefined;
+  let handle: OctaneApplicationHandle | undefined;
+  let cleaned = false;
+  const cleanup = () => {
+    if (handle) {
+      handle.dispose();
+      return;
+    }
+    if (cleaned) return;
+    cleaned = true;
+    cleanupResources([
+      () => root?.unmount(),
+      () => releaseModule?.(),
+      () => bridge?.dispose(),
+      release,
+    ]);
+  };
+  try {
+    // Capture the selected host before asynchronous application imports.
+    const federation = input.federation
+      ? createFederationScope(input.federation, false)
+      : undefined;
+    if (hydration) {
+      const { document, documentId } = hydration;
+      bridge = bootstrapStreamedSignalHydration({
+        buildId: input.nativeHydrationBuildId,
+        documentId,
+        ...(document.defaultView === null
+          ? {}
+          : {
+              target: document.defaultView as unknown as Record<
+                string,
+                unknown
+              >,
+            }),
+      });
+    }
+    const loaded = await loadApplication(input, cleanup);
+    const application = loaded.application;
+    releaseModule = loaded.releaseModule;
+    input.signal?.throwIfAborted();
+    if (bridge) {
+      root = hydrateRoot(
+        input.container,
+        federation ? FederationApplication : application.default,
+        federation ? { scope: federation, application } : application.props,
+        { ...errors.options, signalOwner: bridge.signalOwner },
+      );
+    } else {
+      root = createRoot(input.container, errors.options);
+      federation
+        ? root.render(FederationApplication, { scope: federation, application })
+        : root.render(application.default, application.props);
+    }
+    errors.assertInitialRender();
+    input.signal?.throwIfAborted();
+    handle = createHandle({
+      root,
+      identity: input.identity,
+      releaseModule,
+      release,
+      bridge,
+      federation,
+      ...(input.signal === undefined ? {} : { signal: input.signal }),
+      onCleanupError: error => reportCleanupError(input, error),
+    });
+    errors.attach(handle);
+    return handle;
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+
+export async function mountOctaneApplication(
+  input: OctaneApplicationOptions,
+): Promise<OctaneApplicationHandle> {
+  assertOctaneIdentity(input.identity);
+  assertNativeHydrationBuildId(input.nativeHydrationBuildId);
+  input.signal?.throwIfAborted();
+  return startApplication(input, claimRoot(input.container));
+}
+
+export async function hydrateOctaneApplication(
+  input: OctaneHydrationOptions,
+): Promise<OctaneApplicationHandle> {
+  assertOctaneIdentity(input.identity);
+  assertNativeHydrationBuildId(input.nativeHydrationBuildId);
+  assertNativeHydrationBuildId(input.documentNativeHydrationBuildId);
+  if (input.nativeHydrationBuildId !== input.documentNativeHydrationBuildId) {
+    throw new Error(
+      'Octane hydration bytes belong to a different native client compilation.',
+    );
+  }
+  assertRendererIdentity(input.documentIdentity, input.identity);
+  input.signal?.throwIfAborted();
+  if (
+    typeof input.documentId !== 'string' ||
+    input.documentId.trim().length === 0
+  ) {
+    throw new Error('Octane hydration requires a nonempty document identity.');
+  }
+  const document = input.container.ownerDocument;
+  if (!document)
+    throw new Error('An Octane hydration root requires a document.');
+  if (document !== globalThis.document) {
+    throw new Error(
+      'Octane hydration requires a root in the active browser document.',
+    );
+  }
+  if (documents.has(document)) {
+    throw new Error('An Octane signal bridge already owns this document.');
+  }
+  const releaseRoot = claimRoot(input.container);
+  const documentOwner = Symbol(input.documentId);
+  documents.set(document, documentOwner);
+  const release = () => {
+    releaseRoot();
+    if (documents.get(document) === documentOwner) documents.delete(document);
+  };
+  return startApplication(input, release, {
+    document,
+    documentId: input.documentId,
+  });
+}

package/src/entry-application.ts

@@ -0,0 +1,72 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import type { NativeI18nView } from '@modern-js/renderer-core/entry-client';
+import type { NativeRouterFactory } from '@modern-js/renderer-core/router';
+import {
+  type AnyRoute,
+  type AnyRouter,
+  createMemoryHistory,
+  createRouter,
+} from '@octanejs/tanstack-router';
+import { type ComponentBody, createElement } from 'octane';
+import { I18nProvider } from './i18n/I18nProvider';
+import type { I18nInstanceLike } from './i18n/types';
+import {
+  createFileSystemRouteTree,
+  type FileSystemRouteModule,
+} from './routes';
+
+export type OctaneI18nView = NativeI18nView<unknown, LocalisedUrlsOption>;
+
+/** Wrap a component entry in its request's or document's i18n provider. */
+export function componentView(
+  component: unknown,
+  i18n?: OctaneI18nView,
+): ComponentBody {
+  const App = component as ComponentBody;
+  if (!i18n) return App;
+  return () =>
+    createElement(I18nProvider, {
+      instance: i18n.instance as I18nInstanceLike,
+      languages: i18n.languages,
+      localisedUrls: i18n.localisedUrls,
+      children: createElement(App),
+    });
+}
+
+/** The Octane route tree and router of a generated entry. */
+export const octaneRouterFactory: NativeRouterFactory<AnyRoute, AnyRouter> = {
+  routeTree: (routes, modules, options) =>
+    createFileSystemRouteTree(
+      routes,
+      modules as Readonly<Record<string, FileSystemRouteModule>>,
+      options,
+    ),
+  router: ({ location, ...options }) =>
+    createRouter({
+      ...options,
+      ...(location
+        ? {
+            origin: location.origin,
+            history: createMemoryHistory({ initialEntries: [location.href] }),
+          }
+        : {}),
+    }),
+};
+
+interface LocalizedRouterProps {
+  readonly router: AnyRouter;
+  readonly i18n: OctaneI18nView;
+}
+
+/** Wrap a router root in the request's or document's i18n provider. */
+export function localizedRouterRoot(
+  Root: ComponentBody<{ router: AnyRouter }>,
+): ComponentBody<LocalizedRouterProps> {
+  return ({ router, i18n }) =>
+    createElement(I18nProvider, {
+      instance: i18n.instance as I18nInstanceLike,
+      languages: i18n.languages,
+      localisedUrls: i18n.localisedUrls,
+      children: createElement(Root, { router }),
+    });
+}

package/src/entry-client.ts

@@ -0,0 +1,80 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  type NativeClientEntryOptions,
+  type NativeI18nInstance,
+  startNativeClientEntry,
+} from '@modern-js/renderer-core/entry-client';
+import { createNativeRouter } from '@modern-js/renderer-core/router';
+import type { ComponentBody } from 'octane';
+import {
+  hydrateOctaneApplication,
+  mountOctaneApplication,
+  type OctaneApplicationModule,
+  readOctaneDocumentBootstrap,
+} from './client';
+import {
+  componentView,
+  localizedRouterRoot,
+  octaneRouterFactory,
+} from './entry-application';
+import {
+  OctaneRouterRoot,
+  prepareOctaneRouterHydration,
+} from './router-client';
+
+export interface OctaneClientEntryOptions
+  extends NativeClientEntryOptions<NativeI18nInstance, LocalisedUrlsOption> {
+  /** The native client compilation hash, `__webpack_hash__`. */
+  readonly nativeHydrationBuildId: string;
+}
+
+const LocalizedRouterRoot = localizedRouterRoot(OctaneRouterRoot);
+
+/** Start a generated Octane browser entry: mount, or hydrate the server document. */
+export function startNativeClient(options: OctaneClientEntryOptions): void {
+  const { nativeHydrationBuildId } = options;
+  startNativeClientEntry(options, {
+    readBootstrap: (document, identity) =>
+      readOctaneDocumentBootstrap(document, identity, nativeHydrationBuildId),
+    createRouter: (application, routerOptions) =>
+      createNativeRouter(application, routerOptions, octaneRouterFactory),
+    async prepareRouter(router, hydrating, signal) {
+      // Hydration adopts the server's matches; a fresh mount loads its own.
+      if (hydrating) await prepareOctaneRouterHydration(router, { signal });
+      else await router.load();
+    },
+    async start({ root, identity, bootstrap, signal, load }) {
+      const application = {
+        container: root,
+        identity,
+        nativeHydrationBuildId,
+        federation: options.federation,
+        signal,
+        // Hydration installs the native signal bridge before this importer runs.
+        load: async (): Promise<OctaneApplicationModule> => {
+          const view = await load();
+          if (view.kind === 'component')
+            return { default: componentView(view.component, view.i18n) };
+          return view.i18n
+            ? {
+                default: LocalizedRouterRoot as ComponentBody,
+                props: { router: view.router, i18n: view.i18n },
+              }
+            : {
+                default: OctaneRouterRoot as ComponentBody,
+                props: { router: view.router },
+              };
+        },
+      };
+      const handle = bootstrap?.hydrating
+        ? await hydrateOctaneApplication({
+            ...application,
+            documentIdentity: bootstrap.identity,
+            documentId: bootstrap.documentId,
+            documentNativeHydrationBuildId: bootstrap.nativeHydrationBuildId,
+          })
+        : await mountOctaneApplication(application);
+      return () => handle.dispose();
+    },
+  });
+}