@lowdefy/server-dev 6.0.0 → 7.0.0

package/client/App.jsx

@@ -18,19 +18,30 @@ import React, { Suspense, useCallback, useEffect, useRef, useState } from 'react
 import useSWR from 'swr';
 
 import { ErrorBoundary } from '@lowdefy/block-utils';
-import { useDarkMode, useLocale } from '@lowdefy/client';
+import { IconProvider, useDarkMode, useLocale } from '@lowdefy/client';
 import { StyleProvider } from '@ant-design/cssinjs';
 import { App as AntdApp, theme as antdTheme } from 'antd';
 import { XProvider } from '@ant-design/x';
+import { appStorageKey, serializer } from '@lowdefy/helpers';
 
 import antdLocaleLoaders from '../build/i18n/antdLocales.js';
 import antdXLocaleLoaders from '../build/i18n/antdXLocales.js';
 import dayjsLocaleMap from '../build/i18n/dayjsLocales.js';
+import rawTheme from '../build/theme.json';
 import Auth from '../lib/client/auth/Auth.jsx';
 import ErrorBar from '../lib/client/ErrorBar.jsx';
+import getCspNonce from '../lib/client/getCspNonce.js';
 import request from '../lib/client/utils/request.js';
 import Routing from './Routing.jsx';
 
