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

package/lib/docs/formatFeedback.js

@@ -1,121 +0,0 @@
-/*
-  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

@@ -1,204 +0,0 @@
-/*
-  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

@@ -1,180 +0,0 @@
-/*
-  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

@@ -1,115 +0,0 @@
-/*
-  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, headlessUser } from '../server/auth/headlessUser.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, width = 1280, height = 800, timeout = 15000 }) {
-  const url = buildPageUrl({ origin, pageId });
-  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(headlessUser)).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 };

package/lib/docs/getBuildStatus.js

@@ -1,37 +0,0 @@
-/*
-  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 clientErrorStore from './clientErrorStore.js';
-import readBuildArtifact from './readBuildArtifact.js';
-
-// Feedback loop for agents: build status (written by the build manager to
-// build/buildStatus.json) plus recent browser errors reported via
-// POST /api/client-error. Lets an agent check "did my last edit work?"
-// without tailing terminal logs.
-function getBuildStatus() {
-  const build = readBuildArtifact({ name: 'buildStatus.json' }) ?? {
-    status: 'unknown',
-    message:
-      'No build status yet — the build manager has not written build/buildStatus.json. ' +
-      'This is expected before the first build completes.',
-  };
-  return {
-    build,
-    clientErrors: clientErrorStore.list(),
-  };
-}
-
-export default getBuildStatus;