@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/docs/listModuleDocEntries.js

@@ -0,0 +1,69 @@
+/*
+  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 path from 'node:path';
+import { type } from '@lowdefy/helpers';
+
+import listPackageDocFiles from './listPackageDocFiles.js';
+import parseModuleSource from './parseModuleSource.js';
+import readDocTitle from './readDocTitle.js';
+
+// Docs of the app's modules: each README and docs/*.md, plus a generated page
+// of the components, exports and vars its module.lowdefy.yaml declares.
+// Returns the entries and the local module roots, whose doc files can change
+// while the server runs.
+function listModuleDocEntries({ modules }) {
+  const entries = [];
+  const localDirs = [];
+  for (const moduleEntry of Object.values(modules ?? {})) {
+    if (moduleEntry.isLocal) {
+      localDirs.push(moduleEntry.moduleRoot);
+    }
+    const base = {
+      section: 'Modules',
+      source: 'module',
+      ...parseModuleSource({ source: moduleEntry.source }),
+    };
+    const moduleSlug = `modules/${moduleEntry.id}`;
+    const { readme, docs } = listPackageDocFiles({ dir: moduleEntry.moduleRoot });
+    if (!type.isNone(readme)) {
+      entries.push({
+        ...base,
+        slug: moduleSlug,
+        title: readDocTitle({ filePath: readme, fallback: `${moduleEntry.id} module` }),
+        filePath: readme,
+      });
+    }
+    for (const filePath of docs) {
+      const stem = path.basename(filePath, '.md');
+      entries.push({
+        ...base,
+        slug: `${moduleSlug}/${stem}`,
+        title: readDocTitle({ filePath, fallback: stem }),
+        filePath,
+      });
+    }
+    entries.push({
+      ...base,
+      slug: `${moduleSlug}/manifest`,
+      title: `${moduleEntry.id} module: components, exports and vars`,
+      moduleEntry,
+    });
+  }
+  return { entries, localDirs };
+}
+
+export default listModuleDocEntries;

package/lib/docs/listPackageDocFiles.js

@@ -0,0 +1,67 @@
+/*
+  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';
+
+// Docs are served from inside the package only: a file, or a docs folder,
+// that links outside it is left out, as is a link that points nowhere or a
+// directory named like a markdown file.
+function isFileInside({ realDir, filePath }) {
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+  const realPath = fs.realpathSync(filePath);
+  return realPath.startsWith(`${realDir}${path.sep}`) && fs.statSync(realPath).isFile();
+}
+
+function listMarkdownFiles({ realDir, dir }) {
+  return fs
+    .readdirSync(dir)
+    .filter((fileName) => fileName.endsWith('.md'))
+    .sort()
+    .map((fileName) => path.join(dir, fileName))
+    .filter((filePath) => isFileInside({ realDir, filePath }));
+}
+
+// The markdown a plugin or module ships: its README, and the files in docs/
+// (a plugin that builds its docs may only have dist/docs/).
+function listPackageDocFiles({ dir }) {
+  // A local plugin or module can be removed while the server runs.
+  if (!fs.existsSync(dir)) {
+    return { readme: null, docs: [] };
+  }
+  const realDir = fs.realpathSync(dir);
+  let readme = null;
+  for (const fileName of ['README.md', 'readme.md']) {
+    const filePath = path.join(dir, fileName);
+    if (isFileInside({ realDir, filePath })) {
+      readme = filePath;
+      break;
+    }
+  }
+  let docs = [];
+  for (const docsDir of ['docs', 'dist/docs']) {
+    const dirPath = path.join(dir, docsDir);
+    if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
+      docs = listMarkdownFiles({ realDir, dir: dirPath });
+      break;
+    }
+  }
+  return { readme, docs };
+}
+
+export default listPackageDocFiles;

package/lib/docs/listPluginDocEntries.js

@@ -0,0 +1,111 @@
+/*
+  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';
+import { type } from '@lowdefy/helpers';
+
+import listPackageDocFiles from './listPackageDocFiles.js';
+import readDocTitle from './readDocTitle.js';
+import readPluginPackages from './readPluginPackages.js';
+import resolvePluginDir from './resolvePluginDir.js';
+
+// Type kinds a doc can be looked up by, singular as the core docs name them.
+const TYPE_KINDS = {
+  actions: 'action',
+  agents: 'agent',
+  blocks: 'block',
+  connections: 'connection',
+  notifications: 'notification',
+  operators: 'operator',
+  requests: 'request',
+  websockets: 'websocket',
+};
+
+function readPackageVersion({ dir, fallback }) {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  return packageJson.version ?? fallback;
+}
+
+// A published plugin is installed inside node_modules; a local one links to a
+// directory outside it.
+function isLocalPluginDir({ dir }) {
+  return !dir.split(path.sep).includes('node_modules');
+}
+
+// Docs shipped by the app's plugins, Lowdefy's own left out (the core docs
+// cover them). Returns the entries, the directories whose doc files can change
+// while the server runs, and each type's doc slug, keyed "kind:typeName".
+function listPluginDocEntries() {
+  const entries = [];
+  const localDirs = [];
+  const typeDocs = new Map();
+  for (const plugin of readPluginPackages()) {
+    if (plugin.package.startsWith('@lowdefy/')) {
+      continue;
+    }
+    const dir = resolvePluginDir({ packageName: plugin.package });
+    if (type.isNone(dir)) {
+      continue;
+    }
+    const local = isLocalPluginDir({ dir });
+    if (local) {
+      localDirs.push(dir);
+    }
+    const base = {
+      section: 'Plugins',
+      source: local ? 'local-plugin' : 'plugin',
+      package: plugin.package,
+      version: readPackageVersion({ dir, fallback: plugin.version }),
+    };
+    const { readme, docs } = listPackageDocFiles({ dir });
+    const packageSlug = `plugins/${plugin.package}`;
+    if (!type.isNone(readme)) {
+      entries.push({ ...base, slug: packageSlug, title: plugin.package, filePath: readme });
+    }
+    const docsByStem = new Map();
+    for (const filePath of docs) {
+      const stem = path.basename(filePath, '.md');
+      const entry = {
+        ...base,
+        slug: `${packageSlug}/${stem}`,
+        title: readDocTitle({ filePath, fallback: stem }),
+        filePath,
+      };
+      docsByStem.set(stem.toLowerCase(), entry);
+      entries.push(entry);
+    }
+    for (const [kinds, typeNames] of Object.entries(plugin.types)) {
+      const kind = TYPE_KINDS[kinds];
+      if (type.isUndefined(kind)) {
+        continue;
+      }
+      for (const typeName of typeNames) {
+        const typeEntry = docsByStem.get(typeName.toLowerCase());
+        if (!type.isUndefined(typeEntry)) {
+          typeEntry.kind = typeEntry.kind ?? kind;
+          typeEntry.typeName = typeEntry.typeName ?? typeName;
+          typeDocs.set(`${kind}:${typeName}`, typeEntry.slug);
+        } else if (!type.isNone(readme)) {
+          typeDocs.set(`${kind}:${typeName}`, packageSlug);
+        }
+      }
+    }
+  }
+  return { entries, localDirs, typeDocs };
+}
+
+export default listPluginDocEntries;

package/lib/docs/listPlugins.js

@@ -14,67 +14,18 @@
   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);
-  }
-}
+import getDocsIndex from './getDocsIndex.js';
+import readPluginPackages from './readPluginPackages.js';
 
 function listPlugins() {
-  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' });
-
-  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);
+  const slugs = new Set(getDocsIndex().entries.map((entry) => entry.slug));
+  return readPluginPackages().map((plugin) => {
+    const docSlug = `plugins/${plugin.package}`;
+    if (!slugs.has(docSlug)) {
+      return plugin;
     }
-  }
-
-  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));
+    return { ...plugin, docSlug };
+  });
 }
 
 export default listPlugins;

package/lib/docs/listTypes.js

@@ -16,7 +16,7 @@
 
 import { type } from '@lowdefy/helpers';
 
-import getDocsManifest from './getDocsManifest.js';
+import getDocsIndex from './getDocsIndex.js';
 import normalizeTypeKind from './normalizeTypeKind.js';
 import readBuildArtifact from './readBuildArtifact.js';
 
@@ -52,19 +52,27 @@ function listTypes({ kind }) {
   const normalizedKind = normalizeTypeKind({ kind });
   if (type.isNone(normalizedKind)) {
     throw new Error(
-      `Unknown type kind. Received ${JSON.stringify(kind)}. Use one of: blocks, operators, actions, connections, requests, agents, notifications, websockets.`
+      `Unknown type kind. Received ${JSON.stringify(
+        kind
+      )}. Use one of: blocks, operators, actions, connections, requests, agents, notifications, websockets.`
     );
   }
   const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
   const types = readBuildArtifact({ name: 'types.json', deserialize: true }) ?? {};
   const blockMetas = readBuildArtifact({ name: 'plugins/blockMetas.json' }) ?? {};
-  const manifest = getDocsManifest();
+  const { entries, typeDocs } = getDocsIndex();
 
   const docSlugsByType = new Map();
   const kindSingular = normalizedKind.slice(0, -1);
-  for (const doc of manifest?.docs ?? []) {
-    if (doc.kind === kindSingular && doc.typeName) {
-      docSlugsByType.set(doc.typeName, doc.slug);
+  for (const entry of entries) {
+    if (entry.source === 'core' && entry.kind === kindSingular && entry.typeName) {
+      docSlugsByType.set(entry.typeName, entry.slug);
+    }
+  }
+  for (const [key, slug] of typeDocs) {
+    const separator = key.indexOf(':');
+    if (key.slice(0, separator) === kindSingular) {
+      docSlugsByType.set(key.slice(separator + 1), slug);
     }
   }
 

package/lib/docs/loadFrameworkHazards.js

@@ -0,0 +1,40 @@
+/*
+  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 { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+let hazards;
+
+// Framework-level hazards ship hand-authored in @lowdefy/docs-content (its
+// content/ directory is regenerated, hazards.json at the package root is
+// not). Memoized like getDocsManifest: the list changes only with a release.
+function loadFrameworkHazards() {
+  if (hazards !== undefined) {
+    return hazards;
+  }
+  try {
+    const hazardsPath = require.resolve('@lowdefy/docs-content/hazards.json');
+    hazards = JSON.parse(fs.readFileSync(hazardsPath, 'utf8'));
+  } catch {
+    // docs-content not installed — type-attached hazards are still served.
+    hazards = null;
+  }
+  return hazards;
+}
+
+export default loadFrameworkHazards;

package/lib/docs/loadFrameworkHazards.test.mjs

@@ -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 loadFrameworkHazards from './loadFrameworkHazards.js';
+
+test('loadFrameworkHazards loads the shipped hazards.json with well-formed unique entries', () => {
+  const hazards = loadFrameworkHazards();
+  expect(Array.isArray(hazards)).toBe(true);
+  expect(hazards.length).toBeGreaterThan(0);
+  const ids = hazards.map((hazard) => hazard.id);
+  expect(new Set(ids).size).toEqual(ids.length);
+  for (const hazard of hazards) {
+    expect(hazard.id).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+    expect(typeof hazard.message).toBe('string');
+    expect(hazard.see === null || typeof hazard.see === 'string').toBe(true);
+    const { kinds, types, when } = hazard.appliesTo;
+    expect(kinds !== undefined || types !== undefined).toBe(true);
+    for (const kind of kinds ?? []) {
+      expect(['blocks', 'operators', 'actions', 'connections', 'requests', 'pages']).toContain(
+        kind
+      );
+    }
+    if (when !== undefined) {
+      expect(when).toEqual('connectionTenantNotNone');
+    }
+  }
+});
+
+test('loadFrameworkHazards returns the same memoized list on repeated calls', () => {
+  expect(loadFrameworkHazards()).toBe(loadFrameworkHazards());
+});

package/lib/docs/loadState.js

@@ -14,27 +14,35 @@
   limitations under the License.
 */
 
