45 — Two Storefront Widgets (v1 Requirement, Screen 8.1)

45 — Two Storefront Widgets (v1 Requirement, Screen 8.1)

Source: 02-Implementation-Blueprint.md — Screen 8.1 — Two storefront widgets (v1 requirement).

This document is a build spec only. No code changes are implied until a task references this file.

Related: 05 (widget + read API), 11 (published content controls), 44 (per-product binding rule), 21 (route/file map).

---

0) Goal (one sentence)

Deliver two clearly separated storefront experiences in v1: a home widget for top store-wide videos and a PDP widget for product-scoped testimonials only.

---

1) Non-negotiable v1 requirement

Merchants must be able to place and control:

1. Home widget
   • store-wide social proof
   • default top 5 video testimonials
2. PDP widget
   • only testimonials linked to current product
   • explicit fallback behavior when product has no testimonials

This is mandatory and should not be collapsed into vague “single widget” behavior without mode clarity.

---

2) Widget A — Home (Top video reviews)

2.1 Functional contract

• Placement: home/index template
• Data scope: shop-wide published testimonials
• Default filter: mediaType=video
• Default count: limit=5
• Default order: featured first, then newest/sort order (as configured)

2.2 Settings defaults

• homeWidgetEnabled = true
• homeMaxItems = 5
• homeMediaFilter = video_only
• homeRanking = featured_then_newest

2.3 Empty behavior

• Show configured empty-state copy (no random fallback unless explicit future setting).

---

3) Widget B — PDP (Product-only reviews)

3.1 Functional contract

• Placement: product template
• Data scope: shopifyProductId == current product id
• Product binding source: primary submission product id (see 44)

3.2 Settings defaults

• pdpWidgetEnabled = true
• pdpMediaFilter configurable
• pdpMaxItems configurable (default e.g. 12)

3.3 Fallback modes (required)

When no product-specific rows:

• show_global_featured
• show_recent
• hide_widget

Merchant must choose behavior through settings.

---

4) Theme-extension implementation options

Option A (recommended)

Two explicit blocks:

• testimonial-widget-home.liquid
• testimonial-widget-pdp.liquid

Pros:

• clearer merchant mental model
• fewer misconfiguration errors
• easier support docs

Option B

Single block with widget_mode setting.

Pros: fewer files
Cons: more misconfiguration risk.

For v1 clarity, prefer Option A.

---

5) API contract split

Public read endpoint must distinguish placement:

• Home query:
  • placement=home
  • ignores product_id
• PDP query:
  • placement=pdp
  • requires product_id
  • enforces product-only filter before fallback logic

Response contracts should include enough metadata for widget rendering and empty/fallback handling.

---

6) Data integrity and leakage prevention

Critical constraints:

1. PDP route must never show another product’s testimonials unless fallback mode explicitly says so.
2. Home route should not accidentally inherit PDP product filters.
3. Unpublished/unapproved/non-ready media must be excluded in both modes.

Regression tests should specifically cover cross-product leakage.

---

7) Merchant UX requirements

In app admin:

• explain difference between Home and PDP widgets in plain language
• expose separate enable toggles and limits
• provide preview hints for each context

In Theme Editor:

• block labels should be explicit:
  • “Testimonial Widget — Home”
  • “Testimonial Widget — Product”

---

8) Rollout strategy

1. ship both blocks behind feature flag
2. verify on test theme:
   • home renders
   • PDP product scoping works
3. enable progressively for pilot shops
4. monitor fallback usage and error rates

---

9) Acceptance checklist

• Merchant can add both blocks independently in theme editor.
• Home widget shows top configured video set (default 5).
• PDP widget shows only current product rows.
• Each fallback mode behaves exactly as configured.
• Disabling one widget does not affect the other.
• No cross-product data leakage in PDP mode.

---

10) Suggested implementation order (for Cursor)

1. Finalize settings schema for home/pdp separate defaults.
2. Implement read API placement split and predicates.
3. Build two liquid blocks + shared JS.
4. Wire admin settings UI labels and help copy.
5. Add integration tests for home vs PDP behavior.

---

11) References

• 02-Implementation-Blueprint.md — Screen 8.1
• 05-storefront-widgets-and-read-api.md
• 11-published-content-screen-7.md
• 44-per-product-collection-rule-required-blueprint.md
• 21-route-and-file-map-blueprint-section-6.md

---

12) Note on numbering

This folder already includes 05 through 44 plans. This file is 45-....