@lowdefy/server-dev 5.6.0 → 6.1.0

package/{pages/_app.js → client/App.jsx}

@@ -14,14 +14,7 @@
   limitations under the License.
 */
 
-// CSS layer order — MUST be the first CSS import. Turbopack treats this as critical
-// CSS that loads before hydration, locking the cascade priority (antd > base/preflight)
-// before antd's StyleProvider injects @layer antd {} at runtime.
-import '../build/layer-order.css';
-
 import React, { Suspense, useCallback, useEffect, useRef, useState } from 'react';
-import dynamic from 'next/dynamic';
-import { useRouter } from 'next/router';
 import useSWR from 'swr';
 
 import { ErrorBoundary } from '@lowdefy/block-utils';
@@ -33,13 +26,10 @@ import { XProvider } from '@ant-design/x';
 import antdLocaleLoaders from '../build/i18n/antdLocales.js';
 import antdXLocaleLoaders from '../build/i18n/antdXLocales.js';
 import dayjsLocaleMap from '../build/i18n/dayjsLocales.js';
-import Auth from '../lib/client/auth/Auth.js';
-import ErrorBar from '../lib/client/ErrorBar.js';
+import Auth from '../lib/client/auth/Auth.jsx';
+import ErrorBar from '../lib/client/ErrorBar.jsx';
 import request from '../lib/client/utils/request.js';
