@lowdefy/server-dev 6.1.0 → 7.1.0

package/client/Routing.jsx

@@ -14,7 +14,7 @@
   limitations under the License.
 */
 
-import React, { Suspense, useEffect, useState } from 'react';
+import React, { Suspense, useCallback, useEffect, useState } from 'react';
 
 import Head from '@lowdefy/client/adapters/Head.js';
 import createLinkComponent from '@lowdefy/client/adapters/Link.js';
@@ -23,10 +23,12 @@ import BuildingPage from '../lib/client/BuildingPage.jsx';
 import RestartingPage from '../lib/client/RestartingPage.jsx';
 import FeedbackMount from './feedback/FeedbackMount.jsx';
 import Inspector from './Inspector.jsx';
+import JourneyObserver from './JourneyObserver.jsx';
 import OpenInEditorListener from './openInEditor/OpenInEditorListener.jsx';
+import Recorder from './Recorder.jsx';
 import Reload from './Reload.jsx';
 import Page from './Page.jsx';
-import setPageId from '../lib/client/setPageId.js';
+import getPagePath from '../lib/client/getPagePath.js';
 import { bumpNavVersion, getReloadVersion } from '../lib/client/utils/useMutateCache.js';
 import useRootConfig from '../lib/client/utils/useRootConfig.js';
 
@@ -39,12 +41,18 @@ import staticJsMap from '../build/plugins/operators/clientJsMap.js';
 
 // Replaces lib/client/App.js — page resolution driven by the custom router
 // instead of next/router, everything else preserved.
-function Routing({ auth, lowdefy, router }) {
+function Routing({ auth, lowdefy, recording, router }) {
   const { data: rootConfig } = useRootConfig(router.basePath);
   const [location, setLocation] = useState(() => router.getLocation());
 
   useEffect(() => {
     return router.subscribe((location) => {
+      // The URL already names the next page, but window.lowdefy.pageId and
+      // its context stay the previous page's until Page renders the next
+      // one. Marked here, synchronously inside the navigation (a Link in
+      // onInit included), so a headless caller waiting on isPageReady does
+      // not settle on the page being left. Page.jsx clears it.
+      lowdefy._devNavigating = true;
       // Dynamic pages re-resolve per navigation — bump before setLocation so
       // the page config SWR key changes with the navigation. The router
       // notifies with a fresh location object per event, so same-URL
@@ -52,40 +60,55 @@ function Routing({ auth, lowdefy, router }) {
       bumpNavVersion();
       setLocation(location);
     });
-  }, [router]);
+  }, [lowdefy, router]);
 
   const [Link] = useState(() => createLinkComponent({ router }));
 
+  // The page instance on screen, { pageId, pathParams, instanceKey }, as the fetched page names
+  // it. null until the first page renders; it names the previous page while the next one fetches.
+  const [shownPage, setShownPage] = useState(null);
+  const onPageShown = useCallback((page) => {
+    setShownPage((current) => (current?.instanceKey === page.instanceKey ? current : page));
+  }, []);
+
   if (rootConfig?.theme) {
     lowdefy.theme = rootConfig.theme;
   }
 
-  const { redirect, pageId } = setPageId(location, rootConfig);
+  // The page is fetched by path; the server says which page it is.
+  const { redirect, path } = getPagePath(location, rootConfig);
   useEffect(() => {
     if (redirect) {
-      router.replace({ pathname: `/${pageId}` });
+      router.replace({ pathname: `/${path}` });
     }
-  }, [redirect, pageId, router]);
+  }, [redirect, path, router]);
   if (redirect) {
     return '';
   }
