@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.1 → 3.9.0-ultramodern.10

package/src/workspaceEvents.ts

@@ -0,0 +1,324 @@
+export type UltramodernPerformanceReadinessSignalId =
+  | 'bfcache'
+  | 'core-web-vitals-rum'
+  | 'duplicate-prefetch-warmup'
+  | 'cache-policy-sanity'
+  | 'save-data-behavior'
+  | 'cloudflare-ssr-cache-hints';
+
+export type UltramodernWorkspaceLocale = 'en' | 'cs';
+
+export type UltramodernPerformanceReadinessSignalStatus =
+  | 'pass'
+  | 'warn'
+  | 'fail';
+
+export const ultramodernWorkspaceEventNames = {
+  navigate: 'ultramodern:navigate',
+  performanceSignal: 'ultramodern:performance-signal',
+  remoteReady: 'ultramodern:remote-ready',
+  routeSettled: 'ultramodern:route-settled',
+} as const;
+
+export type UltramodernWorkspaceEventName =
+  (typeof ultramodernWorkspaceEventNames)[keyof typeof ultramodernWorkspaceEventNames];
+
+export interface UltramodernNavigatePayload {
+  to: string;
+  replace?: boolean;
+  state?: Record<string, unknown>;
+}
+
+export interface UltramodernRouteSettledPayload {
+  pathname: string;
+  locale?: UltramodernWorkspaceLocale;
+  title?: string;
+}
+
+export interface UltramodernRemoteReadyPayload {
+  appId: string;
+  build?: string;
+  surface?: string;
+  version?: string;
+}
+
+export interface UltramodernPerformanceSignalPayload {
+  signalId: UltramodernPerformanceReadinessSignalId;
+  status: UltramodernPerformanceReadinessSignalStatus;
+  durationMs?: number;
+  detail?: Record<string, unknown>;
+}
+
+export interface UltramodernWorkspaceEventPayloadMap {
+  'ultramodern:navigate': UltramodernNavigatePayload;
+  'ultramodern:performance-signal': UltramodernPerformanceSignalPayload;
+  'ultramodern:remote-ready': UltramodernRemoteReadyPayload;
+  'ultramodern:route-settled': UltramodernRouteSettledPayload;
+}
+
+export class UltramodernWorkspaceEventValidationError {
+  readonly message: string;
+  readonly name = 'UltramodernWorkspaceEventValidationError';
+  readonly eventName: UltramodernWorkspaceEventName;
+  readonly payload: unknown;
+
+  constructor(eventName: UltramodernWorkspaceEventName, payload: unknown) {
+    this.message = `Invalid payload for UltraModern workspace event "${eventName}"`;
+    this.eventName = eventName;
+    this.payload = payload;
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+const isNonNegativeNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+const isUltramodernWorkspaceLocale = (
+  value: unknown,
+): value is UltramodernWorkspaceLocale => value === 'en' || value === 'cs';
+
+const isPerformanceReadinessSignalId = (
+  value: unknown,
+): value is UltramodernPerformanceReadinessSignalId =>
+  value === 'bfcache' ||
+  value === 'core-web-vitals-rum' ||
+  value === 'duplicate-prefetch-warmup' ||
+  value === 'cache-policy-sanity' ||
+  value === 'save-data-behavior' ||
+  value === 'cloudflare-ssr-cache-hints';
+
+const isPerformanceReadinessSignalStatus = (
+  value: unknown,
+): value is UltramodernPerformanceReadinessSignalStatus =>
+  value === 'pass' || value === 'warn' || value === 'fail';
+
+const hasOptionalString = (value: Record<string, unknown>, key: string) =>
+  value[key] === undefined || isNonEmptyString(value[key]);
+
+const hasOptionalBoolean = (value: Record<string, unknown>, key: string) =>
+  value[key] === undefined || typeof value[key] === 'boolean';
+
+const hasOptionalRecord = (value: Record<string, unknown>, key: string) =>
+  value[key] === undefined || isRecord(value[key]);
+
+const hasOptionalNonNegativeNumber = (
+  value: Record<string, unknown>,
+  key: string,
+) => value[key] === undefined || isNonNegativeNumber(value[key]);
+
+const hasOptionalLocale = (value: Record<string, unknown>, key: string) =>
+  value[key] === undefined || isUltramodernWorkspaceLocale(value[key]);
+
+export const isUltramodernNavigatePayload = (
+  payload: unknown,
+): payload is UltramodernNavigatePayload =>
+  isRecord(payload) &&
+  isNonEmptyString(payload.to) &&
+  hasOptionalBoolean(payload, 'replace') &&
+  hasOptionalRecord(payload, 'state');
+
+export const isUltramodernRouteSettledPayload = (
+  payload: unknown,
+): payload is UltramodernRouteSettledPayload =>
+  isRecord(payload) &&
+  isNonEmptyString(payload.pathname) &&
+  hasOptionalLocale(payload, 'locale') &&
+  hasOptionalString(payload, 'title');
+
+export const isUltramodernRemoteReadyPayload = (
+  payload: unknown,
+): payload is UltramodernRemoteReadyPayload =>
+  isRecord(payload) &&
+  isNonEmptyString(payload.appId) &&
+  hasOptionalString(payload, 'build') &&
+  hasOptionalString(payload, 'surface') &&
+  hasOptionalString(payload, 'version');
+
+export const isUltramodernPerformanceSignalPayload = (
+  payload: unknown,
+): payload is UltramodernPerformanceSignalPayload =>
+  isRecord(payload) &&
+  isPerformanceReadinessSignalId(payload.signalId) &&
+  isPerformanceReadinessSignalStatus(payload.status) &&
+  hasOptionalNonNegativeNumber(payload, 'durationMs') &&
+  hasOptionalRecord(payload, 'detail');
+
+const ultramodernWorkspaceEventValidators: {
+  [Name in UltramodernWorkspaceEventName]: (
+    payload: unknown,
+  ) => payload is UltramodernWorkspaceEventPayloadMap[Name];
+} = {
+  [ultramodernWorkspaceEventNames.navigate]: isUltramodernNavigatePayload,
+  [ultramodernWorkspaceEventNames.performanceSignal]:
+    isUltramodernPerformanceSignalPayload,
+  [ultramodernWorkspaceEventNames.remoteReady]: isUltramodernRemoteReadyPayload,
+  [ultramodernWorkspaceEventNames.routeSettled]:
+    isUltramodernRouteSettledPayload,
+};
+
+export const isUltramodernWorkspaceEventPayload = <
+  Name extends UltramodernWorkspaceEventName,
+>(
+  eventName: Name,
+  payload: unknown,
+): payload is UltramodernWorkspaceEventPayloadMap[Name] =>
+  ultramodernWorkspaceEventValidators[eventName](payload);
+
+export const assertUltramodernWorkspaceEventPayload = <
+  Name extends UltramodernWorkspaceEventName,
+>(
+  eventName: Name,
+  payload: unknown,
+): UltramodernWorkspaceEventPayloadMap[Name] => {
+  if (!isUltramodernWorkspaceEventPayload(eventName, payload)) {
+    throw new UltramodernWorkspaceEventValidationError(eventName, payload);
+  }
+
+  return payload;
+};
+
+export const createUltramodernWorkspaceEvent = <
+  Name extends UltramodernWorkspaceEventName,
+>(
+  eventName: Name,
+  payload: UltramodernWorkspaceEventPayloadMap[Name],
+): CustomEvent<UltramodernWorkspaceEventPayloadMap[Name]> =>
+  new CustomEvent(eventName, {
+    bubbles: true,
+    composed: true,
+    detail: assertUltramodernWorkspaceEventPayload(eventName, payload),
+  });
+
+export const dispatchUltramodernWorkspaceEvent = <
+  Name extends UltramodernWorkspaceEventName,
+>(
+  target: EventTarget,
+  eventName: Name,
+  payload: UltramodernWorkspaceEventPayloadMap[Name],
+) => target.dispatchEvent(createUltramodernWorkspaceEvent(eventName, payload));
+
+export const onUltramodernWorkspaceEvent = <
+  Name extends UltramodernWorkspaceEventName,
+>(
+  target: EventTarget,
+  eventName: Name,
+  handler: (
+    payload: UltramodernWorkspaceEventPayloadMap[Name],
+    event: CustomEvent<UltramodernWorkspaceEventPayloadMap[Name]>,
+  ) => void,
+) => {
+  const listener = (event: Event) => {
+    if (!('detail' in event)) {
+      throw new UltramodernWorkspaceEventValidationError(eventName, undefined);
+    }
+
+    const customEvent = event as CustomEvent<unknown>;
+    handler(
+      assertUltramodernWorkspaceEventPayload(eventName, customEvent.detail),
+      customEvent as CustomEvent<UltramodernWorkspaceEventPayloadMap[Name]>,
+    );
+  };
+
+  target.addEventListener(eventName, listener);
+
+  return () => {
+    target.removeEventListener(eventName, listener);
+  };
+};
+
+export const dispatchUltramodernNavigate = (
+  target: EventTarget,
+  payload: UltramodernNavigatePayload,
+) =>
+  dispatchUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.navigate,
+    payload,
+  );
+
+export const dispatchUltramodernRouteSettled = (
+  target: EventTarget,
+  payload: UltramodernRouteSettledPayload,
+) =>
+  dispatchUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.routeSettled,
+    payload,
+  );
+
+export const dispatchUltramodernRemoteReady = (
+  target: EventTarget,
+  payload: UltramodernRemoteReadyPayload,
+) =>
+  dispatchUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.remoteReady,
+    payload,
+  );
+
+export const dispatchUltramodernPerformanceSignal = (
+  target: EventTarget,
+  payload: UltramodernPerformanceSignalPayload,
+) =>
+  dispatchUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.performanceSignal,
+    payload,
+  );
+
+export const onUltramodernNavigate = (
+  target: EventTarget,
+  handler: (
+    payload: UltramodernNavigatePayload,
+    event: CustomEvent<UltramodernNavigatePayload>,
+  ) => void,
+) =>
+  onUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.navigate,
+    handler,
+  );
+
+export const onUltramodernRouteSettled = (
+  target: EventTarget,
+  handler: (
+    payload: UltramodernRouteSettledPayload,
+    event: CustomEvent<UltramodernRouteSettledPayload>,
+  ) => void,
+) =>
+  onUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.routeSettled,
+    handler,
+  );
+
+export const onUltramodernRemoteReady = (
+  target: EventTarget,
+  handler: (
+    payload: UltramodernRemoteReadyPayload,
+    event: CustomEvent<UltramodernRemoteReadyPayload>,
+  ) => void,
+) =>
+  onUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.remoteReady,
+    handler,
+  );
+
+export const onUltramodernPerformanceSignal = (
+  target: EventTarget,
+  handler: (
+    payload: UltramodernPerformanceSignalPayload,
+    event: CustomEvent<UltramodernPerformanceSignalPayload>,
+  ) => void,
+) =>
+  onUltramodernWorkspaceEvent(
+    target,
+    ultramodernWorkspaceEventNames.performanceSignal,
+    handler,
+  );

