@lowdefy/server-e2e 5.6.0 → 6.0.0

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

@@ -14,24 +14,20 @@
   limitations under the License.
 */
 
-// CSS layer order — MUST be the first CSS import. Next.js 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, { useCallback, useRef } from 'react';
-import dynamic from 'next/dynamic';
 
 import { ErrorBoundary } from '@lowdefy/block-utils';
-import { useDarkMode } from '@lowdefy/client';
+import { useDarkMode, useLocale } from '@lowdefy/client';
 import { StyleProvider } from '@ant-design/cssinjs';
-import { App as AntdApp, ConfigProvider, theme as antdTheme } from 'antd';
+import { App as AntdApp, theme as antdTheme } from 'antd';
+import { XProvider } from '@ant-design/x';
 
-import Auth from '../lib/client/auth/Auth.js';
+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.jsx';
 import createLogUsage from '../lib/client/createLogUsage.js';
-
-// Must be in _app due to next specifications.
-import '../build/globals.css';
+import Page from './Page.jsx';
 
 function ThemeTokenResolver({ lowdefyRef, children }) {
   const { token } = antdTheme.useToken();
@@ -42,7 +38,9 @@ function ThemeTokenResolver({ lowdefyRef, children }) {
   return children;
 }
 
-function App({ Component, pageProps: { session, rootConfig, pageConfig } }) {
+function App({ config }) {
+  const { rootConfig, session } = config;
+
   const usageDataRef = useRef({});
   const lowdefyRef = useRef({ eventCallback: createLogUsage({ usageDataRef }) });
   if (rootConfig?.theme) {
@@ -54,6 +52,21 @@ function App({ Component, pageProps: { session, rootConfig, pageConfig } }) {
     configDarkMode: lowdefyRef.current.theme?.darkMode,
   });
 
+  const {
+    active: activeLocale,
+    antdLocale,
+    antdXLocale,
+  } = useLocale({
+    i18n: rootConfig?.i18n,
+    antdLocaleLoaders,
+    antdXLocaleLoaders,
+    dayjsLocaleMap,
+  });
+
+  if (rootConfig?.i18n?.defaultLocale) {
+    lowdefyRef.current.i18n = { ...rootConfig.i18n, active: activeLocale };
+  }
+
   const {
     lightToken: _lightToken,
     darkToken: _darkToken,
@@ -70,9 +83,22 @@ function App({ Component, pageProps: { session, rootConfig, pageConfig } }) {
     }
   }, []);
 
+  // XProvider extends antd's ConfigProvider; merging antd + antd-X locale packs
+  // 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>
-      <ConfigProvider
+      <XProvider
+        locale={mergedLocale}
+        form={
+          antdLocale?.Form?.defaultValidateMessages
+            ? { validateMessages: antdLocale.Form.defaultValidateMessages }
+            : undefined
+        }
         theme={{
           ...antdConfig,
           token,
@@ -88,26 +114,15 @@ function App({ Component, pageProps: { session, rootConfig, pageConfig } }) {
               <Auth session={session}>
                 {(auth) => {
                   usageDataRef.current.user = auth.session?.hashed_id;
-                  return (
-                    <Component
-                      auth={auth}
-                      lowdefy={lowdefyRef.current}
-                      rootConfig={rootConfig}
-                      pageConfig={pageConfig}
-                    />
-                  );
+                  return <Page auth={auth} config={config} lowdefy={lowdefyRef.current} />;
                 }}
               </Auth>
             </ErrorBoundary>
           </ThemeTokenResolver>
         </AntdApp>
-      </ConfigProvider>
+      </XProvider>
     </StyleProvider>
   );
 }
 
-const DynamicApp = dynamic(() => Promise.resolve(App), {
-  ssr: false,
-});
-
-export default DynamicApp;
+export default App;

package/client/Page.jsx

@@ -0,0 +1,110 @@
+/*
+  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, useRef, useState } from 'react';
+
+import Client from '@lowdefy/client';
+import createRouter from '@lowdefy/client/adapters/createRouter.js';
+import createLinkComponent from '@lowdefy/client/adapters/Link.js';
+import { createUrl } from '@lowdefy/client/adapters/url.js';
+import Head from '@lowdefy/client/adapters/Head.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 jsMap from '../build/plugins/operators/clientJsMap.js';
+
+// Replaces lib/client/Page.js. The first page renders from the config
+// embedded in the HTML; SPA navigations fetch /api/page/* and swap pageConfig.
+function Page({ auth, config, lowdefy }) {
+  const [pageConfig, setPageConfig] = useState(config.pageConfig);
+
+  const routerRef = useRef(null);
+  if (!routerRef.current) {
+    const router = createRouter({ basePath: config.basePath ?? '', window });
+    routerRef.current = {
+      router,
+      Link: createLinkComponent({ router }),
+    };
+  }
+  const { router, Link } = routerRef.current;
+
+  // Temporary sequence guard for the superseded-navigation race: a slow
+  // response for an abandoned navigation must not paint over a newer one.
+  // Remove when the loader-based lifecycle replaces these fetch paths.
+  const latestNavRef = useRef(0);
+
+  useEffect(() => {
+    const unsubscribe = router.subscribe(async ({ pageId }) => {
+      const token = ++latestNavRef.current;
+      const targetPageId = pageId ?? config.rootConfig.home.pageId;
+      try {
+        // Forward the current query string so server-side Dynamic block
+        // resolution sees the same urlQuery as an initial HTML load.
+        const res = await fetch(
+          `${router.basePath}/api/page/${targetPageId}${window.location.search}`
+        );
+        if (!res.ok) {
+          if (token !== latestNavRef.current) return;
+          if (targetPageId !== '404') {
+            router.replace({ pathname: '/404' });
+          }
+          return;
+        }
+        const { pageConfig: nextPageConfig } = await res.json();
+        if (token !== latestNavRef.current) return;
+        setPageConfig(nextPageConfig);
+      } catch (error) {
+        // Network failure on SPA navigation — fall back to a full page load.
+        if (token !== latestNavRef.current) return;
+        window.location.assign(
+          createUrl({
+            basePath: router.basePath,
+            pathname: targetPageId === config.rootConfig.home.pageId ? '/' : `/${targetPageId}`,
+          })
+        );
+      }
+    });
+    return unsubscribe;
+  }, []);
+
+  return (
+    <Client
+      auth={auth}
+      Components={{ Head, Link }}
+      config={{
+        pageConfig,
+        rootConfig: config.rootConfig,
+      }}
+      jsMap={jsMap}
+      lowdefy={lowdefy}
+      router={router}
+      stage="e2e"
+      types={{
+        actions,
+        blockMetas,
+        blocks,
+        icons,
+        operators,
+      }}
+      window={window}
+    />
+  );
+}
+
+export default Page;

package/client/main.jsx

@@ -0,0 +1,39 @@
+/*
+  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.
+*/
+
+// CSS layer order — MUST be the first CSS import. This locks the cascade
+// priority (antd > base/preflight) before antd's StyleProvider injects
+// @layer antd {} at runtime.
+import '../build/layer-order.css';
+
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+import App from './App.jsx';
+
+import '../build/globals.css';
+
+const config = JSON.parse(document.getElementById('__LOWDEFY_CONFIG__').textContent);
+const container = document.getElementById('root');
+
+// Keep one React root across Vite HMR updates — re-running createRoot on a
+// container that already has a root is an error.
+const root = import.meta.hot?.data.root ?? createRoot(container);
+if (import.meta.hot) {
+  import.meta.hot.data.root = root;
+}
+
+root.render(<App config={config} />);

package/lib/build/app.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/app.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/app.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/appMeta.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/appMeta.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/appMeta.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/auth.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/auth.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/auth.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/config.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/config.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/config.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/i18n.js

@@ -0,0 +1,26 @@
+/*
+  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.
+*/
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { serializer } from '@lowdefy/helpers';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/i18n.json'), 'utf8'));
+
+export default serializer.deserialize(raw);

package/lib/build/logger.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/logger.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/logger.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/theme.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/theme.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/theme.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/client/auth/{Auth.js → Auth.jsx}

@@ -14,7 +14,11 @@
   limitations under the License.
 */
 
-import authConfig from '../../build/auth.js';
+import { serializer } from '@lowdefy/helpers';
+
+import rawAuthConfig from '../../../build/auth.json';
+
+const authConfig = serializer.deserialize(rawAuthConfig);
 
 function e2eNotSupported() {
   throw new Error('Sign-in and sign-out are not supported in e2e testing.');

package/lib/server/auth/{getServerSession.js → session.js}

@@ -14,8 +14,10 @@
   limitations under the License.
 */
 
-function getServerSession({ req }) {
-  const cookieHeader = req?.headers?.cookie ?? '';
+// E2E test-user injection: the session is read from the lowdefy_e2e_user
+// cookie (base64-encoded JSON user object) instead of a real auth engine.
+function getSession(c) {
+  const cookieHeader = c.req.header('cookie') ?? '';
   const match = cookieHeader.match(/lowdefy_e2e_user=([^;]+)/);
   if (!match) {
     return undefined;
@@ -30,4 +32,4 @@ function getServerSession({ req }) {
   }
 }
 
-export default getServerSession;
+export default getSession;

package/lib/server/log/createHandleError.test.mjs

@@ -0,0 +1,126 @@
+/*
+  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 { jest } from '@jest/globals';
+import { ConfigError, LowdefyInternalError } from '@lowdefy/errors';
+
+import createHandleError from './createHandleError.js';
+
+// This sink is the sole writer of `error.handled`. Two callers read the flag and
+// neither can set it for itself: runRoutine's catch guards on `!error.handled` to
+// avoid logging a nested error twice, and the browser's handleError skips the
+// round-trip to /api/client-error when it is set. runRoutine deliberately gave up
+// its own assignment on the strength of this function, so the tests below pin the
+// assignment and — more importantly — its position ahead of everything that can
+// throw.
+
+const keyMap = { key_1: { key: 'root.pages[0:home]', '~r': 'ref_1', '~l': 5 } };
+const refMap = { ref_1: { path: 'pages/home.yaml' } };
+
+function testContext({ logger, readConfigFile, configDirectory } = {}) {
+  return {
+    configDirectory,
+    logger: logger ?? { error: jest.fn() },
+    readConfigFile:
+      readConfigFile ??
+      jest.fn(async (path) => {
+        if (path === 'keyMap.json') return keyMap;
+        if (path === 'refMap.json') return refMap;
+        return null;
+      }),
+  };
+}
+
+beforeEach(() => {
+  console.error = jest.fn();
+});
+
+test('handleError marks the error handled and resolves its location', async () => {
+  const context = testContext();
+  const handleError = createHandleError({ context });
+  const error = new ConfigError('Bad config.', { configKey: 'key_1' });
+
+  await handleError(error);
+
+  expect(error.handled).toBe(true);
+  expect(error.source).toBe('pages/home.yaml:5');
+  expect(error.config).toBe('root.pages[0:home]');
+  expect(context.logger.error).toHaveBeenCalledWith(error);
+});
+
+test('handleError marks a LowdefyInternalError handled even though it never gets a source', async () => {
+  // The Decision 7 case. Location resolution is deliberately skipped for an
+  // internal error, so `source` stays undefined - which is why the client's
+  // already-logged gate reads `handled` and not `source`. Keyed on source, this
+  // error was POSTed back to /api/client-error and logged a second time.
+  const context = testContext();
+  const handleError = createHandleError({ context });
+  const error = new LowdefyInternalError('Unexpected condition.');
+
+  await handleError(error);
+
+  expect(error.handled).toBe(true);
+  expect(error.source).toBeUndefined();
+  expect(context.readConfigFile).not.toHaveBeenCalled();
+  expect(context.logger.error).toHaveBeenCalledWith(error);
+});
+
+test('handleError marks the error handled before it logs, so a throwing logger cannot skip the flag', async () => {
+  const logger = {
+    error: jest.fn(() => {
+      throw new Error('Log drain unreachable.');
+    }),
+  };
+  const context = testContext({ logger });
+  const handleError = createHandleError({ context });
+  const error = new ConfigError('Bad config.', { configKey: 'key_1' });
+
+  await handleError(error);
+
+  // The sink swallows its own failure - reaching it is what makes the error
+  // already-logged, so the flag must survive the log call failing. Were it set
+  // after the log, this error would cross the wire unflagged and be logged a
+  // second time from the browser.
+  expect(error.handled).toBe(true);
+  expect(logger.error).toHaveBeenCalled();
+  expect(console.error).toHaveBeenCalled();
+});
+
+test('handleError marks the error handled when location resolution rejects', async () => {
+  const readConfigFile = jest.fn(async () => {
+    throw new Error('keyMap.json unreadable.');
+  });
+  const context = testContext({ readConfigFile });
+  const handleError = createHandleError({ context });
+  const error = new ConfigError('Bad config.', { configKey: 'key_1' });
+
+  await handleError(error);
+
+  expect(error.handled).toBe(true);
+  // ConfigError's constructor initialises source to null; resolution failing
+  // leaves it there rather than assigning.
+  expect(error.source).toBeNull();
+});
+
+test('handleError marks a plain Error handled', async () => {
+  const context = testContext();
+  const handleError = createHandleError({ context });
+  const error = new Error('Something broke.');
+
+  await handleError(error);
+
+  expect(error.handled).toBe(true);
+});

package/lowdefy/createCustomPluginTypesMap.mjs

@@ -55,6 +55,7 @@ async function createCustomPluginTypesMap({ directories }) {
       server: {},
     },
     requests: {},
+    websockets: {},
   };
 
   const pluginDefinitions = await getPluginDefinitions({ directories });

package/lowdefy/createCustomPluginTypesMap.test.mjs

@@ -50,6 +50,8 @@ jest.unstable_mockModule('@lowdefy/node-utils', () => ({
   spawnProcess: jest.fn(),
   readFile: jest.fn(async () => pluginYaml),
   writeFile: jest.fn(),
+  writeFileIfChanged: jest.fn(),
+  installIfPackageJsonChanged: jest.fn(),
 }));
 
 jest.unstable_mockModule('node:module', () => ({