@wix/zero-config-implementation 1.71.0 → 1.73.0

package/src/react-runtime-loader.ts

@@ -0,0 +1,656 @@
+import { createHash } from 'node:crypto'
+import { createRequire, register } from 'node:module'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { MessageChannel, MessagePort } from 'node:worker_threads'
+import { buildRefElementTaggerSource, tagRefElementComponentForCleanup } from './ref-elements/component-tag'
+import type { RefElementModule } from './ref-elements/types'
+
+const JSX_INTERCEPTOR_STATE_KEY = 'zero-config:jsx-interceptor'
+const JSX_ORIGINALS_KEY = 'zero-config:jsx-originals'
+const REACT_ORIGINALS_KEY = 'zero-config:react-originals'
+const LOADER_REGISTERED_KEY = Symbol.for('zero-config:jsx-loader-registered')
+const RUNTIME_STATE_KEY = Symbol.for('zero-config:ref-element-runtime-state')
+const REF_ELEMENT_LOADER_REQUEST_TIMEOUT_MS = 1_000
+const REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM = 'zero-config-ref-entry'
+
+interface RegisteredRefElementModuleState {
+  exportNames: string[]
+  resolvedModuleUrl: string
+  refComponentType: string
+}
+
+interface PreparedRefElementEsmImport {
+  cleanup: () => Promise<void>
+  importUrl: string
+}
+
+interface RefElementLoaderRequest {
+  modulesByResolvedUrl: Record<string, RegisteredRefElementModuleState>
+  requestId: number
+  signature: string
+}
+
+interface RefElementLoaderResponse {
+  error?: string
+  requestId: number
+  success: boolean
+}
+
+interface PendingLoaderRequest {
+  reject: (error: Error) => void
+  resolve: () => void
+}
+
+interface ActiveCjsRefElementExtraction {
+  cleanupHandlers: Array<() => void>
+  id: number
+  runtimeModulesByResolvedPath: Map<string, RegisteredRefElementModuleState[]>
+}
+
+interface InternalModuleApi {
+  _load: (request: string, parent: NodeJS.Module | null | undefined, isMain: boolean) => unknown
+  _resolveFilename: (
+    request: string,
+    parent: NodeJS.Module | null | undefined,
+    isMain: boolean,
+    options?: unknown,
+  ) => string
+}
+
+interface RefElementRuntimeState {
+  activeCjsExtractions: Map<number, ActiveCjsRefElementExtraction>
+  loaderPort: MessagePort | null
+  nextCjsExtractionId: number
+  nextLoaderRequestId: number
+  pendingLoaderRequests: Map<number, PendingLoaderRequest>
+  registeredEsmModulesByResolvedUrl: Map<string, RegisteredRefElementModuleState>
+  originalModuleLoad: InternalModuleApi['_load'] | null
+}
+
+export async function prepareRefElementEsmImport(
+  entryPath: string,
+  runtimeModules: RefElementModule[] = [],
+): Promise<PreparedRefElementEsmImport> {
+  ensureReactRuntimeLoader()
+
+  if (runtimeModules.length === 0) {
+    return {
+      cleanup: async () => {},
+      importUrl: pathToFileURL(entryPath).href,
+    }
+  }
+
+  const registeredModules = mergeRefElementModules(runtimeModules)
+  const refElementEntrySignature = buildRefElementEntrySignature(registeredModules)
+  await registerEsmRefElementModules(refElementEntrySignature, registeredModules)
+  const entryImportUrl = pathToFileURL(entryPath)
+  entryImportUrl.searchParams.set(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM, refElementEntrySignature)
+
+  return {
+    cleanup: async () => {},
+    importUrl: entryImportUrl.href,
+  }
+}
+
+export function ensureReactRuntimeLoader(): void {
+  const globalRecord = globalThis as Record<symbol, unknown>
+  if (globalRecord[LOADER_REGISTERED_KEY]) {
+    return
+  }
+  const runtimeState = readRefElementRuntimeState()
+  const { port1: runtimePort, port2: loaderPort } = new MessageChannel()
+  try {
+    runtimeState.loaderPort = runtimePort
+    runtimePort.on('message', (message: RefElementLoaderResponse) => {
+      const pendingLoaderRequest = runtimeState.pendingLoaderRequests.get(message.requestId)
+      if (!pendingLoaderRequest) {
+        return
+      }
+
+      runtimeState.pendingLoaderRequests.delete(message.requestId)
+      if (message.success) {
+        pendingLoaderRequest.resolve()
+        return
+      }
+
+      pendingLoaderRequest.reject(new Error(message.error ?? 'Failed to register ref-element modules in the loader'))
+    })
+    runtimePort.unref()
+    loaderPort.unref()
+
+    const require = createRequire(import.meta.url)
+    const reactRuntime = require('react/jsx-runtime') as typeof import('react/jsx-runtime')
+    const reactDevRuntime = require('react/jsx-dev-runtime') as typeof import('react/jsx-dev-runtime')
+    const reactModule = require('react') as Record<string, unknown>
+    ;(globalThis as Record<PropertyKey, unknown>)[Symbol.for(JSX_ORIGINALS_KEY)] = {
+      Fragment: reactRuntime.Fragment,
+      jsx: reactRuntime.jsx,
+      jsxDEV: reactDevRuntime.jsxDEV,
+      jsxs: reactRuntime.jsxs,
+    }
+    ;(globalThis as Record<PropertyKey, unknown>)[Symbol.for(REACT_ORIGINALS_KEY)] = reactModule
+
+    const reactModuleUrl = `data:text/javascript,${encodeURIComponent(buildReactModuleShimSource(Object.keys(reactModule)))}`
+    const interceptorModuleUrl = `data:text/javascript,${encodeURIComponent(buildJsxRuntimeInterceptorSource())}`
+    const loaderSource = buildReactRuntimeLoaderSource({
+      interceptorModuleUrl,
+      reactModuleUrl,
+      taggerSource: buildRefElementTaggerSource(),
+    })
+
+    register(`data:text/javascript,${encodeURIComponent(loaderSource)}`, {
+      data: { port: loaderPort },
+      transferList: [loaderPort],
+    })
+    globalRecord[LOADER_REGISTERED_KEY] = true
+  } catch (error) {
+    runtimeState.loaderPort = null
+    runtimePort.close()
+    loaderPort.close()
+    throw error
+  }
+}
+
+export function readRegisteredRefElementModuleUrlsForTests(): string[] {
+  return [...readRefElementRuntimeState().registeredEsmModulesByResolvedUrl.keys()]
+}
+
+export function readLoaderPortRefStateForTests(): boolean | null {
+  const loaderPort = readRefElementRuntimeState().loaderPort
+  if (!(loaderPort instanceof MessagePort)) {
+    return null
+  }
+
+  return (loaderPort as MessagePort & { hasRef: () => boolean }).hasRef()
+}
+
+export function loadTaggedCjsModule(
+  entryPath: string,
+  runtimeModules: RefElementModule[] = [],
+): { cleanup: () => Promise<void>; moduleExports: Record<string, unknown> } {
+  const runtimeState = readRefElementRuntimeState()
+  const entryRequire = createRequire(entryPath)
+  const activeExtraction = createActiveCjsRefElementExtraction(runtimeState, runtimeModules)
+  installCjsRefElementInterception(runtimeState)
+
+  tagCachedCjsRefElementModules(entryRequire, activeExtraction)
+
+  let didCleanup = false
+  try {
+    const moduleExports = entryRequire(entryPath) as Record<string, unknown>
+
+    return {
+      cleanup: async () => {
+        if (didCleanup) {
+          return
+        }
+
+        didCleanup = true
+        cleanupActiveCjsRefElementExtraction(runtimeState, activeExtraction.id)
+      },
+      moduleExports,
+    }
+  } catch (error) {
+    cleanupActiveCjsRefElementExtraction(runtimeState, activeExtraction.id)
+    throw error
+  }
+}
+
+function readRefElementRuntimeState(): RefElementRuntimeState {
+  const globalRecord = globalThis as Record<symbol, RefElementRuntimeState | undefined>
+  const runtimeState = globalRecord[RUNTIME_STATE_KEY]
+  if (runtimeState) {
+    return runtimeState
+  }
+
+  const nextRuntimeState: RefElementRuntimeState = {
+    activeCjsExtractions: new Map(),
+    loaderPort: null,
+    nextCjsExtractionId: 0,
+    nextLoaderRequestId: 0,
+    pendingLoaderRequests: new Map(),
+    registeredEsmModulesByResolvedUrl: new Map(),
+    originalModuleLoad: null,
+  }
+  globalRecord[RUNTIME_STATE_KEY] = nextRuntimeState
+  return nextRuntimeState
+}
+
+async function registerEsmRefElementModules(
+  refElementEntrySignature: string,
+  runtimeModules: RegisteredRefElementModuleState[],
+): Promise<void> {
+  const runtimeState = readRefElementRuntimeState()
+  const modulesByResolvedUrl: Record<string, RegisteredRefElementModuleState> = {}
+
+  for (const runtimeModule of runtimeModules) {
+    const registeredModule = upsertRefElementModule(runtimeState.registeredEsmModulesByResolvedUrl, runtimeModule)
+    modulesByResolvedUrl[registeredModule.resolvedModuleUrl] = registeredModule
+  }
+
+  await postRefElementLoaderRequest({
+    modulesByResolvedUrl,
+    signature: refElementEntrySignature,
+  })
+}
+
+function postRefElementLoaderRequest(request: Omit<RefElementLoaderRequest, 'requestId'>): Promise<void> {
+  const runtimeState = readRefElementRuntimeState()
+  const loaderPort = runtimeState.loaderPort
+  if (!(loaderPort instanceof MessagePort)) {
+    return Promise.reject(new Error('Ref-element loader has not been initialized'))
+  }
+
+  runtimeState.nextLoaderRequestId += 1
+  const requestId = runtimeState.nextLoaderRequestId
+
+  return new Promise<void>((resolve, reject) => {
+    const requestTimeout = setTimeout(() => {
+      runtimeState.pendingLoaderRequests.delete(requestId)
+      reject(new Error('Timed out waiting for ref-element loader registration'))
+    }, REF_ELEMENT_LOADER_REQUEST_TIMEOUT_MS)
+
+    runtimeState.pendingLoaderRequests.set(requestId, {
+      reject: (error) => {
+        clearTimeout(requestTimeout)
+        reject(error)
+      },
+      resolve: () => {
+        clearTimeout(requestTimeout)
+        resolve()
+      },
+    })
+
+    loaderPort.postMessage({
+      ...request,
+      requestId,
+    } satisfies RefElementLoaderRequest)
+  })
+}
+
+function createActiveCjsRefElementExtraction(
+  runtimeState: RefElementRuntimeState,
+  runtimeModules: RefElementModule[],
+): ActiveCjsRefElementExtraction {
+  runtimeState.nextCjsExtractionId += 1
+
+  const activeExtraction: ActiveCjsRefElementExtraction = {
+    cleanupHandlers: [],
+    id: runtimeState.nextCjsExtractionId,
+    runtimeModulesByResolvedPath: new Map(),
+  }
+
+  for (const runtimeModule of mergeRefElementModules(runtimeModules)) {
+    if (!runtimeModule.resolvedModuleUrl.startsWith('file:')) {
+      continue
+    }
+
+    const resolvedModulePath = fileURLToPath(runtimeModule.resolvedModuleUrl)
+    const existingRuntimeModules = activeExtraction.runtimeModulesByResolvedPath.get(resolvedModulePath) ?? []
+    existingRuntimeModules.push(runtimeModule)
+    activeExtraction.runtimeModulesByResolvedPath.set(resolvedModulePath, existingRuntimeModules)
+  }
+
+  runtimeState.activeCjsExtractions.set(activeExtraction.id, activeExtraction)
+  return activeExtraction
+}
+
+function installCjsRefElementInterception(runtimeState: RefElementRuntimeState): void {
+  if (runtimeState.originalModuleLoad) {
+    return
+  }
+
+  const internalModule = readInternalModuleApi()
+  runtimeState.originalModuleLoad = internalModule._load
+  internalModule._load = function (
+    request: string,
+    parent: NodeJS.Module | null | undefined,
+    isMain: boolean,
+  ): unknown {
+    const moduleExports = runtimeState.originalModuleLoad?.call(this, request, parent, isMain)
+    const resolvedModulePath = resolveRequestedCjsModulePath(request, parent, isMain)
+
+    if (resolvedModulePath) {
+      tagActiveCjsRefElementModules(runtimeState, resolvedModulePath, moduleExports)
+    }
+
+    return moduleExports
+  }
+}
+
+function cleanupActiveCjsRefElementExtraction(runtimeState: RefElementRuntimeState, extractionId: number): void {
+  const activeExtraction = runtimeState.activeCjsExtractions.get(extractionId)
+  if (!activeExtraction) {
+    return
+  }
+
+  runtimeState.activeCjsExtractions.delete(extractionId)
+
+  for (const cleanupHandler of activeExtraction.cleanupHandlers.reverse()) {
+    cleanupHandler()
+  }
+
+  if (runtimeState.activeCjsExtractions.size !== 0) {
+    return
+  }
+
+  const internalModule = readInternalModuleApi()
+  if (runtimeState.originalModuleLoad) {
+    internalModule._load = runtimeState.originalModuleLoad
+    runtimeState.originalModuleLoad = null
+  }
+}
+
+function tagCachedCjsRefElementModules(
+  entryRequire: NodeJS.Require,
+  activeExtraction: ActiveCjsRefElementExtraction,
+): void {
+  for (const [resolvedModulePath, runtimeModules] of activeExtraction.runtimeModulesByResolvedPath) {
+    const cachedModule = entryRequire.cache[resolvedModulePath]
+    if (!cachedModule) {
+      continue
+    }
+
+    for (const runtimeModule of runtimeModules) {
+      activeExtraction.cleanupHandlers.push(...tagCjsRefElementModuleExports(cachedModule.exports, runtimeModule))
+    }
+  }
+}
+
+function tagActiveCjsRefElementModules(
+  runtimeState: RefElementRuntimeState,
+  resolvedModulePath: string,
+  moduleExports: unknown,
+): void {
+  for (const activeExtraction of runtimeState.activeCjsExtractions.values()) {
+    const runtimeModules = activeExtraction.runtimeModulesByResolvedPath.get(resolvedModulePath)
+    if (!runtimeModules) {
+      continue
+    }
+
+    for (const runtimeModule of runtimeModules) {
+      activeExtraction.cleanupHandlers.push(...tagCjsRefElementModuleExports(moduleExports, runtimeModule))
+    }
+  }
+}
+
+function readInternalModuleApi(): InternalModuleApi {
+  const require = createRequire(import.meta.url)
+  return require('node:module') as InternalModuleApi
+}
+
+function resolveRequestedCjsModulePath(
+  request: string,
+  parent: NodeJS.Module | null | undefined,
+  isMain: boolean,
+): string | undefined {
+  try {
+    return readInternalModuleApi()._resolveFilename(request, parent, isMain)
+  } catch {
+    return undefined
+  }
+}
+
+function tagCjsRefElementModuleExports(
+  moduleExports: unknown,
+  runtimeModule: RegisteredRefElementModuleState,
+): Array<() => void> {
+  const cleanupHandlers: Array<() => void> = []
+
+  for (const exportName of runtimeModule.exportNames) {
+    const exportValue = readModuleExportValue(moduleExports, exportName)
+    const cleanupHandler = tagRefElementComponentForCleanup(exportValue, runtimeModule.refComponentType)
+    if (cleanupHandler) {
+      cleanupHandlers.push(cleanupHandler)
+    }
+  }
+
+  return cleanupHandlers
+}
+
+function mergeRefElementModules(runtimeModules: RefElementModule[]): RegisteredRefElementModuleState[] {
+  const registeredModulesByResolvedUrl = new Map<string, RegisteredRefElementModuleState>()
+
+  for (const runtimeModule of runtimeModules) {
+    upsertRefElementModule(registeredModulesByResolvedUrl, {
+      exportNames: [...runtimeModule.exportNames],
+      resolvedModuleUrl: runtimeModule.resolvedModuleUrl,
+      refComponentType: runtimeModule.refComponentType,
+    })
+  }
+
+  return [...registeredModulesByResolvedUrl.values()]
+}
+
+function upsertRefElementModule(
+  registeredModulesByResolvedUrl: Map<string, RegisteredRefElementModuleState>,
+  nextModule: RegisteredRefElementModuleState,
+): RegisteredRefElementModuleState {
+  const existingModule = registeredModulesByResolvedUrl.get(nextModule.resolvedModuleUrl)
+  if (!existingModule) {
+    registeredModulesByResolvedUrl.set(nextModule.resolvedModuleUrl, nextModule)
+    return nextModule
+  }
+
+  if (existingModule.refComponentType !== nextModule.refComponentType) {
+    throw new Error(
+      `Conflicting ref-element types for ${nextModule.resolvedModuleUrl}: ` +
+        `${existingModule.refComponentType} vs ${nextModule.refComponentType}`,
+    )
+  }
+
+  existingModule.exportNames = [...new Set([...existingModule.exportNames, ...nextModule.exportNames])]
+  return existingModule
+}
+
+function buildRefElementEntrySignature(registeredModules: RegisteredRefElementModuleState[]): string {
+  const stableSignatureInput = registeredModules
+    .map((registeredModule) => ({
+      exportNames: [...registeredModule.exportNames].sort(),
+      refComponentType: registeredModule.refComponentType,
+      resolvedModuleUrl: registeredModule.resolvedModuleUrl,
+    }))
+    .sort((leftModule, rightModule) => JSON.stringify(leftModule).localeCompare(JSON.stringify(rightModule)))
+
+  return createHash('sha1').update(JSON.stringify(stableSignatureInput)).digest('hex')
+}
+
+function readModuleExportValue(moduleExports: unknown, exportName: string): unknown {
+  if (exportName === 'default') {
+    if (isComponent(moduleExports)) {
+      return moduleExports
+    }
+
+    if (typeof moduleExports === 'object' && moduleExports !== null) {
+      return (moduleExports as Record<string, unknown>).default
+    }
+
+    return undefined
+  }
+
+  if (typeof moduleExports !== 'object' || moduleExports === null) {
+    return undefined
+  }
+
+  return (moduleExports as Record<string, unknown>)[exportName]
+}
+
+function isComponent(value: unknown): boolean {
+  if (typeof value === 'function') {
+    return true
+  }
+
+  return typeof value === 'object' && value !== null && '$$typeof' in value
+}
+
+function buildReactModuleShimSource(reactExportNames: string[]): string {
+  const reactExportLines = reactExportNames
+    .map((exportName) => {
+      if (exportName === 'createElement') {
+        return `export function createElement() {
+  var state = globalThis[STATE_KEY];
+  if (state && state.currentCreateElement) return state.currentCreateElement.apply(null, arguments);
+  return reactModule.createElement.apply(null, arguments);
+}`
+      }
+
+      return `export var ${exportName} = reactModule.${exportName};`
+    })
+    .join('\n')
+
+  return `
+var REACT_KEY = Symbol.for(${JSON.stringify(REACT_ORIGINALS_KEY)});
+var STATE_KEY = Symbol.for(${JSON.stringify(JSX_INTERCEPTOR_STATE_KEY)});
+var reactModule = globalThis[REACT_KEY];
+export default reactModule;
+${reactExportLines}
+`
+}
+
+function buildJsxRuntimeInterceptorSource(): string {
+  return `
+const ORIGINALS_KEY = Symbol.for(${JSON.stringify(JSX_ORIGINALS_KEY)});
+const STATE_KEY = Symbol.for(${JSON.stringify(JSX_INTERCEPTOR_STATE_KEY)});
+const originals = globalThis[ORIGINALS_KEY];
+function getState() {
+  if (!globalThis[STATE_KEY]) {
+    globalThis[STATE_KEY] = {
+      currentJsx: originals.jsx, currentJsxs: originals.jsxs,
+      currentJsxDEV: originals.jsxDEV, isInsideOriginal: false,
+    };
+  }
+  return globalThis[STATE_KEY];
+}
+export const Fragment = originals.Fragment;
+export function jsx(type, props, key) {
+  const state = getState();
+  if (state.isInsideOriginal) return originals.jsx(type, props, key);
+  state.isInsideOriginal = true;
+  try { return state.currentJsx(type, props, key); }
+  finally { state.isInsideOriginal = false; }
+}
+export function jsxs(type, props, key) {
+  const state = getState();
+  if (state.isInsideOriginal) return originals.jsxs(type, props, key);
+  state.isInsideOriginal = true;
+  try { return state.currentJsxs(type, props, key); }
+  finally { state.isInsideOriginal = false; }
+}
+export function jsxDEV(type, props, key, isStaticChildren, source, self) {
+  const state = getState();
+  if (state.isInsideOriginal) return originals.jsxDEV(type, props, key, isStaticChildren, source, self);
+  state.isInsideOriginal = true;
+  try { return state.currentJsxDEV(type, props, key, isStaticChildren, source, self); }
+  finally { state.isInsideOriginal = false; }
+}
+`
+}
+
+function buildReactRuntimeLoaderSource(options: {
+  interceptorModuleUrl: string
+  reactModuleUrl: string
+  taggerSource: string
+}): string {
+  return `
+const INTERCEPTOR_URL = ${JSON.stringify(options.interceptorModuleUrl)};
+const REACT_MODULE_URL = ${JSON.stringify(options.reactModuleUrl)};
+const TAGGER_SOURCE = ${JSON.stringify(options.taggerSource)};
+const REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM = ${JSON.stringify(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM)};
+const refElementModulesBySignature = Object.create(null);
+export function initialize(data) {
+  data.port.on('message', (message) => {
+    try {
+      const registeredModulesByResolvedUrl = refElementModulesBySignature[message.signature] ?? Object.create(null);
+      Object.assign(registeredModulesByResolvedUrl, message.modulesByResolvedUrl);
+      refElementModulesBySignature[message.signature] = registeredModulesByResolvedUrl;
+
+      data.port.postMessage({ requestId: message.requestId, success: true });
+    } catch (error) {
+      data.port.postMessage({
+        error: error instanceof Error ? error.message : String(error),
+        requestId: message.requestId,
+        success: false,
+      });
+    }
+  });
+}
+function createTaggedRefElementModuleUrl(realUrl, moduleState) {
+  const realModuleImportUrl = new URL(realUrl);
+  realModuleImportUrl.searchParams.set('zero-config-ref-real', moduleState.refComponentType);
+  const namedExportLines = moduleState.exportNames
+    .filter((exportName) => exportName !== 'default')
+    .map((exportName) => \`export const \${exportName} = safelyTagRefElementComponent(realModule.\${exportName}, REF_COMPONENT_TYPE);\`)
+    .join('\\n');
+  const taggedModuleSource = \`
+import * as realModule from \${JSON.stringify(realModuleImportUrl.href)};
+const REF_COMPONENT_TYPE = \${JSON.stringify(moduleState.refComponentType)};
+\${TAGGER_SOURCE}
+export default safelyTagRefElementComponent(realModule.default ?? realModule, REF_COMPONENT_TYPE);
+\${namedExportLines}
+export * from \${JSON.stringify(realModuleImportUrl.href)};
+\`;
+
+  return \`data:text/javascript,\${encodeURIComponent(taggedModuleSource)}\`;
+}
+function readRefElementEntrySignature(urlString) {
+  if (!urlString) {
+    return undefined;
+  }
+
+  try {
+    const url = new URL(urlString);
+    return url.searchParams.get(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+function shouldPropagateRefElementEntrySignature(resolvedUrl) {
+  return resolvedUrl.startsWith('file:') && !resolvedUrl.includes('/node_modules/');
+}
+function addRefElementEntrySignature(resolvedUrl, refElementEntrySignature) {
+  const signedUrl = new URL(resolvedUrl);
+  if (!signedUrl.searchParams.has(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM)) {
+    signedUrl.searchParams.set(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM, refElementEntrySignature);
+  }
+  return signedUrl.href;
+}
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier === 'react/jsx-runtime' || specifier === 'react/jsx-dev-runtime') {
+    return { shortCircuit: true, url: INTERCEPTOR_URL };
+  }
+  if (specifier === 'react') {
+    return { shortCircuit: true, url: REACT_MODULE_URL };
+  }
+
+  const resolvedModule = await nextResolve(specifier, context);
+  if (new URL(resolvedModule.url).searchParams.has('zero-config-ref-real')) {
+    return resolvedModule;
+  }
+
+  const refElementEntrySignature = readRefElementEntrySignature(context.parentURL);
+  if (!refElementEntrySignature) {
+    return resolvedModule;
+  }
+
+  const refElementModulesByResolvedUrl = refElementModulesBySignature[refElementEntrySignature] ?? Object.create(null);
+  const moduleState = refElementModulesByResolvedUrl[resolvedModule.url];
+  if (moduleState) {
+    return {
+      ...resolvedModule,
+      shortCircuit: true,
+      url: createTaggedRefElementModuleUrl(resolvedModule.url, moduleState),
+    };
+  }
+
+  if (shouldPropagateRefElementEntrySignature(resolvedModule.url)) {
+    return {
+      ...resolvedModule,
+      shortCircuit: true,
+      url: addRefElementEntrySignature(resolvedModule.url, refElementEntrySignature),
+    };
+  }
+
+  return resolvedModule;
+}
+`
+}