feat(unstable_createRoot): support unsafe_penetrate

weareoutman · weareoutman · commit 785217d88955 · 2025-04-22T16:24:18.000+08:00
diff --git a/etc/runtime.api.md b/etc/runtime.api.md
@@ -119,6 +119,7 @@ export interface CreateRootOptions {
     portal?: HTMLElement;
     scope?: "page" | "fragment";
     unknownBricks?: "silent" | "throw";
+    unsafe_penetrate?: boolean;
 }
 
 // Warning: (ae-forgotten-export) The symbol "Runtime" needs to be exported by the entry point index.d.ts
@@ -458,6 +459,8 @@ interface RuntimeContext extends LegacyCompatibleRuntimeContext {
     tplStateStoreMap: Map<string, DataStore<"STATE">>;
     // (undocumented)
     tplStateStoreScope?: DataStore<"STATE">[];
+    // (undocumented)
+    unsafe_penetrate?: boolean;
 }
 
 // @public (undocumented)
@@ -582,7 +585,7 @@ const symbolForRootRuntimeContext: unique symbol;
 function unmountUseBrick({ rendererContext }: RenderUseBrickResult, mountResult: MountUseBrickResult): void;
 
 // @public (undocumented)
-export function unstable_createRoot(container: HTMLElement | DocumentFragment, { portal: _portal, scope, unknownBricks }?: CreateRootOptions): {
+export function unstable_createRoot(container: HTMLElement | DocumentFragment, { portal: _portal, scope, unknownBricks, unsafe_penetrate, }?: CreateRootOptions): {
     render(brick: BrickConf | BrickConf[], { theme, uiVersion, language, context, functions, templates, i18n: i18nData, url, app, }?: RenderOptions): Promise<void>;
     unmount(): void;
 };
diff --git a/packages/runtime/src/createRoot.ts b/packages/runtime/src/createRoot.ts
@@ -43,6 +43,14 @@ export interface CreateRootOptions {
    * Defaults to "throw".
    */
   unknownBricks?: "silent" | "throw";
+
+  /**
+   * Set unsafe_penetrate to true to allow accessing global variables
+   * from an isolated root.
+   *
+   * It is unsafe, use it at your own risk.
+   */
+  unsafe_penetrate?: boolean;
 }
 
 export interface RenderOptions {
@@ -59,7 +67,12 @@ export interface RenderOptions {
 
 export function unstable_createRoot(
   container: HTMLElement | DocumentFragment,
-  { portal: _portal, scope = "fragment", unknownBricks }: CreateRootOptions = {}
+  {
+    portal: _portal,
+    scope = "fragment",
+    unknownBricks,
+    unsafe_penetrate,
+  }: CreateRootOptions = {}
 ) {
   let portal = _portal;
   let createPortal: RenderRoot["createPortal"];
@@ -110,6 +123,7 @@ export function unstable_createRoot(
         pendingPermissionsPreCheck: [],
         tplStateStoreMap: new Map<string, DataStore<"STATE">>(),
         formStateStoreMap: new Map<string, DataStore<"FORM_STATE">>(),
+        unsafe_penetrate,
       } as Partial<RuntimeContext> as RuntimeContext;
 
       if (url) {
diff --git a/packages/runtime/src/internal/compute/computeRealValue.spec.ts b/packages/runtime/src/internal/compute/computeRealValue.spec.ts
@@ -1,6 +1,11 @@
 import { describe, test, expect } from "@jest/globals";
 import { asyncComputeRealValue, computeRealValue } from "./computeRealValue.js";
 import type { RuntimeContext } from "../interfaces.js";
+import { _internalApiGetRuntimeContext } from "../Runtime.js";
+
+jest.mock("../Runtime.js", () => ({
+  _internalApiGetRuntimeContext: jest.fn(),
+}));
 
 const query = new URLSearchParams("q=foo");
 const runtimeContext = {
@@ -13,6 +18,10 @@ const runtimeContextWithNoData = { query } as RuntimeContext;
 const fn = () => {};
 
 describe("asyncComputeRealValue", () => {
+  beforeEach(() => {
+    (_internalApiGetRuntimeContext as jest.Mock).mockReset();
+  });
+
   test("useBrick", async () => {
     expect(
       await asyncComputeRealValue(
@@ -155,6 +164,10 @@ describe("asyncComputeRealValue", () => {
 });
 
 describe("computeRealValue", () => {
+  beforeEach(() => {
+    (_internalApiGetRuntimeContext as jest.Mock).mockReset();
+  });
+
   test("useBrick with legacy transform", () => {
     expect(
       computeRealValue(
@@ -297,4 +310,23 @@ describe("computeRealValue", () => {
       },
     });
   });
+
+  test("without unsafe penetrate", () => {
+    (_internalApiGetRuntimeContext as jest.Mock).mockReturnValue({
+      query: new URLSearchParams("q=bar"),
+    });
+    expect(computeRealValue("Q: ${QUERY.q}", runtimeContext)).toEqual("Q: foo");
+  });
+
+  test("with unsafe penetrate", () => {
+    (_internalApiGetRuntimeContext as jest.Mock).mockReturnValue({
+      query: new URLSearchParams("q=bar"),
+    });
+    expect(
+      computeRealValue("Q: ${QUERY.q}", {
+        ...runtimeContext,
+        unsafe_penetrate: true,
+      })
+    ).toEqual("Q: bar");
+  });
 });
diff --git a/packages/runtime/src/internal/compute/computeRealValue.ts b/packages/runtime/src/internal/compute/computeRealValue.ts
@@ -1,3 +1,4 @@
+import { omit, pick } from "lodash";
 import { isEvaluable } from "@next-core/cook";
 import { hasOwnProperty, isObject } from "@next-core/utils/general";
 import { transformAndInject, transform, inject } from "@next-core/inject";
@@ -14,6 +15,16 @@ import {
   isLazyContentInUseBrick,
 } from "./getNextStateOfUseBrick.js";
 import { hasBeenComputed, markAsComputed } from "./markAsComputed.js";
+import { _internalApiGetRuntimeContext } from "../Runtime.js";
+
+const penetrableCtxNames = [
+  "app",
+  "location",
+  "query",
+  "match",
+  "flags",
+  "sys",
+] as const;
 
 export interface ComputeOptions {
   $$lazyForUseBrick?: boolean;
@@ -42,16 +53,25 @@ export async function asyncComputeRealValue(
     if (preEvaluated || isEvaluable(value as string)) {
       result = await asyncEvaluate(value, runtimeContext, { lazy });
       dismissMarkingComputed = shouldDismissMarkingComputed(value);
+    } else if (lazy) {
+      result = value;
     } else {
-      result = lazy
-        ? value
-        : (hasOwnProperty(runtimeContext, "data")
-            ? internalOptions.noInject
-              ? transform
-              : transformAndInject
-            : internalOptions.noInject
+      const penetrableCtx = runtimeContext.unsafe_penetrate
+        ? ({
+            ...pick(_internalApiGetRuntimeContext(), penetrableCtxNames),
+            ...omit(runtimeContext, penetrableCtxNames),
+          } as RuntimeContext)
+        : runtimeContext;
+
+      result = (
+        hasOwnProperty(penetrableCtx, "data")
+          ? internalOptions.noInject
+            ? transform
+            : transformAndInject
+          : internalOptions.noInject
             ? identity
-            : inject)(value, runtimeContext);
+            : inject
+      )(value, penetrableCtx);
     }
 
     if (!dismissMarkingComputed) {
@@ -121,16 +141,25 @@ export function computeRealValue(
     if (preEvaluated || isEvaluable(value as string)) {
       result = evaluate(value, runtimeContext);
       dismissMarkingComputed = shouldDismissMarkingComputed(value);
+    } else if (lazy) {
+      result = value;
     } else {
-      result = lazy
-        ? value
-        : (hasOwnProperty(runtimeContext, "data")
-            ? internalOptions.noInject
-              ? transform
-              : transformAndInject
-            : internalOptions.noInject
+      const penetrableCtx = runtimeContext.unsafe_penetrate
+        ? ({
+            ...pick(_internalApiGetRuntimeContext(), penetrableCtxNames),
+            ...omit(runtimeContext, penetrableCtxNames),
+          } as RuntimeContext)
+        : runtimeContext;
+
+      result = (
+        hasOwnProperty(penetrableCtx, "data")
+          ? internalOptions.noInject
+            ? transform
+            : transformAndInject
+          : internalOptions.noInject
             ? identity
-            : inject)(value, runtimeContext);
+            : inject
+      )(value, penetrableCtx);
     }
 
     if (!dismissMarkingComputed) {
diff --git a/packages/runtime/src/internal/compute/evaluate.spec.ts b/packages/runtime/src/internal/compute/evaluate.spec.ts
@@ -254,6 +254,10 @@ formStateStore.define(
 const consoleError = jest.spyOn(console, "error");
 
 describe("evaluate", () => {
+  beforeEach(() => {
+    (_internalApiGetRuntimeContext as jest.Mock).mockReset();
+  });
+
   test.each<[string, unknown]>([
     ["<% [] %>", []],
     ["<% EVENT.detail %>", "yes"],
@@ -406,7 +410,7 @@ describe("evaluate", () => {
   });
 
   test("Access existed global CTX.DS", () => {
-    (_internalApiGetRuntimeContext as jest.Mock).mockReturnValueOnce({
+    (_internalApiGetRuntimeContext as jest.Mock).mockReturnValue({
       ctxStore: {
         has(key: string) {
           return key === "DS";
@@ -418,6 +422,26 @@ describe("evaluate", () => {
     });
     expect(evaluate("<% CTX.DS.demo %>", runtimeContext)).toBe("mocked-DS");
   });
+
+  test("unsafe penetrate", () => {
+    const unsafeContext = {
+      ...runtimeContext,
+      unsafe_penetrate: true,
+    };
+    (_internalApiGetRuntimeContext as jest.Mock).mockReturnValue({
+      app: {
+        id: "global",
+        name: "Global",
+        homepage: "/global",
+      },
+      flags: {
+        unsafe: true,
+      },
+    });
+    expect(evaluate("<% APP.id %>", unsafeContext)).toBe("global");
+    expect(evaluate("<% FLAGS.unsafe %>", unsafeContext)).toBe(true);
+    expect(evaluate("<% FLAGS.test %>", unsafeContext)).toBe(undefined);
+  });
 });
 
 describe("asyncEvaluate", () => {
diff --git a/packages/runtime/src/internal/compute/evaluate.ts b/packages/runtime/src/internal/compute/evaluate.ts
@@ -303,18 +303,13 @@ function lowLevelEvaluate(
   return {
     blockingList,
     run() {
-      const {
-        app: currentApp,
-        location,
-        query,
-        match,
-        flags,
-        sys,
-        ctxStore,
-        data,
-        event,
-      } = runtimeContext;
-      const app = runtimeContext.overrideApp ?? currentApp;
+      const { ctxStore, data, event, unsafe_penetrate } = runtimeContext;
+
+      const penetrableCtx = unsafe_penetrate
+        ? _internalApiGetRuntimeContext()!
+        : runtimeContext;
+
+      const { app, location, query, match, flags, sys } = penetrableCtx;
 
       for (const variableName of attemptToVisitGlobals) {
         switch (variableName) {
diff --git a/packages/runtime/src/internal/interfaces.ts b/packages/runtime/src/internal/interfaces.ts
@@ -35,6 +35,8 @@ export interface RuntimeContext extends LegacyCompatibleRuntimeContext {
   formStateStoreId?: string;
   formStateStoreScope?: DataStore<"FORM_STATE">[];
   inUseBrick?: boolean;
+
+  unsafe_penetrate?: boolean;
 }
 
 export type AsyncPropertyEntry = [

Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,8 @@ export interface RuntimeContext extends LegacyCompatibleRuntimeContext {`
`35`	`35`	`formStateStoreId?: string;`
`36`	`36`	`formStateStoreScope?: DataStore<"FORM_STATE">[];`
`37`	`37`	`inUseBrick?: boolean;`
	`38`	`+`
	`39`	`+ unsafe_penetrate?: boolean;`
`38`	`40`	`}`
`39`	`41`
`40`	`42`	`export type AsyncPropertyEntry = [`