@akinon/projectzero 1.99.0-snapshot-ZERO-3640-20250919140935 → 1.100.0-rc.71

package/app-template/.github/instructions/edge-cases.instructions.md

@@ -0,0 +1,73 @@
+---
+applyTo: '**'
+---
+
+# Edge Cases & Troubleshooting Instructions
+
+## Overview
+
+This document contains common edge cases, bugs, and troubleshooting steps encountered in Project Zero Next.js development. These are real-world issues that have caused development delays and should be checked first when similar problems occur.
+
+## Checkout Flow Edge Cases
+
+### 1. Order Selection Page Request Timing
+
+**Problem:** `orderselectionpage` request should NOT be called after `walletselectionpage` or `walletpaymentpage` requests.
+
+This causes checkout flow to break after wallet payment steps, order selection shows incorrect state, and payment flow gets reset unexpectedly. After `walletselectionpage` or `walletpaymentpage` requests are made, `orderselectionpage` request should not be called. Always check the sequence of checkout API calls.
+
+### 2. Guest Login with URL Parameters
+
+**Problem:** Adding `?page=IndexPage` to checkout URLs breaks guest login functionality.
+
+Guest login fails on checkout URLs with `?page=IndexPage` but works fine without the parameter. This parameter interferes with authentication middleware routing. Avoid adding unnecessary URL parameters to checkout flows.
+
+### 3. Agreement Error After 3D Payment Redirect
+
+**Problem:** "You must accept agreement to continue" error appears after 3D payment or redirections, but the issue is NOT related to agreements.
+
+Agreement error occurs after successful 3D payment and checkout flow breaks after external redirections. The error message is misleading - actually `preOrder` data gets reset/lost during payment redirections. Don't assume agreement errors are actually about agreements.
+
+### 4. Address Visibility with fetchCheckout
+
+**Problem:** When `fetchCheckout` request includes `page=IndexPage` parameter, addresses don't show in checkout and the entire flow breaks.
+
+Addresses are missing from checkout page, shipping options don't load, and checkout flow is completely broken. Avoid adding unnecessary parameters to core checkout requests and validate that all checkout data loads properly.
+
+## Plugin & Configuration Edge Cases
+
+### 5. Attribute-Based Shipping Options Typo
+
+**Problem:** `attribute_based_shipping_options` was incorrectly entered as `atribute_based` (missing 't') in brand configurations.
+
+Shipping options don't work for specific brands and debugging is difficult because the setting exists but is misspelled. This can cause days of debugging. Always double-check configuration property names.
+
+### 6. Apple Pay Plugin Configuration
+
+**Problem:** Apple Pay can work as both `confirmation` and `wallet` payment types, but for the plugin to work properly, it should NOT be configured as `confirmation` type.
+
+Apple Pay flow breaks in certain scenarios, payment confirmation issues occur, and plugin conflicts with checkout flow. Always configure Apple Pay as wallet type.
+
+## Build & Development Edge Cases
+
+### 7. Build Failures Due to yarn.lock Corruption
+
+**Problem:** Build fails with apparent TypeScript errors in `@akinon/next` components, but the real issue is a corrupted `yarn.lock` file.
+
+Build fails with nonsensical type errors, components from `@akinon/next` are flagged with errors, and multiple versions of the same package exist in lock file.
+
+```bash
+# Check for duplicate packages in yarn.lock
+yarn list --pattern "@akinon/next" --depth=0
+
+# If multiple versions exist, clean up
+rm yarn.lock
+rm -rf node_modules
+yarn install
+```
+
+Regularly check `yarn.lock` for duplicate dependencies and use `yarn dedupe` after adding new packages.
+
+---
+
+**Remember:** Edge cases often have misleading error messages. Always investigate the root cause rather than fixing symptoms. The most time-consuming bugs are usually simple configuration or timing issues.

package/app-template/.gitignore

@@ -67,3 +67,6 @@ certificates
 public/locales/*/index.json
 
 certificates
+
+# generated files
+generated-routes.js