feat(template): switch PDP variants optimistically

[laugharn]

Summary

• update PDP option selection and color media immediately while preserving real option links
• keep variant ID, price, availability, bundles, and purchase controls server-authoritative
• disable purchase actions while the selected variant route is resolving
• document the optimistic selection behavior

Why

The PDP should feel instant without downloading or reconstructing the complete variant matrix in the browser. This keeps the existing selected-variant query and bounded product payload, while adding only a small client context for visual selection state and transition safety.

Unlike #518, this does not add adjacentVariants, expand firstSelectableVariant, or use Hydrogen's product form store.

Verification

• pnpm exec tsc --noEmit (apps/template) — passed
• focused oxlint on all 8 touched template files — passed with 0 warnings and 0 errors
• focused oxfmt --check on all 8 touched template files — passed
• pnpm build (apps/template) — passed; 33/33 static pages generated
• pnpm exec oxfmt --check content/docs/anatomy/pages/pdp.mdx (apps/docs) — passed
• git diff --check — passed

The session-requested lib/markdown/negotiation.test.ts and lib/markdown/routing.test.ts do not exist on main, and this checkout has no Vitest dependency, so those historical focused tests could not be run.

Notes

The repository-wide template formatting check still reports two unrelated pre-existing files: components/product-detail/bundle-components.tsx and lib/shopify/transforms/product.ts.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shop-docs	Ready	Preview, v0	Aug 24, 2026 12:29pm
shop-template	Ready	Preview, v0	Aug 24, 2026 12:29pm