@blamejs/blamejs-shop 0.4.11 → 0.4.12

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.12 (2026-06-05) — **Blog posts render their Markdown, plural search queries match again, and the search-ranking metrics view gets the impression and click data it was built to read.** Four search-and-content fixes. Published blog posts were showing their raw Markdown source — headings, bold, and links rendered as literal text — even though the authoring screen has always promised Markdown; the edge now renders it through the same sanitized renderer the post primitive uses, so the live page matches the editor's promise. The query stemmer over-stripped plurals ending in a vowel plus "es" ("tees", "shoes", "does"), so those searches missed their synonym groups and matched unrelated products; it now strips those down to the right singular. The search-ranking event log finally has production writers — every search records an impression and every result click records a click against the active weight set, so the admin search-metrics view shows real click-through and conversion instead of an empty table. And the analytics search funnel now applies the same hygiene the autocomplete log does, so "Popular searches" and the analytics top-terms report agree. **Added:** *Search-ranking impressions and clicks are recorded, so the admin metrics view has data* — The search-ranking feature ships a weight-set metrics view that reads an event log to report click-through, conversion, and click-to-purchase per weight set — but nothing ever wrote those events, so the view was always empty. Two writers are now wired. Every search records one impression against the active weight set (a drop-silent, fire-and-forget write that never affects the search response). Every search result link carries a `?from=search` marker plus the query it was ranked for; when a shopper follows one to a product page, that page records a click against the active weight set. Both work with JavaScript off — the click signal is read server-side from the link, with no tracking beacon. Facet narrowing is recorded the same way, so the facet-usage rollup reflects real use. Purchase attribution is deliberately left out of this release: tying a completed order back to the search that led to it needs a session-to-order link the event schema doesn't carry, so the metrics view reports impressions, clicks, and the click-through ratio from real traffic while purchase counts and conversion stay at zero until that linkage ships. **Fixed:** *Blog posts render Markdown instead of showing the raw source* — A published post's body is authored in Markdown — the editor labels the field "Body (Markdown)" and the post primitive's renderer turns headings, lists, blockquotes, rules, inline code, bold, italic, and https-or-rooted links into HTML. But the edge-served public post page painted the body as plain escaped text, so a shopper saw literal `## Heading` and `**bold**` markers rather than formatted copy. The edge now renders the body through the same sanitized renderer the primitive uses, so the live page matches what the editor previews and the authoring screen promises. The security posture is unchanged: every operator-authored byte is HTML-escaped, raw HTML never passes through (any `<` lands as `&lt;`), and link URLs are restricted to https or `/`-rooted paths — a `<script>` or `javascript:` link in a post body renders inert. · *Plural search queries ending in a vowel plus "es" match again* — The query stemmer tried its `-es` plural rule before its `-s` rule, so a word ending in a vowel plus "es" was over-stripped: "tees" became "te", "shoes" became "sho", "does" became "do". Two things broke as a result — the over-stripped term no longer matched its operator-curated synonym group (so a search for "tees" missed a "tee"/"t-shirt" grouping), and the truncated term fed a broad substring match that surfaced unrelated products. The stemmer now strips the full `-es` only when the stem ends in a sibilant ("boxes" → "box", "dishes" → "dish", "churches" → "church") and takes the bare `-s` otherwise ("tees" → "tee", "shoes" → "shoe", "does" → "doe"). The edge search mirror carries the identical rule, so the result is the same whether the page is served from the edge cache or the container. · *The analytics search funnel and the autocomplete log apply the same query hygiene* — Two search sinks recorded the typed query with different cleaning. The autocomplete query log stripped control bytes and lowercased before writing; the analytics funnel that feeds the top-search-terms report trimmed only — so a control byte could reach the analytics table raw, and the two reports counted differently. The storefront now normalizes the query once (strip control bytes, trim, lowercase) and hands the same value to both sinks. The analytics top-terms report also groups case-insensitively, so a term typed as "Hat" and "hat" collapses into one row — folding any mixed-case history written before this — matching how "Popular searches" has always counted. The consent gate on analytics recording is unchanged.
+
 - v0.4.11 (2026-06-05) — **Search autocomplete: a live suggestions dropdown in the header, plus an admin screen to curate it.** Typing in the storefront search box now opens an autocomplete dropdown with matching products, what other shoppers are searching for, and operator-curated featured links. A new admin screen pins those featured suggestions and surfaces a popular-searches report so you can see demand and spot terms that return nothing. The search box keeps working with JavaScript off — the dropdown is a progressive enhancement on top of the plain form. **Added:** *Search autocomplete in the storefront header* — As a shopper types in the header search box, a dropdown opens beneath it with up to three groups: matching products (linking straight to the product page), popular recent searches (click one to run it), and operator-curated featured suggestions (linking wherever you point them). It's keyboard-navigable — arrow keys move through the list, Enter picks, Escape dismisses — and announces itself to screen readers as a combobox. The dropdown is served from a cacheable JSON endpoint that carries no per-visitor data, and it's a pure enhancement: with JavaScript off, or before the data loads, the box stays an ordinary search form that submits to the results page. · *Search-suggestions admin screen* — A new Search suggestions screen under the admin console lets you curate featured suggestions: pin a typed prefix (for example, prefix "free" surfaces "Free shipping over $50"), set its destination link, priority, and an optional active window, then edit the priority or status inline or remove it. Below the curation table, a read-only Popular searches view reports what shoppers have typed over the last 30 days — each term's search count, its zero-result share, and when it was last seen — so a high zero-result term flags a stock or naming gap worth closing. Every search a shopper runs is logged for this report (the visitor's session identifier is hashed before storage), and entries older than 90 days are pruned automatically.
 
 - v0.4.10 (2026-06-05) — **The Promo banners console is back in the admin nav.** The promo-banners management screen introduced in 0.4.4 was fully built and mounted, but the admin nav never showed its link: the nav filters items against an availability map, and the map was missing the one key the Promo banners item checks, so the link was filtered off every page and the screen was reachable only by typing /admin/promo-banners. The key is in the map now, and a contract test pins every nav item's gate key to the map so a future screen can't ship undiscoverable the same way. **Added:** *Nav gate keys are contract-tested* — A test now parses every nav item's gate key against the availability map and fails the suite on any mismatch, in either direction of drift — a new screen whose key is forgotten can't ship with a permanently hidden link again. **Fixed:** *Promo banners nav link renders* — The admin nav gates each item on an availability map keyed by the deps the console was mounted with. The Promo banners item checked a key the map never defined, which reads as permanently unavailable — so the link was hidden on every authenticated admin page even though the screen itself mounted and worked. Operators see the link again wherever the promo-banners primitive is wired.

