climaybe 3.4.8 → 3.6.0

package/README.md

@@ -169,6 +169,7 @@ The CLI writes config into `climaybe.config.json`:
   "default_store": "voldt-staging.myshopify.com",
   "preview_workflows": true,
   "build_workflows": true,
+  "profile_workflows": true,
   "lighthouse_workflows": true,
   "commitlint": true,
   "cursor_skills": true,
@@ -263,6 +264,19 @@ Optional package, enabled via the `climaybe init` prompt (`Enable preview + clea
 | `reusable-cleanup-themes.yml` | workflow_call | `cleanup_mode: by_pr` deletes names ending with `-PR{padded}`; `orphan_pr` deletes `-PR<n>` when PR `n` is not open. Optional `result_artifact_prefix` for matrix fan-in on `pr-close` |
 | `reusable-extract-pr-number.yml` | workflow_call | Extracts padded/unpadded PR number outputs for naming and API-safe usage |
 
+### Optional Liquid performance profiling package
+
+Enabled via `climaybe init` prompt (`Enable Liquid performance profiling workflows?`; default: yes).
+
+Runs on every push to `main` (skipping store-sync and hotfix-backport commits). Creates a shared preview theme, measures TTFB for four core templates (index, collection, product, cart) over 4 iterations each, discards the first (warm-up) run, and reports the average of the last 3 in the GitHub Actions job summary.
+
+Requires `SHOPIFY_STORE_URL` and `SHOPIFY_THEME_ACCESS_TOKEN` secrets. When secrets are missing, the workflow skips gracefully.
+
+| Workflow | Trigger | What it does |
+|----------|---------|-------------|
+| `liquid-performance.yml` | Push to `main` | Gate check for secrets, then calls reusable profiler |
+| `reusable-liquid-profile.yml` | workflow_call | Shares theme, measures TTFB per template × 4 iterations, reports avg of last 3, cleans up theme |
+
 ### Build and Lighthouse workflows
 
 Optional package. `climaybe init` asks two separate questions: **build workflows** (bundle `_scripts` JS + compile Tailwind in CI; default: yes) and, if build is on, **Lighthouse CI** (performance + a11y budget on the `staging` branch; default: yes, stored as `lighthouse_workflows`). Lighthouse runs inside the build pipeline, so it requires build workflows.

package/bin/version.txt

@@ -1 +1 @@
-3.4.8
+3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "climaybe",
-  "version": "3.4.8",
+  "version": "3.6.0",
   "description": "Shopify CLI by Electric Maybe for theme CI/CD workflows, branch orchestration, app setup, and dev tooling",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -5,6 +5,7 @@ import {
   promptStoreLoop,
   promptPreviewWorkflows,
   promptBuildWorkflows,
+  promptProfileWorkflows,
   promptLighthouseWorkflows,
   promptDevKit,
   promptVSCodeDevTasks,
@@ -99,6 +100,9 @@ async function runInitFlow() {
     enableLighthouseWorkflows = await promptLighthouseWorkflows();
   }
 
+  hint('CI that measures Liquid TTFB for core templates on every push to main.');
+  const enableProfileWorkflows = await promptProfileWorkflows();
+
   hint('Local config + ignore defaults for theme work (Theme Check, Prettier, Lighthouse, gitignore).', 'theme-dev-kit');
   const enableDevKit = await promptDevKit();
   let enableVSCodeTasks = false;
@@ -157,6 +161,7 @@ async function runInitFlow() {
     default_store: stores[0].domain,
     preview_workflows: enablePreviewWorkflows,
     build_workflows: enableBuildWorkflows,
+    profile_workflows: enableProfileWorkflows,
     lighthouse_workflows: enableBuildWorkflows ? enableLighthouseWorkflows : undefined,
     build_entrypoints_ready: enableBuildWorkflows ? missingBuildFiles?.length === 0 : undefined,
     dev_kit: enableDevKit,
@@ -213,6 +218,7 @@ async function runInitFlow() {
   scaffoldWorkflows(mode, {
     includePreview: enablePreviewWorkflows,
     includeBuild: enableBuildWorkflows,
+    includeProfile: enableProfileWorkflows,
   });
 
   // 7. Optional commitlint + Husky and the AI ruleset (rules, skills, agents + editor bridges)
@@ -259,6 +265,7 @@ async function runInitFlow() {
   }
   console.log(pc.dim(`  Preview workflows: ${enablePreviewWorkflows ? 'enabled' : 'disabled'}`));
   console.log(pc.dim(`  Build workflows: ${enableBuildWorkflows ? 'enabled' : 'disabled'}`));
+  console.log(pc.dim(`  Profile workflows: ${enableProfileWorkflows ? 'enabled' : 'disabled'}`));
   if (enableBuildWorkflows) {
     console.log(pc.dim(`  Lighthouse CI: ${enableLighthouseWorkflows ? 'enabled' : 'disabled'}`));
   }

package/src/commands/update-workflows.js

@@ -6,6 +6,7 @@ import {
   isCursorSkillsEnabled,
   getAiEditors,
   isPreviewWorkflowsEnabled,
+  isProfileWorkflowsEnabled,
   readConfig,
 } from '../lib/config.js';
 import { scaffoldWorkflows } from '../lib/workflows.js';
@@ -28,6 +29,7 @@ export async function updateCommand() {
   const mode = getMode();
   const includePreview = isPreviewWorkflowsEnabled();
   const includeBuild = isBuildWorkflowsEnabled();
+  const includeProfile = isProfileWorkflowsEnabled();
 
   // Keep theme project files in sync (root files, package.json, .gitignore, VS Code tasks).
   scaffoldThemeDevKit({
@@ -42,7 +44,7 @@ export async function updateCommand() {
     scaffoldAiConfig(process.cwd(), { editors: getAiEditors() });
   }
 
-  scaffoldWorkflows(mode, { includePreview, includeBuild });
+  scaffoldWorkflows(mode, { includePreview, includeBuild, includeProfile });
 
   console.log(pc.bold(pc.green('\n  Project files updated!\n')));
 }

package/src/cursor/rules/00-rule-index.mdc

@@ -13,6 +13,7 @@ When you perform any of the following, **read and apply** the corresponding rule
 - **Accessibility, a11y, focus, WCAG, UI behavior** → `accessibility-rules.mdc`
 - **JavaScript, web components, _scripts/, *.js** → `javascript-standards.mdc`
 - **Tailwind CSS, theme tokens, Liquid/CSS classes, _styles/** → `tailwindcss-rules.mdc`
+- **Store performance, LCP/INP/CLS, head scripts, third-party tags, CSS/JS tiering, images, _head*/_body* snippets** → `performance-guide.mdc`
 - **Liquid syntax and usage** → `liquid.mdc`
 - **Section files (sections/*.liquid)** → `sections.mdc`
 - **Snippets (snippets/*.liquid)** → `snippets.mdc`

package/src/cursor/rules/global-rules-reference.mdc

@@ -52,6 +52,7 @@ These rules are synced from ~/.claude/rules/:
 ### Project-Specific Rules
 These rules are unique to this project:
 - `project-overview.mdc` - Electric Maybe theme overview
+- `performance-guide.mdc` - Store performance architecture (CSS/JS tiering, third-party containment, LCP)
 - `js-refactor-tasks.mdc` - Current refactoring tasks
 
 ## Important Notes

package/src/cursor/rules/performance-guide.mdc

@@ -0,0 +1,436 @@
+---
+description: Store performance architecture for our themes — CSS/JS tiering, third-party containment, images, Section API, and maintenance checklist
+globs:
+  - "_scripts/**"
+  - "_styles/**"
+  - "snippets/_head*.liquid"
+  - "snippets/_body*.liquid"
+  - "layout/theme.liquid"
+  - "snippets/a--image*.liquid"
+alwaysApply: false
+---
+# Store Performance Guide
+
+Reference for how this theme optimizes storefront performance. Read this before adding scripts, third-party tags, CSS, or heavy Liquid to `<head>`.
+
+## Goals & budgets
+
+| Metric | Target | Primary levers |
+|--------|--------|----------------|
+| LCP | < 2.5s | Critical CSS, LCP preloads, font discipline, hero image sizing |
+| INP / TBT | Low main-thread blocking | Deferred JS, idle third-parties, smaller `index.js` |
+| CLS | Stable layout | Explicit image dimensions, `font-display: swap`, reserved space |
+| Third-party cost | Contained | Resource blocker, `content_for_header` sanitization, deferred analytics |
+
+**Source of truth for JS:** `_scripts/` → built to `assets/` via `npm run scripts:build`. Never edit `assets/*.js` directly.
+
+---
+
+## Page load timeline
+
+```
+┌─ HEAD (critical path) ─────────────────────────────────────────────────────┐
+│ 1. _head-resource-blocker     Network + DOM patches (first script)         │
+│ 2. _head-urgent-script        Geoblock / track-my-order redirect           │
+│ 3. _meta-tags, _head-seo      Meta, favicons (low fetchpriority)           │
+│ 4. _product-preload-slider    PDP: up to 5 slider images (portrait)        │
+│ 5. _index-preload-hero        Homepage: mobile LCP hero preload            │
+│ 6. _head-style                Fonts, :root tokens, critical.css, style.css │
+│ 7. _script-variables          window.theme, routes, icons SVG, Klaviyo cfg │
+│ 8. debug-proxy (conditional)  API proxy for preview/dev only               │
+│ 9. index.js [+ page bundles]  Route-specific modules in head             │
+│10. speculationrules           Conservative prerender for internal links     │
+│11. _head-console-filter       Suppresses noisy third-party console (LH)   │
+│12. content_for_header         Shopify apps — sanitized after capture        │
+│13. Post-header cleanup         Removes blocked script/link nodes            │
+└────────────────────────────────────────────────────────────────────────────┘
+┌─ BODY ─────────────────────────────────────────────────────────────────────┐
+│ Main content (sections/snippets)                                           │
+│ _body-script → deferred.js (module, end of body)                           │
+│   → scheduleIdle → deferred-integrations.js (conditional)                  │
+│   → klaviyo-cart-tracking.js, hotjar-deferred.js                           │
+└────────────────────────────────────────────────────────────────────────────┘
+┌─ IDLE / INTERACTION ───────────────────────────────────────────────────────┐
+│ Hotjar (8s idle or first scroll/click/touch/keydown)                       │
+│ Rebuy product view analytics (PDP, 2s idle)                                  │
+│ Variant image prefetch (hover; touch: max 3 after 5s idle)                   │
+│ cart.js injected when cart drawer opens                                    │
+│ electric-section lazy fetch (IntersectionObserver, often 1200px margin)    │
+└────────────────────────────────────────────────────────────────────────────┘
+┌─ window.load ──────────────────────────────────────────────────────────────┐
+│ AddShoppers referral widget (async)                                        │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. CSS tiering
+
+### Critical bundle (render-blocking)
+
+- **Source:** `_styles/critical.css` → `assets/critical.css`
+- **Scope:** Header + homepage hero shell only; narrow `@source` list (~12 Liquid files)
+- **Loaded in:** `snippets/_head-style.liquid` via `stylesheet_tag`
+
+When adding above-the-fold UI to header or index hero, ensure Tailwind classes are covered by critical `@source` paths or accept FOUC until full CSS loads.
+
+### Full stylesheet (non-blocking)
+
+- **Source:** `_styles/main.css` → `assets/style.css`
+- **Pattern:** `media="print" onload="this.media='all'"` + `<noscript>` fallback
+- **Also:** `rel="preload" as="style" fetchpriority="high"` for early discovery
+
+Build: `npm run tailwind:build` or `tailwind:watch` (builds both critical + main).
+
+### Theme tokens
+
+- `_styles/theme-tokens.css` — shared `@theme` imported by both CSS entry points
+- Inline `:root` variables in `_head-style.liquid` for fonts, spacing, buttons
+
+### Disabled / deferred CSS ideas
+
+- `content-visibility: auto` on sections — **commented out** in `_styles/main.css` (evaluate before enabling)
+- Lazysizes CSS — removed; native `loading="lazy"` only
+
+---
+
+## 2. Font strategy
+
+### Self-hosted fonts (no Typekit / Google Fonts on storefront)
+
+| Family | File | Preload? | Usage |
+|--------|------|----------|-------|
+| Grosa Medium | `grosa-medium.woff2` | **Yes** | Above-the-fold body emphasis |
+| Ivy Presto Headline Light | `ivypresto-headline-light.woff2` | **Yes** | Headings (`iheadline`) |
+| Grosa Regular | `grosa-regular.woff2` | No | Body text; loads via `@font-face` |
+
+All use `font-display: swap`.
+
+### Font blocking
+
+`_head-resource-blocker.liquid` + `layout/theme.liquid` sanitization block:
+
+- Adobe Typekit (`use.typekit.net`, `p.typekit.net`)
+- Google Fonts
+- Shopify Font CDN webfonts (`fonts.shopifycdn.com`, Nunito)
+- Klaviyo legacy brand fonts (`kl-custom-fonts`, Shopify Files `.woff`)
+- Rebuy onsite CDN (`cdn.rebuyengine.com`, `/onsite/`) — **API** (`rebuyengine.com/api/*`) still allowed
+
+### Preconnect budget
+
+- `_head-typography.liquid`: `cdn.shopify.com`, `cdn.shopifycloud.com`; dns-prefetch `v.shopify.com`
+- Unused preconnects removed: `fonts.shopifycdn.com`, `shop.app`
+
+---
+
+## 3. JavaScript architecture
+
+### Build system
+
+**File:** `.climaybe/build-scripts.js` (via `npm run scripts:build`)
+
+| Entry (`_scripts/`) | Output (`assets/`) | Loaded |
+|---------------------|-------------------|--------|
+| `main.js` | `index.js` | All pages, `<head>` module |
+| `deferred.js` | `deferred.js` | End of `<body>` |
+| `deferred-integrations.js` | `deferred-integrations.js` | Idle inject when DOM matches |
+| `productpage.js` | `productpage.js` | PDP `<head>` |
+| `product--variant-radios.js` | `product--variant-radios.js` | PDP `<head>` |
+| `debug-proxy.js` | `debug-proxy.js` | Conditional `<head>` |
+
+**Also in head (not in bundler — manual sync risk):**
+
+- `collectionpage.js` ← `_scripts/collectionpage.js`
+- `cart.js` ← `_scripts/cart.js`
+
+**Per-section assets** (loaded with `defer` / `type="module"` from sections): `wishlist-feed.js`, `irl.js`, `reviews-custom.js`, `product--form.js`, `product-model.js`, `loading-banner.js`, etc.
+
+Production build strips JSDoc and `console.*` from bundled output.
+
+### `index.js` (critical bundle)
+
+**Entry:** `_scripts/main.js`
+
+Includes: `core-components.js`, `header.js`, `electric-section.js`, `electric-slider.js`, `electric-search.js`, `cart-dynamic.js`, `electric-cart-upsell-tabs.js`, pagination, checkout spinner delegation.
+
+**Keep lean.** New features belong in `deferred.js`, page bundles, or lazy-loaded section scripts unless needed for first paint.
+
+### `deferred.js` (body bundle)
+
+**Entry:** `_scripts/deferred.js`
+
+Always loads: product card scripts, quick ATC modal, Klaviyo cart tracking, Hotjar deferred, chat button visibility.
+
+**Conditionally loads** `deferred-integrations.js` when DOM contains:
+`electric-wish`, `electric-wish-counter`, `promo-banner`, `electric-rebuy-simplify`, `footer-newsletter`, `[data-gorgias-widget]`, `.js-promo-banner-text`
+
+Uses `scheduleIdle(..., { timeout: 3000 })` from `_scripts/utils/perf.js`.
+
+### `productpage.js` (PDP bundle)
+
+Includes: gallery, video player, variant preview, variant prefetch, Rebuy product view, gift card sync.
+
+### Idle scheduling utility
+
+**Canonical:** `_scripts/utils/perf.js` → `scheduleIdle(callback, { timeout })`
+
+Falls back to `setTimeout(1)` when `requestIdleCallback` unavailable.
+
+**Consumers:** `deferred.js`, `hotjar-deferred.js`, `rebuy-product-view.js`, `product-variant-prefetch.js`, `recently-viewed.js`
+
+---
+
+## 4. Third-party containment
+
+### Layer 1: Resource blocker (runtime)
+
+`snippets/_head-resource-blocker.liquid` — **must stay first in `<head>`**
+
+Patches: `fetch`, `XHR`, `createElement`, `setAttribute`, DOM insertion, inline style mutation, `MutationObserver` for late injections.
+
+### Layer 2: Header sanitization (Liquid)
+
+`layout/theme.liquid` captures `content_for_header`, replaces blocked host strings with `blocked.invalid/*`, then runs a cleanup script.
+
+### Layer 3: Deferred / conditional loading
+
+| Service | File | Strategy |
+|---------|------|----------|
+| Hotjar | `_scripts/hotjar-deferred.js` | Idle 8s or first user interaction |
+| Klaviyo cart events | `_scripts/klaviyo-cart-tracking.js` | `deferred.js`; listens `cart:added` |
+| Rebuy analytics (PDP view) | `_scripts/rebuy-product-view.js` | Idle 2s on product pages |
+| Rebuy recommendations | `_scripts/electric-rebuy-simplify.js` | Integrations bundle; IO `rootMargin: 1200px` |
+| AddShoppers | `_head-script.liquid` | `window.load`, async, `loadCss: false` |
+| Affirm | `affirm-messaging` web component | Lazy on first product form |
+| Kimonix | `_body-script.liquid` | Async only if `kimonix_void_script` in header |
+| Gorgias | App embed + `gorgias-widget.js` | App via Shopify; triggers deferred |
+
+### Layer 4: Console filter (Lighthouse only)
+
+`_head-console-filter.liquid` — suppresses known third-party `console.error/warn` patterns. **Do not rely on this for debugging** — disable mentally when investigating app bugs.
+
+### Shopify app embeds (`config/settings_data.json`)
+
+| App | Status | Notes |
+|-----|--------|-------|
+| Elevar (GTM/dataLayer) | Enabled | Primary tag orchestration — audit in GTM, not theme |
+| Klaviyo onsite embed | Enabled | Fonts may be blocked; onsite JS from Shopify |
+| Gorgias | Enabled | Chat |
+| Photolock | Enabled | Image protection |
+| Okendo, Checkout Blocks | Disabled | — |
+
+### Inactive / dead integrations
+
+| File | Status |
+|------|--------|
+| `snippets/_script-blocker.liquid` | Fully commented out |
+| `snippets/_head-rebuy-stylesheet-blocker.liquid` | Not rendered |
+| `snippets/_head-csp.liquid` | Not rendered |
+| `snippets/_criteo-tracking.liquid` | Not rendered |
+| `snippets/shoplift.liquid` | Commented out in `theme.liquid` |
+| instant.page | Removed; `data-instant-allow-query-string` on body is legacy |
+
+---
+
+## 5. Images & LCP
+
+### Snippets
+
+| Snippet | Behavior |
+|---------|----------|
+| `a--image.liquid` | Responsive `srcset`; LCP: `fetchpriority="high"`, `loading="eager"`, `decoding="async"`; else `loading="lazy"`; auto-lazy after 2nd section/item |
+| `a--image-responsive.liquid` | `<picture>` breakpoints; LCP path avoids desktop 2x retina |
+
+### Preloads
+
+| Snippet | When | What |
+|---------|------|------|
+| `_index-preload-hero.liquid` | `request.page_type == 'index'` | Mobile 420w hero from `settings.homepage_lcp_image` |
+| `_product-preload-slider-images.liquid` | PDP | Up to 5 portrait slider images, `imagesrcset` 480/960 |
+| `_head-seo.liquid` | All | Favicons `fetchpriority="low"` |
+
+### No lazysizes
+
+Theme uses **native `loading="lazy"`** only. `unveilLazyloadIn()` in `core-components.js` is a no-op kept for API compatibility.
+
+### Variant image prefetch (PDP)
+
+`_scripts/product-variant-prefetch.js`:
+
+- **Desktop:** hover/focus → fetch `?section_id=api--product-images&variant={id}` → preload image URLs from JSON payload
+- **Touch:** after 5s idle, max **3** variants, images section only (no `product--main` fetch)
+
+---
+
+## 6. Navigation & prefetch
+
+### Speculation Rules (native prerender)
+
+`snippets/_head-script.liquid` — `eagerness: "conservative"`
+
+Prerenders same-origin links except account, cart, login. Do not add instant.page alongside this.
+
+### electric-section (Section Rendering API)
+
+`_scripts/electric-section.js`:
+
+- Lazy load via `IntersectionObserver` (`data-onload`, configurable `data-onload-root-margin`)
+- Fragment cache (max 10 entries)
+- Events: `electric-section:prefetch`, `electric-section:fetch`
+- Used for collection tabs, IRL, more-to-love, header fragments, etc.
+
+### electric-pub (tab prefetch)
+
+`_scripts/electric-pub.js` — prefetches tab content on hover/focus or intersection.
+
+### Cart script on demand
+
+`core-components.js` → `loadCartScriptOnce()` injects `cart.js` with `defer` when cart drawer opens (not on every page upfront).
+
+---
+
+## 7. Shopify-specific patterns
+
+### Route-conditional head scripts
+
+From `_head-script.liquid`:
+
+```liquid
+index.js                          → all pages
+productpage.js                    → product
+product--variant-radios.js          → product
+collectionpage.js                   → collection, search
+cart.js                             → cart template
+```
+
+### Geoblock
+
+When `settings.geoblock_enabled`:
+
+- `html.geoblock-pending` hides body until `/browsing_context_suggestions.json` returns
+- Currently **disabled** in `settings_data.json`
+- **Caveat:** fetch failure only warns — body can stay hidden if enabled without a fallback
+
+### Fabric cart restoration
+
+Inline in `_head-script.liquid` — cart/product template logic for `_fabric` localStorage flow.
+
+### Debug API proxy
+
+`_scripts/debug-proxy.js` — loads only when debug cookie, `?debug_proxy*`, or Shopify design mode. Rewrites proxy API fetch URLs.
+
+---
+
+## 8. Klaviyo & analytics data flow
+
+### Cart tracking (deferred)
+
+1. `product--form.js` dispatches `cart:added` with cart payload
+2. `klaviyo-cart-tracking.js` waits for `_learnq`, pushes `Added to Cart v3` + legacy `Added to Cart`
+3. Product page context from `window.theme.klaviyoCart` in `_script-variables.liquid`
+4. Cart page replays `cart:added` from `sessionStorage cart:justAdded`
+
+### Viewed Product (not deferred)
+
+`sections/product--icons-model.liquid` — large inline Klaviyo script when comparison section renders. **Candidate for future deferral.**
+
+### Rebuy
+
+- Widget CDN blocked; custom `electric-rebuy-simplify` uses API
+- Product view POST deferred via `rebuy-product-view.js`
+- Global helpers in `_script-variables.liquid` (`rebuyTrackEvent`, session storage for added variants)
+
+---
+
+## 9. Adding new features — checklist
+
+### New JavaScript
+
+- [ ] Default to `_scripts/` source file, not `assets/`
+- [ ] If needed on every page → consider `deferred.js` not `main.js`
+- [ ] If third-party → defer (idle/interaction/load), never sync in head unless unavoidable
+- [ ] If PDP-only → `productpage.js` or section `{% javascript %}`
+- [ ] Add to `.climaybe/build-scripts.js` if new bundle entry
+- [ ] Run `npm run scripts:build`
+- [ ] Use `scheduleIdle` from `utils/perf.js` for non-critical init
+- [ ] AbortController + cleanup in web components
+
+### New third-party script
+
+- [ ] Can it go through GTM with consent + idle trigger instead of theme?
+- [ ] If app embed: expect `content_for_header` injection — add to blocker list if it conflicts (fonts, duplicate widgets)
+- [ ] Add domain to `_head-console-filter` only if noise is unavoidable
+- [ ] Never add sync analytics in `_head-script.liquid`
+
+### New above-the-fold UI
+
+- [ ] Extend `critical.css` `@source` if new classes needed at first paint
+- [ ] LCP image: use `fetchpriority="high"`, explicit dimensions, preload in dedicated snippet
+- [ ] Do not preload more than 2 fonts
+
+### New section below fold
+
+- [ ] `loading="lazy"` on images
+- [ ] Consider `<electric-section data-onload>` instead of bundling in `index.js`
+- [ ] Pass `lazyload: true` to product cards
+
+---
+
+## 10. Testing & measurement
+
+### Before shipping perf changes
+
+1. **Chrome DevTools** — Performance trace: LCP element, long tasks, third-party cost
+2. **Network** — throttle Slow 4G; verify critical.css → first paint, style.css non-blocking
+3. **Coverage** — how much of `index.js` executes on homepage vs PDP
+4. **Block third-parties test** — block `googletagmanager.com`, `static.klaviyo.com`, `static.hotjar.com`; if TBT collapses, marketing stack is the bottleneck
+5. **Theme Check** — `npm run lint:liquid`
+6. **Build** — `npm run scripts:build && npm run tailwind:build`
+
+### Debug modes
+
+| URL param | Effect |
+|-----------|--------|
+| `?debug_typekit=1` | Typekit audit (`_head-typekit-debug`) |
+| `?debug_rebuy=1` | Rebuy logging |
+| `?debug_proxy=1` | API proxy prompt |
+| `?debug_proxy_domain=` | Set proxy origin |
+
+---
+
+## 11. Known gaps & maintenance risks
+
+1. **`collectionpage.js` / `cart.js` not in build targets** — `_scripts` edits may not reach `assets/` until manual copy or build update
+2. **Many section scripts outside bundler** — verify `assets/` sync when editing `_scripts/wishlist-feed.js`, etc.
+3. **Stale LiquidDoc** in `_head-script.liquid`, `_head-urgent-script.liquid` — docs mention Rebuy head prefetch, instant.page, promo anti-flash that moved or were removed
+4. **`index.js` size (~340KB+)** — largest theme-controlled bottleneck; split `core-components.js` further if TBT regresses
+5. **GTM / Elevar** — largest real-world cost; theme cannot fix container bloat
+6. **`_head-console-filter`** — masks errors; misleading during app debugging
+7. **Klaviyo Viewed Product inline** — still heavy on PDP with icons model section
+
+---
+
+## 12. File quick reference
+
+| Concern | Primary files |
+|---------|---------------|
+| Load order | `layout/theme.liquid` |
+| Resource blocking | `snippets/_head-resource-blocker.liquid` |
+| CSS tiering | `snippets/_head-style.liquid`, `_styles/critical.css`, `_styles/main.css` |
+| JS bootstrap | `snippets/_head-script.liquid`, `snippets/_body-script.liquid` |
+| Globals | `snippets/_script-variables.liquid` |
+| Build | `.climaybe/build-scripts.js`, `package.json` |
+| Idle utils | `_scripts/utils/perf.js` |
+| Images | `snippets/a--image.liquid`, `snippets/a--image-responsive.liquid` |
+| LCP preloads | `snippets/_index-preload-hero.liquid`, `snippets/_product-preload-slider-images.liquid` |
+| Section lazy load | `_scripts/electric-section.js` |
+| Deferred 3P | `_scripts/hotjar-deferred.js`, `_scripts/klaviyo-cart-tracking.js`, `_scripts/rebuy-product-view.js` |
+| App embeds | `config/settings_data.json` |
+
+---
+
+## 13. Related rules
+
+- `javascript-standards.mdc` — web components, layout thrashing, `scheduleIdle` patterns
+- `tailwindcss-rules.mdc` — static classes, `@source` for critical CSS
+- `project-overview.mdc` — performance targets (< 16ms init, 60fps), build outputs vs source (`_scripts/` / `_styles/`, never `assets/` directly)

package/src/lib/config.js

@@ -260,6 +260,14 @@ export function isCommitlintEnabled(cwd = process.cwd()) {
   return config?.commitlint === true;
 }
 
+/**
+ * Whether optional Liquid performance profile workflows are enabled.
+ */
+export function isProfileWorkflowsEnabled(cwd = process.cwd()) {
+  const config = readConfig(cwd);
+  return config?.profile_workflows === true;
+}
+
 /**
  * Whether the bundled AI ruleset (rules, skills, subagents) was installed (init or add-cursor).
  */

package/src/lib/prompts.js

@@ -149,6 +149,20 @@ export async function promptBuildWorkflows() {
   return !!enableBuildWorkflows;
 }
 
+/**
+ * Ask whether Liquid performance profile workflows should be scaffolded.
+ */
+export async function promptProfileWorkflows() {
+  const { enableProfileWorkflows } = await prompts({
+    type: 'confirm',
+    name: 'enableProfileWorkflows',
+    message: 'Enable Liquid performance profiling workflows? (TTFB measurement on main)',
+    initial: true,
+  });
+
+  return !!enableProfileWorkflows;
+}
+
 /**
  * Ask whether Lighthouse CI should run as part of the build pipeline.
  * Only meaningful when build workflows are enabled (Lighthouse runs after the build).

package/src/lib/workflows.js

@@ -37,7 +37,7 @@ function copyWorkflow(srcDir, fileName, destDir) {
  * but for simplicity we track known filenames instead.
  */
 function getKnownWorkflowFiles() {
-  const dirs = ['shared', 'single', 'multi', 'preview', 'build'];
+  const dirs = ['shared', 'single', 'multi', 'preview', 'build', 'profile'];
   const files = new Set();
   for (const dir of dirs) {
     const dirPath = join(TEMPLATES_DIR, dir);
@@ -72,7 +72,7 @@ function cleanWorkflows(cwd = process.cwd()) {
  * - Copies single/ or multi/ (+ single/) based on mode.
  */
 export function scaffoldWorkflows(mode = 'single', options = {}, cwd = process.cwd()) {
-  const { includePreview = false, includeBuild = false } = options;
+  const { includePreview = false, includeBuild = false, includeProfile = false } = options;
   const dest = ghWorkflowsDir(cwd);
   mkdirSync(dest, { recursive: true });
 
@@ -113,9 +113,17 @@ export function scaffoldWorkflows(mode = 'single', options = {}, cwd = process.c
     ensureBuildWorkflowDefaults(cwd);
   }
 
+  if (includeProfile) {
+    const profileDir = join(TEMPLATES_DIR, 'profile');
+    for (const f of listYmls(profileDir)) {
+      copyWorkflow(profileDir, f, dest);
+    }
+  }
+
   const total = readdirSync(dest).filter((f) => f.endsWith('.yml')).length;
   console.log(pc.green(`  Scaffolded ${total} workflow(s) → .github/workflows/`));
   console.log(pc.dim(`  Mode: ${mode}-store`));
   console.log(pc.dim(`  Preview workflows: ${includePreview ? 'enabled' : 'disabled'}`));
   console.log(pc.dim(`  Build workflows: ${includeBuild ? 'enabled' : 'disabled'}`));
+  console.log(pc.dim(`  Profile workflows: ${includeProfile ? 'enabled' : 'disabled'}`));
 }

package/src/workflows/profile/liquid-performance.yml

@@ -0,0 +1,47 @@
+# climaybe — Liquid Performance (Optional Profile Package)
+# Profiles Liquid rendering performance (TTFB) for core templates on main.
+# Pushes a shared theme, measures TTFB for index/collection/product/cart,
+# runs 4 iterations per template, reports the average of the last 3 runs.
+
+name: Liquid Performance
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  profile-gate:
+    runs-on: ubuntu-latest
+    if: >
+      !contains(github.event.head_commit.message, '[hotfix-backport]')
+      && !contains(github.event.head_commit.message, '[stores-to-root]')
+      && !contains(github.event.head_commit.message, '[root-to-stores]')
+    outputs:
+      run_profile: ${{ steps.check.outputs.run_profile }}
+    env:
+      SHOPIFY_STORE_URL: ${{ secrets.SHOPIFY_STORE_URL }}
+      SHOPIFY_THEME_ACCESS_TOKEN: ${{ secrets.SHOPIFY_THEME_ACCESS_TOKEN }}
+    steps:
+      - name: Check if profiling should run
+        id: check
+        run: |
+          SKIP_REASONS=()
+          if [ -z "$SHOPIFY_STORE_URL" ]; then
+            SKIP_REASONS+=("Missing secret: SHOPIFY_STORE_URL")
+          fi
+          if [ -z "$SHOPIFY_THEME_ACCESS_TOKEN" ]; then
+            SKIP_REASONS+=("Missing secret: SHOPIFY_THEME_ACCESS_TOKEN")
+          fi
+          if [ ${#SKIP_REASONS[@]} -gt 0 ]; then
+            echo "run_profile=false" >> $GITHUB_OUTPUT
+            echo "Liquid profiling skipped:"
+            for reason in "${SKIP_REASONS[@]}"; do echo "  - $reason"; done
+          else
+            echo "run_profile=true" >> $GITHUB_OUTPUT
+          fi
+
+  liquid-profile:
+    needs: [profile-gate]
+    if: needs.profile-gate.outputs.run_profile == 'true'
+    uses: ./.github/workflows/reusable-liquid-profile.yml
+    secrets: inherit

package/src/workflows/profile/reusable-liquid-profile.yml

@@ -0,0 +1,199 @@
+name: Reusable Liquid Profile
+
+on:
+  workflow_call:
+    inputs:
+      iterations:
+        required: false
+        type: number
+        default: 4
+        description: "Total profiling iterations per template (first is discarded as warm-up)"
+      store_alias_secret:
+        required: false
+        type: string
+        description: "Upper snake-case alias for scoped secret (e.g. VOLDT_STAGING). If set, uses SHOPIFY_*_<this>; else uses SHOPIFY_STORE_URL / SHOPIFY_THEME_ACCESS_TOKEN."
+
+jobs:
+  profile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Validate theme root
+        run: |
+          if [ ! -f "layout/theme.liquid" ]; then
+            echo "layout/theme.liquid not found. Ensure workflow runs at theme repository root."
+            exit 1
+          fi
+
+      - name: Install Shopify CLI
+        run: npm install -g @shopify/cli @shopify/theme
+
+      - name: Share preview theme
+        id: share
+        env:
+          SHOPIFY_STORE_URL: ${{ inputs.store_alias_secret && secrets[format('SHOPIFY_STORE_URL_{0}', inputs.store_alias_secret)] || secrets.SHOPIFY_STORE_URL }}
+          SHOPIFY_THEME_ACCESS_TOKEN: ${{ inputs.store_alias_secret && secrets[format('SHOPIFY_THEME_ACCESS_TOKEN_{0}', inputs.store_alias_secret)] || secrets.SHOPIFY_THEME_ACCESS_TOKEN }}
+        run: |
+          if [ -z "$SHOPIFY_STORE_URL" ] || [ -z "$SHOPIFY_THEME_ACCESS_TOKEN" ]; then
+            echo "Missing Shopify secrets."
+            exit 1
+          fi
+
+          OUTPUT=$(shopify theme share \
+            --store "$SHOPIFY_STORE_URL" \
+            --password "$SHOPIFY_THEME_ACCESS_TOKEN" 2>&1)
+          STATUS=$?
+
+          echo "$OUTPUT"
+          if [ $STATUS -ne 0 ]; then
+            echo "Theme share failed."
+            exit $STATUS
+          fi
+
+          THEME_ID=$(echo "$OUTPUT" | sed -n 's/.*#\([0-9]*\).*/\1/p' | head -1)
+          if [ -z "$THEME_ID" ]; then
+            echo "Could not parse theme id from share output."
+            exit 1
+          fi
+
+          echo "theme_id=$THEME_ID" >> $GITHUB_OUTPUT
+          echo "Shared theme ID: $THEME_ID"
+
+      - name: Resolve profiling URLs
+        id: urls
+        run: |
+          URLS_JSON='[
+            {"template": "index",      "path": "/"},
+            {"template": "collection", "path": "/collections"},
+            {"template": "product",    "path": "/products"},
+            {"template": "cart",       "path": "/cart"}
+          ]'
+          echo "urls=$URLS_JSON" >> $GITHUB_OUTPUT
+
+      - name: Profile Liquid performance
+        id: profile
+        env:
+          SHOPIFY_STORE_URL: ${{ inputs.store_alias_secret && secrets[format('SHOPIFY_STORE_URL_{0}', inputs.store_alias_secret)] || secrets.SHOPIFY_STORE_URL }}
+          SHOPIFY_CLI_THEME_TOKEN: ${{ inputs.store_alias_secret && secrets[format('SHOPIFY_THEME_ACCESS_TOKEN_{0}', inputs.store_alias_secret)] || secrets.SHOPIFY_THEME_ACCESS_TOKEN }}
+          THEME_ID: ${{ steps.share.outputs.theme_id }}
+          ITERATIONS: ${{ inputs.iterations }}
+        run: |
+          STORE=$(echo "$SHOPIFY_STORE_URL" | sed 's|^https\?://||; s|/.*||')
+          REPORT_FILE="liquid-profile-report.md"
+          RESULTS_JSON="[]"
+
+          TEMPLATES=("index" "collection" "product" "cart")
+          PATHS=("/" "/collections" "/products" "/cart")
+
+          echo "## Liquid Performance Report" > "$REPORT_FILE"
+          echo "" >> "$REPORT_FILE"
+          echo "| Template | Avg TTFB (last 3) | Run 1 (warm-up) | Run 2 | Run 3 | Run 4 |" >> "$REPORT_FILE"
+          echo "|----------|-------------------|-----------------|-------|-------|-------|" >> "$REPORT_FILE"
+
+          HAS_ERROR=false
+
+          for i in "${!TEMPLATES[@]}"; do
+            TEMPLATE="${TEMPLATES[$i]}"
+            URL_PATH="${PATHS[$i]}"
+            echo ""
+            echo "=== Profiling $TEMPLATE ($URL_PATH) ==="
+
+            TIMES=()
+            ALL_TIMES_DISPLAY=()
+
+            for ((iter=1; iter<=ITERATIONS; iter++)); do
+              echo "  Iteration $iter/$ITERATIONS for $TEMPLATE..."
+
+              START_MS=$(date +%s%N)
+              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+                --connect-timeout 30 \
+                --max-time 60 \
+                "https://${STORE}${URL_PATH}?preview_theme_id=${THEME_ID}" \
+                -H "Accept: text/html") || true
+              END_MS=$(date +%s%N)
+
+              TTFB_MS=$(( (END_MS - START_MS) / 1000000 ))
+              echo "    HTTP $HTTP_CODE — TTFB: ${TTFB_MS}ms"
+
+              TIMES+=("$TTFB_MS")
+              ALL_TIMES_DISPLAY+=("${TTFB_MS}ms")
+
+              if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "301" ] && [ "$HTTP_CODE" != "302" ]; then
+                echo "    Warning: unexpected HTTP status $HTTP_CODE"
+              fi
+
+              sleep 2
+            done
+
+            WARMUP="${ALL_TIMES_DISPLAY[0]}"
+
+            if [ ${#TIMES[@]} -ge 4 ]; then
+              SUM=0
+              COUNT=0
+              for ((j=1; j<${#TIMES[@]}; j++)); do
+                SUM=$((SUM + TIMES[j]))
+                COUNT=$((COUNT + 1))
+              done
+              AVG=$((SUM / COUNT))
+            else
+              SUM=0
+              for t in "${TIMES[@]}"; do
+                SUM=$((SUM + t))
+              done
+              AVG=$((SUM / ${#TIMES[@]}))
+            fi
+
+            RUN2="${ALL_TIMES_DISPLAY[1]:-n/a}"
+            RUN3="${ALL_TIMES_DISPLAY[2]:-n/a}"
+            RUN4="${ALL_TIMES_DISPLAY[3]:-n/a}"
+
+            echo "| \`$TEMPLATE\` | **${AVG}ms** | $WARMUP | $RUN2 | $RUN3 | $RUN4 |" >> "$REPORT_FILE"
+
+            RESULTS_JSON=$(echo "$RESULTS_JSON" | jq --arg t "$TEMPLATE" --argjson avg "$AVG" \
+              --argjson times "$(printf '%s\n' "${TIMES[@]}" | jq -s '.')" \
+              '. + [{"template": $t, "avg_ms": $avg, "times_ms": $times}]')
+
+            echo "  → $TEMPLATE average (last 3): ${AVG}ms"
+          done
+
+          echo "" >> "$REPORT_FILE"
+          echo "_${ITERATIONS} iterations per template; average excludes the first (warm-up) run._" >> "$REPORT_FILE"
+          echo "_Theme ID: ${THEME_ID} | Store: ${STORE}_" >> "$REPORT_FILE"
+
+          echo ""
+          echo "=== Report ==="
+          cat "$REPORT_FILE"
+
+          {
+            echo "report<<REPORT_EOF"
+            cat "$REPORT_FILE"
+            echo "REPORT_EOF"
+          } >> $GITHUB_OUTPUT
+
+          echo "results_json=$(echo "$RESULTS_JSON" | jq -c '.')" >> $GITHUB_OUTPUT
+
+      - name: Post results as job summary
+        env:
+          REPORT: ${{ steps.profile.outputs.report }}
+        run: |
+          echo "$REPORT" >> $GITHUB_STEP_SUMMARY
+
+      - name: Cleanup preview theme
+        if: always()
+        env:
+          SHOPIFY_STORE_URL: ${{ inputs.store_alias_secret && secrets[format('SHOPIFY_STORE_URL_{0}', inputs.store_alias_secret)] || secrets.SHOPIFY_STORE_URL }}
+          SHOPIFY_THEME_ACCESS_TOKEN: ${{ inputs.store_alias_secret && secrets[format('SHOPIFY_THEME_ACCESS_TOKEN_{0}', inputs.store_alias_secret)] || secrets.SHOPIFY_THEME_ACCESS_TOKEN }}
+          THEME_ID: ${{ steps.share.outputs.theme_id }}
+        run: |
+          if [ -z "$THEME_ID" ]; then
+            echo "No theme ID to clean up."
+            exit 0
+          fi
+
+          echo "Deleting preview theme $THEME_ID..."
+          shopify theme delete --theme "$THEME_ID" \
+            --store "$SHOPIFY_STORE_URL" \
+            --password "$SHOPIFY_THEME_ACCESS_TOKEN" \
+            --force 2>&1 || echo "Theme cleanup failed (non-fatal)."