leglas 0.8.0 → 0.9.0

package/README.md

@@ -12,6 +12,7 @@
   <a href="https://www.npmjs.com/package/leglas"><img src="https://img.shields.io/npm/v/leglas" alt="npm"></a>
   <a href="https://github.com/FredAmartey/leglas/actions/workflows/ci.yml"><img src="https://github.com/FredAmartey/leglas/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/leglas" alt="license"></a>
+  <a href="https://leglas.vercel.app/changelog/"><img src="https://img.shields.io/badge/changelog-what's%20new-0B1839" alt="changelog"></a>
 </p>
 
 <p align="center">
@@ -534,6 +535,7 @@ pnpm install
 pnpm build       # build every package
 pnpm test        # run the test suite
 pnpm typecheck   # type check every package
+pnpm site        # build the site, homepage and changelog, into dist/site
 ```
 
 | Package           | Contents                                           |
@@ -549,11 +551,18 @@ terminal and `pnpm --filter @leglas/shell dev` in another.
 Two packages are published, both unscoped: `leglas`, which bundles the
 server and the built interface, and `leglas-mcp`. Releases are
 tag-driven: set the same version in both packages and `plugin.json`, turn
-the changelog's Unreleased section into that version, push a `v<version>`
-tag, and CI runs the suite and publishes through npm trusted publishing.
-A tag that disagrees with the manifests is refused, and so is a patch tag
-when `api-surface.txt` has moved since the previous one. No npm token
-exists anywhere in the project.
+the changelog's Unreleased section into that version with a title for what
+the release was about, push a `v<version>` tag, and CI runs the suite and
+publishes through npm trusted publishing. A tag that disagrees with the
+manifests is refused, and so is a patch tag when `api-surface.txt` has
+moved since the previous one. No npm token exists anywhere in the project.
+
+The [site](https://leglas.vercel.app/) is two pages, the homepage and the
+[changelog](https://leglas.vercel.app/changelog/), written by `site.ts`. The
+changelog page is made from `CHANGELOG.md` and nothing else, so describing a
+release in the changelog is the whole job. Vercel builds it from
+`vercel.json` on every push, so main is the live site and every pull request
+gets a preview.
 
 ## License
 

package/dist/bin.js

@@ -2211,6 +2211,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;
@@ -2304,10 +2330,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);
@@ -2455,7 +2483,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();
@@ -2599,7 +2627,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();
@@ -2649,6 +2683,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];
@@ -3344,10 +3379,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");
@@ -3379,6 +3414,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.)`);
   }
@@ -6060,6 +6098,7 @@ async function startServer(options) {
             height: shot.height,
             viewport: result2.frame.width,
             errors: result2.errors,
+            hydration: result2.hydration,
             cut: result2.cut
           });
         } catch (error) {
@@ -6803,6 +6842,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
@@ -7566,6 +7613,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
     };
   }
@@ -7593,6 +7644,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`);

package/dist/index.js

@@ -688,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
@@ -2593,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;
@@ -2686,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);
@@ -2837,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();
@@ -2981,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();
@@ -3031,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];
@@ -3726,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");
@@ -3761,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.)`);
   }
@@ -6442,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) {
@@ -7474,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
     };
   }
@@ -7501,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`);