@lowdefy/server-dev 5.6.0 → 6.0.0

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

@@ -13,12 +13,30 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
 /* eslint-disable react/jsx-props-no-spreading */
 
 import React, { useEffect, useRef } from 'react';
-import { getSession, SessionProvider, signIn, signOut, useSession } from 'next-auth/react';
+import {
+  authConfigManager,
+  getSession,
+  SessionProvider,
+  signIn,
+  signOut,
+  useSession,
+} from '@hono/auth-js/react';
+
+import { serializer } from '@lowdefy/helpers';
+
+import rawLowdefyConfig from '../../../build/config.json';
 
-import lowdefyConfig from '../../build/config.js';
+const lowdefyConfig = serializer.deserialize(rawLowdefyConfig);
+
+// @hono/auth-js/react configures its fetch paths through a module-level
+// manager instead of SessionProvider props.
+if (lowdefyConfig.basePath) {
+  authConfigManager.setConfig({ basePath: `${lowdefyConfig.basePath}/api/auth` });
+}
 
 function Session({ children }) {
   const wasAuthenticated = useRef(false);
@@ -31,9 +49,8 @@ function Session({ children }) {
     }
   }, [status]);
 
-  // If session is passed to SessionProvider from getServerSideProps
-  // we won't have a loading state here.
-  // But 404 uses getStaticProps so we have this for 404.
+  // If session is passed to SessionProvider from the server-rendered config
+  // we won't have a loading state here, but unauthenticated first loads do.
   if (status === 'loading') {
     return '';
   }
