leglas 0.7.4 → 0.9.0

package/dist/index.js

@@ -281,6 +281,19 @@ function parseArgs(argv) {
     }
     return { kind: "requests", json: rest.includes("--json"), clear: rest.includes("--clear") };
   }
+  if (argv[0] === "log") {
+    const rest = argv.slice(1);
+    const flags = rest.filter((argument) => argument.startsWith("--"));
+    const unknown = flags.find((flag) => flag !== "--json");
+    if (unknown !== void 0) {
+      return { kind: "error", message: `leglas log does not take ${unknown}.` };
+    }
+    const names = rest.filter((argument) => !argument.startsWith("--"));
+    if (names.length > 1) {
+      return { kind: "error", message: "leglas log takes one entry at most." };
+    }
+    return { kind: "log", entry: names[0] ?? null, json: flags.includes("--json") };
+  }
   if (argv[0] === "list") {
     const rest = argv.slice(1);
     const unknown = rest.find((argument) => argument !== "--json");
@@ -675,6 +688,14 @@ When asked for design variations, alternatives, or "a few options":
    and register it with \`npx leglas add --title "\u2026" --url "/" --branch <branch>\`
    (the config needs \`devCommand\` with \`{port}\`). Everything below is the
    ordinary, in-app path.
+   A page the app rebuilds in the browser after load (anything that hydrates:
+   Next, Nuxt, SvelteKit, a captured production site) is not its served HTML.
+   Markup edited there shows for a moment and is then replaced from the app's
+   own JavaScript and data, so make the change where that JavaScript gets what
+   it renders. When that is a script other directions share, give it a
+   per-direction override that defaults to what it renders today: every other
+   direction renders exactly as before, which is adding beside, not rewriting.
+   \`npx leglas show\` says when a page was rebuilt after load.
 2. Run \`npx leglas explore <surface> --count <n>\` first, adding
    \`--based-on "<title>"\` when the user wants variations of a direction they
    already like. It prints what the set needs and how to register it. In
@@ -725,6 +746,12 @@ out of the ignored directory, deletes the rest of the exploration, and drops
 them from the rail. Then change their component to use the kept component
 instead of the switcher.
 
+Keeping also writes what the exploration was into \`design-log/\`, which is
+committed. Before exploring a surface, read \`npx leglas log --json\` and any
+entry for that surface: it says what was already tried there, in the user's own
+words, and which direction won. Proposing something that was already rejected
+wastes their time, and the record is there so you do not have to ask.
+
 Useful to know:
 
 - \`.leglas/\` is gitignored. Exploration is disposable and nothing in there
@@ -785,6 +812,84 @@ ${AGENTS_SECTION}`
 // src/keep.ts
 import { basename as basename4, extname as extname4, normalize as normalize2 } from "path";
 
+// ../server/dist/log.js
+var DEFAULT_LOG_DIR = "design-log";
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "untitled";
+}
+function frameFor(title, requests) {
+  let found = null;
+  for (const request of requests) {
+    if (request.title !== title)
+      continue;
+    for (const attachment of request.attachments ?? []) {
+      if (attachment.kind === "frame")
+        found = attachment;
+    }
+  }
+  return found;
+}
+function askedOf(title, requests) {
+  return requests.filter((request) => request.title === title && request.status !== "failed" && request.intent.trim() !== "").map((request) => request.intent.trim());
+}
+function composeEntry(input) {
+  const slug = `${input.date}-${slugify(input.surface)}`;
+  const pictures = [];
+  const lines2 = [];
+  lines2.push(`# ${input.surface}, ${input.date}`);
+  lines2.push("");
+  lines2.push(`**${input.won.title}** won and became \`${input.won.to}\`. ${input.previews.length === 1 ? "It was the only direction." : `${input.previews.length} directions were compared.`}`);
+  lines2.push("");
+  for (const preview of input.previews) {
+    const won = preview.title === input.won.title;
+    lines2.push(`## ${preview.title}${won ? " \u2014 kept" : ""}`);
+    lines2.push("");
+    if (preview.note !== void 0 && preview.note.trim() !== "") {
+      lines2.push(preview.note.trim());
+      lines2.push("");
+    }
+    const frame = frameFor(preview.title, input.requests);
+    if (frame !== null) {
+      const name = `${slugify(preview.title)}.png`;
+      pictures.push({ from: frame.file, to: name });
+      lines2.push(`![${preview.title}](${slug}/${name})`);
+      lines2.push("");
+    }
+    if (preview.basedOn !== void 0) {
+      lines2.push(`A variant of ${preview.basedOn}.`);
+      lines2.push("");
+    }
+    const asked = askedOf(preview.title, input.requests);
+    if (asked.length > 0) {
+      lines2.push("Asked for:");
+      lines2.push("");
+      for (const words of asked)
+        lines2.push(`- ${words}`);
+      lines2.push("");
+    }
+    const notes = input.annotations.filter((note) => note.title === preview.title);
+    if (notes.length > 0) {
+      lines2.push("Marked on the design:");
+      lines2.push("");
+      for (const note of notes)
+        lines2.push(`- ${note.note}`);
+      lines2.push("");
+    }
+  }
+  const failed = input.requests.filter((request) => request.status === "failed");
+  if (failed.length > 0) {
+    lines2.push("## Changes that did not land");
+    lines2.push("");
+    for (const request of failed) {
+      const why = request.failure?.message;
+      lines2.push(`- ${request.title}: ${request.intent}${why === void 0 ? "" : ` (${why})`}`);
+    }
+    lines2.push("");
+  }
+  return { slug, markdown: `${lines2.join("\n").trimEnd()}
+`, pictures };
+}
+
 // ../server/dist/config.js
 var DEFAULT_DEV_SERVER = "http://localhost:3000";
 var DEFAULT_INSTALL_COMMAND = "npm install";