-
-// Full Tailwind CSS — also loaded via <link href="tailwind-jit.css"> in _document.js
-// for hot-reloading. The Turbopack chunk provides layer ordering guarantee on initial load.
-import '../build/globals.css';
+import Routing from './Routing.jsx';
 
 function ThemeTokenResolver({ lowdefyRef, children }) {
   const { token } = antdTheme.useToken();
@@ -50,12 +40,11 @@ function ThemeTokenResolver({ lowdefyRef, children }) {
   return children;
 }
 
-function App({ Component }) {
-  const router = useRouter();
+function App({ router }) {
   const lowdefyRef = useRef({});
   const [runtimeErrors, setRuntimeErrors] = useState([]);
-  // Subscribe to rootConfig SWR cache — deduplicates with inner App.js fetch.
-  // Without suspense so _app.js doesn't suspend — just re-renders when data arrives.
+  // Subscribe to rootConfig SWR cache — deduplicates with Routing's fetch.
+  // Without suspense so App doesn't suspend — just re-renders when data arrives.
   const { data: rootConfig } = useSWR(`${router.basePath}/api/root`, (url) => request({ url }));
   if (rootConfig?.theme) {
     lowdefyRef.current.theme = rootConfig.theme;
@@ -66,7 +55,11 @@ function App({ Component }) {
     configDarkMode: lowdefyRef.current.theme?.darkMode,
   });
 
-  const { active: activeLocale, antdLocale, antdXLocale } = useLocale({
+  const {
+    active: activeLocale,
+    antdLocale,
+    antdXLocale,
+  } = useLocale({
     i18n: rootConfig?.i18n,
     antdLocaleLoaders,
     antdXLocaleLoaders,
@@ -99,12 +92,10 @@ function App({ Component }) {
     ]);
   }, []);
 
-  // Clear runtime errors on route change
+  // Clear runtime errors on navigation
   useEffect(() => {
-    const clearErrors = () => setRuntimeErrors([]);
-    router.events.on('routeChangeStart', clearErrors);
-    return () => router.events.off('routeChangeStart', clearErrors);
-  }, [router.events]);
+    return router.subscribe(() => setRuntimeErrors([]));
+  }, [router]);
 
   const handleError = useCallback((error) => {
     if (lowdefyRef.current?._internal?.handleError) {
@@ -115,10 +106,11 @@ function App({ Component }) {
   }, []);
 
   // XProvider extends antd's ConfigProvider; merging antd + antd-X locale packs
-  // gives X components their built-in strings alongside antd's.
-  const mergedLocale = antdLocale || antdXLocale
-    ? { ...(antdLocale ?? {}), ...(antdXLocale ?? {}) }
-    : undefined;
+  // gives X components (Bubble, Sender, Conversations, ...) their built-in strings
+  // alongside antd's. antd X ships only en_US + zh_CN; other locales fall back
+  // to en_US for X-native strings.
+  const mergedLocale =
+    antdLocale || antdXLocale ? { ...(antdLocale ?? {}), ...(antdXLocale ?? {}) } : undefined;
 
   return (
     <StyleProvider layer>
@@ -153,7 +145,7 @@ function App({ Component }) {
               >
                 <Auth>
                   {(auth) => {
-                    return <Component auth={auth} lowdefy={lowdefyRef.current} />;
+                    return <Routing auth={auth} lowdefy={lowdefyRef.current} router={router} />;
                   }}
                 </Auth>
               </Suspense>
@@ -166,8 +158,4 @@ function App({ Component }) {
   );
 }
 
-const DynamicApp = dynamic(() => Promise.resolve(App), {
-  ssr: false,
-});
-
-export default DynamicApp;
+export default App;

package/client/DevStreamContext.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { createContext } from 'react';
+
+// The one /api/reload EventSource a dev tab holds, owned by Reload.jsx and
+// shared with Inspector.jsx: { source, tabId }. Dev runs on HTTP/1.1, where
+// browsers cap connections per host at six and an open event stream holds
+// one for the life of the tab. Two streams per tab meant three tabs of the
+// same app saturated the pool and the next fetch queued forever, so every
+// dev-only channel rides this single stream instead of opening its own.
+//   - source: the EventSource, null until Reload's effect has opened it.
+//   - tabId: the id the server assigned this connection in its tab registry
+//     (lib/docs/tabChannel.js), null until the stream's `tab` event arrives.
+const DevStreamContext = createContext({ source: null, tabId: null });
+
+export default DevStreamContext;

package/client/Inspector.jsx

@@ -0,0 +1,226 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { useContext, useEffect, useRef } from 'react';
+
+import { type, serializer } from '@lowdefy/helpers';
+
+import DevStreamContext from './DevStreamContext.js';
+
+// Dev-only agent-state-xray channel. Listens for inspect-request/eval-request
+// events on the tab's single /api/reload EventSource (owned by Reload.jsx,
+// shared through DevStreamContext) rather than opening its own — a second
+// stream per tab exhausted the browser's HTTP/1.1 connection pool once a few
+// tabs of the same app were open, and every later fetch queued forever.
+//
+// pageId tracking: routes/reload.js registers every connection as an
+// inspectable tab (lib/docs/tabChannel.js) and announces the tab id on the
+// stream. This component then posts { tabId, pageId } to
+// /api/dev-inspect/page whenever the developer navigates, so the registry's
+// view of "what page is this tab on" stays current without reconnecting.
+//
+// Never let a bad payload or a plugin's operator error crash the app this is
+// piggybacking on — every handler is wrapped, and the component itself
+// always renders null.
+function postJson({ basePath, path, body }) {
+  try {
+    fetch(`${basePath}/api/dev-inspect${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }).catch(() => {
+      // Best-effort — a failed callback just leaves the agent's request to
+      // time out server-side, and a failed page update leaves the tab
+      // registered on its previous page.
+    });
+  } catch {
+    // JSON.stringify or fetch throwing synchronously — still best-effort.
+  }
+}
+
+function postResult({ basePath, requestId, result }) {
+  postJson({ basePath, path: '', body: { requestId, result } });
+}
+
+function postTabPage({ basePath, tabId, pageId }) {
+  postJson({ basePath, path: '/page', body: { tabId, pageId } });
+}
+
+function buildSnapshot({ lowdefy, pageId }) {
+  const context = lowdefy?.contexts?.[`page:${pageId}`];
+  if (type.isNone(context)) {
+    return { error: `No live context for page "${pageId}".` };
+  }
+  return serializer.serializeToString({
+    pageId,
+    state: context.state,
+    requests: context.requests,
+    eventLog: (context.eventLog ?? []).slice(-50),
+    global: lowdefy.lowdefyGlobal,
+    user: lowdefy.user,
+    input: lowdefy.inputs?.[`page:${pageId}`],
+    urlQuery: window.location.search,
+  });
+}
+
+// Dev-only agent-state-xray: puts a human tester's real browser tab into a
+// checkpoint's recorded state when it loads a page with `?_checkpoint=<name>`
+// in the URL. Fetches the checkpoint's state part from
+// GET <basePath>/api/dev-inspect/checkpoint/<name> (src/routes/devInspect.js
+// — that fetch also loads the checkpoint's recorded requests into
+// devMockRegistry server-side, so this tab's own requests replay recorded
+// data), then injects state the same way e2e-utils' setState does:
+// context._internal.State.set(...) + context._internal.update(). Polls
+// briefly for the page context to exist since this can run before the page
+// has finished mounting. Never lets a bad checkpoint or a missing context
+// break the app — every step is try/catch, and failures just leave the app
+// running unmodified.
+async function bootstrapFromCheckpoint({ basePath, pageId, checkpointName, isCancelled }) {
+  try {
+    const response = await fetch(
+      `${basePath}/api/dev-inspect/checkpoint/${encodeURIComponent(checkpointName)}`
+    );
+    const body = await response.json();
+    if (!response.ok || body?.error) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `Failed to load checkpoint "${checkpointName}": ${body?.error ?? response.statusText}`
+      );
+      return;
+    }
+    const payload = serializer.deserialize(body);
+
+    const deadline = Date.now() + 5000;
+    let context;
+    while (!isCancelled() && Date.now() < deadline) {
+      context = window.lowdefy?.contexts?.[`page:${pageId}`];
+      if (context) {
+        break;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (isCancelled() || type.isNone(context)) {
+      return;
+    }
+
+    Object.entries(payload.state ?? {}).forEach(([key, value]) => {
+      context._internal.State.set(key, value);
+    });
+    context._internal.update();
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error('Failed to load checkpoint "%s":', checkpointName, error);
+  }
+}
+
+function evalExpression({ lowdefy, pageId, expression }) {
+  const context = lowdefy?.contexts?.[`page:${pageId}`];
+  if (type.isNone(context)) {
+    return { error: `No live context for page "${pageId}".` };
+  }
+  // Callers may pass the operator expression as a JSON-serializable object,
+  // or (since it travels as a JSON string end-to-end from an MCP tool
+  // argument) as a JSON string that needs one more parse.
+  const input = type.isString(expression) ? JSON.parse(expression) : expression;
+  const { output, errors } = context._internal.parser.parse({ input, location: 'agent_eval' });
+  return {
+    value: serializer.serializeToString(output),
+    errors: errors.map((error) => error.message),
+  };
+}
+
+const Inspector = ({ basePath, lowdefy, pageId }) => {
+  const { source, tabId } = useContext(DevStreamContext);
+  const pageIdRef = useRef(pageId);
+  pageIdRef.current = pageId;
+
+  useEffect(() => {
+    if (type.isNone(source)) {
+      return undefined;
+    }
+
+    const onInspectRequest = (message) => {
+      let requestId;
+      try {
+        const data = JSON.parse(message.data);
+        requestId = data.requestId;
+        const targetPageId = data.pageId ?? pageIdRef.current;
+        const result = buildSnapshot({ lowdefy, pageId: targetPageId });
+        postResult({ basePath, requestId, result });
+      } catch (error) {
+        postResult({ basePath, requestId, result: { error: error.message } });
+      }
+    };
+
+    const onEvalRequest = (message) => {
+      let requestId;
+      try {
+        const data = JSON.parse(message.data);
+        requestId = data.requestId;
+        const targetPageId = data.pageId ?? pageIdRef.current;
+        const result = evalExpression({
+          lowdefy,
+          pageId: targetPageId,
+          expression: data.expression,
+        });
+        postResult({ basePath, requestId, result });
+      } catch (error) {
+        postResult({ basePath, requestId, result: { error: error.message } });
+      }
+    };
+
+    source.addEventListener('inspect-request', onInspectRequest);
+    source.addEventListener('eval-request', onEvalRequest);
+    return () => {
+      source.removeEventListener('inspect-request', onInspectRequest);
+      source.removeEventListener('eval-request', onEvalRequest);
+    };
+  }, [basePath, lowdefy, source]);
+
+  useEffect(() => {
+    if (type.isNone(tabId) || type.isNone(pageId)) {
+      return;
+    }
+    postTabPage({ basePath, tabId, pageId });
+  }, [basePath, tabId, pageId]);
+
+  useEffect(() => {
+    if (type.isNone(pageId)) {
+      return undefined;
+    }
+    const checkpointName = new URLSearchParams(window.location.search).get('_checkpoint');
+    if (type.isNone(checkpointName)) {
+      return undefined;
+    }
+
+    let cancelled = false;
+    bootstrapFromCheckpoint({
+      basePath,
+      pageId,
+      checkpointName,
+      isCancelled: () => cancelled,
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [basePath, pageId]);
+
+  return null;
+};
+
+export default Inspector;

package/{lib/client/Page.js → client/Page.jsx}

@@ -18,10 +18,9 @@ import React, { useEffect, useRef } from 'react';
 import { GenIcon } from 'react-icons/lib';
 import Client from '@lowdefy/client';
 
-import BuildErrorPage from './BuildErrorPage.js';
-import InstallingPluginsPage from './InstallingPluginsPage.js';
-import RestartingPage from './RestartingPage.js';
-import usePageConfig from './utils/usePageConfig.js';
+import BuildErrorPage from '../lib/client/BuildErrorPage.jsx';
+import InstallingPluginsPage from '../lib/client/InstallingPluginsPage.jsx';
+import usePageConfig from '../lib/client/utils/usePageConfig.js';
 
 const Page = ({
   auth,
@@ -48,7 +47,7 @@ const Page = ({
   }, [pageConfig?._warnings, lowdefy]);
 
   if (!pageConfig) {
-    router.replace(`/404`);
+    router.replace({ pathname: '/404' });
     return '';
   }
   if (pageConfig.buildError) {
@@ -63,9 +62,6 @@ const Page = ({
   if (pageConfig.installing) {
     return <InstallingPluginsPage packages={pageConfig.packages} />;
   }
-  if (resetContext.restarting) {
-    return <RestartingPage />;
-  }
 
   // Merge dynamic JS entries fetched after JIT build with the static jsMap
   const mergedJsMap = pageConfig._jsEntries ? { ...jsMap, ...pageConfig._jsEntries } : jsMap;

package/client/Reload.jsx

@@ -0,0 +1,85 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import React, { useEffect, useState } from 'react';
+
+import DevStreamContext from './DevStreamContext.js';
+import useMutateCache from '../lib/client/utils/useMutateCache.js';
+import waitForRestartedServer from '../lib/client/utils/waitForRestartedServer.js';
+
+// SSE listener — config rebuilds notify via /api/reload. Tailwind CSS updates
+// arrive through Vite HMR now (globals.css is in the dev module graph), so
+// the old tailwind-jit.css link cache-bust is gone.
+//
+// This is the tab's only EventSource. It is shared through DevStreamContext
+// so Inspector.jsx can listen on the same connection instead of opening a
+// second one — see the connection-limit note in DevStreamContext.js.
+const Reload = ({ children, basePath, lowdefy }) => {
+  const [reset, setReset] = useState(false);
+  const [restarting, setRestarting] = useState(false);
+  const [devStream, setDevStream] = useState({ source: null, tabId: null });
+  // reset is a one-shot boolean the engine lowers only after a page mounts
+  // (getContext.js) — while a page is suspended it stays true and setReset(true)
+  // bails out of re-rendering. The tick always changes, so every reload event
+  // re-invokes Routing's render prop, which re-reads reloadVersion and mints a
+  // fresh Suspense/SWR key — a suspended tab recovers instead of stranding on
+  // the building screen.
+  const [, setReloadTick] = useState(0);
+  const mutateCache = useMutateCache(basePath);
+  useEffect(() => {
+    const sse = new EventSource(`${basePath}/api/reload`);
+
+    // routes/reload.js registers every connection as an inspectable tab and
+    // announces the id it chose as the first event on the stream. The stream
+    // is published to consumers only then, in one state update, so the page
+    // subtree re-renders once at mount rather than once per field.
+    sse.addEventListener('tab', (message) => {
+      const { tabId } = JSON.parse(message.data);
+      setDevStream({ source: sse, tabId });
+    });
+
+    sse.addEventListener('reload', () => {
+      // add a update delay to prevent rerender before server is shut down for rebuild, ideally we don't want to do this.
+      // TODO: We need to pass a flag when a rebuild will happen so that client does not trigger render.
+      setTimeout(async () => {
+        await mutateCache();
+        if (lowdefy._internal?.initialised) {
+          lowdefy._internal.initialised = false;
+        }
+        setReset(true);
+        setReloadTick((tick) => tick + 1);
+        console.log('Reloaded config.');
+      }, 600);
+    });
+
+    sse.onerror = () => {
+      setRestarting(true);
+      console.log('Rebuilding Lowdefy App.');
+      sse.close();
+      waitForRestartedServer(basePath);
+    };
+    return () => {
+      sse.close();
+    };
+  }, []);
+  return (
+    <DevStreamContext.Provider value={devStream}>
+      {children({ reset, setReset, restarting })}
+    </DevStreamContext.Provider>
+  );
+};
+
+export default Reload;

package/client/Routing.jsx

@@ -0,0 +1,117 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import React, { Suspense, useEffect, useState } from 'react';
+
+import Head from '@lowdefy/client/adapters/Head.js';
+import createLinkComponent from '@lowdefy/client/adapters/Link.js';
+
+import BuildingPage from '../lib/client/BuildingPage.jsx';
+import RestartingPage from '../lib/client/RestartingPage.jsx';
+import FeedbackMount from './feedback/FeedbackMount.jsx';
+import Inspector from './Inspector.jsx';
+import OpenInEditorListener from './openInEditor/OpenInEditorListener.jsx';
+import Reload from './Reload.jsx';
+import Page from './Page.jsx';
+import setPageId from '../lib/client/setPageId.js';
+import { bumpNavVersion, getReloadVersion } from '../lib/client/utils/useMutateCache.js';
+import useRootConfig from '../lib/client/utils/useRootConfig.js';
+
+import actions from '../build/plugins/actions.js';
+import blockMetas from '../build/plugins/blockMetas.json';
+import blocks from '../build/plugins/blocks.js';
+import icons from '../build/plugins/icons.js';
+import operators from '../build/plugins/operators/client.js';
+import staticJsMap from '../build/plugins/operators/clientJsMap.js';
+
+// Replaces lib/client/App.js — page resolution driven by the custom router
+// instead of next/router, everything else preserved.
+function Routing({ auth, lowdefy, router }) {
+  const { data: rootConfig } = useRootConfig(router.basePath);
+  const [location, setLocation] = useState(() => router.getLocation());
+
+  useEffect(() => {
+    return router.subscribe((location) => {
+      // Dynamic pages re-resolve per navigation — bump before setLocation so
+      // the page config SWR key changes with the navigation. The router
+      // notifies with a fresh location object per event, so same-URL
+      // navigations already produce a state change.
+      bumpNavVersion();
+      setLocation(location);
+    });
+  }, [router]);
+
+  const [Link] = useState(() => createLinkComponent({ router }));
+
+  if (rootConfig?.theme) {
+    lowdefy.theme = rootConfig.theme;
+  }
+
+  const { redirect, pageId } = setPageId(location, rootConfig);
+  useEffect(() => {
+    if (redirect) {
+      router.replace({ pathname: `/${pageId}` });
+    }
+  }, [redirect, pageId, router]);
+  if (redirect) {
+    return '';
+  }
+
+  return (
+    <>
+      <FeedbackMount basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+      <OpenInEditorListener basePath={router.basePath} pageId={pageId} />
+      <Reload basePath={router.basePath} lowdefy={lowdefy}>
+        {(resetContext) => (
+          <>
+            {/* Inside Reload so it can share Reload's event stream (DevStreamContext). */}
+            <Inspector basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+            {/* Rendered here, not in Page — Page sits below the Suspense boundary
+                and cannot render anything while its config fetch is suspended, so
+                a restarting server would present as "Building page..." forever. */}
+            {resetContext.restarting ? (
+              <RestartingPage />
+            ) : (
+              <Suspense key={`${pageId}_${getReloadVersion()}`} fallback={<BuildingPage />}>
+                <Page
+                  auth={auth}
+                  Components={{ Head, Link }}
+                  config={{
+                    rootConfig,
+                  }}
+                  jsMap={staticJsMap}
+                  lowdefy={lowdefy}
+                  pageId={pageId}
+                  resetContext={resetContext}
+                  router={router}
+                  types={{
+                    actions,
+                    blockMetas,
+                    blocks,
+                    icons,
+                    operators,
+                  }}
+                />
+              </Suspense>
+            )}
+          </>
+        )}
+      </Reload>
+    </>
+  );
+}
+
+export default Routing;

package/client/clientBuildImports.test.mjs

@@ -0,0 +1,61 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Everything the client imports from build/ ships in the browser bundle. build/config.json is
+// server-only: it carries every deployment environment's settings (other environments' urls,
+// secret names, email filters). The client learns only the current environment's name and
+// switched-off features, through appMeta. This allowlist fails the build of any new client import
+// of a build artifact until it has been checked for what it exposes.
+const allowed = new Set([
+  'auth.json',
+  'appMeta.json',
+  'logger.json',
+  'i18n/antdLocales.js',
+  'i18n/antdXLocales.js',
+  'i18n/dayjsLocales.js',
+  'plugins/actions.js',
+  'plugins/blockMetas.json',
+  'plugins/blocks.js',
+  'plugins/icons.js',
+  'plugins/operators/client.js',
+  'plugins/operators/clientJsMap.js',
+]);
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function listSourceFiles(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) return listSourceFiles(full);
+    return /\.(js|jsx|mjs)$/.test(entry.name) && !entry.name.includes('.test.') ? [full] : [];
+  });
+}
+
+test('client code imports only client-safe build artifacts', () => {
+  const imported = ['client', 'lib/client'].flatMap((dir) =>
+    listSourceFiles(path.join(root, dir)).flatMap((file) =>
+      [...fs.readFileSync(file, 'utf8').matchAll(/from '[^']*\/build\/([^']+)'/g)].map(
+        (match) => ({ file: path.relative(root, file), artifact: match[1] })
+      )
+    )
+  );
+  expect(imported.length).toBeGreaterThan(0);
+  expect(imported.filter(({ artifact }) => !allowed.has(artifact))).toEqual([]);
+});