-import { type } from '@lowdefy/helpers';
+import { type, urlQuery as urlQueryFn } from '@lowdefy/helpers';
 
-import lowdefyConfig from '../build/config.js';
-import { getBrowser, openPage } from './getBrowser.js';
+import { buildPageUrl, getBrowser, openPage } from './getBrowser.js';
+import noBrowserError from './noBrowserError.js';
 import { loadMocks } from './devMockRegistry.js';
 import { readCheckpoint } from './checkpointStore.js';
+import resolvePageInstance from './resolvePageInstance.js';
+import resolveToolCaller from './resolveToolCaller.js';
+import unsettledPageNote from './unsettledPageNote.js';
+import withBrowserSlot from './withBrowserSlot.js';
+import withDataSession from './withDataSession.js';
 
 const VERIFY_KEY_COUNT = 3;
+const READY_TIMEOUT = 15000;
 
 // Loads a state checkpoint's recorded requests into devMockRegistry (shared
 // by both modes below — src/routes/request.js consults it regardless of how
 // the page was opened), then either:
-//   - 'headless': drives a headless page to the checkpoint's pageId/urlQuery,
-//     injects its recorded state directly into the live context, and verifies
+//   - 'headless': drives a headless page to the checkpoint's page instance
+//     (pageId, pathParams) and urlQuery, injects its recorded state directly
+//     into that instance's context, and verifies
 //     a few keys round-tripped. Good for an agent verifying its own change.
