@bleedingdev/modern-js-renderer-octane 0.0.0-stage → 3.9.3-ultramodern.2

package/src/entry-server.ts

@@ -0,0 +1,142 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  collectDataHeaders,
+  dataMetadataToDocumentPolicy,
+  mergeDataResponseIntoResponse,
+  mergeDataResponseMetadata,
+  mergeHeaderFields,
+} from '@modern-js/renderer-core/data';
+import {
+  createNativeServerEntry as createServerEntry,
+  type NativeI18nInstance,
+  type NativeServerEntry,
+  type NativeServerEntryOptions,
+} from '@modern-js/renderer-core/entry-server';
+import { createNativeRouter } from '@modern-js/renderer-core/router';
+import type { ResponsePolicy } from '@modern-js/renderer-core/session';
+import type { ServerRenderNode } from 'octane/server';
+import {
+  componentView,
+  localizedRouterRoot,
+  octaneRouterFactory,
+} from './entry-application';
+import { validateOctaneModuleManifest } from './manifest';
+import {
+  createOctaneRequestHandler,
+  createOctaneRouterInjection,
+  createSsrStreamResponse,
+  OctaneRouterServer,
+} from './router-server';
+import { renderOctaneApplication, renderOctaneCSRDocument } from './server';
+
+/** Document-describing fields an Octane route's `headers()` may set. */
+const OCTANE_DOCUMENT_FIELDS = new Set([
+  'content-language',
+  'content-location',
+  'content-disposition',
+]);
+
+/**
+ * The loader projection strips representation fields; the ones an Octane route
+ * declares for the document itself are kept, as Solid document headers are.
+ */
+export function withOctaneDocumentFields(
+  policy: ResponsePolicy,
+  responseHeaders: Headers,
+): ResponsePolicy {
+  const fields = collectDataHeaders(responseHeaders).filter(([name]) =>
+    OCTANE_DOCUMENT_FIELDS.has(name.toLowerCase()),
+  );
+  return fields.length
+    ? { ...policy, headers: [...policy.headers, ...fields] }
+    : policy;
+}
+
+export type OctaneServerEntryOptions = NativeServerEntryOptions<
+  NativeI18nInstance,
+  LocalisedUrlsOption
+>;
+
+const LocalizedRouterServer = localizedRouterRoot(OctaneRouterServer);
+
+/** The native transport handlers of a generated Octane server entry. */
+export function createNativeServerEntry(
+  options: OctaneServerEntryOptions,
+): NativeServerEntry {
+  return createServerEntry(options, {
+    document: (document, nativeManifest, identity) => ({
+      ...document,
+      nativeHydrationBuildId: validateOctaneModuleManifest(
+        nativeManifest,
+        identity,
+      ).nativeHydrationBuildId,
+    }),
+    run: (_session, callback) => callback(),
+    respond: (_session, response) => response,
+    createRouter: (application, routerOptions) =>
+      createNativeRouter(application, routerOptions, octaneRouterFactory),
+    renderCSR: ({ session }, document) =>
+      renderOctaneCSRDocument({ session, document }),
+    renderComponent: ({ session }, component, document, i18n) =>
+      renderOctaneApplication({
+        session,
+        App: componentView(component, i18n) as ServerRenderNode,
+        document,
+        federation: options.federation,
+      }),
+    async renderRoutes({
+      request,
+      context: { session },
+      router,
+      outcomes,
+      document,
+      forbiddenValues,
+      i18n,
+    }) {
+      const response = await createOctaneRequestHandler({
+        request,
+        session,
+        createRouter: () => router,
+        serialization: { forbiddenValues },
+      })(async ({ router, responseHeaders }) => {
+        const metadata = mergeDataResponseMetadata(outcomes, {
+          status: router.state.statusCode ?? 200,
+        });
+        // Route headers() take precedence over loader singleton fields; list
+        // fields keep both.
+        const policy = dataMetadataToDocumentPolicy({
+          ...metadata,
+          headers: mergeHeaderFields(
+            collectDataHeaders(responseHeaders),
+            metadata.headers,
+          ),
+        });
+        session.resolveResponse(
+          withOctaneDocumentFields(policy, responseHeaders),
+        );
+        const rendered = await renderOctaneApplication({
+          session,
+          ...(i18n
+            ? {
+                App: LocalizedRouterServer as ServerRenderNode,
+                props: { router, i18n },
+              }
+            : {
+                App: OctaneRouterServer as ServerRenderNode,
+                props: { router },
+              }),
+          document,
+          federation: options.federation,
+          injection: createOctaneRouterInjection(router, session),
+        });
+        return createSsrStreamResponse(router, rendered);
+      });
+      return session.committedPolicy
+        ? response
+        : mergeDataResponseIntoResponse(
+            response,
+            mergeDataResponseMetadata(outcomes, { status: response.status }),
+          );
+    },
+  });
+}

