@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/client/auth/createFetchCheckingBuild.js

@@ -0,0 +1,45 @@
+/*
+  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 shouldReloadForBuild from '@lowdefy/client/shouldReloadForBuild.js';
+
+// fetch for the auth client and /api/user. When an auth call fails and the
+// server's x-lowdefy-build (src/middleware/stampBuildId.js) shows a newer build
+// answered, the route may have been renamed or removed since this bundle
+// loaded, so the tab reloads once onto the current build. The promise never
+// settles: the page is unloading, and a rejection would surface as an auth
+// error. A successful call from a newer build carries on; the next navigation
+// reloads the tab (client/Page.jsx). buildId is the build this bundle was made
+// from.
+function createFetchCheckingBuild({ buildId }) {
+  return async function fetchCheckingBuild(input, init) {
+    const response = await fetch(input, init);
+    if (
+      !response.ok &&
+      shouldReloadForBuild({
+        bundleBuildId: buildId,
+        serverBuildId: response.headers.get('x-lowdefy-build'),
+        window,
+      })
+    ) {
+      window.location.reload();
+      return new Promise(() => {});
+    }
+    return response;
+  };
+}
+
+export default createFetchCheckingBuild;

package/lib/client/bundleBuildId.js

@@ -0,0 +1,25 @@
+/*
+  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.
+*/
+
+// The dev server stamps no x-lowdefy-build on auth responses and refuses no call from another
+// build: a config edit reaches open tabs through /api/reload. So the auth fetch never reloads in
+// dev and needs no build id. The client does not import build/appMeta.json, which every rebuild
+// rewrites with a new id, so Vite would hot-update the auth client on every config edit. The auth
+// templates in lib/client/auth are byte-identical with the production server's, so each server
+// supplies the build id from outside them.
+const bundleBuildId = null;
+
+export default bundleBuildId;

package/lib/client/collectVisibleBlockIds.js

@@ -0,0 +1,51 @@
+/*
+  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.
+*/
+
+// The ids of the blocks a person could see right now. A block counts when its
+// wrapper (`#bl-<blockId>`) is shown and the block's own markup inside it has
+// a size. A Modal or Drawer renders nothing there but an empty anchor: its
+// content sits in a portal, in its slot wrappers (`#ar-<blockId>-<slot>`),
+// which antd hides with display: none once closed, so a shown wrapper with
+// nothing sized inside counts while one of its own slot wrappers is shown. Run in the page, by the journey observer on every DOM change
+// and by the runner's page.evaluate at each settle, so it reads nothing from
+// its closure.
+function collectVisibleBlockIds() {
+  function isShown(element) {
+    return element.checkVisibility({ opacityProperty: true, visibilityProperty: true });
+  }
+  function hasSize(element) {
+    const { width, height } = element.getBoundingClientRect();
+    return width > 0 && height > 0;
+  }
+  const ids = [];
+  document.querySelectorAll('[id^="bl-"]').forEach((wrapper) => {
+    if (!isShown(wrapper)) {
+      return;
+    }
+    const blockId = wrapper.id.slice(3);
+    if ([...wrapper.children].some(hasSize)) {
+      ids.push(blockId);
+      return;
+    }
+    const areas = document.querySelectorAll(`[id^="ar-${CSS.escape(blockId)}-"]`);
+    if ([...areas].some((area) => isShown(area) && hasSize(area))) {
+      ids.push(blockId);
+    }
+  });
+  return ids;
+}
+
+export default collectVisibleBlockIds;

package/lib/client/getCspNonce.js

@@ -0,0 +1,25 @@
+/*
+  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.
+*/
+
+// The page's Content-Security-Policy nonce, from the csp-nonce meta tag the server
+// writes when config.security.contentSecurityPolicy is on (Vite reads the same tag).
+// Browsers hide nonce attributes from getAttribute, so it is read from the property.
+// An empty string when the policy is off.
+function getCspNonce() {
+  return document.querySelector('meta[property="csp-nonce"]')?.nonce ?? '';
+}
+
+export default getCspNonce;

package/lib/client/getPagePath.js

