@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/server/readInstanceRecord.test.mjs

@@ -0,0 +1,99 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+
+import { jest } from '@jest/globals';
+
+const mockGetProcessStartTime = jest.fn();
+jest.unstable_mockModule('child_process', () => ({
+  spawnSync: mockGetProcessStartTime,
+  execSync: mockGetProcessStartTime,
+  execFileSync: mockGetProcessStartTime,
+  execFile: mockGetProcessStartTime,
+  spawn: mockGetProcessStartTime,
+}));
+
+const { default: readInstanceRecord } = await import('./readInstanceRecord.js');
+const { default: startIdleGc } = await import('./startIdleGc.js');
+
+const configDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-instance-record-'));
+const recordPath = path.join(configDirectory, '.lowdefy', 'instance.json');
+const STARTED = Symbol.for('lowdefy.server-dev.idleGc');
+
+afterAll(() => {
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  fs.rmSync(path.join(configDirectory, '.lowdefy'), { recursive: true, force: true });
+  delete globalThis[STARTED];
+});
+
+function writeRecord(record) {
+  fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+  fs.writeFileSync(recordPath, typeof record === 'string' ? record : JSON.stringify(record));
+}
+
+test('readInstanceRecord returns the record as written, without checking the manager process', () => {
+  writeRecord({ pid: 999999, lastActivityAt: '2026-10-03T10:00:00.000Z', activeRequests: 0 });
+
+  expect(readInstanceRecord({ configDirectory })).toEqual({
+    pid: 999999,
+    lastActivityAt: '2026-10-03T10:00:00.000Z',
+    activeRequests: 0,
+  });
+  expect(mockGetProcessStartTime).not.toHaveBeenCalled();
+});
+
+test('readInstanceRecord returns null when there is no record', () => {
+  expect(readInstanceRecord({ configDirectory })).toBeNull();
+});
+
+test('readInstanceRecord returns null for a record caught mid-write', () => {
+  writeRecord('{"pid": 12');
+
+  expect(readInstanceRecord({ configDirectory })).toBeNull();
+});
+
+test('the idle GC poll reads the record and collects without spawning a process', () => {
+  // performance is not redefinable on this Node, and nothing here reads it.
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+  try {
+    const gc = jest.fn();
+    const start = Date.parse('2026-10-03T10:00:00.000Z');
+    // A full record, which readDevInstance would check with ps.
+    writeRecord({
+      pid: process.pid,
+      configDirectory: fs.realpathSync.native(configDirectory),
+      processStartTime: 'Sat Oct  3 10:00:00 2026',
+      lastActivityAt: new Date(start).toISOString(),
+      activeRequests: 0,
+      building: false,
+    });
+
+    startIdleGc({ configDirectory, gc, now: () => start + 10_000 });
+    jest.advanceTimersByTime(5000);
+
+    expect(gc).toHaveBeenCalledTimes(1);
+    expect(mockGetProcessStartTime).not.toHaveBeenCalled();
+  } finally {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  }
+});

package/lib/server/readMergedMaps.js

