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

package/src/plugin/create.ts

@@ -0,0 +1,273 @@
+export type OctaneAppSourceOptions = {
+  appId: string;
+  title: string;
+  entryName?: string;
+  appRole?: 'shell' | 'vertical';
+  sourceExtension: '.tsx' | '.tsrx';
+  jsxImportSource: string;
+  capabilities: {
+    ssr: boolean;
+    federation: boolean;
+  };
+};
+
+export type OctaneAppSourceArtifact = {
+  path: string;
+  content: string;
+};
+
+export type OctaneAppSources = {
+  sourceExtension: '.tsx';
+  jsxImportSource: 'octane';
+  artifacts: OctaneAppSourceArtifact[];
+};
+
+/** The renderer adapter owns entry generation, the document and hydration. */
+export function generateOctaneAppSources(
+  options: OctaneAppSourceOptions,
+): OctaneAppSources {
+  if ((options.entryName ?? 'main') !== 'main') {
+    throw new Error(
+      'The Octane app template supports the main entry only. The create-time workspace writer places src/modern-app-env.d.ts, src/routes/index.css and the package manifest at the app root regardless of entryName, so it cannot yet route a second entry into src/<entryName>/. Add that entry by hand after generation (mirror src/routes under src/<entryName>/routes) until an admitted native multi-entry create template exists; the native entry generator itself already supports arbitrary entry names.',
+    );
+  }
+  if (!options.appId.trim() || !options.title.trim()) {
+    throw new Error('The Octane app template requires an appId and title.');
+  }
+  if (options.sourceExtension !== '.tsx') {
+    throw new Error(
+      'The Octane app template requires the admitted .tsx source profile. .tsrx generation requires an admitted native template profile.',
+    );
+  }
+  if (options.jsxImportSource !== 'octane') {
+    throw new Error(
+      'The Octane app template requires jsxImportSource: "octane" from the admitted profile.',
+    );
+  }
+  if (
+    typeof options.capabilities.ssr !== 'boolean' ||
+    typeof options.capabilities.federation !== 'boolean'
+  ) {
+    throw new Error('The Octane app template requires admitted capabilities.');
+  }
+  const title = JSON.stringify(options.title);
+  const aboutTitle = JSON.stringify(`${options.title} - About`);
+  const appId = JSON.stringify(options.appId);
+  return {
+    sourceExtension: '.tsx',
+    jsxImportSource: 'octane',
+    artifacts: [
+      {
+        path: 'src/routes/layout.tsx',
+        content: `import { Link, Outlet } from '@modern-js/renderer-octane/router';
+import Stable from '../components/stable';
+import './index.css';
+
+const appTitle = ${title};
+
+export default function Layout() {
+  return (
+    <main data-testid="native-layout">
+      <header>
+        <p>{appTitle}</p>
+        <nav aria-label="Application">
+          <Link to="/">Home</Link>
+          <Link to="/about">About</Link>
+${options.capabilities.federation ? '          <Link to="/remotes">Federated applications</Link>\n' : ''}
+        </nav>
+      </header>
+      <Stable />
+      <Outlet />
+    </main>
+  );
+}
+`,
+      },
+      {
+        path: 'src/routes/page.tsx',
+        content: `import {
+  Link,
+  useLoaderData,
+  useOctaneRouteAction,
+} from '@modern-js/renderer-octane/router';
+import { useActionState } from 'octane';
+import Counter from '../components/counter';
+
+const appId = ${appId};
+const appTitle = ${title};
+
+export default function HomePage() {
+  const data = useLoaderData({ strict: false });
+  const submit = useOctaneRouteAction();
+  const [result, action, pending] = useActionState(submit, undefined);
+  return (
+    <section data-app-id={appId} data-testid="native-route" data-renderer="octane">
+      <h1>{appTitle}</h1>
+      <Counter />
+      <pre data-testid="native-loader-value">{JSON.stringify(data)}</pre>
+      <form action={action}>
+        <label>
+          Name <input name="name" />
+        </label>
+        <button type="submit" disabled={pending}>
+          Save
+        </button>
+        <button type="submit" name="intent" value="redirect">
+          Save and redirect
+        </button>
+      </form>
+      <pre data-testid="native-action-value">{JSON.stringify(result)}</pre>
+      <Link to="/about">Open native about route</Link>
+    </section>
+  );
+}
+`,
+      },
+      {
+        path: 'src/routes/page.head.ts',
+        content: `import type { FileSystemRouteModule } from '@modern-js/renderer-octane/router';
+
+export const head: NonNullable<FileSystemRouteModule['head']> = () => ({
+  meta: [
+    { title: ${title} },
+    { name: 'description', content: 'Built with the native Octane renderer' },
+  ],
+});
+`,
+      },
+      {
+        path: 'src/routes/about/page.tsx',
+        content: `import { Link } from '@modern-js/renderer-octane/router';
+
+export default function AboutPage() {
+  return (
+    <section data-testid="native-about">
+      <h1>Native Octane navigation</h1>
+      <Link to="/">Home</Link>
+    </section>
+  );
+}
+`,
+      },
+      {
+        path: 'src/routes/about/page.head.ts',
+        content: `import type { FileSystemRouteModule } from '@modern-js/renderer-octane/router';
+
+export const head: NonNullable<FileSystemRouteModule['head']> = () => ({
+  meta: [
+    { title: ${aboutTitle} },
+    { name: 'description', content: 'Built with the native Octane renderer' },
+  ],
+});
+`,
+      },
+      {
+        path: 'src/components/counter.tsx',
+        content: `import { useState } from 'octane';
+
+export default function Counter() {
+  const [count, setCount] = useState(0);
+  return (
+    <section data-testid="native-edited-component">
+      <span data-testid="native-hmr-marker">Counter before native edit</span>
+      <button type="button" onClick={() => setCount(value => value + 1)}>
+        Increment
+      </button>
+      <output data-testid="native-count">{count}</output>
+    </section>
+  );
+}
+`,
+      },
+      {
+        path: 'src/components/stable.tsx',
+        content: `import { useState } from 'octane';
+
+export default function Stable() {
+  const [count, setCount] = useState(0);
+  return (
+    <section data-testid="native-unaffected-component">
+      <button type="button" onClick={() => setCount(value => value + 1)}>
+        Increment stable state
+      </button>
+      <output data-testid="native-unaffected-count">{count}</output>
+    </section>
+  );
+}
+`,
+      },
+      {
+        path: 'src/routes/page.data.ts',
+        content: `import type { DataHandlerInput } from '@modern-js/renderer-core/data';
+
+export function loader({ request }: DataHandlerInput) {
+  const url = new URL(request.url);
+  if (url.searchParams.get('case') === 'not-found')
+    throw new Response('Native route not found', { status: 404 });
+  if (url.searchParams.get('case') === 'error')
+    throw new Error('Native loader failure');
+  if (url.searchParams.get('case') === 'redirect')
+    return new Response(null, { headers: { location: '/about' }, status: 302 });
+  return {
+    message: 'Native loader value',
+    privateValue: request.headers.get('x-conformance-private'),
+  };
+}
+
+export function action({ request }: DataHandlerInput) {
+  return request.formData().then(form => {
+    const name = form.get('name');
+    if (typeof name !== 'string' || name.trim().length === 0)
+      return Response.json(
+        { fieldErrors: { name: 'Name required' } },
+        { status: 422 },
+      );
+    if (form.get('intent') === 'redirect')
+      return new Response(null, {
+        headers: {
+          location: '/about',
+          'set-cookie': 'conformance-saved=1; Path=/; SameSite=Lax',
+        },
+        status: 303,
+      });
+    if (form.get('intent') === 'throw') throw new Error('Native action failure');
+    return {
+      saved: name,
+      privateValue: request.headers.get('x-conformance-private'),
+    };
+  });
+}
+`,
+      },
+      {
+        path: 'src/routes/error.tsx',
+        content: `import type { ErrorRouteComponent } from '@modern-js/renderer-octane/router';
+
+const ErrorBoundary: ErrorRouteComponent = props => (
+  <section data-testid="native-error">
+    <h1>Something went wrong</h1>
+    <output>
+      {props.error instanceof Error ? props.error.message : String(props.error)}
+    </output>
+  </section>
+);
+
+export default ErrorBoundary;
+`,
+      },
+      {
+        path: 'src/routes/not-found.tsx',
+        content: `import type { NotFoundRouteComponent } from '@modern-js/renderer-octane/router';
+
+const NotFound: NotFoundRouteComponent = () => (
+  <section data-testid="native-not-found">
+    <h1>Page not found</h1>
+  </section>
+);
+
+export default NotFound;
+`,
+      },
+    ],
+  };
+}