@@ -0,0 +1,36 @@
+/*
+  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 { buildPagePath } from '@lowdefy/helpers';
+
+// The path to fetch for a router location ({ path, pathname, search }, path ''
+// at the app root). The app root shows the home page, at its own path: a
+// configured homePageId is served at the root, and an app without one
+// redirects there.
+function getPagePath(location, rootConfig) {
+  if (location.path !== '') {
+    return { redirect: false, path: location.path };
+  }
+  const { home, pagePaths } = rootConfig;
+  const path = buildPagePath({
+    pageId: home.pageId,
+    path: pagePaths[home.pageId],
+    pathParams: home.pathParams,
+  });
+  return { redirect: home.configured === false, path };
+}
+
+export default getPagePath;

package/lib/client/getPagePath.test.mjs

@@ -0,0 +1,51 @@
+/*
+  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 getPagePath from './getPagePath.js';
+
+const rootConfig = {
+  home: { configured: true, pageId: 'users', pathParams: {} },
+  pagePaths: { users: 'admin/users' },
+};
+
+test('getPagePath fetches a non-root path as it is', () => {
+  expect(getPagePath({ path: 'tickets/a%2Bb/1' }, rootConfig)).toEqual({
+    redirect: false,
+    path: 'tickets/a%2Bb/1',
+  });
+});
+
+test('getPagePath fetches the configured home page at its own path from the root', () => {
+  expect(getPagePath({ path: '' }, rootConfig)).toEqual({ redirect: false, path: 'admin/users' });
+});
+
+test('getPagePath redirects the root to the first menu link, built with its path values', () => {
+  expect(
+    getPagePath(
+      { path: '' },
+      {
+        home: { configured: false, pageId: 'ticket', pathParams: { space: 'support', id: '1' } },
+        pagePaths: { ticket: 'tickets/{space}/{id}' },
+      }
+    )
+  ).toEqual({ redirect: true, path: 'tickets/support/1' });
+});
+
+test('getPagePath reads a home page without a path at its id', () => {
+  expect(
+    getPagePath({ path: '' }, { home: { configured: false, pageId: 'home' }, pagePaths: {} })
+  ).toEqual({ redirect: true, path: 'home' });
+});

package/lib/client/utils/formatErrorsForCopy.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.
+*/
+
+function formatErrorsForCopy(errors) {
+  return errors
+    .map((error) => {
+      const prefix =
+        error.prodError === true ? `[${error.type}] (fails in prod)` : `[${error.type}]`;
+      let text = `${prefix} ${error.message}`;
+      if (error.source) text += `\n  Source: ${error.source}`;
+      if (error.stack) text += `\n${error.stack}`;
+      return text;
+    })
+    .join('\n\n');
+}
+
+export default formatErrorsForCopy;

package/lib/client/utils/formatErrorsForCopy.test.mjs

@@ -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.
+*/
+import formatErrorsForCopy from './formatErrorsForCopy.js';
+
+test('formatErrorsForCopy marks a prod-gated warning after the type prefix', () => {
+  expect(
+    formatErrorsForCopy([
+      { type: 'ConfigWarning', message: '_state is not available.', prodError: true },
+    ])
+  ).toBe('[ConfigWarning] (fails in prod) _state is not available.');
+});
+
+test('formatErrorsForCopy leaves a plain warning prefix unmarked', () => {
+  expect(formatErrorsForCopy([{ type: 'ConfigWarning', message: 'Duplicate shortcut.' }])).toBe(
+    '[ConfigWarning] Duplicate shortcut.'
+  );
+});
+
+test('formatErrorsForCopy appends source and stack and joins entries with a blank line', () => {
+  expect(
+    formatErrorsForCopy([
+      { type: 'ConfigError', message: 'Bad type.', source: 'home.yaml:3' },
+      { type: 'BlockError', message: 'Render failed.', stack: 'at Block' },
+    ])
+  ).toBe('[ConfigError] Bad type.\n  Source: home.yaml:3\n\n[BlockError] Render failed.\nat Block');
+});

package/lib/client/utils/getErrorBarColor.js

@@ -0,0 +1,25 @@
+/*
+  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.
+*/
+
+// Three severities: a real error is red, a warning that fails the production
+// build is dark orange, and a plain warning is yellow.
+function getErrorBarColor(errors) {
+  if (errors.some((error) => error.type !== 'ConfigWarning')) return '#cf1322';
+  if (errors.some((error) => error.prodError === true)) return '#ad4e00';
+  return '#d48806';
+}
+
+export default getErrorBarColor;

package/lib/client/utils/getErrorBarColor.test.mjs

