@lowdefy/server-dev 0.0.0-experimental-20260905100314 → 0.0.0-experimental-20260908103554

package/client/DevStreamContext.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.
+*/
+
+import { createContext } from 'react';
+
+// The one /api/reload EventSource a dev tab holds, owned by Reload.jsx and
+// shared with Inspector.jsx: { source, tabId }. Dev runs on HTTP/1.1, where
+// browsers cap connections per host at six and an open event stream holds
+// one for the life of the tab. Two streams per tab meant three tabs of the
+// same app saturated the pool and the next fetch queued forever, so every
+// dev-only channel rides this single stream instead of opening its own.
+//   - source: the EventSource, null until Reload's effect has opened it.
+//   - tabId: the id the server assigned this connection in its tab registry
+//     (lib/docs/tabChannel.js), null until the stream's `tab` event arrives.
+const DevStreamContext = createContext({ source: null, tabId: null });
+
+export default DevStreamContext;

package/client/Inspector.jsx

@@ -14,40 +14,51 @@
   limitations under the License.
 */
 
-import { useEffect, useRef } from 'react';
+import { useContext, 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.
+import DevStreamContext from './DevStreamContext.js';
+
+// Dev-only agent-state-xray channel. Listens for inspect-request/eval-request
+// events on the tab's single /api/reload EventSource (owned by Reload.jsx,
+// shared through DevStreamContext) rather than opening its own — a second
+// 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: 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.
+// pageId 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.
 //
 // 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 }) {
+function postJson({ basePath, path, body }) {
   try {
-    fetch(`${basePath}/api/dev-inspect`, {
+    fetch(`${basePath}/api/dev-inspect${path}`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ requestId, result }),
+      body: JSON.stringify(body),
     }).catch(() => {
       // Best-effort — a failed callback just leaves the agent's request to
-      // time out server-side.
+      // time out server-side, and a failed page update leaves the tab
+      // registered on its previous page.
     });
   } catch {
     // JSON.stringify or fetch throwing synchronously — still best-effort.
   }
 }
 