package/src/plugin/index.ts

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import {
+  defineRendererAdapter,
+  type NativeRendererAdapter,
+  nativeRendererDependencies,
+} from '@modern-js/renderer-core/adapter';
+import { compilerArtifacts } from '../manifest';
+import { createOctaneCompilerPlugin, pluginSourceDirectory } from './compiler';
+import { generateOctaneAppSources } from './create';
+import { octaneProfile } from './profile';
+import { assertOctaneEntrySource } from './source';
+
+/** The build-side Octane renderer adapter UltraModern loads for `renderer: 'octane'`. */
+export const rendererAdapter: NativeRendererAdapter<'octane'> =
+  defineRendererAdapter({
+    name: 'octane',
+    kind: 'native',
+    profile: octaneProfile,
+    routerFrameworks: ['octane'],
+    runtime: {
+      package: 'octane',
+      bootstrap: '@modern-js/renderer-octane',
+      entryClient: '@modern-js/renderer-octane/entry-client',
+      entryServer: '@modern-js/renderer-octane/entry-server',
+      router: '@modern-js/renderer-octane/router',
+      i18n: '@modern-js/renderer-octane/i18n',
+      manifest: '@modern-js/renderer-octane/manifest',
+    },
+    federation: {
+      library: 'module',
+      ssr: true,
+      shared: [
+        'octane',
+        'octane/',
+        'octane/internal/context',
+        'octane/internal/signal-read',
+        'octane/signals',
+        '@octanejs/tanstack-router',
+        '@octanejs/tanstack-router/',
+        '@modern-js/renderer-octane',
+        '@modern-js/renderer-octane/',
+        '@modern-js/renderer-octane/router',
+        '@modern-js/renderer-octane/federation',
+        '@modern-js/renderer-core',
+        '@modern-js/renderer-core/',
+        '@tanstack/router-core',
+        '@tanstack/history',
+        'seroval',
+        'seroval-plugins',
+      ],
+      // A remote can use a native API the local app never imports. Publish
+      // these providers from the host so their private hook state stays local.
+      sharedByEnvironment: {
+        client: {
+          'octane/internal/client': 'octane/internal/client',
+          'octane/signals/client': 'octane/signals/client',
+          'octane/profiling': 'octane/profiling',
+          'octane/hydration/streamed-signals':
+            'octane/hydration/streamed-signals',
+          '@modern-js/renderer-octane/client':
+            '@modern-js/renderer-octane/client',
+        },
+        server: {
+          octane: 'octane/server',
+          'octane/server': 'octane/server',
+          'octane/internal/server': 'octane/internal/server',
+          'octane/signals/server': 'octane/signals/server',
+        },
+      },
+    },
+    worker: { nativeDocuments: true, rsc: false },
+    lazyStyles: 'document',
+    // Hydration bytes belong to this exact native client compilation.
+    entryClient: {
+      declarations: 'declare const __webpack_hash__: string;\n',
+      fields: { nativeHydrationBuildId: '__webpack_hash__' },
+    },
+    svgComponentTemplate: () =>
+      path.join(pluginSourceDirectory(), 'svg-component-template.cjs'),
+    compiler: createOctaneCompilerPlugin,
+    artifacts: compilerArtifacts,
+    assertSupportedSource: assertOctaneEntrySource,
+    create: {
+      templates: { federation: true, workers: true },
+      dependencies: (profile, { typescriptVersion }) => ({
+        frameworkDependencies: [
+          '@modern-js/renderer-core',
+          '@modern-js/renderer-octane',
+        ],
+        dependencies: nativeRendererDependencies(profile),
+        devDependencies: {
+          [profile.compiler.name]:
+            profile.dependencies[profile.compiler.name] ??
+            profile.compiler.version,
+          typescript: typescriptVersion,
+        },
+        typecheckCommand: 'octane-tsc --noEmit --project tsconfig.json',
+        tsconfig: {
+          tsrx: {
+            compiler: 'octane/compiler/volar',
+            platform: 'web',
+          },
+        },
+      }),
+      generateAppSources: generateOctaneAppSources,
+    },
+  });

