feat(ep-commerce): server-cart shopper context + composable checkout

.ralph/AGENTS.md

@@ -25,6 +25,9 @@ cd packages/plasmic-mcp && npm run typecheck      # TypeScript type checking (ts
 
 - Monorepo: platform/ (apps), packages/ (SDK), plasmicpkgs/ (code components)
 - **EP Commerce components:** `plasmicpkgs/commerce-providers/elastic-path/src/`
+- **Server-cart architecture (current focus):** `elastic-path/src/shopper-context/` (new directory)
+- **Singleton context pattern to follow:** `elastic-path/src/bundle/composable/BundleContext.tsx`, `elastic-path/src/cart-drawer/CartDrawerContext.tsx`
+- **Existing cart hooks (being replaced):** `elastic-path/src/cart/use-cart.tsx`, `use-add-item.tsx`, `use-remove-item.tsx`, `use-update-item.tsx`
 - **Composable component examples:** `elastic-path/src/bundle/composable/`, `elastic-path/src/cart-drawer/`, `elastic-path/src/variant-picker/`
 - **Existing hooks:** `elastic-path/src/product/use-search.tsx`, `use-product.tsx`; `elastic-path/src/site/use-categories.tsx`
 - **Data normalization:** `elastic-path/src/utils/normalize.ts`

.ralph/PROMPT_build.md

@@ -1,20 +1,20 @@
-0a. Study `.ralph/specs/*` with up to 500 parallel Sonnet subagents to learn the application specifications.
+0a. Study `.ralph/specs/server-cart-architecture.md` and `.ralph/specs/phase-0-shopper-context.md` through `.ralph/specs/phase-3-credential-removal.md` with up to 500 parallel Sonnet subagents to learn the server-cart architecture specifications.
 0b. Study @.ralph/IMPLEMENTATION_PLAN.md.
-0c. For reference, the application source code is in `packages/*/src/*`, `plasmicpkgs/*/src/*`, `plasmicpkgs-dev/*`, `platform/wab/src/*`.
+0c. For reference, the application source code is in `plasmicpkgs/commerce-providers/elastic-path/src/*`. Study the existing singleton context pattern in `src/bundle/composable/BundleContext.tsx` and `src/cart-drawer/CartDrawerContext.tsx` — new ShopperContext must follow this pattern.
 