+function postResult({ basePath, requestId, result }) {
+  postJson({ basePath, path: '', body: { requestId, result } });
+}
+
+function postTabPage({ basePath, tabId, pageId }) {
+  postJson({ basePath, path: '/page', body: { tabId, pageId } });
+}
+
 function buildSnapshot({ lowdefy, pageId }) {
   const context = lowdefy?.contexts?.[`page:${pageId}`];
   if (type.isNone(context)) {
@@ -133,17 +144,16 @@ function evalExpression({ lowdefy, pageId, expression }) {
 }
 
 const Inspector = ({ basePath, lowdefy, pageId }) => {
+  const { source, tabId } = useContext(DevStreamContext);
   const pageIdRef = useRef(pageId);
   pageIdRef.current = pageId;
 
   useEffect(() => {
-    if (type.isNone(pageId)) {
+    if (type.isNone(source)) {
       return undefined;
     }
 
-    const sse = new EventSource(`${basePath}/api/reload?pageId=${encodeURIComponent(pageId)}`);
-
-    sse.addEventListener('inspect-request', (message) => {
+    const onInspectRequest = (message) => {
       let requestId;
       try {
         const data = JSON.parse(message.data);
@@ -154,9 +164,9 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
       } catch (error) {
         postResult({ basePath, requestId, result: { error: error.message } });
       }
-    });
+    };
 
-    sse.addEventListener('eval-request', (message) => {
+    const onEvalRequest = (message) => {
       let requestId;
       try {
         const data = JSON.parse(message.data);
@@ -171,12 +181,22 @@ const Inspector = ({ basePath, lowdefy, pageId }) => {
       } catch (error) {
         postResult({ basePath, requestId, result: { error: error.message } });
       }
-    });
+    };
 
+    source.addEventListener('inspect-request', onInspectRequest);
+    source.addEventListener('eval-request', onEvalRequest);
     return () => {
-      sse.close();
+      source.removeEventListener('inspect-request', onInspectRequest);
+      source.removeEventListener('eval-request', onEvalRequest);
     };
-  }, [basePath, lowdefy, pageId]);
+  }, [basePath, lowdefy, source]);
+
+  useEffect(() => {
+    if (type.isNone(tabId) || type.isNone(pageId)) {
+      return;
+    }
+    postTabPage({ basePath, tabId, pageId });
+  }, [basePath, tabId, pageId]);
 
   useEffect(() => {
     if (type.isNone(pageId)) {

package/client/Reload.jsx

@@ -16,15 +16,21 @@
 
 import React, { useEffect, useState } from 'react';
 
+import DevStreamContext from './DevStreamContext.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.
+//
+// This is the tab's only EventSource. It is shared through DevStreamContext
+// so Inspector.jsx can listen on the same connection instead of opening a
+// second one — see the connection-limit note in DevStreamContext.js.
 const Reload = ({ children, basePath, lowdefy }) => {
   const [reset, setReset] = useState(false);
   const [restarting, setRestarting] = useState(false);
+  const [devStream, setDevStream] = useState({ source: null, tabId: null });
   // reset is a one-shot boolean the engine lowers only after a page mounts
   // (getContext.js) — while a page is suspended it stays true and setReset(true)
   // bails out of re-rendering. The tick always changes, so every reload event
@@ -36,6 +42,15 @@ const Reload = ({ children, basePath, lowdefy }) => {
   useEffect(() => {
     const sse = new EventSource(`${basePath}/api/reload`);
 
+    // routes/reload.js registers every connection as an inspectable tab and
+    // announces the id it chose as the first event on the stream. The stream
+    // is published to consumers only then, in one state update, so the page
+    // subtree re-renders once at mount rather than once per field.
+    sse.addEventListener('tab', (message) => {
+      const { tabId } = JSON.parse(message.data);
+      setDevStream({ source: sse, tabId });
+    });
+
     sse.addEventListener('reload', () => {
       // add a update delay to prevent rerender before server is shut down for rebuild, ideally we don't want to do this.
       // TODO: We need to pass a flag when a rebuild will happen so that client does not trigger render.
@@ -60,7 +75,11 @@ const Reload = ({ children, basePath, lowdefy }) => {
       sse.close();
     };
   }, []);
-  return <>{children({ reset, setReset, restarting })}</>;
+  return (
+    <DevStreamContext.Provider value={devStream}>
+      {children({ reset, setReset, restarting })}
+    </DevStreamContext.Provider>
+  );
 };
 
 export default Reload;

package/client/Routing.jsx

@@ -72,40 +72,43 @@ function Routing({ auth, lowdefy, router }) {
 
   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) =>
-          // Rendered here, not in Page — Page sits below the Suspense boundary
-          // and cannot render anything while its config fetch is suspended, so
-          // a restarting server would present as "Building page..." forever.
-          resetContext.restarting ? (
-            <RestartingPage />
-          ) : (
-            <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>
-          )
-        }
+        {(resetContext) => (
+          <>
+            {/* Inside Reload so it can share Reload's event stream (DevStreamContext). */}
+            <Inspector basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+            {/* Rendered here, not in Page — Page sits below the Suspense boundary
+                and cannot render anything while its config fetch is suspended, so
+                a restarting server would present as "Building page..." forever. */}
+            {resetContext.restarting ? (
+              <RestartingPage />
+            ) : (
+              <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>
     </>
   );

package/lib/client/auth/AuthConfigured.jsx

@@ -18,6 +18,7 @@ import React, { useEffect, useRef, useState } from 'react';
 import { createAuthClient } from 'better-auth/react';
 import {
   adminClient,
+  emailOTPClient,
   magicLinkClient,
   organizationClient,
   phoneNumberClient,
@@ -44,6 +45,7 @@ const authClient = createAuthClient({
   baseURL: `${window.location.origin}${lowdefyConfig.basePath ?? ''}/api/auth`,
   plugins: [
     adminClient(),
+    emailOTPClient(),
     magicLinkClient(),
     oauthProviderClient(),
     organizationClient(),
@@ -57,8 +59,8 @@ const authClient = createAuthClient({
 // signal-driven refetch on the calls that would otherwise fire one, so
 // nothing competes with (and aborts) the refetch UpdateSession awaits.
 // Only calls that mutate an existing session are suppressed - calls that
-// can establish one (the sign-ins, and the two-factor, phone-number and
-// passkey verifies) keep their signal: its refetch is what makes the store
+// can establish one (the sign-ins, and the two-factor, phone-number,
+// email-otp and passkey verifies) keep their signal: its refetch is what makes the store
 // notice a login when no navigation follows.
 // disableSignal silences all atomListeners for the call, including the
 // organization plugin's org atoms - none are exposed to app config, so a
@@ -193,6 +195,9 @@ function AuthConfigured({ authConfig, children, serverUser }) {
     // oauth_query contract as oauth2Consent: the signed query rides from
     // window.location.search, so the call must run before any navigation.
     oauth2Continue: (params) => authClient.oauth2.continue(params),
+    // The one-time email code: send, then sign in with it.
+    emailOtpSend: (params) => authClient.emailOtp.sendVerificationOtp(params),
+    emailOtpVerify: (params) => authClient.signIn.emailOtp(params),
     phoneNumberRequestPasswordReset: (params) =>
       authClient.phoneNumber.requestPasswordReset(params),
     phoneNumberResetPassword: (params) => authClient.phoneNumber.resetPassword(params),

package/lib/client/auth/AuthNotConfigured.js

@@ -39,6 +39,8 @@ function AuthNotConfigured({ authConfig, children, user = null }) {
     listOrganizations: authNotConfigured,
     oauth2Consent: authNotConfigured,
     oauth2Continue: authNotConfigured,
+    emailOtpSend: authNotConfigured,
+    emailOtpVerify: authNotConfigured,
     phoneNumberRequestPasswordReset: authNotConfigured,
     phoneNumberResetPassword: authNotConfigured,
     phoneNumberSendOtp: authNotConfigured,

package/lib/docs/createDocsMcpServer.js

@@ -445,13 +445,13 @@ function createDocsMcpServer({ origin, honoContext } = {}) {
     'lowdefy_run_journey',
     {
       description:
-        'Drive a page of the running dev server headless through declarative steps and assert what happens — the way to verify behaviour (a form submits, a modal opens, a filter works), not just layout. Blocks are addressed by blockId. A step that fails stops the journey and is returned as data (passed: false, failure with index/step/expected/actual/message, later steps "skipped") — never as a tool error. Always returns the final page state and any screenshots taken (as images after the JSON text).',
+        'Drive a page of the running dev server headless through declarative steps and assert what happens — the way to verify behaviour (a form submits, a modal opens, a filter works), not just layout. Blocks are addressed by blockId; a target object narrows to a grid row/cell ({"blockId": "grid", "row": 1, "column": "actions"}), to the control with exactly some text ({"blockId": "grid", "row": 1, "text": "Edit"}), or reaches portal-rendered controls page-wide by text alone ({"text": "OK"} for a confirm dialog or modal footer button, a menu item). A step that fails stops the journey and is returned as data (passed: false, failure with index/step/expected/actual/message, later steps "skipped") — never as a tool error. Always returns the final page state and any screenshots taken (as images after the JSON text).',
       inputSchema: {
         pageId: z.string().describe('The page id to open.'),
         steps: z
           .array(z.record(z.any()))
           .describe(
-            'Ordered steps, one key each: {"click": blockId} | {"fill": {"blockId", "value"}} | {"select": {"blockId", "value"}} (option by exact text) | {"press": "Enter" | "Mod+k"} (Mod is Meta/Control per platform) | {"wait": {"ms": n} | {"request": requestId} | {"state": path}} | {"screenshot": name?} | {"expect": {"state": {"path", "equals"}} | {"visible": blockId} | {"text": {"blockId", "contains"}} | {"url": {"contains"}}}. Each step gets 5s; after an interaction the runner waits for the page\'s pending events and requests to settle.'
+            'Ordered steps, one key each: {"click": target} | {"fill": {...target, "value"}} | {"select": {...target, "value"}} (option by exact text) | {"press": "Enter" | "Mod+k"} (Mod is Meta/Control per platform) | {"wait": {"ms": n} | {"request": requestId} | {"state": path}} | {"screenshot": name?} | {"expect": {"state": {"path", "equals"}} | {"visible": target} | {"text": {...target, "contains"}} | {"url": {"contains"}}}. A target is a blockId string, or an object of {"blockId", "row" (zero-based grid row as displayed), "column" (grid col-id), "text" (exact text of the interactive control to use), "nth" (zero-based pick among several matches)}; "text" without "blockId" searches the whole page, which is how confirm dialog / modal footer buttons and dropdown menu items are reached. fill, select and expect.text need a blockId. Each step gets 5s; after an interaction the runner waits for the page\'s pending events and requests to settle.'
           ),
         user: userSchema,
         urlQuery: z

package/lib/docs/getOverview.js

@@ -71,7 +71,7 @@ function getOverview() {
     '   Or subscribe instead of polling: `GET /lowdefy-docs/events` streams `build`, `client_error`, `server_error` and `restart` events over SSE (MCP clients receive the same as `notifications/message` from logger `lowdefy`).',
     '2. **Verify the page**: `GET /lowdefy-docs/page-config/{pageId}` — or `lowdefy_get_page_config`. The fully built page config, or its structured build errors.',
     '3. **See it rendered**: `GET /lowdefy-docs/screenshot/{pageId}` — or `lowdefy_screenshot_page`. PNG of the page in headless Chromium.',
-    '4. **Verify behaviour**: `POST /lowdefy-docs/journey` `{pageId, steps, user, urlQuery}` — or `lowdefy_run_journey`. Drive the page headless with declarative steps (`click`, `fill`, `select`, `press`, `wait`, `screenshot`, `expect: { state | visible | text | url }`, blocks addressed by blockId) and assert what happens. A failing step stops the journey and returns `passed: false` with `failure: { index, step, expected, actual, message }` and the final page `state` — data, not an error.',
+    '4. **Verify behaviour**: `POST /lowdefy-docs/journey` `{pageId, steps, user, urlQuery}` — or `lowdefy_run_journey`. Drive the page headless with declarative steps (`click`, `fill`, `select`, `press`, `wait`, `screenshot`, `expect: { state | visible | text | url }`) and assert what happens. Targets are a blockId, or `{ blockId, row, column, text, nth }` to reach the button in a grid cell, a control by its exact text, or — with `text` alone — a confirm dialog / modal footer button rendered outside every block. A failing step stops the journey and returns `passed: false` with `failure: { index, step, expected, actual, message }` and the final page `state` — data, not an error.',
     '5. **Locate config**: `GET /lowdefy-docs/find/{id}?pageId=...` — or `lowdefy_find_config`. Which yaml file defines a page/block/request id.',
     '6. **Scaffold**: `lowdefy_scaffold_page` creates a canonical new page file (then register it in lowdefy.yaml).',
     '',