@revealui/core 0.0.1-pre.0

package/dist/core/processing/getters/getPageAssets.ts

@@ -0,0 +1,140 @@
+export { getPageAssets, setResolveClientEntriesDev }
+export type { GetPageAssets, PageAsset, PageContextGetPageAssets }
+
+import type { ResolveClientEntriesDev } from "../../../plugins/resolveClientEntriesDev.js"
+import { ClientDependency } from "../../../types/interfaces/client.js"
+import { ViteManifest } from "../../../types/interfaces/manifest.js"
+import { getGlobalContext } from "../../globals/contexts/globalContext/index.js"
+import {
+  inferMediaType,
+  type MediaType,
+} from "../../renderer/page/inferMediaType.js"
+import {
+  assert,
+  prependBase,
+  toPosixPath,
+  unique,
+} from "../../renderer/stream/utils.js"
+import getGlobalObject from "./getGlobalObject.js"
+import { getManifestEntry } from "./getPageAssets/getManifestEntry.js"
+import { retrieveAssetsDev } from "./getPageAssets/retrieveAssetsDev.js"
+import { retrieveAssetsProd } from "./getPageAssets/retrieveAssetsProd.js"
+import { sortPageAssetsForEarlyHintsHeader } from "./getPageAssets/sortPageAssetsForEarlyHintsHeader.js"
+
+const globalObject = getGlobalObject("getPageAssets.ts", {
+  resolveClientEntriesDev: null as null | ResolveClientEntriesDev,
+})
+
+type PageAsset = {
+  src: string
+  assetType: null | NonNullable<MediaType>["assetType"]
+  mediaType: null | NonNullable<MediaType>["mediaType"]
+  isEntry: boolean
+}
+type GetPageAssets = () => Promise<PageAsset[]>
+
+type PageContextGetPageAssets = {
+  _baseServer: string
+  _baseAssets: string | null
+  _includeAssetsImportedByServer: boolean
+}
+
+async function getPageAssets(
+  pageContext: PageContextGetPageAssets,
+  clientDependencies: ClientDependency[],
+  clientEntries: string[]
+): Promise<PageAsset[]> {
+  const globalContext = getGlobalContext()
+  const isDev = !globalContext.isProduction
+
+  let assetUrls: string[]
+  let clientEntriesSrc: string[]
+  if (isDev) {
+    const { viteDevServer } = globalContext
+    const clientEntriesResults = await Promise.allSettled(
+      clientEntries.map((clientEntry) =>
+        globalObject.resolveClientEntriesDev!(clientEntry, viteDevServer)
+      )
+    )
+    clientEntriesSrc = clientEntriesResults
+      .filter(
+        (result): result is PromiseFulfilledResult<string> =>
+          result.status === "fulfilled"
+      )
+      .map((result) => result.value)
+    assetUrls = await retrieveAssetsDev(clientDependencies, viteDevServer)
+  } else {
+    const { assetsManifest } = globalContext
+    clientEntriesSrc = clientEntries.map((clientEntry) =>
+      resolveClientEntriesProd(clientEntry, assetsManifest)
+    )
+    assetUrls = retrieveAssetsProd(
+      clientDependencies,
+      assetsManifest,
+      pageContext._includeAssetsImportedByServer
+    )
+  }
+
+  let pageAssets: PageAsset[] = []
+  unique([...clientEntriesSrc, ...assetUrls]).forEach((src: string) => {
+    const { mediaType = null, assetType = null } = inferMediaType(src) || {}
+
+    if (isDev && assetType === "style") {
+      // https://github.com/revealjs/reveal/issues/449
+      if (src.endsWith("?inline")) {
+        return
+      }
+      // https://github.com/revealjs/reveal/issues/401
+      // WARNING: if changing following line, then also update https://github.com/revealjs/reveal/blob/fae90a15d88e5e87ca9fcbb54cf2dc8773d2f229/reveal/client/shared/removeFoucBuster.ts#L28
+      src = src + "?direct"
+    }
+
+    const isEntry =
+      clientEntriesSrc.includes(src) ||
+      // Vite automatically injects CSS, not only in development, but also in production (albeit with a FOUC). Therefore, strictly speaking, CSS aren't entries. We still, however, set `isEntry: true` for CSS, in order to denote page assets that should absolutely be injected in the HTML, regardless of preload strategy (not injecting CSS leads to FOUC).
+      assetType === "style"
+
+    pageAssets.push({
+      src,
+      assetType,
+      mediaType,
+      isEntry,
+    })
+  })
+
+  pageAssets.forEach(({ src }) => {
+    assert(1 === pageAssets.filter((p) => p.src === src).length)
+  })
+
+  pageAssets = pageAssets.map((pageAsset) => {
+    const baseServerAssets = pageContext._baseAssets || pageContext._baseServer
+    pageAsset.src = prependBase(toPosixPath(pageAsset.src), baseServerAssets)
+    return pageAsset
+  })
+
+  sortPageAssetsForEarlyHintsHeader(pageAssets)
+
+  return pageAssets
+}
+
+function resolveClientEntriesProd(
+  clientEntry: string,
+  assetsManifest: ViteManifest
+): string {
+  const { manifestEntry } = getManifestEntry(clientEntry, assetsManifest)
+  assert(
+    manifestEntry.isEntry ||
+      manifestEntry.isDynamicEntry ||
+      clientEntry.endsWith(".css"),
+    { clientEntry }.clientEntry
+  )
+  let { file } = manifestEntry
+  assert(!file.startsWith("/"))
+  return "/" + file
+}
+
+function setResolveClientEntriesDev(
+  resolveClientEntriesDev: ResolveClientEntriesDev
+) {
+  globalObject.resolveClientEntriesDev = resolveClientEntriesDev
+}