+// rootConfig arrives after the first render; the build-written theme gives
+// the icon provider its settings until then.
+const buildTheme = serializer.deserialize(rawTheme);
+
+// antd and antd X put this nonce on the style tags they add, so the page's
+// Content-Security-Policy applies them. Empty (no nonce) when the policy is off.
+const csp = { nonce: getCspNonce() };
+
 function ThemeTokenResolver({ lowdefyRef, children }) {
   const { token } = antdTheme.useToken();
   if (!lowdefyRef.current.theme) {
@@ -40,7 +51,7 @@ function ThemeTokenResolver({ lowdefyRef, children }) {
   return children;
 }
 
-function App({ router }) {
+function App({ config, router }) {
   const lowdefyRef = useRef({});
   const [runtimeErrors, setRuntimeErrors] = useState([]);
   // Subscribe to rootConfig SWR cache — deduplicates with Routing's fetch.
@@ -50,9 +61,12 @@ function App({ router }) {
     lowdefyRef.current.theme = rootConfig.theme;
   }
 
+  // Device preferences, kept per app (the same key the HTML template's dark mode script reads).
+  const storageScope = { basePath: router.basePath, slug: config.slug };
   const { algorithm, token, components } = useDarkMode({
     antd: lowdefyRef.current.theme?.antd,
     configDarkMode: lowdefyRef.current.theme?.darkMode,
+    storageKey: appStorageKey({ ...storageScope, name: 'lowdefy_darkMode' }),
   });
 
   const {
@@ -64,6 +78,7 @@ function App({ router }) {
     antdLocaleLoaders,
     antdXLocaleLoaders,
     dayjsLocaleMap,
+    storageKey: appStorageKey({ ...storageScope, name: 'lowdefy_locale' }),
   });
 
   if (rootConfig?.i18n?.defaultLocale) {
@@ -88,6 +103,7 @@ function App({ router }) {
         message: error.message,
         source: error.source,
         stack: error.stack,
+        prodError: error.prodError === true,
       },
     ]);
   }, []);
@@ -115,6 +131,7 @@ function App({ router }) {
   return (
     <StyleProvider layer>
       <XProvider
+        csp={csp}
         locale={mergedLocale}
         form={
           antdLocale?.Form?.defaultValidateMessages
@@ -130,29 +147,40 @@ function App({ router }) {
           algorithm,
         }}
       >
-        <AntdApp>
-          <ThemeTokenResolver lowdefyRef={lowdefyRef}>
-            <ErrorBoundary fullPage onError={handleError}>
-              <Suspense
-                fallback={
-                  <div
-                    style={{
-                      minHeight: '100vh',
-                      background: 'var(--ant-color-bg-layout)',
+        {/* Message, Notification and ConfirmModal render in the App.useApp()
+            holders here, above the Client's icon provider. */}
+        <IconProvider icons={rootConfig?.theme.icons ?? buildTheme.icons}>
+          <AntdApp>
+            <ThemeTokenResolver lowdefyRef={lowdefyRef}>
+              <ErrorBoundary fullPage onError={handleError}>
+                <Suspense
+                  fallback={
+                    <div
+                      style={{
+                        minHeight: '100vh',
+                        background: 'var(--ant-color-bg-layout)',
+                      }}
+                    />
+                  }
+                >
+                  <Auth user={config?.user}>
+                    {(auth) => {
+                      return (
+                        <Routing
+                          auth={auth}
+                          lowdefy={lowdefyRef.current}
+                          recording={config?.recording}
+                          router={router}
+                        />
+                      );
                     }}
-                  />
-                }
-              >
-                <Auth>
-                  {(auth) => {
-                    return <Routing auth={auth} lowdefy={lowdefyRef.current} router={router} />;
-                  }}
-                </Auth>
-              </Suspense>
-            </ErrorBoundary>
-            <ErrorBar errors={runtimeErrors} />
-          </ThemeTokenResolver>
-        </AntdApp>
+                  </Auth>
+                </Suspense>
+              </ErrorBoundary>
+              <ErrorBar errors={runtimeErrors} />
+            </ThemeTokenResolver>
+          </AntdApp>
+        </IconProvider>
       </XProvider>
     </StyleProvider>
   );

package/client/Inspector.jsx

@@ -26,11 +26,13 @@ import DevStreamContext from './DevStreamContext.js';
 // 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
+// Page 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.
+// stream. This component then posts { tabId, pageId, pathParams, instanceKey }
+// to /api/dev-inspect/page whenever the page instance on screen changes, so the
+// registry's view of "what instance is this tab on" stays current without
+// reconnecting. A request names the instance to read (the dev server picks
+// it); without one it reads the instance on screen.
 //
 // 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
@@ -55,23 +57,62 @@ function postResult({ basePath, requestId, result }) {
   postJson({ basePath, path: '', body: { requestId, result } });
 }
 
-function postTabPage({ basePath, tabId, pageId }) {
-  postJson({ basePath, path: '/page', body: { tabId, pageId } });
+function postTabPage({ basePath, tabId, page }) {
+  postJson({
+    basePath,
+    path: '/page',
+    body: {
+      tabId,
+      pageId: page.pageId,
+      pathParams: page.pathParams,
+      instanceKey: page.instanceKey,
+    },
+  });
+}
+
+// `page "ticket"`, or `page "ticket" (tickets/s/1)` for an instance of a page with placeholders,
+// whose instance key ends in the path its values build.
+function describePage({ pageId, instanceKey }) {
+  const hashIndex = instanceKey.indexOf('#');
+  if (hashIndex === -1) {
+    return `page "${pageId}"`;
+  }
+  return `page "${pageId}" (${instanceKey.slice(hashIndex + 1)})`;
+}
+
+function requestedPage({ data, shownPage }) {
+  if (type.isString(data.instanceKey)) {
+    return { pageId: data.pageId, pathParams: data.pathParams, instanceKey: data.instanceKey };
+  }
+  return shownPage;
 }
 
-function buildSnapshot({ lowdefy, pageId }) {
-  const context = lowdefy?.contexts?.[`page:${pageId}`];
+function findContext({ lowdefy, page }) {
+  if (type.isNone(page)) {
+    return { error: 'No page has rendered in this tab yet.' };
+  }
+  const context = lowdefy?.contexts?.[page.instanceKey];
   if (type.isNone(context)) {
-    return { error: `No live context for page "${pageId}".` };
+    return { error: `No live context for ${describePage(page)}.` };
+  }
+  return { context };
+}
+
+function buildSnapshot({ lowdefy, page }) {
+  const { context, error } = findContext({ lowdefy, page });
+  if (error) {
+    return { error };
   }
   return serializer.serializeToString({
-    pageId,
+    pageId: page.pageId,
+    pathParams: context.pathParams,
+    instanceKey: page.instanceKey,
     state: context.state,
     requests: context.requests,
     eventLog: (context.eventLog ?? []).slice(-50),
     global: lowdefy.lowdefyGlobal,
     user: lowdefy.user,
-    input: lowdefy.inputs?.[`page:${pageId}`],
+    input: lowdefy.inputs?.[page.instanceKey],
     urlQuery: window.location.search,
   });
 }
@@ -88,7 +129,7 @@ function buildSnapshot({ lowdefy, pageId }) {
 // 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 }) {
+async function bootstrapFromCheckpoint({ basePath, instanceKey, checkpointName, isCancelled }) {
   try {
     const response = await fetch(
       `${basePath}/api/dev-inspect/checkpoint/${encodeURIComponent(checkpointName)}`
@@ -106,7 +147,7 @@ async function bootstrapFromCheckpoint({ basePath, pageId, checkpointName, isCan
     const deadline = Date.now() + 5000;
     let context;
     while (!isCancelled() && Date.now() < deadline) {
-      context = window.lowdefy?.contexts?.[`page:${pageId}`];
+      context = window.lowdefy?.contexts?.[instanceKey];
       if (context) {
         break;
       }
@@ -127,10 +168,10 @@ async function bootstrapFromCheckpoint({ basePath, pageId, checkpointName, isCan
   }
 }
 
-function evalExpression({ lowdefy, pageId, expression }) {
-  const context = lowdefy?.contexts?.[`page:${pageId}`];
-  if (type.isNone(context)) {
-    return { error: `No live context for page "${pageId}".` };
+function evalExpression({ lowdefy, page, expression }) {
+  const { context, error } = findContext({ lowdefy, page });
+  if (error) {
+    return { error };
   }
   // 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
@@ -143,10 +184,10 @@ function evalExpression({ lowdefy, pageId, expression }) {
   };
 }
 
-const Inspector = ({ basePath, lowdefy, pageId }) => {
+const Inspector = ({ basePath, lowdefy, page }) => {
   const { source, tabId } = useContext(DevStreamContext);
-  const pageIdRef = useRef(pageId);
-  pageIdRef.current = pageId;
+  const pageRef = useRef(page);
+  pageRef.current = page;
 
   useEffect(() => {
     if (type.isNone(source)) {
@@ -158,8 +199,10 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
       try {
         const data = JSON.parse(message.data);
         requestId = data.requestId;
-        const targetPageId = data.pageId ?? pageIdRef.current;
-        const result = buildSnapshot({ lowdefy, pageId: targetPageId });
+        const result = buildSnapshot({
+          lowdefy,
+          page: requestedPage({ data, shownPage: pageRef.current }),
+        });
         postResult({ basePath, requestId, result });
       } catch (error) {
         postResult({ basePath, requestId, result: { error: error.message } });
@@ -171,10 +214,9 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
       try {
         const data = JSON.parse(message.data);
         requestId = data.requestId;
-        const targetPageId = data.pageId ?? pageIdRef.current;
         const result = evalExpression({
           lowdefy,
-          pageId: targetPageId,
+          page: requestedPage({ data, shownPage: pageRef.current }),
           expression: data.expression,
         });
         postResult({ basePath, requestId, result });
@@ -192,14 +234,15 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
   }, [basePath, lowdefy, source]);
 
   useEffect(() => {
-    if (type.isNone(tabId) || type.isNone(pageId)) {
+    if (type.isNone(tabId) || type.isNone(page)) {
       return;
     }
-    postTabPage({ basePath, tabId, pageId });
-  }, [basePath, tabId, pageId]);
+    postTabPage({ basePath, tabId, page });
+  }, [basePath, tabId, page]);
 
+  const instanceKey = page?.instanceKey;
   useEffect(() => {
-    if (type.isNone(pageId)) {
+    if (type.isNone(instanceKey)) {
       return undefined;
     }
     const checkpointName = new URLSearchParams(window.location.search).get('_checkpoint');
@@ -210,7 +253,7 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
     let cancelled = false;
     bootstrapFromCheckpoint({
       basePath,
-      pageId,
+      instanceKey,
       checkpointName,
       isCancelled: () => cancelled,
     });
@@ -218,7 +261,7 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
     return () => {
       cancelled = true;
     };
-  }, [basePath, pageId]);
+  }, [basePath, instanceKey]);
 
   return null;
 };

package/client/JourneyObserver.jsx

@@ -0,0 +1,47 @@
+/*
+  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 { useEffect } from 'react';
+import { getTrace } from '@lowdefy/engine';
+
+import collectVisibleBlockIds from '../lib/client/collectVisibleBlockIds.js';
+import startJourneyObserver from './journeyObserver/startJourneyObserver.js';
+
+// Dev-only: tells the journey runner which events completed and which blocks
+// were visible in a journey's own pages (see journeyObserver/). It renders
+// null, like Inspector, does nothing in a developer's tab, and never lets an
+// error reach the app.
+function JourneyObserver({ lowdefy }) {
+  useEffect(() => {
+    let stop = null;
+    try {
+      stop = startJourneyObserver({ window, lowdefy, getTrace, collectVisibleBlockIds });
+    } catch {
+      return undefined;
+    }
+    return () => {
+      try {
+        stop?.();
+      } catch {
+        // Best effort.
+      }
+    };
+  }, [lowdefy]);
+
+  return null;
+}
+
+export default JourneyObserver;

package/client/Page.jsx

@@ -15,11 +15,12 @@
 */
 
 import React, { useEffect, useRef } from 'react';
-import { GenIcon } from 'react-icons/lib';
 import Client from '@lowdefy/client';
+import { pageInstanceKey } from '@lowdefy/helpers';
 
 import BuildErrorPage from '../lib/client/BuildErrorPage.jsx';
 import InstallingPluginsPage from '../lib/client/InstallingPluginsPage.jsx';
+import RedirectingPage from '../lib/client/RedirectingPage.jsx';
 import usePageConfig from '../lib/client/utils/usePageConfig.js';
 
 const Page = ({
@@ -28,12 +29,18 @@ const Page = ({
   config,
   jsMap,
   lowdefy,
-  pageId,
+  onPageShown,
+  path,
   resetContext,
   router,
   types,
 }) => {
-  const { data: pageConfig } = usePageConfig(pageId, router.basePath);
+  const { data } = usePageConfig(path, router.basePath, auth.user, lowdefy);
+  const pageConfig = data?.pageConfig;
+  // Past the config fetch (which suspends), this render shows the page the
+  // URL names, so a navigation Routing marked has landed. Set during render,
+  // like lowdefy.pageId (initLowdefyContext), so the two change together.
+  lowdefy._devNavigating = false;
 
   // Push build warnings to ErrorBar via runtime error callback
   const pushedWarningsRef = useRef(null);
@@ -46,37 +53,60 @@ const Page = ({
     }
   }, [pageConfig?._warnings, lowdefy]);
 
-  if (!pageConfig) {
+  // Tells the in-page dev tools which page instance is on screen, from the fetched page.
+  useEffect(() => {
+    if (pageConfig) {
+      onPageShown({
+        pageId: data.pageId,
+        pathParams: data.pathParams,
+        instanceKey: pageInstanceKey({
+          pageId: data.pageId,
+          path: pageConfig.path,
+          pathParams: data.pathParams,
+        }),
+      });
+    }
+  }, [pageConfig, data?.pageId, data?.pathParams, onPageShown]);
+
+  // Full load to the sign-in page so it can return here after sign-in — an
+  // effect, not a fetcher side effect, so the redirect re-fires if the same
+  // cached result renders again.
+  useEffect(() => {
+    if (data?.authRedirect) {
+      window.location.assign(data.authRedirect);
+    }
+  }, [data?.authRedirect]);
+
+  if (!data) {
     router.replace({ pathname: '/404' });
     return '';
   }
-  if (pageConfig.buildError) {
-    return (
-      <BuildErrorPage
-        errors={pageConfig.errors}
-        message={pageConfig.message}
-        source={pageConfig.source}
-      />
-    );
+  if (data.authRedirect) {
+    return <RedirectingPage redirect={data.authRedirect} />;
+  }
+  if (data.buildError) {
+    return <BuildErrorPage errors={data.errors} message={data.message} source={data.source} />;
   }
-  if (pageConfig.installing) {
-    return <InstallingPluginsPage packages={pageConfig.packages} />;
+  if (data.installing) {
+    return <InstallingPluginsPage packages={data.packages} />;
   }
 
   // Merge dynamic JS entries fetched after JIT build with the static jsMap
   const mergedJsMap = pageConfig._jsEntries ? { ...jsMap, ...pageConfig._jsEntries } : jsMap;
 
-  // Merge JIT-discovered icon data into the static icons object.
-  // createIcon.js looks up Icons[name] on every render from the captured reference,
-  // so mutating the original object makes new icons available immediately.
+  // Merge JIT-delivered icon data into the static icons map. Icons are data
+  // (IconData), and createIcon looks up Icons[name] on every render from the
+  // captured reference, so mutating the original object makes them available
+  // immediately.
   if (pageConfig._dynamicIcons) {
-    for (const [name, data] of Object.entries(pageConfig._dynamicIcons)) {
-      if (!types.icons[name]) {
-        types.icons[name] = GenIcon(data);
-      }
-    }
+    Object.assign(types.icons, pageConfig._dynamicIcons);
   }
 
+  // The build this config was served under, for the recorder to stamp on each
+  // interaction. Set during render, like the icons above, so it is in place
+  // before any interaction on this config.
+  lowdefy._devBuildId = pageConfig._buildId ?? null;
+
   return (
     <Client
       auth={auth}
@@ -87,6 +117,8 @@ const Page = ({
       }}
       jsMap={mergedJsMap}
       lowdefy={lowdefy}
+      matchedPath={data.matchedPath}
+      pathParams={data.pathParams}
       resetContext={resetContext}
       router={router}
       stage="dev"

package/client/Recorder.jsx

@@ -0,0 +1,73 @@
+/*
+  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 { getTrace } from '@lowdefy/engine';
+
+import createRecorder from './recorder/createRecorder.js';
+import DevStreamContext from './DevStreamContext.js';
+
+// Dev-only journey recorder: records how the developer uses the app, locally,
+// so an agent can turn what they tried into journeys (see recorder/). It
+// renders null, like Inspector, and never lets an error reach the app.
+//
+// It opens no connection of its own: a second long-lived stream per tab once
+// exhausted the browser's HTTP/1.1 connection pool (see DevStreamContext.js).
+// It listens for `reload` on the tab's one shared stream and flushes there,
+// only to send promptly: each record carries the build of the page config it
+// was made on (lowdefy._devBuildId, set by Page.jsx).
+// `path` is the path Page fetches, so a navigation starts a pageview; `page`
+// is the page instance on screen, { pageId, pathParams, instanceKey }, as the
+// fetched page names it, which completes it.
+function Recorder({ basePath, lowdefy, page, path, recording }) {
+  const { source } = useContext(DevStreamContext);
+  const recorderRef = useRef(null);
+
+  useEffect(() => {
+    let recorder = null;
+    try {
+      recorder = createRecorder({ basePath, lowdefy, recording, window, getTrace });
+    } catch {
+      return undefined;
+    }
+    if (recorder === null) return undefined;
+    recorderRef.current = recorder;
+    return () => {
+      recorderRef.current = null;
+      try {
+        recorder.stop();
+      } catch {
+        // Best effort.
+      }
+    };
+  }, [recording?.enabled]);
+
+  useEffect(() => {
+    recorderRef.current?.pageview({ path });
+  }, [path, recording?.enabled]);
+
+  useEffect(() => {
+    if (page !== null) recorderRef.current?.pageShown(page);
+  }, [page?.instanceKey, recording?.enabled]);
+
+  useEffect(() => {
+    return recorderRef.current?.attachStream(source);
+  }, [source, recording?.enabled]);
+
+  return null;
+}
+
+export default Recorder;