package/src/plugin/profile.ts

@@ -0,0 +1,50 @@
+import type { RendererBuildProfile } from '@modern-js/renderer-core/adapter';
+
+export const octaneProfile: RendererBuildProfile<'octane'> = {
+  renderer: 'octane',
+  status: 'preview',
+  protocolVersion: 1,
+  minimumNode: '26.12.0',
+  hmr: {
+    editedBoundary: 'may-reset',
+    unaffectedComponents: 'preserved',
+    document: 'preserved',
+    roots: 'single',
+    cleanup: 'exactly-once',
+  },
+  compiler: { name: '@octanejs/rspack-plugin', version: '0.2.4' },
+  hydration: {
+    name: 'octane',
+    version: '0.13.8',
+  },
+  router: {
+    name: '@octanejs/tanstack-router',
+    version: '0.2.10',
+    coreName: '@tanstack/router-core',
+    coreVersion: '1.171.38',
+  },
+  sourceExtensions: ['.tsx', '.tsrx', '.ts', '.js'],
+  jsxImportSource: 'octane',
+  dependencies: {
+    '@tsrx/oxc': '0.20.0',
+    octane:
+      'https://github.com/BleedingDev/octane/releases/download/ultramodern-octane-2383d2ab1e70/octane-0.13.8.tgz',
+    '@octanejs/tanstack-router':
+      'https://github.com/BleedingDev/octane/releases/download/ultramodern-octane-2383d2ab1e70/octanejs-tanstack-router-0.2.10.tgz',
+    '@octanejs/rspack-plugin':
+      'https://github.com/BleedingDev/octane/releases/download/ultramodern-octane-2383d2ab1e70/octanejs-rspack-plugin-0.2.4.tgz',
+    '@tanstack/router-core':
+      'https://github.com/BleedingDev/router/releases/download/ultramodern-router-core-585d3233f7f5/tanstack-router-core-1.171.38.tgz',
+    '@modern-js/renderer-octane': '3.8.3',
+    seroval: '1.6.9',
+    'seroval-plugins': '1.6.9',
+  },
+  capabilities: {
+    worker: true,
+    moduleFederation: true,
+    rsc: false,
+    ssg: true,
+    i18n: true,
+    svgComponent: true,
+  },
+};