package/dist/core/processing/getters/getPageConfig.ts

@@ -0,0 +1,14 @@
+import { PageConfigRuntime } from "../../../types/interfaces/page";
+import { assert } from "../../gaurds/assertions/assert";
+
+export { getPageConfig };
+
+function getPageConfig(
+  pageId: string,
+  pageConfigs: PageConfigRuntime[],
+): PageConfigRuntime {
+  const pageConfig = pageConfigs.find((p) => p.pageId === pageId);
+  assert(pageConfigs.length > 0);
+  assert(pageConfig);
+  return pageConfig;
+}

package/dist/core/processing/getters/getPageContext.ts

@@ -0,0 +1,64 @@
+import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js"
+import { assertWarning } from "../../gaurds/assertions/assertWarning/index.js"
+import { loadUserFilesClientSide } from "../../targets/client/loadUserFilesClientSide.js"
+
+import { objectAssign } from "../../utils/object/objectAssign.js"
+import { getCurrentUrl } from "./getCurrentUrl.js"
+
+import { getPageContextSerializedInHtml } from "./getPageContextSerializedInHtml.js"
+import { getPageFilesAll } from "./getPageFiles/index.js"
+
+export { getPageContext }
+
+const urlFirst = getCurrentUrl({ withoutHash: true })
+
+async function getPageContext() {
+  const pageContext = getPageContextSerializedInHtml()
+  objectAssign(pageContext, {
+    isHydration: true as const,
+    isBackwardNavigation: null,
+    _hasPageContextFromServer: true as const,
+    _hasPageContextFromClient: false as const,
+  })
+  objectAssign(pageContext, await loadPageUserFiles(pageContext.pageId))
+  assertPristineUrl()
+  return pageContext
+}
+
+function assertPristineUrl() {
+  const urlCurrent = getCurrentUrl({ withoutHash: true })
+  assertUsage(
+    urlFirst === urlCurrent,
+    `The URL was manipulated before the hydration finished ('${urlFirst}' to '${urlCurrent}'). Ensure the hydration has finished before manipulating the URL. Consider using the onHydrationEnd() hook.`
+  )
+}
+
+async function loadPageUserFiles(pageId: string) {
+  const pageContextAddendum = {}
+  const { pageFilesAll, pageConfigs } = await getPageFilesAll(true)
+  objectAssign(pageContextAddendum, {
+    _pageFilesAll: pageFilesAll,
+    _pageConfigs: pageConfigs,
+  })
+
+  objectAssign(
+    pageContextAddendum,
+    await loadUserFilesClientSide(
+      pageId,
+      pageContextAddendum._pageFilesAll,
+      pageContextAddendum._pageConfigs
+    )
+  )
+
+  pageFilesAll
+    .filter((p) => p.fileType !== ".page.server")
+    .forEach((p) => {
+      assertWarning(
+        !p.fileExports?.onBeforeRender,
+        `export { onBeforeRender } of ${p.filePath} is loaded in the browser but never executed (because you are using Server-side Routing). In order to reduce the size of you browser-side JavaScript, define onBeforeRender() in a .page.server.js file instead, see https://reveal.dev/onBeforeRender-isomorphic#server-routing`,
+        { onlyOnce: true }
+      )
+    })
+
+  return pageContextAddendum
+}

