@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/readJourneySession.js

@@ -0,0 +1,56 @@
+/*
+  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 {
+  buildSessionReport,
+  formatSessionReport,
+  parseSince,
+  readRecordings,
+} from '@lowdefy/node-utils';
+import { type } from '@lowdefy/helpers';
+
+import { getConfigDirectory } from './checkpointPaths.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+function describeEmpty() {
+  if (process.env.LOWDEFY_DEV_RECORD === 'false') {
+    return 'No recorded dev sessions: recording is off (LOWDEFY_DEV_RECORD=false).';
+  }
+  return 'No recorded dev sessions in this window.';
+}
+
+// What lowdefy_journey_session answers, as `lowdefy journeys session` prints
+// it: without an id, the dev sessions this app recorded, newest first; with
+// one, that session's log. Returns { text } or { error }.
+function readJourneySession({ id, since, now = Date.now() }) {
+  const start = type.isNone(since) ? undefined : parseSince({ since, now });
+  const records = readRecordings({
+    configDirectory: getConfigDirectory(),
+    source: 'dev',
+    since: type.isUndefined(start) ? undefined : new Date(start),
+  }).filter((record) => type.isUndefined(start) || Date.parse(record?.t) >= start);
+  const report = buildSessionReport({
+    records,
+    id,
+    blockMetas: readBuildArtifact({ name: 'plugins/blockMetas.json' }) ?? {},
+  });
+  if (!type.isUndefined(report.error)) {
+    return { error: report.error };
+  }
+  return { text: formatSessionReport({ report, empty: describeEmpty() }).join('\n') };
+}
+
+export default readJourneySession;

package/lib/docs/readMailOutbox.js

@@ -0,0 +1,37 @@
+/*
+  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 'fs';
+import path from 'path';
+
+import getMailOutboxDirectory from './getMailOutboxDirectory.js';
+
+// The messages the dev mail sink has captured this session, oldest first. The
+// sink names each file by its receive sequence and writes it in one rename, so
+// a listing never sees half a message.
+async function readMailOutbox({ configDirectory }) {
+  const directory = getMailOutboxDirectory({ configDirectory });
+  const fileNames = (await fs.promises.readdir(directory))
+    .filter((fileName) => fileName.endsWith('.json'))
+    .sort();
+  return Promise.all(
+    fileNames.map(async (fileName) =>
+      JSON.parse(await fs.promises.readFile(path.join(directory, fileName), 'utf8'))
+    )
+  );
+}
+
+export default readMailOutbox;

package/lib/docs/readPagePath.js

@@ -0,0 +1,27 @@
+/*
+  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 readBuildArtifact from './readBuildArtifact.js';
+
+// A page's path pattern, from the route table the skeleton build writes. A page
+// the table does not hold has none, so its URL is its id, which the server
+// answers as it answers any unknown page.
+function readPagePath({ pageId }) {
+  const routes = readBuildArtifact({ name: 'routes.json', deserialize: true });
+  return routes.find((route) => route.pageId === pageId)?.path;
+}
+
+export default readPagePath;

package/lib/docs/readPluginPackages.js

@@ -0,0 +1,99 @@
+/*
+  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 readBuildArtifact from './readBuildArtifact.js';
+
+function addTypes({ plugins, store, kind }) {
+  for (const [typeName, definition] of Object.entries(store ?? {})) {
+    if (!plugins[definition.package]) {
+      plugins[definition.package] = {
+        package: definition.package,
+        version: definition.version,
+        types: {},
+      };
+    }
+    const plugin = plugins[definition.package];
+    if (!plugin.types[kind]) {
+      plugin.types[kind] = [];
+    }
+    plugin.types[kind].push(typeName);
+  }
+}
+
+// Icon sets are keyed by set id, with one layer per plugin that declares it.
+function addIconSets({ plugins, iconSets }) {
+  for (const [setId, layers] of Object.entries(iconSets ?? {})) {
+    for (const layer of layers) {
+      addTypes({ plugins, store: { [setId]: layer }, kind: 'iconSets' });
+    }
+  }
+}
+
+function readPluginPackages() {
+  const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
+  const customTypesMap = readBuildArtifact({ name: 'customTypesMap.json' }) ?? {};
+  const installedPackages = readBuildArtifact({ name: 'installedPluginPackages.json' }) ?? [];
+
+  const plugins = {};
+  addTypes({ plugins, store: availableTypes.actions, kind: 'actions' });
+  addTypes({ plugins, store: availableTypes.agents, kind: 'agents' });
+  addTypes({ plugins, store: availableTypes.blocks, kind: 'blocks' });
+  addTypes({ plugins, store: availableTypes.connections, kind: 'connections' });
+  addTypes({ plugins, store: availableTypes.notifications, kind: 'notifications' });
+  addTypes({ plugins, store: availableTypes.operators?.client, kind: 'operators' });
+  addTypes({ plugins, store: availableTypes.operators?.server, kind: 'operators' });
+  addTypes({ plugins, store: availableTypes.requests, kind: 'requests' });
+  addTypes({ plugins, store: availableTypes.websockets, kind: 'websockets' });
+  addIconSets({ plugins, iconSets: customTypesMap.iconSets });
+
+  const customPackages = new Set();
+  const customStores = [
+    customTypesMap.actions,
+    customTypesMap.agents,
+    customTypesMap.blocks,
+    customTypesMap.connections,
+    customTypesMap.operators?.client,
+    customTypesMap.operators?.server,
+    customTypesMap.requests,
+    customTypesMap.websockets,
+  ];
+  for (const store of customStores) {
+    for (const definition of Object.values(store ?? {})) {
+      customPackages.add(definition.package);
+    }
+  }
+  for (const layers of Object.values(customTypesMap.iconSets ?? {})) {
+    for (const layer of layers) {
+      customPackages.add(layer.package);
+    }
+  }
+
+  return Object.values(plugins)
+    .map((plugin) => ({
+      ...plugin,
+      custom: customPackages.has(plugin.package),
+      installed: installedPackages.includes(plugin.package),
+      types: Object.fromEntries(
+        Object.entries(plugin.types).map(([kind, typeNames]) => [
+          kind,
+          [...new Set(typeNames)].sort(),
+        ])
+      ),
+    }))
+    .sort((a, b) => a.package.localeCompare(b.package));
+}
+
+export default readPluginPackages;

package/lib/docs/readProxyBuildWait.js

@@ -0,0 +1,38 @@
+/*
+  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';
+
+import buildWaitHeader from './buildWaitHeader.js';
+
+// A build can restart this process, which ends any wait running in it, so
+// the manager's proxy waits for builds and restarts before it forwards a
+// build-status wait, and passes what it saw in this header. Null when the
+// request did not come through that wait.
+function readProxyBuildWait({ getHeader }) {
+  const header = getHeader(buildWaitHeader);
+  if (type.isNone(header)) {
+    return null;
+  }
+  const params = new URLSearchParams(header);
+  return {
+    settled: params.get('settled') === 'true',
+    sawBuild: params.get('sawBuild') === 'true',
+    waitedMs: Number(params.get('waitedMs')),
+  };
+}
+
+export default readProxyBuildWait;

package/lib/docs/readRoutineSteps.js

@@ -0,0 +1,45 @@
+/*
+  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';
+
+import isRoutineStep from '../server/isRoutineStep.js';
+
+// Every step of an endpoint routine, at any depth: steps sit in arrays, and
+// control objects (`:if`, `:try`, `:parallel`, ...) hold more arrays of steps
+// under their `:` keys. A step's own properties are data, never more steps.
+function readRoutineSteps({ routine }) {
+  const steps = [];
+  function walk(node) {
+    if (type.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    if (isRoutineStep(node)) {
+      steps.push(node);
+      return;
+    }
+    if (type.isObject(node)) {
+      Object.keys(node)
+        .filter((key) => key.startsWith(':'))
+        .forEach((key) => walk(node[key]));
+    }
+  }
+  walk(routine);
+  return steps;
+}
+
+export default readRoutineSteps;

package/lib/docs/registerShownTextEngine.js

@@ -0,0 +1,118 @@
+/*
+  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 { SHOWN_TEXT_ENGINE } from './shownTextSelector.js';
+
+// The selector engine a `containing` target is found by: the innermost
+// elements whose shown text contains the string. Playwright's getByText reads
+// an element's text nodes joined with nothing between them, so a label and
+// value that only layout separates (`<span>Assigned to</span><b>Jane</b>` in a
+// flex row, table cells, block children) read as "Assigned toJane" and match
+// nothing. innerText is the text as the page lays it out, with a break between
+// block-level boxes. Like getByText, matching collapses whitespace and ignores
+// case, and an element matches only when none of its children does, so a
+// strict target still names one element and not its every ancestor.
+//
+// Playwright serialises the function and runs it in the page, so everything
+// it uses is inside it. The selector body is a JSON string, so `>>` or quotes
+// in the text never split the selector.
+function createShownTextEngine() {
+  const SKIPPED = new Set(['HEAD', 'SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE']);
+  const BUTTON_INPUTS = 'input[type=button], input[type=submit]';
+
+  function normalize(text) {
+    return text
+      .replace(/[\u200b\u00ad]/g, '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .toLowerCase();
+  }
+
+  // innerText only adds whitespace to textContent and drops hidden text, so an
+  // element whose textContent, spaces removed, lacks the string, spaces
+  // removed, cannot match. This check skips the layout innerText costs on
+  // almost every element.
+  function squash(text) {
+    return text.replace(/[\s\u200b\u00ad]/g, '').toLowerCase();
+  }
+
+  function queryAll(root, selector) {
+    const needle = normalize(JSON.parse(selector));
+    const squashed = squash(needle);
+    const matches = [];
+    // Children are visited first: an element with a matching child is no match
+    // itself and needs no innerText, so innerText is read only on the
+    // innermost candidates, not on every ancestor up to <html>.
+    function visit(element) {
+      if (SKIPPED.has(element.tagName) || !squash(element.textContent ?? '').includes(squashed)) {
+        return false;
+      }
+      let childMatches = false;
+      for (const child of element.children) {
+        if (visit(child)) {
+          childMatches = true;
+        }
+      }
+      if (childMatches) {
+        return true;
+      }
+      if (!normalize(element.innerText ?? element.textContent ?? '').includes(needle)) {
+        return false;
+      }
+      matches.push(element);
+      return true;
+    }
+    const start = root.nodeType === Node.DOCUMENT_NODE ? root.documentElement : root;
+    if (start) {
+      visit(start);
+      // A button input shows its value, which no textContent holds, so it is
+      // looked for apart from the walk, as getByText finds it.
+      const inputs = [
+        ...(start.matches?.(BUTTON_INPUTS) ? [start] : []),
+        ...start.querySelectorAll(BUTTON_INPUTS),
+      ];
+      for (const input of inputs) {
+        if (normalize(input.value).includes(needle)) {
+          matches.push(input);
+        }
+      }
+    }
+    return matches;
+  }
+
+  return {
+    query(root, selector) {
+      return queryAll(root, selector)[0] ?? null;
+    },
+    queryAll,
+  };
+}
+
+let registered = null;
+
+// Registers the engine with Playwright once per process. Playwright applies a
+// registered engine to every browser context, open or yet to be created.
+function registerShownTextEngine(selectors) {
+  if (registered === null) {
+    registered = selectors.register(SHOWN_TEXT_ENGINE, createShownTextEngine).catch((error) => {
+      registered = null;
+      throw error;
+    });
+  }
+  return registered;
+}
+
+export default registerShownTextEngine;

package/lib/docs/requestRestart.js

@@ -0,0 +1,30 @@
+/*
+  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';
+
+// The manager's child is the Vite process, not this Hono app, so there is no
+// IPC channel back to the manager. Like build/reload and build/invalidatePages,
+// a sentinel file in the build directory is the channel: the manager watches
+// for .restart and restarts the server when it appears.
+function requestRestart({ reason }) {
+  const filePath = path.join(process.cwd(), 'build', '.restart');
+  fs.writeFileSync(filePath, JSON.stringify({ requestedAt: new Date().toISOString(), reason }));
+  return { requested: true, reason };
+}
+
+export default requestRestart;

package/lib/docs/requestRestart.test.mjs

@@ -0,0 +1,49 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-request-restart-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+process.chdir(fixtureDir);
+
+const { default: requestRestart } = await import('./requestRestart.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+test('requestRestart writes the .restart sentinel with the reason and a timestamp', () => {
+  const result = requestRestart({ reason: 'Added a server operator' });
+
+  expect(result).toEqual({ requested: true, reason: 'Added a server operator' });
+  const sentinel = JSON.parse(fs.readFileSync(path.join(fixtureDir, 'build', '.restart'), 'utf8'));
+  expect(sentinel.reason).toBe('Added a server operator');
+  expect(new Date(sentinel.requestedAt).toISOString()).toBe(sentinel.requestedAt);
+});
+
+test('requestRestart writes the sentinel without a reason', () => {
+  const result = requestRestart({ reason: undefined });
+
+  expect(result).toEqual({ requested: true, reason: undefined });
+  const sentinel = JSON.parse(fs.readFileSync(path.join(fixtureDir, 'build', '.restart'), 'utf8'));
+  expect(sentinel).not.toHaveProperty('reason');
+  expect(sentinel.requestedAt).toEqual(expect.any(String));
+});

package/lib/docs/resolvePageInstance.js

@@ -0,0 +1,46 @@
+/*
+  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 { buildPagePath, pageInstanceKey, type } from '@lowdefy/helpers';
+
+import readPagePath from './readPagePath.js';
+
+// The page instance a dev tool names by `pageId` and `pathParams`: the page's
+// path pattern (readPagePath, undefined for a page the route table does not
+// list) and the key its context and input are stored under. Returns
+// { path, instanceKey }, or { error } for pathParams that are not an object or
+// that miss a placeholder of the pattern, as data for the tool to return to the
+// agent before it opens a browser.
+function resolvePageInstance({ pageId, pathParams }) {
+  if (!type.isNone(pathParams) && !type.isObject(pathParams)) {
+    return {
+      error: `"pathParams" must be an object of path values, e.g. {"ticket_id": "1"}. Received ${JSON.stringify(
+        pathParams
+      )}.`,
+    };
+  }
+  const path = readPagePath({ pageId });
+  try {
+    buildPagePath({ pageId, path, pathParams });
+  } catch (error) {
+    return {
+      error: `${error.message} Page "${pageId}" is served at "${path}": pass "pathParams" with a value for each placeholder.`,
+    };
+  }
+  return { path, instanceKey: pageInstanceKey({ pageId, path, pathParams }) };
+}
+
+export default resolvePageInstance;

package/lib/docs/resolvePageInstance.test.mjs

@@ -0,0 +1,81 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+
+// readPagePath reads build/routes.json from process.cwd(): chdir into a fixture
+// that has one before the module loads.
+const originalCwd = process.cwd();
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-page-instance-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
+fs.writeFileSync(
+  path.join(fixtureDir, 'build', 'routes.json'),
+  JSON.stringify([
+    { pageId: 'home', path: 'home' },
+    { pageId: 'about', path: 'company/about' },
+    { pageId: 'ticket', path: 'tickets/{space}/{ticket_id}' },
+  ])
+);
+process.chdir(fixtureDir);
+
+const { default: resolvePageInstance } = await import('./resolvePageInstance.js');
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+test('resolvePageInstance keys a page without placeholders by its id', () => {
+  expect(resolvePageInstance({ pageId: 'home' })).toEqual({
+    path: 'home',
+    instanceKey: 'page:home',
+  });
+  expect(resolvePageInstance({ pageId: 'about' })).toEqual({
+    path: 'company/about',
+    instanceKey: 'page:about',
+  });
+});
+
+test('resolvePageInstance keys a patterned page instance by the path its values build', () => {
+  expect(
+    resolvePageInstance({ pageId: 'ticket', pathParams: { space: 's', ticket_id: 1 } })
+  ).toEqual({
+    path: 'tickets/{space}/{ticket_id}',
+    instanceKey: 'page:ticket#tickets/s/1',
+  });
+});
+
+test('resolvePageInstance returns the builder error naming a missing placeholder', () => {
+  expect(resolvePageInstance({ pageId: 'ticket', pathParams: { space: 's' } })).toEqual({
+    error:
+      'Link to page "ticket" is missing a value for path placeholder "ticket_id". Page "ticket" is served at "tickets/{space}/{ticket_id}": pass "pathParams" with a value for each placeholder.',
+  });
+});
+
+test('resolvePageInstance returns an error for pathParams that are not an object', () => {
+  expect(resolvePageInstance({ pageId: 'ticket', pathParams: '1' }).error).toMatch(
+    /"pathParams" must be an object of path values/
+  );
+});
+
+test('resolvePageInstance builds a page the route table does not list as its id', () => {
+  expect(resolvePageInstance({ pageId: 'missing' })).toEqual({
+    path: undefined,
+    instanceKey: 'page:missing',
+  });
+});

package/lib/docs/resolveSource.js

@@ -24,24 +24,28 @@ import tabAvailable from './tabAvailable.js';
 // actually looking at (their own interactions, in-flight requests), while
 // headless always starts a clean navigation.
 //
-// `user` is headless-only — the developer's tab carries their real session,
-// which the dev server cannot re-identify — so it selects the headless source,
-// and contradicts an explicit `source: 'tab'`.
+// `user` and `data` are headless-only — the developer's tab carries their real
+// session and reads the app's real database, which the dev server cannot
+// swap — so either selects the headless source, and contradicts an explicit
+// `source: 'tab'`.
 //
 // Returns { tryTab }, or { error, invalidInput } for a contradictory call.
 // `invalidInput` marks the caller's own mistake rather than a failed render, so
 // the HTTP routes can answer 400 instead of a 502 that reads as "the renderer
 // broke, retry".
-function resolveSource({ name, pageId, source, user }) {
-  const hasUser = !type.isNone(user);
+function resolveSource({ name, pageId, pathParams, source, user, data }) {
+  const hasUser = !type.isNone(user) || !type.isNone(data);
   if (hasUser && source === 'tab') {
+    const param = type.isNone(user) ? 'data' : 'user';
     return {
-      error: `${name} cannot apply "user" to the developer's live tab — it carries their real session. Omit "source", or use "headless".`,
+      error: `${name} cannot apply "${param}" to the developer's live tab — it carries their real session and database. Omit "source", or use "headless".`,
       invalidInput: true,
     };
   }
   return {
-    tryTab: source === 'tab' || (source === undefined && !hasUser && tabAvailable({ pageId })),
+    tryTab:
+      source === 'tab' ||
+      (source === undefined && !hasUser && tabAvailable({ pageId, pathParams })),
   };
 }