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

package/src/plugin/compiler-manifest.cjs

@@ -0,0 +1,178 @@
+const { createHash } = require('node:crypto');
+const path = require('node:path');
+const { getOctaneRspackBuildInfo } = require('@octanejs/rspack-plugin');
+
+const name = 'ultramodern:octane:compiler-manifest';
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+/** The released native compiler remains responsible for every transformation. */
+class OctaneCompilerManifestPlugin {
+  constructor(options) {
+    this.options = options;
+  }
+
+  apply(compiler) {
+    compiler.hooks.normalModuleFactory.tap(name, factory => {
+      factory.hooks.beforeResolve.tap(name, result => {
+        if (/\.svg\?(?:[^#]*&)?react(?:[=&]|$)/u.test(result.request)) {
+          throw new Error(
+            'unsupported-renderer-capability: `?react` SVG imports are React components; import Octane SVG components with `?component`.',
+          );
+        }
+      });
+      factory.hooks.afterResolve.tap(name, result => {
+        const resource = result.createData?.resource?.split('?')[0];
+        if (resource && path.extname(resource).toLowerCase() === '.jsx') {
+          throw new Error(
+            `unsupported-renderer-capability: Octane does not support .jsx source: ${resource}. Supported source extensions: .tsx, .tsrx, .ts, .js.`,
+          );
+        }
+      });
+    });
+    if (!this.options.emitClientManifest) return;
+    compiler.hooks.thisCompilation.tap(name, compilation => {
+      compilation.hooks.processAssets.tap(
+        {
+          name,
+          stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT + 1,
+        },
+        () => {
+          // Preserve the owning resolver/compiler diagnostic on an invalid graph.
+          if (compilation.errors.length) return;
+          const buildAsset = compilation.getAsset('octane-client-build.json');
+          if (!buildAsset)
+            throw new Error(
+              'The native Octane client build manifest is missing.',
+            );
+          const nativeBuild = JSON.parse(buildAsset.source.source().toString());
+          if (
+            nativeBuild.version !== 1 ||
+            nativeBuild.buildId !== compilation.hash
+          ) {
+            throw new Error(
+              'The native Octane client manifest does not match the completed compilation.',
+            );
+          }
+          const sourcesByModule = new Map();
+          const moduleAssets = new Map();
+          const visit = (module, inheritedAssets = []) => {
+            const chunks = [
+              ...compilation.chunkGraph.getModuleChunksIterable(module),
+            ];
+            const previousAssets = moduleAssets.get(module);
+            const assets = [
+              ...new Set([
+                ...(previousAssets ?? []),
+                ...inheritedAssets,
+                ...chunks.flatMap(chunk => [...chunk.files]),
+              ]),
+            ]
+              .filter(file => file.endsWith('.js'))
+              .sort();
+            // Rspack also lists concatenated children as standalone modules.
+            // A later parent visit can supply their first emitted chunk.
+            if (
+              previousAssets &&
+              assets.every(file => previousAssets.has(file))
+            )
+              return;
+            moduleAssets.set(module, new Set(assets));
+            const info = getOctaneRspackBuildInfo(module);
+            if (info && assets.length) {
+              const resource = module.resource?.split('?')[0];
+              const emitted = module.originalSource();
+              if (!resource || !emitted) {
+                throw new Error(
+                  `Octane compiled module has no source: ${module.identifier()}.`,
+                );
+              }
+              const relative = path.relative(this.options.root, resource);
+              sourcesByModule.set(module, {
+                resource:
+                  relative.split(path.sep).join('/') +
+                  (info.resourceQuery ?? ''),
+                canonicalId: info.canonicalId,
+                moduleId:
+                  compilation.chunkGraph.getModuleId(module) ??
+                  module.identifier(),
+                transformKind: info.transformKind,
+                emittedSourceSha256: digest(emitted.buffer()),
+                assets,
+              });
+            }
+            for (const nested of module.modules ?? []) visit(nested, assets);
+          };
+          for (const module of compilation.modules) visit(module);
+          const sources = [...sourcesByModule.values()];
+          sources.sort((left, right) =>
+            left.resource.localeCompare(right.resource),
+          );
+          const identities = this.options.rendererIdentities();
+          if (!identities || !Object.keys(identities).length) {
+            throw new Error(
+              'Octane compiler requires immutable application entry identities.',
+            );
+          }
+          for (const [entryName, rendererIdentity] of Object.entries(
+            identities,
+          )) {
+            if (
+              rendererIdentity?.renderer !== 'octane' ||
+              rendererIdentity.entryName !== entryName
+            ) {
+              throw new Error(
+                `Octane compiler identity conflicts with entry ${entryName}.`,
+              );
+            }
+            const entrypoint = compilation.entrypoints.get(entryName);
+            if (!entrypoint)
+              throw new Error(
+                `Octane compiler has no client entry for ${entryName}.`,
+              );
+            const entryChunks = new Set(entrypoint.chunks);
+            for (const chunk of entrypoint.chunks) {
+              for (const referenced of chunk.getAllReferencedChunks())
+                entryChunks.add(referenced);
+            }
+            const files = [
+              ...new Set(
+                [...entryChunks]
+                  .flatMap(chunk => [...chunk.files])
+                  .filter(file => file.endsWith('.js')),
+              ),
+            ].sort();
+            const fileSet = new Set(files);
+            const manifest = {
+              schemaVersion: 1,
+              renderer: 'octane',
+              runtimeVersion: this.options.runtimeVersion,
+              compilerVersion: this.options.compilerVersion,
+              rendererIdentity,
+              nativeHydrationBuildId: nativeBuild.buildId,
+              sourceModules: sources.flatMap(source => {
+                const assets = source.assets.filter(file => fileSet.has(file));
+                return assets.length ? [{ ...source, assets }] : [];
+              }),
+              assets: files.map(file => ({
+                file,
+                sha256: digest(compilation.getAsset(file).source.buffer()),
+              })),
+            };
+            this.options.validateManifest(
+              manifest,
+              rendererIdentity,
+              compilation.hash,
+            );
+            compilation.emitAsset(
+              this.options.manifestFilename(entryName),
+              new compiler.webpack.sources.RawSource(
+                `${JSON.stringify(manifest, null, 2)}\n`,
+              ),
+            );
+          }
+        },
+      );
+    });
+  }
+}
+module.exports = { OctaneCompilerManifestPlugin };

package/src/plugin/compiler.ts

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { NativeRendererCompilerOptions } from '@modern-js/renderer-core/adapter';
+import type { RsbuildPlugin } from '@rsbuild/core';
+import {
+  OCTANE_COMPILER_VERSION,
+  OCTANE_RUNTIME_VERSION,
+  octaneModuleManifestFileName,
+  validateOctaneModuleManifest,
+} from '../manifest';
+
+export function pluginSourceDirectory(): string {
+  let directory = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const compiler = path.join(directory, 'src/plugin');
+    if (
+      fs.existsSync(path.join(directory, 'package.json')) &&
+      fs.existsSync(path.join(compiler, 'compiler-manifest.cjs'))
+    )
+      return compiler;
+    const parent = path.dirname(directory);
+    if (parent === directory)
+      throw new Error('Cannot locate the UltraModern Octane compiler package.');
+    directory = parent;
+  }
+}
+
+/** Octane owns native compilation; UltraModern retains the application host. */
+export function createOctaneCompilerPlugin(
+  options: NativeRendererCompilerOptions,
+): RsbuildPlugin {
+  return {
+    name: 'ultramodern:octane:compiler',
+    setup(api) {
+      const directory = pluginSourceDirectory();
+      const require = createRequire(path.join(directory, 'index.cjs'));
+      const {
+        OctaneCompilerManifestPlugin,
+      } = require('./compiler-manifest.cjs');
+      // The application installs the Octane compiler; resolve it lazily so
+      // descriptor readers never load it.
+      const {
+        inferRspackEnvironment,
+        OctaneRspackPlugin,
+      }: typeof import('@octanejs/rspack-plugin') = require('@octanejs/rspack-plugin');
+      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) =>
+        mergeRsbuildConfig(config, {
+          source: {
+            // Released native bindings export raw TypeScript and TSRX.
+            include: [/[/\\]@octanejs[/\\]/u],
+          },
+        }),
+      );
+      api.modifyRspackConfig((config, { environment: rsbuildEnvironment }) => {
+        // The Cloudflare SSR worker targets `webworker`; it still renders
+        // the server document rather than a client hydration bundle.
+        const environment =
+          rsbuildEnvironment.name === options.workerEnvironmentName
+            ? 'server'
+            : inferRspackEnvironment(config.target);
+        // Octane prepends '.tsrx' only when it is absent. Keep TypeScript
+        // modules first so an extensionless './link' cannot select a
+        // case-colliding Link.tsrx on case-insensitive file systems.
+        config.resolve ??= {};
+        const extensions = (config.resolve.extensions ?? []).filter(
+          extension => extension !== '.tsrx',
+        );
+        extensions.splice(
+          Math.max(extensions.indexOf('.ts'), extensions.indexOf('.tsx')) + 1,
+          0,
+          '.tsrx',
+        );
+        config.resolve.extensions = extensions;
+        config.plugins ??= [];
+        config.plugins.push(
+          new OctaneRspackPlugin({
+            root: api.context.rootPath,
+            environment,
+            transpile: false,
+          }),
+        );
+        config.plugins.push(
+          new OctaneCompilerManifestPlugin({
+            emitClientManifest: environment === 'client',
+            root: api.context.rootPath,
+            runtimeVersion: OCTANE_RUNTIME_VERSION,
+            compilerVersion: OCTANE_COMPILER_VERSION,
+            rendererIdentities: options.rendererIdentities,
+            manifestFilename: octaneModuleManifestFileName,
+            validateManifest: validateOctaneModuleManifest,
+          }),
+        );
+        config.module ??= {};
+        config.module.rules ??= [];
+        // Rsbuild's existing SWC rule handles ordinary .ts/.tsx sources.
+        // TSRX needs the same stripping stage after Octane's pre-loader.
+        config.module.rules.push({
+          test: /\.tsrx$/u,
+          type: 'javascript/auto',
+          use: [
+            {
+              loader: 'builtin:swc-loader',
+              options: { detectSyntax: 'auto' },
+            },
+          ],
+        });
+      });
+    },
+  };
+}

package/src/plugin/create.ts

@@ -0,0 +1,272 @@
+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, { status: 302, headers: { location: '/about' } });
+  return {
+    message: 'Native loader value',
+    privateValue: request.headers.get('x-conformance-private'),
+  };
+}
+
+export async function action({ request }: DataHandlerInput) {
+  const form = await request.formData();
+  const name = form.get('name');
+  if (typeof name !== 'string' || !name.trim())
+    return Response.json(
+      { fieldErrors: { name: 'Name required' } },
+      { status: 422 },
+    );
+  if (form.get('intent') === 'redirect')
+    return new Response(null, {
+      status: 303,
+      headers: {
+        location: '/about',
+        'set-cookie': 'conformance-saved=1; Path=/; SameSite=Lax',
+      },
+    });
+  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,105 @@
+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: false },
+      dependencies: (profile, { typescriptVersion }) => ({
+        frameworkDependencies: [
+          '@modern-js/renderer-core',
+          '@modern-js/renderer-octane',
+        ],
+        dependencies: nativeRendererDependencies(profile),
+        devDependencies: {
+          [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,
+    },
+  });