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

package/src/i18n/languageSync.ts

@@ -0,0 +1,132 @@
+import {
+  createLatestLanguageSyncBinding,
+  type LanguageSyncFailure,
+  type LanguageSyncPolicy,
+} from '@modern-js/i18n-runtime-extensions/language-sync/controller';
+import { hookSlots, useCallback, useEffect, useRef } from 'octane';
+
+export interface OctaneLatestLanguageSyncOptions<TTarget extends object> {
+  changeLanguage: (
+    target: TTarget,
+    language: string,
+  ) => PromiseLike<unknown> | unknown;
+  commitLanguage: (target: TTarget, language: string) => void;
+  desiredLanguage?: string;
+  enabled?: boolean;
+  policy?: LanguageSyncPolicy;
+  readLanguage?: (target: TTarget) => string | undefined;
+  reportFailure?: (failure: LanguageSyncFailure) => void;
+  target?: TTarget;
+}
+
+// Plain TypeScript is not rewritten by the Octane compiler, so each hook call
+// site carries its own stable slot.
+const bindingSlot = Symbol(hookSlots(1));
+const callbacksSlot = Symbol(hookSlots(1));
+const activationSlot = Symbol(hookSlots(1));
+const requestSlot = Symbol(hookSlots(1));
+const retrySlot = Symbol(hookSlots(1));
+const requestCallbackSlot = Symbol(hookSlots(1));
+
+/**
+ * Octane binding over the fork's renderer-neutral `Coordinator`/`Binding`
+ * pair (`@modern-js/i18n-runtime-extensions`'s `createLatestLanguageSyncBinding`):
+ * the same "latest intent wins, retry with backoff, report terminal failure"
+ * policy the React `useLatestLanguageSync` hook drives.
+ *
+ * Octane's own hook API (`useState`/`useEffect`/`useContext`/
+ * `useSyncExternalStore`, confirmed in `node_modules/octane/dist/runtime.d.ts`)
+ * is React-shaped, so this binding mirrors
+ * `i18n-extensions/src/language-sync/react.ts`'s `useLatestLanguageSync`
+ * directly — the Solid binding needed a `createEffect`/`onCleanup`
+ * reshaping for Solid 2's different (compute/effect-split, no
+ * `useEffect`-style dependency arrays) reactivity model; Octane does not.
+ */
+export const useLatestLanguageSync = <TTarget extends object>({
+  changeLanguage,
+  commitLanguage,
+  desiredLanguage,
+  enabled = true,
+  policy,
+  readLanguage,
+  reportFailure,
+  target,
+}: OctaneLatestLanguageSyncOptions<TTarget>): ((language: string) => void) => {
+  const bindingRef = useRef<ReturnType<
+    typeof createLatestLanguageSyncBinding<TTarget>
+  > | null>(null, bindingSlot);
+  if (bindingRef.current === null) {
+    bindingRef.current = createLatestLanguageSyncBinding<TTarget>(policy);
+  }
+  const binding = bindingRef.current;
+
+  useEffect(
+    () => {
+      binding.updateCallbacks({
+        changeLanguage,
+        commitLanguage,
+        readLanguage,
+        reportFailure,
+      });
+    },
+    undefined,
+    callbacksSlot,
+  );
+
+  useEffect(
+    () => {
+      if (!enabled || !target) {
+        return;
+      }
+      binding.activate(target);
+      return () => binding.deactivate();
+    },
+    [binding, enabled, target],
+    activationSlot,
+  );
+
+  useEffect(
+    () => {
+      if (!enabled || !target || !desiredLanguage) {
+        binding.clearRequest();
+        return;
+      }
+      binding.request(desiredLanguage);
+    },
+    [binding, desiredLanguage, enabled, target],
+    requestSlot,
+  );
+
+  useEffect(
+    () => {
+      if (
+        !enabled ||
+        !target ||
+        !desiredLanguage ||
+        typeof window === 'undefined'
+      ) {
+        return;
+      }
+      const retryCurrentIntent = () => binding.request(desiredLanguage);
+      const retryVisibleIntent = () => {
+        if (document.visibilityState === 'visible') {
+          retryCurrentIntent();
+        }
+      };
+      window.addEventListener('online', retryCurrentIntent);
+      document.addEventListener('visibilitychange', retryVisibleIntent);
+      return () => {
+        window.removeEventListener('online', retryCurrentIntent);
+        document.removeEventListener('visibilitychange', retryVisibleIntent);
+      };
+    },
+    [binding, desiredLanguage, enabled, target],
+    retrySlot,
+  );
+
+  return useCallback(
+    (language: string) => binding.request(language),
+    [binding],
+    requestCallbackSlot,
+  );
+};

