@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/searchIcons.test.mjs

@@ -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 { jest } from '@jest/globals';
+
+// searchIcons reads the dev build's iconAliases.json and customTypesMap.json,
+// which only exist in a built server directory, and loads installed icon set
+// plugins through the build's loader. Lucide's names are real.
+const mockReadBuildArtifact = jest.fn();
+jest.unstable_mockModule('./readBuildArtifact.js', () => ({
+  default: mockReadBuildArtifact,
+}));
+
+const buildDev = await import('@lowdefy/build/dev');
+const mockLoadIconSets = jest.fn();
+jest.unstable_mockModule('@lowdefy/build/dev', () => ({
+  ...buildDev,
+  loadIconSets: mockLoadIconSets,
+}));
+
+const { default: searchIcons } = await import('./searchIcons.js');
+
+function layer(names) {
+  return { names: new Set(names) };
+}
+
+function mockArtifacts({ aliases = null, iconSets = {} } = {}) {
+  mockReadBuildArtifact.mockImplementation(({ name }) => {
+    if (name === 'iconAliases.json') return aliases;
+    if (name === 'customTypesMap.json') return { iconSets };
+    return null;
+  });
+}
+
+beforeEach(() => {
+  mockReadBuildArtifact.mockReset();
+  mockLoadIconSets.mockReset();
+  mockLoadIconSets.mockResolvedValue({ lucide: [layer([])] });
+});
+
+test('searchIcons lists matching semantic names, then canonical Lucide names, then aliases', async () => {
+  mockArtifacts({ aliases: { delete: 'Trash', edit: 'Pencil' } });
+  const result = await searchIcons({ query: 'trash' });
+  expect(result.semantic).toEqual([{ name: 'delete', icon: 'Trash' }]);
+  expect(result.icons[0]).toBe('Trash');
+  expect(result.icons).toContain('Trash2');
+  // Trash2 is a canonical name in Lucide 1.x; aliases come after every canonical name.
+  const { canonical } = buildDev.getLucideIconNames();
+  const firstAlias = result.icons.findIndex((name) => !canonical.includes(name));
+  if (firstAlias !== -1) {
+    expect(result.icons.slice(firstAlias).every((name) => !canonical.includes(name))).toBe(true);
+  }
+});
+
+test('searchIcons ranks canonical names before Lucide alias names', async () => {
+  mockArtifacts();
+  const result = await searchIcons({ query: 'house', limit: 100 });
+  expect(result.icons).toContain('House');
+  const home = await searchIcons({ query: 'home', limit: 100 });
+  // Home is an alias of House.
+  expect(home.icons).toContain('Home');
+  expect(home.icons.indexOf('Home')).toBeGreaterThan(home.icons.indexOf('HousePlus'));
+});
+
+test('searchIcons includes theme aliases from the build', async () => {
+  mockArtifacts({ aliases: { invoice: 'Receipt' } });
+  const result = await searchIcons({ query: 'invoice' });
+  expect(result.semantic).toEqual([{ name: 'invoice', icon: 'Receipt' }]);
+});
+
+test('searchIcons falls back to the built-in names before the first build', async () => {
+  mockArtifacts();
+  const result = await searchIcons({ query: 'external link' });
+  expect(result.semantic).toEqual([{ name: 'external-link', icon: 'ExternalLink' }]);
+});
+
+test('searchIcons lists installed set names qualified, after Lucide names', async () => {
+  const iconSets = { tabler: [{ package: '@acme/icons-tabler', version: '1.0.0' }] };
+  mockArtifacts({ iconSets });
+  mockLoadIconSets.mockResolvedValue({
+    lucide: [layer(['Pencil']), layer(['PencilInvoice'])],
+    tabler: [layer(['PencilBolt', 'Other'])],
+  });
+  const result = await searchIcons({ query: 'pencil', limit: 100 });
+  expect(result.icons[0]).toBe('Pencil');
+  // An icon a plugin adds to lucide is listed unqualified; other sets qualified.
+  expect(result.icons.slice(-2)).toEqual(['PencilInvoice', 'tabler:PencilBolt']);
+  expect(mockLoadIconSets).toHaveBeenCalledWith({
+    context: { directories: { server: process.cwd() }, typesMap: { iconSets } },
+  });
+});
+
+test('searchIcons requires every query word to match', async () => {
+  mockArtifacts();
+  const result = await searchIcons({ query: 'arrow right circle', limit: 50 });
+  expect(result.icons.length).toBeGreaterThan(0);
+  result.icons.forEach((name) => {
+    const lower = name.toLowerCase();
+    expect(lower).toContain('arrow');
+    expect(lower).toContain('right');
+    expect(lower).toContain('circle');
+  });
+});
+
+test('searchIcons caps icon names at the limit', async () => {
+  mockArtifacts();
+  expect((await searchIcons({ query: 'user', limit: 5 })).icons).toHaveLength(5);
+});
+
+test('searchIcons throws without a query', async () => {
+  await expect(searchIcons({ query: ' ' })).rejects.toThrow(
+    'searchIcons requires a "query" string.'
+  );
+});