@@ -42,12 +59,8 @@ function Session({ children }) {
 
 function AuthConfigured({ authConfig, children, serverSession }) {
   const auth = { authConfig, getSession, signIn, signOut };
-  let basePath = lowdefyConfig.basePath;
-  if (basePath) {
-    basePath = `${basePath}/api/auth`;
-  }
   return (
-    <SessionProvider session={serverSession} basePath={basePath}>
+    <SessionProvider session={serverSession}>
       <Session>
         {(session) => {
           auth.session = session;

package/lib/client/setPageId.js

@@ -14,18 +14,19 @@
   limitations under the License.
 */
 
-function setPageId(router, rootConfig) {
-  if (router.pathname === `/404`) {
+// location comes from the custom router (@lowdefy/client/adapters):
+// { pageId, pathname, search }. pageId is null at the root path.
+function setPageId(location, rootConfig) {
+  if (location.pageId === '404') {
     return { redirect: false, pageId: '404' };
   }
-  const segments = router.query.pageId;
-  if (!segments || segments.length === 0) {
+  if (!location.pageId) {
     if (rootConfig.home.configured === false) {
       return { redirect: true, pageId: rootConfig.home.pageId };
     }
     return { redirect: false, pageId: rootConfig.home.pageId };
   }
-  return { redirect: false, pageId: segments.join('/') };
+  return { redirect: false, pageId: location.pageId };
 }
 
 export default setPageId;

package/lib/client/utils/useMutateCache.js

@@ -16,12 +16,25 @@
 
 import { useSWRConfig } from 'swr';
 
+// Module-level counters that bust usePageConfig SWR keys: reloadVersion moves
+// on config reloads (all pages), navVersion on client-side navigations
+// (dynamic pages only — server-resolved content must re-resolve per
+// navigation, never serve from the SWR cache).
 let reloadVersion = 0;
+let navVersion = 0;
 
 function getReloadVersion() {
   return reloadVersion;
 }
 
+function bumpNavVersion() {
+  navVersion += 1;
+}
+
+function getNavVersion() {
+  return navVersion;
+}
+
 function useMutateCache(basePath) {
   const { mutate } = useSWRConfig();
   return () => {
@@ -34,5 +47,5 @@ function useMutateCache(basePath) {
   };
 }
 
-export { getReloadVersion };
+export { bumpNavVersion, getNavVersion, getReloadVersion };
 export default useMutateCache;

package/lib/client/utils/usePageConfig.js

@@ -13,7 +13,12 @@
 
 import useSWR from 'swr';
 
-import { getReloadVersion } from './useMutateCache.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();
 
 function parseJsModule(text) {
   const fn = new Function('exports', text.replace('export default', 'exports.default ='));
@@ -22,30 +27,24 @@ function parseJsModule(text) {
   return mod.default ?? {};
 }
 
-async function fetchJsEntries(basePath) {
+export async function fetchPageConfig(url) {
+  // 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.
+  let res;
   try {
-    const res = await fetch(`${basePath}/api/js/client`);
-    if (!res.ok) return {};
-    return parseJsModule(await res.text());
-  } catch {
-    return {};
+    res = await fetch(url, {
+      headers: { 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch (error) {
+    if (error.name === 'TimeoutError' || error.name === 'AbortError') {
+      throw new Error(
+        `Page config request "${url}" timed out - the dev server may be restarting. Reload the page.`
+      );
+    }
+    throw error;
   }
-}
-
-async function fetchDynamicIcons(basePath) {
-  try {
-    const res = await fetch(`${basePath}/api/icons/dynamic`);
-    if (!res.ok) return {};
-    return parseJsModule(await res.text());
-  } catch {
-    return {};
-  }
-}
-
-async function fetchPageConfig(url) {
-  const res = await fetch(url, {
-    headers: { 'Content-Type': 'application/json' },
-  });
   if (res.status === 404) {
     return null;
   }
@@ -60,34 +59,37 @@ async function fetchPageConfig(url) {
     throw new Error(data.message || 'Request error');
   }
 
-  // Fetch jsMap and dynamic icons after page build completes
-  // (JIT build may have added new entries).
-  // Extract basePath from the URL to construct the endpoints.
-  const basePath = url.replace(/\/api\/page\/.*$/, '');
-  const [jsEntries, dynamicIcons] = await Promise.all([
-    fetchJsEntries(basePath),
-    fetchDynamicIcons(basePath),
-  ]);
-  data._jsEntries = jsEntries;
-  data._dynamicIcons = dynamicIcons;
+  // 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.
+  // _dynamicIcons is already plain data — leave it for Page to inject.
+  if (data._jsEntries) data._jsEntries = parseJsModule(data._jsEntries);
 
-  // Bust CSS cache so the browser picks up newly compiled Tailwind classes
-  const cssLink = document.getElementById('tailwind-jit-css');
-  if (cssLink) {
-    cssLink.href = `${basePath}/tailwind-jit.css?v=${Date.now()}`;
+  if (data?.dynamic === true) {
+    dynamicUrls.add(url);
   }
 
   return data;
 }
 
 function usePageConfig(pageId, basePath) {
-  const url = `${basePath}/api/page/${pageId}`;
+  // 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. The fetcher receives
-  // [url, version] but only uses url — the version just busts the cache.
-  const { data } = useSWR([url, getReloadVersion()], ([fetchUrl]) => fetchPageConfig(fetchUrl), {
-    suspense: true,
-  });
+  // 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;
+  const { data } = useSWR(
+    [url, getReloadVersion(), navVersion],
+    ([fetchUrl]) => fetchPageConfig(fetchUrl),
+    {
+      suspense: true,
+    }
+  );
   return { data };
 }
 

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

@@ -0,0 +1,62 @@
+/*
+  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';
+
+// usePageConfig imports swr and useMutateCache only for the hook; the fetcher
+// under test needs neither. Mock them so the module loads in the node test env.
+jest.unstable_mockModule('swr', () => ({ default: jest.fn() }));
+jest.unstable_mockModule('./useMutateCache.js', () => ({
+  getNavVersion: jest.fn(),
+  getReloadVersion: jest.fn(),
+}));
+
+const { fetchPageConfig } = await import('./usePageConfig.js');
+
+function mockJsonResponse(body) {
+  return { status: 200, ok: true, json: async () => body };
+}
+
+afterEach(() => {
+  delete global.fetch;
+});
+
+test('fetchPageConfig compiles inlined _jsEntries module text into a { hash: fn } object', async () => {
+  global.fetch = jest.fn(async () =>
+    mockJsonResponse({
+      id: 'p',
+      _jsEntries: "export default { 'h1': ({ args }) => { return args.x + 1; } };",
+      _dynamicIcons: { FiZap: { tag: 'svg' } },
+    })
+  );
+
+  const data = await fetchPageConfig('http://localhost/api/page/p');
+
+  expect(typeof data._jsEntries.h1).toBe('function');
+  expect(data._jsEntries.h1({ args: { x: 1 } })).toBe(2);
+  // _dynamicIcons passes through untouched.
+  expect(data._dynamicIcons).toEqual({ FiZap: { tag: 'svg' } });
+});
+
+test('fetchPageConfig issues only the page-config request — no /api/js or /api/icons fetch', async () => {
+  global.fetch = jest.fn(async () => mockJsonResponse({ id: 'p' }));
+
+  const data = await fetchPageConfig('http://localhost/api/page/p');
+
+  expect(data._jsEntries).toBeUndefined();
+  expect(global.fetch).toHaveBeenCalledTimes(1);
+  expect(global.fetch.mock.calls[0][0]).toBe('http://localhost/api/page/p');
+});

package/lib/docs/captureAnnotatedScreenshot.js

@@ -0,0 +1,88 @@
+/*
+  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 drawAnnotationsSvg from '../../client/feedback/drawAnnotationsSvg.js';
+import { getBrowser, openPage } from './getBrowser.js';
+
+// Renders the page headless at the batch's recorded viewport/scroll, injects
+// the developer's drawn shapes and element outlines as an SVG layer inside
+// the page, screenshots the composite, and saves it under the config dir's
+// .lowdefy/annotations/ (gitignored). The saved path goes into the formatted
+// feedback text so an agent can read the image. Never throws — returns
+// { path } or { error }.
+async function captureAnnotatedScreenshot({ origin, batch, fileName }) {
+  let browser;
+  try {
+    browser = await getBrowser();
+  } catch (error) {
+    return { error: `No Chromium available for the annotated screenshot (${error.message}).` };
+  }
+
+  const viewport = batch.viewport ?? {};
+  const width = viewport.width || 1280;
+  const height = viewport.height || 800;
+  const urlQuery = batch.urlQuery && batch.urlQuery !== '?' ? batch.urlQuery : '';
+
+  let context;
+  try {
+    const opened = await openPage({
+      browser,
+      origin,
+      pageId: `${batch.pageId}${urlQuery}`,
+      width,
+      height,
+    });
+    context = opened.context;
+    const { page } = opened;
+
+    if (viewport.scrollX || viewport.scrollY) {
+      await page.evaluate(
+        ([x, y]) => window.scrollTo(x, y),
+        [viewport.scrollX ?? 0, viewport.scrollY ?? 0]
+      );
+      await page.waitForTimeout(200);
+    }
+
+    // Shapes and element rects are viewport-relative at the recorded scroll
+    // offset — after scrolling to the same offset they overlay 1:1. The
+    // compositor is shared with the in-tab capture (drawAnnotationsSvg is
+    // self-contained, so Playwright can serialize it into the page).
+    await page.evaluate(drawAnnotationsSvg, batch.annotations ?? []);
+    await page.waitForTimeout(150);
+
+    const buffer = await page.screenshot({ type: 'png' });
+
+    const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+    const dir = path.join(configDirectory, '.lowdefy', 'annotations');
+    fs.mkdirSync(dir, { recursive: true });
+    const name =
+      fileName ?? `${batch.pageId}-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
+    fs.writeFileSync(path.join(dir, name), buffer);
+
+    return { path: path.join('.lowdefy', 'annotations', name) };
+  } catch (error) {
+    return { error: `Failed to capture annotated screenshot: ${error.message}` };
+  } finally {
+    if (context) {
+      await context.close();
+    }
+  }
+}
+
+export default captureAnnotatedScreenshot;

package/lib/docs/checkpointPaths.js

@@ -0,0 +1,91 @@
+/*
+  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 'fs';
+import path from 'path';
+
+// Shared path/file-listing helpers for createConfigCheckpoint.js,
+// listConfigCheckpoints.js and revertConfigCheckpoint.js.
+
+const CONFIG_FILE_EXTENSIONS = ['.yaml', '.yml', '.json', '.md', '.js', '.env'];
+const EXCLUDED_DIRECTORY_NAMES = ['.lowdefy', 'node_modules', '.git', 'checkpoints'];
+const MAX_CHECKPOINTS = 20;
+const MANIFEST_FILE_NAME = 'manifest.json';
+
+function getConfigDirectory() {
+  return process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd();
+}
+
+function getCheckpointsRoot() {
+  return path.join(getConfigDirectory(), '.lowdefy', 'checkpoints');
+}
+
+// path.extname('.env') is '' (dotfiles have no extension in Node's eyes), so a
+// dotfile named exactly ".env" needs its own basename check.
+function isConfigFile(filePath) {
+  if (path.basename(filePath) === '.env') {
+    return true;
+  }
+  return CONFIG_FILE_EXTENSIONS.includes(path.extname(filePath));
+}
+
+// Recursively lists config-relevant files under `configDirectory`, returned as
+// paths relative to it. Skips directories that should never be snapshotted —
+// build output (.lowdefy, which also holds the checkpoints themselves),
+// dependencies (node_modules) and version control (.git).
+function listConfigFiles({ configDirectory }) {
+  const results = [];
+
+  function walk(currentDir) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRECTORY_NAMES.includes(entry.name)) {
+          continue;
+        }
+        walk(fullPath);
+      } else if (entry.isFile() && isConfigFile(fullPath)) {
+        results.push(path.relative(configDirectory, fullPath));
+      }
+    }
+  }
+
+  if (fs.existsSync(configDirectory)) {
+    walk(configDirectory);
+  }
+  return results;
+}
+
+// Slugifies a checkpoint label for use in a directory name — lowercase,
+// non-alphanumeric runs collapsed to a single "-", leading/trailing "-"
+// trimmed. Falls back to "checkpoint" when the label slugifies to nothing
+// (e.g. an empty string or a label made only of punctuation).
+function slug(label) {
+  const slugified = String(label ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slugified === '' ? 'checkpoint' : slugified;
+}
+
+export {
+  getCheckpointsRoot,
+  getConfigDirectory,
+  listConfigFiles,
+  MANIFEST_FILE_NAME,
+  MAX_CHECKPOINTS,
+  slug,
+};