@grimoire-rs/indexer 0.3.2 → 0.3.3

package/dist/renderer/astro/components/Catalog.js

@@ -120,12 +120,21 @@ function CopyButton({ command, variant = "default", name, }) {
 // hydrates in the browser, so importing the build-time payload here would
 // ship the whole catalog twice.
 export default function Catalog({ packages, vscodeExtension, }) {
-    // Seeded from `?q=…` on the very first render, not from an effect: a
-    // keyword chip on a package page links here, and filtering one render late
-    // means painting the full catalog and then collapsing it. The server has
-    // no `location`, so it renders the unfiltered list — which is what a
-    // crawler and a `?q=`-less visitor should both get.
-    const [query, setQuery] = useState(() => typeof location === "undefined" ? "" : (new URLSearchParams(location.search).get("q") ?? ""));
+    // Empty on the first render, ALWAYS — `?q=…` is applied a beat later, in
+    // the layout effect below. This is not a style preference, it is the one
+    // rule this island has to obey.
+    //
+    // Preact does not diff props while hydrating; its own source says so, and
+    // only re-applies props whose value is a function. Text children *are*
+    // diffed. So when the first client render disagrees with the server's, you
+    // get cards whose text is right and whose every attribute belongs to
+    // whichever package the server put at that position: one package's logo
+    // over another's name, and a link that opens the wrong page. Nothing
+    // throws. This used to seed from `location` here, and did exactly that.
+    const [query, setQuery] = useState("");
+    // Whether the URL's query has been applied. Gates the reveal below, so the
+    // catalog is never unhidden while it still shows the unfiltered list.
+    const [seeded, setSeeded] = useState(false);
     const [kind, setKind] = useState(null);
     const [sort, setSort] = useState("name");
     // Deprecated packages are hidden until asked for: a retired package is
@@ -168,19 +177,29 @@ export default function Catalog({ packages, vscodeExtension, }) {
             behavior: matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth",
         });
     };
+    // Apply `?q=…`, now that hydration has matched the server's markup and
+    // Preact owns the tree. A layout effect rather than a plain one: the
+    // resulting render must land before the browser paints, or a `?q=` visitor
+    // sees the whole catalog flash past on the way to their results.
+    useLayoutEffect(() => {
+        setQuery(new URLSearchParams(location.search).get("q") ?? "");
+        setSeeded(true);
+    }, []);
     // Base.astro hides the catalog before first paint when the URL carries a
