@lowdefy/server-dev 5.6.0 → 6.1.0

package/lib/docs/formatFeedback.js

@@ -0,0 +1,121 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+// Turns one or more enriched feedback batches (after enrichFeedback.js has
+// attached `annotation.location`) into a single agent-readable text block.
+// The overlay copies this text to the developer's clipboard — they paste it
+// into their agent session. Kept as a pure string formatter — no
+// build-artifact access.
+function formatFeedback({ items }) {
+  if (type.isNone(items) || items.length === 0) {
+    return 'No pending feedback. The developer has not submitted any annotations yet.';
+  }
+  return items.map(formatBatch).join('\n\n---\n\n');
+}
+
+function formatBatch(batch) {
+  const viewport = batch.viewport ?? {};
+  const lines = [
+    `Feedback: ${batch.annotations?.length ?? 0} annotation(s) on page "${batch.pageId}" ` +
+      `(${batch.url ?? 'unknown url'}) — viewport ${viewport.width}x${viewport.height} ` +
+      `@${viewport.dpr ?? 1}x, scrollY ${viewport.scrollY ?? 0}`,
+    '',
+  ];
+
+  (batch.annotations ?? []).forEach((annotation, index) => {
+    lines.push(formatAnnotation({ annotation, index }));
+  });
+
+  if (batch.screenshotPath) {
+    lines.push('');
+    lines.push(`Annotated screenshot: ${batch.screenshotPath} (read this image to see the drawings)`);
+  }
+
+  lines.push('');
+  lines.push(
+    `For the page's live state call lowdefy_inspect_state({ pageId: "${batch.pageId}" }).`
+  );
+
+  return lines.join('\n');
+}
+
+function formatAnnotation({ annotation, index }) {
+  const lines = [];
+  const num = index + 1;
+  const locationText = formatLocation(annotation.location);
+
+  if (annotation.kind === 'element' && annotation.target) {
+    const header = locationText
+      ? `${num}. Element "${annotation.target.blockId}" (${locationText})`
+      : `${num}. Element "${annotation.target.blockId}"`;
+    lines.push(header);
+    if (annotation.target.ancestorBlockIds?.length > 0) {
+      lines.push(`   Ancestors: ${annotation.target.ancestorBlockIds.join(' > ')}`);
+    }
+    if (annotation.target.tag) {
+      const text = annotation.target.text ? ` "${annotation.target.text}"` : '';
+      lines.push(`   Tag: ${annotation.target.tag}${text}`);
+    }
+  } else {
+    lines.push(`${num}. Region`);
+  }
+
+  lines.push(`   Comment: ${annotation.comment}`);
+
+  const shapesSummary = summarizeShapes({
+    shapes: annotation.geometry?.shapes,
+    hasElementRect: !type.isNone(annotation.geometry?.elementRect),
+  });
+  if (shapesSummary) {
+    lines.push(`   Shapes: ${shapesSummary}`);
+  }
+
+  return lines.join('\n');
+}
+
+function formatLocation(location) {
+  if (type.isNone(location)) {
+    return null;
+  }
+  if (location.source && location.resolvedVia) {
+    return `generated at runtime — defined via ancestor "${location.resolvedVia}": ${location.source}`;
+  }
+  return location.source ?? location.note ?? null;
+}
+
+// Counts shapes by type (rect/arrow/freehand) preserving first-seen order,
+// e.g. "1 rect around the element, 1 arrow" — the first counted type is
+// attributed to the targeted element when the annotation carries an
+// elementRect, since that is the shape drawn to select it.
+function summarizeShapes({ shapes, hasElementRect }) {
+  if (!shapes || shapes.length === 0) {
+    return null;
+  }
+  const counts = new Map();
+  shapes.forEach((shape) => {
+    counts.set(shape.type, (counts.get(shape.type) ?? 0) + 1);
+  });
+  return Array.from(counts.entries())
+    .map(([shapeType, shapeCount], index) => {
+      const label = `${shapeCount} ${shapeType}${shapeCount > 1 ? 's' : ''}`;
+      return index === 0 && hasElementRect ? `${label} around the element` : label;
+    })
+    .join(', ');
+}
+
+export default formatFeedback;

package/lib/docs/formatFeedback.test.mjs