package/lib/docs/selectExercised.js

@@ -0,0 +1,39 @@
+/*
+  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';
+
+// What the lowdefy_run_journey tool returns of a run's `exercised` block.
+// The full block lists every request, endpoint, event and rendered block, which
+// is hundreds of lines for a short journey, so the tool returns a count of each
+// by default. `selection` true returns the block whole, false leaves it out.
+// Only the tool's response is trimmed: the REST route, and so `lowdefy test`'s
+// exercised.json that the journey lints read, always carries the whole block.
+function selectExercised({ exercised, selection }) {
+  if (selection === true || type.isNone(exercised)) {
+    return { exercised };
+  }
+  if (selection === false) {
+    return {};
+  }
+  const counts = {};
+  Object.entries(exercised).forEach(([key, value]) => {
+    if (type.isArray(value)) counts[key] = value.length;
+  });
+  return { exercised: { counts, note: 'Pass exercised: true for the full block.' } };
+}
+
+export default selectExercised;

package/lib/docs/selectFinalState.js

@@ -0,0 +1,66 @@
+/*
+  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 { get, type } from '@lowdefy/helpers';
+
+// The final state is returned whole when it is small. A page holding request
+// results or long lists can hold hundreds of KB, more than an agent's context
+// should take on every journey, so above this it is summarised instead.
+const DEFAULT_STATE_LIMIT = 10_000;
+
+function summariseState({ state, characters }) {
+  const keys = Object.fromEntries(
+    Object.entries(state)
+      .map(([key, value]) => [key, (JSON.stringify(value) ?? '').length])
+      .sort(([, a], [, b]) => b - a)
+  );
+  return {
+    characters,
+    keys,
+    note: `The final state is ${characters} characters, over the ${DEFAULT_STATE_LIMIT} returned by default. keys lists each top-level key with its size. Pass state: ["path", ...] for the paths you need, or state: true for all of it.`,
+  };
+}
+
+// Picks what the journey result carries of the final page state:
+//   false          nothing
+//   true           the whole state
+//   [path, ...]    { [path]: value } for each path, null where it is undefined
+//   undefined      the whole state when it is at most DEFAULT_STATE_LIMIT
+//                  characters of JSON, otherwise `stateOmitted`, a summary of
+//                  its size and top-level keys
+// A state that could not be read ({ error }) is returned as is, since the
+// error is what the caller needs to see.
+function selectFinalState({ state, selection }) {
+  if (selection === false) {
+    return {};
+  }
+  if (selection === true || !type.isObject(state) || !type.isUndefined(state.error)) {
+    return { state };
+  }
+  if (type.isArray(selection)) {
+    return {
+      state: Object.fromEntries(selection.map((path) => [path, get(state, path) ?? null])),
+    };
+  }
+  const characters = JSON.stringify(state).length;
+  if (characters <= DEFAULT_STATE_LIMIT) {
+    return { state };
+  }
+  return { stateOmitted: summariseState({ state, characters }) };
+}
+
+export { DEFAULT_STATE_LIMIT };
+export default selectFinalState;

package/lib/docs/selectFinalState.test.mjs

@@ -0,0 +1,51 @@
+/*
+  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 selectFinalState, { DEFAULT_STATE_LIMIT } from './selectFinalState.js';
+
+test('selectFinalState returns a small state whole by default', () => {
+  expect(selectFinalState({ state: { a: 1 } })).toEqual({ state: { a: 1 } });
+});
+
+test('selectFinalState summarises a state over the limit, largest key first', () => {
+  const state = { small: 1, large: 'x'.repeat(DEFAULT_STATE_LIMIT) };
+  const { state: returned, stateOmitted } = selectFinalState({ state });
+  expect(returned).toBeUndefined();
+  expect(stateOmitted.characters).toEqual(JSON.stringify(state).length);
+  expect(Object.entries(stateOmitted.keys)).toEqual([
+    ['large', DEFAULT_STATE_LIMIT + 2],
+    ['small', 1],
+  ]);
+});
+
+test('selectFinalState returns the paths asked for, null where undefined', () => {
+  const state = { form: { name: 'Ada', tags: [] }, flag: false };
+  expect(selectFinalState({ state, selection: ['form.name', 'flag', 'form.missing'] })).toEqual({
+    state: { 'form.name': 'Ada', flag: false, 'form.missing': null },
+  });
+});
+
+test('selectFinalState returns nothing for false and everything for true', () => {
+  const state = { large: 'x'.repeat(DEFAULT_STATE_LIMIT * 2) };
+  expect(selectFinalState({ state, selection: false })).toEqual({});
+  expect(selectFinalState({ state, selection: true })).toEqual({ state });
+});
+
+test('selectFinalState passes a state read error through whatever was selected', () => {
+  const state = { error: 'Could not read final state: Target closed' };
+  expect(selectFinalState({ state, selection: ['a'] })).toEqual({ state });
+  expect(selectFinalState({ state })).toEqual({ state });
+});

package/lib/docs/serverErrorStore.js

@@ -0,0 +1,54 @@
+/*
+  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 { publish } from './devEventBus.js';
+import getBuildId from './getBuildId.js';
+import isRunErrorEntry from './isRunErrorEntry.js';
+import { recordRunError } from './runErrorBuffers.js';
+
+// Module-level ring buffer of recent server-side errors (request, endpoint, MCP
+// and agent tool failures) — feeds the getBuildStatus feedback endpoint so
+// agents can see server errors, with their config source, without tailing
+// server logs. Deliberately in-memory only: entries are lost on server
+// restart, which is fine since this is a live-session debugging aid.
+const MAX_ENTRIES = 50;
+
+const entries = [];
+
+// Each entry is stamped with the build it happened under (see getBuildId).
+// An entry a journey run caused goes to that run's own
+// buffer only (see runErrorBuffers), or is dropped when the run has ended:
+// kept out of this ring and the event bus, it never reaches build-status or
+// an agent's event stream, and a run that trips many errors cannot evict the
+// developer's own. The run reports its errors in its own result.
+function push(entry) {
+  const stamped = { ...entry, buildId: getBuildId() };
+  if (isRunErrorEntry(stamped)) {
+    recordRunError({ ...stamped, store: 'server' });
+    return;
+  }
+  entries.push(stamped);
+  if (entries.length > MAX_ENTRIES) {
+    entries.shift();
+  }
+  publish({ type: 'server_error', ...stamped });
+}
+
+function list() {
+  return [...entries];
+}
+
+export default { push, list };

package/lib/docs/serverErrorStore.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 { jest } from '@jest/globals';
+
+const mockPublish = jest.fn();
+jest.unstable_mockModule('./devEventBus.js', () => ({
+  publish: mockPublish,
+}));
+jest.unstable_mockModule('./getBuildId.js', () => ({
+  default: () => '2026-01-01T00:00:00.000Z',
+}));
+
+const { default: serverErrorStore } = await import('./serverErrorStore.js');
+
+const buildId = '2026-01-01T00:00:00.000Z';
+
+test('serverErrorStore push adds an entry stamped with the current build, list returns it, and it is published as a server_error event', () => {
+  serverErrorStore.push({ message: 'first' });
+  expect(serverErrorStore.list()).toEqual([{ message: 'first', buildId }]);
+  expect(mockPublish).toHaveBeenCalledWith({ type: 'server_error', message: 'first', buildId });
+});
+
+test('serverErrorStore list returns a copy that does not alias the store', () => {
+  const entries = serverErrorStore.list();
+  entries.push({ message: 'not stored' });
+  expect(serverErrorStore.list()).toEqual([{ message: 'first', buildId }]);
+});
+
+test('serverErrorStore caps at 50 entries and drops the oldest', () => {
+  for (let i = 0; i < 60; i++) {
+    serverErrorStore.push({ index: i });
+  }
+  const entries = serverErrorStore.list();
+  expect(entries.length).toEqual(50);
+  expect(entries[0].index).toEqual(10);
+  expect(entries[49].index).toEqual(59);
+});

package/lib/docs/setupTestFixtures.mjs

@@ -33,10 +33,15 @@ function setupTestFixtures() {
 
   // lib/build/config.js reads this at import time (screenshotPage → basePath).
   write('build/config.json', {});
+  write('build/routes.json', [{ pageId: 'home', path: 'home' }]);
 
   write('build/plugins/availableTypes.json', {
     actions: {
-      SetState: { package: '@lowdefy/actions-core', originalTypeName: 'SetState', version: '5.0.0' },
+      SetState: {
+        package: '@lowdefy/actions-core',
+        originalTypeName: 'SetState',
+        version: '5.0.0',
+      },
     },
     agents: {},
     auth: { adapters: {}, callbacks: {}, events: {}, providers: {} },
@@ -58,7 +63,11 @@ function setupTestFixtures() {
       },
       server: {
         _get: { package: '@lowdefy/operators-js', originalTypeName: '_get', version: '5.0.0' },
-        _secret: { package: '@lowdefy/operators-js', originalTypeName: '_secret', version: '5.0.0' },
+        _secret: {
+          package: '@lowdefy/operators-js',
+          originalTypeName: '_secret',
+          version: '5.0.0',
+        },
       },
     },
     requests: {
@@ -105,23 +114,52 @@ function setupTestFixtures() {
     TestBlock: { type: 'object', properties: {} },
   });
   write('build/plugins/blockMetas.json', {
-    Button: { category: 'display' },
-    TestBlock: { category: 'input', valueType: 'string' },
+    Button: { category: 'display', hazards: [] },
+    TestBlock: {
+      category: 'input',
+      valueType: 'string',
+      hazards: [
+        { id: 'test-block-hazard', message: 'TestBlock does something surprising.', see: null },
+        // Same id as a framework hazard — getHazards must de-duplicate, keeping
+        // the plugin's own wording.
+        {
+          id: 'visible-false-prunes-state',
+          message: 'Plugin wording for visible: false.',
+          see: null,
+        },
+      ],
+    },
   });
   write('build/plugins/actionSchemas.json', { SetState: { type: 'object' } });
   write('build/plugins/operatorSchemas.json', { _get: { params: { type: 'object' } } });
+  write('build/plugins/operatorMetas.json', {
+    _get: {
+      hazards: [
+        { id: 'get-fixture-hazard', message: '_get fixture hazard.', see: 'operators/_get' },
+      ],
+    },
+  });
   write('build/plugins/connectionSchemas.json', {
     AxiosHttp: { schema: { type: 'object' }, requests: ['AxiosHttp'] },
   });
   write('build/plugins/requestSchemas.json', {
     AxiosHttp: { schema: { type: 'object' }, meta: { checkRead: false, checkWrite: false } },
     ReadOnlyRequest: { schema: { type: 'object' }, meta: { checkRead: true, checkWrite: false } },
-    WriteRequest: { schema: { type: 'object' }, meta: { checkRead: true, checkWrite: true } },
+    WriteRequest: {
+      schema: { type: 'object' },
+      meta: {
+        checkRead: true,
+        checkWrite: true,
+        hazards: [{ id: 'write-request-hazard', message: 'Writes are final.', see: null }],
+      },
+    },
     // No "meta" at all — some custom plugins don't declare it; treated as unknown.
     UnknownMetaRequest: { schema: { type: 'object' } },
   });
   write('build/customTypesMap.json', {
-    blocks: { TestBlock: { package: 'test-plugin', originalTypeName: 'TestBlock', version: '1.0.0' } },
+    blocks: {
+      TestBlock: { package: 'test-plugin', originalTypeName: 'TestBlock', version: '1.0.0' },
+    },
   });
   write('build/installedPluginPackages.json', [
     '@lowdefy/blocks-antd',
@@ -139,7 +177,7 @@ function setupTestFixtures() {
   );
 
   // Feedback-loop fixtures — build status, and a JIT-built page's registry,
-  // keyMap and refMap entries (see packages/build/src/build/addKeys.js for
+  // key map and ref map entries (see packages/build/src/build/addKeys.js for
   // the key path format: `[index:id]` / `[index:id:Type]`).
   write('build/buildStatus.json', {
     status: 'ok',
@@ -155,12 +193,12 @@ function setupTestFixtures() {
     unbuilt: { pageId: 'unbuilt', auth: null, refId: 'ref-unbuilt', refPath: 'pages/unbuilt.yaml' },
   });
 
-  // Mirrors the real dev keyMap shape: the skeleton build keys the whole
-  // config (`root.pages[N:id]` page stubs only), while each JIT page build
-  // runs addKeys on the page object itself — so page CONTENT keys are
-  // `root.blocks[...]` with no page segment, one `root`-keyed subtree per
-  // built page, distinguishable only via the ~k_parent chain. Tree roots
-  // reference a parent id that is never written to keyMap.
+  // Mirrors the real dev key map shape: the skeleton build keys the whole
+  // config (`root.pages[N:id]` page stubs only) in keyMap.json, while each JIT
+  // page build runs addKeys on the page object itself and writes its keys to a
+  // jitMaps/ file — so page CONTENT keys are `root.blocks[...]` with no page
+  // segment, one `root`-keyed subtree per built page, distinguishable only via
+  // the ~k_parent chain. Tree roots reference a parent id that is never written.
   write('build/keyMap.json', {
     'key-root': { key: 'root', '~k_parent': 'key-root-parent' },
     'key-pages': { key: 'root.pages', '~k_parent': 'key-root', '~r': 'ref-home' },
@@ -176,32 +214,6 @@ function setupTestFixtures() {
       '~r': 'ref-other',
       '~l': 1,
     },
-    // JIT subtree for page "home".
-    'key-home': { key: 'root', '~k_parent': 'key-home-jit-parent', '~r': 'ref-home', '~l': 1 },
-    'key-button': {
-      key: 'root.blocks[2:my_button:Button]',
-      '~k_parent': 'key-home',
-      '~r': 'ref-home',
-      '~l': 5,
-    },
-    // List item block — config ids inside lists carry the `$` placeholder;
-    // runtime block ids have array indices applied (`my_list.0.item_title`).
-    'key-list-item': {
-      key: 'root.blocks[3:my_list:List].blocks[0:my_list.$.item_title:Title]',
-      '~k_parent': 'key-home',
-      '~r': 'ref-home',
-      '~l': 9,
-    },
-    // JIT subtree for page "other" — holds a block id that also exists on
-    // home, with an IDENTICAL key shape. findConfig must scope pageId scans
-    // via the ~k_parent chain, not the key path.
-    'key-other': { key: 'root', '~k_parent': 'key-other-jit-parent', '~r': 'ref-other', '~l': 1 },
-    'key-other-button': {
-      key: 'root.blocks[0:my_button:Button]',
-      '~k_parent': 'key-other',
-      '~r': 'ref-other',
-      '~l': 4,
-    },
     // Skeleton-built page (like the default 404) — content is keyed inside
     // the global config tree with the page segment inline, and chains to the
     // shared config root rather than a page-specific one.
@@ -219,6 +231,63 @@ function setupTestFixtures() {
     },
   });
 
+  // JIT subtree for page "home".
+  write('build/jitMaps/abc123-1-1.json', {
+    keyMap: {
+      'key-home': { key: 'root', '~k_parent': 'key-home-jit-parent', '~r': 'ref-home', '~l': 1 },
+      'key-button': {
+        key: 'root.blocks[2:my_button:Button]',
+        '~k_parent': 'key-home',
+        '~r': 'ref-home',
+        '~l': 5,
+      },
+      // List item block — config ids inside lists carry the `$` placeholder;
+      // runtime block ids have array indices applied (`my_list.0.item_title`).
+      'key-list-item': {
+        key: 'root.blocks[3:my_list:List].blocks[0:my_list.$.item_title:Title]',
+        '~k_parent': 'key-home',
+        '~r': 'ref-home',
+        '~l': 9,
+      },
+    },
+    refMap: {},
+  });
+
+  // JIT subtree for page "other" — holds a block id that also exists on
+  // home, with an IDENTICAL key shape. findConfig must scope pageId scans
+  // via the ~k_parent chain, not the key path.
+  write('build/jitMaps/abc123-1-2.json', {
+    keyMap: {
+      'key-other': {
+        key: 'root',
+        '~k_parent': 'key-other-jit-parent',
+        '~r': 'ref-other',
+        '~l': 1,
+      },
+      'key-other-button': {
+        key: 'root.blocks[0:my_button:Button]',
+        '~k_parent': 'key-other',
+        '~r': 'ref-other',
+        '~l': 4,
+      },
+      // Requests over a tenant-walled and a shared connection — findConfig
+      // resolves connectionId from the per-request artifact for hazards.
+      'key-other-req-tenant': {
+        key: 'root.requests[0:req-tenant:WriteRequest]',
+        '~k_parent': 'key-other',
+        '~r': 'ref-other',
+        '~l': 12,
+      },
+      'key-other-req-shared': {
+        key: 'root.requests[1:req-shared:WriteRequest]',
+        '~k_parent': 'key-other',
+        '~r': 'ref-other',
+        '~l': 18,
+      },
+    },
+    refMap: {},
+  });
+
   write('build/refMap.json', {
     'ref-home': { parent: null, path: 'pages/home.yaml' },
     'ref-other': { parent: null, path: 'pages/other.yaml' },
@@ -227,6 +296,9 @@ function setupTestFixtures() {
 
   write('build/pages/home.json', {
     pageId: 'home',
+    // The skeleton build keys the page's auth, chaining to the global root —
+    // a real artifact carries this before any JIT-keyed block.
+    auth: { public: true, '~k': 'key-home-stub' },
     blocks: [
       { id: 'my_button', type: 'Button', '~k': 'key-button' },
       {
@@ -285,6 +357,28 @@ function setupTestFixtures() {
     properties: {},
   });
 
+  write('build/pages/other/requests/req-tenant.json', {
+    id: 'request:other:req-tenant',
+    requestId: 'req-tenant',
+    pageId: 'other',
+    connectionId: 'tenant_db',
+    type: 'WriteRequest',
+    payload: {},
+    properties: {},
+  });
+  write('build/pages/other/requests/req-shared.json', {
+    id: 'request:other:req-shared',
+    requestId: 'req-shared',
+    pageId: 'other',
+    connectionId: 'shared_db',
+    type: 'WriteRequest',
+    payload: {},
+    properties: {},
+  });
+  // Index of walled connections (packages/build/src/build/full/writeConnections.js)
+  // — shared connections are never listed here.
+  write('build/tenantConnections.json', [{ connectionId: 'tenant_db', type: 'MongoDBCollection' }]);
+
   write('build/connectionIds.json', ['axios']);
   write('build/connections/axios.json', {
     id: 'connection:axios',

package/lib/docs/shownTextSelector.js

@@ -0,0 +1,28 @@
+/*
+  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.
+*/
+
+// The name the journey runner's selector engine is registered under
+// (registerShownTextEngine.js).
+const SHOWN_TEXT_ENGINE = 'lowdefy-shown-text';
+
+// The selector for a `containing` target. The body is a JSON string, so `>>` or
+// quotes in the text never split the selector.
+function shownTextSelector(text) {
+  return `${SHOWN_TEXT_ENGINE}=${JSON.stringify(text)}`;
+}
+
+export { SHOWN_TEXT_ENGINE };
+export default shownTextSelector;