package/src/federation-context.ts

@@ -0,0 +1,53 @@
+import {
+  type FederationInstance,
+  getFederationHost,
+  type NativeFederationBinding,
+} from '@modern-js/renderer-core/federation';
+import { type ComponentBody, createContext, createElement } from 'octane';
+
+/** One application owns its host runtime; each response owns its render scope. */
+export interface OctaneFederationScope {
+  readonly instance: FederationInstance | undefined;
+  readonly server: boolean;
+  readonly nonce?: string;
+}
+
+export const FederationContext = createContext<OctaneFederationScope | null>(
+  null,
+);
+
+export function createFederationScope(
+  binding: NativeFederationBinding | undefined,
+  server: boolean,
+  nonce?: string,
+): OctaneFederationScope {
+  return {
+    instance: getFederationHost(binding),
+    server,
+    ...(nonce === undefined ? {} : { nonce }),
+  };
+}
+
+export function FederationRoot(props: {
+  readonly scope: OctaneFederationScope;
+  readonly children?: unknown;
+}) {
+  return createElement(FederationContext, {
+    value: props.scope,
+    children: props.children,
+  });
+}
+
+/** A stable root component retains native state when its application updates. */
+export function FederationApplication(props: {
+  readonly scope: OctaneFederationScope;
+  readonly application: {
+    readonly default: ComponentBody;
+    readonly props?: unknown;
+  };
+}) {
+  return createElement(FederationRoot, {
+    scope: props.scope,
+    children: createElement(props.application.default, props.application.props),
+  });
+}

package/src/federation.ts

@@ -0,0 +1,158 @@
+import {
+  loadFederatedModule,
+  remoteBrowserAssets,
+} from '@modern-js/renderer-core/federation';
+import {
+  type ComponentBody,
+  createElement,
+  lazy,
+  type OctaneNode,
+  preinit,
+  Suspense,
+  useContext,
+} from 'octane';
+import {
+  FederationContext,
+  type OctaneFederationScope,
+} from './federation-context';
+
+/** The native component shape exposed by a same-renderer Octane remote. */
+export interface FederatedModule<P extends object> {
+  readonly default: ComponentBody<P>;
+}
+
+export interface FederatedComponentOptions {
+  /** Native content shown while loading, or after a failed server load. */
+  readonly fallback?: () => OctaneNode;
+  /** A positive load limit; the server defaults to 3000ms. */
+  readonly timeout?: number;
+}
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeout: number | undefined,
+  label: string,
+): Promise<T> {
+  if (timeout === undefined) return promise;
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () =>
+        reject(
+          new Error(`Remote module ${label} did not load within ${timeout}ms`),
+        ),
+      timeout,
+    );
+    (timer as { unref?: () => void }).unref?.();
+    promise.then(
+      value => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      error => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Render a native Octane remote by its `remote/Expose` id or a browser loader.
+ * Native Suspense owns server fallbacks, streamed styles and hydration adoption;
+ * browser failures reach the nearest native ErrorBoundary. A loader function is
+ * browser-only; use an id to render through the host's server federation runtime.
+ */
+export function federatedComponent<P extends object = Record<string, never>>(
+  remote: string | (() => Promise<FederatedModule<P>>),
+  options: FederatedComponentOptions = {},
+): ComponentBody<P> {
+  if (
+    typeof remote === 'string'
+      ? !/^[^/]+\/.+/u.test(remote)
+      : typeof remote !== 'function'
+  ) {
+    throw new TypeError(
+      "federatedComponent requires a remote id such as 'remote/Widget' or a loader",
+    );
+  }
+  if (
+    options.timeout !== undefined &&
+    (!Number.isFinite(options.timeout) || options.timeout <= 0)
+  ) {
+    throw new TypeError(
+      'federatedComponent timeout must be a positive number of milliseconds',
+    );
+  }
+  const id = typeof remote === 'string' ? remote : undefined;
+  const standalone: OctaneFederationScope = {
+    instance: undefined,
+    server: typeof document === 'undefined',
+  };
+  // 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>>();
+
+  return props => {
+    const context = useContext(FederationContext) ?? standalone;
+    let Remote = components.get(context);
+    if (!Remote) {
+      Remote = lazy(async () => {
+        try {
+          if (context.server && !id) {
+            throw new Error(
+              'A federatedComponent loader renders in the browser only; use a remote id to server-render it',
+            );
+          }
+          const module = await withTimeout(
+            Promise.resolve().then(() =>
+              id
+                ? loadFederatedModule<FederatedModule<P>>(context.instance, id)
+                : (remote as () => Promise<FederatedModule<P>>)(),
+            ),
+            options.timeout ?? (context.server ? 3000 : undefined),
+            id ?? 'loader',
+          );
+          if (typeof module?.default !== 'function') {
+            throw new TypeError(
+              '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;
+          const Loaded: ComponentBody<P> = props => {
+            // 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 ?? []) {
+              preinit(href, {
+                as: 'style',
+                precedence: 'federated',
+                ...(context.nonce === undefined
+                  ? {}
+                  : { nonce: context.nonce }),
+              });
+            }
+            return createElement(component, props);
+          };
+          return { default: Loaded };
+        } catch (error) {
+          // A later mount or ErrorBoundary reset may retry a failed load.
+          if (!context.server) components.delete(context);
+          throw error;
+        }
+      });
+      components.set(context, Remote);
+    }
+    return createElement(Suspense, {
+      fallback: options.fallback,
+      children: createElement(Remote, props),
+    });
+  };
+}

package/src/i18n/I18nProvider.ts

@@ -0,0 +1,56 @@
+import { createElement, hookSlots, useEffect, useState } from 'octane';
+import { I18nContext } from './context';
+import type { I18nContextValue, I18nInstanceLike } from './types';
+
+export interface I18nProviderProps extends Omit<I18nContextValue, 'language'> {
+  children?: unknown;
+}
+
+/**
+ * Provides a per-request i18next-shaped instance to the Octane tree. The
+ * instance must come from the caller (created with `cloneInstance` per
+ * request on the server, and the same instance reused on hydration) — this
+ * provider holds no module-level state of its own beyond the one reactive
+ * `language` state it derives from `instance` and shares with every
+ * consumer through context, matching `@modern-js/plugin-i18n`'s React
+ * `ModernI18nProvider` shape (one subscription, pushed through context,
+ * rather than every consumer subscribing to `languageChanged` itself).
+ *
+ * No JSX: built with `createElement`, matching this package's existing
+ * style (see `src/routes.ts`), and avoiding any dependency on Octane's
+ * JSX/compiler toolchain for a file that needs none of its features.
+ */
+// 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));
+
+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);
+      };
+    },
+    [props.instance],
+    languageSubscriptionSlot,
+  );
+
+  const value: I18nContextValue = {
+    instance: props.instance,
+    languages: props.languages,
+    localisedUrls: props.localisedUrls,
+    language,
+  };
+
+  return createElement(I18nContext, { value, children: props.children });
+}