-//     Takes a `user` so a checkpoint captured on a role-gated page restores
-//     into a page that actually renders (see resolveHeadlessUser.js).
+//     Takes a `user` (and `data`, see resolveToolCaller) so a checkpoint
+//     captured on a role-gated page restores into a page that actually
+//     renders (see resolveHeadlessUser.js).
 //   - 'registry-only': just returns a URL a human can open in a real browser
 //     tab — client/Inspector.jsx's `?_checkpoint=` bootstrap does the state
 //     injection client-side once that tab loads.
-async function loadState({ origin, name, mode = 'headless', user }) {
+async function loadState({ origin, name, mode = 'headless', user, data }) {
   if (type.isNone(name) || !type.isString(name)) {
     return { error: `loadState requires a "name" string. Received ${JSON.stringify(name)}.` };
   }
@@ -42,10 +50,10 @@ async function loadState({ origin, name, mode = 'headless', user }) {
   // `user` only reaches a page this function opens itself. In 'registry-only'
   // mode the developer opens the returned URL in their own browser, carrying
   // their own session, so an injected caller would be silently dropped.
-  if (!type.isNone(user) && mode === 'registry-only') {
+  if ((!type.isNone(user) || !type.isNone(data)) && mode === 'registry-only') {
+    const param = type.isNone(user) ? 'data' : 'user';
     return {
-      error:
-        'loadState cannot apply "user" in "registry-only" mode — the developer opens the returned URL in their own browser, carrying their own session. Use the default "headless" mode.',
+      error: `loadState cannot apply "${param}" in "registry-only" mode — the developer opens the returned URL in their own browser, carrying their own session and database. Use the default "headless" mode.`,
       invalidInput: true,
     };
   }
@@ -62,16 +70,25 @@ async function loadState({ origin, name, mode = 'headless', user }) {
     return { error: `Checkpoint "${name}" has no recorded pageId.` };
   }
 
+  const { pathParams } = checkpoint;
+  const instance = resolvePageInstance({ pageId, pathParams });
+  if (!type.isUndefined(instance.error)) {
+    return { error: `Checkpoint "${name}" cannot open its page: ${instance.error}` };
+  }
+
   loadMocks({ pageId, mocks: checkpoint.requests });
 
-  const basePath = lowdefyConfig.basePath ?? '';
-  const urlQuery = checkpoint.urlQuery ?? '';
+  // The checkpoint keeps the query string the page was captured at.
+  const urlQuery = urlQueryFn.parse(checkpoint.urlQuery);
 
   if (mode === 'registry-only') {
-    const separator = urlQuery.includes('?') ? '&' : '?';
-    const url = `${origin}${basePath}/${pageId}${urlQuery}${separator}_checkpoint=${encodeURIComponent(
-      name
-    )}`;
+    const url = buildPageUrl({
+      origin,
+      pageId,
+      path: instance.path,
+      pathParams,
+      urlQuery: { ...urlQuery, _checkpoint: name },
+    });
     return {
       url,
       instructions:
@@ -91,55 +108,106 @@ async function loadState({ origin, name, mode = 'headless', user }) {
     return { error: `loadState requires an "origin" string. Received ${JSON.stringify(origin)}.` };
   }
 
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    return caller;
+  }
+
+  return withBrowserSlot({
+    task: () =>
+      withDataSession({
+        dataSet: caller.dataSet,
+        task: ({ dataCookie }) =>
+          loadStateInBrowser({
+            origin,
+            name,
+            mode,
+            user: caller.user,
+            dataCookie,
+            pageId,
+            instance,
+            pathParams,
+            urlQuery,
+            checkpoint,
+          }),
+      }),
+  });
+}
+
+// The part of loadState that runs in the browser, inside a browser slot.
+async function loadStateInBrowser({
+  origin,
+  name,
+  mode,
+  user,
+  dataCookie,
+  pageId,
+  instance,
+  pathParams,
+  urlQuery,
+  checkpoint,
+}) {
   let browser;
   try {
     browser = await getBrowser();
   } catch (error) {
-    return {
-      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
-    };
+    return { error: noBrowserError(error) };
   }
 
   let context;
   try {
-    // buildPageUrl (used internally by openPage) joins origin/basePath/pageId
-    // as a plain string, so folding the query string into the pageId segment
-    // reproduces the checkpoint's exact URL without needing a query-aware
-    // variant of openPage.
-    const opened = await openPage({ browser, origin, pageId: `${pageId}${urlQuery}`, user });
+    const opened = await openPage({
+      browser,
+      origin,
+      pageId,
+      path: instance.path,
+      pathParams,
+      urlQuery,
+      user,
+      dataCookie,
+      timeout: READY_TIMEOUT,
+    });
     context = opened.context;
     const { page } = opened;
 
-    await page.waitForFunction((id) => Boolean(window.lowdefy?.contexts?.[`page:${id}`]), pageId, {
-      timeout: 15000,
-    });
+    await page.waitForFunction(
+      (contextKey) => Boolean(window.lowdefy?.contexts?.[contextKey]),
+      instance.instanceKey,
+      {
+        timeout: READY_TIMEOUT,
+      }
+    );
 
     const stateEntries = Object.entries(checkpoint.state ?? {});
     await page.evaluate(
-      ({ id, entries }) => {
-        const pageContext = window.lowdefy.contexts[`page:${id}`];
+      ({ contextKey, entries }) => {
+        const pageContext = window.lowdefy.contexts[contextKey];
         entries.forEach(([key, value]) => {
           pageContext._internal.State.set(key, value);
         });
         pageContext._internal.update();
       },
-      { id: pageId, entries: stateEntries }
+      { contextKey: instance.instanceKey, entries: stateEntries }
     );
 
     const verifyKeys = stateEntries.slice(0, VERIFY_KEY_COUNT).map(([key]) => key);
     const verifiedKeys = await page.evaluate(
-      ({ id, keys }) => {
-        const pageContext = window.lowdefy.contexts[`page:${id}`];
+      ({ contextKey, keys }) => {
+        const pageContext = window.lowdefy.contexts[contextKey];
         const result = {};
         keys.forEach((key) => {
           result[key] = pageContext.state?.[key];
         });
         return result;
       },
-      { id: pageId, keys: verifyKeys }
+      { contextKey: instance.instanceKey, keys: verifyKeys }
     );
 
-    return { loaded: true, mode, url: opened.url, verifiedKeys };
+    const result = { loaded: true, mode, url: opened.url, verifiedKeys };
+    if (!opened.ready) {
+      return { ...result, ready: false, note: unsettledPageNote({ timeout: READY_TIMEOUT }) };
+    }
+    return result;
   } catch (error) {
     return { error: `Failed to load checkpoint "${name}": ${error.message}` };
   } finally {