package/tests/buildIdentity.test.ts

@@ -0,0 +1,51 @@
+import { resolveUltramodernBuildArtifact } from '../src/buildIdentity';
+
+const artifact = {
+  deliveryUnit: {
+    build: 'original',
+    buildMarker: 'original',
+    sourceRevision: 'workspace',
+    unitId: 'shop/catalog',
+  },
+  surfaces: {
+    api: {
+      build: 'original',
+      buildMarker: 'original',
+      sourceRevision: 'workspace',
+      surface: 'api',
+    },
+    ui: {
+      build: 'original',
+      buildMarker: 'original',
+      sourceRevision: 'workspace',
+      surface: 'ui',
+    },
+  },
+} as const;
+
+const readers = {
+  buildMarker: () => 'compiled-build',
+  sourceRevision: () => 'compiled-revision',
+};
+
+it('falls back only for missing compiler references and preserves each supplied value', () => {
+  expect(resolveUltramodernBuildArtifact(artifact)).toEqual(artifact);
+
+  const result = resolveUltramodernBuildArtifact(artifact, {
+    buildMarker: readers.buildMarker,
+    sourceRevision: () => {
+      throw new ReferenceError('ULTRAMODERN_SOURCE_REVISION is not defined');
+    },
+  });
+  expect(result.deliveryUnit.buildMarker).toBe('compiled-build');
+  expect(result.deliveryUnit.sourceRevision).toBe('workspace');
+  const failure = new Error('reader failed');
+  expect(() =>
+    resolveUltramodernBuildArtifact(artifact, {
+      ...readers,
+      buildMarker: () => {
+        throw failure;
+      },
+    }),
+  ).toThrow(failure);
+});