package/src/i18n/LocalizedLink.ts

@@ -0,0 +1,112 @@
+import {
+  canonicalPath,
+  configuredLanguage,
+  localizePath,
+} from '@modern-js/i18n-runtime-extensions/paths';
+import { createElement, hookSlots, type OctaneNode, useContext } from 'octane';
+import {
+  Link,
+  type LinkComponentProps,
+  useLocation,
+  useRouter,
+} from '../router';
+import { I18nContext } from './context';
+
+// Plain TypeScript is not rewritten by the Octane compiler: router hooks take
+// their stable slot explicitly.
+const locationSlot = Symbol(hookSlots(1));
+
+export interface LocalizedLinkProps {
+  /** A canonical, language-agnostic target, e.g. `/products/red-shoe`. */
+  to: string;
+  /** Localize for a specific language instead of the current one. */
+  language?: string;
+  children?: unknown;
+  class?: string;
+  activeProps?: LinkComponentProps<'a'>['activeProps'];
+  inactiveProps?: LinkComponentProps<'a'>['inactiveProps'];
+  activeOptions?: LinkComponentProps<'a'>['activeOptions'];
+  replace?: boolean;
+  preload?: LinkComponentProps<'a'>['preload'];
+}
+
+/**
+ * A thin wrapper over the native Octane router `Link`
+ * (`@octanejs/tanstack-router`'s precompiled `Link.tsrx`) that localizes a
+ * canonical `to` for the current (or an explicit) language before handing it
+ * to the real link — the same contract as `@modern-js/plugin-i18n`'s React
+ * `Link`. It resolves the href itself via the shared pathname helpers, so it
+ * works with or without the router's i18n `rewrite`. Every link, including
+ * one to another language, is the native `Link`: navigation, preloading and
+ * active state stay with the router.
+ *
+ * Under the i18n `rewrite` the router matches canonical paths and localizes
+ * outgoing locations to the current language, so a link to another language
+ * routes to the canonical `to` and publishes the target language's URL as a
+ * route mask (the rewrite keeps a mask's explicit language). The entry's
+ * router language synchronization (`syncWithRouter`) switches the i18next
+ * instance from the navigated URL, as it does for history navigation.
+ *
+ * No JSX: built with `createElement`, matching this package's existing
+ * style (see `src/routes.ts`).
+ */
+export function LocalizedLink(props: LocalizedLinkProps): OctaneNode {
+  const context = useContext(I18nContext);
+  if (!context) {
+    throw new Error(
+      '[renderer-octane] LocalizedLink was used outside of an I18nProvider.',
+    );
+  }
+  const router = useRouter();
+
+  // An explicit language must be configured: it becomes the locale prefix.
+  const language =
+    props.language === undefined
+      ? context.language
+      : configuredLanguage(props.language, context.languages);
+  const href = localizePath(props.to, language, {
+    languages: [...context.languages],
+    localisedUrls: context.localisedUrls,
+  });
+  const crossLanguage = language !== context.language;
+  const rewrite = Boolean(router.options.rewrite);
+
+  return createElement(
+    Link,
+    {
+      // Octane's `Link` builds its location from `to` alone. Under the i18n
+      // router rewrite the router matches canonical paths and localizes the
+      // public href itself; without it, the localized path is the route path.
+      to: rewrite ? props.to : href,
+      ...(rewrite && crossLanguage ? { mask: { to: href } } : {}),
+      ...(crossLanguage ? { hreflang: language } : {}),
+      class: props.class,
+      activeProps: props.activeProps,
+      inactiveProps: props.inactiveProps,
+      activeOptions: props.activeOptions,
+      replace: props.replace,
+      preload: props.preload,
+    },
+    props.children,
+  );
+}
+
+/**
+ * Language-invariant active check: `to="/products"` is active whether the
+ * current location is `/en/products` or `/produkty` under a mapped locale.
+ */
+export function useIsLocalizedActive(canonicalTarget: string): boolean {
+  const context = useContext(I18nContext);
+  if (!context) {
+    throw new Error(
+      '[renderer-octane] useIsLocalizedActive was used outside of an I18nProvider.',
+    );
+  }
+  const location = useLocation(undefined, locationSlot);
+  return (
+    canonicalPath(location.pathname, {
+      languages: [...context.languages],
+      localisedUrls: context.localisedUrls,
+    }) === canonicalTarget
+  );
+}