@@ -0,0 +1,34 @@
+/*
+  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 getErrorBarColor from './getErrorBarColor.js';
+
+test('getErrorBarColor returns red when any entry is not a warning', () => {
+  expect(
+    getErrorBarColor([{ type: 'ConfigWarning', prodError: true }, { type: 'ConfigError' }])
+  ).toBe('#cf1322');
+});
+
+test('getErrorBarColor returns dark orange when every entry is a warning and one fails in prod', () => {
+  expect(
+    getErrorBarColor([{ type: 'ConfigWarning' }, { type: 'ConfigWarning', prodError: true }])
+  ).toBe('#ad4e00');
+});
+
+test('getErrorBarColor returns yellow when every entry is a plain warning', () => {
+  expect(
+    getErrorBarColor([{ type: 'ConfigWarning' }, { type: 'ConfigWarning', prodError: false }])
+  ).toBe('#d48806');
+});

package/lib/client/utils/request.js

@@ -14,6 +14,8 @@
   limitations under the License.
 */
 
+import { serializer } from '@lowdefy/helpers';
+
 async function request({ url, method = 'GET', body }) {
   const res = await fetch(url, {
     method,
@@ -27,7 +29,12 @@ async function request({ url, method = 'GET', body }) {
   }
   if (!res.ok) {
     const body = await res.json();
-    throw new Error(body?.['~e']?.message ?? body?.message ?? 'Request error');
+    // A Lowdefy error envelope is revived rather than flattened to its message,
+    // so the class, configKey and source survive to the error handler.
+    if (body?.['~e']) {
+      throw serializer.deserialize(body);
+    }
+    throw new Error(body?.message ?? 'Request error');
   }
   return res.json();
 }

package/lib/client/utils/usePageConfig.js

@@ -13,12 +13,16 @@
 
 import useSWR from 'swr';
 
+import { serializer, type } from '@lowdefy/helpers';
+import recordCallerStamp from '@lowdefy/client/recordCallerStamp.js';
+import shouldReloadForCaller from '@lowdefy/client/shouldReloadForCaller.js';
+
 import { getNavVersion, getReloadVersion } from './useMutateCache.js';
 
-// URLs whose config is server-resolved per request — learned from the fetched
-// config's dynamic flag, so the first visit caches like a static page and
-// every later navigation refetches.
-const dynamicUrls = new Set();
+// Page config URLs (without the query string) of pages whose config is
+// server-resolved per request, mapped to the navigation version of the fetch
+// that found them dynamic. Learned from the fetched config's dynamic flag.
+const dynamicPages = new Map();
 
 function parseJsModule(text) {
   const fn = new Function('exports', text.replace('export default', 'exports.default ='));
@@ -27,7 +31,11 @@ function parseJsModule(text) {
   return mod.default ?? {};
 }
 
-export async function fetchPageConfig(url) {
+// user is the caller the page renders: a page config the server answered as
+// another caller, or with other roles, reloads the tab (shouldReloadForCaller).
+// Otherwise its caller stamp is kept on lowdefy (recordCallerStamp).
+export async function fetchPageConfig(url, { lowdefy, user }) {
+  const basePath = url.replace(/\/api\/page\/.*$/, '');
   // A stalled request (server restart mid-request, exhausted sockets) must
   // become a visible error, never an eternal Suspense fallback — the reload
   // recovery path cannot fire while the page tree is suspended.
@@ -48,6 +56,20 @@ export async function fetchPageConfig(url) {
   if (res.status === 404) {
     return null;
   }
+  if (res.status === 401 || res.status === 403) {
+    // 401: logged-out navigation to a protected page. 403: authorised but second
+    // factor not yet enrolled. Page renders a redirect screen and full-loads to
+    // the destination so it can return here afterwards. Returning a settled value
+    // (never a parked promise) keeps the SWR key healthy: if the navigation is
+    // dropped, the tab still recovers on the next reload event or via the manual
+    // link on the redirect screen.
+    const { redirect } = await res.json();
+    const authRedirect = redirect ?? `${basePath}/404`;
+    console.warn(
+      `Lowdefy dev: "${url}" returned ${res.status} - redirecting to "${authRedirect}".`
+    );
+    return { authRedirect };
+  }
   const data = await res.json();
   if (data?.buildError) {
     return data;
@@ -56,36 +78,78 @@ export async function fetchPageConfig(url) {
     return data;
   }
   if (!res.ok) {
+    // A Lowdefy error envelope is revived rather than flattened to its message,
+    // so the class, configKey and source survive to the error handler.
+    if (data?.['~e']) {
+      throw serializer.deserialize(data);
+    }
     throw new Error(data.message || 'Request error');
   }
+  const serverCaller = res.headers.get('x-lowdefy-caller');
+  if (shouldReloadForCaller({ serverCaller, user, window })) {
+    // The page unloads; settling would render the other caller's config.
+    window.location.reload();
+    return new Promise(() => {});
+  }
+  recordCallerStamp({ lowdefy, serverCaller });
 
-  // The JIT build folds this page's _js entries and dynamic icons into the
-  // response, so first paint needs no secondary fetch. _jsEntries arrives as
-  // module text — compile it to the { hash: fn } object Page expects.
+  // A page response is { pageId, pathParams, matchedPath, pageConfig }: the page
+  // the server matched the path to, the values it carries and the path it was
+  // matched on. The JIT build folds this page's _js entries and dynamic icons
+  // into pageConfig, so first paint needs no secondary fetch. _jsEntries arrives
+  // as module text — compile it to the { hash: fn } object Page expects.
   // _dynamicIcons is already plain data — leave it for Page to inject.
-  if (data._jsEntries) data._jsEntries = parseJsModule(data._jsEntries);
+  const { pageConfig } = data;
+  if (pageConfig._jsEntries) pageConfig._jsEntries = parseJsModule(pageConfig._jsEntries);
 
-  if (data?.dynamic === true) {
-    dynamicUrls.add(url);
+  return data;
+}
+
+export function recordDynamicPage({ data, pageUrl }) {
+  if (data?.pageConfig?.dynamic !== true) {
+    dynamicPages.delete(pageUrl);
+    return;
+  }
+  // Keep the first navigation version: later fetches of a known dynamic page
+  // must not move it, or their key would fall back to the static key.
+  if (!dynamicPages.has(pageUrl)) {
+    dynamicPages.set(pageUrl, getNavVersion());
   }
+}
 
-  return data;
+// The query string only changes the config of a dynamic page (server-side
+// Dynamic block resolution reads urlQuery), so a static page keys on its URL
+// alone and a Link that only changes the query reuses the cached config instead
+// of suspending behind the Building page fallback. A dynamic page keys on the
+// query and the navigation version, so it re-resolves on every navigation.
+// reloadVersion orphans every cached entry after a config reload. The fetch
+// that first finds a page dynamic was made under the static key, so for the
+// rest of that navigation the page keeps the static key and uses that result
+// rather than fetching it again.
+export function getPageConfigKey({ pageUrl, search }) {
+  const foundAtNavVersion = dynamicPages.get(pageUrl);
+  const navVersion = getNavVersion();
+  if (type.isUndefined(foundAtNavVersion) || foundAtNavVersion === navVersion) {
+    return [pageUrl, getReloadVersion()];
+  }
+  return [pageUrl, getReloadVersion(), search, navVersion];
 }
 
-function usePageConfig(pageId, basePath) {
-  // Forward the current query string so server-side Dynamic block resolution
-  // sees the same urlQuery as an initial HTML load. Including it in the SWR
-  // key also caches dynamic pages per query string.
-  const url = `${basePath}/api/page/${pageId}${window.location.search}`;
-  // Include reloadVersion in the SWR key so that after a config reload,
-  // previously cached page data is not reused. Dynamic pages also key on the
-  // navigation version — server-resolved content must re-resolve on every
-  // navigation, never serve from the SWR cache. The fetcher receives
-  // [url, ...versions] but only uses url — the versions just bust the cache.
-  const navVersion = dynamicUrls.has(url) ? getNavVersion() : 0;
+// path is the page's URL path without basePath and the leading "/", still
+// encoded; the server matches it to a page.
+// user is the caller the page renders; lowdefy keeps the last caller stamp.
+function usePageConfig(path, basePath, user, lowdefy) {
+  const pageUrl = `${basePath}/api/page/${path}`;
+  const search = window.location.search;
+  // The fetch always forwards the current query string, so server-side Dynamic
+  // block resolution sees the same urlQuery as an initial HTML load.
   const { data } = useSWR(
-    [url, getReloadVersion(), navVersion],
-    ([fetchUrl]) => fetchPageConfig(fetchUrl),
+    getPageConfigKey({ pageUrl, search }),
+    async () => {
+      const data = await fetchPageConfig(`${pageUrl}${search}`, { lowdefy, user });
+      recordDynamicPage({ data, pageUrl });
+      return data;
+    },
     {
       suspense: true,
     }