@lowdefy/shell 0.0.0-experimental-20261019052246

package/src/dev/tab/createDevTabClient.js

@@ -0,0 +1,277 @@
+/*
+  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 devPassiveHeader from '@lowdefy/node-utils/devPassiveHeader.js';
+
+import answerEval from './answerEval.js';
+import answerInspect from './answerInspect.js';
+import answerLoadState from './answerLoadState.js';
+import DEV_CLIENT_MARKER from './devClientMarker.js';
+import getShownPage from './getShownPage.js';
+import readEventStream from './readEventStream.js';
+
+const FIRST_EVENT_MS = 5000;
+const RECONNECT_MS = 1000;
+const PAGE_CHECK_MS = 500;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// The phone's platform and app id ride on every registration, so the dev server's device tools
+// know a simulator from an Android device (server-dev src/routes/reload.js).
+function deviceQuery(device) {
+  const params = new URLSearchParams({ client: DEV_CLIENT_MARKER });
+  if (type.isString(device?.platform)) {
+    params.set('platform', device.platform);
+  }
+  if (type.isString(device?.app)) {
+    params.set('app', device.app);
+  }
+  return params.toString();
+}
+
+// The instance a request names (the dev server picks it), else the one on screen.
+function requestedPage({ request, shownPage }) {
+  if (type.isString(request.instanceKey)) {
+    return {
+      pageId: request.pageId,
+      pathParams: request.pathParams,
+      instanceKey: request.instanceKey,
+    };
+  }
+  return shownPage;
+}
+
+/**
+ * Lowdefy Dev's dev-tab client: the shell joins the dev server's tab channel as a browser tab does
+ * (server-dev src/routes/reload.js, lib/docs/tabChannel.js, src/routes/devInspect.js), so agents
+ * reach it with the tools they use on a browser tab.
+ *
+ * - It registers on /api/reload, reading the event stream from a streaming fetch body. When the
+ *   stream cannot be read (no `tab` event within 5 s), it polls /api/reload?transport=poll every
+ *   second instead.
+ * - It posts the page instance on screen to /api/dev-inspect/page whenever it changes.
+ * - It names the phone's platform and app id (`device`) when it registers, for the device tools.
+ * - `reload` runs onReload. `inspect-request` and `eval-request` are answered on /api/dev-inspect
+ *   with the payloads a browser tab posts; `load-state-request` sets a state checkpoint on the page
+ *   (`{ requestId, state, verify }`); `step-request` runs a journey step (onStep), and
+ *   `inject` fakes the next device result (onInject: `{ requestId, inject: { kind, value, name } }`).
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase The dev server's URL.
+ * @param {{ platform: string, app: string }} [params.device] The phone's platform ('ios' or
+ *   'android') and app id (bundle id or package).
+ * @param {Function} params.fetch The Fetch API for posts and polls (pairing and shell headers).
+ * @param {Function} params.streamFetch A Fetch API whose response body streams (expo/fetch), with
+ *   the same headers.
+ * @param {() => Object|null} params.getLowdefy The open app's lowdefy object.
+ * @param {() => Promise} params.onReload
+ * @param {({ injection }) => Object} params.onInject
+ * @param {({ step, page }) => Promise<Object>} params.onStep
+ * @param {(message: string) => void} [params.log]
+ * @param {number} [params.pollInterval] Ms between polls.
+ */
+function createDevTabClient({
+  apiBase,
+  device,
+  fetch,
+  getLowdefy,
+  log = () => undefined,
+  onInject,
+  onReload,
+  onStep,
+  pollInterval = 1000,
+  streamFetch,
+}) {
+  let stopped = false;
+  let tabId = null;
+  let postedPage = null;
+  let streamAbort = null;
+  let pageTimer = null;
+
+  async function post(path, body) {
+    try {
+      await fetch(`${apiBase}/api/dev-inspect${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    } catch (error) {
+      // A failed answer leaves the agent's request to time out on the server.
+      log(`Dev tab: could not reach the dev server (${error.message}).`);
+    }
+  }
+
+  function postShownPage() {
+    const page = getShownPage(getLowdefy());
+    if (tabId === null || page === null) {
+      return;
+    }
+    const key = `${tabId}|${page.instanceKey}`;
+    if (key === postedPage) {
+      return;
+    }
+    postedPage = key;
+    post('/page', { tabId, ...page });
+  }
+
+  async function respond({ event, request }) {
+    const lowdefy = getLowdefy();
+    const page = requestedPage({ request, shownPage: getShownPage(lowdefy) });
+    if (event === 'inspect-request') {
+      return answerInspect({ lowdefy, page });
+    }
+    if (event === 'eval-request') {
+      return answerEval({ expression: request.expression, lowdefy, page });
+    }
+    if (event === 'load-state-request') {
+      return answerLoadState({ lowdefy, page, state: request.state, verify: request.verify });
+    }
+    if (event === 'inject') {
+      return onInject({ injection: request.inject });
+    }
+    return onStep({ step: request.step, page });
+  }
+
+  async function answer({ event, data }) {
+    let requestId;
+    try {
+      const request = JSON.parse(data);
+      requestId = request.requestId;
+      const result = await respond({ event, request });
+      await post('', { requestId, result });
+    } catch (error) {
+      await post('', { requestId, result: { error: error.message } });
+    }
+  }
+
+  async function handleEvent({ event, data }) {
+    switch (event) {
+      case 'tab':
+        tabId = JSON.parse(data).tabId;
+        postedPage = null;
+        log(`Dev tab: joined the dev server as tab ${tabId}.`);
+        postShownPage();
+        return;
+      case 'reload':
+        log('Dev tab: the dev server rebuilt the app; reloading.');
+        await onReload();
+        return;
+      case 'inspect-request':
+      case 'eval-request':
+      case 'load-state-request':
+      case 'step-request':
+      case 'inject':
+        await answer({ event, data });
+        return;
+      default:
+        // ping
+        return;
+    }
+  }
+
+  function dispatch(message) {
+    handleEvent(message).catch((error) =>
+      log(`Dev tab: ${message.event} failed: ${error.message}`)
+    );
+  }
+
+  // Resolves 'ended' when an open stream ends (the dev server restarted), 'unreachable' when the
+  // server did not answer, and 'unsupported' when no event arrived over a stream that opened.
+  async function runStream() {
+    let received = false;
+    const controller = new AbortController();
+    streamAbort = controller;
+    const firstEventTimer = setTimeout(() => {
+      if (!received) controller.abort();
+    }, FIRST_EVENT_MS);
+    try {
+      const res = await streamFetch(`${apiBase}/api/reload?${deviceQuery(device)}`, {
+        headers: { Accept: 'text/event-stream' },
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        return 'unreachable';
+      }
+      if (type.isNone(res.body?.getReader)) {
+        return 'unsupported';
+      }
+      await readEventStream({
+        body: res.body,
+        onEvent: (message) => {
+          received = true;
+          dispatch(message);
+        },
+      });
+      return 'ended';
+    } catch (error) {
+      if (received) return 'ended';
+      return controller.signal.aborted ? 'unsupported' : 'unreachable';
+    } finally {
+      clearTimeout(firstEventTimer);
+    }
+  }
+
+  async function runPolls() {
+    while (!stopped) {
+      const tabQuery = tabId === null ? '' : `&tabId=${encodeURIComponent(tabId)}`;
+      try {
+        const res = await fetch(
+          `${apiBase}/api/reload?transport=poll&${deviceQuery(device)}${tabQuery}`,
+          { headers: { [devPassiveHeader]: '1' } }
+        );
+        if (res.ok) {
+          const { events } = await res.json();
+          events.forEach(dispatch);
+        }
+      } catch (error) {
+        // The dev server is restarting: poll again.
+      }
+      await sleep(pollInterval);
+    }
+  }
+
+  async function run() {
+    while (!stopped) {
+      const outcome = await runStream();
+      if (stopped) return;
+      if (outcome === 'unsupported') {
+        log('Dev tab: the event stream could not be read; polling every second.');
+        tabId = null;
+        await runPolls();
+        return;
+      }
+      await sleep(RECONNECT_MS);
+    }
+  }
+
+  function start() {
+    pageTimer = setInterval(postShownPage, PAGE_CHECK_MS);
+    run();
+  }
+
+  function stop() {
+    stopped = true;
+    streamAbort?.abort();
+    clearInterval(pageTimer);
+  }
+
+  return { getTabId: () => tabId, start, stop };
+}
+
+export default createDevTabClient;

package/src/dev/tab/createDevTabClient.test.js

@@ -0,0 +1,314 @@
+/*
+  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';
+import { waitFor } from '@testing-library/react-native';
+import { get, serializer } from '@lowdefy/helpers';
+
+import createDevTabClient from './createDevTabClient.js';
+import DEV_CLIENT_MARKER from './devClientMarker.js';
+import { DEV_CLIENT_MARKER as BUNDLE_MARKER } from '../../../shellVariant.js';
+
+// The tab channel's payloads, shared with the dev server's tests
+// (server-dev src/routes/devInspect.test.mjs): a phone answers in a browser tab's shape.
+const fixtures = require('../../../../servers/server-dev/test/tabChannelFixtures.json');
+
+const apiBase = 'http://192.168.1.20:3000';
+
+function createStream() {
+  const encoder = new TextEncoder();
+  const chunks = [];
+  let waiting = null;
+  let closed = false;
+  function deliver(result) {
+    const resolve = waiting;
+    waiting = null;
+    resolve(result);
+  }
+  return {
+    body: {
+      getReader: () => ({
+        read: () => {
+          if (chunks.length > 0) return Promise.resolve({ done: false, value: chunks.shift() });
+          if (closed) return Promise.resolve({ done: true });
+          return new Promise((resolve) => {
+            waiting = resolve;
+          });
+        },
+      }),
+    },
+    send(event, data) {
+      const value = encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+      if (waiting) deliver({ done: false, value });
+      else chunks.push(value);
+    },
+    close() {
+      closed = true;
+      if (waiting) deliver({ done: true });
+    },
+  };
+}
+
+// The app-level lowdefy object with the fixture page on screen at /tickets/7.
+function createLowdefy() {
+  const context = {
+    ...fixtures.pageContext,
+    state: { ...fixtures.pageContext.state },
+    pathParams: fixtures.page.pathParams,
+    _internal: {
+      parser: {
+        parse: ({ input }) => ({ output: get(context.state, input._state), errors: [] }),
+      },
+      State: {
+        set: (key, value) => {
+          context.state[key] = value;
+        },
+      },
+      update: jest.fn(),
+    },
+  };
+  return {
+    basePath: '',
+    pathMemory: new Map([['tickets/7', fixtures.page]]),
+    contexts: { [fixtures.page.instanceKey]: context },
+    inputs: { [fixtures.page.instanceKey]: fixtures.app.input },
+    lowdefyGlobal: fixtures.app.lowdefyGlobal,
+    user: fixtures.app.user,
+    _internal: {
+      globals: {
+        window: {
+          location: {
+            href: `${apiBase}/tickets/7${fixtures.app.urlQuery}`,
+            search: fixtures.app.urlQuery,
+          },
+        },
+      },
+    },
+  };
+}
+
+function setup({ device, stream = createStream(), streamFetch, pollEvents = [] } = {}) {
+  const fetch = jest.fn(async (url) => {
+    if (url.includes('transport=poll')) {
+      return { ok: true, json: async () => ({ tabId: 'phone', events: pollEvents.splice(0) }) };
+    }
+    return { ok: true, json: async () => ({ ok: true }) };
+  });
+  const onReload = jest.fn(async () => undefined);
+  const onStep = jest.fn(async ({ step }) => ({ ok: true, ran: step }));
+  const onInject = jest.fn(({ injection }) => ({ ok: true, kind: injection.kind, pending: 1 }));
+  const client = createDevTabClient({
+    apiBase,
+    device,
+    fetch,
+    getLowdefy: createLowdefy,
+    onInject,
+    onReload,
+    onStep,
+    pollInterval: 10,
+    streamFetch: streamFetch ?? jest.fn(async () => ({ ok: true, body: stream.body })),
+  });
+  client.start();
+  return { client, fetch, onInject, onReload, onStep, stream };
+}
+
+function posts(fetch, path) {
+  return fetch.mock.calls
+    .filter(([url, init]) => url === `${apiBase}/api/dev-inspect${path}` && init.method === 'POST')
+    .map(([, init]) => JSON.parse(init.body));
+}
+
+let running;
+afterEach(() => {
+  running?.client.stop();
+  running?.stream.close();
+});
+
+test('the marker a release bundle is checked for is the one the client sends', () => {
+  expect(DEV_CLIENT_MARKER).toBe(BUNDLE_MARKER);
+});
+
+test('the shell registers as a tab on the reload stream and posts the page it shows', async () => {
+  running = setup();
+  const { client, fetch, stream } = running;
+  expect(posts(fetch, '/page')).toEqual([]);
+  stream.send('tab', { tabId: 'phone' });
+  await waitFor(() =>
+    expect(posts(fetch, '/page')).toEqual([{ tabId: 'phone', ...fixtures.page }])
+  );
+  expect(client.getTabId()).toBe('phone');
+});
+
+test('the stream is opened on /api/reload with the dev client marker', async () => {
+  const stream = createStream();
+  const streamFetch = jest.fn(async () => ({ ok: true, body: stream.body }));
+  running = setup({ stream, streamFetch });
+  await waitFor(() => expect(streamFetch).toHaveBeenCalled());
+  const [url, init] = streamFetch.mock.calls[0];
+  expect(url).toBe(`${apiBase}/api/reload?client=${DEV_CLIENT_MARKER}`);
+  expect(init.headers).toEqual({ Accept: 'text/event-stream' });
+});
+
+test('the stream names the phone platform and app id for the device tools', async () => {
+  const stream = createStream();
+  const streamFetch = jest.fn(async () => ({ ok: true, body: stream.body }));
+  running = setup({ device: { platform: 'ios', app: 'com.lowdefy.dev' }, stream, streamFetch });
+  await waitFor(() => expect(streamFetch).toHaveBeenCalled());
+  expect(streamFetch.mock.calls[0][0]).toBe(
+    `${apiBase}/api/reload?client=${DEV_CLIENT_MARKER}&platform=ios&app=com.lowdefy.dev`
+  );
+});
+
+test('a load-state-request sets the checkpoint state on the page and answers the keys it verified', async () => {
+  running = setup();
+  running.stream.send(fixtures.loadStateRequest.event, {
+    requestId: 'r-load',
+    ...fixtures.page,
+    ...fixtures.loadStateRequest.payload,
+  });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  expect(posts(running.fetch, '')[0]).toEqual({
+    requestId: 'r-load',
+    result: fixtures.loadStateResult,
+  });
+});
+
+test('a reload event reloads the app', async () => {
+  running = setup();
+  running.stream.send('reload', {});
+  await waitFor(() => expect(running.onReload).toHaveBeenCalledTimes(1));
+});
+
+test('an inspect-request is answered with the payload a browser tab posts', async () => {
+  running = setup();
+  running.stream.send(fixtures.inspectRequest.event, {
+    requestId: 'r-inspect',
+    ...fixtures.page,
+    ...fixtures.inspectRequest.payload,
+  });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  const [answer] = posts(running.fetch, '');
+  expect(answer.requestId).toBe('r-inspect');
+  expect(serializer.deserializeFromString(answer.result)).toEqual(fixtures.inspectResult);
+});
+
+test('an eval-request is answered with the payload a browser tab posts', async () => {
+  running = setup();
+  running.stream.send(fixtures.evalRequest.event, {
+    requestId: 'r-eval',
+    ...fixtures.page,
+    ...fixtures.evalRequest.payload,
+  });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  const [answer] = posts(running.fetch, '');
+  expect(answer.requestId).toBe('r-eval');
+  expect({
+    value: serializer.deserializeFromString(answer.result.value),
+    errors: answer.result.errors,
+  }).toEqual(fixtures.evalResult);
+});
+
+test('a request for a page with no live context is answered with an error', async () => {
+  running = setup();
+  running.stream.send('inspect-request', {
+    requestId: 'r-gone',
+    pageId: 'home',
+    pathParams: {},
+    instanceKey: 'page:home',
+  });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  expect(posts(running.fetch, '')[0]).toEqual({
+    requestId: 'r-gone',
+    result: { error: 'No live context for page "home".' },
+  });
+});
+
+test('a step-request runs the journey step and posts its result', async () => {
+  running = setup();
+  running.stream.send('step-request', {
+    requestId: 'r-step',
+    ...fixtures.page,
+    step: { click: 'save' },
+  });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  expect(running.onStep).toHaveBeenCalledWith({
+    step: { click: 'save' },
+    page: fixtures.page,
+  });
+  expect(posts(running.fetch, '')[0]).toEqual({
+    requestId: 'r-step',
+    result: { ok: true, ran: { click: 'save' } },
+  });
+});
+
+test('a failed step is answered with its error', async () => {
+  running = setup();
+  running.onStep.mockImplementation(async () => {
+    throw new Error('Block "save" is not on page "ticket".');
+  });
+  running.stream.send('step-request', { requestId: 'r-fail', step: { click: 'save' } });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  expect(posts(running.fetch, '')[0].result).toEqual({
+    error: 'Block "save" is not on page "ticket".',
+  });
+});
+
+test('an inject request fakes the next device result and posts what was queued', async () => {
+  running = setup();
+  running.stream.send('inject', {
+    requestId: 'r-inject',
+    inject: { kind: 'scan', value: { data: 'JOB-42', type: 'qr' } },
+  });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  expect(running.onInject).toHaveBeenCalledWith({
+    injection: { kind: 'scan', value: { data: 'JOB-42', type: 'qr' } },
+  });
+  expect(posts(running.fetch, '')[0]).toEqual({
+    requestId: 'r-inject',
+    result: { ok: true, kind: 'scan', pending: 1 },
+  });
+});
+
+test('a refused injection is answered with why', async () => {
+  running = setup();
+  running.onInject.mockImplementation(() => {
+    throw new Error('A scan injection needs { data }. Received "JOB-42".');
+  });
+  running.stream.send('inject', { requestId: 'r-bad', inject: { kind: 'scan', value: 'JOB-42' } });
+  await waitFor(() => expect(posts(running.fetch, '')).toHaveLength(1));
+  expect(posts(running.fetch, '')[0].result).toEqual({
+    error: 'A scan injection needs { data }. Received "JOB-42".',
+  });
+});
+
+test('without a readable stream the shell polls every interval, as a passive caller', async () => {
+  const pollEvents = [
+    { event: 'tab', data: JSON.stringify({ tabId: 'phone' }) },
+    { event: 'reload', data: '{}' },
+  ];
+  running = setup({
+    pollEvents,
+    streamFetch: jest.fn(async () => ({ ok: true, body: null })),
+  });
+  await waitFor(() => expect(running.onReload).toHaveBeenCalledTimes(1));
+  await waitFor(() => expect(posts(running.fetch, '/page')).toHaveLength(1));
+  const polls = running.fetch.mock.calls.filter(([url]) => url.includes('transport=poll'));
+  expect(polls[0][0]).toBe(`${apiBase}/api/reload?transport=poll&client=${DEV_CLIENT_MARKER}`);
+  expect(polls[0][1].headers).toEqual({ 'x-lowdefy-passive': '1' });
+  await waitFor(() =>
+    expect(running.fetch.mock.calls.some(([url]) => url.endsWith('&tabId=phone'))).toBe(true)
+  );
+});

package/src/dev/tab/devClientMarker.js

@@ -0,0 +1,22 @@
+/*
+  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.
+*/
+
+// Sent with every connection the dev-tab client opens, so the dev server knows a shell's tab from a
+// browser's, and so a release bundle that holds it fails scripts/checkReleaseBundle.mjs. Keep it in
+// step with shellVariant.js.
+const DEV_CLIENT_MARKER = 'lowdefy-dev-tab-client';
+
+export default DEV_CLIENT_MARKER;

package/src/dev/tab/devClientMarker.test.js

@@ -0,0 +1,23 @@
+/*
+  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 DEV_CLIENT_MARKER from './devClientMarker.js';
+
+const { DEV_CLIENT_MARKER: RELEASE_CHECK_MARKER } = require('../../../shellVariant.js');
+
+test('the dev-tab client marker matches the one the release bundle check looks for', () => {
+  expect(DEV_CLIENT_MARKER).toBe(RELEASE_CHECK_MARKER);
+});

package/src/dev/tab/findPageContext.js

@@ -0,0 +1,43 @@
+/*
+  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';
+
+// `page "ticket"`, or `page "ticket" (tickets/s/1)` for an instance of a page with placeholders,
+// whose instance key holds the path its values build. Worded as the browser tab words it. A
+// screen's key ends in `@{instanceId}`, its route instance, which is left out.
+function describePage({ pageId, instanceKey }) {
+  const pageKey = instanceKey.split('@')[0];
+  const hashIndex = pageKey.indexOf('#');
+  if (hashIndex === -1) {
+    return `page "${pageId}"`;
+  }
+  return `page "${pageId}" (${pageKey.slice(hashIndex + 1)})`;
+}
+
+// The engine context of a page instance: `{ context }`, or `{ error }` as a browser tab answers it.
+function findPageContext({ lowdefy, page }) {
+  if (type.isNone(page)) {
+    return { error: 'No page has rendered in this tab yet.' };
+  }
+  const context = lowdefy?.contexts?.[page.instanceKey];
+  if (type.isNone(context)) {
+    return { error: `No live context for ${describePage(page)}.` };
+  }
+  return { context };
+}
+
+export default findPageContext;