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

package/src/router-snapshot.ts

@@ -0,0 +1,251 @@
+import {
+  assertPublicData,
+  DataProtocolError,
+} from '@modern-js/renderer-core/data';
+import {
+  type AnySerializationAdapter,
+  createSerializationAdapter,
+} from '@octanejs/tanstack-router';
+import { RouteDataError } from './routes';
+
+export const ADAPTER_KEY = 'ultramodern.octane-public-snapshot.v1';
+export const ROUTE_ERROR_KIND = 'ultramodern-route-error';
+export const NATIVE_ERROR_KIND = 'ultramodern-native-error';
+const nativeErrorTypes: Readonly<Record<string, typeof Error>> = Object.freeze({
+  Error,
+  TypeError,
+  RangeError,
+  SyntaxError,
+  ReferenceError,
+  URIError,
+  EvalError,
+});
+export const NATIVE_ROOT_FIELDS = new Set([
+  'manifest',
+  'matches',
+  'lastMatchId',
+  'dehydratedData',
+]);
+export const MATCH_FIELDS = new Set(['i', 'u', 's', 'b', 'l', 'e', 'ssr', 'g']);
+export function invalid(message: string): DataProtocolError {
+  const error = new DataProtocolError(`Octane router snapshot: ${message}`);
+  // Native Seroval may continue parsing this owned diagnostic after cleanup.
+  // Its Error serializer must not request even a lazy native stack accessor.
+  delete error.stack;
+  return error;
+}
+
+export function descriptors(
+  value: object,
+  allowed?: ReadonlySet<string>,
+  allowLazyStack = false,
+): Record<string, PropertyDescriptor> {
+  const result: Record<string, PropertyDescriptor> = Object.create(null);
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (typeof key !== 'string' || (allowed && !allowed.has(key))) {
+      throw invalid('an unsupported own field cannot be transferred');
+    }
+    if (descriptor.get || descriptor.set) {
+      if (key === 'stack' && allowLazyStack) continue;
+      throw invalid('accessors cannot be transferred');
+    }
+    result[key] = descriptor;
+  }
+  return result;
+}
+
+export function record(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null)
+  );
+}
+
+export function stringField(
+  fields: Record<string, PropertyDescriptor>,
+  key: string,
+) {
+  const value: unknown = fields[key]?.value;
+  if (typeof value !== 'string') throw invalid(`${key} must be a string`);
+  return value;
+}
+
+export function nativePromise(value: unknown): value is Promise<unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Promise.prototype
+  );
+}
+
+export function clearStack(error: Error, stack: unknown) {
+  delete error.stack;
+  if (typeof stack === 'string') {
+    Object.defineProperty(error, 'stack', {
+      value: stack,
+      writable: true,
+      configurable: true,
+    });
+  }
+}
+
+function decodeRouteError(error: unknown): unknown {
+  if (!record(error)) return error;
+  const errorFields = descriptors(error);
+  const kind = errorFields['kind']?.value;
+  if (kind !== ROUTE_ERROR_KIND && kind !== NATIVE_ERROR_KIND) return error;
+  if (kind === NATIVE_ERROR_KIND) {
+    descriptors(
+      error,
+      new Set(['kind', 'type', 'name', 'message', 'stack', 'cause']),
+    );
+    assertPublicData(error);
+    const type = stringField(errorFields, 'type');
+    const Constructor = Object.getOwnPropertyDescriptor(nativeErrorTypes, type)
+      ?.value as typeof Error | undefined;
+    if (!Constructor) throw invalid('the native Error type is unsupported');
+    const restored = new Constructor(stringField(errorFields, 'message'));
+    clearStack(restored, errorFields['stack']?.value);
+    Object.defineProperty(restored, 'name', {
+      value: stringField(errorFields, 'name'),
+      writable: true,
+      configurable: true,
+    });
+    if (errorFields['cause'])
+      Object.defineProperty(restored, 'cause', {
+        value: errorFields['cause'].value,
+        writable: true,
+        configurable: true,
+      });
+    return restored;
+  }
+  const expected = new Set([
+    'kind',
+    'routeId',
+    'status',
+    'data',
+    'name',
+    'message',
+    'stack',
+    'cause',
+  ]);
+  descriptors(error, expected);
+  const routeId = stringField(errorFields, 'routeId');
+  const name = stringField(errorFields, 'name');
+  const message = stringField(errorFields, 'message');
+  const status: unknown = errorFields['status']?.value;
+  if (
+    !routeId ||
+    !Number.isInteger(status) ||
+    (status as number) < 400 ||
+    (status as number) > 599
+  ) {
+    throw invalid('a route error has invalid identity or status');
+  }
+  assertPublicData(error);
+  const restored = new RouteDataError(routeId, {
+    kind: 'error',
+    status: status as number,
+    error: { name, message },
+    data: errorFields['data']?.value,
+    thrown: true,
+  });
+  clearStack(restored, errorFields['stack']?.value);
+  if (errorFields['cause']) {
+    Object.defineProperty(restored, 'cause', {
+      value: errorFields['cause'].value,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return restored;
+}
+
+/** Native hydrate installs this decoder before replaying adapter-dependent scripts. */
+function decodeNativeSnapshot(value: unknown): object {
+  if (!record(value)) throw invalid('the native root must be a record');
+  const fields = descriptors(value, NATIVE_ROOT_FIELDS);
+  const matches: unknown = fields['matches']?.value;
+  if (!Array.isArray(matches)) throw invalid('native matches must be an array');
+  const matchFields = descriptors(matches);
+  const promises = new WeakMap<Promise<unknown>, Promise<unknown>>();
+  const loaders = new WeakMap<object, object>();
+  const errors = new WeakMap<object, unknown>();
+  const decodeError = (error: unknown) => {
+    if (error === null || typeof error !== 'object') return error;
+    if (errors.has(error)) return errors.get(error);
+    const restored = decodeRouteError(error);
+    errors.set(error, restored);
+    return restored;
+  };
+  const decodePromise = (promise: Promise<unknown>) => {
+    const previous = promises.get(promise);
+    if (previous) return previous;
+    const restored = Promise.prototype.then.call(
+      promise,
+      undefined,
+      (error: unknown) => {
+        throw decodeError(error);
+      },
+    ) as Promise<unknown>;
+    promises.set(promise, restored);
+    void Promise.prototype.then.call(restored, undefined, () => {});
+    return restored;
+  };
+  const decodeLoader = (loader: unknown): unknown => {
+    if (nativePromise(loader)) return decodePromise(loader);
+    if (!record(loader)) return loader;
+    const properties = descriptors(loader);
+    if (!Object.values(properties).some(field => nativePromise(field.value)))
+      return loader;
+    const previous = loaders.get(loader);
+    if (previous) return previous;
+    const restored = Object.create(Object.getPrototypeOf(loader));
+    loaders.set(loader, restored);
+    for (const [key, field] of Object.entries(properties)) {
+      Object.defineProperty(restored, key, {
+        ...field,
+        value: nativePromise(field.value)
+          ? decodePromise(field.value)
+          : field.value,
+      });
+    }
+    if (!Object.isExtensible(loader)) Object.preventExtensions(restored);
+    return restored;
+  };
+  const restoredMatches: Record<string, unknown>[] = [];
+  for (let index = 0; index < matches.length; index++) {
+    const match: unknown = matchFields[String(index)]?.value;
+    if (!record(match)) throw invalid('a native match must be a record');
+    const properties = descriptors(match, MATCH_FIELDS);
+    const restored: Record<string, unknown> = {};
+    for (const [key, field] of Object.entries(properties)) {
+      restored[key] =
+        key === 'e'
+          ? decodeError(field.value)
+          : key === 'l'
+            ? decodeLoader(field.value)
+            : field.value;
+    }
+    restoredMatches.push(restored);
+  }
+  const restored: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(fields))
+    restored[key] = key === 'matches' ? restoredMatches : field.value;
+  return restored;
+}
+
+// The native generic represents arbitrary dynamic match values as `any` too;
+// the actual supported data contract is checked before this adapter returns.
+export const octaneRouterSnapshotAdapter: AnySerializationAdapter =
+  createSerializationAdapter<any, any>({
+    key: ADAPTER_KEY,
+    test: (_value): _value is any => false,
+    toSerializable() {
+      throw invalid('the client decoder cannot serialize a server snapshot');
+    },
+    fromSerializable: decodeNativeSnapshot,
+  });

package/src/router.ts

@@ -0,0 +1,192 @@
+import {
+  createDataClient,
+  type PublicDataOutcome,
+} from '@modern-js/renderer-core/data';
+import type { RendererIdentity } from '@modern-js/renderer-core/identity';
+import {
+  type AnyRouter,
+  redirect,
+  useMatch,
+  useRouter,
+} from '@octanejs/tanstack-router';
+import { createSubSlot, useCallback, useEffect, useRef } from 'octane';
+import { assertOctaneIdentity } from './bootstrap';
+import { resolveRouteData } from './routes';
+
+/** These bindings own matching, preloading, navigation and route component lifetimes. */
+export * from '@octanejs/tanstack-router';
+export {
+  createRouter as createApplicationRouter,
+  RouterProvider as ApplicationRouter,
+} from '@octanejs/tanstack-router';
+export type {
+  FileSystemDataModule,
+  FileSystemRouteModule,
+  FileSystemRouteOptions,
+} from './routes';
+export {
+  createFileSystemRouteTree,
+  matchApplicationRouteIds,
+  matchApplicationRoutes,
+  RouteDataError,
+  resolveRouteData,
+  selectApplicationDataRoute,
+} from './routes';
+
+/** Read the identity selected by this application's framework composition. */
+export function useApplicationIdentity(): Readonly<RendererIdentity> {
+  const identity = useRouter().options.context?.ultramodern?.rendererIdentity;
+  if (!identity || typeof identity !== 'object' || Array.isArray(identity)) {
+    throw new Error(
+      'The Octane application router is missing its renderer identity',
+    );
+  }
+  assertOctaneIdentity(identity);
+  return Object.freeze({ ...identity });
+}
+
+/** Bind an action to its nearest native route, including ancestor layouts. */
+export function useApplicationRouteId(): string {
+  const router = useRouter();
+  const routeId = useMatch({ strict: false, select: match => match.routeId });
+  if (typeof routeId !== 'string') {
+    throw new Error(
+      'The Octane application requires an active native route match',
+    );
+  }
+  const id = router.routesById[routeId]?.options.staticData?.ultramodernRouteId;
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error(
+      'The Octane application route is missing its filesystem identity',
+    );
+  }
+  return id;
+}
+
+/**
+ * Native actions follow a redirect as a navigation, a GET. HTTP lets that
+ * happen for 303, and for 301/302 only after POST; any other redirect keeps
+ * the method and body, which a navigation would silently drop, so it fails.
+ */
+function assertNavigableActionRedirect(status: number, method: string): void {
+  if (
+    status === 307 ||
+    status === 308 ||
+    ((status === 301 || status === 302) && method !== 'POST')
+  )
+    throw new Error(
+      `A native action redirect must not preserve the method (HTTP ${status} after ${method}); redirect with 303 to navigate after the mutation`,
+    );
+}
+
+export interface OctaneRouteActionOptions {
+  readonly router: AnyRouter;
+  readonly routeId: string;
+  readonly identity: RendererIdentity;
+  readonly url?: string | (() => string);
+  readonly method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  readonly fetch?: typeof globalThis.fetch;
+  readonly signal?: AbortSignal;
+}
+
+/** Native useActionState owns submission state and the HTML form action. */
+export function createOctaneRouteAction(input: OctaneRouteActionOptions) {
+  const data = createDataClient(input.routeId, input.identity, {
+    fetch: input.fetch,
+  });
+  return async (
+    _previous: PublicDataOutcome | undefined,
+    formData: FormData,
+  ): Promise<PublicDataOutcome> => {
+    input.signal?.throwIfAborted();
+    const target =
+      typeof input.url === 'function'
+        ? input.url()
+        : (input.url ?? input.router.latestLocation.publicHref);
+    const origin = input.router.options.origin ?? globalThis.location?.origin;
+    const request = new Request(new URL(target, origin), {
+      method: input.method ?? 'POST',
+      body: formData,
+      signal: input.signal,
+    });
+    const outcome = await data.action({ request });
+    await outcome.completion;
+    input.signal?.throwIfAborted();
+    if (outcome.kind === 'redirect') {
+      assertNavigableActionRedirect(outcome.status, request.method);
+      const resolved = input.router.resolveRedirect(
+        redirect({
+          href: new URL(outcome.location, request.url).href,
+          statusCode: outcome.status,
+        }),
+      );
+      // Native navigation chooses document loading from the normalized href.
+      await input.router.navigate({ href: resolved.options.href });
+    } else if (
+      (outcome.kind === 'error' || outcome.kind === 'not-found') &&
+      outcome.thrown
+    ) {
+      resolveRouteData(input.routeId, outcome);
+    } else if (outcome.kind === 'success') {
+      await input.router.invalidate();
+    }
+    return outcome;
+  };
+}
+
+export type OctaneRouteActionBinding = Pick<
+  OctaneRouteActionOptions,
+  'url' | 'method' | 'fetch'
+>;
+
+// Plain TypeScript is not rewritten by the Octane compiler: derive each
+// composed hook's slot from the caller's, with a stable slotless fallback.
+const actionSlot = createSubSlot({ slotlessPrefix: 'ultramodern-action:' });
+
+/**
+ * Bind an action to the nearest native route and to this component's
+ * lifetime: unmounting aborts a submission still in flight, so its late
+ * result cannot redirect or invalidate the route the user moved on to.
+ */
+export function useOctaneRouteAction(
+  binding?: OctaneRouteActionBinding,
+): ReturnType<typeof createOctaneRouteAction>;
+export function useOctaneRouteAction(...args: unknown[]) {
+  const tail = args.at(-1);
+  const slot = typeof tail === 'symbol' ? tail : undefined;
+  const binding = (
+    typeof args[0] === 'object' && args[0] !== null ? args[0] : {}
+  ) as OctaneRouteActionBinding;
+  const router = useRouter();
+  const identity = useApplicationIdentity();
+  const routeId = useApplicationRouteId();
+  const owner = useRef<AbortController | null>(null, actionSlot(slot, 'owner'));
+  useEffect(
+    () => {
+      const controller = new AbortController();
+      owner.current = controller;
+      return () =>
+        controller.abort(
+          new DOMException('The route action owner unmounted', 'AbortError'),
+        );
+    },
+    [],
+    actionSlot(slot, 'lifetime'),
+  );
+  const { url, method, fetch } = binding;
+  return useCallback(
+    (previous: PublicDataOutcome | undefined, formData: FormData) =>
+      createOctaneRouteAction({
+        router,
+        routeId,
+        identity,
+        url,
+        method,
+        fetch,
+        signal: owner.current?.signal,
+      })(previous, formData),
+    // The identity is read from the router, so the router stands for it.
+    [router, routeId, url, method, fetch],
+    actionSlot(slot, 'action'),
+  );
+}

package/src/routes.ts

@@ -0,0 +1,263 @@
+import type {
+  DataOutcome,
+  FileSystemRouteIR,
+  PublicDataOutcome,
+} from '@modern-js/renderer-core/data';
+import {
+  type FileSystemRouteOptions,
+  loadFileSystemRoute,
+  type NativeLoaderMatch,
+  nativeRoutePath,
+  resolveRouteData as resolveNativeRouteData,
+  splitFileSystemRoutes,
+} from '@modern-js/renderer-core/router';
+import {
+  type AnyRoute,
+  type AnyRouteMatch,
+  type AnyRouter,
+  createRootRoute,
+  createRoute,
+  ErrorComponent,
+  type ErrorRouteComponent,
+  HeadContent,
+  type NotFoundRouteComponent,
+  notFound,
+  Outlet,
+  type RouteComponent,
+  redirect,
+  Scripts,
+} from '@octanejs/tanstack-router';
+import { createElement, Fragment } from 'octane';
+
+export type {
+  FileSystemDataModule,
+  FileSystemRouteOptions,
+} from '@modern-js/renderer-core/router';
+export {
+  matchApplicationRouteIds,
+  matchApplicationRoutes,
+  RouteDataError,
+  selectApplicationDataRoute,
+} from '@modern-js/renderer-core/router';
+
+/** Generated imports contain native view bindings, keyed by the structural id. */
+export interface FileSystemRouteModule {
+  component?: RouteComponent;
+  pendingComponent?: RouteComponent;
+  errorComponent?: ErrorRouteComponent;
+  notFoundComponent?: NotFoundRouteComponent;
+  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>;
+  head?: AnyRoute['options']['head'];
+}
+
+/** Native route boundaries decide how redirects, missing data and errors render. */
+export function resolveRouteData(
+  routeId: string,
+  outcome: DataOutcome | PublicDataOutcome,
+): unknown {
+  return resolveNativeRouteData({ redirect, notFound }, routeId, outcome);
+}
+
+interface ReactiveNativeMatch {
+  get(): AnyRouteMatch;
+  subscribe(callback: () => void): { unsubscribe(): void };
+}
+
+function isReactiveNativeMatch(value: unknown): value is ReactiveNativeMatch {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'get') === 'function' &&
+    typeof Reflect.get(value, 'subscribe') === 'function'
+  );
+}
+
+/** A transport failure belongs to the native generation that fetched it. */
+function observeRouteCompletion(
+  router: AnyRouter,
+  controller: AbortController,
+  signal: AbortSignal,
+  completion: Promise<void>,
+) {
+  void completion.catch(error => {
+    if (signal.aborted) return;
+    const match = [
+      ...router.stores.pendingMatches.get(),
+      ...router.stores.matches.get(),
+      ...router.stores.cachedMatches.get(),
+    ].find(candidate => candidate.abortController === controller);
+    if (!match) return;
+    const store = [
+      router.stores.pendingMatchStores.get(match.id),
+      router.stores.matchStores.get(match.id),
+      router.stores.cachedMatchStores.get(match.id),
+    ].find(candidate => candidate?.get().abortController === controller);
+    if (!store) return;
+    let subscription: { unsubscribe(): void } | undefined;
+    let settled = false;
+    const cleanup = () => {
+      subscription?.unsubscribe();
+      signal.removeEventListener('abort', onAbort);
+    };
+    const onAbort = () => {
+      settled = true;
+      cleanup();
+    };
+    const publish = () => {
+      if (settled) return;
+      const current = store.get();
+      if (
+        current.abortController !== controller ||
+        signal.aborted ||
+        (current.status !== 'pending' && current.status !== 'success')
+      ) {
+        onAbort();
+        return;
+      }
+      // The initial loader can still be pending after its critical value returns.
+      if (current.status !== 'success' || current.isFetching) return;
+      settled = true;
+      cleanup();
+      const route = router.routesById[current.routeId];
+      let failure = error;
+      try {
+        route?.options.onError?.(failure);
+      } catch (onErrorFailure) {
+        failure = onErrorFailure;
+      }
+      // Native successful loads have already preloaded their route components.
+      if (signal.aborted) return;
+      router.updateMatch(match.id, previous =>
+        previous.abortController === controller &&
+        previous.status === 'success' &&
+        !previous.isFetching
+          ? {
+              ...previous,
+              error: failure,
+              status: 'error',
+              isFetching: false,
+            }
+          : previous,
+      );
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (isReactiveNativeMatch(store)) subscription = store.subscribe(publish);
+    if (settled) subscription?.unsubscribe();
+    else publish();
+  });
+}
+
+/** Pass filesystem structure to native factories without matching any URL. */
+export function createFileSystemRouteTree<Context = unknown>(
+  routes: readonly FileSystemRouteIR[],
+  modules: Readonly<Record<string, FileSystemRouteModule>>,
+  options: FileSystemRouteOptions<Context, AnyRouter> = {},
+): AnyRoute {
+  const { root: rootDescriptor, children } = splitFileSystemRoutes(routes);
+
+  function bindings(
+    route: FileSystemRouteIR,
+    errorComponent?: ErrorRouteComponent,
+  ) {
+    const needsData = Boolean(route.modules?.data || route.modules?.clientData);
+    if (needsData && !options.loadRoute) {
+      throw new Error(`An Octane data route requires its loader: ${route.id}`);
+    }
+    const loadRoute = options.loadRoute;
+    const { head, ...module } = modules[route.id] ?? {};
+    return {
+      ...module,
+      ...(head !== undefined ? { head } : {}),
+      // Octane's server renders an uncaught match error through the root
+      // outlet's Suspense, which defers it to a client retry that then
+      // replaces the whole layout. Give every child match the nearest
+      // error.tsx (or the native default) so the error renders in place.
+      ...(errorComponent ? { errorComponent } : {}),
+      component: module.component ?? Outlet,
+      staticData: { ultramodernRouteId: route.id },
+      ...(needsData && loadRoute
+        ? {
+            loader: async (match: NativeLoaderMatch) => {
+              const { outcome, signal } = await loadFileSystemRoute(
+                route,
+                loadRoute,
+                options,
+                match,
+              );
+              if ('completion' in outcome && outcome.completion) {
+                const router = options.getRouter?.();
+                if (!router) {
+                  throw new Error(
+                    'An Octane streamed data route requires its native router',
+                  );
+                }
+                let failed = false;
+                let failure: unknown;
+                void outcome.completion.catch(error => {
+                  failed = true;
+                  failure = error;
+                });
+                // Detect a terminal failure already received with the first frame.
+                await Promise.resolve();
+                signal.throwIfAborted();
+                if (failed) throw failure;
+                observeRouteCompletion(
+                  router,
+                  match.abortController,
+                  signal,
+                  outcome.completion,
+                );
+              }
+              options.onOutcome?.(route.id, outcome);
+              return resolveRouteData(route.id, outcome);
+            },
+          }
+        : {}),
+    };
+  }
+
+  const rootBindings = rootDescriptor
+    ? bindings(rootDescriptor)
+    : { component: Outlet };
+  const authoredRoot: RouteComponent = rootBindings.component;
+  function OctaneDocumentRoot(props: Parameters<RouteComponent>[0]) {
+    return createElement(
+      Fragment,
+      null,
+      createElement(HeadContent),
+      createElement(authoredRoot, props),
+      createElement(Scripts),
+    );
+  }
+  if (authoredRoot.preload !== undefined) {
+    OctaneDocumentRoot.preload = authoredRoot.preload;
+  }
+  const rootErrorComponent =
+    (rootDescriptor && modules[rootDescriptor.id]?.errorComponent) ||
+    ErrorComponent;
+  const root = createRootRoute({
+    ...rootBindings,
+    component: OctaneDocumentRoot,
+  });
+
+  function bind(
+    route: FileSystemRouteIR,
+    parent: AnyRoute,
+    inheritedErrorComponent: ErrorRouteComponent,
+  ): AnyRoute {
+    const errorComponent =
+      modules[route.id]?.errorComponent ?? inheritedErrorComponent;
+    const native = createRoute({
+      getParentRoute: () => parent,
+      ...nativeRoutePath(route),
+      ...bindings(route, errorComponent),
+    });
+    return native.addChildren(
+      route.children.map(child => bind(child, native, errorComponent)),
+    );
+  }
+
+  return root.addChildren(
+    children.map(route => bind(route, root, rootErrorComponent)),
+  );
+}