package/src/i18n/types.ts

@@ -0,0 +1,36 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+
+/**
+ * The slice of an i18next-shaped instance this binding needs. Deliberately
+ * not `@modern-js/plugin-i18n`'s `I18nInstance`: that type is intentionally
+ * narrowed (no index signature, non-overloaded methods — see plugin-i18n's
+ * fork notes) and, more importantly, the plugin package's peer dependencies
+ * require React/ReactDOM, which an Octane-only application must never need
+ * to install. `on`/`off` are real i18next `EventEmitter` methods this
+ * interface adds back for the reactive `languageChanged` subscription.
+ */
+export interface I18nInstanceLike {
+  language: string;
+  t(key: string | string[], options?: Record<string, unknown>): string;
+  changeLanguage?(lng?: string): Promise<unknown> | unknown;
+  on?(event: 'languageChanged', callback: (lng: string) => void): void;
+  off?(event: 'languageChanged', callback: (lng: string) => void): void;
+  /** SSR per-request isolation: the server clones a base instance per request. */
+  cloneInstance?(options?: Record<string, unknown>): I18nInstanceLike;
+}
+
+export interface I18nContextValue {
+  /** Per-request instance. Never a module-level singleton. */
+  instance: I18nInstanceLike;
+  languages: readonly string[];
+  localisedUrls?: LocalisedUrlsOption;
+  /**
+   * Reactive current language, owned by `I18nProvider`'s own `useState` +
+   * one `languageChanged` subscription. `instance.language` is a plain
+   * mutable field, not itself reactive — Octane's context only re-renders
+   * consumers when the Provider commits a *new* `value` object (its
+   * `$$version` bumps), so every consumer reads this field off the context
+   * value instead of reaching into `instance.language` directly.
+   */
+  language: string;
+}

package/src/i18n/useI18n.ts