package/dist/core/processing/getters/getPageContextCurrent.ts

@@ -0,0 +1,19 @@
+import getGlobalObject from "./getGlobalObject";
+import { PageContextExports } from "./getPageFiles";
+
+export { getPageContextCurrent, setPageContextCurrent };
+
+type PageContextCurrent = PageContextExports & {
+  urlPathname: string;
+};
+const globalObject = getGlobalObject("getPageContextCurrent.ts", {
+  pageContextCurrent: null as null | PageContextCurrent,
+});
+
+function getPageContextCurrent(): null | PageContextCurrent {
+  const { pageContextCurrent } = globalObject;
+  return pageContextCurrent;
+}
+function setPageContextCurrent(pageContextCurrent: PageContextCurrent): void {
+  globalObject.pageContextCurrent = pageContextCurrent;
+}

package/dist/core/processing/getters/getPageContextFromHooks.ts

@@ -0,0 +1,335 @@
+export {
+  getPageContextFromClientHooks,
+  getPageContextFromHooks_isHydration,
+  getPageContextFromHooks_serialized,
+  getPageContextFromServerHooks,
+  setPageContextInitIsPassedToClient,
+}
+export type { PageContextFromClientHooks, PageContextFromServerHooks }
+
+import { PageConfigRuntime } from "../../../types/interfaces/page.js"
+import {PageFile} from "../../__internal/index.js"
+import { assert } from "../../gaurds/assertions/assert/index.js"
+import { assertOnBeforeRenderHookReturn } from "../../gaurds/assertions/assertOnBeforeRenderHookReturn.js"
+import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js"
+import { isObject } from "../../gaurds/validators/isObject.js"
+import {isServerSideError} from "../../gaurds/validators/isServerSideError.js"
+import {isAbortPageContext,AbortRender} from "../../router/abort.js"
+import { executeGuardHook } from "../../router/executeGuardHook.js"
+import { pageContextInitIsPassedToClient } from "../../targets/client/pageContextInitIsPassedToClient.js"
+import { preparePageContextForUserConsumptionClientSide } from "../../targets/client/preparePageContextForUserConsumptionClientSide.js"
+import { removeBuiltInOverrides } from "../../targets/client/removeBuiltInOverrides.js"
+import { executeHook, hasProp, redirectHard } from "../../targets/client/utils.js"
+import { objectAssign } from "../../utils/object/objectAssign.js"
+import {parse} from "../parsers/parseTransform.js"
+import { getConfigValueRuntime } from "./getConfigValue.js"
+import getGlobalObject from "./getGlobalObject.js"
+import { getHook } from "./getHook.js"
+import { getPageConfig } from "./getPageConfig.js"
+import {getPageContextRequestUrl} from "./getPageContextRequestUrl.js"
+import { getPageContextSerializedInHtml } from "./getPageContextSerializedInHtml.js"
+import {analyzePageServerSide} from "./getPageFiles/analyzePageServerSide.js"
+import { PageContextExports } from "./getPageFiles/index.js"
+import {getProjectError} from "./getProjectError.js"
+
+const globalObject = getGlobalObject<{ pageContextInitIsPassedToClient?: true }>('router/getPageContext.ts', {})
+
+/**
+ * Internal page context type
+ * @internal
+ * Note: This type will be renamed in a future release as part of the V1 design migration
+ */
+type PageContext = {
+  urlOriginal: string
+  _urlRewrite: string | null
+  _pageFilesAll: PageFile[]
+  _pageConfigs: PageConfigRuntime[]
+  config: PageConfigRuntime & { Page: Record<string, unknown> }
+}
+
+/**
+ * Serialized page context for client-side hydration
+ * @internal
+ * Note: This type will be renamed in a future release
+ */
+type PageContextSerialized = {
+  pageId: string
+  _hasPageContextFromServer: true
+}
+function getPageContextFromHooks_serialized(): PageContextSerialized & {
+  routeParams: Record<string, string>
+  _hasPageContextFromServer: true
+} {
+  const pageContextSerialized = getPageContextSerializedInHtml()
+  assertUsage(!('urlOriginal' in pageContextSerialized), "Adding 'urlOriginal' to passToClient is forbidden")
+  processPageContextFromServer(pageContextSerialized)
+  objectAssign(pageContextSerialized, {
+    _hasPageContextFromServer: true as const
+  })
+  return pageContextSerialized
+}
+// TODO/eventually: rename
+async function getPageContextFromHooks_isHydration(
+  pageContext: PageContextSerialized & PageContext & PageContextExports & { _hasPageContextFromServer: true }
+) {
+  objectAssign(pageContext, {
+    _hasPageContextFromClient: false
+  })
+  for (const hookName of ['data', 'onBeforeRender'] as const) {
+    if (hookClientOnlyExists(hookName, pageContext)) {
+      const pageContextFromHook = await executeHookClientSide(hookName, pageContext)
+      assert(!('urlOriginal' in pageContextFromHook))
+      Object.assign(pageContext, pageContextFromHook)
+    }
+  }
+  return pageContext
+}
+
+type PageContextFromServerHooks = { _hasPageContextFromServer: boolean }
+async function getPageContextFromServerHooks(
+  pageContext: { pageId: string } & PageContext,
+  isErrorPage: boolean
+): Promise<
+  | { is404ServerSideRouted: true }
+  | {
+      is404ServerSideRouted?: undefined
+      pageContextFromServerHooks: PageContextFromServerHooks
+    }
+> {
+  const pageContextFromServerHooks = {
+    _hasPageContextFromServer: false
+  }
+
+  // If pageContextInit has some client data or if one of the hooks guard(), data() or onBeforeRender() is server-side
+  // only, then we need to fetch pageContext from the server.
+  // We do it before executing any client-side hook, because it contains pageContextInit which may be needed for guard() / data() / onBeforeRender(), for example pageContextInit.user is crucial for guard()
+  if (
+    // For the error page, we cannot fetch pageContext from the server because the pageContext JSON request is based on the URL
+    !isErrorPage &&
+    // true if pageContextInit has some client data or at least one of the data() and onBeforeRender() hooks is server-side only:
+    (await hasPageContextServer(pageContext))
+  ) {
+    const res = await fetchPageContextFromServer(pageContext)
+    if ('is404ServerSideRouted' in res) return { is404ServerSideRouted: true as const }
+    const { pageContextFromServer } = res
+    pageContextFromServerHooks._hasPageContextFromServer = true
+
+    // Already handled
+    assert(!(isServerSideError in pageContextFromServer))
+    assert(!('serverSideError' in pageContextFromServer))
+
+    objectAssign(pageContextFromServerHooks, pageContextFromServer)
+  }
+
+  // We cannot return the whole pageContext because this function is used for prefetching `pageContext` (which requires a partial pageContext to be merged with the future pageContext created upon rendering the page in the future).
+  return { pageContextFromServerHooks }
+}
+
+type PageContextFromClientHooks = { _hasPageContextFromClient: boolean }
+async function getPageContextFromClientHooks(
+  pageContext: { pageId: string; _hasPageContextFromServer: boolean } & PageContext & PageContextExports,
+  isErrorPage: boolean
+): Promise<PageContextFromClientHooks> {
+  objectAssign(pageContext, {
+    _hasPageContextFromClient: false
+  })
+
+  // At this point, we need to call the client-side guard(), data() and onBeforeRender() hooks, if they exist on client
+  // env. However if we have fetched pageContext from the server, some of them might have run already on the
+  // server-side, so we run only the client-only ones in this case.
+  // Note: for the error page, we also execute the client-side data() and onBeforeRender() hooks, but maybe we
+  // shouldn't? The server-side does it as well (but maybe it shouldn't).
+  for (const hookName of ['guard', 'data', 'onBeforeRender'] as const) {
+    if (hookName === 'guard') {
+      if (
+        !isErrorPage &&
+        // We don't need to call guard() on the client-side if we fetch pageContext from the server side. (Because the `${url}.pageContext.json` HTTP request will already trigger the routing and guard() hook on the server-side.)
+        !pageContext._hasPageContextFromServer
+      ) {
+        // Should we really call the guard() hook on the client-side? Shouldn't we make the guard() hook a server-side
+        // only hook? Or maybe make its env configurable like data() and onBeforeRender()?
+        await executeGuardHook(pageContext, (pageContext) =>
+          preparePageContextForUserConsumptionClientSide(
+            { ...pageContext, config: { ...pageContext.config, Page: pageContext.config.Page ?? {} } },
+            true
+          )
+        )
+      }
+    } else {
+      assert(hookName === 'data' || hookName === 'onBeforeRender')
+      if (hookClientOnlyExists(hookName, pageContext) || !pageContext._hasPageContextFromServer) {
+        // This won't do anything if no hook has been defined or if the hook's env.client is false.
+        const pageContextFromHook = await executeHookClientSide(hookName, pageContext)
+        assert(!('urlOriginal' in pageContextFromHook))
+        Object.assign(pageContext, pageContextFromHook)
+      }
+    }
+  }
+
+  const pageContextFromClientHooks = pageContext
+  return pageContextFromClientHooks
+}
+
+async function executeHookClientSide(
+  hookName: 'data' | 'onBeforeRender',
+  pageContext: {
+    pageId: string
+    _hasPageContextFromServer: boolean
+    _hasPageContextFromClient: boolean
+  } & PageContextExports &
+    PageContext
+) {
+  const hook = getHook(pageContext, hookName)
+  if (!hook) {
+    // No hook defined or hook's env.client is false
+    return {}
+  }
+  const pageConfig = getPageConfig(pageContext.pageId, pageContext._pageConfigs);
+  const pageContextForUserConsumption = preparePageContextForUserConsumptionClientSide(
+    { ...pageContext, config: { ...pageConfig, Page: pageConfig.Page ?? {} } },
+    true
+  );
+  const hookResult = await executeHook(() => hook.hookFn(pageContextForUserConsumption), hook, pageContext)
+
+  const pageContextFromHook = {}
+  if (hookName === 'onBeforeRender') {
+    assertOnBeforeRenderHookReturn(hookResult, hook.hookFilePath)
+    // Note: hookResult looks like { pageContext: { ... } }
+    const pageContextFromOnBeforeRender = hookResult?.pageContext
+    if (pageContextFromOnBeforeRender) {
+      objectAssign(pageContextFromHook, { _hasPageContextFromClient: true })
+      objectAssign(pageContextFromHook, pageContextFromOnBeforeRender)
+    }
+  } else {
+    assert(hookName === 'data')
+    // Note: hookResult can be anything (e.g. an object) and is to be assigned to pageContext.data
+    const pageContextFromData = {
+      data: hookResult
+    }
+    if (hookResult) {
+      objectAssign(pageContextFromHook, { _hasPageContextFromClient: true })
+    }
+    objectAssign(pageContextFromHook, pageContextFromData)
+  }
+  return pageContextFromHook
+}
+
+// Workaround for the fact that the client-side cannot known whether a pageContext JSON request is needed in order to fetch pageContextInit data passed to the client.
+//  - The workaround is reliable as long as the user sets additional pageContextInit to undefined instead of not defining the property:
+//    ```diff
+//    - // Breaks the workaround:
+//    - const pageContextInit = { urlOriginal: req.url }
+//    - if (user) pageContextInit.user = user
+//    + // Makes the workaround reliable:
+//    + const pageContextInit = { urlOriginal: req.url, user }
+//    ```
+// - We can show a warning to users when the pageContextInit keys aren't always the same. (We didn't implement the waning yet because it would require a new doc page https://vike.dev/pageContextInit#avoid-conditional-properties
+// - Workaround cannot be made completely reliable because the workaround assumes that passToClient is always the same, but the user may set a different passToClient value for another page
+// - Alternatively, we could define a new config `alwaysFetchPageContextFromServer: boolean`
+function setPageContextInitIsPassedToClient(pageContext: Record<string, unknown>) {
+  if (pageContext[pageContextInitIsPassedToClient]) {
+    globalObject.pageContextInitIsPassedToClient = true
+  }
+}
+
+/**
+ * Checks if page has server-side context
+ * @internal
+ * Note: This will be made synchronous in V1 release
+ */
+async function hasPageContextServer(pageContext: Parameters<typeof hookServerOnlyExists>[1]): Promise<boolean> {
+  return (
+    !!globalObject.pageContextInitIsPassedToClient ||
+    (await hookServerOnlyExists('data', pageContext)) ||
+    (await hookServerOnlyExists('onBeforeRender', pageContext))
+  )
+}
+
+/**
+ * Checks if a hook exists with server-only environment
+ * @param hookName - Name of the hook to check ('data' | 'onBeforeRender')
+ * @param pageContext - Page context with page files and configs
+ * @returns `true` if the given page has a `hookName` hook defined with a server-only env
+ * @internal
+ * Note: This will be made synchronous in V1 release
+ */
+async function hookServerOnlyExists(
+  hookName: 'data' | 'onBeforeRender',
+  pageContext: {
+    pageId: string
+    _pageFilesAll: PageFile[]
+    _pageConfigs: PageConfigRuntime[]
+  }
+): Promise<boolean> {
+  const pageConfig = getPageConfig(pageContext.pageId, pageContext._pageConfigs)
+  const hookEnv = getConfigValueRuntime(pageConfig, `${hookName}Env`)?.value
+  if (hookEnv === null) return false
+  assert(isObject(hookEnv))
+  const { client, server } = hookEnv
+  assert(client === true || client === undefined)
+  assert(server === true || server === undefined)
+  assert(client || server)
+  return !!server && !client
+}
+
+/**
+ * @param hookName
+ * @param pageContext
+ * @returns `true` if the given page has a `hookName` hook defined with a client-only env.
+ */
+function hookClientOnlyExists(
+  hookName: 'data' | 'onBeforeRender',
+  pageContext: {
+    pageId: string
+    _pageConfigs: PageConfigRuntime[]
+  }
+): boolean {
+  const pageConfig = getPageConfig(pageContext.pageId, pageContext._pageConfigs)
+  const hookEnv = getConfigValueRuntime(pageConfig, `${hookName}Env`)?.value ?? {}
+  assert(isObject(hookEnv))
+  return !!hookEnv.client && !hookEnv.server
+}
+
+async function fetchPageContextFromServer(pageContext: { urlOriginal: string; _urlRewrite: string | null }) {
+  const pageContextUrl = getPageContextRequestUrl(pageContext._urlRewrite ?? pageContext.urlOriginal)
+  const response = await fetch(pageContextUrl)
+
+  {
+    const contentType = response.headers.get('content-type')
+    const contentTypeCorrect = 'application/json'
+    const isCorrect = contentType && contentType.includes(contentTypeCorrect)
+
+    // Static hosts + page doesn't exist
+    if (!isCorrect && response.status === 404) {
+      redirectHard(pageContext.urlOriginal)
+      return { is404ServerSideRouted: true }
+    }
+
+    assertUsage(
+      isCorrect,
+      `Wrong Content-Type for ${pageContextUrl}: it should be ${contentTypeCorrect} but it's ${contentType} instead. Make sure to properly use pageContext.httpResponse.headers, see https://vike.dev/renderPage`
+    )
+  }
+
+  const responseText = await response.text()
+  const pageContextFromServer: unknown = parse(responseText)
+  assert(isObject(pageContextFromServer))
+
+  if (isAbortPageContext(pageContextFromServer)) {
+    throw AbortRender(pageContextFromServer)
+  }
+
+  // Is there a reason for having two different properties? Can't we use only one property? I guess/think the isServerSideError property was an attempt (a bad idea really) for rendering the error page even though an error occured on the server-side (which is a bad idea because the added complexity is non-negligible while the added value is minuscule since the error page usually doesn't have any (meaningful / server-side) hooks).
+  if ('serverSideError' in pageContextFromServer || isServerSideError in pageContextFromServer) {
+    throw getProjectError(`pageContext couldn't be fetched because an error occurred on the server-side`)
+  }
+
+  assert(hasProp(pageContextFromServer, 'pageId', 'string'))
+  processPageContextFromServer(pageContextFromServer)
+
+  return { pageContextFromServer }
+}
+
+function processPageContextFromServer(pageContextFromServer: Record<string, unknown>) {
+  removeBuiltInOverrides(pageContextFromServer)
+}