package/lib/analytics.js

@@ -492,18 +492,26 @@ function create(opts) {
     // GROUPs by the denormalised column so the query never decodes
     // the JSON payload. Default limit 10; max 100 (same envelope as
     // `topSKUs`).
+    //
+    // GROUPs + sorts on `lower(search_q)` so "Tee" and "tee" collapse
+    // into one row, matching how the autocomplete "Popular searches"
+    // aggregate (search-suggestions, which lowercases on write)
+    // counts them. New writes already arrive lowercased from the
+    // storefront record site; lowering at aggregate time folds any
+    // mixed-case history written before that. ASCII queries only, so
+    // SQLite's built-in `lower()` (ASCII-only) is sufficient.
     topSearchTerms: async function (windowOpts) {
       var w = _resolveEventWindow(windowOpts);
       var limit = (windowOpts && windowOpts.limit) == null ? 10 : windowOpts.limit;
       _limit(limit, "limit");
       var r = await query(
-        "SELECT search_q AS search_q, COUNT(*) AS count " +
+        "SELECT lower(search_q) AS search_q, COUNT(*) AS count " +
         "  FROM analytics_events " +
         " WHERE event_type = 'search_query' " +
         "   AND search_q IS NOT NULL " +
         "   AND occurred_at >= ?1 AND occurred_at < ?2 " +
-        " GROUP BY search_q " +
-        " ORDER BY count DESC, search_q ASC " +
+        " GROUP BY lower(search_q) " +
+        " ORDER BY count DESC, lower(search_q) ASC " +
         " LIMIT ?3",
         [w.from, w.to, limit],
       );

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.11",
+  "version": "0.4.12",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/search-synonyms.js

@@ -276,7 +276,21 @@ function _stem(token) {
   if (token.length >= 5 && token.slice(-3) === "ies") return token.slice(0, -3) + "y";
   if (token.length >= 5 && token.slice(-3) === "ing") return token.slice(0, -3);
   if (token.length >= 4 && token.slice(-2) === "ed")  return token.slice(0, -2);
-  if (token.length >= 4 && token.slice(-2) === "es")  return token.slice(0, -2);
+  // `-es` is only a true plural suffix when the stem ends in a sibilant
+  // (`s`/`x`/`z`/`ch`/`sh`): boxes -> box, dishes -> dish, churches ->
+  // church. For vowel-final stems the singular keeps a trailing `e` and
+  // the plural is a bare `-s` — stripping `-es` there over-strips
+  // (tees -> te, shoes -> sho, does -> do). Strip `-es` only for the
+  // sibilant case; everything else falls through to the bare `-s` rule
+  // (tees -> tee, shoes -> shoe, does -> doe).
+  if (token.length >= 4 && token.slice(-2) === "es") {
+    var esStem = token.slice(0, -2);
+    var esLast = esStem.slice(-1);
+    var esLast2 = esStem.slice(-2);
+    if (esLast === "s" || esLast === "x" || esLast === "z" || esLast2 === "ch" || esLast2 === "sh") {
+      return esStem;
+    }
+  }
   if (token.length >= 4 && token.slice(-1) === "s")   return token.slice(0, -1);
   return token;
 }

package/lib/storefront.js

@@ -1854,6 +1854,9 @@ var SEARCH_MAX_FACET_KEYS   = 32;
 var SEARCH_MAX_FACET_VALUES = 64;
 var SEARCH_MAX_VALUE_LEN    = 256;
 var SEARCH_CONTROL_BYTE_RE  = /[\x00-\x1f\x7f]/;
+// Global twin for strip-all replaces (the non-global one above is used for
+// presence tests; `.replace` needs the `g` flag to clear every byte).
+var SEARCH_CONTROL_BYTE_RE_G = /[\x00-\x1f\x7f]/g;
 
 // Parse `?key=value` repeats off a parsed URL into the
 // `{ facetKey: [value, ...] }` shape the searchFacets primitive
@@ -1942,13 +1945,20 @@ function renderSearch(opts) {
   } else {
     var assetPrefix = opts.asset_prefix || "/assets/";
     var fmt = _priceFormatter(opts);
+    // `?from=search&sq=<query>` marks the click as originating in a ranked
+    // result list. The PDP route reads it to log a click event against the
+    // active ranking weight set (the impression/click signals the admin
+    // search-metrics view aggregates); `sq` carries the query the list was
+    // ranked for, which recordSearchEvent requires. Works with JS off; no
+    // beacon. Mirrored byte-for-byte by worker/render/search.js.
+    var resultLinkSuffix = "?from=search&sq=" + encodeURIComponent(qTrim.slice(0, 200));
     var cards = products.map(function (p) {
       var priceStr = p.starting_price_minor != null
         ? fmt(p.starting_price_minor, p.starting_price_currency || "USD")
         : "—";
       var imageUrl = p.hero_media ? assetPrefix + p.hero_media.r2_key : null;
       var imageAlt = p.hero_media ? (p.hero_media.alt_text || p.title) : null;
-      return _buildProductCard({ title: p.title, price: priceStr, slug: p.slug, image_url: imageUrl, image_alt: imageAlt });
+      return _buildProductCard({ title: p.title, price: priceStr, slug: p.slug + resultLinkSuffix, image_url: imageUrl, image_alt: imageAlt });
     }).join("\n");
     resultsInner = "<section class=\"search-grid\"><div class=\"grid\">" + cards + "</div></section>";
   }
@@ -10661,6 +10671,88 @@ function mount(router, deps) {
     } catch (_e) { /* drop-silent — analytics is supplementary to every request */ }
   }
 
+  // Search-ranking impression. Resolves the active weight set, then logs a
+  // single list-level impression against it. The metrics view aggregates
+  // impressions per weights_slug to compute CTR / conversion, so the slug
+  // is the join key; query is denormalised for operator inspection. No
+  // active set → no-op (recordSearchEvent would throw SEARCH_WEIGHTS_NOT
+  // _FOUND, which the catch swallows). HOT PATH: fire-and-forget +
+  // drop-silent — a metrics write must never affect the search response.
+  function _recordSearchImpression(req, term) {
+    if (!deps.searchRanking) return;
+    try {
+      var sid = null;
+      try { sid = _readSidCookie(req); } catch (_e) { sid = null; }
+      Promise.resolve(deps.searchRanking.activeWeights())
+        .then(function (active) {
+          if (!active || !active.slug) return;   // ranking not configured → nothing to attribute
+          var ev = { query: term, event_type: "impression", weights_slug: active.slug };
+          if (sid) ev.session_id = sid;
+          return deps.searchRanking.recordSearchEvent(ev);
+        })
+        .catch(function () { /* drop-silent — impression bump never fails the search */ });
+    } catch (_e) { /* drop-silent — supplementary to every search */ }
+  }
+
+  // Search-ranking click. Logged from the PDP route when the inbound link
+  // carried `?from=search`. Attributes the click to whatever weight set is
+  // active at click time — the same set new impressions log against — so
+  // CTR stays coherent (an operator rarely flips the active set mid-session;
+  // if they do, both new impressions and new clicks follow the new set).
+  // `productId` is denormalised for inspection; the metrics view keys on the
+  // weights_slug + time window. HOT PATH: fire-and-forget + drop-silent.
+  function _recordSearchClick(req, term, productId) {
+    if (!deps.searchRanking) return;
+    // recordSearchEvent requires a non-empty query; a click that lost its
+    // `sq` marker can't be attributed, so skip rather than fire a call that
+    // would throw.
+    if (typeof term !== "string" || term.trim().length === 0) return;
+    try {
+      var sid = null;
+      try { sid = _readSidCookie(req); } catch (_e) { sid = null; }
+      Promise.resolve(deps.searchRanking.activeWeights())
+        .then(function (active) {
+          if (!active || !active.slug) return;
+          var ev = { query: term, event_type: "click", weights_slug: active.slug };
+          if (productId) ev.product_id = productId;
+          if (sid) ev.session_id = sid;
+          return deps.searchRanking.recordSearchEvent(ev);
+        })
+        .catch(function () { /* drop-silent — click bump never fails the PDP */ });
+    } catch (_e) { /* drop-silent — supplementary to every PDP view */ }
+  }
+
+  // Facet-usage events. One per applied facet value the shopper narrowed
+  // by, so the admin facet-usage rollup reflects real use. `filters` is the
+  // `{ key: [value, ...] }` shape the search handler already parsed +
+  // validated against the live facet defs. HOT PATH: fire-and-forget +
+  // drop-silent — a usage write must never affect the search response.
+  function _recordFacetUses(req, filters) {
+    if (!deps.searchFacets) return;
+    try {
+      var sid = null;
+      try { sid = _readSidCookie(req); } catch (_e) { sid = null; }
+      var sessionId = sid || "anon";
+      // searchFacets is a per-request factory (bound to a catalog); the
+      // usage write needs no catalog, so an instance with an empty list
+      // adapter is enough for recordFacetUse.
+      var sf = deps.searchFacets({ list: function () { return Promise.resolve({ rows: [] }); } });
+      var keys = Object.keys(filters);
+      for (var k = 0; k < keys.length; k += 1) {
+        var values = filters[keys[k]];
+        if (!Array.isArray(values)) continue;
+        for (var v = 0; v < values.length; v += 1) {
+          (function (key, value) {
+            try {
+              Promise.resolve(sf.recordFacetUse({ key: key, value: value, session_id: sessionId }))
+                .catch(function () { /* drop-silent — usage bump never fails the search */ });
+            } catch (_e) { /* drop-silent — skip a value that fails validation */ }
+          })(keys[k], values[v]);
+        }
+      }
+    } catch (_e) { /* drop-silent — supplementary to every search */ }
+  }
+
   // Resolve the active trust badges for a container-only placement and
   // concatenate each one's sanitized renderHtml. Fires an impression per
   // rendered badge (fire-and-forget — the counter is drop-silent on the hot
@@ -12353,12 +12445,20 @@ function mount(router, deps) {
       shop_name:       shopName,
       cart_count:      cartCount,
     }, _requestUrls(req), ccy)));
