@lowdefy/shell 3.23.2 → 7.2.0

package/src/session/createAppSession.test.js

@@ -0,0 +1,391 @@
+/*
+  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 createAppSession from './createAppSession.js';
+import createFakeServer, { header } from '../test/createFakeServer.js';
+import createMemoryCacheStore from '../test/createMemoryCacheStore.js';
+import createNetworkError from '../test/createNetworkError.js';
+import createMemoryStore from '../host/createMemoryStore.js';
+import { createPages, createRoot } from '../test/fixtures.js';
+
+const apiBase = 'https://field.example.com';
+const app = { id: 'field', name: 'Field', urls: { production: apiBase } };
+
+function createServer(overrides = {}) {
+  return createFakeServer({
+    caller: 'c-anon; roles=r0',
+    root: createRoot(),
+    rootEtag: '"root-1"',
+    pages: createPages([
+      ['today', 'today', '"p-today-1"'],
+      ['jobs', 'jobs', '"p-jobs-1"'],
+      ['jobs/{job_id}', 'job', '"p-job-1"'],
+    ]),
+    ...overrides,
+  });
+}
+
+function createSession({
+  server,
+  cacheStore = createMemoryCacheStore(),
+  kv = createMemoryStore(),
+}) {
+  const tokenStore = { get: () => 'token-1' };
+  const session = createAppSession({
+    apiBase,
+    app,
+    cacheStore,
+    fetch: server.fetch,
+    kv,
+    tokenStore,
+  });
+  return { cacheStore, kv, session };
+}
+
+function callsTo(server, pathname) {
+  return server.fetch.mock.calls.filter(([url]) => new URL(url).pathname === pathname);
+}
+
+test('a first start fetches the root, the user and every page in the index', async () => {
+  const server = createServer({ user: { id: 'u1' } });
+  const { session } = createSession({ server });
+  expect(session.getState().status).toBe('loading');
+  await session.start();
+  const state = session.getState();
+  expect(state.status).toBe('ready');
+  expect(state.user).toEqual({ id: 'u1' });
+  expect(state.buildId).toBe('build-1');
+  expect(Object.keys(state.pages).sort()).toEqual(['job', 'jobs', 'today']);
+  expect(state.pages.job).toEqual(
+    expect.objectContaining({ hash: 'h-job-1', etag: '"p-job-1"', buildId: 'build-1' })
+  );
+  expect(state.rootConfig.pagePaths).toEqual({
+    today: 'today',
+    jobs: 'jobs',
+    job: 'jobs/{job_id}',
+  });
+  expect(callsTo(server, '/api/page/jobs/%7Bjob_id%7D')).toHaveLength(1);
+});
+
+test('every shell call carries the session token as a bearer token', async () => {
+  const server = createServer();
+  const { session } = createSession({ server });
+  await session.start();
+  server.fetch.mock.calls.forEach(([, init]) => {
+    expect(header(init, 'Authorization')).toBe('Bearer token-1');
+  });
+});
+
+test('pages are fetched at most 4 at a time', async () => {
+  const pageIndex = Array.from({ length: 10 }, (_, i) => ({
+    path: `p${i}`,
+    pageId: `p${i}`,
+    hash: `h${i}`,
+    typesKey: 'carried',
+  }));
+  const server = createServer({
+    root: createRoot({ pageIndex }),
+    pages: createPages(pageIndex.map((entry) => [entry.path, entry.pageId, `"${entry.hash}"`])),
+  });
+  let inFlight = 0;
+  let most = 0;
+  const serve = server.fetch.getMockImplementation();
+  server.fetch.mockImplementation(async (url, init) => {
+    inFlight += 1;
+    most = Math.max(most, inFlight);
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    inFlight -= 1;
+    return serve(url, init);
+  });
+  const { session } = createSession({ server });
+  await session.start();
+  expect(Object.keys(session.getState().pages)).toHaveLength(10);
+  expect(most).toBeLessThanOrEqual(4);
+});
+
+describe('cache keying', () => {
+  test('the cache is kept per app, caller and roles', async () => {
+    const server = createServer({ caller: 'c-ada; session=s1; roles=r-staff' });
+    const { cacheStore, session } = createSession({ server });
+    await session.start();
+    expect(session.getState().cacheKey).toBe('field:c-ada:r-staff');
+    expect([...cacheStore.roots.keys()]).toEqual(['field:c-ada:r-staff']);
+    expect([...cacheStore.pages.get('field:c-ada:r-staff').keys()].sort()).toEqual([
+      'job',
+      'jobs',
+      'today',
+    ]);
+  });
+
+  test('a start renders the last cache at once, before the server answers', async () => {
+    const server = createServer({ caller: 'c-ada; roles=r-staff' });
+    const cacheStore = createMemoryCacheStore();
+    const kv = createMemoryStore();
+    await createSession({ server, cacheStore, kv }).session.start();
+
+    let answer;
+    const offline = { fetch: jest.fn(() => new Promise((resolve) => (answer = resolve))) };
+    const { session } = createSession({ server: offline, cacheStore, kv });
+    const started = session.start();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    const state = session.getState();
+    expect(state.status).toBe('ready');
+    expect(state.cacheKey).toBe('field:c-ada:r-staff');
+    expect(Object.keys(state.pages).sort()).toEqual(['job', 'jobs', 'today']);
+    expect(offline.fetch).toHaveBeenCalled();
+    answer(Promise.reject(createNetworkError()));
+    await started;
+  });
+
+  test('with no signal the app keeps its cached pages', async () => {
+    const server = createServer();
+    const cacheStore = createMemoryCacheStore();
+    const kv = createMemoryStore();
+    await createSession({ server, cacheStore, kv }).session.start();
+    const offline = {
+      fetch: jest.fn(async () => Promise.reject(createNetworkError())),
+    };
+    const { session } = createSession({ server: offline, cacheStore, kv });
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    await session.start();
+    expect(session.getState().status).toBe('ready');
+    expect(Object.keys(session.getState().pages)).toHaveLength(3);
+    // No signal is not a fault.
+    expect(consoleError).not.toHaveBeenCalled();
+    consoleError.mockRestore();
+  });
+
+  test('a sync the server fails while the cache serves the app is reported', async () => {
+    const server = createServer();
+    const cacheStore = createMemoryCacheStore();
+    const kv = createMemoryStore();
+    await createSession({ server, cacheStore, kv }).session.start();
+    const failing = {
+      fetch: jest.fn(async () => ({
+        ok: false,
+        status: 500,
+        headers: { get: () => null },
+        json: async () => ({ message: 'Internal server error.' }),
+      })),
+    };
+    const { session } = createSession({ server: failing, cacheStore, kv });
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    await session.start();
+    expect(session.getState().status).toBe('ready');
+    // No page has made a core yet, so the report goes to the device console.
+    expect(consoleError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'Internal server error.', status: 500 })
+    );
+    consoleError.mockRestore();
+  });
+
+  test('with no signal and no cache the app shows the error', async () => {
+    const offline = {
+      fetch: jest.fn(async () => Promise.reject(createNetworkError())),
+    };
+    const { session } = createSession({ server: offline });
+    await session.start();
+    expect(session.getState().status).toBe('error');
+    expect(session.getState().error.message).toBe('Network request failed');
+  });
+
+  test('an app without mobile pages shows an error', async () => {
+    const server = createServer();
+    server.fetch.mockImplementation(async () => ({
+      ok: false,
+      status: 404,
+      headers: { get: () => null },
+      json: async () => ({}),
+    }));
+    const { session } = createSession({ server });
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    await session.start();
+    expect(session.getState().error.message).toBe('This app has no mobile pages.');
+    expect(consoleError).toHaveBeenCalledWith(session.getState().error);
+    consoleError.mockRestore();
+  });
+});
+
+describe('ETag reuse', () => {
+  test('a sync revalidates the root with its ETag and keeps it on a 304', async () => {
+    const server = createServer();
+    const { session } = createSession({ server });
+    await session.start();
+    const { root, rootConfig } = session.getState();
+    server.fetch.mockClear();
+    await session.sync();
+    const [rootCall] = callsTo(server, '/api/mobile/root');
+    expect(header(rootCall[1], 'If-None-Match')).toBe('"root-1"');
+    expect(session.getState().root).toBe(root);
+    expect(session.getState().rootConfig).toBe(rootConfig);
+    expect(server.fetch.mock.calls.filter(([url]) => url.includes('/api/page/'))).toHaveLength(0);
+  });
+
+  test('only pages whose hash changed are fetched again, revalidated with their ETag', async () => {
+    const server = createServer();
+    const { session } = createSession({ server });
+    await session.start();
+    const before = session.getState().pages;
+    server.state.root = createRoot({
+      buildId: 'build-2',
+      pageIndex: [
+        { path: 'today', pageId: 'today', hash: 'h-today-2', typesKey: 'carried' },
+        { path: 'jobs', pageId: 'jobs', hash: 'h-jobs-1', typesKey: 'carried' },
+      ],
+    });
+    server.state.rootEtag = '"root-2"';
+    server.state.pages.today = {
+      pageConfig: { ...before.today.pageConfig, v: 2 },
+      etag: '"p-today-2"',
+    };
+    server.fetch.mockClear();
+    await session.sync();
+    const pageCalls = server.fetch.mock.calls.filter(([url]) => url.includes('/api/page/'));
+    expect(pageCalls.map(([url]) => url)).toEqual([`${apiBase}/api/page/today`]);
+    expect(header(pageCalls[0][1], 'If-None-Match')).toBe('"p-today-1"');
+    const state = session.getState();
+    expect(state.buildId).toBe('build-2');
+    expect(state.pages.today.pageConfig.v).toBe(2);
+    expect(state.pages.jobs).toBe(before.jobs);
+    expect(state.pages.job).toBeUndefined();
+  });
+
+  test('a page answered with a 304 is kept under its new hash', async () => {
+    const server = createServer();
+    const { session } = createSession({ server });
+    await session.start();
+    server.state.root = createRoot({
+      pageIndex: [{ path: 'today', pageId: 'today', hash: 'h-today-2', typesKey: 'carried' }],
+    });
+    server.state.rootEtag = '"root-2"';
+    await session.sync();
+    expect(session.getState().pages.today.hash).toBe('h-today-2');
+    expect(session.getState().pages.today.etag).toBe('"p-today-1"');
+  });
+});
+
+describe('caller changes', () => {
+  test("a root answered as another caller resets the app onto that caller's cache", async () => {
+    const server = createServer({ caller: 'c-ada; roles=r-staff' });
+    const { cacheStore, session } = createSession({ server });
+    await session.start();
+    const { generation, homeRequests, lowdefy } = session.getState();
+    server.state.caller = 'c-ben; roles=r-admin';
+    server.state.root = createRoot({
+      pageIndex: [{ path: 'today', pageId: 'today', hash: 'h-today-admin', typesKey: 'carried' }],
+    });
+    server.state.rootEtag = '"root-admin"';
+    await session.sync();
+    const state = session.getState();
+    expect(state.cacheKey).toBe('field:c-ben:r-admin');
+    expect(state.generation).toBe(generation + 1);
+    expect(state.homeRequests).toBe(homeRequests + 1);
+    expect(state.lowdefy).not.toBe(lowdefy);
+    expect(Object.keys(state.pages)).toEqual(['today']);
+    expect(state.pages.today.hash).toBe('h-today-admin');
+    // The first caller's cache is kept for when they come back.
+    expect([...cacheStore.roots.keys()].sort()).toEqual([
+      'field:c-ada:r-staff',
+      'field:c-ben:r-admin',
+    ]);
+    expect(session.takeHomeRequest()).toBe(true);
+    expect(session.takeHomeRequest()).toBe(false);
+  });
+
+  test('onCallerChanged drops the screens, refetches the root under the new key and goes home', async () => {
+    const server = createServer({ caller: 'c-ada; roles=r-staff' });
+    const { session } = createSession({ server });
+    await session.start();
+    const before = session.getState();
+    const statuses = [];
+    session.subscribe(() => statuses.push(session.getState().status));
+    server.state.caller = 'c-anon; roles=r0';
+    const reset = session.handleCallerChanged();
+    expect(session.getState().status).toBe('loading');
+    await reset;
+    const state = session.getState();
+    expect(statuses[0]).toBe('loading');
+    expect(state.status).toBe('ready');
+    expect(state.cacheKey).toBe('field:c-anon:r0');
+    expect(state.generation).toBeGreaterThan(before.generation);
+    expect(state.homeRequests).toBeGreaterThan(before.homeRequests);
+    expect(session.takeHomeRequest()).toBe(true);
+  });
+});
+
+test('onBuildChanged syncs and rebuilds every screen on the new build', async () => {
+  const server = createServer();
+  const { session } = createSession({ server });
+  await session.start();
+  const before = session.getState();
+  server.state.root = createRoot({ buildId: 'build-2' });
+  server.state.rootEtag = '"root-2"';
+  await session.handleBuildChanged();
+  const state = session.getState();
+  expect(state.buildId).toBe('build-2');
+  expect(state.generation).toBe(before.generation + 1);
+  expect(state.lowdefy).toEqual({ buildId: 'build-2' });
+  expect(state.homeRequests).toBe(before.homeRequests);
+});
+
+describe('loadPage', () => {
+  test('a cached page with a hash is not fetched again on a visit', async () => {
+    const server = createServer();
+    const { session } = createSession({ server });
+    await session.start();
+    server.fetch.mockClear();
+    const entry = session.getState().root.pageIndex[0];
+    await session.loadPage({ entry, path: 'today' });
+    expect(server.fetch).not.toHaveBeenCalled();
+  });
+
+  test('a dev page (no hash) is fetched on every visit by its path', async () => {
+    const pageIndex = [{ path: 'jobs/{job_id}', pageId: 'job' }];
+    const server = createServer({
+      root: createRoot({ pageIndex, typeSets: {} }),
+      pages: createPages([['jobs/7', 'job', '"dev-1"']]),
+    });
+    const { session } = createSession({ server });
+    await session.start();
+    expect(session.getState().pages).toEqual({});
+    await session.loadPage({ entry: pageIndex[0], path: 'jobs/7' });
+    await session.loadPage({ entry: pageIndex[0], path: 'jobs/7' });
+    const pageCalls = callsTo(server, '/api/page/jobs/7');
+    expect(pageCalls).toHaveLength(2);
+    expect(header(pageCalls[1][1], 'If-None-Match')).toBe('"dev-1"');
+    expect(session.getState().pages.job.pageConfig.pageId).toBe('job');
+  });
+
+  test('a dynamic page is fetched on every visit', async () => {
+    const server = createServer();
+    server.state.pages.today.pageConfig.dynamic = true;
+    const { session } = createSession({ server });
+    await session.start();
+    server.fetch.mockClear();
+    await session.loadPage({ entry: session.getState().root.pageIndex[0], path: 'today' });
+    expect(callsTo(server, '/api/page/today')).toHaveLength(1);
+  });
+});
+
+test('fetchOtherPage reports a web page for the shell to open in the browser', async () => {
+  const server = createServer({ otherSurfaces: { reports: { pageConfig: null, surface: 'web' } } });
+  const { session } = createSession({ server });
+  await session.start();
+  expect(await session.fetchOtherPage('reports')).toEqual({ notFound: true, surface: 'web' });
+  expect(await session.fetchOtherPage('nothing')).toEqual({ notFound: true, surface: null });
+});

package/src/session/getPageView.js

@@ -0,0 +1,59 @@
+/*
+  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 node-utils matcher is the one the server matches page paths with; this file imports only
+// @lowdefy/helpers.
+import matchPagePath from '@lowdefy/node-utils/matchPagePath.js';
+
+import encodePagePath from '../sync/encodePagePath.js';
+import findMissingPageTypes from '../types/findMissingPageTypes.js';
+import isShellTooOld from '../version/isShellTooOld.js';
+
+/**
+ * What a screen showing `path` draws, from the session state:
+ * - `{ view: 'update', reason }`: the shell is older than minShellVersion, or lacks a type the page
+ *   needs ("Update the app to open this page"). Other pages still open.
+ * - `{ view: 'other', path }`: no mobile page has this path (a web page, or none).
+ * - `{ view: 'loading', entry, pathParams }`: the page is not in the cache yet.
+ * - `{ view: 'page', entry, page, pathParams }`: render it.
+ *
+ * @param {Object} params
+ * @param {Object} params.shell The shell config: `version` and `typeManifest`.
+ * @param {Object} params.state The session state (createAppSession).
+ * @param {string} params.path The route's path, without the leading "/".
+ */
+function getPageView({ path, shell, state }) {
+  const { pages, root } = state;
+  if (isShellTooOld({ minShellVersion: root.minShellVersion, shellVersion: shell.version })) {
+    return { view: 'update', reason: 'minShellVersion' };
+  }
+  const match = matchPagePath({ routes: root.pageIndex, path: encodePagePath(path) });
+  if (match === null) {
+    return { view: 'other', path };
+  }
+  const entry = root.pageIndex.find((indexEntry) => indexEntry.pageId === match.pageId);
+  const page = pages[entry.pageId];
+  const missing = findMissingPageTypes({ entry, manifest: shell.typeManifest, page, root });
+  if (missing.length > 0) {
+    return { view: 'update', reason: 'types', missing };
+  }
+  if (page === undefined) {
+    return { view: 'loading', entry, pathParams: match.pathParams };
+  }
+  return { view: 'page', entry, page, pathParams: match.pathParams };
+}
+
+export default getPageView;