@@ -903,6 +1008,10 @@ function normalizeConfig(raw, options = {}) {
   if (requireDevCommand && previews.some((preview) => preview.branch !== void 0) && devCommand === void 0) {
     errors.push("A preview names a branch, so devCommand is required: Leglas has to start that checkout itself.");
   }
+  const logDir = source["logDir"] ?? DEFAULT_LOG_DIR;
+  if (typeof logDir !== "string" || logDir.trim() === "") {
+    errors.push("logDir must be a non-empty string.");
+  }
   const installCommand = source["installCommand"] ?? DEFAULT_INSTALL_COMMAND;
   if (typeof installCommand !== "string" || installCommand.trim() === "") {
     errors.push("installCommand must be a non-empty string.");
@@ -919,7 +1028,8 @@ function normalizeConfig(raw, options = {}) {
       previews,
       scanPreviews,
       devCommand: typeof devCommand === "string" ? devCommand : void 0,
-      installCommand
+      installCommand,
+      logDir
     },
     errors: []
   };
@@ -1697,6 +1807,7 @@ import net from "net";
 function createProxyHandler(options) {
   const target = new URL(options.target);
   const host = target.hostname;
+  const dialHost = host.replace(/^\[|\]$/g, "");
   const port = Number(target.port || (target.protocol === "https:" ? 443 : 80));
   const authority = target.port ? `${host}:${target.port}` : host;
   function upstreamHeaders(req) {
@@ -1713,7 +1824,19 @@ function createProxyHandler(options) {
   }
   return {
     request(req, res, publicOrigin) {
-      const upstream = http.request({ host, port, method: req.method, path: req.url, headers: upstreamHeaders(req) }, (upstreamRes) => {
+      options.onActivity?.();
+      options.onOpen?.();
+      let open = true;
+      const close = () => {
+        if (!open)
+          return;
+        open = false;
+        options.onActivity?.();
+        options.onClose?.();
+      };
+      res.once("finish", close);
+      res.once("close", close);
+      const upstream = http.request({ host: dialHost, port, method: req.method, path: req.url, headers: upstreamHeaders(req) }, (upstreamRes) => {
         const headers = { ...upstreamRes.headers };
         const location = rewriteLocation(typeof headers.location === "string" ? headers.location : void 0, publicOrigin);
         if (location !== void 0)
@@ -1735,7 +1858,17 @@ Start it, or point Leglas somewhere else with --user-port.`);
       req.pipe(upstream);
     },
     upgrade(req, socket, head) {
-      const upstream = net.connect(port, host, () => {
+      options.onActivity?.();
+      options.onOpen?.();
+      let open = true;
+      const closeActivity = () => {
+        if (!open)
+          return;
+        open = false;
+        options.onActivity?.();
+        options.onClose?.();
+      };
+      const upstream = net.connect(port, dialHost, () => {
         const headers = Object.entries(upstreamHeaders(req)).map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : value}\r
 `).join("");
         upstream.write(`${req.method} ${req.url} HTTP/1.1\r
@@ -1747,6 +1880,7 @@ ${headers}\r
         socket.pipe(upstream);
       });
       const shutdown = () => {
+        closeActivity();
         upstream.destroy();
         socket.destroy();
       };
@@ -1757,6 +1891,62 @@ ${headers}\r
     }
   };
 }
+function startProxyServer(options) {
+  return new Promise((resolve5, reject) => {
+    let open = 0;
+    const handler = createProxyHandler({
+      ...options,
+      onOpen: () => {
+        open += 1;
+        options.onOpen?.();
+      },
+      onClose: () => {
+        open = Math.max(0, open - 1);
+        options.onClose?.();
+      }
+    });
+    const server = http.createServer((req, res) => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      handler.request(req, res, `http://127.0.0.1:${port}`);
+    });
+    const sockets = /* @__PURE__ */ new Set();
+    server.on("connection", (socket) => {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
+    });
+    server.on("upgrade", (req, socket, head) => handler.upgrade(req, socket, head));
+    const onError = (error) => {
+      server.removeListener("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      let closed = null;
+      resolve5({
+        active: () => open > 0,
+        close: () => {
+          if (closed !== null)
+            return closed;
+          closed = new Promise((done) => {
+            for (const socket of sockets)
+              socket.destroy();
+            sockets.clear();
+            server.closeAllConnections();
+            server.close(() => done());
+          });
+          return closed;
+        },
+        url: `http://127.0.0.1:${port}`
+      });
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(0, "127.0.0.1");
+  });
+}
 
 // ../server/dist/browser.js
 import { randomBytes } from "crypto";
@@ -2411,6 +2601,32 @@ function createBrowserPool(options = {}) {
   };
 }
 
+// ../server/dist/hydration.js
+function hydrationEvidence(messages) {
+  for (const raw of messages) {
+    const message2 = raw.split("\n", 1)[0]?.trim() ?? "";
+    if (/Minified React error #(418|419|422|423|425)\b/.test(message2)) {
+      return { framework: "React", message: message2 };
+    }
+    if (/Hydration failed because/.test(message2) || /error while hydrating/i.test(message2) || /Text content (did not|does not) match/i.test(message2) || /Expected server HTML to contain/i.test(message2) || /did not match\. Server:/.test(message2)) {
+      return { framework: "React", message: message2 };
+    }
+    if (/Hydration (node|text|children|class|style|attribute) mismatch/i.test(message2) || /Hydration completed but contains mismatches/i.test(message2)) {
+      return { framework: "Vue", message: message2 };
+    }
+    if (/hydration_mismatch/.test(message2)) {
+      return { framework: "Svelte", message: message2 };
+    }
+    if (/Hydration Mismatch\. Unable to find DOM nodes/.test(message2)) {
+      return { framework: "Solid", message: message2 };
+    }
+    if (/hydrat/i.test(message2) && (/expected .+ but found/i.test(message2) || /mismatch/i.test(message2) && /(node|element|markup|dom|tag|text|attribute|server|client)/i.test(message2))) {
+      return { framework: "the app", message: message2 };
+    }
+  }
+  return null;
+}
+
 // ../server/dist/capture.js
 var FRAME_MAX_HEIGHT = 4e3;
 var MIN_WIDTH = 320;
@@ -2504,10 +2720,12 @@ function locatorExpression(focus) {
 async function render(page, input) {
   const width = clamp(Math.round(input.width), MIN_WIDTH, MAX_WIDTH);
   const errors = [];
+  let hydration = null;
   const remember = (value) => {
+    const message2 = String(value ?? "").trim().slice(0, 240);
+    hydration ??= hydrationEvidence([message2]);
     if (errors.length >= 10)
       return;
-    const message2 = String(value ?? "").slice(0, 240);
     if (message2 === "" || /favicon/i.test(message2))
       return;
     errors.push(message2);
@@ -2655,7 +2873,7 @@ async function render(page, input) {
         resolved
       });
     }
-    return { frame, crops, errors, cut };
+    return { frame, crops, errors, hydration, cut };
   } finally {
     for (const stop of unlisten)
       stop();
@@ -2799,7 +3017,13 @@ async function attachRequest(cwd, requestId, input, deps) {
   const capture = deps.capture ?? capturePage;
   const deadlineMs = deps.deadlineMs ?? 12e3;
   const destination = join5(cwd, CAPTURES_DIR, requestId);
-  const captured = { attachments: [], errors: [], cut: false, skipped: null };
+  const captured = {
+    attachments: [],
+    errors: [],
+    hydration: null,
+    cut: false,
+    skipped: null
+  };
   const references = [];
   requestedWidths.set(captured, Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Math.round(input.width))));
   const controller = new AbortController();
@@ -2849,6 +3073,7 @@ async function attachRequest(cwd, requestId, input, deps) {
         viewport: direction.frame.width
       });
       captured.errors = direction.errors;
+      captured.hydration = direction.hydration;
       captured.cut = direction.cut;
       for (let index = 0; index < direction.crops.length; index += 1) {
         const crop = direction.crops[index];
@@ -3122,6 +3347,8 @@ async function startAppProcess(options) {
 }
 
 // ../server/dist/branches.js
+var BRANCH_IDLE_MS = 10 * 60 * 1e3;
+var BRANCH_SWEEP_MS = 3e4;
 function publicBranchState(state) {
   if (state.status === "ready")
     return { status: "ready" };
@@ -3131,7 +3358,11 @@ function createBranchRegistry(options) {
   const states = new Map(options.previews.map((preview) => [preview.title, { status: "idle" }]));
   const previews = new Map(options.previews.map((preview) => [preview.title, preview]));
   const inflight = /* @__PURE__ */ new Map();
+  const stopping = /* @__PURE__ */ new Map();
+  const lastActivity = /* @__PURE__ */ new Map();
+  const proxies = /* @__PURE__ */ new Map();
   const boot = options.startWorktree ?? startWorktree;
+  const proxy = options.startProxy ?? startProxyServer;
   let closed = false;
   let stopPromise = null;
   const transition = (title, state) => {
@@ -3143,6 +3374,43 @@ function createBranchRegistry(options) {
     options.onChange?.(title, state);
     return state;
   };
+  const stopReady = (title, state, toIdle) => {
+    const current = stopping.get(title);
+    if (current !== void 0)
+      return current;
+    const pending = (async () => {
+      await proxies.get(title)?.close().catch(() => {
+      });
+      await state.worktree.stop().catch(() => {
+      });
+      proxies.delete(title);
+      lastActivity.delete(title);
+      if (toIdle && !closed && states.get(title) === state) {
+        transition(title, { status: "idle" });
+      }
+    })().finally(() => {
+      stopping.delete(title);
+    });
+    stopping.set(title, pending);
+    return pending;
+  };
+  const sweep = () => {
+    const now = Date.now();
+    for (const [title, state] of states) {
+      const branchProxy = proxies.get(title);
+      if (state.status !== "ready" || branchProxy === void 0 || stopping.has(title))
+        continue;
+      if (branchProxy.active()) {
+        lastActivity.set(title, now);
+        continue;
+      }
+      const seen = lastActivity.get(title) ?? now;
+      if (now - seen >= BRANCH_IDLE_MS)
+        void stopReady(title, state, true);
+    }
+  };
+  const sweepTimer = setInterval(sweep, BRANCH_SWEEP_MS);
+  sweepTimer.unref();
   const begin = (title) => {
     const preview = previews.get(title);
     const current = states.get(title);
@@ -3170,9 +3438,21 @@ function createBranchRegistry(options) {
     } catch (error) {
       checkout = Promise.reject(error);
     }
-    const starting = checkout.then((worktree) => {
+    const starting = checkout.then(async (worktree) => {
       transition(title, { status: "starting", phase: "starting" });
-      return transition(title, { status: "ready", worktree });
+      try {
+        const branchProxy = await proxy({
+          target: worktree.url,
+          onActivity: () => lastActivity.set(title, Date.now())
+        });
+        proxies.set(title, branchProxy);
+        lastActivity.set(title, Date.now());
+        return transition(title, { status: "ready", worktree });
+      } catch (error) {
+        await worktree.stop().catch(() => {
+        });
+        throw error;
+      }
     }).catch((error) => transition(title, {
       status: "failed",
       reason: error instanceof Error ? error.message : String(error)
@@ -3184,15 +3464,17 @@ function createBranchRegistry(options) {
   };
   return {
     state: (title) => states.get(title),
+    url: (title) => proxies.get(title)?.url,
     start: begin,
     stop: () => {
       if (stopPromise !== null)
         return stopPromise;
       closed = true;
+      clearInterval(sweepTimer);
       stopPromise = Promise.allSettled([...inflight.values()]).then(async () => {
-        const worktrees = [...states.values()].filter((state) => state.status === "ready").map((state) => state.worktree);
-        await Promise.all(worktrees.map((worktree) => worktree.stop().catch(() => {
-        })));
+        await Promise.allSettled([...stopping.values()]);
+        const ready = [...states.entries()].filter((entry) => entry[1].status === "ready" && proxies.has(entry[0]));
+        await Promise.all(ready.map(([title, state]) => stopReady(title, state, false)));
       });
       return stopPromise;
     }
@@ -3487,10 +3769,10 @@ function scope(leglasCommand, quotedTitle) {
 
 This is a scoped design change: no test run, no build, and no survey of the rest of the project is needed. The result is checked visually in a live preview, not by tooling.
 
-Leave every other direction exactly as it is; they are alternatives being compared side by side, so changing a sibling destroys the comparison. Keep the change additive: do not rewrite shared components that other directions rely on.`;
+Leave every other direction exactly as it is; they are alternatives being compared side by side, so changing a sibling destroys the comparison. Keep the change additive: do not rewrite shared components that other directions rely on. A shared script may gain one small per-direction override, at the point it reads what it renders, that defaults to what it renders today; every other direction then renders exactly as before, so that counts as additive.`;
 }
 function capturedBlock(captured) {
-  if (captured === null || captured.attachments.length === 0 && captured.errors.length === 0 && captured.skipped === null)
+  if (captured === null || captured.attachments.length === 0 && captured.errors.length === 0 && captured.hydration === null && captured.skipped === null)
     return "";
   const lines2 = [];
   const frames = captured.attachments.filter((attachment) => attachment.kind === "frame" || attachment.kind === "note");
@@ -3522,6 +3804,9 @@ function capturedBlock(captured) {
     for (const error of captured.errors)
       lines2.push(`  - ${error}`);
   }
+  if (captured.hydration !== null) {
+    lines2.push(`After load, ${captured.hydration.framework} rebuilt this page in the browser from the app's own JavaScript and data (${captured.hydration.message}). Markup edited in the served HTML shows for a moment and is then replaced, so make the change where that JavaScript gets what it renders: the data or source it reads, or a per-direction override that a shared script reads with the original as its default. Look at the result a few seconds after load, not at first paint.`);
+  }
   if (captured.skipped !== null) {
     lines2.push(`(${captured.skipped} Use the live preview instead.)`);
   }
@@ -5289,6 +5574,7 @@ function resolveTitle(input, titles, renames) {
 
 // ../server/dist/server.js
 import { createReadStream, existsSync as existsSync3, statSync, unwatchFile, watch as watchFs, watchFile } from "fs";
+import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir8, readdir as readdir3, writeFile as writeFile8 } from "fs/promises";
 import http2 from "http";
 import net3 from "net";
@@ -5367,6 +5653,30 @@ function sendJson(res, status, body) {
   });
   res.end(payload);
 }
+function etagMatches(value, etag) {
+  if (value === void 0)
+    return false;
+  const values = Array.isArray(value) ? value : [value];
+  return values.some((header) => header.split(",").some((candidate) => {
+    const tag = candidate.trim();
+    return tag === "*" || tag === etag || tag === `W/${etag}`;
+  }));
+}
+function sendConditionalJson(req, res, body) {
+  const payload = JSON.stringify(body);
+  const etag = `"${createHash2("sha256").update(payload).digest("base64url")}"`;
+  if (etagMatches(req.headers["if-none-match"], etag)) {
+    res.writeHead(304, { etag, "cache-control": "private, no-cache" });
+    res.end();
+    return;
+  }
+  res.writeHead(200, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "private, no-cache",
+    etag
+  });
+  res.end(payload);
+}
 var CAPTURE_DEADLINE_MS = 15e3;
 var CAPTURE_LOAD_MS = Math.floor(CAPTURE_DEADLINE_MS * LOAD_SHARE);
 function captureSlug(title) {
@@ -5759,9 +6069,10 @@ async function startServer(options) {
       return preview;
     const state = branches.state(preview.title) ?? { status: "idle" };
     const { url: route, ...withoutUrl } = preview;
+    const branchUrl = branches.url(preview.title);
     return state.status === "ready" ? {
       ...withoutUrl,
-      url: `${state.worktree.url}${route}`,
+      url: `${branchUrl ?? state.worktree.url}${route}`,
       state: publicBranchState(state)
     } : { ...withoutUrl, state: publicBranchState(state) };
   };
@@ -5770,7 +6081,7 @@ async function startServer(options) {
     if (preview.branch === void 0)
       return preview;
     const state = branches.state(preview.title);
-    return state?.status === "ready" ? { ...preview, url: `${state.worktree.url}${preview.url}` } : null;
+    return state?.status === "ready" ? { ...preview, url: `${branches.url(preview.title) ?? state.worktree.url}${preview.url}` } : null;
   };
   if (options.pool === void 0) {
     void reapOrphanedBrowsers().catch(() => {
@@ -5833,7 +6144,7 @@ async function startServer(options) {
         errors.push(notice);
       return void readLocalPreviews(cwd).then(({ previews: local, errors: localErrors }) => {
         if (localErrors.length > 0) {
-          return sendJson(res, 200, {
+          return sendConditionalJson(req, res, {
             project,
             devServer: target,
             scanPreviews: config?.scanPreviews ?? true,
@@ -5846,7 +6157,7 @@ async function startServer(options) {
         const currentBoot = boot.filter((preview) => preview.local !== true || localTitles.has(preview.title));
         const known = new Set(currentBoot.map((preview) => preview.title));
         const fresh = local.filter((preview) => !known.has(preview.title) && preview.branch === void 0 && preview.file === void 0);
-        sendJson(res, 200, {
+        sendConditionalJson(req, res, {
           project,
           devServer: target,
           scanPreviews: config?.scanPreviews ?? true,
@@ -5854,7 +6165,7 @@ async function startServer(options) {
           errors,
           warnings: configWarnings
         });
-      }).catch(() => sendJson(res, 200, {
+      }).catch(() => sendConditionalJson(req, res, {
         project,
         devServer: target,
         scanPreviews: config?.scanPreviews ?? true,
@@ -6177,6 +6488,7 @@ async function startServer(options) {
             height: shot.height,
             viewport: result.frame.width,
             errors: result.errors,
+            hydration: result.hydration,
             cut: result.cut
           });
         } catch (error) {
@@ -6289,7 +6601,7 @@ async function startServer(options) {
         waiting: null,
         failedIds: []
       };
-      return void readRequests(cwd).then((requests) => sendJson(res, 200, {
+      return void readRequests(cwd).then((requests) => sendConditionalJson(req, res, {
         requests: requests.map(({ id, title, intent, mode, status, failure, notes }) => ({
           id,
           title,
@@ -6392,7 +6704,7 @@ async function startServer(options) {
       });
     }
     if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "GET") {
-      return void readAnnotations(cwd).then((annotations) => sendJson(res, 200, { annotations }));
+      return void readAnnotations(cwd).then((annotations) => sendConditionalJson(req, res, { annotations }));
     }
     if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "POST") {
       if (!hasJsonBody(req)) {
@@ -6518,7 +6830,7 @@ async function startServer(options) {
       });
     }
     if (path === `${LEGLAS_PREFIX}/api/health`) {
-      return void probe(target).then((reachable) => sendJson(res, 200, { devServer: target, reachable, cwd }));
+      return void probe(target).then((reachable) => sendConditionalJson(req, res, { devServer: target, reachable, cwd }));
     }
     if (path.startsWith(`${FILES_PREFIX}/`)) {
       const rest = path.slice(FILES_PREFIX.length + 1);
@@ -6708,7 +7020,7 @@ async function runInit(options, deps) {
 
 // src/run-keep.ts
 import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir9, readFile as readFile13, rm as rm5, writeFile as writeFile10 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir9, readFile as readFile13, rm as rm5, writeFile as writeFile10 } from "fs/promises";
 import { dirname as dirname9, join as join14 } from "path";
 
 // src/resolve-title.ts
@@ -6736,6 +7048,29 @@ function renameExport(source, to) {
     to
   );
 }
+async function writeLogEntry(options) {
+  const entry = composeEntry({
+    surface: options.surface,
+    won: options.won,
+    previews: options.previews,
+    requests: await readRequests(options.cwd),
+    annotations: await readAnnotations(options.cwd),
+    date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  });
+  const dir = join14(options.cwd, options.logDir);
+  await mkdir9(dir, { recursive: true });
+  const file = join14(dir, `${entry.slug}.md`);
+  await writeFile10(file, entry.markdown, "utf8");
+  if (entry.pictures.length > 0) {
+    const pictureDir = join14(dir, entry.slug);
+    await mkdir9(pictureDir, { recursive: true });
+    for (const picture of entry.pictures) {
+      await copyFile2(join14(options.cwd, picture.from), join14(pictureDir, picture.to)).catch(() => {
+      });
+    }
+  }
+  return `${options.logDir}/${entry.slug}.md`;
+}
 async function runKeep(options, deps) {
   const loaded = await loadConfig(options.cwd);
   const local = await readLocalPreviews(options.cwd);
@@ -6764,6 +7099,20 @@ async function runKeep(options, deps) {
   const source = await readFile13(from, "utf8");
   await mkdir9(dirname9(to), { recursive: true });
   await writeFile10(to, renameExport(source, plan.exportName), "utf8");
+  const surface = plan.removeDir.slice(plan.removeDir.lastIndexOf("/") + 1);
+  let logged = null;
+  let logError = null;
+  try {
+    logged = await writeLogEntry({
+      cwd: options.cwd,
+      logDir: loaded.config?.logDir ?? DEFAULT_LOG_DIR,
+      surface,
+      won: { title: resolved.title, to: plan.move.to },
+      previews: previews.filter((preview) => plan.dropTitles.includes(preview.title))
+    });
+  } catch (error) {
+    logError = error instanceof Error ? error.message : String(error);
+  }
   await rm5(join14(options.cwd, plan.removeDir), { recursive: true, force: true });
   const dropped = await dropLocalPreviews(options.cwd, plan.dropTitles);
   if (options.json) {
@@ -6775,6 +7124,8 @@ async function runKeep(options, deps) {
         exportName: plan.exportName,
         removed: plan.removeDir,
         droppedPreviews: dropped,
+        logged,
+        logError,
         instructions: plan.instructions
       })
     );
@@ -6782,6 +7133,8 @@ async function runKeep(options, deps) {
   }
   deps.log(`  kept     ${plan.move.to}`);
   deps.log(`  removed  ${plan.removeDir}`);
+  if (logged !== null) deps.log(`  logged   ${logged}`);
+  if (logError !== null) deps.error(`  The decision log could not be written: ${logError}`);
   if (dropped > 0) {
     deps.log(`  dropped  ${dropped} direction${dropped === 1 ? "" : "s"} from the rail`);
   }
@@ -7168,6 +7521,10 @@ async function runShow(options, deps) {
       height: captured.height,
       viewport: captured.viewport,
       errors: Array.isArray(captured.errors) ? captured.errors.filter((error) => typeof error === "string") : [],
+      hydration: typeof captured.hydration === "object" && captured.hydration !== null && typeof captured.hydration.framework === "string" && typeof captured.hydration.message === "string" ? {
+        framework: captured.hydration.framework,
+        message: captured.hydration.message
+      } : null,
       cut: captured.cut === true
     };
   }
@@ -7195,6 +7552,12 @@ async function runShow(options, deps) {
     if (envelope2.screenshot.cut) {
       deps.log("              the top of the page only; it is taller than one capture");
     }
+    if (envelope2.screenshot.hydration !== null) {
+      deps.log(
+        `  hydration   ${envelope2.screenshot.hydration.framework} rebuilt the page in the browser after load; the served markup is not what is on screen`
+      );
+      deps.log(`              ${envelope2.screenshot.hydration.message}`);
+    }
     if (envelope2.screenshot.errors.length > 0) {
       const count = envelope2.screenshot.errors.length;
       deps.log(`  console     ${count} ${count === 1 ? "error" : "errors"} on load`);