@@ -0,0 +1,86 @@
+/*
+  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/promises';
+import path from 'node:path';
+import { serializer } from '@lowdefy/helpers';
+
+async function readJson(filePath) {
+  return serializer.deserializeFromString(await fs.readFile(filePath, 'utf8'));
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return await readJson(filePath);
+  } catch (error) {
+    // A jitMaps file can be pruned between the listing and the read.
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function listJitMapsFiles(jitMapsDirectory) {
+  try {
+    return await fs.readdir(jitMapsDirectory);
+  } catch (error) {
+    // No page has been built since the last config build.
+    if (error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+// <childId>-<generation>-<write>.json. Files of one build context can repeat
+// an entry (see writeJitMaps in @lowdefy/build), and the later write is the
+// more complete one, so files are applied in write order.
+function compareWriteOrder(a, b) {
+  const [childA, generationA, writeA] = path.basename(a, '.json').split('-');
+  const [childB, generationB, writeB] = path.basename(b, '.json').split('-');
+  if (childA !== childB) {
+    return childA < childB ? -1 : 1;
+  }
+  return Number(generationA) - Number(generationB) || Number(writeA) - Number(writeB);
+}
+
+// The dev server's key and ref maps: the config build's keyMap.json and
+// refMap.json, plus the entries every retained JIT page build wrote to
+// jitMaps/. Read in full on each call; only the error path and the dev tools
+// call it.
+async function readMergedMaps({ buildDirectory }) {
+  const jitMapsDirectory = path.join(buildDirectory, 'jitMaps');
+  const [keyMap, refMap, files] = await Promise.all([
+    readJson(path.join(buildDirectory, 'keyMap.json')),
+    readJson(path.join(buildDirectory, 'refMap.json')),
+    listJitMapsFiles(jitMapsDirectory),
+  ]);
+  const merged = { keyMap, refMap };
+  const jitMaps = await Promise.all(
+    files
+      .filter((file) => file.endsWith('.json'))
+      .sort(compareWriteOrder)
+      .map((file) => readJsonIfExists(path.join(jitMapsDirectory, file)))
+  );
+  for (const maps of jitMaps.filter((entry) => entry !== null)) {
+    Object.assign(merged.keyMap, maps.keyMap);
+    Object.assign(merged.refMap, maps.refMap);
+  }
+  return merged;
+}
+
+export default readMergedMaps;

package/lib/server/readMergedMaps.test.mjs

@@ -0,0 +1,79 @@
+/*
+  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 'fs';
+import os from 'os';
+import path from 'path';
+
+import readMergedMaps from './readMergedMaps.js';
+
+let buildDirectory;
+
+function write(file, data) {
+  const filePath = path.join(buildDirectory, file);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data));
+}
+
+beforeEach(() => {
+  buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-merged-maps-'));
+  write('keyMap.json', { cfg_1: { key: 'root' } });
+  write('refMap.json', { cfg_r: { parent: null, path: 'lowdefy.yaml' } });
+});
+
+afterEach(() => {
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});
+
+test('readMergedMaps returns the config build maps when no page has been built', async () => {
+  expect(await readMergedMaps({ buildDirectory })).toEqual({
+    keyMap: { cfg_1: { key: 'root' } },
+    refMap: { cfg_r: { parent: null, path: 'lowdefy.yaml' } },
+  });
+});
+
+test('readMergedMaps adds every jitMaps file, the later write of an entry winning', async () => {
+  write('jitMaps/abc-1-2.json', {
+    keyMap: { cfg_abc_2: { key: 'root.blocks[0:b]' } },
+    refMap: { cfg_abc_r: { parent: null, path: 'pages/b.yaml' } },
+  });
+  write('jitMaps/abc-1-10.json', {
+    keyMap: { cfg_abc_3: { key: 'root.blocks[0:c]' } },
+    refMap: { cfg_abc_r: { parent: null, path: 'pages/b.yaml', lineNumber: 1 } },
+  });
+  write('jitMaps/abc-1-1.json', {
+    keyMap: { cfg_abc_1: { key: 'root' } },
+    refMap: { cfg_abc_r: { parent: null } },
+  });
+
+  const { keyMap, refMap } = await readMergedMaps({ buildDirectory });
+
+  expect(Object.keys(keyMap).sort()).toEqual(['cfg_1', 'cfg_abc_1', 'cfg_abc_2', 'cfg_abc_3']);
+  expect(refMap.cfg_abc_r).toEqual({ parent: null, path: 'pages/b.yaml', lineNumber: 1 });
+  expect(refMap.cfg_r).toEqual({ parent: null, path: 'lowdefy.yaml' });
+});
+
+test('readMergedMaps skips a jitMaps file still being written under its temporary name', async () => {
+  write('jitMaps/abc-1-1.json', { keyMap: { cfg_abc_1: { key: 'root' } }, refMap: {} });
+  fs.writeFileSync(
+    path.join(buildDirectory, 'jitMaps', '.abc-1-2.json.123.abcd1234.tmp'),
+    '{"keyM'
+  );
+
+  const { keyMap } = await readMergedMaps({ buildDirectory });
+
+  expect(Object.keys(keyMap).sort()).toEqual(['cfg_1', 'cfg_abc_1']);
+});

package/lib/server/recording/appendRecords.js

@@ -0,0 +1,33 @@
+/*
+  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 { traceIdDate } from '@lowdefy/helpers';
+
+// Appends records as JSON lines to
+// <config>/.lowdefy/traces/<source>/<yyyy-mm-dd>/<id>.jsonl. The date comes
+// from the id, so a session that crosses midnight stays in one file. Each
+// append opens the file afresh, so a file pruned mid-session simply starts
+// again. The watchers never see these writes: .lowdefy is a dot-path.
+function appendRecords({ configDirectory, source, id, records }) {
+  const directory = path.join(configDirectory, '.lowdefy', 'traces', source, traceIdDate(id));
+  fs.mkdirSync(directory, { recursive: true });
+  const lines = records.map((record) => `${JSON.stringify(record)}\n`).join('');
+  fs.appendFileSync(path.join(directory, `${id}.jsonl`), lines);
+}
+
+export default appendRecords;

package/lib/server/recording/errorRecordingStamp.js

@@ -0,0 +1,34 @@
+/*
+  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';
+
+// The recording identity an error entry carries: { source, run, journey } for
+// a request or page in a headless journey run (run and journey
+// are the cookie's run.id and run.journey), or null for a developer's own tab
+// and for headless tool contexts, whose cookie is 'off'.
+function errorRecordingStamp(recording) {
+  if (!type.isObject(recording)) {
+    return null;
+  }
+  return {
+    source: recording.source,
+    run: recording.run.id,
+    journey: recording.run.journey,
+  };
+}
+
+export default errorRecordingStamp;

package/lib/server/recording/errorRecordingStamp.test.mjs

@@ -0,0 +1,31 @@
+/*
+  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 errorRecordingStamp from './errorRecordingStamp.js';
+
+test('errorRecordingStamp gives the source, run id and journey of a verified run cookie', () => {
+  expect(
+    errorRecordingStamp({
+      source: 'journey',
+      run: { id: '20261003T151200Z-p0d4rm', by: 'agent', journey: 'save-ticket', actor: 'main' },
+    })
+  ).toEqual({ source: 'journey', run: '20261003T151200Z-p0d4rm', journey: 'save-ticket' });
+});
+
+test('errorRecordingStamp is null for a developer tab and a headless tool context', () => {
+  expect(errorRecordingStamp(null)).toBeNull();
+  expect(errorRecordingStamp('off')).toBeNull();
+});

package/lib/server/recording/isRecordingEnabled.js

@@ -0,0 +1,31 @@
+/*
+  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 readRecordingCookie from './readRecordingCookie.js';
+
+// Whether a page should mount the recorder: not when the developer turned
+// recording off (LOWDEFY_DEV_RECORD=false, in the shell or .env), and not in a
+// headless context marked off or a run that records nothing, so those never
+// even subscribe.
+function isRecordingEnabled(cookieHeader) {
+  if (process.env.LOWDEFY_DEV_RECORD === 'false') {
+    return false;
+  }
+  const recording = readRecordingCookie(cookieHeader);
+  return recording !== 'off' && recording?.record !== false;
+}
+
+export default isRecordingEnabled;

package/lib/server/recording/readRecordingCookie.js

@@ -0,0 +1,71 @@
+/*
+  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 { isTraceId, type } from '@lowdefy/helpers';
+
+import { JOURNEY_COOKIES, readJourneyCookie } from '../journeyCookies.js';
+
+const RUN_SOURCES = ['journey'];
+
+function parsePayload(payload) {
+  try {
+    return JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// What the recording cookie on a request says: 'off' (a headless tool context
+// that must not record), { source, run } (a headless journey run),
+// or null (no verified cookie - a developer's own tab, which records as dev).
+// A run that records nothing (a journey run its caller does not record) also
+// carries record: false: its errors are attributed to it, but the recorder
+// stays off.
+// Only the dev server's own headless browser can write a verified cookie, so a
+// page can never relabel what it records.
+function readRecordingCookie(cookieHeader) {
+  const payload = readJourneyCookie({ cookieHeader, name: JOURNEY_COOKIES.recording.name });
+  if (payload === null) {
+    return null;
+  }
+  if (payload === 'off') {
+    return 'off';
+  }
+  const parsed = parsePayload(payload);
+  if (
+    !type.isObject(parsed) ||
+    !RUN_SOURCES.includes(parsed.source) ||
+    !type.isObject(parsed.run) ||
+    !isTraceId(parsed.run.id)
+  ) {
+    return null;
+  }
+  const recording = {
+    source: parsed.source,
+    run: {
+      id: parsed.run.id,
+      by: parsed.run.by ?? null,
+      journey: parsed.run.journey ?? null,
+      actor: parsed.run.actor ?? null,
+    },
+  };
+  if (parsed.record === false) {
+    recording.record = false;
+  }
+  return recording;
+}
+
+export default readRecordingCookie;

package/lib/server/recording/readRecordingCookie.test.mjs

@@ -0,0 +1,73 @@
+/*
+  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 { default: readRecordingCookie } = await import('./readRecordingCookie.js');
+const { default: recordingCookiePayload } = await import('./recordingCookiePayload.js');
+const { default: isRecordingEnabled } = await import('./isRecordingEnabled.js');
+const { JOURNEY_COOKIES, writeJourneyCookie } = await import('../journeyCookies.js');
+
+const origin = 'http://localhost:3001';
+
+function cookieFor(payload) {
+  const cookie = writeJourneyCookie({ name: JOURNEY_COOKIES.recording.name, payload, origin });
+  return `other=1; ${cookie.name}=${cookie.value}`;
+}
+
+afterEach(() => {
+  delete process.env.LOWDEFY_DEV_RECORD;
+});
+
+test('readRecordingCookie returns null with no cookie or a forged one', () => {
+  expect(readRecordingCookie(undefined)).toBe(null);
+  expect(readRecordingCookie('lowdefy_recording=nope.off')).toBe(null);
+});
+
+test('readRecordingCookie reads off and a run payload', () => {
+  expect(readRecordingCookie(cookieFor('off'))).toBe('off');
+  const recording = {
+    source: 'journey',
+    run: { id: '20261003T160000Z-77abcd', by: 'agent', journey: 'save-ticket', actor: 'main' },
+  };
+  expect(readRecordingCookie(cookieFor(recordingCookiePayload({ recording })))).toEqual(recording);
+});
+
+test('readRecordingCookie keeps record: false on a run that records nothing, and isRecordingEnabled is false for it', () => {
+  const recording = {
+    source: 'journey',
+    run: { id: '20261003T160000Z-77abcd', by: 'agent', journey: 'save-ticket', actor: 'main' },
+    record: false,
+  };
+  const cookie = cookieFor(recordingCookiePayload({ recording }));
+  expect(readRecordingCookie(cookie)).toEqual(recording);
+  expect(isRecordingEnabled(cookie)).toBe(false);
+});
+
+test('readRecordingCookie treats a verified payload with a bad source or run id as absent', () => {
+  const badSource = recordingCookiePayload({
+    recording: { source: 'production', run: { id: '20261003T160000Z-77abcd' } },
+  });
+  const badRun = recordingCookiePayload({ recording: { source: 'journey', run: { id: '../x' } } });
+  expect(readRecordingCookie(cookieFor(badSource))).toBe(null);
+  expect(readRecordingCookie(cookieFor(badRun))).toBe(null);
+  expect(readRecordingCookie(cookieFor('%%%'))).toBe(null);
+});
+
+test('isRecordingEnabled is false for the env switch and for an off cookie, else true', () => {
+  expect(isRecordingEnabled(undefined)).toBe(true);
+  expect(isRecordingEnabled(cookieFor('off'))).toBe(false);
+  process.env.LOWDEFY_DEV_RECORD = 'false';
+  expect(isRecordingEnabled(undefined)).toBe(false);
+});

package/lib/server/recording/recordingCookiePayload.js

@@ -0,0 +1,33 @@
+/*
+  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';
+
+// The recording cookie's payload for a headless context: 'off' when the
+// context is a tool looking at a page (screenshots, inspection, operator
+// evaluation, state loads), else the run it records as. A run with
+// record: false (a journey run its caller does not record) records nothing,
+// but its errors still carry its run, so the run claims its own.
+function recordingCookiePayload({ recording }) {
+  if (type.isUndefined(recording)) {
+    return 'off';
+  }
+  const { source, run } = recording;
+  const payload = recording.record === false ? { source, run, record: false } : { source, run };
+  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+export default recordingCookiePayload;

package/lib/server/recording/servedBuilds.js

@@ -0,0 +1,46 @@
+/*
+  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';
+
+const MAX_BUILDS = 100;
+
+// Insertion-ordered, so the oldest id is the first one dropped. Kept on
+// globalThis because Vite re-evaluates the SSR module graph when a rebuild
+// rewrites the build artifacts, which would empty a module-level set at the
+// moment the recorder flushes the attempt the rebuild ended.
+const BUILDS_KEY = Symbol.for('lowdefy.devServer.servedBuilds');
+globalThis[BUILDS_KEY] ??= new Set();
+const builds = globalThis[BUILDS_KEY];
+
+// The build ids this Hono process has sent a page config under (jitPage.js
+// adds each `_buildId`). The recording route keeps the build a record names
+// only when it is in here: the page names the build it rendered, but cannot
+// invent one.
+function add(id) {
+  if (!type.isString(id)) return;
+  builds.delete(id);
+  builds.add(id);
+  if (builds.size > MAX_BUILDS) {
+    builds.delete(builds.values().next().value);
+  }
+}
+
+function has(id) {
+  return type.isString(id) && builds.has(id);
+}
+
+export default { add, has };

package/lib/server/recording/servedBuilds.test.mjs

@@ -0,0 +1,42 @@
+/*
+  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 servedBuilds from './servedBuilds.js';
+
+function buildId(index) {
+  return new Date(Date.UTC(2026, 9, 3, 0, index)).toISOString();
+}
+
+test('servedBuilds ignores null and non-string ids', () => {
+  servedBuilds.add(null);
+  servedBuilds.add(undefined);
+  servedBuilds.add(42);
+  expect(servedBuilds.has(null)).toBe(false);
+  expect(servedBuilds.has(undefined)).toBe(false);
+  expect(servedBuilds.has(42)).toBe(false);
+});
+
+test('servedBuilds keeps the newest 100 build ids, re-serving one keeps it', () => {
+  for (let index = 0; index < 100; index += 1) {
+    servedBuilds.add(buildId(index));
+  }
+  servedBuilds.add(buildId(0));
+  servedBuilds.add(buildId(100));
+  expect(servedBuilds.has(buildId(0))).toBe(true);
+  expect(servedBuilds.has(buildId(1))).toBe(false);
+  expect(servedBuilds.has(buildId(2))).toBe(true);
+  expect(servedBuilds.has(buildId(100))).toBe(true);
+});