@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/formatFeedback.js

@@ -28,10 +28,31 @@ function formatFeedback({ items }) {
   return items.map(formatBatch).join('\n\n---\n\n');
 }
 
+// A page with placeholders in its path names the instance by its values.
+function hasPathParams(batch) {
+  return Object.keys(batch.pathParams ?? {}).length > 0;
+}
+
+function describePage(batch) {
+  if (!hasPathParams(batch)) {
+    return `page "${batch.pageId}"`;
+  }
+  return `page "${batch.pageId}" with pathParams ${JSON.stringify(batch.pathParams)}`;
+}
+
+function inspectStateCall(batch) {
+  if (!hasPathParams(batch)) {
+    return `lowdefy_inspect_state({ pageId: "${batch.pageId}" })`;
+  }
+  return `lowdefy_inspect_state({ pageId: "${batch.pageId}", pathParams: ${JSON.stringify(
+    batch.pathParams
+  )} })`;
+}
+
 function formatBatch(batch) {
   const viewport = batch.viewport ?? {};
   const lines = [
-    `Feedback: ${batch.annotations?.length ?? 0} annotation(s) on page "${batch.pageId}" ` +
+    `Feedback: ${batch.annotations?.length ?? 0} annotation(s) on ${describePage(batch)} ` +
       `(${batch.url ?? 'unknown url'}) — viewport ${viewport.width}x${viewport.height} ` +
       `@${viewport.dpr ?? 1}x, scrollY ${viewport.scrollY ?? 0}`,
     '',
@@ -43,13 +64,13 @@ function formatBatch(batch) {
 
   if (batch.screenshotPath) {
     lines.push('');
-    lines.push(`Annotated screenshot: ${batch.screenshotPath} (read this image to see the drawings)`);
+    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}" }).`
-  );
+  lines.push(`For the page's live state call ${inspectStateCall(batch)}.`);
 
   return lines.join('\n');
 }

package/lib/docs/formatFeedback.test.mjs

@@ -202,3 +202,51 @@ test('formatFeedback multiple batches are joined and each keeps its own pageId i
   expect(text).toContain('lowdefy_inspect_state({ pageId: "login" })');
   expect(text).toContain('lowdefy_inspect_state({ pageId: "home" })');
 });
+
+test('formatFeedback names the page instance by its pathParams', () => {
+  const text = formatFeedback({
+    items: [
+      {
+        pageId: 'ticket',
+        pathParams: { space: 's', ticket_id: '1' },
+        url: '/tickets/s/1',
+        viewport: { width: 100, height: 100 },
+        annotations: [],
+      },
+    ],
+  });
+  expect(text).toContain(
+    'Feedback: 0 annotation(s) on page "ticket" with pathParams {"space":"s","ticket_id":"1"} (/tickets/s/1)'
+  );
+  expect(text).toContain(
+    'lowdefy_inspect_state({ pageId: "ticket", pathParams: {"space":"s","ticket_id":"1"} })'
+  );
+});
+
+test('formatFeedback leaves empty pathParams out', () => {
+  const text = formatFeedback({
+    items: [
+      {
+        pageId: 'home',
+        pathParams: {},
+        url: '/home',
+        viewport: { width: 100, height: 100 },
+        annotations: [],
+      },
+    ],
+  });
+  expect(text).toContain('Feedback: 0 annotation(s) on page "home" (/home)');
+  expect(text).toContain('lowdefy_inspect_state({ pageId: "home" })');
+});
+
+test('enrichFeedback keeps the batch pathParams', async () => {
+  const enriched = await enrichFeedback({
+    batch: {
+      pageId: 'ticket',
+      pathParams: { space: 's', ticket_id: '1' },
+      urlQuery: '',
+      annotations: [],
+    },
+  });
+  expect(enriched.pathParams).toEqual({ space: 's', ticket_id: '1' });
+});

package/lib/docs/getAppMap.js

@@ -58,8 +58,13 @@ function summarizeRequests({ pageId, requests }) {
   });
 }
 
