@lowdefy/server-dev 5.5.1 → 6.0.0

package/client/feedback/pinResponsiveImages.js

@@ -0,0 +1,59 @@
+/*
+  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.
+*/
+
+// html-to-image embeds img.src and clones srcset/<source> attributes as-is:
+// the selection the browser actually displays (img.currentSrc) is ignored, so
+// a <picture> rasterizes its fallback src stretched into the displayed box
+// (e.g. the PageHeaderMenu square logo warped into the wordmark's slot), and
+// remote srcset candidates can't load inside the sandboxed SVG rasterization
+// anyway. Pin every responsive image to its currentSrc for the capture — the
+// URL the tab already displays, so nothing changes visually — and return a
+// restore function for the caller's finally block.
+function pinResponsiveImages() {
+  const restores = [];
+
+  document.querySelectorAll('img').forEach((img) => {
+    const isResponsive =
+      img.hasAttribute('srcset') || (img.currentSrc && img.currentSrc !== img.src);
+    if (!img.currentSrc || !isResponsive) return;
+    const src = img.getAttribute('src');
+    const srcset = img.getAttribute('srcset');
+    restores.push(() => {
+      if (src === null) {
+        img.removeAttribute('src');
+      } else {
+        img.setAttribute('src', src);
+      }
+      if (srcset !== null) {
+        img.setAttribute('srcset', srcset);
+      }
+    });
+    img.setAttribute('src', img.currentSrc);
+    img.removeAttribute('srcset');
+  });
+
+  document.querySelectorAll('picture > source[srcset]').forEach((source) => {
+    const srcset = source.getAttribute('srcset');
+    restores.push(() => source.setAttribute('srcset', srcset));
+    source.removeAttribute('srcset');
+  });
+
+  return function restore() {
+    restores.forEach((fn) => fn());
+  };
+}
+
+export default pinResponsiveImages;

package/client/feedback/sendFeedback.js