-    // query. Reveal it once this render — the filtered one — has hit the DOM.
-    // A layout effect, so the reveal lands in the same frame as the content.
+    // query. Reveal it only once the filtered render is in the DOM — keyed on
+    // `seeded`, so the unfiltered first render is never the one revealed.
     useLayoutEffect(() => {
-        // Hydration attaches handlers but does not diff props against the server
-        // markup, so the box the server rendered empty stays empty even though
-        // this render filtered on `query`. Written straight to the DOM, which is
-        // what the vnode already claims.
+        if (!seeded)
+            return;
+        // The input's `value` prop was skipped during hydration for the same
+        // reason every other prop was, and the render that applied the query is
+        // a normal diff — but write it anyway: this effect is also what runs on
+        // a `?q=`-less load, where no second render is queued at all.
         const input = searchRef.current;
         if (input && input.value !== query)
             input.value = query;
         delete document.documentElement.dataset.query;
-    }, []);
+    }, [seeded]);
     // `/` jumps to the search box, the convention every package registry
     // shares. Bound on the document so it works wherever the reader is.
     useEffect(() => {

package/dist/renderer/astro/components/Catalog.tsx

@@ -187,14 +187,21 @@ export default function Catalog({
   packages: CatalogPackage[];
   vscodeExtension: string | null;
 }) {
-  // Seeded from `?q=…` on the very first render, not from an effect: a
-  // keyword chip on a package page links here, and filtering one render late
-  // means painting the full catalog and then collapsing it. The server has
-  // no `location`, so it renders the unfiltered list — which is what a
-  // crawler and a `?q=`-less visitor should both get.
-  const [query, setQuery] = useState(() =>
-    typeof location === "undefined" ? "" : (new URLSearchParams(location.search).get("q") ?? ""),
-  );
+  // Empty on the first render, ALWAYS — `?q=…` is applied a beat later, in
+  // the layout effect below. This is not a style preference, it is the one
+  // rule this island has to obey.
+  //
+  // Preact does not diff props while hydrating; its own source says so, and
+  // only re-applies props whose value is a function. Text children *are*
+  // diffed. So when the first client render disagrees with the server's, you
+  // get cards whose text is right and whose every attribute belongs to
+  // whichever package the server put at that position: one package's logo
+  // over another's name, and a link that opens the wrong page. Nothing
+  // throws. This used to seed from `location` here, and did exactly that.
+  const [query, setQuery] = useState("");
+  // Whether the URL's query has been applied. Gates the reveal below, so the
+  // catalog is never unhidden while it still shows the unfiltered list.
+  const [seeded, setSeeded] = useState(false);
   const [kind, setKind] = useState<string | null>(null);
   const [sort, setSort] = useState<Sort>("name");
   // Deprecated packages are hidden until asked for: a retired package is
@@ -240,18 +247,28 @@ export default function Catalog({
     });
   };
 
+  // Apply `?q=…`, now that hydration has matched the server's markup and
+  // Preact owns the tree. A layout effect rather than a plain one: the
+  // resulting render must land before the browser paints, or a `?q=` visitor
+  // sees the whole catalog flash past on the way to their results.
+  useLayoutEffect(() => {
+    setQuery(new URLSearchParams(location.search).get("q") ?? "");
+    setSeeded(true);
+  }, []);
+
   // Base.astro hides the catalog before first paint when the URL carries a
-  // query. Reveal it once this render — the filtered one — has hit the DOM.
-  // A layout effect, so the reveal lands in the same frame as the content.
+  // query. Reveal it only once the filtered render is in the DOM — keyed on
+  // `seeded`, so the unfiltered first render is never the one revealed.
   useLayoutEffect(() => {
-    // Hydration attaches handlers but does not diff props against the server
-    // markup, so the box the server rendered empty stays empty even though
-    // this render filtered on `query`. Written straight to the DOM, which is
-    // what the vnode already claims.
+    if (!seeded) return;
+    // The input's `value` prop was skipped during hydration for the same
+    // reason every other prop was, and the render that applied the query is
+    // a normal diff — but write it anyway: this effect is also what runs on
+    // a `?q=`-less load, where no second render is queued at all.
     const input = searchRef.current;
     if (input && input.value !== query) input.value = query;
     delete document.documentElement.dataset.query;
-  }, []);
+  }, [seeded]);
 
   // `/` jumps to the search box, the convention every package registry
   // shares. Bound on the document so it works wherever the reader is.

package/dist/renderer/astro/layouts/Base.astro

@@ -68,9 +68,10 @@ function repoLabel(url: string): string {
       // package page) means the catalog the server rendered — every package,
       // empty search box — is the wrong one. Flag it so CSS holds the
       // catalog back rather than showing the full list and collapsing it a
-      // moment later. The island drops the flag on its first render, which
-      // is already the filtered one; the timeout is the failsafe for an
-      // island that never hydrates, where a flash beats a blank page.
+      // moment later. The island drops the flag once it has applied the
+      // query — which is the render after hydration, never the hydrating one
+      // itself; the timeout is the failsafe for an island that never
+      // hydrates, where a flash beats a blank page.
       if (new URLSearchParams(location.search).get("q")) {
         document.documentElement.dataset.query = "";
         setTimeout(() => delete document.documentElement.dataset.query, 3000);
@@ -864,8 +865,10 @@ function repoLabel(url: string): string {
            search box, so painting it and then collapsing to the match is a
            flash of the wrong answer. `visibility` rather than `display` —
            the space stays reserved, so the footer does not jump either. The
-           attribute is set before first paint and dropped by the island's
-           first render, which is already the filtered one. */
+           attribute is set before first paint and dropped once the island
+           has applied the query — the render after hydration, because
+           hydrating against markup that disagrees with the server silently
+           mismatches every attribute (see Catalog.tsx). */
         :root[data-query] .catalog {
           visibility: hidden;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grimoire-rs/indexer",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "CLI + Astro integration for running your own grim package index",
   "type": "module",
   "license": "Apache-2.0",
@@ -38,6 +38,7 @@
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.0",
     "js-yaml": "^4.1.0",
+    "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"