@blamejs/blamejs-shop 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.4.9 (2026-06-05) — **Scheduled jobs actually run now, the cart's discount-code entry renders, and low-stock alerts reach the admin console.** Three shipped features were unreachable in a deployed store because the production composition never connected them. The worker's scheduled ticks and inventory events carry no browser headers, so the bot guard rejected every one of them before the shared-secret check ran — cart recovery, back-in-stock scans, wishlist alerts and digests, abandoned-checkout reaping, and customer-portal expiry never executed on a deployment fronted by the bundled worker. The cart page's discount-code entry and the low-stock alert pipeline were similarly disconnected: each renders or mounts only when the server hands the backing engine to the surface, and the server never did. All three are wired now, and the boot test gains a full-composition pass that fails the build when a gated surface stops reaching the wire. **Added:** *Boot test proves the full composition on the wire* — The integration boot test now boots `server.js` twice: once bare (the container health-check contract, unchanged) and once against an in-memory stand-in for the worker's SQL bridge, which mounts the full catalog + cart + storefront + admin composition exactly as a deployment runs it. The bridged pass adds to cart through the production middleware stack, applies a discount code end to end (the entry renders, the code resolves, the applied chip persists), proves the worker-shaped scheduled tick reaches its handler, and drives a real stock mutation — an admin restock on a SKU under its threshold — into a persisted low-stock alert row without ever touching the intake endpoint directly. A feature gated on a dependency the server forgets to hand over now fails this gate instead of shipping invisible — the failure mode behind all three fixes above. **Fixed:** *Internal scheduled and event endpoints are no longer rejected by the bot guard* — The worker calls the container's internal endpoints (`/_/cart-recovery-tick`, `/_/stock-alert-sweep`, `/_/wishlist-alerts-sweep`, `/_/wishlist-digest-sweep`, `/_/customer-portal-expire`, `/_/stale-order-reap`, `/_/low-stock-alert`) with no browser fingerprint, and the bot guard's missing-header heuristic returned 403 before each handler's constant-time shared-secret check ever ran. Because the worker fires these calls without reading the response, the failures were invisible: on a deployment fronted by the bundled worker, none of these jobs had ever executed — abandoned checkouts kept their stock holds, recovery and wishlist passes never ran, and expired portal grants were never cleaned. These paths now skip the browser-fingerprint heuristics only; every one of them still refuses callers without the shared bridge secret, and `/_/health` keeps its bot-guard coverage unchanged. · *The cart page's discount-code entry renders* — The "Have a discount code?" block and its `POST /cart/coupon` / `POST /cart/coupon/remove` routes mount only when the storefront receives the discount engine, and the server never passed it — so the entry introduced in 0.3.69 was invisible in a deployed store even though checkout already honoured codes submitted through its own field. The engine is now threaded to the storefront: shoppers can apply and remove codes on the cart, and the applied code carries through the same quote-and-confirm path checkout always used. · *Low-stock alerts flow end to end* — Crossing a SKU's low-stock threshold produced no alert, for two independent reasons. The catalog's stock-mutating operations — the checkout hold, a release, a decrement, an admin restock — expose an observer hook for exactly this, and the server never connected it, so the threshold check simply never ran. And the worker-side path (the inventory lock posting the alert to the container) had no `/_/low-stock-alert` endpoint to receive it, so even a directly-posted alert was dropped: no `inventory_alerts` row, no `inventory.low_stock` webhook, and a `/admin/inventory/alerts` screen that never mounted. Both halves are wired now: every stock mutation that leaves a SKU under its configured threshold writes the alert row, fans out the webhook through the shared dispatcher, and emits the warning log line; the intake endpoint exists (secret-gated, like the other internal endpoints); and the admin alert-history screen is reachable. · *Stray editor artifact removed from release-notes/* — A temporary file accidentally committed alongside the 0.3.74 notes is gone from the repository.

package/README.md

@@ -91,6 +91,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/category-navigation.js`** | Hierarchical category tree surfaced as public browse pages. `GET /categories` lists the active top-level categories as a card grid; `GET /categories/:slug` renders one category — its title and optional description, a breadcrumb chain from the catalog root down to the current category, an optional hero image, and a grid of the category's direct child sub-categories. Each page reads fresh against the active tree, so archived / unpublished categories drop out of every surface. Public, no sign-in; an unknown, archived, or malformed slug is a 404 (never a 500), and a category with no children renders a graceful empty state. Linked from the footer on every page. The tree itself (define / move / reorder / archive, with cycle defense bounded by `MAX_TREE_DEPTH`) is operator-managed through the primitive's write API. |
 | **`lib/search-facets.js`** | Filterable search. A search result page renders facet groups — collection, price range, in-stock — as server-rendered controls; selecting one narrows the results and rides the URL query string (`?q=…&collection=…&in_stock=1`), counts beside each option reflect the current result set, facets combine across groups, and active filters show as removable chips with a clear-all path that survives result pagination. All filtering is server-side from the query string (no client JS); unknown facet keys, out-of-range prices, and garbage values are ignored rather than erroring; an empty filtered result shows a clear-filters state. Runs identically at the edge worker and the container — the edge reads the catalog and facet registry straight from D1, missing-table-resilient. |
 | **`lib/search-synonyms.js`** | Typo-tolerant, synonym-aware query matching. Before the catalog is searched, the query is expanded through an operator-curated vocabulary — synonym groups (so "tee" matches "t-shirt"), common typo corrections, and stopword removal — and the page shows a "Showing results for" note when the query was corrected or expanded. A query that still matches nothing falls back to the raw terms so search never silently empties on an unknown word. Shared rewrite instance; runs identically at the edge and the container. |
+| **`lib/search-suggestions.js`** | Search-box autocomplete. As a shopper types, the header search box opens a dropdown (`GET /search/suggestions`, a cacheable JSON endpoint carrying no per-visitor data) with up to three groups: matching products, popular recent searches, and operator-curated featured suggestions pinned to a typed prefix. The dropdown is keyboard-navigable and announces as a combobox; it's a progressive enhancement — JS-off and the pre-load state both fall back to the plain search form. Every search a shopper runs is logged for the admin popular-searches report (the session identifier is hashed before storage; entries past 90 days are pruned automatically). Operators curate the featured rows and read the report from the admin Search suggestions screen; an unsafe link scheme is refused at write time. |
 | **`lib/cookie-consent.js`** | GDPR/ePrivacy cookie consent. Every page carries a banner until the visitor decides — accept all, reject non-essential, or manage categories — with the choice in a sealed first-party cookie and recorded in a consent ledger for the audit trail. Strictly-necessary cookies are always on; analytics/marketing are opt-in and default-deny, and a `DNT`/`Sec-GPC` header forces non-essential to denied regardless of stored opt-in. `POST /consent` sets the choice (safe-redirect back); `GET /cookies` is the preferences page (footer-linked). A server-side gating hook renders a category's script only when granted. Banner + form are server-rendered (work with JS off; the island only hides the banner once decided) and identical at the edge and container. |
 | **`lib/currency-display.js`** | Multi-currency display. Shoppers pick a display currency from the footer switcher (`POST /currency`, sealed cookie, 303 back); product pages, the grid, search, and the cart then show prices converted into it via operator-set FX rates (stored as integer basis points, banker's rounding), formatted per the currency's locale. Conversion is display-only — the cart line and the charged amount stay in the base currency, and a "Prices shown in <display>; you'll be charged in <base>" disclosure appears whenever converting. An optional per-currency rounding rule (composed with `lib/currency-rounding.js`) snaps converted prices to a display increment (e.g. CHF 0.05). Every failure mode — no rate on file, an expired rate, a de-listed currency, a tampered cookie — falls back to base-currency display, never a broken / `NaN` price. Base + enabled list come from `SHOP_BASE_CURRENCY` / `SHOP_CURRENCIES` (or `shop.base_currency` / `shop.currencies` config). Switcher + conversions are server-rendered (work with JS off) and identical at the edge and container. |
 | **`lib/translations.js`** | Storefront localization. The UI chrome (nav, search, newsletter band, footer) renders in the visitor's locale, resolved identically at the edge and container: `?lang=`, then a first-party cookie, then `Accept-Language`, then the operator default. A footer locale switcher (languages shown by their autonyms) persists the choice and 303s back; `GET /locale` sets the cookie. Right-to-left languages set the document `dir`. Strings layer the operator's translation rows over a built-in English baseline — a missing key falls back to English, never a raw placeholder. Enable it by seeding a locale policy (default + supported locales) via `localeRouter`; with none seeded the storefront renders the English baseline and shows no switcher. `SHOP_DEFAULT_LOCALE` sets the edge default and `SHOP_LOCALES` (the supported list) lets the edge forward an `Accept-Language`-preferred non-default locale to the container instead of caching the default; an explicit cookie/`?lang=` choice is always container-served. Server-rendered (works with JS off), byte-identical edge/container. |
@@ -98,7 +99,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/giftcards.js`** | Prepaid bearer gift cards. `issue({ amount_minor, currency })` generates a 16-char code (32-glyph alphabet, no ambiguous letters) via `b.crypto.generateBytes`, stores only its `namespaceHash` digest + a 4-char hint, and returns the plaintext code once. `balance(code)` / `lookup(code)` resolve a code to its live balance (constant-time hash compare); `redeem({ code, order_id, amount_minor })` decrements the balance with an atomic `balance >= amount` SQL guard so concurrent spends can't overdraw. Redeemed at checkout as a credit against the order grand total: the amount due drops by the applied balance (never below zero), the order still records the full total it owed, and the debit is recorded once per order — a card that fully covers the order is marked paid with no Stripe charge. Customers check a balance at `GET /gift-cards`; the page is not a code-existence oracle (unknown / malformed / expired all return the same generic not-found). |
 | **`lib/gift-card-ledger.js`** | Append-only credit / debit / expire history per gift card, with a denormalized `balance_after_minor` snapshot for O(1) balance reads. `credit` / `debit` / `expire` write one row each; `history(id)` paginates a card's transactions; `transactionsForOrder(id)` lists a card's movements for one order. The audit trail behind the admin gift-card ledger console; overdraft is refused at the primitive layer. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, tracks new SKUs, and opens the low-stock alert history (`/admin/inventory/alerts`) — each alert row is written when a checkout decrement crosses a SKU's threshold, alongside an `inventory.low_stock` webhook to subscribed endpoints; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, with a rate-bounded resend of the order confirmation to an operator-supplied address (the buyer's email is stored only as a hash, so the operator types the recipient), and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer, plus a customer-service notes thread per order (internal or customer-visible, pinnable, resolvable); **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); each customer opens to an aggregated activity timeline (orders, loyalty, wishlist, reviews, support) read from the tables those primitives already populate; customer segments export their members as a streamed CSV — id, display name, join date, order count, deliberately no email column; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules — including code-unlocked rules a shopper redeems with a discount code on the cart page — + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. **Errors** (`/admin/errors`) lists captured server-error detail — time, status, route, and a truncated message for scrubbed 500-class failures (checkout confirm, public API, admin actions) — newest-first, with the same path answering a bearer-token request with JSON so the log is one `curl` away. **Carts** (`/admin/carts`) lists abandoned carts — active, has items, idle past a tunable window (24h default) — with line counts, value at risk, and guest/signed-in attribution; a per-cart action mints a single-use, code-gated discount the operator shares through their own channel (recovery email is impossible by design: buyer addresses are stored only as hashes, and the screen says so). **Analytics** (`/admin/analytics`) is the pre-purchase view the sales report can't see — browse-to-buy funnel with conversion rate, top search terms, most-viewed products, units-ranked top SKUs, and a revenue-by-day sparkline — cross-linked with the Reports screen, read-only, every aggregate window- and limit-bounded. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, Carts, and Errors links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, tracks new SKUs, and opens the low-stock alert history (`/admin/inventory/alerts`) — each alert row is written when a checkout decrement crosses a SKU's threshold, alongside an `inventory.low_stock` webhook to subscribed endpoints; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, with a rate-bounded resend of the order confirmation to an operator-supplied address (the buyer's email is stored only as a hash, so the operator types the recipient), and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer, plus a customer-service notes thread per order (internal or customer-visible, pinnable, resolvable); **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); each customer opens to an aggregated activity timeline (orders, loyalty, wishlist, reviews, support) read from the tables those primitives already populate; customer segments export their members as a streamed CSV — id, display name, join date, order count, deliberately no email column; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules — including code-unlocked rules a shopper redeems with a discount code on the cart page — + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. **Errors** (`/admin/errors`) lists captured server-error detail — time, status, route, and a truncated message for scrubbed 500-class failures (checkout confirm, public API, admin actions) — newest-first, with the same path answering a bearer-token request with JSON so the log is one `curl` away. **Carts** (`/admin/carts`) lists abandoned carts — active, has items, idle past a tunable window (24h default) — with line counts, value at risk, and guest/signed-in attribution; a per-cart action mints a single-use, code-gated discount the operator shares through their own channel (recovery email is impossible by design: buyer addresses are stored only as hashes, and the screen says so). **Analytics** (`/admin/analytics`) is the pre-purchase view the sales report can't see — browse-to-buy funnel with conversion rate, top search terms, most-viewed products, units-ranked top SKUs, and a revenue-by-day sparkline — cross-linked with the Reports screen, read-only, every aggregate window- and limit-bounded. **Search suggestions** (`/admin/search-suggestions`) curates the storefront autocomplete — pin a featured link to a typed prefix, set its priority / status / active window, edit or remove it inline — and surfaces a read-only popular-searches report (each term's 30-day count, zero-result share, and last-seen) so an unmatched term flags a stock or naming gap. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, Search suggestions, Carts, and Errors links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 

package/SECURITY.md

@@ -195,6 +195,18 @@ node -e "
   Redemption decrements with an atomic `balance >= amount` SQL guard
   keyed on the order id, so concurrent or replayed checkouts can never
   overdraw a card or apply more than the remaining balance.
+- **The search-query log is privacy-bounded, and curated suggestions
+  can't stage an XSS.** Every storefront search a shopper runs is logged
+  to power the admin popular-searches report, but the visitor's session
+  identifier is hashed (`b.crypto.namespaceHash`) before storage — the
+  log holds no recoverable customer-side identifier — and rows older than
+  90 days are pruned automatically by a self-gated daily sweep. Operator-
+  curated featured suggestions refuse a `javascript:` / `data:` /
+  `vbscript:` link scheme at write time, and both the autocomplete
+  dropdown (built entirely with `textContent`, never `innerHTML`) and the
+  admin report (every echoed query / display field escaped) treat the
+  logged query text as untrusted — a shopper can't smuggle markup into an
+  operator dashboard through the search box.
 - **Abandoned checkouts don't strand stock forever.** Checkout reserves
   stock with an atomic conditional hold before charging; an order whose
   buyer abandons the payment sheet (or whose PaymentIntent expires) would

package/lib/admin.js

@@ -571,6 +571,7 @@ function mount(router, deps) {
   var clickAndCollect = deps.clickAndCollect || null; // pickup-locations CRUD + pickup queue console disabled when absent
   var giftOptions     = deps.giftOptions     || null; // gift-wrap catalog console disabled when absent
   var searchRanking   = deps.searchRanking   || null; // search-ranking weight-set + pin console disabled when absent
+  var searchSuggestions = deps.searchSuggestions || null; // featured-suggestion curation + popular-searches view disabled when absent
   var trustBadges     = deps.trustBadges     || null; // trust-badge authoring console disabled when absent
   var preorder        = deps.preorder        || null; // pre-order campaign console (define/launch/close) disabled when absent
   // Read-only activity log at /admin/audit. Defaults ON — the framework
@@ -592,7 +593,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -6200,6 +6201,112 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- search suggestions ---------------------------------------------
+  // Operator curation for the header autocomplete dropdown: featured
+  // suggestions (typing "free" surfaces "Free shipping over $50") plus a
+  // read-only "Popular searches" view over the 30-day query log. Content-
+  // negotiated like the other console screens — bearer → JSON; signed-in
+  // browser → the HTML table + create form.
+  if (deps.searchSuggestions) {
+    var suggestions = deps.searchSuggestions;
+
+    router.get("/admin/search-suggestions", _pageOrApi(true,
+      R(async function (req, res) {
+        var featured = await _listFeaturedSuggestions(suggestions);
+        var popular = await suggestions.popularQueries({ limit: 50 });
+        _json(res, 200, { featured: featured, popular: popular });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var popular = [];
+        var featured = [];
+        try { popular = await suggestions.popularQueries({ limit: 50 }); }
+        catch (_e) { popular = []; }
+        try { featured = await _listFeaturedSuggestions(suggestions); }
+        catch (_e2) { featured = []; }
+        _sendHtml(res, 200, renderAdminSearchSuggestions({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          featured: featured, popular: popular,
+          created:  url && url.searchParams.get("created"),
+          updated:  url && url.searchParams.get("updated"),
+          deleted:  url && url.searchParams.get("deleted"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the suggestion." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/search-suggestions", _pageOrApi(false,
+      W("search_suggestion.add", async function (req, res) {
+        var row;
+        try { row = await suggestions.addFeatured(req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        try {
+          await suggestions.addFeatured(_featuredSuggestionFromForm(req.body || {}));
+        } catch (e) {
+          var n = _safeNotice(e, "search_suggestion.add");
+          var featured = [];
+          var popular = [];
+          try { featured = await _listFeaturedSuggestions(suggestions); } catch (_e) { featured = []; }
+          try { popular = await suggestions.popularQueries({ limit: 50 }); } catch (_e2) { popular = []; }
+          return _sendHtml(res, n.status, renderAdminSearchSuggestions({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            featured: featured, popular: popular,
+            notice: n.message.replace(/^searchSuggestions[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".search_suggestion.add", outcome: "success" });
+        _redirect(res, "/admin/search-suggestions?created=1");
+      },
+    ));
+
+    router.post("/admin/search-suggestions/:id/edit", _pageOrApi(false,
+      W("search_suggestion.update", async function (req, res) {
+        var row;
+        try { row = await suggestions.updateFeatured(req.params.id, _featuredSuggestionPatchFromForm(req.body || {})); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!row) return _problem(res, 404, "search-suggestion-not-found");
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        try {
+          var row = await suggestions.updateFeatured(id, _featuredSuggestionPatchFromForm(req.body || {}));
+          if (!row) return _redirect(res, "/admin/search-suggestions?err=1");
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          return _redirect(res, "/admin/search-suggestions?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".search_suggestion.update", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/search-suggestions?updated=1");
+      },
+    ));
+
+    router.post("/admin/search-suggestions/:id/delete", _pageOrApi(false,
+      W("search_suggestion.delete", async function (req, res) {
+        var out;
+        try { out = await suggestions.deleteFeatured(req.params.id); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!out.removed) return _problem(res, 404, "search-suggestion-not-found");
+        _json(res, 200, out);
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var out = { removed: false };
+        try { out = await suggestions.deleteFeatured(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!out.removed) return _redirect(res, "/admin/search-suggestions?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".search_suggestion.delete", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/search-suggestions?deleted=1");
+      },
+    ));
+  }
+
   // ---- promo banners --------------------------------------------------
   // Operator-authored marketing banners at six fixed storefront placements.
   // Content-negotiated like the other console screens: bearer → the JSON
@@ -11878,6 +11985,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "blog",         href: "/admin/blog",         label: "Blog",         requires: "blog" },
   { key: "help",         href: "/admin/help",         label: "Help center",  requires: "knowledgeBase" },
   { key: "pages",        href: "/admin/pages",        label: "Pages",        requires: "storefrontPages" },
+  { key: "search-suggestions", href: "/admin/search-suggestions", label: "Search suggestions", requires: "searchSuggestions" },
   { key: "surveys",      href: "/admin/surveys",      label: "Surveys",      requires: "customerSurveys" },
   { key: "hours",        href: "/admin/hours",        label: "Hours",        requires: "businessHours" },
   { key: "giftcards",    href: "/admin/gift-cards",    label: "Gift cards",   requires: "giftcards" },
@@ -16640,6 +16748,56 @@ function _announcementPatchFromForm(body) {
   return patch;
 }
 
+// ---- search-suggestion form coercion --------------------------------
+
+// Read every featured suggestion for the curation table — through the
+// injected instance's listFeatured (the primitive's suggest() is prefix-
+// scoped + active-only; the console needs the full set), so a
+// composition that created the primitive with a custom query handle
+// reads the same rows the write surface (addFeatured / updateFeatured /
+// deleteFeatured) writes.
+function _listFeaturedSuggestions(searchSuggestions) {
+  return searchSuggestions.listFeatured({});
+}
+
+// Coerce the create form into the shape searchSuggestions.addFeatured
+// expects: prefix + display_text + link_url, an optional integer
+// priority, optional epoch schedule bounds, and a status. Blank optional
+// fields drop out so the primitive applies its own defaults (priority 0,
+// starts_at now, status active). The primitive validates the result
+// (control bytes, length caps, refused link schemes, expires>starts) and
+// throws a TypeError on a bad shape, which the browser path degrades to a
+// clean err notice and the bearer path to a 400.
+function _featuredSuggestionFromForm(body) {
+  body = body || {};
+  var out = {
+    prefix:       typeof body.prefix === "string" ? body.prefix.trim() : body.prefix,
+    display_text: typeof body.display_text === "string" ? body.display_text.trim() : body.display_text,
+    link_url:     typeof body.link_url === "string" ? body.link_url.trim() : body.link_url,
+  };
+  if (body.priority != null && String(body.priority).trim() !== "") {
+    out.priority = _strictMinorInt(body.priority, "searchSuggestions.addFeatured", "priority");
+  }
+  var sa = _epochFromForm(body.starts_at);  if (sa != null) out.starts_at = sa;
+  var ea = _epochFromForm(body.expires_at); if (ea != null) out.expires_at = ea;
+  if (body.status != null && body.status !== "") out.status = body.status;
+  return out;
+}
+
+// Coerce the inline edit form into an updateFeatured patch. The console's
+// per-row form only exposes the two cheap-to-flip columns — priority and
+// status — so the patch carries just those; the primitive's whitelist
+// validates each before it touches the row.
+function _featuredSuggestionPatchFromForm(body) {
+  body = body || {};
+  var patch = {};
+  if (body.priority != null && String(body.priority).trim() !== "") {
+    patch.priority = _strictMinorInt(body.priority, "searchSuggestions.updateFeatured", "priority");
+  }
+  if (body.status != null && body.status !== "") patch.status = body.status;
+  return patch;
+}
+
 // ---- search-ranking form coercion -----------------------------------
 
 // `?from`/`?to` ms-epoch query params for the metrics rollup → integer, or a
@@ -16903,6 +17061,104 @@ function renderAdminAnnouncements(opts) {
   return _renderAdminShell(opts.shop_name, "Announcements", bodyHtml, "announcements", opts.nav_available);
 }
 
+// Search-suggestions curation screen: the featured-suggestion table (with
+// a per-row inline priority/status edit + a delete), a create form, and a
+// read-only "Popular searches" view over the recent query log. Every
+// echoed field — prefix, display text, link, query text — is operator- or
+// shopper-authored, so it runs through _htmlEscape on the way out.
+function renderAdminSearchSuggestions(opts) {
+  opts = opts || {};
+  var featured = opts.featured || [];
+  var popular  = opts.popular  || [];
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Suggestion saved.</div>" : "";
+  var updated  = opts.updated  ? "<div class=\"banner banner--ok\">Suggestion updated.</div>" : "";
+  var deleted  = opts.deleted  ? "<div class=\"banner banner--ok\">Suggestion removed.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  function _statusOpts(selected) {
+    return ["active", "draft", "expired"].map(function (s) {
+      return "<option value=\"" + s + "\"" + (s === selected ? " selected" : "") + ">" + s + "</option>";
+    }).join("");
+  }
+
+  function _window(f) {
+    var from = f.starts_at != null ? _datetimeLocalValue(Number(f.starts_at)).replace("T", " ") : "—";
+    var to   = f.expires_at != null ? _datetimeLocalValue(Number(f.expires_at)).replace("T", " ") : "open";
+    return _htmlEscape(from + " → " + to);
+  }
+
+  var featuredRows = featured.map(function (f) {
+    var enc = encodeURIComponent(f.id);
+    var statusClass = f.status === "active" ? "paid" : (f.status === "expired" ? "cancelled" : "");
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(f.prefix) + "</code></td>" +
+      "<td>" + _htmlEscape(f.display_text) + "</td>" +
+      "<td><a href=\"" + _htmlEscape(f.link_url) + "\" rel=\"noopener noreferrer\">" + _htmlEscape(f.link_url) + "</a></td>" +
+      "<td>" + _window(f) + "</td>" +
+      "<td>" +
+        "<form method=\"post\" action=\"/admin/search-suggestions/" + _htmlEscape(enc) + "/edit\" class=\"form-inline\">" +
+          "<input type=\"number\" name=\"priority\" value=\"" + _htmlEscape(String(f.priority)) + "\" min=\"0\" max=\"1000000\" class=\"input-narrow\" aria-label=\"Priority\">" +
+          "<select name=\"status\" aria-label=\"Status\">" + _statusOpts(f.status) + "</select>" +
+          "<button class=\"btn\" type=\"submit\">Save</button>" +
+        "</form>" +
+      "</td>" +
+      "<td><span class=\"status-pill " + statusClass + "\">" + _htmlEscape(f.status) + "</span></td>" +
+      "<td>" +
+        "<form method=\"post\" action=\"/admin/search-suggestions/" + _htmlEscape(enc) + "/delete\" class=\"form-inline\">" +
+          "<button class=\"btn btn--danger\" type=\"submit\">Delete</button>" +
+        "</form>" +
+      "</td>" +
+    "</tr>";
+  }).join("");
+
+  var featuredTable = featured.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr>" +
+        "<th scope=\"col\">Prefix</th><th scope=\"col\">Display text</th><th scope=\"col\">Link</th>" +
+        "<th scope=\"col\">Window</th><th scope=\"col\">Priority / status</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th>" +
+        "</tr></thead><tbody>" + featuredRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No featured suggestions yet. Add one below to surface a curated link as shoppers type.</p>";
+
+  var createForm =
+    "<div class=\"panel mt mw-40\">" +
+      "<h3 class=\"subhead\">Add a featured suggestion</h3>" +
+      "<p class=\"meta\">Pin a curated link to a typed prefix — e.g. prefix &ldquo;free&rdquo; surfaces &ldquo;Free shipping over $50&rdquo;. Higher priority wins when more than one matches. Leave the schedule blank for an always-on suggestion.</p>" +
+      "<form method=\"post\" action=\"/admin/search-suggestions\">" +
+        _setupField("Prefix", "prefix", "", "text", "Lowercased on save. The leading characters a shopper types.", " maxlength=\"100\" required") +
+        _setupField("Display text", "display_text", "", "text", "What the dropdown row reads.", " maxlength=\"200\" required") +
+        _setupField("Link URL", "link_url", "", "text", "Where the row links. https:// or a /-rooted path — javascript:/data: are refused.", " maxlength=\"2048\" required") +
+        _setupField("Priority (optional)", "priority", "", "number", "Higher shows first. Defaults to 0.", " min=\"0\" max=\"1000000\"") +
+        "<label class=\"form-field\"><span>Starts at (optional)</span><input type=\"datetime-local\" name=\"starts_at\"></label>" +
+        "<label class=\"form-field\"><span>Expires at (optional)</span><input type=\"datetime-local\" name=\"expires_at\"></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Add suggestion</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var popularRows = popular.map(function (p) {
+    var share = Math.round((Number(p.zero_result_share) || 0) * 100);
+    var lastSeen = p.last_seen != null ? _datetimeLocalValue(Number(p.last_seen)).replace("T", " ") : "—";
+    return "<tr>" +
+      "<td>" + _htmlEscape(p.query_normalized) + "</td>" +
+      "<td>" + _htmlEscape(String(Number(p.count) || 0)) + "</td>" +
+      "<td>" + _htmlEscape(String(share)) + "%</td>" +
+      "<td>" + _htmlEscape(lastSeen) + "</td>" +
+    "</tr>";
+  }).join("");
+
+  var popularTable = popular.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr>" +
+        "<th scope=\"col\">Query</th><th scope=\"col\">Count</th><th scope=\"col\">Zero-result share</th><th scope=\"col\">Last seen</th>" +
+        "</tr></thead><tbody>" + popularRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No searches logged yet.</p>";
+
+  var bodyHtml = "<section><h2>Search suggestions</h2>" + created + updated + deleted + notice +
+    featuredTable + createForm +
+    "<h3 class=\"subhead mt\">Popular searches (last 30 days)</h3>" +
+    "<p class=\"meta\">What shoppers are typing into the search box. A high zero-result share is a stock or naming gap worth closing.</p>" +
+    popularTable +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, "Search suggestions", bodyHtml, "search-suggestions", opts.nav_available);
+}
+
 // ---- promo-banner form coercion -------------------------------------
 
 var _PROMO_PLACEMENT_LABELS = {

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,13 +1,13 @@
 {
-  "version": "0.4.10",
+  "version": "0.4.12",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",
       "fingerprinted": "css/admin.44eb97700c660798.css"
     },
     "css/main.css": {
-      "integrity": "sha384-fxUZj7xaROivK6yjixSJavibw/WXXmUgjxS4mSG2PXavX/j2GZrsi9uquxvcJjTa",
-      "fingerprinted": "css/main.0117fe12d12ac55b.css"
+      "integrity": "sha384-nRqjlZAYU5a0XVp9OWxcVw3zzZpj6vPcj+5XRf4byAgK49fg8W5QFx8vFLm40ldA",
+      "fingerprinted": "css/main.4eb7c53f87817566.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",
@@ -52,6 +52,10 @@
     "js/saved-card.js": {
       "integrity": "sha384-Kaj6n+Any4rwCH2lyREHoq30MrAZtEd/fTa+tDnIrMJ4zO01YWRhW5TTujcYyuVn",
       "fingerprinted": "js/saved-card.d7fd750d746dbe4d.js"
+    },
+    "js/search-suggest.js": {
+      "integrity": "sha384-Hw1PLzUPkH0rjuz/4wTjrK+jAVqfGAVuTHNPmZcwbqUvJAuFTk7DjbuAFRHyliuc",
+      "fingerprinted": "js/search-suggest.f25cfda1fed825bf.js"
     }
   }
 }

package/lib/search-suggestions.js

@@ -51,6 +51,10 @@
  *     the id didn't exist.
  *   - `deleteFeatured(id)` — operator-only. Returns
  *     `{ removed: boolean }`.
+ *   - `listFeatured({ limit?, offset? })` — operator-only curation
+ *     read: every featured row regardless of status or schedule
+ *     window, priority-then-recency ordered (suggest() is the
+ *     shopper-scoped read; this is the console's).
  *   - `popularQueries({ from?, to?, limit? })` — operator dashboard
  *     aggregate. Returns `[ { query_normalized, count, last_seen,
  *     zero_result_share } ]` sorted by count desc.
@@ -463,6 +467,37 @@ function create(opts) {
       return { removed: Number(r.rowCount || 0) > 0 };
     },
 
+    // The curation-console read: every featured row regardless of status
+    // or schedule window (suggest() answers the shopper and is prefix-
+    // scoped + active-only; an operator managing the set needs the full
+    // list). Ordered the way an operator scans it — priority first, then
+    // most-recently-touched. Reads through the instance's own query
+    // handle, so a composition that injected a custom handle sees the
+    // same rows it writes.
+    listFeatured: async function (listOpts) {
+      listOpts = listOpts || {};
+      // Console-read bounds — wider than the shopper-facing MAX_LIMIT
+      // (the autocomplete answers with 5; an operator pages the full
+      // curated set).
+      var limit  = listOpts.limit  == null ? 500 : listOpts.limit;
+      var offset = listOpts.offset == null ? 0   : listOpts.offset;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > 1000) {
+        throw new TypeError("searchSuggestions.listFeatured: limit must be 1...1000");
+      }
+      if (!Number.isInteger(offset) || offset < 0) {
+        throw new TypeError("searchSuggestions.listFeatured: offset must be a non-negative integer");
+      }
+      var r = await query(
+        "SELECT id, prefix, display_text, link_url, priority, " +
+        "starts_at, expires_at, status, created_at, updated_at " +
+        "FROM featured_search_suggestions " +
+        "ORDER BY priority DESC, updated_at DESC, id DESC " +
+        "LIMIT ?1 OFFSET ?2",
+        [limit, offset],
+      );
+      return r.rows;
+    },
+
     popularQueries: async function (popOpts) {
       popOpts = popOpts || {};
       var now    = Date.now();

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

@@ -305,7 +305,7 @@ var LAYOUT =
   "        <div class=\"site-search__inner\">\n" +
   "          <label for=\"site-search-q\" class=\"skip-link\">{{search_label}}</label>\n" +
   "          <svg class=\"site-search__icon\" viewBox=\"0 0 24 24\" width=\"18\" height=\"18\" aria-hidden=\"true\"><path d=\"M21 21l-4.35-4.35M11 19a8 8 0 1 1 0-16 8 8 0 0 1 0 16Z\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.75\" stroke-linecap=\"round\"/></svg>\n" +
-  "          <input id=\"site-search-q\" type=\"search\" name=\"q\" value=\"{{search_q}}\" placeholder=\"{{search_placeholder}}\" autocomplete=\"off\" spellcheck=\"false\" maxlength=\"200\">\n" +
+  "          <input id=\"site-search-q\" type=\"search\" name=\"q\" value=\"{{search_q}}\" placeholder=\"{{search_placeholder}}\" autocomplete=\"off\" spellcheck=\"false\" maxlength=\"200\" data-suggest=\"/search/suggestions\" role=\"combobox\" aria-expanded=\"false\" aria-autocomplete=\"list\" aria-controls=\"site-search-suggest\">\n" +
   "          <button type=\"submit\">{{search_submit}}</button>\n" +
   "        </div>\n" +
   "      </form>\n" +
@@ -386,6 +386,7 @@ var LAYOUT =
   CONSENT_BANNER +
   "RAW_CONSENT_SCRIPT" +
   "RAW_CART_COUNT_SCRIPT" +
+  "RAW_SEARCH_SUGGEST_SCRIPT" +
   "RAW_ANNOUNCEMENT_SCRIPT" +
   "</body>\n" +
   "</html>\n";
@@ -1041,6 +1042,7 @@ function _wrap(opts) {
     .replace("RAW_HREFLANG", hreflangHtml)
     .replace("RAW_CONSENT_SCRIPT", _islandScript("consent.js", { id: "consent-island", policy: _activeConsentPolicy }))
     .replace("RAW_CART_COUNT_SCRIPT", _islandScript("cart-count.js", { id: "cart-count-island" }))
+    .replace("RAW_SEARCH_SUGGEST_SCRIPT", _islandScript("search-suggest.js", { id: "search-suggest-island" }))
     .replace("RAW_ANNOUNCEMENT_SCRIPT", announcementScript)
     .replace("RAW_CURRENCY_SWITCHER", switcherHtml)
     .replace("RAW_LOCALE_SWITCHER", localeCtx.switcher_html || "");
@@ -1680,6 +1682,16 @@ function _renderSearchChips(facets, filters, q) {
 // exist). Mirrors the edge renderer's SEARCH_PAGE_SIZE.
 var SEARCH_PAGE_SIZE = 24;
 
+// Search-query-log retention + the self-gating sweep cadence. Every
+// /search hit logs a row (drop-silent) for the admin "Popular searches"
+// view; rows older than the retention window are pruned by a sweep that
+// runs at most once a day, gated by a module-level timestamp (the same
+// self-gating shape server.js uses for the stock-alert sweep) so a busy
+// search page doesn't issue a DELETE on every request.
+var SEARCH_QUERY_RETENTION_MS  = b.constants.TIME.days(90);
+var SEARCH_QUERY_CLEANUP_EVERY_MS = b.constants.TIME.days(1);
+var _lastSearchQueryCleanupAt  = 0;
+
 // `/search?...` URL for a specific results page — the query + active
 // filters carried forward (so paging preserves the facet state) with a
 // `page` param appended for any page past the first. Page 1 omits the
@@ -1842,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
@@ -1930,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>";
   }
@@ -10649,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
@@ -12341,15 +12445,106 @@ 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
+    // logging hiccup must never fail the search the shopper just ran. The
+    // session id is the well-shaped sid cookie or "anon" (the primitive
+    // 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 && searchTerm.length > 0) {
+      try {
+        deps.searchSuggestions.recordQuery({
+          q:            searchTerm,
+          session_id:   _readSidCookie(req) || "anon",
+          result_count: totalCount,
+        }).catch(function () { /* drop-silent — logging never fails the search */ });
+      } catch (_e) { /* drop-silent — logging never fails the search */ }
+      var nowMs = Date.now();
+      if (nowMs - _lastSearchQueryCleanupAt >= SEARCH_QUERY_CLEANUP_EVERY_MS) {
+        _lastSearchQueryCleanupAt = nowMs;
+        try {
+          deps.searchSuggestions.cleanupOldQueries(nowMs - SEARCH_QUERY_RETENTION_MS)
+            .catch(function () { /* drop-silent — retention is best-effort */ });
+        } 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)
+  // fetches this as the shopper types. Mounted only when the searchSuggestions
+  // dep is wired; absent it, the island's fetch 404s and the box stays a plain
+  // form (no-JS and dep-off both degrade to a normal /search submit). The
+  // response is public + 30s-cacheable: it carries no per-session data (product
+  // matches, recent popular terms, operator-curated rows — all shared chrome).
+  if (deps.searchSuggestions) {
+    router.get("/search/suggestions", async function (req, res) {
+      function _emit(status, obj) {
+        res.status(status);
+        res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+        // 30s shared cache — the data is identical for every visitor; per-
+        // session chrome (cart count) rides its own no-store endpoint.
+        res.setHeader && res.setHeader("cache-control", "public, max-age=30");
+        var payload = JSON.stringify(obj);
+        return res.end ? res.end(payload) : res.send(payload);
+      }
+      var EMPTY = { products: [], queries: [], featured: [] };
+
+      // Defensive request-shape reader: a missing / non-string / blank /
+      // oversized q is a 200 with the empty shape, never a 4xx the island
+      // has to special-case. Trim + cap at the primitive's max before it
+      // ever reaches the engine.
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var qRaw = url && url.searchParams.get("q");
+      var q = typeof qRaw === "string" ? qRaw.trim() : "";
+      if (q.length > 200) q = q.slice(0, 200);
+      if (!q.length) return _emit(200, EMPTY);
+
+      // Hot path — ANY engine failure returns the empty shape, never a 500.
+      // Drop-silent by design: a suggestions hiccup must degrade to "no
+      // dropdown", never break the page the shopper is typing on.
+      try {
+        var out = await deps.searchSuggestions.suggest({ q: q });
+        return _emit(200, {
+          products: Array.isArray(out && out.products) ? out.products : [],
+          queries:  Array.isArray(out && out.queries)  ? out.queries  : [],
+          featured: Array.isArray(out && out.featured) ? out.featured : [],
+        });
+      } catch (_e) {
+        return _emit(200, EMPTY);
+      }
+    });
+  }
+
   router.get("/products/:slug", async function (req, res) {
     var slug = req.params && req.params.slug;
     if (!slug) return _send(res, 400, renderNotFound({ shop_name: shopName, theme: theme }));
@@ -12521,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.10",
+  "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": {