package/src/plugin/source.ts

@@ -0,0 +1,16 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { octaneProfile } from './profile';
+
+export async function assertOctaneEntrySource(
+  source: string | false | undefined,
+): Promise<void> {
+  if (
+    source &&
+    path.extname(source).toLowerCase() === '.jsx' &&
+    (await fs.stat(source)).isFile()
+  )
+    throw new Error(
+      `unsupported-renderer-capability: Octane does not support .jsx source: ${source}. Supported source extensions: ${octaneProfile.sourceExtensions.join(', ')}.`,
+    );
+}

package/src/plugin/svg-component-template.cjs

@@ -0,0 +1,17 @@
+// Octane follows React host semantics: refs are props and inner markup is
+// trusted HTML. Native attribute names and `class` pass through unchanged.
+module.exports = ({
+  attributes,
+  markup,
+  origin,
+}) => `/** @jsxImportSource octane */
+// Generated by UltraModern from ${origin}. Do not edit.
+import { trustHTML } from 'octane';
+
+const attributes: { readonly [name: string]: string } = ${attributes};
+const markup = trustHTML(${markup});
+
+export default function SvgComponent(props: { readonly [name: string]: unknown }) {
+  return <svg {...attributes} {...props} dangerouslySetInnerHTML={markup} />;
+}
+`;