@@ -0,0 +1,204 @@
+/*
+  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';
+
+const mockFindConfig = jest.fn();
+jest.unstable_mockModule('./findConfig.js', () => ({
+  default: mockFindConfig,
+}));
+
+const { default: enrichFeedback } = await import('./enrichFeedback.js');
+const { default: formatFeedback } = await import('./formatFeedback.js');
+
+beforeEach(() => {
+  mockFindConfig.mockReset();
+});
+
+// --- enrichFeedback ---
+
+test('enrichFeedback attaches a location to annotations with a target blockId', async () => {
+  mockFindConfig.mockResolvedValue({
+    matches: [
+      {
+        keyPath: 'root.pages[0:login].blocks[2:submit_button:Button]',
+        location: {
+          source: 'pages/login.yaml:12',
+          config: 'root.pages[0:login].blocks[2:submit_button:Button]',
+        },
+      },
+    ],
+  });
+  const batch = {
+    pageId: 'login',
+    annotations: [
+      {
+        id: '1',
+        kind: 'element',
+        comment: 'too small',
+        target: {
+          blockId: 'submit_button',
+          ancestorBlockIds: ['submit_button', 'login_form'],
+          tag: 'BUTTON',
+          text: 'Submit',
+        },
+        geometry: { elementRect: { x: 220, y: 480, width: 96, height: 40 }, shapes: [] },
+      },
+    ],
+  };
+
+  const enriched = await enrichFeedback({ batch });
+
+  expect(mockFindConfig).toHaveBeenCalledWith({ id: 'submit_button', pageId: 'login' });
+  expect(enriched.annotations[0].location).toEqual({
+    source: 'pages/login.yaml:12',
+    config: 'root.pages[0:login].blocks[2:submit_button:Button]',
+  });
+});
+
+test('enrichFeedback attaches a note when findConfig finds no matches', async () => {
+  mockFindConfig.mockResolvedValue({
+    matches: [],
+    note: 'Block is generated at runtime — no configured ancestor found on page "login".',
+  });
+  const batch = {
+    pageId: 'login',
+    annotations: [{ id: '1', kind: 'element', comment: 'x', target: { blockId: 'missing' } }],
+  };
+
+  const enriched = await enrichFeedback({ batch });
+
+  expect(enriched.annotations[0].location).toEqual({
+    note: 'Block is generated at runtime — no configured ancestor found on page "login".',
+  });
+});
+
+test('enrichFeedback leaves annotations without a target blockId unchanged', async () => {
+  const batch = {
+    pageId: 'login',
+    annotations: [{ id: '1', kind: 'region', comment: 'x', target: null }],
+  };
+
+  const enriched = await enrichFeedback({ batch });
+
+  expect(mockFindConfig).not.toHaveBeenCalled();
+  expect(enriched.annotations[0]).toEqual({ id: '1', kind: 'region', comment: 'x', target: null });
+});
+
+test('enrichFeedback still returns the batch when findConfig throws', async () => {
+  mockFindConfig.mockRejectedValue(new Error('boom'));
+  const batch = {
+    pageId: 'login',
+    annotations: [{ id: '1', kind: 'element', comment: 'x', target: { blockId: 'submit_button' } }],
+  };
+
+  const enriched = await enrichFeedback({ batch });
+
+  expect(enriched.annotations).toHaveLength(1);
+  expect(enriched.annotations[0].location.note).toMatch(/Failed to resolve location: boom/);
+});
+
+// --- formatFeedback ---
+
+test('formatFeedback returns a message when there is no pending feedback', () => {
+  expect(formatFeedback({ items: [] })).toMatch(/No pending feedback/);
+});
+
+test('formatFeedback formats an element annotation with location, ancestors, comment, shapes, and screenshot', () => {
+  const items = [
+    {
+      pageId: 'login',
+      url: '/login?x=1',
+      viewport: { width: 1280, height: 720, scrollX: 0, scrollY: 340, dpr: 2 },
+      annotations: [
+        {
+          id: '1',
+          kind: 'element',
+          comment: 'Button is too small on mobile',
+          target: {
+            blockId: 'submit_button',
+            ancestorBlockIds: ['submit_button', 'login_form'],
+            tag: 'BUTTON',
+            text: 'Submit',
+          },
+          geometry: {
+            elementRect: { x: 220, y: 480, width: 96, height: 40 },
+            shapes: [
+              { type: 'rect', points: [] },
+              { type: 'arrow', points: [] },
+            ],
+          },
+          location: {
+            source: 'pages/login.yaml:12',
+            config: 'root.pages[0:login].blocks[2:submit_button:Button]',
+          },
+        },
+      ],
+      screenshotPath: '.lowdefy/annotations/login-test.png',
+    },
+  ];
+
+  const text = formatFeedback({ items });
+
+  expect(text).toContain('1 annotation(s) on page "login"');
+  expect(text).toContain('viewport 1280x720 @2x, scrollY 340');
+  expect(text).toContain('Element "submit_button" (pages/login.yaml:12)');
+  expect(text).toContain('Ancestors: submit_button > login_form');
+  expect(text).toContain('Comment: Button is too small on mobile');
+  expect(text).toContain('1 rect around the element, 1 arrow');
+  expect(text).toContain('Annotated screenshot: .lowdefy/annotations/login-test.png');
+  expect(text).toContain('lowdefy_inspect_state({ pageId: "login" })');
+  expect(text).not.toContain('Console');
+});
+
+test('formatFeedback formats a region annotation without a target', () => {
+  const items = [
+    {
+      pageId: 'home',
+      url: '/home',
+      viewport: { width: 1280, height: 720 },
+      annotations: [
+        {
+          id: '1',
+          kind: 'region',
+          comment: 'Layout looks off here',
+          target: null,
+          geometry: { elementRect: null, shapes: [{ type: 'freehand', points: [] }] },
+        },
+      ],
+    },
+  ];
+
+  const text = formatFeedback({ items });
+
+  expect(text).toContain('1. Region');
+  expect(text).toContain('Comment: Layout looks off here');
+  expect(text).toContain('1 freehand');
+});
+
+test('formatFeedback multiple batches are joined and each keeps its own pageId in instructions', () => {
+  const items = [
+    { pageId: 'login', url: '/login', viewport: { width: 100, height: 100 }, annotations: [] },
+    { pageId: 'home', url: '/home', viewport: { width: 100, height: 100 }, annotations: [] },
+  ];
+
+  const text = formatFeedback({ items });
+
+  expect(text).toContain('page "login"');
+  expect(text).toContain('page "home"');
+  expect(text).toContain('lowdefy_inspect_state({ pageId: "login" })');
+  expect(text).toContain('lowdefy_inspect_state({ pageId: "home" })');
+});

package/lib/docs/getAppMap.js

@@ -0,0 +1,180 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+import readBuildArtifact from './readBuildArtifact.js';
+
+// Recursively counts blocks on a page, including blocks nested in slots
+// (packages/build/src/build/buildPages/buildBlock/moveAreasToSlots.js moves
+// "areas" to "slots" during build, so built page artifacts only ever have
+// "slots").
+function countBlocks(blocks, types) {
+  let count = 0;
+  (blocks ?? []).forEach((block) => {
+    count += 1;
+    if (block.type) {
+      types.add(block.type);
+    }
+    Object.values(block.slots ?? {}).forEach((slot) => {
+      count += countBlocks(slot?.blocks, types);
+    });
+  });
+  return count;
+}
+
+function summarizeBlocks(blocks) {
+  const types = new Set();
+  const blockCount = countBlocks(blocks, types);
+  return { blockCount, blockTypes: [...types] };
+}
+
+// The request's "type" is stripped from the page artifact by the build
+// (packages/build/src/build/full/writeRequests.js deletes
+// type/connectionId/properties/auth after writing the per-request file), so
+// it is read from the dedicated per-request artifact instead.
+function summarizeRequests({ pageId, requests }) {
+  return (requests ?? []).map((request) => {
+    const requestConfig = readBuildArtifact({
+      name: `pages/${pageId}/requests/${request.requestId}.json`,
+      deserialize: true,
+    });
+    return { id: request.requestId, type: requestConfig?.type ?? null };
+  });
+}
+
+function getPages() {
+  const registry = readBuildArtifact({ name: 'pageRegistry.json' }) ?? {};
+  const pages = [];
+  let unbuiltCount = 0;
+
+  Object.entries(registry).forEach(([pageId, entry]) => {
+    const built = readBuildArtifact({ name: `pages/${pageId}.json`, deserialize: true });
+    const page = {
+      pageId,
+      file: entry.refPath,
+      auth: entry.auth,
+      built: !type.isNone(built),
+    };
+    if (type.isNone(built)) {
+      unbuiltCount += 1;
+    } else {
+      Object.assign(page, summarizeBlocks(built.blocks));
+      page.requests = summarizeRequests({ pageId, requests: built.requests });
+    }
+    pages.push(page);
+  });
+
+  return { pages, unbuiltCount };
+}
+
+// Menu items can nest further links (e.g. MenuGroup), so this recurses; kept
+// to id/type/pageId/title only — no properties/auth noise.
+function summarizeMenuItem(menuItem) {
+  const summary = {
+    menuItemId: menuItem.menuItemId ?? menuItem.id,
+    type: menuItem.type,
+  };
+  if (!type.isNone(menuItem.pageId)) {
+    summary.pageId = menuItem.pageId;
+  }
+  if (!type.isNone(menuItem.properties?.title)) {
+    summary.title = menuItem.properties.title;
+  }
+  if (type.isArray(menuItem.links)) {
+    summary.links = menuItem.links.map(summarizeMenuItem);
+  }
+  return summary;
+}
+
+function getMenus() {
+  const menus = readBuildArtifact({ name: 'menus.json', deserialize: true }) ?? [];
+  return menus.map((menu) => ({
+    menuId: menu.menuId ?? menu.id,
+    links: (menu.links ?? []).map(summarizeMenuItem),
+  }));
+}
+
+function getConnections() {
+  const ids = readBuildArtifact({ name: 'connectionIds.json' }) ?? [];
+  return ids.map((id) => {
+    const connection = readBuildArtifact({ name: `connections/${id}.json`, deserialize: true });
+    return { id, type: connection?.type ?? null };
+  });
+}
+
+// api/ and agents/ have one artifact file per id and no id manifest (unlike
+// connectionIds.json / websocketIds.json), so their ids come from a
+// directory listing instead of readBuildArtifact.
+function listArtifactIds({ buildDirectory, dirName }) {
+  const dirPath = path.join(buildDirectory, dirName);
+  if (!fs.existsSync(dirPath)) {
+    return [];
+  }
+  return fs
+    .readdirSync(dirPath)
+    .filter((filename) => filename.endsWith('.json'))
+    .map((filename) => filename.slice(0, -'.json'.length));
+}
+
+function getEndpoints({ buildDirectory }) {
+  return listArtifactIds({ buildDirectory, dirName: 'api' }).map((id) => {
+    const endpoint = readBuildArtifact({ name: `api/${id}.json`, deserialize: true });
+    return { id, type: endpoint?.type ?? null };
+  });
+}
+
+function getAgents({ buildDirectory }) {
+  return listArtifactIds({ buildDirectory, dirName: 'agents' }).map((id) => {
+    const agent = readBuildArtifact({ name: `agents/${id}.json`, deserialize: true });
+    return { id, type: agent?.type ?? null };
+  });
+}
+
+function getWebsockets() {
+  return readBuildArtifact({ name: 'websocketIds.json' }) ?? [];
+}
+
+// Compact snapshot of the whole app for an agent to orient itself: every
+// page (with block/request detail only for pages that have a built
+// artifact — pages are JIT-built on first visit, see lib/docs/getPageConfig.js),
+// menus, connections, api endpoints, agents and websockets.
+function getAppMap() {
+  const buildDirectory = path.join(process.cwd(), 'build');
+  const { pages, unbuiltCount } = getPages();
+
+  const map = {
+    pages,
+    menus: getMenus(),
+    connections: getConnections(),
+    endpoints: getEndpoints({ buildDirectory }),
+    agents: getAgents({ buildDirectory }),
+    websockets: getWebsockets(),
+  };
+
+  if (unbuiltCount > 0) {
+    map.note =
+      `${unbuiltCount} page(s) have not been built yet, so only "file" and "auth" are shown ` +
+      'for them. Visit the page in the browser, or GET /lowdefy-docs/page/{pageId}, to trigger ' +
+      'a build and see their blocks and requests.';
+  }
+
+  return map;
+}
+
+export default getAppMap;

package/lib/docs/getBrowser.js

@@ -0,0 +1,127 @@
+/*
+  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 { chromium } from 'playwright-core';
+import { type } from '@lowdefy/helpers';
+
+import lowdefyConfig from '../build/config.js';
+import { HEADLESS_USER_COOKIE } from '../server/auth/headlessUser.js';
+import resolveHeadlessUser from '../server/auth/resolveHeadlessUser.js';
+
+// playwright-core does not bundle a browser (unlike @playwright/test) — it
+// only drives one that is already installed. `channel: 'chrome'` picks up a
+// system Chrome install first since that's more likely to already be
+// present than a Playwright-managed Chromium in a dev environment.
+async function launchBrowser() {
+  try {
+    return await chromium.launch({ channel: 'chrome' });
+  } catch {
+    return await chromium.launch();
+  }
+}
+
+// Module-level singleton — a browser process is expensive to start, so it is
+// launched once and reused across every headless caller (screenshots, state
+// inspection, operator evaluation). Cached as a promise so concurrent calls
+// awaiting startup share the same launch instead of racing.
+let browserPromise = null;
+
+async function getBrowser() {
+  if (type.isNone(browserPromise)) {
+    // Clear the cache on failure so the next call retries the launch
+    // instead of replaying a cached rejection forever.
+    browserPromise = launchBrowser().catch((error) => {
+      browserPromise = null;
+      throw error;
+    });
+  }
+  let browser = await browserPromise;
+  if (!browser.isConnected()) {
+    browserPromise = launchBrowser().catch((error) => {
+      browserPromise = null;
+      throw error;
+    });
+    browser = await browserPromise;
+  }
+  return browser;
+}
+
+// `origin` should already include any configured basePath prefix that the
+// caller can't derive itself (e.g. from a request URL) — here it's read from
+// build/config.json (the same source app.js uses to mount the app) so
+// callers only need to pass the bare origin.
+function buildPageUrl({ origin, pageId }) {
+  const basePath = lowdefyConfig.basePath ?? '';
+  return `${origin}${basePath}/${pageId}`;
+}
+
+// Opens a fresh browser context + page at the app's pageId route. Callers
+// obtain `browser` via getBrowser() themselves so they can map a launch
+// failure to their own "no browser available" error message, separate from
+// navigation failures.
+async function openPage({
+  browser,
+  origin,
+  pageId,
+  user,
+  width = 1280,
+  height = 800,
+  timeout = 15000,
+}) {
+  const url = buildPageUrl({ origin, pageId });
+  // Resolved before the context is created so an invalid `user` can't leave an
+  // orphaned context behind.
+  const injectedUser = resolveHeadlessUser({ user });
+  const context = await browser.newContext({ viewport: { width, height } });
+  // Inject an authenticated user so auth-protected pages don't 404 for the
+  // cookieless headless context. Mirrors the e2e user-cookie pattern; scoped to
+  // `origin` so it rides along on the same-origin /api/* fetches.
+  await context.addCookies([
+    {
+      name: HEADLESS_USER_COOKIE,
+      value: Buffer.from(JSON.stringify(injectedUser)).toString('base64'),
+      url: origin,
+    },
+  ]);
+  const page = await context.newPage();
+  try {
+    await page.goto(url, { waitUntil: 'networkidle', timeout });
+  } catch {
+    // Pages with long-polling/SSE connections (reload, websockets) never
+    // go network-idle — fall back to 'load' rather than failing outright.
+    await page.goto(url, { waitUntil: 'load', timeout });
+  }
+  // The engine builds the page context (and runs onInit + initial requests)
+  // after the bundle loads — 'load'/'networkidle' fire before that. Every
+  // caller (screenshot, inspect, eval, checkpoint load) needs the app
+  // actually mounted, so wait for the context and for initial requests to
+  // settle. Tolerant: on timeout proceed and let the caller surface what it
+  // finds — a screenshot of a hung page is still useful signal.
+  await page
+    .waitForFunction(
+      (id) => {
+        const pageContext = window.lowdefy?.contexts?.[`page:${id}`];
+        if (!pageContext) return false;
+        return !Object.values(pageContext.requests ?? {}).some((calls) => calls?.[0]?.loading);
+      },
+      pageId,
+      { timeout }
+    )
+    .catch(() => {});
+  return { context, page, url };
+}
+
+export { getBrowser, openPage, buildPageUrl };