package/tests/contextExtensions.test.ts

@@ -0,0 +1,27 @@
+import { createRuntimeContextExtension } from '../src/contextExtensions';
+
+describe('runtime context extensions', () => {
+  it('does not leak into string-key enumeration of the context', () => {
+    const extension = createRuntimeContextExtension<string>('test:hidden');
+    const context = {};
+    const keysBefore = Object.keys(context);
+
+    extension.set(context, 'secret');
+
+    expect(Object.keys(context)).toEqual(keysBefore);
+    expect(JSON.stringify(context)).not.toContain('secret');
+    for (const key in context) {
+      expect(typeof key).toBe('string');
+      expect((context as Record<string, unknown>)[key]).not.toBe('secret');
+    }
+  });
+
+  it('survives object spreads so SSR context copies keep their extensions', () => {
+    const extension = createRuntimeContextExtension<string>('test:spread');
+    const context = {};
+    extension.set(context, 'carried');
+
+    const copy = { ...context };
+    expect(extension.get(copy)).toBe('carried');
+  });
+});

package/tests/headRuntime.test.tsx

@@ -0,0 +1,229 @@
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { createHeadRuntime } from '../src/headRuntime';
+import { ensureHelmetContext, getHelmetContext } from '../src/helmetContext';
+import * as rendererHead from '../src/rendererHead';
+
+const { Head: Helmet, wrapServerRoot } = createHeadRuntime();
+const getHelmetData = (context: object) => getHelmetContext(context)?.helmet;
+
+const createServerContext = () => ({ isBrowser: false }) as any;
+
+const renderWithContext = (context: any, node: React.ReactNode) => {
+  rendererHead.beginHeadRender(context);
+  try {
+    const html = renderToString(
+      wrapServerRoot(node, {
+        runtimeContext: context,
+        helmetContext: ensureHelmetContext(context),
+      }),
+    );
+    return rendererHead.completeHeadRender(context, html);
+  } catch (error) {
+    rendererHead.abortHeadRender(context);
+    throw error;
+  }
+};
+
+describe('server Helmet collection', () => {
+  it('keeps independently registered adapters scoped to their own providers', () => {
+    const outer = createHeadRuntime();
+    const inner = createHeadRuntime();
+    const outerContext = {};
+    const innerContext = {};
+
+    renderToString(
+      outer.wrapServerRoot(
+        inner.wrapServerRoot(
+          <>
+            <outer.Head>
+              <title>outer application</title>
+            </outer.Head>
+            <inner.Head>
+              <title>inner application</title>
+            </inner.Head>
+          </>,
+          {
+            runtimeContext: innerContext,
+            helmetContext: ensureHelmetContext(innerContext),
+          },
+        ),
+        {
+          runtimeContext: outerContext,
+          helmetContext: ensureHelmetContext(outerContext),
+        },
+      ),
+    );
+
+    expect(getHelmetData(outerContext)?.title.toString()).toBe(
+      '<title data-rh="true">outer application</title>',
+    );
+    expect(getHelmetData(innerContext)?.title.toString()).toBe(
+      '<title data-rh="true">inner application</title>',
+    );
+  });
+
+  it('excludes Helmet records from a discarded Suspense primary branch', () => {
+    const context = createServerContext();
+    const never = new Promise<never>(() => {});
+
+    const SuspendForever = (): null => {
+      throw never;
+    };
+
+    const html = renderWithContext(
+      context,
+      <>
+        <Helmet>
+          <meta name="outside" content="committed" />
+        </Helmet>
+        <React.Suspense
+          fallback={
+            <>
+              <Helmet>
+                <meta name="fallback" content="committed" />
+              </Helmet>
+              <span>fallback rendered</span>
+            </>
+          }
+        >
+          <Helmet>
+            <meta name="abandoned-unique" content="ghost" />
+          </Helmet>
+          <SuspendForever />
+        </React.Suspense>
+      </>,
+    );
+
+    expect(html).toContain('fallback rendered');
+    const meta = getHelmetData(context)!.meta.toString();
+    expect(meta).toContain('name="outside"');
+    expect(meta).toContain('name="fallback"');
+    expect(meta).not.toContain('name="abandoned-unique"');
+  });
+
+  it('collects title/meta during SSR and renders nothing inline', () => {
+    const context = createServerContext();
+    const html = renderWithContext(
+      context,
+      <main>
+        <Helmet>
+          <title>Server Title</title>
+          <meta name="description" content="hello" />
+        </Helmet>
+        body
+      </main>,
+    );
+
+    expect(html).not.toContain('Server Title');
+    const helmet = getHelmetData(context)!;
+    expect(helmet.title.toString()).toBe(
+      '<title data-rh="true">Server Title</title>',
+    );
+    expect(helmet.meta.toString()).toBe(
+      '<meta data-rh="true" name="description" content="hello">',
+    );
+  });
+
+  it('dedupes meta by primary attribute across nested Helmets, inner wins', () => {
+    const context = createServerContext();
+    renderWithContext(
+      context,
+      <>
+        <Helmet>
+          <meta name="description" content="outer" />
+          <meta name="keywords" content="modernjs" />
+        </Helmet>
+        <section>
+          <Helmet>
+            <meta name="description" content="inner" />
+          </Helmet>
+        </section>
+      </>,
+    );
+
+    const meta = getHelmetData(context)!.meta.toString();
+    expect(meta).toContain('content="inner"');
+    expect(meta).not.toContain('content="outer"');
+    expect(meta).toContain('content="modernjs"');
+  });
+
+  it('applies the innermost title and the innermost titleTemplate', () => {
+    const context = createServerContext();
+    renderWithContext(
+      context,
+      <>
+        <Helmet titleTemplate="%s | Site">
+          <title>Outer</title>
+        </Helmet>
+        <Helmet>
+          <title>Inner</title>
+        </Helmet>
+      </>,
+    );
+
+    expect(getHelmetData(context)!.title.toString()).toBe(
+      '<title data-rh="true">Inner | Site</title>',
+    );
+  });
+
+  it('publishes prioritized SEO tags separately with component parity', () => {
+    const context = createServerContext();
+    renderWithContext(
+      context,
+      <Helmet prioritizeSeoTags htmlAttributes={{ class: 'app' } as any}>
+        <title>Priority Page</title>
+        <meta name="description" content="priority description" />
+        <meta name="keywords" content="ordinary keywords" />
+        <link rel="canonical" href="https://example.com/page" />
+        <link rel="stylesheet" href="/page.css" />
+        <script type="application/ld+json">{'{"name":"page"}'}</script>
+        <script src="/ordinary.js" />
+      </Helmet>,
+    );
+
+    const helmet = getHelmetData(context)!;
+    expect(helmet.priority.toString()).toContain('priority description');
+    expect(helmet.priority.toString()).toContain('https://example.com/page');
+    expect(helmet.priority.toString()).toContain('application/ld+json');
+    expect(helmet.meta.toString()).toContain('ordinary keywords');
+    expect(helmet.meta.toString()).not.toContain('priority description');
+    expect(helmet.link.toString()).toContain('/page.css');
+    expect(helmet.link.toString()).not.toContain('https://example.com/page');
+    expect(helmet.script.toString()).toContain('/ordinary.js');
+    expect(helmet.script.toString()).not.toContain('application/ld+json');
+  });
+
+  it('is idempotent when React replays the tree (streaming SSR retry)', () => {
+    const context = createServerContext();
+    const app = (
+      <>
+        <Helmet titleTemplate="%s | Site">
+          <title>Page</title>
+          <meta name="description" content="stable" />
+          <html lang="en" />
+        </Helmet>
+        <Helmet>
+          <meta property="og:title" content="Page" />
+        </Helmet>
+      </>
+    );
+
+    renderWithContext(context, app);
+    const first = getHelmetData(context)!;
+    const firstSnapshot = {
+      title: first.title.toString(),
+      meta: first.meta.toString(),
+      htmlAttributes: first.htmlAttributes.toString(),
+    };
+
+    // Simulate a replayed render against the same per-request context.
+    renderWithContext(context, app);
+    const second = getHelmetData(context)!;
+
+    expect(second.title.toString()).toBe(firstSnapshot.title);
+    expect(second.meta.toString()).toBe(firstSnapshot.meta);
+    expect(second.htmlAttributes.toString()).toBe(firstSnapshot.htmlAttributes);
+    expect(second.meta.toString().match(/description/g)).toHaveLength(1);
+  });
+});