@justai/cuts 0.104.0 → 0.106.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.104.0",
+  "version": "0.106.0",
   "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {

package/src/Catalogue.astro

@@ -49,7 +49,15 @@ interface Props {
   /** Layer one. Empty is valid and correct for an apex with nothing seeded yet. */
   seed?: CatalogueEntry[];
   /** The curated sequence, keyed by host — read by the runtime sort. */
-  order?: Record<string, number>;
+  /** queries: order prop · curated order · data-order · the grid is not sorted · order type
+   *
+   * THE CURATED SEQUENCE, AS A LIST OF HOSTS — which is what the runtime sort reads, and what this
+   * type said until 2026-08-05. It was declared `Record<string, number>` while the script parsed it
+   * as `string[]`; app.zone happened to pass an array so nothing ever disagreed out loud, and
+   * pin.games passed `{}` for "no order" and took the whole runtime append down with it. A type that
+   * describes something other than what the consumer reads is worse than no type: it invites the one
+   * value that will break. */
+  order?: readonly string[];
   /** A shelf label per host: a card has one line to earn a tap, and a bio clamps. Keyed by host. */
   taglines?: Record<string, string>;
   /** Localized category names. The English key stays the stable filter value. */
@@ -78,7 +86,7 @@ interface Props {
 }
 const {
   lang, kind, apexHost,
-  seed = [], order = {}, taglines = {}, catLabels = {}, entries = {},
+  seed = [], order = [], taglines = {}, catLabels = {}, entries = {},
   locales, strings,
 } = Astro.props;
 
@@ -202,6 +210,17 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
       <section class="grid" id="grid" data-kind={kind} data-apex={apexHost} data-new-label={strings.new} data-cat-map={JSON.stringify(catLabels)} data-order={JSON.stringify(order)} data-taglines={JSON.stringify(taglines)}>
         {seed.map((app) => <CatalogueCard app={app} name={appName(app)} desc={appDesc(app)} isNew={isNew(app.added)} newLabel={strings.new} />)}
       </section>
+      {/* queries: runtime cards are unstyled · the card has no CSS · an apex with no seed · scope cid ·
+                   data-astro-cid · pin.games cards render as blue links
+          THE SCOPE, CARRIED IN AN INERT CARD. Cards appended at runtime are built as plain strings, so
+          they sit outside CatalogueCard's scoped CSS and have to be stamped with its `data-astro-cid-*`
+          by hand. That attribute was read off a SEEDED card — which works on any apex that ships a seed,
+          and fails completely on one that does not: pin.games opened with its only game rendered as bare
+          blue underlined links, because there was no card to read the scope from.
+          A <template> is the right home for it. Its content is parsed but never rendered, never matched
+          by a document query and never painted, while Astro still stamps the cid on it at build. So the
+          scope is available from the first paint whether or not this apex has ever seeded a card. */}
+      <template id="cardscope"><CatalogueCard app={{ id: "scope", url: "https://example.invalid", category: "", added: "" } as any} name="" desc="" isNew={false} newLabel="" /></template>
       {/* Both sentences ride data-attributes because the loader below is a BUNDLED script and
           cannot see props — the same seam Posts uses. */}
       <p class="empty" id="empty" hidden
@@ -413,8 +432,14 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
         try { return new URL(a.href).host; } catch { return ""; }
       }),
     );
-    // the appended cards must inherit AppCard's scoped styles → copy the cid attribute off a real card
-    const sample = grid.querySelector<HTMLElement>("a.card");
+    // The appended cards must inherit CatalogueCard's scoped styles → copy the cid off a real card, and
+    // fall back to the inert one in #cardscope when this apex ships no seed. Without that fallback an
+    // empty-seed storefront renders every runtime card as unstyled markup — measured on pin.games' first
+    // night, where the shelf's only game arrived as blue underlined links.
+    const scopeTpl = document.getElementById("cardscope") as HTMLTemplateElement | null;
+    const sample = grid.querySelector<HTMLElement>("a.card")
+      ?? scopeTpl?.content.querySelector<HTMLElement>("a.card")
+      ?? null;
     const scopeAttr = sample ? sample.getAttributeNames().find((n) => n.startsWith("data-astro-cid-")) || null : null;
 
     const esc = (s: unknown): string =>
@@ -539,8 +564,15 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
         // the registry — and an identifier that only matches one route fails silently on the other. A card
         // that fails to match reads as unlisted and jumps to the top, which is the worst possible failure
         // for an ordering bug: it looks deliberate. The host is what both routes agree on.
+        // Anything that is not a list means "no curated order" — never an exception. This parsed a
+        // `{}` once and `{}.map is not a function` killed everything after it, including the event
+        // that tells the filter new cards exist: the shelf showed a card AND "the first games are on
+        // their way" underneath it.
         const orderList: string[] = (() => {
-          try { return JSON.parse(grid.dataset.order || "[]"); } catch { return []; }
+          try {
+            const parsed = JSON.parse(grid.dataset.order || "[]");
+            return Array.isArray(parsed) ? parsed : [];
+          } catch { return []; }
         })();
         const rank = new Map(orderList.map((h, i) => [h, i]));
         const UNLISTED = -1;
@@ -559,9 +591,28 @@ const isNew = (added: string): boolean => { const t0 = Date.parse(added || "");
             return x.added < y.added ? 1 : -1;
           })
           .forEach(({ el }) => grid.appendChild(el));
-        document.dispatchEvent(new Event("zone:cards")); // newcomers in — let the URL filter catch them
+        // queries: the empty message shows under a card · zone:cards never fired · the filter did not
+        //          see the new cards · silent catch
+        //
+        // IN A `finally`, BECAUSE EVERYTHING ABOVE IT IS ORNAMENT AND THIS IS NOT. Once cards are in
+        // the DOM, the filter has to be told — it owns which of them are visible and whether the
+        // "nothing here" line is showing. Sorting them is a nicety; leaving the page claiming to be
+        // empty while a card sits above the claim is a defect a visitor sees.
+        //
+        // It sat at the end of a promise chain ending in `.catch(() => {})`, so one TypeError in the
+        // sort silenced it with nothing logged anywhere. That combination — a throw between the work
+        // and its announcement, and a catch that says nothing — is how a page ends up confidently
+        // wrong. The `finally` fixes the ordering; the catch below now says what it swallowed.
+      })
+      .catch((err) => {
+        // Never fatal — a storefront must render without the registry. But it must not be SILENT:
+        // the seed and the build-time layer are already on the page, and a swallowed error here is
+        // the difference between "no new personas today" and "the append is broken".
+        console.warn("[catalogue] runtime append failed", err);
       })
-      .catch(() => {});
+      .finally(() => {
+        document.dispatchEvent(new Event("zone:cards")); // cards are in — let the filter catch them
+      });
   })();
 </script>