+    // One hygiene pass for every search sink. The autocomplete query log
+    // (searchSuggestions.recordQuery) strips control bytes + lowercases
+    // before it writes; the analytics funnel must see the SAME shape so
+    // "Popular searches" and the analytics "top search terms" aggregate
+    // the same rows. Strip control bytes, trim, lowercase once here — a
+    // query that was only control bytes / whitespace collapses to "" and
+    // every sink below skips it.
+    var searchTerm = q.replace(SEARCH_CONTROL_BYTE_RE_G, "").trim().toLowerCase();
     // Consent-gated funnel event — feeds the top-search-terms aggregate.
-    // Only a real (non-empty) query counts; the typed term is bounded to
-    // 200 chars above (recordEvent caps search_q at 256). Container-served
+    // Only a real (non-empty) query counts; the term is bounded to 200
+    // chars above (recordEvent caps search_q at 256). Container-served
     // only; fire-and-forget + drop-silent.
-    if (q.trim().length > 0) {
-      _recordAnalyticsEvent(req, { event_type: "search_query", search_q: q.trim() });
+    if (searchTerm.length > 0) {
+      _recordAnalyticsEvent(req, { event_type: "search_query", search_q: searchTerm });
     }
     // Log the query for the admin "Popular searches" view + the autocomplete
     // popular-terms group. Observability sink — drop-silent by design: a
@@ -12367,10 +12467,10 @@ function mount(router, deps) {
     // hashes it before any write, so neither value is recoverable). Only a
     // real (non-empty) query is logged. Alongside it, a self-gated retention
     // sweep runs at most once a day to prune rows past the 90-day window.
-    if (deps.searchSuggestions && q.trim().length > 0) {
+    if (deps.searchSuggestions && searchTerm.length > 0) {
       try {
         deps.searchSuggestions.recordQuery({
-          q:            q.trim(),
+          q:            searchTerm,
           session_id:   _readSidCookie(req) || "anon",
           result_count: totalCount,
         }).catch(function () { /* drop-silent — logging never fails the search */ });
@@ -12384,6 +12484,20 @@ function mount(router, deps) {
         } catch (_e2) { /* drop-silent — retention is best-effort */ }
       }
     }
+    // Search-ranking impression — one event per rendered result list,
+    // keyed to the active weight set (the slug the admin search-metrics
+    // view aggregates CTR / conversion against). recordSearchEvent rejects
+    // a missing weight set, so this is a no-op until the operator activates
+    // one. Observability sink — drop-silent by design: a metrics hiccup
+    // must never fail the search the shopper just ran.
+    if (deps.searchRanking && searchTerm.length > 0) {
+      _recordSearchImpression(req, searchTerm);
+    }
+    // Facet-narrowing usage — one event per applied facet value, so the
+    // admin can see which facets shoppers actually use. Drop-silent.
+    if (deps.searchFacets && searchTerm.length > 0 && filters && Object.keys(filters).length > 0) {
+      _recordFacetUses(req, filters);
+    }
   });
 
   // Autocomplete data for the header search box — the island (search-suggest.js)
@@ -12602,6 +12716,18 @@ function mount(router, deps) {
     // most-viewed-products aggregate. Container-served only (anonymous PDPs
     // are edge-cached and never reach here); fire-and-forget + drop-silent.
     _recordAnalyticsEvent(req, { event_type: "pdp_view", product_id: product.id });
+    // Search-ranking click — a PDP reached via a ranked result list carries
+    // `?from=search&sq=<query>`. Defensive reader: a missing / unrelated
+    // marker is the common case (direct nav, related-rail) and logs nothing;
+    // a blank / over-long `sq` is dropped by the primitive's own validation
+    // (caught drop-silent in _recordSearchClick). The click is attributed to
+    // the active weight set, the same set new impressions log against, so the
+    // admin search-metrics CTR stays coherent.
+    if (deps.searchRanking && pdpUrl && pdpUrl.searchParams.get("from") === "search") {
+      var clickQ = pdpUrl.searchParams.get("sq");
+      if (typeof clickQ === "string" && clickQ.length > 200) clickQ = clickQ.slice(0, 200);
+      _recordSearchClick(req, clickQ, product.id);
+    }
     _send(res, 200, html);
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {