@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/snapshotState.js

@@ -18,6 +18,7 @@ import { type } from '@lowdefy/helpers';
 
 import { buildPageUrl } from './getBrowser.js';
 import inspectState from './inspectState.js';
+import readPagePath from './readPagePath.js';
 import { writeCheckpoint } from './checkpointStore.js';
 
 // Snapshots the running app (page state + recorded request/api responses)
@@ -25,8 +26,10 @@ import { writeCheckpoint } from './checkpointStore.js';
 // on-disk layout. Reuses inspectState.js's tab-first/headless-fallback
 // snapshot rather than driving a browser directly, so a snapshot always
 // reflects whatever a developer is actually looking at when one is
-// available.
-async function snapshotState({ origin, pageId, name, notes, source, overwrite }) {
+// available. With only a `pageId`, a tab's snapshot is of the instance it
+// names (see findPageInstance in tabChannel.js), and the checkpoint keeps that
+// instance's pathParams.
+async function snapshotState({ origin, pageId, pathParams, name, notes, source, overwrite }) {
   if (type.isNone(pageId) || !type.isString(pageId)) {
     return {
       error: `snapshotState requires a "pageId" string. Received ${JSON.stringify(pageId)}.`,
@@ -36,12 +39,17 @@ async function snapshotState({ origin, pageId, name, notes, source, overwrite })
     return { error: `snapshotState requires a "name" string. Received ${JSON.stringify(name)}.` };
   }
 
-  const snapshot = await inspectState({ origin, pageId, source });
+  const snapshot = await inspectState({ origin, pageId, pathParams, source });
   if (snapshot?.error) {
-    return { error: snapshot.error };
+    return { error: snapshot.error, invalidInput: snapshot.invalidInput };
   }
 
-  const url = `${buildPageUrl({ origin, pageId })}${snapshot.urlQuery ?? ''}`;
+  const url = `${buildPageUrl({
+    origin,
+    pageId,
+    path: readPagePath({ pageId }),
+    pathParams: snapshot.pathParams,
+  })}${snapshot.urlQuery ?? ''}`;
 
   try {
     const { dir, parts } = writeCheckpoint({

package/lib/docs/splitSearchTerms.js

@@ -0,0 +1,62 @@
+/*
+  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.
+*/
+
+const MIN_TERM_LENGTH = 3;
+
+const COMMON_WORDS = new Set([
+  'about',
+  'all',
+  'and',
+  'any',
+  'are',
+  'can',
+  'does',
+  'for',
+  'from',
+  'has',
+  'have',
+  'how',
+  'into',
+  'not',
+  'the',
+  'this',
+  'that',
+  'use',
+  'using',
+  'what',
+  'when',
+  'where',
+  'which',
+  'who',
+  'why',
+  'will',
+  'with',
+  'you',
+  'your',
+]);
+
+// Underscores, dots and dollar signs stay inside a term, so operator names
+// like _string.concat and $match are searched as written.
+function splitSearchTerms({ query }) {
+  const terms = query
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}_.$]+/u)
+    .map((term) => term.replace(/^\.+|\.+$/g, ''))
+    .filter((term) => term.length >= MIN_TERM_LENGTH && !COMMON_WORDS.has(term));
+  return [...new Set(terms)];
+}
+
+export default splitSearchTerms;

package/lib/docs/splitSearchTerms.test.mjs

@@ -0,0 +1,50 @@
+/*
+  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 splitSearchTerms from './splitSearchTerms.js';
+
+test('splitSearchTerms lowercases and splits on spaces and punctuation', () => {
+  expect(splitSearchTerms({ query: 'Link action, pathParams? (path parameters)' })).toEqual([
+    'link',
+    'action',
+    'pathparams',
+    'path',
+    'parameters',
+  ]);
+});
+
+test('splitSearchTerms drops one- and two-letter terms and common words', () => {
+  expect(splitSearchTerms({ query: 'How to use a Modal with the blocks' })).toEqual([
+    'modal',
+    'blocks',
+  ]);
+});
+
+test('splitSearchTerms counts a repeated term once', () => {
+  expect(splitSearchTerms({ query: 'state State STATE page' })).toEqual(['state', 'page']);
+});
+
+test('splitSearchTerms keeps operator names whole', () => {
+  expect(splitSearchTerms({ query: '_string.concat $match _if.' })).toEqual([
+    '_string.concat',
+    '$match',
+    '_if',
+  ]);
+});
+
+test('splitSearchTerms returns no terms when every word is dropped', () => {
+  expect(splitSearchTerms({ query: 'to a of' })).toEqual([]);
+});

package/lib/docs/stateCheckpoints.test.mjs

@@ -29,6 +29,13 @@ const previousConfigDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG;
 const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-state-checkpoints-test-'));
 fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
 fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+fs.writeFileSync(
+  path.join(fixtureDir, 'build', 'routes.json'),
+  JSON.stringify([
+    { pageId: 'home', path: 'home' },
+    { pageId: 'ticket', path: 'tickets/{space}/{ticket_id}' },
+  ])
+);
 process.chdir(fixtureDir);
 process.env.LOWDEFY_DIRECTORY_CONFIG = fixtureDir;
 
@@ -39,6 +46,8 @@ process.env.LOWDEFY_DIRECTORY_CONFIG = fixtureDir;
 jest.unstable_mockModule('playwright-core', () => ({
   chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
 }));
+// A missing shell would otherwise start a real download.
+jest.unstable_mockModule('./installHeadlessShell.js', () => ({ default: () => null }));
 
 const mockInspectState = jest.fn();
 jest.unstable_mockModule('./inspectState.js', () => ({
@@ -101,6 +110,7 @@ describe('checkpointStore', () => {
         'checkpoint.json',
         'state.json',
         'urlQuery.json',
+        'pathParams.json',
         'inputs.json',
         'user.json',
         'global.json',
@@ -118,6 +128,7 @@ describe('checkpointStore', () => {
     expect(typeof result.checkpoint.capturedAt).toBe('string');
     expect(result.state).toEqual({ count: 1 });
     expect(result.urlQuery).toBe('?a=1');
+    expect(result.pathParams).toEqual({});
     expect(result.input).toEqual({ fromInput: true });
     expect(result.user).toEqual({ id: 'u1' });
     expect(result.global).toEqual({ g: 1 });
@@ -168,6 +179,7 @@ describe('checkpointStore', () => {
     const result = readCheckpoint({ name: 'cp-partial' });
     expect(result.state).toEqual({});
     expect(result.urlQuery).toBe('');
+    expect(result.pathParams).toEqual({});
     expect(result.input).toEqual({});
     expect(result.user).toBe(null);
     expect(result.global).toEqual({});
@@ -293,6 +305,32 @@ describe('snapshotState', () => {
     expect(stored.checkpoint.url).toBe('http://localhost:3111/home');
   });
 
+  test('keeps the pathParams of the instance it snapshots', async () => {
+    mockInspectState.mockResolvedValue({
+      pageId: 'ticket',
+      pathParams: { space: 's', ticket_id: '1' },
+      state: { subject: 'One' },
+      requests: {},
+      urlQuery: '?tab=notes',
+      source: 'tab',
+    });
+
+    const result = await snapshotState({
+      origin: 'http://localhost:3111',
+      pageId: 'ticket',
+      name: 'cp-snapshot-instance',
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.parts).toContain('pathParams.json');
+    expect(mockInspectState).toHaveBeenCalledWith(
+      expect.objectContaining({ pageId: 'ticket', pathParams: undefined })
+    );
+    const stored = readCheckpoint({ name: 'cp-snapshot-instance' });
+    expect(stored.pathParams).toEqual({ space: 's', ticket_id: '1' });
+    expect(stored.checkpoint.url).toBe('http://localhost:3111/tickets/s/1?tab=notes');
+  });
+
   test('returns the inspectState error instead of writing a checkpoint', async () => {
     mockInspectState.mockResolvedValue({ error: 'No live context for page "home".' });
 
@@ -337,6 +375,45 @@ describe('loadState', () => {
     });
   });
 
+  test('registry-only mode opens the page instance the checkpoint names', async () => {
+    writeCheckpoint({
+      name: 'cp-load-instance',
+      snapshot: buildSnapshot({
+        pageId: 'ticket',
+        pathParams: { space: 's', ticket_id: '1' },
+        urlQuery: '?tab=notes',
+      }),
+    });
+
+    const result = await loadState({
+      origin: 'http://localhost:3111',
+      name: 'cp-load-instance',
+      mode: 'registry-only',
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.url).toBe(
+      'http://localhost:3111/tickets/s/1?tab=notes&_checkpoint=cp-load-instance'
+    );
+  });
+
+  test('refuses a checkpoint whose pathParams miss a placeholder of its page', async () => {
+    writeCheckpoint({
+      name: 'cp-load-missing',
+      snapshot: buildSnapshot({ pageId: 'ticket', pathParams: { space: 's' }, urlQuery: '' }),
+    });
+
+    const result = await loadState({
+      origin: 'http://localhost:3111',
+      name: 'cp-load-missing',
+      mode: 'registry-only',
+    });
+
+    expect(result.error).toMatch(
+      /Checkpoint "cp-load-missing" cannot open its page: .*placeholder "ticket_id"/
+    );
+  });
+
   test('returns an error when the checkpoint does not exist', async () => {
     const result = await loadState({
       origin: 'http://localhost:3111',

package/lib/docs/tabAvailable.js

@@ -16,13 +16,14 @@
 
 import { type } from '@lowdefy/helpers';
 
-import { listTabs } from './tabChannel.js';
+import { findPageInstance } from './tabChannel.js';
 
 // Shared by inspectState.js and evalOperator.js to decide, when no explicit
-// `source` is requested, whether a live browser tab exists to prefer over a
-// fresh headless one.
-function tabAvailable({ pageId }) {
-  return listTabs().some((tab) => type.isNone(pageId) || tab.pageId === pageId);
+// `source` is requested, whether a live browser tab holds the requested page
+// instance, to prefer over a fresh headless one. A tab the dev server's own
+// headless browser opened is not one to prefer (findPageInstance never picks it).
+function tabAvailable({ pageId, pathParams }) {
+  return !type.isNone(findPageInstance({ pageId, pathParams }));
 }
 
 export default tabAvailable;

package/lib/docs/tabChannel.js

@@ -29,24 +29,52 @@ import { type } from '@lowdefy/helpers';
 const tabs = new Map();
 const pendingRequests = new Map();
 
-function registerTab({ id, pageId, send }) {
+// Orders instance renders across tabs, so "most recently rendered" does not hang on clock ticks.
+let renderSequence = 0;
+
+// A tab the dev server's own headless browser opened (a journey run, a
+// headless tool) is automated: it is listed, so the hub keeps
+// the server alive while it runs, but findPageInstance never picks it for an
+// agent's or developer's live-tab request.
+function registerTab({ id, send, source = 'dev', automated = false }) {
   if (type.isNone(id) || !type.isString(id)) {
     throw new Error(`registerTab requires an "id" string. Received ${JSON.stringify(id)}.`);
   }
   if (!type.isFunction(send)) {
     throw new Error('registerTab requires a "send" function.');
   }
-  tabs.set(id, { id, pageId: pageId ?? null, send, connectedAt: new Date() });
+  tabs.set(id, {
+    id,
+    page: null,
+    rendered: new Map(),
+    send,
+    source,
+    automated,
+    connectedAt: new Date(),
+  });
 }
 
-function updateTabPage({ id, pageId }) {
+// Records the page instance a tab shows, { pageId, pathParams, instanceKey }, and keeps it among
+// the instances the tab has rendered, whose contexts the tab still holds.
+function updateTabPage({ id, pageId, pathParams, instanceKey }) {
   const tab = tabs.get(id);
   if (type.isNone(tab)) {
     // The tab may have disconnected between the client sending the ping and
     // it arriving — nothing to update, and not worth failing the request.
     return;
   }
-  tab.pageId = pageId ?? null;
+  if (!type.isString(pageId) || !type.isString(instanceKey)) {
+    throw new Error(
+      `updateTabPage requires "pageId" and "instanceKey" strings. Received ${JSON.stringify({
+        pageId,
+        instanceKey,
+      })}.`
+    );
+  }
+  renderSequence += 1;
+  const page = { pageId, pathParams: pathParams ?? {}, instanceKey };
+  tab.page = page;
+  tab.rendered.set(instanceKey, { ...page, sequence: renderSequence });
 }
 
 function unregisterTab({ id }) {
@@ -54,37 +82,101 @@ function unregisterTab({ id }) {
 }
 
 function listTabs() {
-  return Array.from(tabs.values()).map(({ id, pageId, connectedAt }) => ({
+  return Array.from(tabs.values()).map(({ id, page, source, automated, connectedAt }) => ({
     id,
-    pageId,
+    pageId: page?.pageId ?? null,
+    pathParams: page?.pathParams ?? null,
+    instanceKey: page?.instanceKey ?? null,
+    source,
+    automated,
     connectedAt,
   }));
 }
 
-// Most recently connected tab wins — Map preserves insertion order, and
-// re-registering a tab id (reconnect) deletes then re-sets it, so the last
-// entry is always the most recent connection.
-function findTab({ pageId }) {
-  const candidates = Array.from(tabs.values()).filter(
-    (tab) => type.isNone(pageId) || tab.pageId === pageId
+// Path values compare as strings: a tab reports them decoded from its URL, an agent may pass
+// a number.
+function pathParamsMatch({ requested, rendered }) {
+  if (type.isNone(requested)) {
+    return true;
+  }
+  const requestedKeys = Object.keys(requested);
+  if (requestedKeys.length !== Object.keys(rendered).length) {
+    return false;
+  }
+  return requestedKeys.every((key) => String(requested[key]) === rendered[key]);
+}
+
+function instanceMatches({ instance, pageId, pathParams }) {
+  if (type.isNone(pageId)) {
+    return true;
+  }
+  return (
+    instance.pageId === pageId &&
+    pathParamsMatch({ requested: pathParams, rendered: instance.pathParams })
   );
-  if (candidates.length === 0) {
+}
+
+// Which tab and page instance a dev tool request reads, as { tab, pageId, pathParams,
+// instanceKey }, or undefined when no tab has one:
+//   - the instance on screen in a tab, when one shows the requested page (and values), the most
+//     recently connected such tab first (Map order: a reconnect deletes and re-sets the tab id);
+//   - else the requested page's most recently rendered instance (with those values) in any tab,
+//     whose context that tab still holds.
+// A request naming no page reads the instance on screen in the most recently connected tab.
+// Automated tabs are skipped.
+function findPageInstance({ pageId, pathParams } = {}) {
+  const candidates = Array.from(tabs.values()).filter((tab) => !tab.automated);
+  const onScreen = candidates.filter(
+    (tab) => !type.isNone(tab.page) && instanceMatches({ instance: tab.page, pageId, pathParams })
+  );
+  if (onScreen.length > 0) {
+    const tab = onScreen[onScreen.length - 1];
+    return { tab, ...tab.page };
+  }
+  if (type.isNone(pageId)) {
+    return undefined;
+  }
+  let found;
+  candidates.forEach((tab) => {
+    tab.rendered.forEach((instance) => {
+      if (!instanceMatches({ instance, pageId, pathParams })) {
+        return;
+      }
+      if (type.isNone(found) || instance.sequence > found.sequence) {
+        found = { tab, ...instance };
+      }
+    });
+  });
+  if (type.isNone(found)) {
     return undefined;
   }
-  return candidates[candidates.length - 1];
+  const { sequence, ...instance } = found;
+  return instance;
 }
 
-function requestFromTab({ pageId, event, payload = {}, timeout = 5000 }) {
+function describeRequestedPage({ pageId, pathParams }) {
+  if (type.isNone(pageId)) {
+    return 'any page';
+  }
+  if (type.isNone(pathParams)) {
+    return `page "${pageId}"`;
+  }
+  return `page "${pageId}" with pathParams ${JSON.stringify(pathParams)}`;
+}
+
+function requestFromTab({ pageId, pathParams, event, payload = {}, timeout = 5000 }) {
   if (type.isNone(event) || !type.isString(event)) {
     throw new Error(
       `requestFromTab requires an "event" string. Received ${JSON.stringify(event)}.`
     );
   }
-  const tab = findTab({ pageId });
-  if (type.isNone(tab)) {
-    const location = type.isNone(pageId) ? 'any page' : `page "${pageId}"`;
+  const instance = findPageInstance({ pageId, pathParams });
+  if (type.isNone(instance)) {
     return Promise.resolve({
-      error: `No browser tab connected on ${location}. Ask the developer to open the page, or use source: "headless".`,
+      error: `No browser tab connected on ${describeRequestedPage({
+        pageId,
+        pathParams,
+      })}. Ask the developer to open the page, or use source: "headless".`,
     });
   }
 
@@ -101,7 +193,13 @@ function requestFromTab({ pageId, event, payload = {}, timeout = 5000 }) {
       resolve(result);
     });
 
-    tab.send(event, { requestId, ...payload });
+    instance.tab.send(event, {
+      requestId,
+      pageId: instance.pageId,
+      pathParams: instance.pathParams,
+      instanceKey: instance.instanceKey,
+      ...payload,
+    });
   });
 }
 
@@ -116,4 +214,12 @@ function resolveTabRequest({ requestId, result }) {
   return true;
 }
 
-export { listTabs, registerTab, requestFromTab, resolveTabRequest, unregisterTab, updateTabPage };
+export {
+  findPageInstance,
+  listTabs,
+  registerTab,
+  requestFromTab,
+  resolveTabRequest,
+  unregisterTab,
+  updateTabPage,
+};