package/src/router-client.ts

@@ -0,0 +1,144 @@
+import { type AnyRouter, RouterProvider } from '@octanejs/tanstack-router';
+import { hydrate } from '@octanejs/tanstack-router/ssr/client';
+import {
+  createElement,
+  hookSlots,
+  initializeHydrationEventCapture,
+  useEffect,
+} from 'octane';
+import { octaneRouterSnapshotAdapter } from './router-snapshot';
+
+export interface OctaneRouterHydrationOptions {
+  signal?: AbortSignal;
+}
+
+const hydration = new WeakMap<AnyRouter, Promise<void>>();
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason === undefined
+    ? new DOMException('Octane router hydration aborted', 'AbortError')
+    : signal.reason;
+}
+
+function awaitHydration(
+  promise: Promise<void>,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!signal) return promise;
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (success: boolean, error?: unknown) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', onAbort);
+      if (success) resolve();
+      else reject(error);
+    };
+    const onAbort = () => finish(false, abortReason(signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      () => finish(true),
+      error => finish(false, error),
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+
+interface ReactiveMatchIds {
+  get(): readonly string[];
+  subscribe(callback: () => void): { unsubscribe(): void };
+}
+
+function isReactiveMatchIds(value: unknown): value is ReactiveMatchIds {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'get') === 'function' &&
+    typeof Reflect.get(value, 'subscribe') === 'function'
+  );
+}
+
+function waitForCommittedMatches(
+  router: AnyRouter,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted();
+  const matchesId = router.stores.ids;
+  if (matchesId.get().length > 0) return Promise.resolve();
+  if (!isReactiveMatchIds(matchesId)) {
+    throw new Error(
+      'Octane router hydration requires its native reactive match store',
+    );
+  }
+  return new Promise((resolve, reject) => {
+    let subscription: ReturnType<typeof matchesId.subscribe> | undefined;
+    let settled = false;
+    const cleanup = () => {
+      subscription?.unsubscribe();
+      signal?.removeEventListener('abort', onAbort);
+    };
+    const finish = () => {
+      if (settled || matchesId.get().length === 0) return;
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (signal) reject(abortReason(signal));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    subscription = matchesId.subscribe(finish);
+    // Native stores can notify synchronously while a subscription is installed.
+    if (settled) subscription.unsubscribe();
+    else finish();
+  });
+}
+
+/** Restore native SSR matches before Octane adopts the server's route ranges. */
+export async function prepareOctaneRouterHydration(
+  router: AnyRouter,
+  options: OctaneRouterHydrationOptions = {},
+): Promise<void> {
+  initializeHydrationEventCapture();
+  options.signal?.throwIfAborted();
+  const adapters = router.options.serializationAdapters ?? [];
+  if (!adapters.includes(octaneRouterSnapshotAdapter)) {
+    const nativeOptions = {
+      ...router.options,
+      serializationAdapters: [octaneRouterSnapshotAdapter, ...adapters],
+    };
+    router.update(nativeOptions);
+  }
+  let pending = hydration.get(router);
+  if (!pending) {
+    pending = Promise.resolve(hydrate(router)).then(() => {});
+    // Native hydration can finish after this startup owner has been cancelled.
+    void pending.catch(() => {});
+    hydration.set(router, pending);
+  }
+  await awaitHydration(pending, options.signal);
+  await waitForCommittedMatches(router, options.signal);
+  options.signal?.throwIfAborted();
+}
+
+const routerHydrationEffectSlot = Symbol(hookSlots(1));
+
+/** Adopt the native provider's ranges inside the admitted fragment host. */
+export function OctaneRouterRoot({ router }: { router: AnyRouter }) {
+  useEffect(
+    () => {
+      window.$_TSR?.h();
+    },
+    [],
+    routerHydrationEffectSlot,
+  );
+  return createElement(RouterProvider, { router });
+}