@@ -0,0 +1,119 @@
+import {
+  configuredLanguage,
+  localizePath,
+} from '@modern-js/i18n-runtime-extensions/paths';
+import { languageFromPathname } from '@modern-js/i18n-runtime-extensions/request-language';
+import { useContext } from 'octane';
+import { useRouter } from '../router';
+import { I18nContext } from './context';
+import type { I18nInstanceLike } from './types';
+
+export interface UseI18nReturn {
+  t: I18nInstanceLike['t'];
+  /** Current language. Re-renders the calling component on `languageChanged`. */
+  language: string;
+  languages: readonly string[];
+  /** The raw per-request instance, for advanced use (namespaces, `exists`, ...). */
+  instance: I18nInstanceLike;
+  /**
+   * Switches the i18next instance's language. With a router, also navigates to
+   * the localized path so the URL and active language stay aligned.
+   */
+  changeLanguage: (language: string) => Promise<void>;
+}
+
+/**
+ * Language switches per instance run one at a time: a switch that a newer
+ * one has superseded before it starts is skipped, so no two switches ever
+ * interleave their language loads and navigations.
+ */
+const languageSwitches = new WeakMap<
+  object,
+  { latest: number; queue: Promise<void> }
+>();
+
+/**
+ * Must render under `I18nProvider`; throws rather than silently reading a
+ * fallback instance when no provider is mounted (Octane's `createContext`
+ * requires a default value, so `I18nContext`'s default is `null` and this
+ * hook turns that into a loud error instead of a shared singleton).
+ */
+export function useI18n(): UseI18nReturn {
+  const context = useContext(I18nContext);
+  if (!context) {
+    throw new Error(
+      '[renderer-octane] useI18n() was called outside of an I18nProvider.',
+    );
+  }
+  const { instance, languages, localisedUrls, language } = context;
+
+  const t: I18nInstanceLike['t'] = (key, options) => instance.t(key, options);
+
+  const router = useRouter({ warn: false });
+
+  const changeLanguage = (requested: string): Promise<void> => {
+    // i18next would fall back silently and the URL would gain an unknown
+    // segment. An unsupported request is rejected before it supersedes any
+    // queued switch.
+    let nextLanguage: string;
+    try {
+      nextLanguage = configuredLanguage(requested, languages);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    const state = languageSwitches.get(instance) ?? {
+      latest: 0,
+      queue: Promise.resolve(),
+    };
+    languageSwitches.set(instance, state);
+    const generation = ++state.latest;
+    const run = state.queue.then(async () => {
+      if (state.latest !== generation) return;
+      // Earlier switches have settled, so this is the language the current
+      // URL was committed with.
+      const committed = instance.language;
+      // The public URL carries the locale. Under the i18n URL rewrite the
+      // router's own location is canonical and has none.
+      const publicLanguage = () =>
+        router
+          ? languageFromPathname(
+              new URL(router.state.location.publicHref, 'http://localhost')
+                .pathname,
+              languages,
+              router.options.basepath,
+            )
+          : undefined;
+      // A failed, blocked or redirected switch leaves the page on some URL;
+      // the language follows that URL's locale, or the committed language on
+      // a URL without one.
+      const reconcile = async () => {
+        const language = publicLanguage() ?? committed;
+        if (instance.language !== language)
+          await instance.changeLanguage?.(language);
+      };
+      try {
+        await instance.changeLanguage?.(nextLanguage);
+      } catch (error) {
+        await reconcile();
+        throw error;
+      }
+      if (!router) return;
+      // The full href keeps the query and fragment across the language switch.
+      const href = localizePath(router.state.location.href, nextLanguage, {
+        languages: [...languages],
+        localisedUrls,
+      });
+      try {
+        await router.navigate({ to: '.', href, replace: true });
+      } catch (error) {
+        await reconcile();
+        throw error;
+      }
+      if (publicLanguage() !== nextLanguage) await reconcile();
+    });
+    state.queue = run.catch(() => {});
+    return run;
+  };
+
+  return { t, language, languages, instance, changeLanguage };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export type { RendererIdentity } from '@modern-js/renderer-core/identity';
+export type { OctaneDocumentBootstrap } from './bootstrap';
+
+export const OCTANE_RUNTIME_PROFILE = Object.freeze({
+  renderer: 'octane',
+  runtime: '0.7.1+ultramodern.1331985ea3b0',
+  router: '0.1.60+ultramodern.0b9f76ee3003',
+  routerCore: '1.171.15',
+  history: '1.162.0',
+});

package/src/manifest.ts

@@ -0,0 +1,253 @@
+import type { NativeCompilerArtifacts } from '@modern-js/renderer-core/adapter';
+import {
+  nativeModuleManifestFilename,
+  type RendererIdentity,
+  readRendererIdentity,
+} from '@modern-js/renderer-core/identity';
+import {
+  assertNativeHydrationBuildId,
+  assertOctaneIdentity,
+} from './bootstrap';
+
+export const OCTANE_RUNTIME_VERSION = '0.7.1+ultramodern.1331985ea3b0';
+export const OCTANE_COMPILER_VERSION = '0.1.55';
+
+export interface OctaneCompiledSource {
+  readonly resource: string;
+  readonly canonicalId: string;
+  readonly moduleId: string | number;
+  readonly transformKind: 'compile' | 'slots' | 'client-only-stub';
+  readonly emittedSourceSha256: string;
+  readonly assets: readonly string[];
+}
+
+export interface OctaneModuleManifest {
+  readonly schemaVersion: 1;
+  readonly renderer: 'octane';
+  readonly runtimeVersion: typeof OCTANE_RUNTIME_VERSION;
+  readonly compilerVersion: typeof OCTANE_COMPILER_VERSION;
+  readonly rendererIdentity: Readonly<RendererIdentity>;
+  readonly nativeHydrationBuildId: string;
+  readonly sourceModules: readonly OctaneCompiledSource[];
+  readonly assets: readonly {
+    readonly file: string;
+    readonly sha256: string;
+  }[];
+}
+
+export function octaneModuleManifestFileName(entryName: string): string {
+  return nativeModuleManifestFilename('octane', entryName);
+}
+
+function record(
+  value: unknown,
+  fields: readonly string[],
+): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Malformed Octane compiler manifest object.');
+  }
+  if (Object.keys(value).some(key => !fields.includes(key))) {
+    throw new Error('Octane compiler manifest contains an unknown field.');
+  }
+  return value as Record<string, unknown>;
+}
+
+function digest(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f\d]{64}$/u.test(value);
+}
+
+function nonempty(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.trim().length > 0 &&
+    !value.includes('\0')
+  );
+}
+
+function assetPath(value: unknown): value is string {
+  return (
+    nonempty(value) &&
+    value.endsWith('.js') &&
+    !value.startsWith('/') &&
+    !value.includes('\\') &&
+    !value.split('/').some(part => part === '..' || part === '.' || !part)
+  );
+}
+
+/** A build's manifest is an immutable artifact: its shape is checked once. */
+const validatedManifests = new WeakMap<object, OctaneModuleManifest>();
+
+/** Validates completed native bytes separately from the source/profile build. */
+export function validateOctaneModuleManifest(
+  value: unknown,
+  expectedIdentity: RendererIdentity,
+  expectedNativeHydrationBuildId?: string,
+): OctaneModuleManifest {
+  assertOctaneIdentity(expectedIdentity);
+  const cached =
+    value && typeof value === 'object'
+      ? validatedManifests.get(value)
+      : undefined;
+  const manifest = cached ?? readOctaneModuleManifest(value);
+  readRendererIdentity(manifest.rendererIdentity, expectedIdentity);
+  if (expectedNativeHydrationBuildId !== undefined) {
+    assertNativeHydrationBuildId(expectedNativeHydrationBuildId);
+    if (manifest.nativeHydrationBuildId !== expectedNativeHydrationBuildId) {
+      throw new Error(
+        'Octane native hydration build differs from the compiled client.',
+      );
+    }
+  }
+  if (!cached) {
+    validatedManifests.set(value as object, manifest);
+    validatedManifests.set(manifest, manifest);
+  }
+  return manifest;
+}
+
+function readOctaneModuleManifest(value: unknown): OctaneModuleManifest {
+  const manifest = record(value, [
+    'schemaVersion',
+    'renderer',
+    'runtimeVersion',
+    'compilerVersion',
+    'rendererIdentity',
+    'nativeHydrationBuildId',
+    'sourceModules',
+    'assets',
+  ]);
+  if (
+    manifest.schemaVersion !== 1 ||
+    manifest.renderer !== 'octane' ||
+    manifest.runtimeVersion !== OCTANE_RUNTIME_VERSION ||
+    manifest.compilerVersion !== OCTANE_COMPILER_VERSION
+  ) {
+    throw new Error(
+      'Octane compiler manifest ABI conflicts with the application.',
+    );
+  }
+  // The caller compares this well-formed record with its expected identity.
+  const rendererIdentity = readRendererIdentity(
+    manifest.rendererIdentity,
+    manifest.rendererIdentity as RendererIdentity,
+  );
+  const nativeHydrationBuildId = manifest.nativeHydrationBuildId;
+  assertNativeHydrationBuildId(nativeHydrationBuildId);
+  if (!Array.isArray(manifest.assets) || !manifest.assets.length) {
+    throw new Error(
+      'Octane compiler manifest has no emitted JavaScript closure.',
+    );
+  }
+  const assetNames = new Set<string>();
+  const assets = manifest.assets.map(value => {
+    const asset = record(value, ['file', 'sha256']);
+    if (
+      !assetPath(asset.file) ||
+      !digest(asset.sha256) ||
+      assetNames.has(asset.file)
+    ) {
+      throw new Error('Invalid Octane emitted asset digest.');
+    }
+    assetNames.add(asset.file);
+    return Object.freeze({ file: asset.file, sha256: asset.sha256 });
+  });
+  if (
+    !Array.isArray(manifest.sourceModules) ||
+    !manifest.sourceModules.length
+  ) {
+    throw new Error(
+      'Octane compiler manifest has no authenticated native sources.',
+    );
+  }
+  const resources = new Set<string>();
+  const sourceModules = manifest.sourceModules.map(value => {
+    const source = record(value, [
+      'resource',
+      'canonicalId',
+      'moduleId',
+      'transformKind',
+      'emittedSourceSha256',
+      'assets',
+    ]);
+    if (
+      !nonempty(source.resource) ||
+      source.resource.startsWith('/') ||
+      source.resource.includes('\\') ||
+      !nonempty(source.canonicalId) ||
+      !(
+        (typeof source.moduleId === 'string' && nonempty(source.moduleId)) ||
+        (typeof source.moduleId === 'number' &&
+          Number.isFinite(source.moduleId))
+      ) ||
+      !(
+        source.transformKind === 'compile' ||
+        source.transformKind === 'slots' ||
+        source.transformKind === 'client-only-stub'
+      ) ||
+      !digest(source.emittedSourceSha256) ||
+      !Array.isArray(source.assets) ||
+      !source.assets.length ||
+      source.assets.some(
+        file => typeof file !== 'string' || !assetNames.has(file),
+      ) ||
+      new Set(source.assets).size !== source.assets.length ||
+      resources.has(source.resource)
+    ) {
+      throw new Error('Invalid Octane native source-to-asset provenance.');
+    }
+    resources.add(source.resource);
+    return Object.freeze({
+      resource: source.resource,
+      canonicalId: source.canonicalId,
+      moduleId: source.moduleId,
+      transformKind: source.transformKind,
+      emittedSourceSha256: source.emittedSourceSha256,
+      assets: Object.freeze([...source.assets] as string[]),
+    });
+  });
+  return Object.freeze({
+    schemaVersion: 1,
+    renderer: 'octane',
+    runtimeVersion: OCTANE_RUNTIME_VERSION,
+    compilerVersion: OCTANE_COMPILER_VERSION,
+    rendererIdentity,
+    nativeHydrationBuildId,
+    sourceModules: Object.freeze(sourceModules),
+    assets: Object.freeze(assets),
+  });
+}
+
+/**
+ * The compiler artifact ABI. It lives in this runtime module, not in the
+ * build-only `./plugin`, because the production server validates manifests
+ * with it and deployments trace it from there.
+ */
+export const compilerArtifacts: NativeCompilerArtifacts = {
+  clientManifestFile: octaneModuleManifestFileName,
+  async validateClientManifest(value, identity, context) {
+    const hydrationBuildId =
+      context.compilationHash ?? context.hydrationBuildId;
+    if (
+      context.development &&
+      (typeof hydrationBuildId !== 'string' || !hydrationBuildId.trim())
+    )
+      throw new Error(
+        'Octane development snapshot has no native hydration build.',
+      );
+    const nativeManifest = validateOctaneModuleManifest(
+      value,
+      identity,
+      hydrationBuildId,
+    );
+    return {
+      nativeManifest,
+      hydrationBuildId: nativeManifest.nativeHydrationBuildId,
+    };
+  },
+  isMutableDevelopmentAsset(filename, entryNames) {
+    return (
+      filename === 'octane-client-build.json' ||
+      entryNames.some(entry => filename === octaneModuleManifestFileName(entry))
+    );
+  },
+};