+// A page's `path` is the URL pattern it is served at (its id when it declares
+// none). A pattern with placeholders, e.g. "tickets/{space}/{ticket_id}", needs
+// `pathParams` to open in the page tools.
 function getPages() {
   const registry = readBuildArtifact({ name: 'pageRegistry.json' }) ?? {};
+  const routes = readBuildArtifact({ name: 'routes.json', deserialize: true });
+  const pathByPageId = new Map(routes.map((route) => [route.pageId, route.path]));
   const pages = [];
   let unbuiltCount = 0;
 
@@ -67,6 +72,7 @@ function getPages() {
     const built = readBuildArtifact({ name: `pages/${pageId}.json`, deserialize: true });
     const page = {
       pageId,
+      path: pathByPageId.get(pageId),
       file: entry.refPath,
       auth: entry.auth,
       built: !type.isNone(built),
@@ -170,7 +176,7 @@ function getAppMap() {
   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 ' +
+      'for them. Visit the page in the browser, or GET /lowdefy-docs/page-config/{pageId}, to trigger ' +
       'a build and see their blocks and requests.';
   }
 

package/lib/docs/getBrowser.js

@@ -14,58 +14,42 @@
   limitations under the License.
 */
 
-import { chromium } from 'playwright-core';
-import { type } from '@lowdefy/helpers';
+import { buildPagePath, type, urlQuery as urlQueryFn } from '@lowdefy/helpers';
 
 import lowdefyConfig from '../build/config.js';
+import createBrowserLifecycle from './createBrowserLifecycle.js';
+import guardJourneyOrigin from './guardJourneyOrigin.js';
+import isPageReady from './isPageReady.js';
+import launchBrowser from './launchBrowser.js';
 import { HEADLESS_USER_COOKIE } from '../server/auth/headlessUser.js';
 import resolveHeadlessUser from '../server/auth/resolveHeadlessUser.js';
+import { JOURNEY_COOKIES, writeJourneyCookie } from '../server/journeyCookies.js';
+import recordingCookiePayload from '../server/recording/recordingCookiePayload.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;
-}
+// Module-level singleton, shared by every headless caller (screenshots,
+// journeys, state inspection, operator evaluation, state loads) and closed
+// after 90 s unused. See createBrowserLifecycle.js.
+const { getBrowser, trackContext } = createBrowserLifecycle({
+  launch: launchBrowser,
+  idleTimeout: 90_000,
+});
 
 // `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 }) {
+// callers only need to pass the bare origin. `urlQuery` (an object) is
+// appended as a query string, serialized by the same helper the engine uses
+// for Link urlQuery, so a page reads it back through _url_query unchanged.
+// `path` is the page's path pattern (readPagePath), filled with `pathParams`
+// by the builder links use; it throws when a placeholder has no value.
+function buildPageUrl({ origin, pageId, path, pathParams, urlQuery }) {
   const basePath = lowdefyConfig.basePath ?? '';
-  return `${origin}${basePath}/${pageId}`;
+  const url = `${origin}${basePath}/${buildPagePath({ pageId, path, pathParams })}`;
+  const query = urlQueryFn.stringify(urlQuery);
+  if (query === '') {
+    return url;
+  }
+  return `${url}?${query}`;
 }
 
 // Opens a fresh browser context + page at the app's pageId route. Callers
@@ -76,52 +60,138 @@ async function openPage({
   browser,
   origin,
   pageId,
+  path,
+  pathParams,
   user,
+  urlQuery,
   width = 1280,
   height = 800,
+  colorScheme = 'light',
+  clientAddress,
+  dataCookie,
+  mutantCookie,
+  recording,
+  onContext,
   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();
+  const url = buildPageUrl({ origin, pageId, path, pathParams, urlQuery });
+  // `none` injects no caller: the context starts signed out and the app's own
+  // auth resolves every request from the session cookies it sets. Otherwise
+  // the user is resolved before the context is created so an invalid `user`
+  // can't leave an orphaned context behind.
+  const injectedUser = user === 'none' ? null : resolveHeadlessUser({ user });
+  // colorScheme is what the page's `prefers-color-scheme` media query reports,
+  // so an app following the system theme renders light or dark accordingly.
+  const context = await browser.newContext({ viewport: { width, height }, colorScheme });
+  trackContext(context);
+  // The URLs a data set journey's context tried to reach on another host of the dev server. Each
+  // was aborted; the journey runner fails the step that caused it.
+  const leftOrigin = [];
+  // From here a failure must close the context before rethrowing: callers only
+  // learn about the context from the return value, so an error thrown mid-open
+  // (a navigation that times out, a crashed page) would otherwise
+  // leak a browser context — and its renderer process — on every failed call.
   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.
+    // A caller that watches the context (a journey's network counter) hooks in
+    // here, before the first request leaves.
+    if (!type.isUndefined(onContext)) {
+      await onContext(context);
+    }
+    // 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. A user the
+    // caller named is explicit: it beats a dev mock user (createLowdefyContext),
+    // while the roleless default does not, so a screenshot under a mock user
+    // still sees what the developer sees.
+    if (injectedUser !== null) {
+      const caller = { user: injectedUser, explicit: !type.isNone(user) };
+      await context.addCookies([
+        {
+          name: HEADLESS_USER_COOKIE,
+          value: Buffer.from(JSON.stringify(caller)).toString('base64'),
+          url: origin,
+        },
+      ]);
+    }
+    // clientAddress is the address the context's requests come from, as far
+    // as the dev server's auth rate limits can tell - see createJourneyActors
+    // and journeyActor.js. A cookie, not a header, so it only reaches the app;
+    // httpOnly, so page JavaScript cannot read the token. Lax, not Strict: a
+    // journey opens an emailed link from a data: URL, a cross-site navigation
+    // that a Strict cookie does not ride, and that one verify request would
+    // then fall back to the shared loopback address (magic-link verify allows
+    // 5 per minute per address).
+    if (!type.isUndefined(clientAddress)) {
+      await context.addCookies([
+        writeJourneyCookie({ name: JOURNEY_COOKIES.actor.name, payload: clientAddress, origin }),
+      ]);
+    }
+    // A journey on a data set: every request from this context reads the data
+    // session's database (see lib/server/applyDataSetRedirect.js), while the
+    // developer's own tabs keep the app's real one. Set before the first
+    // navigation, so no request from this context ever goes without it.
+    if (!type.isUndefined(dataCookie)) {
+      await context.addCookies([
+        writeJourneyCookie({ name: JOURNEY_COOKIES.data.name, payload: dataCookie, origin }),
+      ]);
+      await guardJourneyOrigin({
+        context,
+        origin,
+        onLeave: (departure) => leftOrigin.push(departure),
+      });
+    }
+    // A harden run's mutant: every request from this context reads the mutated
+    // artifact (see lib/server/mutants), while other contexts do not.
+    if (!type.isUndefined(mutantCookie)) {
+      await context.addCookies([
+        writeJourneyCookie({ name: JOURNEY_COOKIES.mutant.name, payload: mutantCookie, origin }),
+      ]);
+    }
+    // Every headless context is marked for the dev recorder: 'off' unless the
+    // caller records a journey run, so screenshots and inspection
+    // never record, and a run's records are labelled by the server, not the
+    // page. See lib/server/recording.
+    await context.addCookies([
+      writeJourneyCookie({
+        name: JOURNEY_COOKIES.recording.name,
+        payload: recordingCookiePayload({ recording }),
+        origin,
+      }),
+    ]);
+    const page = await context.newPage();
+    // 'load', not 'networkidle': every dev page holds the /api/reload event
+    // stream open, so the network never goes idle and a networkidle wait
+    // always ran to its full timeout before anything else happened.
     await page.goto(url, { waitUntil: 'load', timeout });
+    // The engine builds the page context (and runs onInit + initial requests)
+    // after the bundle loads — 'load' fires before that. Every caller
+    // (screenshot, inspect, eval, checkpoint load, journeys) needs the app's
+    // async lifecycle to have settled, not just the bundle to have loaded, so
+    // wait on isPageReady - for the instance the app shows, which is not the
+    // one asked for when the app redirects, as a protected page does for a
+    // signed-out caller. Tolerant: on timeout proceed with ready:
+    // false and let the caller surface what it finds — a snapshot of a hung
+    // page is still useful signal, and a far better answer than a tool failure.
+    let ready = true;
+    await page.waitForFunction(isPageReady, undefined, { timeout }).catch(() => {
+      ready = false;
+    });
+    // Images blocks render start loading only once the page is ready; a
+    // screenshot taken before they arrive shows empty frames. A lazy image
+    // below the fold never loads until scrolled to, so it counts as done.
+    await page
+      .waitForFunction(
+        () =>
+          Array.from(document.images).every((image) => image.complete || image.loading === 'lazy'),
+        undefined,
+        { timeout }
+      )
+      .catch(() => {});
+    return { context, page, ready, url, leftOrigin };
+  } catch (error) {
+    await context.close().catch(() => {});
+    throw error;
   }
-  // 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 };