package/src/session/getPageView.test.js

@@ -0,0 +1,137 @@
+/*
+  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 getPageView from './getPageView.js';
+import { createPage, createRoot, shell } from '../test/fixtures.js';
+
+const pageIndex = [
+  { path: 'today', pageId: 'today', hash: 'h1', typesKey: 'carried' },
+  { path: 'map', pageId: 'map', hash: 'h2', typesKey: 'newBlock' },
+  { path: 'report', pageId: 'report', hash: 'h3', typesKey: 'nextMajor' },
+  { path: 'jobs/{job_id}', pageId: 'job', hash: 'h4', typesKey: 'carried' },
+];
+
+function createState({ root = createRoot({ pageIndex }), pages } = {}) {
+  return {
+    root,
+    pages: pages ?? {
+      today: { hash: 'h1', pageConfig: createPage('today') },
+      map: { hash: 'h2', pageConfig: createPage('map') },
+      report: { hash: 'h3', pageConfig: createPage('report') },
+      job: { hash: 'h4', pageConfig: createPage('job') },
+    },
+  };
+}
+
+describe('the type check', () => {
+  test('a page needing a block the shell lacks shows the update screen, other pages open', () => {
+    const state = createState();
+    expect(getPageView({ path: 'map', shell, state })).toEqual({
+      view: 'update',
+      reason: 'types',
+      missing: [{ category: 'blocks', type: 'Map', package: '@lowdefy/blocks-native', version: 7 }],
+    });
+    expect(getPageView({ path: 'today', shell, state })).toEqual(
+      expect.objectContaining({ view: 'page', pathParams: {} })
+    );
+  });
+
+  test('a type from another major version of its package is missing', () => {
+    expect(getPageView({ path: 'report', shell, state: createState() })).toEqual(
+      expect.objectContaining({
+        view: 'update',
+        missing: [
+          { category: 'blocks', type: 'Title', package: '@lowdefy/blocks-native', version: 8 },
+        ],
+      })
+    );
+  });
+
+  test('a page is checked before it is fetched', () => {
+    expect(getPageView({ path: 'map', shell, state: createState({ pages: {} }) }).view).toBe(
+      'update'
+    );
+  });
+
+  test('a dev page (no type set) is checked by the types its config uses once it arrives', () => {
+    const root = createRoot({
+      pageIndex: [
+        { path: 'today', pageId: 'today' },
+        { path: 'map', pageId: 'map' },
+      ],
+      typeSets: {},
+    });
+    const mapPage = createPage('map');
+    mapPage.slots.content.blocks.push({
+      id: 'block:map:m:0',
+      blockId: 'm',
+      type: 'Map',
+      events: { onClick: { try: [{ id: 'a', type: 'Vibrate' }], catch: [] } },
+    });
+    const state = createState({
+      root,
+      pages: { today: { pageConfig: createPage('today') }, map: { pageConfig: mapPage } },
+    });
+    expect(getPageView({ path: 'today', shell, state }).view).toBe('page');
+    expect(getPageView({ path: 'map', shell, state }).missing).toEqual([
+      { category: 'blocks', type: 'Map' },
+      { category: 'actions', type: 'Vibrate' },
+    ]);
+    expect(getPageView({ path: 'map', shell, state: createState({ root, pages: {} }) }).view).toBe(
+      'loading'
+    );
+  });
+});
+
+describe('minShellVersion', () => {
+  test('a shell older than minShellVersion shows the update screen for every page', () => {
+    const state = createState({ root: createRoot({ pageIndex, minShellVersion: '7.5.0' }) });
+    ['today', 'jobs/12', 'nowhere'].forEach((path) => {
+      expect(getPageView({ path, shell, state })).toEqual({
+        view: 'update',
+        reason: 'minShellVersion',
+      });
+    });
+  });
+
+  test('a shell at or above minShellVersion opens pages', () => {
+    ['7.4.0', '7.3.9', '6.0.0'].forEach((minShellVersion) => {
+      const state = createState({ root: createRoot({ pageIndex, minShellVersion }) });
+      expect(getPageView({ path: 'today', shell, state }).view).toBe('page');
+    });
+  });
+});
+
+test('a path with params opens its page with the values from the path', () => {
+  expect(getPageView({ path: 'jobs/a b', shell, state: createState() })).toEqual(
+    expect.objectContaining({ view: 'page', pathParams: { job_id: 'a b' } })
+  );
+});
+
+test('a page not yet cached is loading', () => {
+  expect(getPageView({ path: 'jobs/12', shell, state: createState({ pages: {} }) })).toEqual({
+    view: 'loading',
+    entry: pageIndex[3],
+    pathParams: { job_id: '12' },
+  });
+});
+
+test('a path no mobile page has is another page', () => {
+  expect(getPageView({ path: 'reports', shell, state: createState() })).toEqual({
+    view: 'other',
+    path: 'reports',
+  });
+});

package/src/sync/encodePagePath.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.
+*/
+
+// A page path for /api/page/*, each segment encoded. An index entry's path can be a pattern such
+// as jobs/{job_id}: its placeholder segment matches any value, so the server serves the page's
+// config, which is the same for every value of its params.
+function encodePagePath(path) {
+  return path
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/');
+}
+
+export default encodePagePath;

