# Guest Checkout

## Objective

Let buyers pay without creating an account, and offer to save their details afterwards.

A checkout path that takes an email, an address, and a payment without requiring registration, with optional account creation after the order is placed.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Ask for the smallest set of fields that completes the order: contact email, shipping address, payment. Do not ask for a password, and do not put an account creation form in front of the payment step.
2. Create the order record before you attempt payment and give it a stable reference. Every retry, decline, and successful charge attaches to that same order, so support can trace a customer's failed attempts.
3. Offer account creation on the confirmation screen, after the money has moved, and pre-fill it from what was already entered. If the app has Email Verification, use it to claim the order rather than inventing a second confirmation flow.
4. Validate the shipping address and the deliverability of the destination before the payment step, so the buyer fixes a typo before a charge is attempted rather than after one is declined.
5. Do not sign the guest in or create a shadow account silently. A hidden account with an unset password becomes a support problem the first time that person tries to register properly.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A double-click on pay, or a refresh mid-payment, must not produce two charges. Generate an idempotency key per checkout attempt, disable the control once submitted, and make the server reject a repeat of the same attempt.
- A browser crash or an expired session must not lose a half-finished checkout. Persist the entered details against the order reference so returning to the checkout link restores the form where it was left.
- If the entered email already belongs to an account, say so and offer sign-in, but do not block the purchase and do not confirm or deny the account's existence in a way that lets someone probe your customer list.
- Address validation runs before payment. A failed delivery check after a successful charge means a refund and an unhappy buyer, so surface the problem while it is still free to fix.
- The order reference must stay stable across payment retries and declines. Issuing a new number on every attempt makes reconciliation and customer support impossible.
- A guest order still needs a way to be looked at later. Send a link that authorises viewing that one order and nothing else, and expire it.
- Payment succeeding while the confirmation response is lost is normal. Reconcile from the payment provider's record rather than assuming an unreturned request means no charge.
- Card details must never touch the app's own storage or logs, even in an error path that dumps the submitted parameters.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] A buyer completes a purchase end to end without creating an account or setting a password.
- [ ] Double-submitting or refreshing during payment produces exactly one charge.
- [ ] An interrupted checkout can be resumed with the entered details intact.
- [ ] The order reference is unchanged across declines and retries.
- [ ] An email matching an existing account offers sign-in without leaking whether the account exists.
- [ ] Account creation is offered after the order and reuses the details already entered.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.