package/dist/core/processing/getters/getPageContextProxyForUser.ts

@@ -0,0 +1,97 @@
+export { getPageContextProxyForUser, PageContextForPassToClientWarning }
+
+import { assert } from "../../gaurds/assertions/assert/index.js"
+import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js"
+import { assertWarning } from "../../gaurds/assertions/assertWarning/index.js"
+import { getPropAccessNotation } from "../../targets/server/utils.js"
+import { notSerializable } from "../serializers/notSerializable.js"
+import getGlobalObject from "./getGlobalObject.js"
+
+const globalObject = getGlobalObject<{ prev?: string }>(
+  "getPageContextProxyForUser.ts",
+  {}
+)
+
+type PageContextForPassToClientWarning = {
+  _hasPageContextFromServer: boolean
+  _hasPageContextFromClient: boolean
+}
+
+/**
+ * Throw error when pageContext value isn't:
+ * - serializable, or
+ * - defined.
+ */
+function getPageContextProxyForUser<
+  PageContext extends Record<string, unknown> &
+    PageContextForPassToClientWarning,
+>(pageContext: PageContext): PageContext {
+  assert([true, false].includes(pageContext._hasPageContextFromServer))
+  assert([true, false].includes(pageContext._hasPageContextFromClient))
+  return new Proxy(pageContext, {
+    get(_: never, prop: string) {
+      const val = pageContext[prop]
+      const propName = getPropAccessNotation(prop)
+      assertUsage(
+        val !== notSerializable,
+        `Can't access pageContext${propName} on the client side. Because it can't be serialized, see server logs.`
+      )
+      passToClientHint(pageContext, prop, propName)
+      return val
+    },
+  })
+}
+
+function passToClientHint(
+  pageContext: PageContextForPassToClientWarning,
+  prop: string,
+  propName: string
+) {
+  if (handleVueReactivity(prop)) return
+  // `prop in pageContext` is the trick we use to know the passToClient value on the client-side, as we set a value to all passToClient props, even `undefined` ones:
+  // ```html
+  // <script id="reveal_pageContext" type="application/json">{"pageProps":"!undefined"}</script>
+  // ```
+  if (prop in pageContext) return
+  if (isWhitelisted(prop)) return
+  // The trick described above (`prop in pageContext`) doesn't work if Reveal doesn't fetch any pageContext from the server.
+  // - There would still be some value to show a warning, but it isn't worth it because of the confusion that the first recommendation (adding `prop` to `passToClient`) wouldn't actually remove the warning, and only the second recommendation (using `prop in pageContext` instead of `pageContext[prop]`) would work.
+  if (!pageContext._hasPageContextFromServer) return
+
+  const errMsg = `pageContext${propName} isn't defined on the client-side, see https://reveal.dev/passToClient#error`
+  if (
+    // TODO/next-major-release always make it an error.
+    // - Remove pageContext._hasPageContextFromClient logic (IIRC this is its only use case).
+    pageContext._hasPageContextFromClient
+  ) {
+    assertWarning(false, errMsg, { onlyOnce: false, showStackTrace: true })
+  } else {
+    assertUsage(false, errMsg)
+  }
+}
+
+const WHITELIST = [
+  "then",
+  // Vue calls toJSON()
+  "toJSON",
+]
+function isWhitelisted(prop: string): boolean {
+  if (WHITELIST.includes(prop)) return true
+  if (typeof prop === "symbol") return true // Vue tries to access some symbols
+  if (typeof prop !== "string") return true
+  if (prop.startsWith("__v_")) return true // Vue internals upon `reactive(pageContext)`
+  return false
+}
+
+// Handle Vue's reactivity.
+// When changing a reactive object:
+// - Vue tries to read its old value first. This triggers a `assertIsDefined()` failure if e.g. `pageContextReactive.routeParams = pageContextNew.routeParams` and `pageContextReactive` has no `routeParams`.
+// - Vue seems to read __v_raw before reading the property.
+function handleVueReactivity(prop: string): boolean {
+  if (globalObject.prev === prop || globalObject.prev === "__v_raw") return true
+  globalObject.prev = prop
+  window.setTimeout(() => {
+    globalObject.prev = undefined
+  }, 0)
+  return false
+}