package/src/sync/fetchPage.js

@@ -0,0 +1,72 @@
+/*
+  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 { LowdefyInternalError, UserError } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+
+import encodePagePath from './encodePagePath.js';
+import readServerError from '../host/readServerError.js';
+
+// GET /api/page/<path> for a page the shell keeps, revalidated with the ETag of the copy it holds.
+// Returns { notModified } on a 304, the page { buildId, etag, pageConfig } on a 200, and
+// { surface } when the page is for another surface (a web page: the shell opens it in the
+// browser). Any other answer throws, so a page without a pageConfig is never cached.
+async function fetchPage({ apiBase, etag, fetchWithAuth, path }) {
+  const headers = etag ? { 'If-None-Match': etag } : {};
+  const res = await fetchWithAuth(`${apiBase}/api/page/${encodePagePath(path)}`, {
+    method: 'GET',
+    headers,
+  });
+  if (res.status === 304) {
+    return { notModified: true };
+  }
+  if (res.status === 404) {
+    const body = await res.json().catch(() => ({}));
+    return { notFound: true, surface: body?.surface ?? null };
+  }
+  if (!res.ok) {
+    throw await readServerError({
+      res,
+      message: `The app's server answered ${res.status} to the page request for "${path}".`,
+    });
+  }
+  const body = await res.json();
+  // lowdefy dev builds a page when it is first opened, and answers { installing } while it installs
+  // the plugins the page needs. Not a fault: the page screen shows this with "Try again".
+  if (body?.installing === true) {
+    const packages =
+      type.isArray(body.packages) && body.packages.length > 0
+        ? body.packages.join(', ')
+        : 'plugins';
+    throw new UserError(
+      `Lowdefy dev is installing ${packages} for "/${path}". Try again once the install finishes.`
+    );
+  }
+  if (!type.isObject(body?.pageConfig)) {
+    throw new LowdefyInternalError(
+      `The app's server answered the page request for "/${path}" with no page config.`
+    );
+  }
+  return {
+    page: {
+      buildId: body.buildId ?? body.pageConfig?._buildId ?? null,
+      etag: res.headers.get('etag'),
+      pageConfig: body.pageConfig,
+    },
+  };
+}
+
+export default fetchPage;