-1. Your task is to implement functionality per the specifications using parallel subagents. Follow @.ralph/IMPLEMENTATION_PLAN.md and choose the most important item to address. Before making changes, search the codebase (don't assume not implemented) using Sonnet subagents. You may use up to 500 parallel Sonnet subagents for searches/reads and only 1 Sonnet subagent for build/tests. Use Opus subagents when complex reasoning is needed (debugging, architectural decisions).
-2. After implementing functionality or resolving problems, run the tests for that unit of code that was improved. Use the test commands from @.ralph/AGENTS.md for the relevant package. If functionality is missing then it's your job to add it as per the application specifications. Ultrathink.
+1. Your task is to implement functionality per the server-cart specifications. Follow @.ralph/IMPLEMENTATION_PLAN.md and choose the most important incomplete item (build in phase order: P0 → P1 → P2 → P3). Before making changes, search the codebase (don't assume not implemented) using Sonnet subagents. You may use up to 500 parallel Sonnet subagents for searches/reads and only 1 Sonnet subagent for build/tests. Use Opus subagents when complex reasoning is needed.
+2. After implementing functionality, run the tests. Use the test commands from @.ralph/AGENTS.md for the relevant package. All new code goes in `plasmicpkgs/commerce-providers/elastic-path/src/shopper-context/`. Ultrathink.
 3. When you discover issues, immediately update @.ralph/IMPLEMENTATION_PLAN.md with your findings using a subagent. When resolved, update and remove the item.
 4. When the tests pass, update @.ralph/IMPLEMENTATION_PLAN.md, then stage changed files with explicit `git add <file1> <file2> ...` (never use `git add -A`, `git add .`, or `git add -u`), then `git commit` with a message describing the changes. After the commit, `git push`.
 
 99999. Important: When authoring documentation, capture the why — tests and implementation importance.
 999999. Important: Single sources of truth, no migrations/adapters. If tests unrelated to your work fail, resolve them as part of the increment.
 9999999. You may add extra logging if required to debug issues.
 99999999. Keep @.ralph/IMPLEMENTATION_PLAN.md current with learnings using a subagent — future work depends on this to avoid duplicating efforts. Update especially after finishing your turn.
-999999999. When you learn something new about how to run the application, update @.ralph/AGENTS.md using a subagent but keep it brief. For example if you run commands multiple times before learning the correct command then that file should be updated.
-9999999999. For any bugs you notice, resolve them or document them in @.ralph/IMPLEMENTATION_PLAN.md using a subagent even if it is unrelated to the current piece of work.
-99999999999. Implement functionality completely. Placeholders and stubs waste efforts and time redoing the same work.
-999999999999. When @.ralph/IMPLEMENTATION_PLAN.md becomes large periodically clean out the items that are completed from the file using a subagent.
-9999999999999. If you find inconsistencies in the .ralph/specs/* then use an Opus subagent with 'ultrathink' requested to update the specs.
-99999999999999. IMPORTANT: Keep @.ralph/AGENTS.md operational only — status updates and progress notes belong in `IMPLEMENTATION_PLAN.md`. A bloated AGENTS.md pollutes every future loop's context.
-999999999999999. IMPORTANT: Always use explicit file paths with `git add` (e.g., `git add packages/plasmic-mcp/src/server.ts`). NEVER use `git add -A`, `git add .`, or `git add -u`.
+999999999. When you learn something new about how to run the application, update @.ralph/AGENTS.md using a subagent but keep it brief.
+9999999999. For any bugs you notice, resolve them or document them in @.ralph/IMPLEMENTATION_PLAN.md using a subagent.
+99999999999. Implement functionality completely. Placeholders and stubs waste time.
+999999999999. When @.ralph/IMPLEMENTATION_PLAN.md becomes large periodically clean out completed items.
+9999999999999. If you find inconsistencies in the .ralph/specs/* then use an Opus subagent with 'ultrathink' to update the specs.
+99999999999999. IMPORTANT: Keep @.ralph/AGENTS.md operational only — status updates belong in IMPLEMENTATION_PLAN.md.
+999999999999999. IMPORTANT: Always use explicit file paths with `git add`. NEVER use `git add -A`, `git add .`, or `git add -u`.

.ralph/PROMPT_plan.md

@@ -1,10 +1,15 @@
-0a. Study `.ralph/specs/*` with up to 250 parallel Sonnet subagents to learn the application specifications.
+0a. Study `.ralph/specs/server-cart-architecture.md` and `.ralph/specs/phase-0-shopper-context.md` through `.ralph/specs/phase-3-credential-removal.md` with up to 250 parallel Sonnet subagents to learn the server-cart architecture specifications.
 0b. Study @.ralph/IMPLEMENTATION_PLAN.md (if present) to understand the plan so far.
-0c. Study `plasmicpkgs/commerce-providers/elastic-path/src/*` with up to 250 parallel Sonnet subagents to understand existing composable component patterns (bundle, cart-drawer, variant-picker), hooks, and utilities.
-0d. For reference, the application source code is in `plasmicpkgs/commerce-providers/elastic-path/src/*`, `packages/*/src/*`, `plasmicpkgs-dev/*`, `platform/wab/src/*`.
+0c. Study `plasmicpkgs/commerce-providers/elastic-path/src/*` with up to 250 parallel Sonnet subagents to understand existing code patterns — especially `src/cart/`, `src/checkout/composable/`, `src/utils/cart-cookie.ts`, `src/registerCommerceProvider.tsx`, `src/const.ts`, and the singleton context pattern in `src/bundle/composable/BundleContext.tsx` and `src/cart-drawer/CartDrawerContext.tsx`.
+0d. For reference, the application source code is in `plasmicpkgs/commerce-providers/elastic-path/src/*`, `packages/*/src/*`, `plasmicpkgs-dev/*`.
 
-1. Study @.ralph/IMPLEMENTATION_PLAN.md (if present; it may be incorrect) and use up to 500 Sonnet subagents to study existing source code in `plasmicpkgs/commerce-providers/elastic-path/src/*` and compare it against `.ralph/specs/*`. Use an Opus subagent to analyze findings, prioritize tasks, and create/update @.ralph/IMPLEMENTATION_PLAN.md as a bullet point list sorted in priority of items yet to be implemented. Ultrathink. Consider searching for TODO, minimal implementations, placeholders, skipped/flaky tests, and inconsistent patterns. Study @.ralph/IMPLEMENTATION_PLAN.md to determine starting point for research and keep it up to date with items considered complete/incomplete using subagents.
+1. Study @.ralph/IMPLEMENTATION_PLAN.md (if present; it may be incorrect) and use up to 500 Sonnet subagents to study existing source code in `plasmicpkgs/commerce-providers/elastic-path/src/*` and compare it against the server-cart specs. Specifically check:
+   - Does `src/shopper-context/` directory exist yet? What files are in it?
+   - What is the current state of `src/cart/use-cart.tsx` and other cart hooks?
+   - How does the Symbol.for singleton context pattern work in `BundleContext.tsx`?
+   - What does `src/checkout/composable/EPCheckoutCartSummary.tsx` accept as props?
+   Use an Opus subagent to analyze findings, prioritize tasks, and create/update @.ralph/IMPLEMENTATION_PLAN.md as a bullet point list sorted by phase (P0 → P1 → P2 → P3). Ultrathink. Consider searching for TODO, placeholders, skipped tests, and incomplete implementations.
 
-IMPORTANT: Plan only. Do NOT implement anything. Do NOT assume functionality is missing; confirm with code search first. Treat `packages/` and `plasmicpkgs/` as the monorepo's shared libraries for SDK packages and code component packages. Prefer consolidated, idiomatic implementations there over ad-hoc copies.
+IMPORTANT: Plan only. Do NOT implement anything. Do NOT assume functionality is missing; confirm with code search first. Build in phase order: Phase 0 must be complete before Phase 1, etc. The primary target directory is `src/shopper-context/` (new) within the EP commerce provider package. Follow the headless Provider → Hook pattern documented in @.ralph/AGENTS.md. Per upstream merge strategy, prefer new files over modifying existing ones.
 
-ULTIMATE GOAL: Implement all specifications in `.ralph/specs/`. The primary source code is in `plasmicpkgs/commerce-providers/elastic-path/src/`. Follow the headless Provider → Repeater composable pattern documented in @.ralph/AGENTS.md. Per upstream merge strategy, prefer new files over modifying existing ones. Consider missing elements and plan accordingly. If an element is missing, search first to confirm it doesn't exist, then if needed author the specification at .ralph/specs/FILENAME.md. If you create a new element then document the plan to implement it in @.ralph/IMPLEMENTATION_PLAN.md using a subagent.
+ULTIMATE GOAL: Implement the server-only cart architecture per `.ralph/specs/phase-0-shopper-context.md` through `.ralph/specs/phase-3-credential-removal.md`. All new code goes in `src/shopper-context/` within `plasmicpkgs/commerce-providers/elastic-path/`. Existing cart hooks in `src/cart/` are NOT modified until Phase 3 (deprecation only). If you find inconsistencies in the specs, use an Opus subagent with 'ultrathink' to update the specs.