package/src/i18n/context.ts

@@ -0,0 +1,12 @@
+import { createContext } from 'octane';
+import type { I18nContextValue } from './types';
+
+export type { I18nContextValue, I18nInstanceLike } from './types';
+
+/**
+ * Octane's `createContext<T>(defaultValue: T)` requires a default (unlike
+ * Solid 2's default-less form), so a missing provider is detected by
+ * checking for `null` in `useI18n`/`useIsLocalizedActive` instead — the same
+ * guard shape `@modern-js/plugin-i18n`'s React `ModernI18nContext` uses.
+ */
+export const I18nContext = createContext<I18nContextValue | null>(null);

package/src/i18n/index.ts

@@ -0,0 +1,35 @@
+export {
+  createRequestLanguageRedirect,
+  detectRequestLanguage,
+  languageFromPathname,
+  type RequestLanguageDetection,
+  type ResolvedRequestLanguage,
+  type ResolveRequestLanguageOptions,
+  resolveRequestLanguage,
+} from '@modern-js/i18n-runtime-extensions/request-language';
+export {
+  createI18nSsrHandoffInlineData,
+  I18N_SSR_HANDOFF_ELEMENT_ID,
+  type I18nSsrHandoffPayload,
+  type I18nSsrHandoffResources,
+  readI18nSsrHandoff,
+} from '@modern-js/i18n-runtime-extensions/ssrLanguageHandoff';
+// Renderer-neutral pieces an application entry composes with these bindings.
+export {
+  type CreateI18nUrlRewriteOptions,
+  createI18nUrlRewrite,
+  type I18nLocationRewrite,
+} from '@modern-js/i18n-runtime-extensions/urlRewrite';
+export { I18nContext } from './context';
+export { I18nProvider, type I18nProviderProps } from './I18nProvider';
+export {
+  LocalizedLink,
+  type LocalizedLinkProps,
+  useIsLocalizedActive,
+} from './LocalizedLink';
+export {
+  type OctaneLatestLanguageSyncOptions,
+  useLatestLanguageSync,
+} from './languageSync';
+export type { I18nContextValue, I18nInstanceLike } from './types';
+export { type UseI18nReturn, useI18n } from './useI18n';