@lowdefy/server-dev 0.0.0-experimental-20260720135014 → 0.0.0-experimental-20260722143027

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/Inspector.jsx

@@ -0,0 +1,206 @@
+/*
+  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, useRef } from 'react';
+
+import { type, serializer } from '@lowdefy/helpers';
+
+// Dev-only agent-state-xray channel — a sibling of Reload.jsx, but with its
+// own /api/reload SSE connection (rather than reusing Reload's) so that
+// connection can carry ?pageId=<pageId>. routes/reload.js only registers a
+// connection as an inspectable tab (lib/docs/tabChannel.js) when that query
+// param is present, which keeps Reload.jsx's plain reload/ping connection
+// out of the tab registry entirely.
+//
+// pageId tracking: this effect depends on `pageId`, so React tears down and
+// reopens the EventSource (a fresh connection, fresh tab id server-side)
+// whenever the developer navigates to a different page — see the longer
+// design note in src/routes/reload.js.
+//
+// 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 postResult({ basePath, requestId, result }) {
+  try {
+    fetch(`${basePath}/api/dev-inspect`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ requestId, result }),
+    }).catch(() => {
+      // Best-effort — a failed callback just leaves the agent's request to
+      // time out server-side.
+    });
+  } catch {
+    // JSON.stringify or fetch throwing synchronously — still best-effort.
+  }
+}
+
+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 "${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 pageIdRef = useRef(pageId);
+  pageIdRef.current = pageId;
+
+  useEffect(() => {
+    if (type.isNone(pageId)) {
+      return undefined;
+    }
+
+    const sse = new EventSource(`${basePath}/api/reload?pageId=${encodeURIComponent(pageId)}`);
+
+    sse.addEventListener('inspect-request', (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 } });
+      }
+    });
+
+    sse.addEventListener('eval-request', (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 } });
+      }
+    });
+
+    return () => {
+      sse.close();
+    };
+  }, [basePath, lowdefy, 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,10 @@ 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 RestartingPage from '../lib/client/RestartingPage.jsx';
+import usePageConfig from '../lib/client/utils/usePageConfig.js';
 
 const Page = ({
   auth,
@@ -48,7 +48,7 @@ const Page = ({
   }, [pageConfig?._warnings, lowdefy]);
 
   if (!pageConfig) {
-    router.replace(`/404`);
+    router.replace({ pathname: '/404' });
     return '';
   }
   if (pageConfig.buildError) {

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

@@ -16,9 +16,12 @@
 
 import React, { useEffect, useState } from 'react';
 
-import useMutateCache from './utils/useMutateCache.js';
-import waitForRestartedServer from './utils/waitForRestartedServer.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.
 const Reload = ({ children, basePath, lowdefy }) => {
   const [reset, setReset] = useState(false);
   const [restarting, setRestarting] = useState(false);
@@ -34,11 +37,6 @@ const Reload = ({ children, basePath, lowdefy }) => {
         if (lowdefy._internal?.initialised) {
           lowdefy._internal.initialised = false;
         }
-        // Refresh JIT CSS link to pick up newly compiled Tailwind classes
-        const cssLink = document.getElementById('tailwind-jit-css');
-        if (cssLink) {
-          cssLink.href = `${basePath}/tailwind-jit.css?v=${Date.now()}`;
-        }
         setReset(true);
         console.log('Reloaded config.');
       }, 600);

package/client/Routing.jsx

@@ -0,0 +1,106 @@
+/*
+  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 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 (
+    <>
+      <Inspector basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+      <FeedbackMount basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+      <OpenInEditorListener basePath={router.basePath} pageId={pageId} />
+      <Reload basePath={router.basePath} lowdefy={lowdefy}>
+        {(resetContext) => (
+          <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/feedback/FeedbackMount.jsx

@@ -0,0 +1,83 @@
+/*
+  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 useFeedbackToggle from './useFeedbackToggle.js';
+
+// Logged once per page load, not once per mount — React StrictMode / HMR can
+// remount this component without a real reload.
+let bannerLogged = false;
+
+function logBannerOnce() {
+  if (bannerLogged) {
+    return;
+  }
+  bannerLogged = true;
+  try {
+    // eslint-disable-next-line no-console
+    console.info(
+      '%cLowdefy Annotate%c — press Cmd/Ctrl+/ to point, draw, and copy annotations for your coding agent.',
+      'color: #4f9cf9; font-weight: bold;',
+      'color: inherit;'
+    );
+    // eslint-disable-next-line no-console
+    console.info(
+      '%cLowdefy Open Code%c — Cmd/Ctrl+click any element to open its yaml in VS Code.',
+      'color: #4f9cf9; font-weight: bold;',
+      'color: inherit;'
+    );
+  } catch {
+    // Never let a console-styling quirk break the app.
+  }
+}
+
+// Code-split: the overlay (state machine, drawing SVG, review tray) only
+// loads once the developer actually opts in.
+const LazyOverlay = React.lazy(() => import('./FeedbackOverlay.jsx'));
+
+// Dev-only, always mounted alongside Inspector.jsx. Mirrors its resilience
+// contract — nothing here may ever throw into the app it's riding along
+// with. Stays inert until the developer presses Cmd/Ctrl+/, at which point
+// the overlay mounts.
+function FeedbackMount({ basePath, lowdefy, pageId }) {
+  const [active, setActive] = useState(false);
+
+  useFeedbackToggle({
+    onToggle: () => setActive((current) => !current),
+  });
+
+  useEffect(() => {
+    logBannerOnce();
+  }, []);
+
+  return (
+    <>
+      {active && (
+        <Suspense fallback={null}>
+          <LazyOverlay
+            basePath={basePath}
+            lowdefy={lowdefy}
+            pageId={pageId}
+            onClose={() => setActive(false)}
+          />
+        </Suspense>
+      )}
+    </>
+  );
+}
+
+export default FeedbackMount;