Add Boost hue-sort runbook (Half A client-side + Half B server-side cov_<hue> metafields)

26d77656f6adeb9e519ce00959f118700133675f · 2026-06-15 12:56:40 -0700 · Steve Abrams
Files touched

A docs/boost-hue-sort-runbook.md
Diff

commit 26d77656f6adeb9e519ce00959f118700133675f
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Mon Jun 15 12:56:40 2026 -0700

    Add Boost hue-sort runbook (Half A client-side + Half B server-side cov_<hue> metafields)
---
 docs/boost-hue-sort-runbook.md | 124 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)

diff --git a/docs/boost-hue-sort-runbook.md b/docs/boost-hue-sort-runbook.md
new file mode 100644
index 0000000..56c9493
--- /dev/null
+++ b/docs/boost-hue-sort-runbook.md
@@ -0,0 +1,124 @@
+# Boost Hue-Sort Runbook — "Solid → Sparse" per color collection
+
+**Goal:** every color collection lists products **most-solid-target-hue first**,
+ramping down to single-dot / no-hue last. Two mechanisms are in play; this runbook
+is the durable, server-side one (Half 2). Dev theme: **NewWall Template [Dev]
+#143739584563**, store `designer-laboratory-sandbox.myshopify.com` (= live
+www.designerwallcoverings.com).
+
+---
+
+## How it works (data layer — already shipped)
+
+Every active product carries hue-coverage metafields computed once from its
+featured image (PIL HSV histogram, $0, no Gemini):
+
+- **`custom.hue_coverage`** — JSON, all 14 hues, e.g. `{"blue":80.5,"red":2.1,...}`.
+  74,604 products. Read by the **client-side** sorter (see Half A below).
+- **`custom.cov_<hue>`** — flat `number_decimal`, one per hue, e.g. `cov_blue = 80.5`.
+  99,847 written across the 7 giant-collection hues. Read by **Boost server-side
+  sort** (Half B below). Boost can only sort by a scalar metafield, not a JSON key —
+  that's why the flat `cov_<hue>` fields exist.
+
+Sort intent everywhere: **higher coverage = earlier**.
+
+---
+
+## Half A — client-side reorder (small/mid collections, ALREADY LIVE on dev theme)
+
+24 collections ≤12k products. Each has an asset `hc-<handle>.js`
+(`window.HC={hue, map:{handle:coverage}}`) + the generic sorter
+`newwall-huesort.js`, gated in `layout/theme.liquid` by a color-handle allow-list.
+The sorter sets each Boost card's CSS `order = 100000 − coverage×100` and re-applies
+on every infinite-scroll append (MutationObserver). Verified 0-inversion on
+`blue-wallcoverings`.
+
+Limitation: it can only reorder the cards **currently loaded in the DOM**, so it's
+ideal for collections a shopper can scroll through, but NOT a true global sort for
+the 12k–33k giants → those use Half B instead.
+
+To re-push Half A assets after editing:
+```bash
+cd /tmp/newwall-theme
+ONLY=(--only layout/theme.liquid --only assets/newwall-huesort.js)
+for f in assets/hc-*.js; do ONLY+=(--only "$f"); done
+shopify theme push --theme 143739584563 \
+  --store designer-laboratory-sandbox.myshopify.com --nodelete "${ONLY[@]}"
+```
+
+---
+
+## Half B — Boost server-side sort (the 10 GIANT collections) — DO THIS IN THE DASHBOARD
+
+Reaches the **entire** collection (works the same on page 1 and page 130). No client
+payload. Requires Boost dashboard login (Boost AI Search & Filter, bc-solutions.net).
+
+### Per collection, once:
+
+1. Boost dashboard → **Filter & Sort → Sorting**.
+2. **Add custom sort** → name it e.g. `Solid → Sparse`.
+3. Rule: **Sort by metafield** → pick the collection's `custom.cov_<hue>` →
+   **High to Low**.
+4. Boost → **Merchandising / Collections** → select the collection →
+   set **Default sort = `Solid → Sparse`**.
+
+### Collection → metafield mapping (the 10 giants)
+
+| Collection handle | Metafield | products tagged |
+|---|---|---|
+| `beige-wallcoverings` | `custom.cov_beige` | 23,599 |
+| `white-wallcovering-collection` | `custom.cov_white` | (white total 21,796) |
+| `white-wallcoverings` | `custom.cov_white` | ″ |
+| `grey-wallcovering` | `custom.cov_gray` | (gray total 14,647) |
+| `gray-wallcoverings` | `custom.cov_gray` | ″ |
+| `brown-wallpaper-collection` | `custom.cov_brown` | 8,151 |
+| `green-wallpaper-collection` | `custom.cov_green` | 10,809 |
+| `yellow-wallpaper-collection` | `custom.cov_yellow` | 10,899 |
+| `blue-wallpaper-collection` | `custom.cov_blue` | (blue total 9,946) |
+| `blue-wallpaper` | `custom.cov_blue` | ″ |
+
+Products without the metafield (image had ~0% of that hue) sort to the tail — correct.
+
+---
+
+## Verify it worked
+
+Open the collection on the live domain under the dev theme:
+```
+https://www.designerwallcoverings.com/collections/<handle>?preview_theme_id=143739584563
+```
+First cards should be the most-saturated/solid in that hue; scrolling deep should
+keep descending (Boost paginates already-sorted, so no client re-sort needed here).
+
+Spot-check a metafield via Admin GraphQL:
+```bash
+TOKEN=$(grep -m1 '^SHOPIFY_ADMIN_TOKEN=' ~/Projects/secrets-manager/.env | cut -d= -f2-)
+curl -s -X POST https://designer-laboratory-sandbox.myshopify.com/admin/api/2024-10/graphql.json \
+  -H "X-Shopify-Access-Token: $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"query":"{product(id:\"gid://shopify/Product/7506089607219\"){title metafield(namespace:\"custom\",key:\"cov_blue\"){value type}}}"}'
+# -> cov_blue = 100.0 (number_decimal)
+```
+
+---
+
+## Optional future: retire the client-side interim entirely
+
+If you want ONE consistent mechanism, write all 14 scalar `cov_<hue>` metafields
+for every color collection (not just the 7 giant hues) and point every color
+collection's Boost default sort at its hue — then `hc-*.js` + `newwall-huesort.js`
+can be dropped from `theme.liquid`. Generators (reusable, idempotent, $0):
+
+- `/tmp/cov_scalar_fanout.py` — writes `custom.cov_<hue>` from `/tmp/hue_computed.jsonl`
+  via Admin GraphQL cursor enumeration (NOT storefront products.json — that HTTP-400s
+  past ~page 100 and can't reach a 33k collection's tail).
+- `/tmp/hue_fanout.py` — recomputes histograms if `/tmp/hue_computed.jsonl` is ever lost.
+
+---
+
+## Standing constraints (don't violate)
+
+- **Dev theme #143739584563 only.** Never publish, never touch the live theme.
+- Metafields are **additive** — never touched product status/title/tags/images or the
+  $4.25 sample variant.
+- PIL only for image analysis (never Gemini — key compromised).
+- Source data: `SHOPIFY_ADMIN_TOKEN` in `~/Projects/secrets-manager/.env`, API 2024-10.
← c1e6e70 Move DWLK-829420 (probe-renamed to Size:Sample) from edge→cl · back to Dw Yolo Loop · Extend hue-sort runbook to all 34 color collections (cov_<hu af6f41a →