Core rollout: PDP, Cart/Drawer, PLP, Search (#4)

## Summary
- complete PDP phase with robust variant state sync
(URL/form/media/price) and add-to-cart UX states
- implement global cart drawer with keyboard accessibility,
quantity/remove async flows, empty/error handling, and cart page async
updates
- add collection sort/filter behavior and progressive load-more; add
predictive search with graceful fallback to full search
- align CI/docs/workflow: branch strategy checks, smoke script, baseline
performance notes, and updated README/CLAUDE/TODO

Author: LucaArgentieri

.github/workflows/ci.yml

@@ -5,6 +5,28 @@ on:
   pull_request:
 
 jobs:
+  branch-strategy:
+    name: Branch Strategy Check
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR source and target branches
+        run: |
+          BASE="${{ github.base_ref }}"
+          HEAD="${{ github.head_ref }}"
+
+          if [ "$BASE" = "staging" ] && [[ ! "$HEAD" =~ ^feat/ ]]; then
+            echo "PRs to staging must come from feat/* branches. Got: $HEAD"
+            exit 1
+          fi
+
+          if [ "$BASE" = "main" ] && [ "$HEAD" != "staging" ]; then
+            echo "PRs to main must come from staging. Got: $HEAD"
+            exit 1
+          fi
+
+          echo "Branch strategy check passed for $HEAD -> $BASE"
+
   quality:
     name: Typecheck and Build
     runs-on: ubuntu-latest
@@ -19,6 +41,8 @@ jobs:
         run: bun run typecheck
       - name: Build assets
         run: bun run build
+      - name: Ensure generated assets are committed
+        run: git diff --exit-code -- assets snippets/vite-tag.liquid
 
   theme-check:
     name: Theme Check

AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md - AI Contributor Guide
+
+This file is for any AI coding assistant (Claude, Codex, Cursor, etc.) working in this repository.
+
+## Goal
+
+- Keep the starter aligned with Shopify docs-first patterns.
+- Keep TypeScript for behavior and Liquid for markup.
+- Keep customization safe via stable `data-js` contracts.
+
+## Non-Negotiable Rules
+
+- Do not generate cart/minicart/search HTML strings in TS.
+- Do not add `{% render 'vite-tag' %}` in sections/snippets.
+- Keep entrypoint routing centralized in `layout/theme.liquid`.
+- Keep API calls user-driven where required by this starter architecture.
+
+## Where to Implement Changes
+
+- Global bootstrap: `frontend/entrypoints/ts/theme.ts`
+- Cart drawer logic: `frontend/entrypoints/ts/cart/drawer.ts`
+- Cart page logic: `frontend/entrypoints/ts/cart/page.ts`
+- Product logic: `frontend/entrypoints/ts/product.ts` + `frontend/entrypoints/ts/product/*`
+- Collection logic: `frontend/entrypoints/ts/collection.ts`
+- Search drawer logic: `frontend/entrypoints/ts/search/drawer.ts`
+- Liquid markup: `sections/**`, `snippets/**`
+
+## Shopify Patterns Required
+
+- Cart mutations use bundled section rendering (`sections`, `sections_url`).
+- Single section rendering (`?section_id=`) is used only where explicitly intended (e.g. drawer hydration).
+- Locale-aware routes use `window.Shopify.routes.root`.
+
+## Stable Data Contracts
+
+- Cart drawer: `cart-drawer`, `cart-open`, `cart-close`, `cart-items`, `cart-empty`, `cart-subtotal`
+- Cart page: `cart-page`, `cart-page-items`, `cart-page-empty`, `cart-page-footer`, `cart-page-subtotal`
+- Product: `product-form`, `option-value`, `thumbnail`, `add-to-cart`, `cart-status`
+- Collection: `collection-root`, `collection-controls`, `collection-products`, `collection-load-more`, `collection-quick-buy`
+- Search drawer: `search-drawer`, `search-open`, `search-close`, `search-drawer-input`, `search-drawer-groups`
+
+## Local Validation
+
+Run these before considering work complete:
+
+```bash
+bun run typecheck
+bun run build
+```
+
+If available in the environment:
+
+```bash
+theme-check
+```
+
+## Branch-Linked Shopify Reminder
+
+For branches connected directly to a Shopify theme, generated assets must be committed:
+
+- `assets/*`
+- `assets/.vite/manifest.json`
+- `snippets/vite-tag.liquid`
+
+## Suggested Work Loop for AI
+
+1. Read `CLAUDE.md`, `README.md`, and this file.
+2. Edit TS behavior and Liquid markup in their correct layers.
+3. Preserve `data-js` hooks unless intentionally migrating both TS + Liquid.
+4. Run typecheck/build.
+5. Update docs/todo when architecture contracts change.

CLAUDE.md

@@ -59,13 +59,29 @@ loading is handled exclusively by the layout.
 `ts/gift-card.ts` is the only exception: loaded directly in `templates/gift_card.liquid`
 because that template uses `{% layout none %}`.
 
+## TS/Liquid contract
+
+**TS logic only, Liquid markup only.**
+
+- Keep behavior and state orchestration in TypeScript modules under `frontend/entrypoints/ts/**`
+- Keep editable markup in Liquid sections/snippets under `sections/**` and `snippets/**`
+- Treat `data-js` attributes as the integration contract between TS and Liquid
+- Do not move markup generation into TS string templates for cart/minicart/search flows
+
 ## When to add JS
 
 - **Global bootstrap only**: `frontend/entrypoints/ts/theme.ts`
 - **Shared logic/utilities** (e.g. modal, DOM helpers): `frontend/entrypoints/ts/utils/*`
 - **Template-specific logic**: the matching entrypoint (e.g. `frontend/entrypoints/ts/product.ts`)
 - **Never create a new entrypoint** without also updating the router in `layout/theme.liquid`
 
+Current interaction ownership:
+- `ts/theme.ts`: global cart drawer bootstrap
+- `ts/product.ts`: PDP variants/media/add-to-cart states
+- `ts/collection.ts`: PLP sort/filter progressive interactions
+- `ts/cart.ts`: cart page quantity/remove interactions
+- `ts/search.ts`: predictive search interactions
+
 ## Theme preview
 
 ### Prerequisites
@@ -160,6 +176,11 @@ Before merging to `staging` or `main`, ensure:
 - `bun run build` passes
 - `theme-check` passes
 - Smoke test the templates touched by the PR
+- Verify manual QA on touched templates (PDP, PLP, cart page, minicart as relevant)
+
+CI enforces branch flow:
+- PR to `staging` must come from `feat/*`
+- PR to `main` must come from `staging`
 
 ## Troubleshooting
 
@@ -186,6 +207,14 @@ Before merging to `staging` or `main`, ensure:
 2. Goal (what it should do)
 3. Approve the plan before execution
 
+### Start feature branch
+
+```bash
+git checkout staging
+git pull
+git checkout -b feat/<feature-name>
+```
+
 ### Naming conventions
 
 - TS entrypoints: match the Shopify `request.page_type` value

README.md

@@ -25,10 +25,21 @@
   - Shared utilities in `frontend/entrypoints/ts/utils/`
   - `typecheck` gate with `tsc --noEmit`
 
+- Core storefront interactions
+  - PDP variant/media/price synchronization + add-to-cart status handling
+  - Cart drawer with keyboard accessibility, quantity/remove async flows, and fallback to `/cart`
+  - Cart page async quantity/remove flows with empty/error states
+  - Collection sorting, filtering, and progressive load-more behavior
+  - Search predictive suggestions with graceful fallback to full search
+
 - Branch-linked deploy workflow
   - Built assets are committed to branch for Shopify Git-connected themes
   - CI validates quality gates (`typecheck`, `vite:build`, `theme-check`)
 
+- AI-ready contributor workflow
+  - Generic agent guide in `AGENTS.md`
+  - Architecture + conventions in `CLAUDE.md`
+
 ---
 
 ## Scripts
@@ -125,6 +136,29 @@
 
 ---
 
+## Customization Contract
+
+- Keep TS modules focused on behavior/state only.
+  - Put DOM events, async flows, and state sync in `frontend/entrypoints/ts/**`.
+- Keep Liquid focused on markup/content structure only.
+  - Put editable HTML structure in `sections/**` and `snippets/**`.
+- Treat `data-js="..."` attributes as a stable public contract between TS and Liquid.
+  - You can restyle or rearrange markup as long as required `data-js` hooks remain intact.
+
+- Search drawer safe customization points:
+  - Layout container and spacing in `sections/search-drawer.liquid`
+  - Result card markup inside `frontend/entrypoints/ts/search/drawer.ts` (`createResultItem`)
+  - Group ordering/labels inside `frontend/entrypoints/ts/search/drawer.ts` (`renderGroups`)
+
+- Stable `data-js` contracts by module:
+  - Cart drawer: `cart-drawer`, `cart-open`, `cart-close`, `cart-items`, `cart-empty`, `cart-subtotal`
+  - Cart page: `cart-page`, `cart-page-items`, `cart-page-empty`, `cart-page-footer`, `cart-page-subtotal`
+  - Product: `product-form`, `option-value`, `thumbnail`, `add-to-cart`, `cart-status`
+  - Collection: `collection-root`, `collection-controls`, `collection-products`, `collection-load-more`, `collection-quick-buy`
+  - Search drawer: `search-drawer`, `search-open`, `search-close`, `search-drawer-input`, `search-drawer-groups`
+
+---
+
 ## Environment Configuration
 
 - `.env` (local, gitignored)
@@ -165,6 +199,51 @@ Flow:
 3. QA on staging theme
 4. Merge `staging` into `main`
 
+Enforcement in CI:
+- PRs to `staging` must come from `feat/*`
+- PRs to `main` must come from `staging`
+
+## Start a Feature Branch
+
+```bash
+git checkout staging
+git pull
+git checkout -b feat/<short-feature-name>
+```
+
+Before opening a PR, run local quality gates:
+
+```bash
+bun run typecheck
+bun run build
+# Optional when installed locally
+theme-check
+```
+
+If the branch is Shopify Git-connected, commit generated build artifacts:
+- `assets/*`
+- `assets/.vite/manifest.json`
+- `snippets/vite-tag.liquid`
+
+---
+
+## Alias Examples
+
+Use path aliases from `vite.config.js` for cleaner imports:
+
+```ts
+import { addToCart } from '@ts/utils/cart';
+import '@css/main.css';
+```
+
+---
+
+## Linting Strategy
+
+- TypeScript quality gate: `bun run typecheck`
+- Liquid quality gate: Theme Check in CI (`Theme Check` job)
+- Local checks: `bun run typecheck` and `bun run build` (plus optional `theme-check`)
+
 ---
 
 ## Troubleshooting