@@ -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.
+*/
+
+// Sends the batch to the dev server for enrichment (blockId → yaml file:line
+// via the build's keyMap) and gets back the formatted, agent-readable text.
+// Best-effort, matching Inspector.jsx's postResult style — a dev-only feature
+// must never throw into the app it rides along with. Returns the formatted
+// string, or null on any failure.
+async function sendFeedback({ basePath, batch }) {
+  try {
+    const response = await fetch(`${basePath}/lowdefy-feedback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(batch),
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    return typeof data.formatted === 'string' ? data.formatted : null;
+  } catch {
+    return null;
+  }
+}
+
+export default sendFeedback;

package/client/feedback/useFeedbackToggle.js

@@ -0,0 +1,70 @@
+/*
+  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 { tinykeys } from 'tinykeys';
+
+// Binds the global Cmd/Ctrl+/ feedback toggle, matching the app's own
+// shortcut convention (see createShortcutManager.js): tinykeys on window,
+// "$mod" for the platform modifier. Registered at capture phase with
+// stopImmediatePropagation so the app's own shortcut manager (or any block
+// event bound to the same key) never also fires.
+function useFeedbackToggle({ onToggle }) {
+  const onToggleRef = useRef(onToggle);
+  onToggleRef.current = onToggle;
+
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return undefined;
+    }
+
+    let unsubscribe;
+    try {
+      unsubscribe = tinykeys(
+        window,
+        {
+          '$mod+Slash': (event) => {
+            try {
+              event.preventDefault();
+              event.stopImmediatePropagation();
+              if (onToggleRef.current) {
+                onToggleRef.current();
+              }
+            } catch {
+              // Never let the toggle handler crash the app.
+            }
+          },
+        },
+        { capture: true }
+      );
+    } catch {
+      // tinykeys unavailable or binding failed — the feature just won't toggle.
+    }
+
+    return () => {
+      try {
+        if (unsubscribe) {
+          unsubscribe();
+        }
+      } catch {
+        // no-op
+      }
+    };
+  }, []);
+}
+
+export default useFeedbackToggle;

package/client/main.jsx

@@ -0,0 +1,42 @@
+/*
+  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.
+*/
+
+// CSS layer order — MUST be the first CSS import. This locks the cascade
+// priority (antd > base/preflight) before antd's StyleProvider injects
+// @layer antd {} at runtime. Vite's PostCSS pipeline compiles globals.css
+// (Tailwind) on the fly and hot-replaces it — the old tailwind-jit.css
+// side-channel is gone.
+import '../build/layer-order.css';
+
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import createRouter from '@lowdefy/client/adapters/createRouter.js';
+
+import App from './App.jsx';
+
+import '../build/globals.css';
+
+const config = JSON.parse(document.getElementById('__LOWDEFY_CONFIG__').textContent);
+const router = createRouter({ basePath: config.basePath ?? '', window });
+const container = document.getElementById('root');
+
+// Keep one React root across Vite HMR updates.
+const root = import.meta.hot?.data.root ?? createRoot(container);
+if (import.meta.hot) {
+  import.meta.hot.data.root = root;
+}
+
+root.render(<App config={config} router={router} />);

package/client/openInEditor/OpenInEditorListener.jsx

@@ -0,0 +1,268 @@
+/*
+  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, { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { blockAncestorChain, nearestBlock } from '../feedback/elementInspect.js';
+import { highlightBox, labelChip, overlayContainer } from '../feedback/feedbackStyles.js';
+import findBlockLocation from './findBlockLocation.js';
+
+const STYLE_TAG_ID = 'lowdefy-open-in-editor-style-tag';
+const BODY_CLASS = 'lowdefy-open-in-editor-target';
+
+// Cursor over arbitrary app descendants can't be forced from inline styles —
+// same trick as feedbackStyles' picking/drawing classes.
+function injectStyleTag() {
+  if (typeof document === 'undefined' || document.getElementById(STYLE_TAG_ID)) {
+    return;
+  }
+  const style = document.createElement('style');
+  style.id = STYLE_TAG_ID;
+  style.textContent = `
+    .${BODY_CLASS}, .${BODY_CLASS} * {
+      cursor: pointer !important;
+    }
+  `;
+  document.head.appendChild(style);
+}
+
+function removeStyleTag() {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  document.getElementById(STYLE_TAG_ID)?.remove();
+}
+
+// The feedback overlay owns clicks while it is open (its picking mode claims
+// them) — the Option/Alt+click shortcut stays out of the way until it closes.
+// :not() skips this component's own highlight portal, which carries
+// data-lowdefy-feedback purely for screenshot/picking exclusion.
+function feedbackOverlayOpen() {
+  return Boolean(
+    document.querySelector('[data-lowdefy-feedback]:not([data-lowdefy-open-in-editor])')
+  );
+}
+
+// Option (macOS) / Alt (Windows, Linux) alone is the shortcut. Cmd/Ctrl are left
+// to the browser (open link in new tab) and Shift to text selection, so any of
+// them held alongside means the developer wants the browser's behaviour.
+function isOpenModifier(event) {
+  return event.altKey && !event.metaKey && !event.ctrlKey && !event.shiftKey;
+}
+
+// Dev-only: Option/Alt+click any element to open the YAML that defines its
+// block in VS Code (vscode://file deep link, at the exact line). While the
+// modifier is held, the hovered block shows the same blue highlight box and
+// blockId chip as the annotation overlay's picking mode, and the cursor
+// switches to a pointer — so the developer sees exactly what a click will
+// open. Mounted always-on from Routing.jsx alongside Inspector and
+// FeedbackMount, and follows their resilience contract — every handler is
+// try/caught so this can never take the app down with it.
+//
+// The click resolves the nearest block and, when that id is generated at
+// runtime (list items, Dynamic endpoints), falls back through the ancestor
+// block chain until an id resolves in config — the same strategy the
+// feedback pipeline uses in enrichFeedback.js.
+function OpenInEditorListener({ basePath, pageId }) {
+  const [hoverBlock, setHoverBlock] = useState(null); // { blockId, rect }
+  // Refs keep the freshest values without re-binding the capture listeners
+  // on every SPA navigation or hover change.
+  const pageIdRef = useRef(pageId);
+  pageIdRef.current = pageId;
+  const hoverRef = useRef(hoverBlock);
+  hoverRef.current = hoverBlock;
+  const lastPointerRef = useRef(null); // { x, y }
+
+  // Style tag lifecycle — the listener is always mounted, so this lives for
+  // the app's lifetime and only the body class toggles per hover.
+  useEffect(() => {
+    injectStyleTag();
+    return () => removeStyleTag();
+  }, []);
+
+  // Pointer cursor only while a block is highlighted — over non-block areas
+  // the cursor stays native, signalling the click would do nothing.
+  useEffect(() => {
+    try {
+      document.body.classList.toggle(BODY_CLASS, Boolean(hoverBlock));
+    } catch {
+      // no-op
+    }
+    return () => {
+      try {
+        document.body.classList.remove(BODY_CLASS);
+      } catch {
+        // no-op
+      }
+    };
+  }, [hoverBlock]);
+
+  useEffect(() => {
+    function clearHover() {
+      if (hoverRef.current) {
+        setHoverBlock(null);
+      }
+    }
+
+    function resolveHover() {
+      try {
+        const point = lastPointerRef.current;
+        if (!point || feedbackOverlayOpen()) {
+          clearHover();
+          return;
+        }
+        const el = document.elementFromPoint(point.x, point.y);
+        const blockId = nearestBlock(el);
+        const blockEl = blockId ? document.getElementById(`bl-${blockId}`) : null;
+        if (!blockEl) {
+          clearHover();
+          return;
+        }
+        const rect = blockEl.getBoundingClientRect();
+        setHoverBlock({
+          blockId,
+          rect: { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+        });
+      } catch {
+        clearHover();
+      }
+    }
+
+    function onPointerMove(event) {
+      try {
+        lastPointerRef.current = { x: event.clientX, y: event.clientY };
+        if (isOpenModifier(event)) {
+          resolveHover();
+        } else {
+          clearHover();
+        }
+      } catch {
+        // Best-effort hover tracking.
+      }
+    }
+
+    // Modifier pressed/released while the mouse is stationary — pointermove
+    // alone would leave the highlight stale.
+    function onKeyDown(event) {
+      if (event.key === 'Alt') {
+        resolveHover();
+      }
+    }
+
+    function onKeyUp(event) {
+      if (event.key === 'Alt') {
+        clearHover();
+      }
+    }
+
+    // Switching apps releases the modifier without a keyup reaching the page.
+    function onBlur() {
+      clearHover();
+    }
+
+    // Keep the highlight glued to the block while the app scrolls under a
+    // stationary cursor.
+    function onScroll() {
+      if (hoverRef.current) {
+        resolveHover();
+      }
+    }
+
+    async function openBlockInEditor({ candidates }) {
+      for (const blockId of candidates) {
+        const location = await findBlockLocation({
+          basePath,
+          blockId,
+          pageId: pageIdRef.current,
+        });
+        if (location) {
+          window.location.assign(`vscode://file${location.file}:${location.line}`);
+          return;
+        }
+      }
+      try {
+        // eslint-disable-next-line no-console
+        console.info(
+          `Lowdefy: no config location found for "${candidates[0]}" — the block is generated at runtime.`
+        );
+      } catch {
+        // no-op
+      }
+    }
+
+    function onClickCapture(event) {
+      try {
+        if (!isOpenModifier(event)) {
+          return;
+        }
+        if (feedbackOverlayOpen()) {
+          return;
+        }
+        const candidates = blockAncestorChain(event.target);
+        if (candidates.length === 0) {
+          return;
+        }
+        // Only claim the click once a block is under the cursor — plain
+        // Option/Alt+clicks elsewhere keep their default behaviour.
+        event.preventDefault();
+        event.stopPropagation();
+        void openBlockInEditor({ candidates });
+      } catch {
+        // Never let the shortcut break the developer's app.
+      }
+    }
+
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    window.addEventListener('blur', onBlur);
+    window.addEventListener('scroll', onScroll, true);
+    window.addEventListener('click', onClickCapture, { capture: true });
+    return () => {
+      window.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+      window.removeEventListener('blur', onBlur);
+      window.removeEventListener('scroll', onScroll, true);
+      window.removeEventListener('click', onClickCapture, { capture: true });
+    };
+  }, [basePath]);
+
+  if (!hoverBlock || typeof document === 'undefined' || !document.body) {
+    return null;
+  }
+  // data-lowdefy-feedback keeps this out of the annotation overlay's element
+  // picking and out of tab-captured screenshots (both exclude that root).
+  return createPortal(
+    <div data-lowdefy-feedback data-lowdefy-open-in-editor style={overlayContainer}>
+      <div
+        style={{
+          ...highlightBox,
+          top: hoverBlock.rect.top,
+          left: hoverBlock.rect.left,
+          width: hoverBlock.rect.width,
+          height: hoverBlock.rect.height,
+        }}
+      >
+        <span style={labelChip}>{hoverBlock.blockId}</span>
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+export default OpenInEditorListener;

package/client/openInEditor/findBlockLocation.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.
+*/
+
+// Resolves a blockId to its YAML source via the dev server's existing
+// GET /lowdefy-docs/find/{id}?pageId= route (which JIT-builds the page's
+// keyMap on demand). Returns { file, line } with an absolute file path, or
+// null when the id has no configured location. Best-effort, matching
+// sendFeedback.js — a dev-only feature must never throw into the app.
+async function findBlockLocation({ basePath, blockId, pageId }) {
+  try {
+    // Omit pageId when unknown — an empty ?pageId= reads as an unknown page
+    // on the server, while no param falls back to scanning all built pages.
+    const query = pageId ? `?pageId=${encodeURIComponent(pageId)}` : '';
+    const response = await fetch(
+      `${basePath}/lowdefy-docs/find/${encodeURIComponent(blockId)}${query}`
+    );
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    const source = data.matches?.[0]?.location?.source;
+    if (typeof source !== 'string' || source.length === 0) {
+      return null;
+    }
+    // source is "<absolute path>" or "<absolute path>:<line>" — a numeric
+    // suffix after the last colon is the 1-based line number. Splitting on
+    // the last colon keeps Windows drive-letter colons intact.
+    const match = source.match(/^(.*):(\d+)$/);
+    if (match) {
+      return { file: match[1], line: Number(match[2]) };
+    }
+    return { file: source, line: 1 };
+  } catch {
+    return null;
+  }
+}
+
+export default findBlockLocation;

package/lib/build/app.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/app.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/app.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/appMeta.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/appMeta.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/appMeta.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/auth.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/auth.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/auth.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/config.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/config.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/config.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/i18n.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/i18n.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/i18n.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/logger.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/logger.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/logger.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

package/lib/build/theme.js

@@ -13,7 +13,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
+// Build artifacts are read from disk because the Hono server runs as
+// unbundled Node.js ESM — JSON imports would need import attributes, and
+// client code imports the build JSON directly through Vite instead.
+import fs from 'node:fs';
+import path from 'node:path';
 import { serializer } from '@lowdefy/helpers';
-import raw from '../../build/theme.json';
+
+const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'build/theme.json'), 'utf8'));
 
 export default serializer.deserialize(raw);

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

@@ -13,13 +13,22 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */
+
 /* eslint-disable react/jsx-props-no-spreading */
 
 import React from 'react';
-import AuthConfigured from './AuthConfigured.js';
+import AuthConfigured from './AuthConfigured.jsx';
 import AuthNotConfigured from './AuthNotConfigured.js';
 
-import authConfig from '../../build/auth.js';
+import { serializer } from '@lowdefy/helpers';
+
+// Client code imports the build JSON directly — Vite handles JSON imports;
+// the lib/build/*.js wrappers are server-only (they read from disk).
+// Deserialize to restore arrays from their ~arr build markers (providers
+// must be a real array for single-provider inference in createAuthMethods).
+import rawAuthConfig from '../../../build/auth.json';
+
+const authConfig = serializer.deserialize(rawAuthConfig);
 
 function Auth({ children, session }) {
   if (authConfig.configured === true) {