-
   return (
     <>
-      <FeedbackMount basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
-      <OpenInEditorListener basePath={router.basePath} pageId={pageId} />
+      <FeedbackMount basePath={router.basePath} lowdefy={lowdefy} page={shownPage} />
+      <OpenInEditorListener basePath={router.basePath} pageId={shownPage?.pageId} />
       <Reload basePath={router.basePath} lowdefy={lowdefy}>
         {(resetContext) => (
           <>
             {/* Inside Reload so it can share Reload's event stream (DevStreamContext). */}
-            <Inspector basePath={router.basePath} lowdefy={lowdefy} pageId={pageId} />
+            <Inspector basePath={router.basePath} lowdefy={lowdefy} page={shownPage} />
+            <JourneyObserver lowdefy={lowdefy} />
+            <Recorder
+              basePath={router.basePath}
+              lowdefy={lowdefy}
+              page={shownPage}
+              path={path}
+              recording={recording}
+            />
             {/* Rendered here, not in Page — Page sits below the Suspense boundary
                 and cannot render anything while its config fetch is suspended, so
                 a restarting server would present as "Building page..." forever. */}
             {resetContext.restarting ? (
               <RestartingPage />
             ) : (
-              <Suspense key={`${pageId}_${getReloadVersion()}`} fallback={<BuildingPage />}>
+              <Suspense key={`${path}_${getReloadVersion()}`} fallback={<BuildingPage />}>
                 <Page
                   auth={auth}
                   Components={{ Head, Link }}
@@ -94,7 +117,8 @@ function Routing({ auth, lowdefy, router }) {
                   }}
                   jsMap={staticJsMap}
                   lowdefy={lowdefy}
-                  pageId={pageId}
+                  onPageShown={onPageShown}
+                  path={path}
                   resetContext={resetContext}
                   router={router}
                   types={{

package/client/clientBuildImports.test.mjs

@@ -36,6 +36,8 @@ const allowed = new Set([
   'plugins/icons.js',
   'plugins/operators/client.js',
   'plugins/operators/clientJsMap.js',
+  // The whole theme already reaches the browser in the root config.
+  'theme.json',
 ]);
 
 const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');

package/client/devStreamConnections.test.mjs

@@ -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 path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const clientDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+function listSourceFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) return listSourceFiles(full);
+    return /\.(js|jsx|mjs)$/.test(entry.name) && !entry.name.includes('.test.') ? [full] : [];
+  });
+}
+
+// Dev serves HTTP/1.1, where a browser holds at most six connections per host.
+// A second long-lived stream per tab once made dev pages load forever, so
+// every dev channel shares Reload.jsx's one EventSource (DevStreamContext).
+test('the dev client constructs exactly one EventSource, in Reload.jsx', () => {
+  const constructions = listSourceFiles(clientDirectory).flatMap((file) => {
+    const count = (fs.readFileSync(file, 'utf8').match(/new EventSource\(/g) ?? []).length;
+    return Array.from({ length: count }, () => path.relative(clientDirectory, file));
+  });
+  expect(constructions).toEqual(['Reload.jsx']);
+});

package/client/feedback/FeedbackMount.jsx

@@ -53,7 +53,7 @@ const LazyOverlay = React.lazy(() => import('./FeedbackOverlay.jsx'));
 // contract — nothing here may ever throw into the app it's riding along
 // with. Stays inert until the developer presses Cmd/Ctrl+/, at which point
 // the overlay mounts.
-function FeedbackMount({ basePath, lowdefy, pageId }) {
+function FeedbackMount({ basePath, lowdefy, page }) {
   const [active, setActive] = useState(false);
 
   useFeedbackToggle({
@@ -71,7 +71,7 @@ function FeedbackMount({ basePath, lowdefy, pageId }) {
           <LazyOverlay
             basePath={basePath}
             lowdefy={lowdefy}
-            pageId={pageId}
+            page={page}
             onClose={() => setActive(false)}
           />
         </Suspense>

package/client/feedback/FeedbackOverlay.jsx

@@ -188,12 +188,15 @@ function buildAnnotation(state) {
   };
 }
 
-function buildBatch({ annotations, includeScreenshot, pageId }) {
+function buildBatch({ annotations, includeScreenshot, page }) {
+  const pageId = page?.pageId;
+  const pathParams = page?.pathParams ?? {};
   return {
     batchId: generateId(),
     timestamp: new Date().toISOString(),
     pageId,
     url: `${window.location.pathname}${window.location.search}`,
+    pathParams,
     urlQuery: window.location.search,
     viewport: {
       width: window.innerWidth,
@@ -204,7 +207,7 @@ function buildBatch({ annotations, includeScreenshot, pageId }) {
     },
     annotations,
     includeScreenshot,
-    stateRef: { captured: true, pageId },
+    stateRef: { captured: true, pageId, pathParams },
   };
 }
 
@@ -288,7 +291,7 @@ function renderShape(shape, key) {
 // app down with it — event handlers are individually try/caught, and the
 // whole render is wrapped so a bad state shape returns null rather than
 // throwing into the app's React tree.
-function FeedbackOverlay({ basePath, pageId, onClose }) {
+function FeedbackOverlay({ basePath, page, onClose }) {
   const [state, dispatch] = useReducer(reducer, initialState);
   const primarySendRef = useRef(null);
   const stateRef = useRef(state);
@@ -624,7 +627,7 @@ function FeedbackOverlay({ basePath, pageId, onClose }) {
       const batch = buildBatch({
         annotations,
         includeScreenshot: current.includeScreenshot,
-        pageId,
+        page,
       });
       // Capture the annotated screenshot in THIS tab — the pixels the
       // developer is actually looking at (theme, loaded data) — and ship it

package/client/feedback/feedbackStyles.js

@@ -18,6 +18,8 @@
 // above ErrorBar.jsx (bottom: 40px, zIndex 99999) but under nothing — this
 // overlay is the topmost thing on the page while active.
 
+import getCspNonce from '../../lib/client/getCspNonce.js';
+
 const STYLE_TAG_ID = 'lowdefy-feedback-style-tag';
 
 const colors = {
@@ -248,6 +250,7 @@ function injectFeedbackStyleTag() {
   }
   const style = document.createElement('style');
   style.id = STYLE_TAG_ID;
+  style.nonce = getCspNonce();
   style.textContent = `
     .lowdefy-feedback-picking, .lowdefy-feedback-picking * {
       cursor: crosshair !important;

package/client/journeyObserver/startJourneyObserver.js

@@ -0,0 +1,101 @@
+/*
+  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.
+*/
+
+const OBSERVE_BINDING = '__lowdefyJourneyObserve';
+
+// Reports what a journey's page runs to the journey runner, through the
+// binding the runner exposes on its own browser contexts only
+// (lib/docs/createJourneyActors.js): every completed Lowdefy event from the
+// engine's trace hook, and every block once it becomes visible, sampled in
+// the animation frame after any DOM change so a message shown and cleared
+// within one step is still seen. In a developer's tab there is no binding,
+// and it does nothing. Returns a stop function, or null when it did not
+// start. Never throws into the app: every callback is wrapped.
+function startJourneyObserver({ window, lowdefy, getTrace, collectVisibleBlockIds }) {
+  const observe = window[OBSERVE_BINDING];
+  if (typeof observe !== 'function') {
+    return null;
+  }
+
+  function forward(message) {
+    try {
+      Promise.resolve(observe(message)).catch(() => {});
+    } catch {
+      // The binding is gone with its context; nothing to report to.
+    }
+  }
+
+  // The hook emits only completed events: bounced debounces and handledBy
+  // returns never arrive, so nothing is filtered here.
+  const unsubscribe = getTrace(lowdefy).subscribe((payload) => {
+    try {
+      forward({
+        kind: 'event',
+        scope: payload.scope,
+        pageId: payload.pageId,
+        blockId: payload.blockId,
+        eventName: payload.eventName,
+        actionIds: (payload.actions ?? []).map((action) => action?.id),
+      });
+    } catch {
+      // A payload this observer cannot read is skipped.
+    }
+  });
+
+  const sent = new Set();
+  let frame = null;
+  function sample() {
+    frame = null;
+    try {
+      const pageId = lowdefy.pageId;
+      const fresh = collectVisibleBlockIds().filter(
+        (blockId) => !sent.has(JSON.stringify([pageId, blockId]))
+      );
+      if (fresh.length === 0) {
+        return;
+      }
+      fresh.forEach((blockId) => sent.add(JSON.stringify([pageId, blockId])));
+      forward({ kind: 'rendered', pageId, blockIds: fresh });
+    } catch {
+      // Sampled again on the next change.
+    }
+  }
+
+  const observer = new window.MutationObserver(() => {
+    if (frame === null) {
+      frame = window.requestAnimationFrame(sample);
+    }
+  });
+  // Attributes too: antd shows and hides a modal or an alert by its style and
+  // class, without adding or removing nodes.
+  observer.observe(window.document.body, {
+    attributes: true,
+    characterData: true,
+    childList: true,
+    subtree: true,
+  });
+  sample();
+
+  return function stop() {
+    unsubscribe();
+    observer.disconnect();
+    if (frame !== null) {
+      window.cancelAnimationFrame(frame);
+    }
+  };
+}
+
+export default startJourneyObserver;

package/client/journeyObserver/startJourneyObserver.test.mjs

@@ -0,0 +1,149 @@
+/*
+  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 startJourneyObserver from './startJourneyObserver.js';
+
+function createFakeWindow({ binding } = {}) {
+  const observers = [];
+  const frames = [];
+  class FakeMutationObserver {
+    constructor(callback) {
+      this.callback = callback;
+      this.disconnect = jest.fn();
+      this.observe = jest.fn();
+      observers.push(this);
+    }
+  }
+  const window = {
+    document: { body: {} },
+    MutationObserver: FakeMutationObserver,
+    requestAnimationFrame: jest.fn((callback) => {
+      frames.push(callback);
+      return frames.length;
+    }),
+    cancelAnimationFrame: jest.fn(),
+  };
+  if (binding !== undefined) {
+    window.__lowdefyJourneyObserve = binding;
+  }
+  function mutate() {
+    observers.forEach((observer) => observer.callback([]));
+  }
+  function runFrames() {
+    frames.splice(0).forEach((callback) => callback());
+  }
+  return { window, observers, mutate, runFrames };
+}
+
+function createFakeTrace() {
+  const unsubscribe = jest.fn();
+  const trace = { subscribe: jest.fn(() => unsubscribe) };
+  return { getTrace: jest.fn(() => trace), trace, unsubscribe };
+}
+
+test('startJourneyObserver does nothing in a developer tab, where there is no binding', () => {
+  const { window, observers } = createFakeWindow();
+  const { getTrace, trace } = createFakeTrace();
+  const stop = startJourneyObserver({
+    window,
+    lowdefy: { pageId: 'home' },
+    getTrace,
+    collectVisibleBlockIds: jest.fn(() => ['a']),
+  });
+  expect(stop).toBeNull();
+  expect(trace.subscribe).not.toHaveBeenCalled();
+  expect(observers).toHaveLength(0);
+});
+
+test('startJourneyObserver forwards completed events and each newly visible block once', () => {
+  const binding = jest.fn(async () => {});
+  const { window, observers, mutate, runFrames } = createFakeWindow({ binding });
+  const { getTrace, trace, unsubscribe } = createFakeTrace();
+  const lowdefy = { pageId: 'home' };
+  let visible = ['home_title'];
+  const stop = startJourneyObserver({
+    window,
+    lowdefy,
+    getTrace,
+    collectVisibleBlockIds: () => visible,
+  });
+  expect(getTrace).toHaveBeenCalledWith(lowdefy);
+  // Subscribed without state: the observer never reads it.
+  expect(trace.subscribe.mock.calls[0]).toHaveLength(1);
+  expect(binding).toHaveBeenCalledWith({
+    kind: 'rendered',
+    pageId: 'home',
+    blockIds: ['home_title'],
+  });
+
+  const listener = trace.subscribe.mock.calls[0][0];
+  listener({
+    scope: 'page',
+    pageId: 'home',
+    blockId: 'save_button',
+    blockType: 'Button',
+    eventName: 'onClick',
+    actions: [{ id: 'save' }, { id: 'set_saved' }],
+    record: {},
+  });
+  expect(binding).toHaveBeenLastCalledWith({
+    kind: 'event',
+    scope: 'page',
+    pageId: 'home',
+    blockId: 'save_button',
+    eventName: 'onClick',
+    actionIds: ['save', 'set_saved'],
+  });
+
+  // Two changes before the next frame sample once; only the new block is sent.
+  visible = ['home_title', 'flash_alert'];
+  mutate();
+  mutate();
+  expect(window.requestAnimationFrame).toHaveBeenCalledTimes(1);
+  runFrames();
+  expect(binding).toHaveBeenLastCalledWith({
+    kind: 'rendered',
+    pageId: 'home',
+    blockIds: ['flash_alert'],
+  });
+  const calls = binding.mock.calls.length;
+  mutate();
+  runFrames();
+  expect(binding.mock.calls).toHaveLength(calls);
+
+  stop();
+  expect(unsubscribe).toHaveBeenCalled();
+  expect(observers[0].disconnect).toHaveBeenCalled();
+});
+
+test('startJourneyObserver keeps the app running when the binding or a payload throws', () => {
+  const binding = jest.fn(() => {
+    throw new Error('context closed');
+  });
+  const { window } = createFakeWindow({ binding });
+  const { getTrace, trace } = createFakeTrace();
+  startJourneyObserver({
+    window,
+    lowdefy: { pageId: 'home' },
+    getTrace,
+    collectVisibleBlockIds: () => ['a'],
+  });
+  const listener = trace.subscribe.mock.calls[0][0];
+  expect(() => listener(null)).not.toThrow();
+  expect(() => listener({ scope: 'page', actions: [] })).not.toThrow();
+});

package/client/openInEditor/OpenInEditorListener.jsx

@@ -20,6 +20,7 @@ import { createPortal } from 'react-dom';
 import { blockAncestorChain, nearestBlock } from '../feedback/elementInspect.js';
 import { highlightBox, labelChip, overlayContainer } from '../feedback/feedbackStyles.js';
 import findBlockLocation from './findBlockLocation.js';
+import getCspNonce from '../../lib/client/getCspNonce.js';
 
 const STYLE_TAG_ID = 'lowdefy-open-in-editor-style-tag';
 const BODY_CLASS = 'lowdefy-open-in-editor-target';
@@ -32,6 +33,7 @@ function injectStyleTag() {
   }
   const style = document.createElement('style');
   style.id = STYLE_TAG_ID;
+  style.nonce = getCspNonce();
   style.textContent = `
     .${BODY_CLASS}, .${BODY_CLASS} * {
       cursor: pointer !important;

package/client/recorder/buildEngineRecord.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// An engine event no interaction caused (a mount event, an app event, a
+// programmatic or off-path event) as a v1 trace record of kind engine. The
+// compiler decides what each compiles to.
+function buildEngineRecord({ engineEvent, session, roles }) {
+  return {
+    v: 1,
+    session,
+    t: new Date(engineEvent.startTimestamp).toISOString(),
+    kind: 'engine',
+    scope: engineEvent.scope,
+    page_id: engineEvent.pageId,
+    roles: roles ?? [],
+    person: null,
+    org: null,
+    target: null,
+    event: engineEvent.traceEvent,
+    build: engineEvent.build ?? null,
+  };
+}
+
+export default buildEngineRecord;

package/client/recorder/buildInteractionRecord.js

@@ -0,0 +1,64 @@
+/*
+  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';
+
+// describeElement's result without what a record keeps elsewhere: the page
+// sits on the record and the enclosing block ids feed pairing only.
+function recordTarget(target) {
+  if (type.isNone(target)) return null;
+  const { page_id: _pageId, block_ids: _blockIds, ...rest } = target;
+  return rest;
+}
+
+// A DOM interaction as a v1 trace record. `paired` are the trace events the
+// pairing rule gave it, innermost first: the first is `event`, the rest go to
+// `also`. `build` is the build of the page config the interaction happened
+// on; `source` and `run` are stamped by the dev server, never the page.
+function buildInteractionRecord({ interaction, paired = [], session, roles }) {
+  const record = {
+    v: 1,
+    session,
+    t: new Date(interaction.t).toISOString(),
+    kind: interaction.kind,
+    scope: 'page',
+    page_id: interaction.target?.page_id ?? interaction.pageId,
+    roles: roles ?? [],
+    person: null,
+    org: null,
+    target: recordTarget(interaction.target),
+    event: paired[0] ?? null,
+    build: interaction.build ?? null,
+  };
+  if (paired.length > 1) {
+    record.also = paired.slice(1);
+  }
+  if (interaction.kind === 'pageview') {
+    record.url = interaction.url;
+    if (!type.isNone(interaction.pathParams)) {
+      record.path_params = interaction.pathParams;
+    }
+  }
+  if (interaction.kind === 'change') {
+    record.value = interaction.value ?? null;
+  }
+  if (interaction.kind === 'key') {
+    record.key = interaction.key;
+  }
+  return record;
+}
+
+export default buildInteractionRecord;

package/client/recorder/buildTraceEvent.js

@@ -0,0 +1,57 @@
+/*
+  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 collectEventActions from './collectEventActions.js';
+import collectEventEndpoints from './collectEventEndpoints.js';
+import collectEventRequests from './collectEventRequests.js';
+import diffStateWrites from './diffStateWrites.js';
+
+// One completed engine event as a trace record's `event` (or `also` entry),
+// built from the engine's trace payload the moment it arrives: the state the
+// event wrote is the difference between the copy taken before its actions ran
+// and the state now, which later events would change.
+function buildTraceEvent({ payload, urlAfter }) {
+  const { context, failure, record } = payload;
+  const responses = record?.responses ?? {};
+  const event = {
+    name: payload.eventName,
+    block_id: payload.blockId,
+    success: payload.success,
+    actions: collectEventActions({ responses }),
+    requests: collectEventRequests({ blockId: payload.blockId, context, responses }),
+    endpoints: collectEventEndpoints({ blockId: payload.blockId, context, responses }),
+    state_writes: diffStateWrites({
+      before: payload.stateBefore,
+      after: context?.state,
+      values: true,
+    }),
+    url_after: urlAfter ?? null,
+  };
+  if (!type.isNone(failure)) {
+    event.error = {
+      name: failure.errorName ?? 'Error',
+      config_key: failure.configKey ?? null,
+      action_type: failure.actionType ?? null,
+      action_id: failure.actionId ?? null,
+    };
+    event.invalid_blocks = failure.invalidBlocks ?? [];
+  }
+  return event;
+}
+
+export default buildTraceEvent;