Misc fixes: Storefront shop layout, product filter UI improvements, and cart badge styling

Major improvements to WooNooW Page Editor system:

Schema & Architecture:
- Canonical section schema with unified sectionSchema.ts
- Normalized feature-grid to use items (not features)
- Standardized default values across all section types
- Schema versioning with automatic migration on read

Backend (PHP):
- Enhanced PlaceholderRenderer with typed output contracts
- Added fallback behavior for empty/invalid dynamic sources
- Added caching support for post data resolution
- New SchemaMigration class for backward compatibility
- New Features class for feature flags
- Enhanced PageSSR with full style support
- Removed controller-level special-casing for related_posts

Frontend (Admin SPA):
- Updated CanvasRenderer with schema-aware transformation
- Enhanced InspectorPanel with canonical schema metadata
- Added new section renderers

Frontend (Customer SPA):
- New section components: BentoCategoryGrid, MarqueeBanner, ProductCarousel, ShoppableImage
- Updated FeatureGridSection for items prop contract

Testing:
- Add PHP tests: SchemaMigrationTest, PlaceholderRendererTest, PageSSRTest
- Add TypeScript tests: schema-integration, feature-grid-regression
- Add parity tests for React vs SSR content matching
- Add CI script: check-schema-drift.mjs
- Add VERIFICATION_CHECKLIST.md

Documentation:
- RELEASE_NOTES-v1.0.md with full release notes
- docs/PAGE_EDITOR_SECTION_SCHEMA_V1.md
- docs/PAGE_EDITOR_SSR_COVERAGE_AUDIT.md

.agent/plans/affiliate-module.md

@@ -0,0 +1,241 @@
+# Affiliate Module Plan
+
+## Overview
+Referral tracking with hybrid customer/affiliate roles, integrated as a core plugin module.
+
+---
+
+## Module Architecture
+
+### Core Features
+- **Affiliate registration**: Customers can become affiliates
+- **Approval workflow**: Manual or auto-approval of affiliates
+- **Unique referral links/codes**: Each affiliate gets unique tracking
+- **Commission tracking**: Track referrals and calculate earnings
+- **Tiered commission rates**: Different rates per product/category/affiliate level
+- **Payout management**: Track and process affiliate payouts
+- **Affiliate dashboard**: Self-service stats and link generator
+
+### Hybrid Roles
+- A customer can also be an affiliate
+- No separate user type; affiliate data linked to existing user
+- Affiliates can still make purchases (self-referral rules configurable)
+
+---
+
+## Database Schema
+
+### Table: `woonoow_affiliates`
+```sql
+CREATE TABLE woonoow_affiliates (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  user_id BIGINT UNSIGNED NOT NULL UNIQUE,
+  status ENUM('pending', 'active', 'rejected', 'suspended') DEFAULT 'pending',
+  referral_code VARCHAR(50) NOT NULL UNIQUE,
+  commission_rate DECIMAL(5,2) DEFAULT NULL,  -- Override global rate
+  tier_id BIGINT UNSIGNED DEFAULT NULL,
+  payment_email VARCHAR(255) DEFAULT NULL,
+  payment_method VARCHAR(50) DEFAULT NULL,
+  total_earnings DECIMAL(15,2) DEFAULT 0,
+  total_unpaid DECIMAL(15,2) DEFAULT 0,
+  total_paid DECIMAL(15,2) DEFAULT 0,
+  referral_count INT UNSIGNED DEFAULT 0,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_user_id (user_id),
+  INDEX idx_status (status),
+  INDEX idx_referral_code (referral_code)
+);
+```
+
+### Table: `woonoow_referrals`
+```sql
+CREATE TABLE woonoow_referrals (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  affiliate_id BIGINT UNSIGNED NOT NULL,
+  order_id BIGINT UNSIGNED NOT NULL,
+  customer_id BIGINT UNSIGNED DEFAULT NULL,
+  subtotal DECIMAL(15,2) NOT NULL,
+  commission_rate DECIMAL(5,2) NOT NULL,
+  commission_amount DECIMAL(15,2) NOT NULL,
+  status ENUM('pending', 'approved', 'rejected', 'paid') DEFAULT 'pending',
+  referral_type ENUM('link', 'code', 'coupon') DEFAULT 'link',
+  ip_address VARCHAR(45) DEFAULT NULL,
+  user_agent TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  approved_at DATETIME DEFAULT NULL,
+  paid_at DATETIME DEFAULT NULL,
+  INDEX idx_affiliate (affiliate_id),
+  INDEX idx_order (order_id),
+  INDEX idx_status (status)
+);
+```
+
+### Table: `woonoow_payouts`
+```sql
+CREATE TABLE woonoow_payouts (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  affiliate_id BIGINT UNSIGNED NOT NULL,
+  amount DECIMAL(15,2) NOT NULL,
+  method VARCHAR(50) DEFAULT NULL,
+  reference VARCHAR(255) DEFAULT NULL,  -- Bank ref, PayPal transaction, etc.
+  status ENUM('pending', 'processing', 'completed', 'failed') DEFAULT 'pending',
+  notes TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  completed_at DATETIME DEFAULT NULL,
+  INDEX idx_affiliate (affiliate_id),
+  INDEX idx_status (status)
+);
+```
+
+### Table: `woonoow_affiliate_tiers` (Optional)
+```sql
+CREATE TABLE woonoow_affiliate_tiers (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  name VARCHAR(100) NOT NULL,
+  commission_rate DECIMAL(5,2) NOT NULL,
+  min_referrals INT UNSIGNED DEFAULT 0,  -- Auto-promote at X referrals
+  min_earnings DECIMAL(15,2) DEFAULT 0,   -- Auto-promote at X earnings
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## Backend Structure
+
+```
+includes/Modules/Affiliate/
+├── AffiliateModule.php      # Bootstrap, hooks, tracking
+├── AffiliateManager.php     # Core logic
+├── ReferralTracker.php      # Track referral cookies/links
+└── AffiliateSettings.php    # Settings schema
+
+includes/Api/AffiliatesController.php  # REST endpoints
+```
+
+### AffiliateManager Methods
+```php
+- register($user_id)              # Register user as affiliate
+- approve($affiliate_id)          # Approve pending affiliate
+- reject($affiliate_id, $reason)  # Reject application
+- suspend($affiliate_id)          # Suspend affiliate
+- track_referral($order, $affiliate) # Create referral record
+- calculate_commission($order, $affiliate) # Calculate earnings
+- approve_referral($referral_id)  # Approve pending referral
+- create_payout($affiliate_id, $amount) # Create payout request
+- process_payout($payout_id)      # Mark payout complete
+- get_affiliate_stats($affiliate_id) # Dashboard stats
+```
+
+### Referral Tracking
+1. Affiliate shares link: `yourstore.com/?ref=CODE`
+2. ReferralTracker sets cookie: `wnw_ref=CODE` (30 days default)
+3. On checkout, check cookie and link to affiliate
+4. On order completion, create referral record
+
+---
+
+## REST API Endpoints
+
+### Admin Endpoints
+```
+GET    /affiliates                 # List affiliates
+GET    /affiliates/{id}            # Affiliate details
+PUT    /affiliates/{id}            # Update affiliate
+POST   /affiliates/{id}/approve    # Approve affiliate
+POST   /affiliates/{id}/reject     # Reject affiliate
+GET    /affiliates/referrals       # All referrals
+GET    /affiliates/payouts         # All payouts
+POST   /affiliates/payouts/{id}/complete # Complete payout
+```
+
+### Customer/Affiliate Endpoints
+```
+GET    /my-affiliate               # Check if affiliate
+POST   /my-affiliate/register      # Register as affiliate
+GET    /my-affiliate/stats         # Dashboard stats
+GET    /my-affiliate/referrals     # My referrals
+GET    /my-affiliate/payouts       # My payouts
+POST   /my-affiliate/payout-request # Request payout
+GET    /my-affiliate/links         # Generate referral links
+```
+
+---
+
+## Admin SPA
+
+### Affiliates List (`/marketing/affiliates`)
+- Table: Name, Email, Status, Referrals, Earnings, Actions
+- Filters: Status, Date range
+- Actions: Approve, Reject, View
+
+### Affiliate Detail (`/marketing/affiliates/:id`)
+- Affiliate info card
+- Stats summary
+- Referrals list
+- Payouts history
+- Action buttons
+
+### Referrals List (`/marketing/affiliates/referrals`)
+- All referrals across affiliates
+- Filters: Status, Affiliate, Date
+
+### Payouts (`/marketing/affiliates/payouts`)
+- Payout requests
+- Process payouts
+- Payment history
+
+---
+
+## Customer SPA
+
+### Become an Affiliate (`/my-account/affiliate`)
+- Registration form (if not affiliate)
+- Dashboard (if affiliate)
+
+### Affiliate Dashboard
+- Stats: Total Referrals, Pending, Approved, Earnings
+- Referral link generator
+- Recent referrals
+- Payout request button
+
+### My Referrals
+- List of referrals with status
+- Commission amount
+
+### My Payouts
+- Payout history
+- Pending amount
+- Request payout form
+
+---
+
+## Settings Schema
+
+```php
+return [
+  'enabled' => true,
+  'registration_type' => 'open',  // open, approval, invite
+  'auto_approve' => false,
+  'default_commission_rate' => 10,  // 10%
+  'commission_type' => 'percentage',  // percentage, flat
+  'cookie_duration' => 30,  // days
+  'min_payout_amount' => 50,
+  'payout_methods' => ['bank_transfer', 'paypal'],
+  'allow_self_referral' => false,
+  'referral_approval' => 'auto',  // auto, manual
+  'approval_delay_days' => 14,  // Wait X days before auto-approve
+];
+```
+
+---
+
+## Implementation Priority
+1. Database tables and AffiliateManager
+2. ReferralTracker (cookie-based tracking)
+3. Order hook to create referrals
+4. Admin SPA affiliates management
+5. Customer SPA affiliate dashboard
+6. Payout management
+7. Tier system (optional)

.agent/plans/onboarding_strategy.md

@@ -0,0 +1,39 @@
+# User Onboarding & Simplification Strategy
+
+## The Problem
+The current "General Settings" screen presents too many technical decisions (SPA Mode, Entry Page, Container Width, Typography, Colors) at once. This creates analysis paralysis for new users who just want to "get the store running."
+
+## Recommended Solution: The "Quick Setup" Wizard
+Instead of dumping users into the Settings screen, we implement a **Linear Onboarding Flow** that launches automatically on the first visit (or manually via "Setup Wizard" button).
+
+### Tech Stack
+*   **No new libraries** needed. We can build this using your existing `@radix-ui` components (Dialog, Cards, Button).
+*   **State**: Managed via simple React state or Zustand store.
+
+### The Flow (4 Steps)
+
+#### 1. Welcome & Mode (The "What"?)
+*   **Question**: "How do you want to run your store?"
+*   **Options**:
+    *   **Immersive (Full SPA)**: "Modern, app-like experience. Best for dedicated stores." (Selects 'full')
+    *   **Classic (Checkout Only)**: "Keep your current theme, but use our super-fast checkout." (Selects 'checkout_only')
+    *   **Standard**: "Use standard WordPress pages." (Selects 'disabled')
+
+#### 2. The Homepage (The "Where"?)
+*   **Question**: "Where should customers land?"
+*   **Action**: Dropdown to select a page.
+*   **Magic Button**: "Auto-create 'Shop' Page" (Creates a page, sets it as SPA Entry, and sets WP Frontpage setting automatically). **<-- This solves the redirect bug confusion.**
+
+#### 3. Styling (The "Look")
+*   **Question**: "Choose your vibe."
+*   **Design**:
+    *   **Layout**: Simple visual toggle between "Boxed" (Focus) vs "Full Width" (Immersive).
+    *   **Theme**: Clickable color swatches (Modern Black, Trusty Blue, Vibrant Purple).
+
+#### 4. The Finish Line
+*   **Action**: "Save & Launch Builder".
+*   **Result**: Redirects the user directly to the Visual Builder for their home page.
+
+## Ancillary Improvements
+1.  **Contextual Hints**: Use the already installed `HoverCard` or `Popover` to add "?" icons next to complex settings (like "SPA Entry Page") explaining them in plain English.
+2.  **Smart Defaults**: Pre-select "Boxed", "Full SPA", and "Modern" font pair so users can just click "Next -> Next -> Next" if they don't care.

.agent/plans/shipping-label.md

@@ -0,0 +1,84 @@
+# Shipping Label Plan
+
+## Overview
+Standardized waybill data structure for shipping label generation.
+
+## Problem
+- Different shipping carrier addons (JNE, JNT, SiCepat, etc.) store data differently
+- No standard structure for label generation
+- Label button needs waybill data to function
+
+## Proposed Solution
+
+### 1. Standardized Meta Key
+Order meta: `_shipping_waybill`
+
+### 2. Data Structure
+```json
+{
+  "tracking_number": "JNE123456789",
+  "carrier": "jne",
+  "carrier_name": "JNE Express",
+  "service": "REG",
+  "estimated_days": 3,
+  "sender": {
+    "name": "Store Name",
+    "address": "Full address line 1",
+    "city": "Jakarta",
+    "postcode": "12345",
+    "phone": "08123456789"
+  },
+  "recipient": {
+    "name": "Customer Name", 
+    "address": "Full address line 1",
+    "city": "Bandung",
+    "postcode": "40123",
+    "phone": "08987654321"
+  },
+  "package": {
+    "weight": "1.5",
+    "weight_unit": "kg",
+    "dimensions": "20x15x10",
+    "dimensions_unit": "cm"
+  },
+  "label_url": null,
+  "barcode": "JNE123456789",
+  "barcode_type": "128",
+  "created_at": "2026-01-05T12:00:00+07:00"
+}
+```
+
+### 3. Addon Integration Contract
+
+Shipping addons MUST:
+1. Call `update_post_meta($order_id, '_shipping_waybill', $waybill_data)`
+2. Use the standard structure above
+3. Set `label_url` if carrier provides downloadable PDF
+4. Set `barcode` for local label generation
+
+### 4. Label Button Behavior
+1. Check if `_shipping_waybill` meta exists on order
+2. If `label_url` → open carrier's PDF
+3. Otherwise → generate printable label from meta data
+
+### 5. UI Behavior
+- Label button hidden if order is virtual-only
+- Label button shows "Generate Label" if no waybill yet
+- Label button shows "Print Label" if waybill exists
+
+## API Endpoint (Future)
+```
+POST /woonoow/v1/orders/{id}/generate-waybill
+- Calls shipping carrier API
+- Stores waybill in standardized format
+- Returns waybill data
+
+GET /woonoow/v1/orders/{id}/waybill
+- Returns current waybill data
+```
+
+## Implementation Priority
+1. Define standard structure (this document)
+2. Implement Label UI conditional logic
+3. Create waybill API endpoint
+4. Document for addon developers

.agent/plans/software-distribution.md

@@ -0,0 +1,379 @@
+# Software Distribution System Plan (Simplified)
+
+Extends WooNooW Licensing with software versioning, changelog, and update checker API. Works for **any software type** - not just WordPress plugins/themes.
+
+---
+
+## Core Principle
+
+**Reuse existing WooCommerce infrastructure:**
+- ✅ Downloadable Product = file hosting (already exists)
+- ✅ Licensing Module = license validation (already exists)
+- ➕ NEW: Version tracking + changelog per product
+- ➕ NEW: Update checker API endpoint
+
+---
+
+## What We Add (Minimal)
+
+| Field | Type | Location |
+|-------|------|----------|
+| `Current Version` | Text (e.g., "1.2.3") | Product Edit |
+| `Changelog` | Rich Text/Markdown | Product Edit |
+| `Software Slug` | Text (unique identifier) | Product Edit |
+| `Enable WP Integration` | Checkbox | Product Edit |
+
+**If "Enable WP Integration" is checked:**
+| Field | Type |
+|-------|------|
+| `Requires WP` | Text |
+| `Tested WP` | Text |
+| `Requires PHP` | Text |
+| `Icon URL` | Image |
+| `Banner URL` | Image |
+
+---
+
+## Database Schema
+
+**Table: `wp_woonoow_software_versions`**
+
+```sql
+CREATE TABLE wp_woonoow_software_versions (
+    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    product_id BIGINT UNSIGNED NOT NULL,
+    version VARCHAR(50) NOT NULL,
+    changelog LONGTEXT,
+    release_date DATETIME NOT NULL,
+    is_current TINYINT(1) DEFAULT 0,
+    download_count INT DEFAULT 0,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    
+    INDEX idx_product (product_id),
+    INDEX idx_current (product_id, is_current),
+    UNIQUE KEY unique_version (product_id, version)
+);
+```
+
+**Product Meta (stored in `wp_postmeta`):**
+```
+_woonoow_software_enabled: yes/no
+_woonoow_software_slug: my-awesome-plugin
+_woonoow_software_current_version: 1.2.3
+_woonoow_software_wp_enabled: yes/no
+_woonoow_software_requires_wp: 6.0
+_woonoow_software_tested_wp: 6.7
+_woonoow_software_requires_php: 7.4
+_woonoow_software_icon: attachment_id or URL
+_woonoow_software_banner: attachment_id or URL
+```
+
+---
+
+## API Endpoints
+
+### 1. Update Check (Generic)
+
+`GET /wp-json/woonoow/v1/software/check`
+
+**Request:**
+```json
+{
+  "license_key": "XXXX-XXXX-XXXX-XXXX",
+  "slug": "my-software",
+  "version": "1.0.0",
+  "site_url": "https://client-site.com"
+}
+```
+
+**Response (Generic - Any Software):**
+```json
+{
+  "success": true,
+  "update_available": true,
+  "product": {
+    "name": "My Awesome Software",
+    "slug": "my-software"
+  },
+  "current_version": "1.0.0",
+  "latest_version": "1.2.3",
+  "download_url": "https://vendor.com/wp-json/woonoow/v1/software/download?token=abc123",
+  "changelog_url": "https://vendor.com/wp-json/woonoow/v1/software/changelog?slug=my-software",
+  "changelog": "## 1.2.3\n- Fixed bug\n- Added feature",
+  "release_date": "2026-02-06"
+}
+```
+
+**Response (WordPress Plugin/Theme - Extended):**
+```json
+{
+  "success": true,
+  "update_available": true,
+  "product": {
+    "name": "My WordPress Plugin",
+    "slug": "my-wp-plugin"
+  },
+  "current_version": "1.0.0",
+  "latest_version": "1.2.3",
+  "download_url": "https://vendor.com/wp-json/woonoow/v1/software/download?token=abc123",
+  "changelog_url": "https://vendor.com/wp-json/woonoow/v1/software/changelog?slug=my-wp-plugin",
+  "changelog": "## 1.2.3\n- Fixed bug",
+  "release_date": "2026-02-06",
+  
+  "wordpress": {
+    "requires": "6.0",
+    "tested": "6.7",
+    "requires_php": "7.4",
+    "icons": {
+      "1x": "https://vendor.com/icon-128.png",
+      "2x": "https://vendor.com/icon-256.png"
+    },
+    "banners": {
+      "low": "https://vendor.com/banner-772x250.jpg",
+      "high": "https://vendor.com/banner-1544x500.jpg"
+    }
+  }
+}
+```
+
+**Response (No Update):**
+```json
+{
+  "success": true,
+  "update_available": false,
+  "current_version": "1.2.3",
+  "latest_version": "1.2.3"
+}
+```
+
+**Response (License Invalid):**
+```json
+{
+  "success": false,
+  "error": "license_expired",
+  "message": "Your license has expired. Renew to receive updates."
+}
+```
+
+---
+
+### 2. Download
+
+`GET /wp-json/woonoow/v1/software/download`
+
+**Request:**
+```
+?token=abc123&license_key=XXXX-XXXX-XXXX-XXXX
+```
+
+**Response:** Binary file stream (the downloadable file from WooCommerce product)
+
+**Token Validation:**
+- One-time use token
+- 5-minute expiry
+- Tied to specific license
+
+---
+
+### 3. Changelog
+
+`GET /wp-json/woonoow/v1/software/changelog`
+
+**Request:**
+```
+?slug=my-software&version=1.2.3 (optional)
+```
+
+**Response:**
+```json
+{
+  "slug": "my-software",
+  "versions": [
+    {
+      "version": "1.2.3",
+      "release_date": "2026-02-06",
+      "changelog": "## 1.2.3\n- Fixed critical bug\n- Added dark mode"
+    },
+    {
+      "version": "1.2.0",
+      "release_date": "2026-01-15",
+      "changelog": "## 1.2.0\n- Major feature release"
+    }
+  ]
+}
+```
+
+---
+
+## Client Integration Examples
+
+### A. WordPress Plugin (Auto-Updates)
+
+Documented in: **woonoow-docs** → Developer → Software Updates
+
+```php
+// Include the updater class (provided by WooNooW)
+require_once 'class-woonoow-updater.php';
+
+new WooNooW_Updater([
+    'api_url'     => 'https://your-store.com/',
+    'slug'        => 'my-plugin',
+    'version'     => MY_PLUGIN_VERSION,
+    'license_key' => get_option('my_plugin_license'),
+    'plugin_file' => __FILE__,
+]);
+```
+
+### B. Generic Software (Manual Check)
+
+For desktop apps, SaaS, scripts, etc:
+
+```javascript
+// Check for updates
+const response = await fetch('https://vendor.com/wp-json/woonoow/v1/software/check', {
+  method: 'POST',
+  body: JSON.stringify({
+    license_key: 'XXXX-XXXX-XXXX-XXXX',
+    slug: 'my-desktop-app',
+    version: '1.0.0'
+  })
+});
+
+const data = await response.json();
+if (data.update_available) {
+  console.log(`New version ${data.latest_version} available!`);
+  console.log(`Download: ${data.download_url}`);
+}
+```
+
+```python
+# Python example
+import requests
+
+response = requests.post('https://vendor.com/wp-json/woonoow/v1/software/check', json={
+    'license_key': 'XXXX-XXXX-XXXX-XXXX',
+    'slug': 'my-python-tool',
+    'version': '1.0.0'
+})
+
+data = response.json()
+if data.get('update_available'):
+    print(f"Update available: {data['latest_version']}")
+```
+
+---
+
+## Implementation Flow
+
+### Product Setup (Seller)
+
+1. Create WooCommerce product (Simple, Downloadable)
+2. Enable Licensing ✓
+3. Enable Software Distribution ✓
+4. Set software slug: `my-software`
+5. Upload downloadable file (uses existing WC functionality)
+6. Set version: `1.0.0`
+7. Add changelog
+8. (Optional) Enable WordPress Integration → fill WP-specific fields
+
+### Release New Version
+
+1. Upload new file to product
+2. Click "Add New Version"
+3. Enter version number: `1.1.0`
+4. Write changelog
+5. Save → Previous version archived, new version active
+
+### Client Updates
+
+1. Client software calls `/software/check` with license key
+2. API validates license → returns latest version info
+3. Client downloads via `/software/download` with token
+4. Client installs update (WordPress = automatic, others = manual/custom)
+
+---
+
+## Files to Create
+
+```
+includes/
+├── Api/
+│   └── SoftwareController.php       # REST endpoints
+├── Modules/
+│   └── Software/
+│       ├── SoftwareModule.php       # Bootstrap
+│       └── SoftwareManager.php      # Core logic
+└── Templates/
+    └── updater/
+        └── class-woonoow-updater.php  # WP client library
+
+admin-spa/src/routes/Settings/
+└── Software.tsx                      # Version manager UI
+```
+
+---
+
+## Documentation (woonoow-docs)
+
+Create new section: **Developer → Software Distribution**
+
+1. **Overview** - What is software distribution
+2. **Setup Guide** - How to configure products
+3. **API Reference** - Endpoint documentation
+4. **WordPress Integration** - How to use the updater class
+5. **Generic Integration** - Examples for non-WP software
+6. **Client Libraries** - Download the updater class
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core ✅
+- [x] Database table + product meta fields (`wp_woonoow_software_versions`, `wp_woonoow_software_downloads`)
+- [x] SoftwareManager class (`includes/Modules/Software/SoftwareManager.php`)
+- [x] SoftwareModule class (`includes/Modules/Software/SoftwareModule.php`)
+- [x] SoftwareSettings class (`includes/Modules/SoftwareSettings.php`)
+- [x] Product edit fields in WooCommerce
+
+### Phase 2: API ✅
+- [x] SoftwareController (`includes/Api/SoftwareController.php`)
+- [x] `/software/check` endpoint (GET/POST)
+- [x] `/software/download` endpoint with token
+- [x] `/software/changelog` endpoint
+
+### Phase 3: Admin UI ✅
+- [x] Version release manager in Admin SPA (`routes/Products/SoftwareVersions/index.tsx`)
+- [x] Changelog editor (Dialog with Textarea)
+- [x] Version history table
+
+### Phase 4: Client Library ✅
+- [x] `class-woonoow-updater.php` for WP (`templates/updater/class-woonoow-updater.php`)
+- [x] Supports both plugins and themes
+- [x] Includes license status checking
+
+### Phase 5: Documentation ✅
+- [x] Add docs to woonoow-docs (`contents/docs/developer/software-updates/index.mdx`)
+- [x] API reference
+- [x] Integration examples (WordPress, JavaScript, Python)
+
+---
+
+## Security
+
+| Measure | Description |
+|---------|-------------|
+| License Validation | All endpoints verify active license |
+| Download Tokens | One-time use, 5-min expiry |
+| Rate Limiting | Max 10 requests/minute per license |
+| Signed URLs | HMAC signature for download links |
+
+---
+
+## Questions Before Implementation
+
+1. ✅ Generic for any software (not just WP)
+2. ✅ Reuse WooCommerce downloadable files
+3. ✅ WordPress fields are optional
+4. ✅ Document client library in woonoow-docs
+
+Ready to proceed with Phase 1?

.agent/plans/subscription-module.md

@@ -0,0 +1,191 @@
+# Subscription Module Plan
+
+## Overview
+Recurring product subscriptions with flexible billing, integrated as a core plugin module (like Newsletter/Wishlist/Licensing).
+
+---
+
+## Module Architecture
+
+### Core Features
+- **Recurring billing**: Weekly, monthly, yearly, custom intervals
+- **Free trials**: X days free before billing starts
+- **Sign-up fees**: One-time fee on first subscription
+- **Automatic renewals**: Process payment on renewal date
+- **Manual renewal**: Allow customers to renew manually
+- **Proration**: Calculate prorated amounts on plan changes
+- **Pause/Resume**: Allow customers to pause subscriptions
+
+### Product Integration
+- Checkbox under "Additional Options": **Enable subscription for this product**
+- When enabled, show subscription settings:
+  - Billing period (weekly/monthly/yearly/custom)
+  - Billing interval (every X periods)
+  - Free trial days
+  - Sign-up fee
+  - Subscription length (0 = unlimited)
+- Variable products: Variation-level subscription settings (different durations/prices per variation)
+
+### Integration with Licensing
+- Licenses can be bound to subscriptions
+- When subscription is active → license is valid
+- When subscription expires/cancelled → license is revoked
+- Auto-renewal keeps license active
+
+---
+
+## Database Schema
+
+### Table: `woonoow_subscriptions`
+```sql
+CREATE TABLE woonoow_subscriptions (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  user_id BIGINT UNSIGNED NOT NULL,
+  order_id BIGINT UNSIGNED NOT NULL,
+  product_id BIGINT UNSIGNED NOT NULL,
+  variation_id BIGINT UNSIGNED DEFAULT NULL,
+  status ENUM('pending', 'active', 'on-hold', 'cancelled', 'expired', 'pending-cancel') DEFAULT 'pending',
+  billing_period ENUM('day', 'week', 'month', 'year') NOT NULL,
+  billing_interval INT UNSIGNED DEFAULT 1,
+  start_date DATETIME NOT NULL,
+  trial_end_date DATETIME DEFAULT NULL,
+  next_payment_date DATETIME DEFAULT NULL,
+  end_date DATETIME DEFAULT NULL,
+  last_payment_date DATETIME DEFAULT NULL,
+  payment_method VARCHAR(100) DEFAULT NULL,
+  payment_meta LONGTEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_user_id (user_id),
+  INDEX idx_order_id (order_id),
+  INDEX idx_status (status),
+  INDEX idx_next_payment (next_payment_date)
+);
+```
+
+### Table: `woonoow_subscription_orders`
+Links subscription to renewal orders:
+```sql
+CREATE TABLE woonoow_subscription_orders (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  subscription_id BIGINT UNSIGNED NOT NULL,
+  order_id BIGINT UNSIGNED NOT NULL,
+  order_type ENUM('parent', 'renewal', 'switch', 'resubscribe') DEFAULT 'renewal',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_subscription (subscription_id),
+  INDEX idx_order (order_id)
+);
+```
+
+---
+
+## Backend Structure
+
+```
+includes/Modules/Subscription/
+├── SubscriptionModule.php      # Bootstrap, hooks, product meta
+├── SubscriptionManager.php     # Core logic
+├── SubscriptionScheduler.php   # Cron jobs for renewals
+└── SubscriptionSettings.php    # Settings schema
+
+includes/Api/SubscriptionsController.php  # REST endpoints
+```
+
+### SubscriptionManager Methods
+```php
+- create($order, $product, $user)     # Create subscription from order
+- renew($subscription_id)              # Process renewal
+- cancel($subscription_id, $reason)    # Cancel subscription
+- pause($subscription_id)              # Pause subscription
+- resume($subscription_id)             # Resume paused subscription
+- switch($subscription_id, $new_product) # Switch plan
+- get_next_payment_date($subscription) # Calculate next date
+- process_renewal_payment($subscription) # Charge payment
+```
+
+### Cron Jobs
+- `woonoow_process_subscription_renewals`: Run daily, process due renewals
+- `woonoow_check_expired_subscriptions`: Mark expired subscriptions
+
+---
+
+## REST API Endpoints
+
+### Admin Endpoints
+```
+GET    /subscriptions              # List all subscriptions
+GET    /subscriptions/{id}         # Get subscription details
+PUT    /subscriptions/{id}         # Update subscription
+POST   /subscriptions/{id}/cancel  # Cancel subscription
+POST   /subscriptions/{id}/renew   # Force renewal
+```
+
+### Customer Endpoints
+```
+GET    /my-subscriptions           # Customer's subscriptions
+GET    /my-subscriptions/{id}      # Subscription detail
+POST   /my-subscriptions/{id}/cancel   # Request cancellation
+POST   /my-subscriptions/{id}/pause    # Pause subscription
+POST   /my-subscriptions/{id}/resume   # Resume subscription
+```
+
+---
+
+## Admin SPA
+
+### Subscriptions List (`/subscriptions`)
+- Table: ID, Customer, Product, Status, Next Payment, Actions
+- Filters: Status, Product, Date range
+- Actions: View, Cancel, Renew
+
+### Subscription Detail (`/subscriptions/:id`)
+- Subscription info card
+- Related orders list
+- Payment history
+- Action buttons: Cancel, Pause, Renew
+
+---
+
+## Customer SPA
+
+### My Subscriptions (`/my-account/subscriptions`)
+- List of active/past subscriptions
+- Status badges
+- Next payment info
+- Actions: Cancel, Pause, View
+
+### Subscription Detail
+- Product info
+- Billing schedule
+- Payment history
+- Management actions
+
+---
+
+## Settings Schema
+
+```php
+return [
+  'default_status' => 'active',
+  'button_text_subscribe' => 'Subscribe Now',
+  'button_text_renew' => 'Renew Subscription',
+  'allow_customer_cancel' => true,
+  'allow_customer_pause' => true,
+  'max_pause_count' => 3,
+  'renewal_retry_days' => [1, 3, 5],  // Retry failed payments
+  'expire_after_failed_attempts' => 3,
+  'send_renewal_reminder' => true,
+  'reminder_days_before' => 3,
+];
+```
+
+---
+
+## Implementation Priority
+1. Database tables and SubscriptionManager
+2. Product meta fields for subscription settings
+3. Order hook to create subscription
+4. Renewal cron job
+5. Admin SPA list/detail pages
+6. Customer SPA pages
+7. Integration with Licensing module

.agent/reports/email-notification-audit-2026-01-29.md

@@ -0,0 +1,228 @@
+# Email Notification System Audit
+
+**Date:** January 29, 2026  
+**Status:** ✅ System Architecture Sound, Minor Issues Identified
+
+---
+
+## Executive Summary
+
+The WooNooW email notification system is **well-architected** with proper async handling, template rendering, and event management. The main components work together correctly. However, some potential gaps and improvements were identified.
+
+---
+
+## System Architecture
+
+```mermaid
+flowchart TD
+    A[WooCommerce Hooks] --> B[EmailManager]
+    B --> C{Is WooNooW Mode?}
+    C -->|Yes| D[EmailRenderer]
+    C -->|No| E[WC Default Emails]
+    D --> F[TemplateProvider]
+    F --> G[Get Template]
+    G --> H[Replace Variables]
+    H --> I[Parse Markdown/Cards]
+    I --> J[wp_mail]
+    J --> K[WooEmailOverride Intercepts]
+    K --> L[MailQueue::enqueue]
+    L --> M[Action Scheduler]
+    M --> N[MailQueue::sendNow]
+    N --> O[Actual wp_mail]
+```
+
+---
+
+## Core Components
+
+| File | Purpose |
+|------|---------|
+| [EmailManager.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EmailManager.php) | Hooks WC order events, disables WC emails, routes to renderer |
+| [EmailRenderer.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EmailRenderer.php) | Renders templates, replaces variables, parses markdown |
+| [TemplateProvider.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/TemplateProvider.php) | Manages templates, defaults, variable definitions |
+| [EventRegistry.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EventRegistry.php) | Central registry of all notification events |
+| [NotificationManager.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/NotificationManager.php) | Validates settings, dispatches to channels |
+| [WooEmailOverride.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Mail/WooEmailOverride.php) | Intercepts wp_mail via `pre_wp_mail` filter |
+| [MailQueue.php](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Mail/MailQueue.php) | Async queue via Action Scheduler |
+
+---
+
+## Email Flow Trace
+
+### 1. Event Trigger
+- WooCommerce fires hooks like `woocommerce_order_status_pending_to_processing`
+- `EmailManager::init_hooks()` registers callbacks for these hooks
+
+### 2. EmailManager Processing
+```php
+// In EmailManager.php
+add_action('woocommerce_order_status_pending_to_processing', [$this, 'send_order_processing_email']);
+```
+- Checks if WooNooW mode enabled: `is_enabled()`
+- Checks if event enabled: `is_event_enabled()`
+- Calls `send_email($event_id, $recipient_type, $order)`
+
+### 3. Email Rendering
+- `EmailRenderer::render()` called
+- Gets template from `TemplateProvider::get_template()`
+- Gets variables from `get_variables()` (order, customer, product data)
+- Replaces `{variable}` placeholders
+- Parses `[card]` markdown syntax
+- Wraps in HTML template from `templates/emails/base.html`
+
+### 4. wp_mail Interception
+- `wp_mail()` is called with rendered HTML
+- `WooEmailOverride::interceptMail()` catches via `pre_wp_mail` filter
+- Returns `true` to short-circuit synchronous send
+
+### 5. Queue & Async Send
+- `MailQueue::enqueue()` stores payload in `wp_options` (temp)
+- Schedules `woonoow/mail/send` action via Action Scheduler
+- `MailQueue::sendNow()` runs asynchronously:
+  - Retrieves payload from options
+  - Disables `WooEmailOverride` to prevent loop
+  - Calls actual `wp_mail()`
+  - Deletes temp option
+
+---
+
+## Findings
+
+### ✅ Working Correctly
+
+1. **Async Email Queue**: Properly prevents timeout issues
+2. **Template System**: Variables replaced correctly
+3. **Event Registry**: Single source of truth
+4. **Subscription Events**: Registered via `woonoow_notification_events_registry` filter
+5. **Global Toggle**: WooNooW vs WooCommerce mode works
+6. **WC Email Disable**: Default emails properly disabled when WooNooW active
+
+### ⚠️ Potential Issues
+
+#### 1. Missing Subscription Variable Population in EmailRenderer
+**Location:** [EmailRenderer.php:147-299](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EmailRenderer.php#L147-L299)
+
+**Issue:** `get_variables()` handles `WC_Order`, `WC_Product`, `WC_Customer` but NOT subscription objects. Subscription notifications pass data like:
+```php
+$data = [
+    'subscription' => $subscription,  // Custom subscription object
+    'customer' => $user,
+    'product' => $product,
+    ...
+]
+```
+
+**Impact:** Subscription email variables like `{subscription_id}`, `{billing_period}`, `{next_payment_date}` may not be replaced.
+
+**Recommendation:** Add subscription variable population in `EmailRenderer::get_variables()`.
+
+---
+
+#### 2. EmailRenderer Type Check for Subscription
+**Location:** [EmailRenderer.php:121-137](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EmailRenderer.php#L121-L137)
+
+**Issue:** `get_recipient_email()` only checks for `WC_Order` and `WC_Customer`. For subscriptions, `$data` is an array, so recipient email extraction fails.
+
+**Impact:** Subscription emails may not find recipient email.
+
+**Recommendation:** Handle array data or subscription object in `get_recipient_email()`.
+
+---
+
+#### 3. SubscriptionModule Sends to NotificationManager, Not EmailManager
+**Location:** [SubscriptionModule.php:529-531](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionModule.php#L529-L531)
+
+**Code:**
+```php
+\WooNooW\Core\Notifications\NotificationManager::send($event_id, 'email', $data);
+```
+
+**Issue:** This goes through `NotificationManager`, which calls its own `send_email()` that uses `EmailRenderer::render()`. The `EmailRenderer::render()` method receives `$data['subscription']` but doesn't know how to handle it.
+
+**Impact:** Subscription email rendering may fail silently.
+
+---
+
+#### 4. No Error Logging in Email Rendering Failures
+**Location:** [EmailRenderer.php:48-57](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EmailRenderer.php#L48-L57)
+
+**Issue:** When `get_template_settings()` returns null or `get_recipient_email()` returns null, the function returns null silently with only an empty debug log statement.
+
+**Recommendation:** Add proper `error_log()` calls for debugging.
+
+---
+
+#### 5. Duplicate wp_mail Calls
+**Location:** Multiple places call `wp_mail()` directly:
+- `EmailManager::send_email()` (line 521)
+- `EmailManager::send_password_reset_email()` (line 406)
+- `NotificationManager::send_email()` (line 170)
+- `NotificationsController` test endpoint (line 1013)
+- `CampaignManager` (lines 275, 329)
+- `NewsletterController` (line 203)
+
+**Issue:** All these are intercepted by `WooEmailOverride`, which is correct. However, if `WooEmailOverride` is disabled (testing mode), all send synchronously.
+
+**Status:** Working as designed.
+
+---
+
+## Subscription Email Gap Analysis
+
+The subscription module has these events defined but needs variable population:
+
+| Event | Variables Needed |
+|-------|-----------------|
+| `subscription_pending_cancellation` | subscription_id, product_name, end_date |
+| `subscription_cancelled` | subscription_id, cancel_reason |
+| `subscription_expired` | subscription_id, product_name |
+| `subscription_paused` | subscription_id, product_name |
+| `subscription_resumed` | subscription_id, product_name |
+| `subscription_renewal_failed` | subscription_id, failed_count, payment_link |
+| `subscription_renewal_payment_due` | subscription_id, payment_link |
+| `subscription_renewal_reminder` | subscription_id, next_payment_date |
+
+**Required Fix:** Add subscription data handling to `EmailRenderer::get_variables()`.
+
+---
+
+## Recommendations
+
+### High Priority
+
+1. **Fix `EmailRenderer::get_variables()`** - Add handling for subscription data arrays
+2. **Fix `EmailRenderer::get_recipient_email()`** - Handle array data with customer key
+
+### Medium Priority
+
+3. **Add error logging** - Replace empty debug conditions with actual logging
+4. **Clean up debug conditions** - Many `if (defined('WP_DEBUG') && WP_DEBUG) {}` are empty
+
+### Low Priority
+
+5. **Consolidate email sending paths** - Consider routing all through one method
+6. **Add email send failure tracking** - Log failed sends for troubleshooting
+
+---
+
+## Test Scripts Available
+
+| Script | Purpose |
+|--------|---------|
+| `check-settings.php` | Diagnose notification settings |
+| `test-email-flow.php` | Interactive email testing dashboard |
+| `test-email-direct.php` | Direct wp_mail testing |
+
+---
+
+## Documentation
+
+Comprehensive docs exist:
+- [NOTIFICATION_SYSTEM.md](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/NOTIFICATION_SYSTEM.md)
+- [EMAIL_DEBUGGING_GUIDE.md](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/EMAIL_DEBUGGING_GUIDE.md)
+
+---
+
+## Conclusion
+
+The email notification system is **production-ready** for order-related notifications. The main gap is **subscription email variable population**, which requires updates to `EmailRenderer.php` to properly handle subscription data and extract variables.

.agent/reports/license-activation-research-2026-01-31.md

@@ -0,0 +1,391 @@
+# OAuth-Style License Activation Research Report
+
+**Date:** January 31, 2026  
+**Objective:** Design a strict license activation system requiring vendor site authentication
+
+---
+
+## Executive Summary
+
+After researching Elementor Pro, Tutor LMS, EDD Software Licensing, and industry standards, the **redirect-based OAuth-like activation flow** is the most secure and user-friendly approach. This pattern:
+- Prevents license key sharing by tying activation to user accounts
+- Provides better UX than manual key entry
+- Enables flexible license management
+- Creates an anti-piracy layer beyond just key validation
+
+---
+
+## Industry Analysis
+
+### 1. Elementor Pro
+
+| Aspect | Implementation |
+|--------|----------------|
+| **Flow** | "Connect & Activate" button → redirect to Elementor.com → login required → authorize connection → return to WP Admin |
+| **Why Listed** | Market leader with 5M+ users; sets the standard for premium plugin activation |
+| **Anti-Piracy** | Account-tied activation; no ability to share just a license key |
+| **Fallback** | Manual key entry via hidden URL parameter `?mode=manually` |
+
+**Key Pattern:** Elementor never shows the license key in the normal flow—users authenticate with their account, not a key.
+
+---
+
+### 2. Tutor LMS (Themeum)
+
+| Aspect | Implementation |
+|--------|----------------|
+| **Flow** | License settings → Enter key → "Connect" button → redirect to Themeum → login → confirm connection |
+| **Why Listed** | Popular LMS plugin; hybrid approach (key + account verification) |
+| **Anti-Piracy** | License keys tied to specific domains registered in user account |
+| **License Display** | Keys visible in account dashboard for copy-paste |
+
+**Key Pattern:** Requires domain registration in vendor account before activation works.
+
+---
+
+### 3. Easy Digital Downloads (EDD) Software Licensing
+
+| Aspect | Implementation |
+|--------|----------------|
+| **Flow** | API-based: plugin sends key + site URL to vendor → server validates → returns activation status |
+| **Why Listed** | Powers many WordPress plugin vendors (WPForms, MonsterInsights, etc.) |
+| **Anti-Piracy** | Activation limits (e.g., 1 site, 5 sites, unlimited); site URL tracking |
+| **Management** | Customer can manage activations in their EDD account |
+
+**Key Pattern:** Traditional key-based but with strict activation limits and site tracking.
+
+---
+
+### 4. WooCommerce Software License Manager
+
+| Aspect | Implementation |
+|--------|----------------|
+| **Flow** | REST API with key + secret authentication |
+| **Why Listed** | Common for WooCommerce-based vendors |
+| **Anti-Piracy** | API-key authentication; activation records |
+
+**Key Pattern:** Programmatic API access, less user-facing UX focus.
+
+---
+
+## Best Practices Identified
+
+### Anti-Piracy Measures
+
+| Measure | Effectiveness | UX Impact |
+|---------|---------------|-----------|
+| **Account authentication required** | ★★★★★ | Minor inconvenience |
+| **Activation limits per license** | ★★★★☆ | None |
+| **Domain/URL binding** | ★★★★☆ | None |
+| **Tying updates/support to valid license** | ★★★★★ | Incentivizes purchase |
+| **Periodic license re-validation** | ★★★☆☆ | Can cause issues |
+| **Encrypted API communication (HTTPS)** | ★★★★★ | None |
+
+### UX Considerations
+
+| Consideration | Priority |
+|---------------|----------|
+| One-click activation (minimal friction) | High |
+| Clear error messages | High |
+| License status visibility in WP Admin | Medium |
+| Easy deactivation for site migrations | High |
+| Fallback manual activation | Medium |
+
+---
+
+## Security Comparison
+
+| Method | Piracy Resistance | Implementation Complexity |
+|--------|-------------------|---------------------------|
+| **Simple key validation** | Low | Simple |
+| **Key + site URL binding** | Medium | Medium |
+| **Key + activation limits** | Medium-High | Medium |
+| **OAuth redirect + account tie** | High | Complex |
+| **OAuth + key + activation limits** | Very High | Complex |
+
+---
+
+## Your Proposed Flow Analysis
+
+### Original Flow Points
+
+1. User navigates to license page → clicks [ACTIVATE]
+2. Redirect to vendor site (licensing.woonoow.com or similar)
+3. Vendor site: login required
+4. Vendor shows licenses for user's account, filtered by product
+5. User selects license to connect
+6. Click "Connect This Site"
+7. Return to `return_url` after short delay
+
+### Identified Gaps
+
+| Gap | Risk | Solution |
+|-----|------|----------|
+| No state parameter | CSRF attack possible | Add signed `state` token |
+| No nonce verification | Replay attacks | Include one-time nonce |
+| Return URL manipulation | Redirect hijacking | Validate return URL on server |
+| No deactivation flow | User can't migrate | Add disconnect button |
+
+---
+
+## Perfected Implementation Plan
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        WP ADMIN (Client Site)                   │
+├─────────────────────────────────────────────────────────────────┤
+│  Settings → License                                              │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  Status: Not Connected                                    │   │
+│  │  [🔗 Connect & Activate]                                  │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────┘
+                        │
+                        ▼ Redirect with signed params
+┌──────────────────────────────────────────────────────────────────┐
+│                    VENDOR SITE (License Server)                  │
+├──────────────────────────────────────────────────────────────────┤
+│  /license/connect?                                               │
+│    product_id=woonoow-pro&                                       │
+│    site_url=https://customer-site.com&                           │
+│    return_url=https://customer-site.com/wp-admin/...&            │
+│    state=<signed_token>&                                         │
+│    nonce=<one_time_code>                                         │
+├──────────────────────────────────────────────────────────────────┤
+│  1. Force login if not authenticated                             │
+│  2. Show licenses owned by user for this product                 │
+│  3. User selects: "Pro License (3/5 sites used)"                 │
+│  4. Click [Connect This Site]                                    │
+│  5. Server records activation                                    │
+│  6. Redirect back with activation token                          │
+└──────────────────────────────────────────────────────────────────┘
+                        │
+                        ▼ Callback with activation token
+┌──────────────────────────────────────────────────────────────────┐
+│                        WP ADMIN (Client Site)                    │
+├──────────────────────────────────────────────────────────────────┤
+│  Callback handler:                                               │
+│  1. Verify state matches stored value                            │
+│  2. Exchange activation_token for license_key via API            │
+│  3. Store license_key securely                                   │
+│  4. Show success: "License activated successfully!"              │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  Status: ✅ Active                                        │   │
+│  │  License: Pro (expires Dec 31, 2026)                      │   │
+│  │  Sites: 4/5 activated                                     │   │
+│  │  [Disconnect]                                             │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Detailed Flow
+
+#### Phase 1: Initiation (Client Plugin)
+
+```php
+// User clicks "Connect & Activate"
+$params = [
+    'product_id'  => 'woonoow-pro',
+    'site_url'    => home_url(),
+    'return_url'  => admin_url('admin.php?page=woonoow-license&action=callback'),
+    'nonce'       => wp_create_nonce('woonoow_license_connect'),
+    'state'       => $this->generate_state_token(), // Signed, stored in transient
+    'timestamp'   => time(),
+];
+
+$redirect_url = 'https://licensing.woonoow.com/connect?' . http_build_query($params);
+wp_redirect($redirect_url);
+```
+
+#### Phase 2: Authentication (Vendor Server)
+
+1. **Login Gate**: If user not logged in → redirect to login with `?redirect=/connect?...`
+2. **Validate Request**: Check `state`, `nonce`, `timestamp` (reject if >10 min old)
+3. **Fetch User Licenses**: Query licenses owned by authenticated user for `product_id`
+4. **Display License Selector**:
+   ```
+   ┌─────────────────────────────────────────────────┐
+   │  Connect site-name.com to your license          │
+   ├─────────────────────────────────────────────────┤
+   │  ○ WooNooW Pro - Agency (Unlimited sites)       │
+   │  ● WooNooW Pro - Business (3/5 sites) ←selected │
+   │  ○ WooNooW Pro - Personal (1/1 sites) [FULL]    │
+   ├─────────────────────────────────────────────────┤
+   │  [Cancel]              [Connect This Site]      │
+   └─────────────────────────────────────────────────┘
+   ```
+5. **Record Activation**: Insert into `license_activations` table
+6. **Generate Callback**: Redirect to `return_url` with:
+   - `activation_token`: Short-lived token (5 min expiry)
+   - `state`: Original state for verification
+
+#### Phase 3: Callback (Client Plugin)
+
+```php
+// Handle callback
+$activation_token = sanitize_text_field($_GET['activation_token']);
+$state = sanitize_text_field($_GET['state']);
+
+// 1. Verify state matches stored transient
+if (!$this->verify_state_token($state)) {
+    wp_die('Invalid state. Possible CSRF attack.');
+}
+
+// 2. Exchange token for license details via secure API
+$response = wp_remote_post('https://licensing.woonoow.com/api/v1/token/exchange', [
+    'body' => [
+        'activation_token' => $activation_token,
+        'site_url' => home_url(),
+    ],
+]);
+
+// 3. Store license data
+$license_data = json_decode(wp_remote_retrieve_body($response), true);
+update_option('woonoow_license', [
+    'key'        => $license_data['license_key'],
+    'status'     => 'active',
+    'expires'    => $license_data['expires_at'],
+    'tier'       => $license_data['tier'],
+    'sites_used' => $license_data['sites_used'],
+    'sites_max'  => $license_data['sites_max'],
+]);
+
+// 4. Redirect with success
+wp_redirect(admin_url('admin.php?page=woonoow-license&activated=1'));
+```
+
+---
+
+### Security Parameters
+
+| Parameter | Purpose | Implementation |
+|-----------|---------|----------------|
+| `state` | CSRF protection | HMAC-signed, stored in transient, expires 10 min |
+| `nonce` | Replay prevention | One-time use, verified on server |
+| `timestamp` | Request freshness | Reject requests >10 min old |
+| `activation_token` | Secure exchange | Short-lived (5 min), single-use |
+| `site_url` | Domain binding | Stored with activation record |
+
+---
+
+### Database Schema (Vendor Server)
+
+```sql
+CREATE TABLE license_activations (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    license_id BIGINT NOT NULL,
+    site_url VARCHAR(255) NOT NULL,
+    activation_token VARCHAR(64),
+    token_expires_at DATETIME,
+    activated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    last_check DATETIME,
+    status ENUM('active', 'deactivated') DEFAULT 'active',
+    metadata JSON,
+    UNIQUE KEY unique_license_site (license_id, site_url),
+    FOREIGN KEY (license_id) REFERENCES licenses(id)
+);
+```
+
+---
+
+### Deactivation Flow
+
+```
+Client: [Disconnect] button clicked
+  → POST /api/v1/license/deactivate
+  → Body: { license_key, site_url }
+  → Server removes activation record
+  → Client clears stored license
+  → Show "Disconnected" status
+```
+
+---
+
+### Periodic Validation
+
+```php
+// Cron check every 24 hours
+add_action('woonoow_daily_license_check', function() {
+    $license = get_option('woonoow_license');
+    if (!$license) return;
+    
+    $response = wp_remote_post('https://licensing.woonoow.com/api/v1/license/validate', [
+        'body' => [
+            'license_key' => $license['key'],
+            'site_url' => home_url(),
+        ],
+    ]);
+    
+    $data = json_decode(wp_remote_retrieve_body($response), true);
+    
+    if ($data['status'] !== 'active') {
+        update_option('woonoow_license', ['status' => 'invalid']);
+        // Optionally disable premium features
+    }
+});
+```
+
+---
+
+## API Endpoints (Vendor Server)
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/connect` | GET | OAuth-like authorization page |
+| `/api/v1/token/exchange` | POST | Exchange activation token for license |
+| `/api/v1/license/validate` | POST | Validate license status |
+| `/api/v1/license/deactivate` | POST | Remove site activation |
+| `/api/v1/license/info` | GET | Get license details |
+
+---
+
+## Comparison: Your Flow vs. Perfected
+
+| Aspect | Your Original | Perfected |
+|--------|---------------|-----------|
+| CSRF Protection | ❌ None | ✅ State token |
+| Replay Prevention | ❌ None | ✅ Nonce + timestamp |
+| Token Exchange | ❌ Direct return | ✅ Secure exchange |
+| Return URL Security | ❌ Unvalidated | ✅ Server whitelist |
+| Deactivation | ❌ Not mentioned | ✅ Full flow |
+| Periodic Validation | ❌ Not mentioned | ✅ Daily cron |
+| Fallback | ❌ None | ✅ Manual key entry |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Server-Side (Licensing Portal)
+1. Create `/connect` authorization page
+2. Build license selection UI
+3. Implement activation recording
+4. Create token exchange API
+
+### Phase 2: Client-Side (WooNooW Plugin)
+1. Create Settings → License admin page
+2. Implement connect redirect
+3. Handle callback and token exchange
+4. Store license securely
+5. Add disconnect functionality
+
+### Phase 3: Validation & Updates
+1. Implement periodic license checks
+2. Gate premium features behind valid license
+3. Integrate with plugin update checker
+
+---
+
+## References
+
+| Source | Relevance |
+|--------|-----------|
+| Elementor Pro Activation | Primary reference for UX flow |
+| Tutor LMS / Themeum | Hybrid key+account approach |
+| OAuth 2.0 Authorization Code Flow | Security pattern basis |
+| EDD Software Licensing | Activation limits pattern |
+| OWASP API Security | State/nonce implementation |

.agent/reports/newsletter-module-audit-2026-02-01.md

@@ -0,0 +1,212 @@
+# Newsletter Module Audit Report
+
+**Date**: 2026-02-01  
+**Auditor**: Antigravity AI  
+**Scope**: Full trace of Newsletter module including broadcast, subscribers, templates, events, and multi-channel support
+
+---
+
+## 1. Module Architecture Overview
+
+```mermaid
+flowchart TD
+    subgraph Frontend
+        NF[NewsletterForm.tsx]
+    end
+    
+    subgraph API
+        NC[NewsletterController.php]
+        CC[CampaignsController - via CampaignManager]
+    end
+    
+    subgraph Core
+        CM[CampaignManager.php]
+        NS[NewsletterSettings.php]
+    end
+    
+    subgraph Notifications
+        ER[EventRegistry.php]
+        NM[NotificationManager.php]
+        ER --> NM
+    end
+    
+    subgraph Admin SPA
+        SUB[Subscribers.tsx]
+        CAMP[Campaigns.tsx]
+    end
+    
+    NF -->|POST /subscribe| NC
+    NC -->|triggers| ER
+    CM -->|uses| NM
+    SUB -->|GET /subscribers| NC
+    CAMP -->|CRUD| CM
+```
+
+---
+
+## 2. Components Traced
+
+| Component | File | Status |
+|-----------|------|--------|
+| Subscriber API | `NewsletterController.php` | ✅ Working |
+| Subscriber UI | `Subscribers.tsx` | ✅ Working |
+| Campaign Manager | `CampaignManager.php` | ✅ Built (CPT-based) |
+| Campaign UI | `Campaigns.tsx` | ✅ Working |
+| Settings Schema | `NewsletterSettings.php` | ✅ Complete |
+| Frontend Form | `NewsletterForm.tsx` | ⚠️ Missing GDPR |
+| Unsubscribe | Token-based URL | ✅ Secure |
+| Email Events | `EventRegistry.php` | ✅ 3 events registered |
+
+---
+
+## 3. Defects Found
+
+### 🔴 Critical
+
+#### 3.1 Double Opt-in NOT Implemented
+**Location**: `NewsletterController.php` (Line 130-189)  
+**Issue**: `NewsletterSettings.php` defines a `double_opt_in` toggle (Line 46-51), but the subscribe function **ignores it completely**.  
+**Impact**: GDPR non-compliance in EU regions  
+**Expected**: When enabled, subscribers should receive confirmation email before being marked active
+
+#### 3.2 Dead Code: `send_welcome_email()`
+**Location**: `NewsletterController.php` (Lines 192-203)  
+**Issue**: This method is **never called**. Welcome emails are now sent via the notification system (`woonoow/notification/event`).  
+**Impact**: Code bloat, potential confusion  
+**Recommendation**: Delete this dead method
+
+---
+
+### 🟠 High Priority
+
+#### 3.3 No Multi-Channel Support (WhatsApp/Telegram/SMS)
+**Issue**: Only `email` and `push` channels exist in `NotificationManager.php`  
+**Impact**: Users cannot broadcast newsletters via WhatsApp, Telegram, or SMS  
+**Current State**:
+- `allowed_platforms` in `NotificationsController.php` (Line 832) lists `telegram`, `whatsapp` for **social links** (not messaging)
+- No actual message delivery integration exists
+
+**Recommendation**: Implement channel bridge pattern for:
+1. **WhatsApp Business API** (or Twilio WhatsApp)
+2. **Telegram Bot API**
+3. **SMS Gateway** (Twilio, Vonage, etc.)
+
+#### 3.4 Subscriber Storage Not Scalable
+**Location**: `NewsletterController.php` (Line 141)  
+**Issue**: Subscribers stored in `wp_options` as serialized array  
+**Impact**: Performance degrades with 1000+ subscribers (Options table not designed for large arrays)  
+**Note**: `NEWSLETTER_CAMPAIGN_PLAN.md` mentions custom table but `wp_woonoow_subscribers` table is **not created**
+
+**Recommendation**: 
+```php
+// Create migration for custom table
+CREATE TABLE wp_woonoow_subscribers (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  email VARCHAR(255) NOT NULL UNIQUE,
+  user_id BIGINT UNSIGNED NULL,
+  status ENUM('pending', 'active', 'unsubscribed') DEFAULT 'pending',
+  consent TINYINT(1) DEFAULT 0,
+  subscribed_at DATETIME,
+  unsubscribed_at DATETIME NULL,
+  ip_address VARCHAR(45),
+  INDEX idx_status (status),
+  INDEX idx_email (email)
+);
+```
+
+---
+
+### 🟡 Medium Priority
+
+#### 3.5 GDPR Consent Checkbox Missing in Frontend
+**Location**: `NewsletterForm.tsx`  
+**Issue**: Settings schema has `gdpr_consent` and `consent_text` fields, but the frontend form doesn't render this checkbox  
+**Impact**: GDPR non-compliance
+
+**Recommendation**: Add consent checkbox:
+```tsx
+{settings.gdpr_consent && (
+  <label className="flex items-start gap-2">
+    <input type="checkbox" required />
+    <span className="text-xs">{settings.consent_text}</span>
+  </label>
+)}
+```
+
+#### 3.6 No Audience Segmentation
+**Issue**: All campaigns go to ALL active subscribers  
+**File**: `CampaignManager.php` (Line 393-410)  
+**Impact**: Cannot target specific user groups (e.g., "Subscribed in last 30 days", "WP Users only")
+
+**Recommendation**: Add filter options to `get_subscribers()`:
+- By date range
+- By user_id (registered vs guest)
+- By custom tags (future feature)
+
+#### 3.7 No Open/Click Tracking
+**Issue**: No analytics for campaign performance  
+**Impact**: Cannot measure engagement or ROI
+
+**Recommendation** (Phase 3):
+- Add tracking pixel for opens
+- Wrap links for click tracking
+- Store in `wp_woonoow_campaign_events` table
+
+---
+
+## 4. Gaps Between Plan and Implementation
+
+| Feature | Plan Status | Implementation Status |
+|---------|-------------|----------------------|
+| Subscribers Table | "Create migration" | ❌ Not created |
+| Double Opt-in | Schema defined | ❌ Not enforced |
+| Campaign Scheduling | Cron registered | ✅ Working |
+| GDPR Consent | Settings exist | ❌ UI not integrated |
+| Multi-channel | Not planned | ❌ Not implemented |
+| A/B Testing | Phase 3 | ❌ Not started |
+| Analytics | Phase 3 | ❌ Not started |
+
+---
+
+## 5. Recommendations Summary
+
+### Immediate Actions (Bug Fixes)
+1. ~~Delete~~ or implement `send_welcome_email()` dead code
+2. Connect `double_opt_in` setting to subscribe flow
+3. Add GDPR checkbox to `NewsletterForm.tsx`
+
+### Short-term (1-2 weeks)
+4. Create `wp_woonoow_subscribers` table for scalability
+5. Add audience segmentation to campaign targeting
+
+### Medium-term (Future Phases)
+6. Implement WhatsApp/Telegram channel bridges
+7. Add open/click tracking for analytics
+
+---
+
+## 6. Security Audit
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Unsubscribe Token | ✅ Secure | HMAC-SHA256 with auth salt |
+| Email Validation | ✅ Validated | `is_email()` + custom validation |
+| CSRF Protection | ✅ Via REST nonce | API uses WP nonces |
+| IP Logging | ✅ Stored | For GDPR data export if needed |
+| Rate Limiting | ⚠️ None | Could be abused for spam subscriptions |
+
+**Recommendation**: Add rate limiting to `/newsletter/subscribe` endpoint (e.g., 5 requests per IP per hour)
+
+---
+
+## 7. Conclusion
+
+The Newsletter module is **functionally complete** for basic use cases. The campaign system is well-architected using WordPress Custom Post Types, and the integration with the notification system is clean.
+
+**Critical gaps** exist around GDPR compliance (double opt-in, consent checkbox) and scalability (options-based storage). Multi-channel support (WhatsApp/Telegram) is **not implemented** and would require significant new development.
+
+**Priority Order**:
+1. GDPR fixes (double opt-in + consent checkbox)
+2. Custom subscribers table
+3. Audience segmentation
+4. Multi-channel bridges (optional, significant scope)

.agent/reports/product-flow-audit-2026-01-29.md

@@ -0,0 +1,212 @@
+# Product Create/Update Flow Audit Report
+
+**Date:** 2026-01-29  
+**Scope:** Full trace of product creation, update, SKU validation, variation handling, virtual product setting, and customer-facing add-to-cart
+
+---
+
+## Executive Summary
+
+**Total Issues Found: 4**
+- **CRITICAL:** 2
+- **WARNING:** 1
+- **INFO:** 1
+
+---
+
+## Critical Issues
+
+### 🔴 Issue #1: SKU Validation Blocks Variation Updates
+
+**Severity:** CRITICAL  
+**Location:** [ProductsController.php#L1009](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/ProductsController.php#L1009)
+
+**Problem:**
+When updating a variable product, the `save_product_variations` method sets SKU unconditionally:
+```php
+if (isset($var_data['sku'])) $variation->set_sku($var_data['sku']);
+```
+
+WooCommerce validates that SKU must be unique across all products. When updating a variation that already has that SKU, WooCommerce throws an exception because it sees the SKU as a duplicate.
+
+**Root Cause:**
+WooCommerce's `set_sku()` method checks for uniqueness but doesn't know the variation already owns that SKU during the update.
+
+**Fix Required:**
+Before setting SKU, check if the new SKU is the same as the current SKU:
+```php
+if (isset($var_data['sku'])) {
+    $current_sku = $variation->get_sku();
+    $new_sku = $var_data['sku'];
+    // Only set if different (to avoid WC duplicate check issue)
+    if ($current_sku !== $new_sku) {
+        $variation->set_sku($new_sku);
+    }
+}
+```
+
+---
+
+### 🔴 Issue #2: Variation Selection Fails (Attribute Format Mismatch)
+
+**Severity:** CRITICAL  
+**Location:** 
+- Backend: [ShopController.php#L363-365](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Frontend/ShopController.php#L363)
+- Frontend: [Product/index.tsx#L97-127](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/Product/index.tsx#L97)
+
+**Problem:**
+"Please select all product options" error appears even when a variation is selected.
+
+**Root Cause:**
+Format mismatch between backend API and frontend matching logic:
+
+| Source | Format | Example |
+|--------|--------|---------|
+| API `variations.attributes` | `attribute_pa_color: "red"` | Lowercase, prefixed |
+| API `attributes` | `name: "Color"` | Human-readable |
+| Frontend `selectedAttributes` | `Color: "Red"` | Human-readable, case preserved |
+
+The matching logic at lines 100-120 has complex normalization but may fail at edge cases:
+- Taxonomy attributes use `pa_` prefix (e.g., `attribute_pa_color`)
+- Custom attributes use direct prefix (e.g., `attribute_size`)
+- The comparison normalizes both sides but attribute names in `selectedAttributes` are human-readable labels
+
+**Fix Required:**
+Improve variation matching by normalizing attribute names consistently:
+
+```typescript
+// In find matching variation logic:
+const variation = (product.variations as any[]).find(v => {
+  return Object.entries(selectedAttributes).every(([attrName, attrValue]) => {
+    const normalizedAttrName = attrName.toLowerCase();
+    const normalizedValue = attrValue.toLowerCase();
+    
+    // Try all possible attribute key formats
+    const possibleKeys = [
+      `attribute_${normalizedAttrName}`,
+      `attribute_pa_${normalizedAttrName}`,
+      normalizedAttrName
+    ];
+    
+    for (const key of possibleKeys) {
+      if (key in v.attributes) {
+        return v.attributes[key].toLowerCase() === normalizedValue;
+      }
+    }
+    return false;
+  });
+});
+```
+
+---
+
+## Warning Issues
+
+### 🟡 Issue #3: Virtual Product Setting May Not Persist for Variable Products
+
+**Severity:** WARNING  
+**Location:** [ProductsController.php#L496-498](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/ProductsController.php#L496)
+
+**Problem:**
+User reports cannot change product to virtual. Investigation shows:
+- Admin-SPA correctly sends `virtual: true` in payload
+- Backend `update_product` correctly calls `$product->set_virtual()`
+- However, for variable products, virtual status may need to be set on each variation
+
+**Observation:**
+The backend code at lines 496-498 handles virtual correctly:
+```php
+if (isset($data['virtual'])) {
+    $product->set_virtual((bool) $data['virtual']);
+}
+```
+
+**Potential Issue:**
+WooCommerce may ignore parent product's virtual flag for variable products. Each variation may need to be set as virtual individually.
+
+**Fix Required:**
+When saving variations, also propagate virtual flag:
+```php
+// In save_product_variations, after setting other fields:
+if ($product->is_virtual()) {
+    $variation->set_virtual(true);
+}
+```
+
+---
+
+## Info Issues
+
+### ℹ️ Issue #4: Missing Error Handling in Add-to-Cart Backend
+
+**Severity:** INFO  
+**Location:** [CartController.php#L202-203](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/Controllers/CartController.php#L202)
+
+**Observation:**
+When `add_to_cart()` returns false, the error message is generic:
+```php
+if (!$cart_item_key) {
+    return new WP_Error('add_to_cart_failed', 'Failed to add product to cart', ['status' => 400]);
+}
+```
+
+WooCommerce may have more specific notices in `wc_notice` stack that could provide better error messages.
+
+**Enhancement:**
+```php
+if (!$cart_item_key) {
+    $notices = wc_get_notices('error');
+    $message = !empty($notices) ? $notices[0]['notice'] : 'Failed to add product to cart';
+    wc_clear_notices();
+    return new WP_Error('add_to_cart_failed', $message, ['status' => 400]);
+}
+```
+
+---
+
+## Code Flow Summary
+
+### Product Update Flow
+```mermaid
+sequenceDiagram
+    Admin SPA->>ProductsController: PUT /products/{id}
+    ProductsController->>WC_Product: set_name, set_sku, etc.
+    ProductsController->>WC_Product: set_virtual, set_downloadable
+    ProductsController->>ProductsController: save_product_variations()
+    ProductsController->>WC_Product_Variation: set_sku (BUG: no duplicate check)
+    WC_Product_Variation-->>WooCommerce: validate_sku()
+    WooCommerce-->>ProductsController: Exception (duplicate SKU)
+```
+
+### Add-to-Cart Flow
+```mermaid
+sequenceDiagram
+    Customer SPA->>Product Page: Select variation
+    Product Page->>useState: selectedAttributes = {Color: "Red"}
+    Product Page->>useEffect: Find matching variation
+    Note right of Product Page: Mismatch: API has attribute_pa_color
+    Product Page-->>useState: selectedVariation = null
+    Customer->>Product Page: Click Add to Cart
+    Product Page->>Customer: "Please select all product options"
+```
+
+---
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `ProductsController.php` | Fix SKU check in `save_product_variations` |
+| `Product/index.tsx` | Fix variation matching logic |
+| `ProductsController.php` | Propagate virtual to variations |
+| `CartController.php` | (Optional) Improve error messages |
+
+---
+
+## Verification Plan
+
+After fixes:
+1. Create a variable product with SKU on variations
+2. Edit the product without changing SKU → should save successfully
+3. Add products to cart → verify variation selection works
+4. Test virtual product setting on simple and variable products

.agent/reports/subscription-flow-audit-2026-01-29.md

@@ -0,0 +1,173 @@
+# Subscription Module Comprehensive Audit Report
+
+**Date:** 2026-01-29  
+**Scope:** Full module trace including orders, notifications, permissions, payment gateway integration, auto/manual renewal, early renewal
+
+---
+
+## Executive Summary
+
+I performed a comprehensive audit of the subscription module and implemented fixes for all Critical and Warning issues.
+
+**Total Issues Found: 11**
+- **CRITICAL:** 2 ✅ FIXED
+- **WARNING:** 5 ✅ FIXED
+- **INFO:** 4 (No action required)
+
+---
+
+## Fixes Implemented
+
+### ✅ Critical Issue #1: `handle_renewal_success` Now Sets Status to Active
+
+**File:** [SubscriptionManager.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L708-L719)
+
+**Change:**
+```diff
+$wpdb->update(
+    self::$table_subscriptions,
+    [
++       'status' => 'active',
+        'next_payment_date' => $next_payment,
+        'last_payment_date' => current_time('mysql'),
+        'failed_payment_count' => 0,
+    ],
+    ['id' => $subscription_id],
+-   ['%s', '%s', '%d'],
++   ['%s', '%s', '%s', '%d'],
+    ['%d']
+);
+```
+
+---
+
+### ✅ Critical Issue #2: Added Renewal Reminder Handler
+
+**File:** [SubscriptionModule.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionModule.php)
+
+**Changes:**
+1. Added action hook registration:
+```php
+add_action('woonoow/subscription/renewal_reminder', [__CLASS__, 'on_renewal_reminder'], 10, 1);
+```
+
+2. Added event registration:
+```php
+$events['subscription_renewal_reminder'] = [
+    'id' => 'subscription_renewal_reminder',
+    'label' => __('Subscription Renewal Reminder', 'woonoow'),
+    // ...
+];
+```
+
+3. Added handler method:
+```php
+public static function on_renewal_reminder($subscription)
+{
+    if (!$subscription || !isset($subscription->id)) {
+        return;
+    }
+    self::send_subscription_notification('subscription_renewal_reminder', $subscription->id);
+}
+```
+
+---
+
+### ✅ Warning Issue #3: Added Duplicate Renewal Order Prevention
+
+**File:** [SubscriptionManager.php::renew](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L511-L535)
+
+**Change:** Before creating a new renewal order, the system now checks for existing pending orders:
+```php
+$existing_pending = $wpdb->get_row($wpdb->prepare(
+    "SELECT so.order_id FROM ... WHERE ... AND p.post_status IN ('wc-pending', 'pending', 'wc-on-hold', 'on-hold')",
+    $subscription_id
+));
+
+if ($existing_pending) {
+    return ['success' => true, 'order_id' => (int) $existing_pending->order_id, 'status' => 'existing'];
+}
+```
+
+Also allowed `on-hold` subscriptions to renew (in addition to `active`).
+
+---
+
+### ✅ Warning Issue #4: Removed Duplicate Route Registration
+
+**File:** [CheckoutController.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/CheckoutController.php)
+
+**Change:** Removed duplicate `/checkout/pay-order/{id}` route registration (was registered twice).
+
+---
+
+### ✅ Warning Issue #5: Added `has_settings` to Subscription Module
+
+**File:** [ModuleRegistry.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/ModuleRegistry.php#L64-L78)
+
+**Change:**
+```diff
+'subscription' => [
+    // ...
+    'default_enabled' => false,
++   'has_settings' => true,
+    'features' => [...],
+],
+```
+
+Now subscription settings will appear in Admin SPA > Settings > Modules > Subscription.
+
+---
+
+### ✅ Issue #10: Replaced Transient Tracking with Database Column
+
+**Files:**
+- [SubscriptionManager.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php) - Added `reminder_sent_at` column
+- [SubscriptionScheduler.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionScheduler.php) - Updated to use database column
+
+**Changes:**
+1. Added column to table schema:
+```sql
+reminder_sent_at DATETIME DEFAULT NULL,
+```
+
+2. Updated scheduler logic:
+```php
+// Query now includes:
+AND (reminder_sent_at IS NULL OR reminder_sent_at < last_payment_date OR ...)
+
+// After sending:
+$wpdb->update($table, ['reminder_sent_at' => current_time('mysql')], ...);
+```
+
+---
+
+## Remaining INFO Issues (No Action Required)
+
+| # | Issue | Status |
+|---|-------|--------|
+| 6 | Payment gateway integration is placeholder only | Phase 2 - needs separate adapter classes |
+| 7 | ThankYou page doesn't display subscription info | Enhancement for future |
+| 9 | "Renew Early" only for active subscriptions | Confirmed as acceptable UX |
+| 11 | API permissions correctly configured | Verified ✓ |
+
+---
+
+## Summary of Files Modified
+
+| File | Changes |
+|------|---------|
+| `SubscriptionManager.php` | • Fixed `handle_renewal_success` to set status<br>• Added duplicate order prevention<br>• Added `reminder_sent_at` column |
+| `SubscriptionModule.php` | • Added renewal reminder hook<br>• Added event registration<br>• Added handler method |
+| `SubscriptionScheduler.php` | • Replaced transient tracking with database column |
+| `CheckoutController.php` | • Removed duplicate route registration |
+| `ModuleRegistry.php` | • Added `has_settings => true` for subscription |
+
+---
+
+## Database Migration Note
+
+> [!IMPORTANT]
+> The `reminder_sent_at` column has been added to the subscriptions table schema. Since `dbDelta()` is used, it should be added automatically on next module re-enable or table check. However, for existing installations, you may need to:
+> 1. Disable and re-enable the Subscription module in Admin SPA, OR
+> 2. Run: `ALTER TABLE wp_woonoow_subscriptions ADD COLUMN reminder_sent_at DATETIME DEFAULT NULL;`

ADDON_BRIDGE_PATTERN.md

@@ -1,325 +0,0 @@
-# Addon Bridge Pattern - Rajaongkir Example
-
-## Philosophy
-
-**WooNooW Core = Zero Addon Dependencies**
-
-We don't integrate specific addons into WooNooW core. Instead, we provide:
-1. **Hook system** for addons to extend functionality
-2. **Bridge snippets** for compatibility with existing plugins
-3. **Addon development guide** for building proper WooNooW addons
-
----
-
-## Problem: Rajaongkir Plugin
-
-Rajaongkir is a WooCommerce plugin that:
-- Removes standard address fields (city, state)
-- Adds custom destination dropdown
-- Stores data in WooCommerce session
-- Works on WooCommerce checkout page
-
-**It doesn't work with WooNooW OrderForm because:**
-- OrderForm uses standard WooCommerce fields
-- Rajaongkir expects session-based destination
-- No destination = No shipping calculation
-
----
-
-## Solution: Bridge Snippet (Not Core Integration!)
-
-### Option A: Standalone Bridge Plugin
-
-Create a tiny bridge plugin that makes Rajaongkir work with WooNooW:
-
-```php
-<?php
-/**
- * Plugin Name: WooNooW Rajaongkir Bridge
- * Description: Makes Rajaongkir plugin work with WooNooW OrderForm
- * Version: 1.0.0
- * Requires: WooNooW, Rajaongkir Official
- */
-
-// Hook into WooNooW's shipping calculation
-add_filter('woonoow_before_shipping_calculate', function($shipping_data) {
-    // If Indonesia and has city, convert to Rajaongkir destination
-    if ($shipping_data['country'] === 'ID' && !empty($shipping_data['city'])) {
-        // Search Rajaongkir API for destination
-        $api = Cekongkir_API::get_instance();
-        $results = $api->search_destination_api($shipping_data['city']);
-        
-        if (!empty($results[0])) {
-            // Set Rajaongkir session data
-            WC()->session->set('selected_destination_id', $results[0]['id']);
-            WC()->session->set('selected_destination_label', $results[0]['text']);
-        }
-    }
-    
-    return $shipping_data;
-});
-
-// Add Rajaongkir destination field to OrderForm via hook system
-add_action('wp_enqueue_scripts', function() {
-    if (!is_admin()) return;
-    
-    wp_enqueue_script(
-        'woonoow-rajaongkir-bridge',
-        plugin_dir_url(__FILE__) . 'dist/bridge.js',
-        ['woonoow-admin'],
-        '1.0.0',
-        true
-    );
-});
-```
-
-**Frontend (bridge.js):**
-
-```typescript
-import { addonLoader, addFilter } from '@woonoow/hooks';
-
-addonLoader.register({
-  id: 'rajaongkir-bridge',
-  name: 'Rajaongkir Bridge',
-  version: '1.0.0',
-  init: () => {
-    // Add destination search field after shipping address
-    addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
-      // Only for Indonesia
-      if (formData.shipping?.country !== 'ID') return content;
-      
-      return (
-        <>
-          {content}
-          <div className="border rounded-lg p-4 mt-4">
-            <h3 className="font-medium mb-3">📍 Shipping Destination</h3>
-            <RajaongkirDestinationSearch
-              value={formData.shipping?.destination_id}
-              onChange={(id, label) => {
-                setFormData({
-                  ...formData,
-                  shipping: {
-                    ...formData.shipping,
-                    destination_id: id,
-                    destination_label: label,
-                  }
-                });
-              }}
-            />
-          </div>
-        </>
-      );
-    });
-  }
-});
-```
-
-### Option B: Code Snippet (No Plugin)
-
-For users who don't want a separate plugin, provide a code snippet:
-
-```php
-// Add to theme's functions.php or custom plugin
-
-// Bridge Rajaongkir with WooNooW
-add_filter('woonoow_shipping_data', function($data) {
-    if ($data['country'] === 'ID' && !empty($data['city'])) {
-        // Auto-search and set destination
-        $api = Cekongkir_API::get_instance();
-        $results = $api->search_destination_api($data['city']);
-        if (!empty($results[0])) {
-            WC()->session->set('selected_destination_id', $results[0]['id']);
-        }
-    }
-    return $data;
-});
-```
-
----
-
-## Proper Solution: Build WooNooW Addon
-
-Instead of bridging Rajaongkir, build a proper WooNooW addon:
-
-**WooNooW Indonesia Shipping Addon**
-
-```php
-<?php
-/**
- * Plugin Name: WooNooW Indonesia Shipping
- * Description: Indonesia shipping with Rajaongkir API
- * Version: 1.0.0
- * Requires: WooNooW 1.0.0+
- */
-
-// Register addon
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['indonesia-shipping'] = [
-        'id'           => 'indonesia-shipping',
-        'name'         => 'Indonesia Shipping',
-        'version'      => '1.0.0',
-        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
-        'dependencies' => ['woocommerce' => '8.0'],
-    ];
-    return $addons;
-});
-
-// Add API endpoints
-add_action('rest_api_init', function() {
-    register_rest_route('woonoow/v1', '/indonesia/search-destination', [
-        'methods' => 'GET',
-        'callback' => function($req) {
-            $query = $req->get_param('query');
-            $api = new RajaongkirAPI(get_option('rajaongkir_api_key'));
-            return $api->searchDestination($query);
-        },
-    ]);
-    
-    register_rest_route('woonoow/v1', '/indonesia/calculate-shipping', [
-        'methods' => 'POST',
-        'callback' => function($req) {
-            $origin = $req->get_param('origin');
-            $destination = $req->get_param('destination');
-            $weight = $req->get_param('weight');
-            
-            $api = new RajaongkirAPI(get_option('rajaongkir_api_key'));
-            return $api->calculateShipping($origin, $destination, $weight);
-        },
-    ]);
-});
-```
-
-**Frontend:**
-
-```typescript
-// dist/addon.ts
-
-import { addonLoader, addFilter } from '@woonoow/hooks';
-import { DestinationSearch } from './components/DestinationSearch';
-
-addonLoader.register({
-  id: 'indonesia-shipping',
-  name: 'Indonesia Shipping',
-  version: '1.0.0',
-  init: () => {
-    // Add destination field
-    addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
-      if (formData.shipping?.country !== 'ID') return content;
-      
-      return (
-        <>
-          {content}
-          <DestinationSearch
-            value={formData.shipping?.destination_id}
-            onChange={(id, label) => {
-              setFormData({
-                ...formData,
-                shipping: { ...formData.shipping, destination_id: id, destination_label: label }
-              });
-            }}
-          />
-        </>
-      );
-    });
-    
-    // Add validation
-    addFilter('woonoow_order_form_validation', (errors, formData) => {
-      if (formData.shipping?.country === 'ID' && !formData.shipping?.destination_id) {
-        errors.destination = 'Please select shipping destination';
-      }
-      return errors;
-    });
-  }
-});
-```
-
----
-
-## Comparison
-
-### Bridge Snippet (Quick Fix)
-✅ Works immediately
-✅ No new plugin needed
-✅ Minimal code
-❌ Depends on Rajaongkir plugin
-❌ Limited features
-❌ Not ideal UX
-
-### Proper WooNooW Addon (Best Practice)
-✅ Native WooNooW integration
-✅ Better UX
-✅ More features
-✅ Independent of Rajaongkir plugin
-✅ Can use any shipping API
-❌ More development effort
-❌ Separate plugin to maintain
-
----
-
-## Recommendation
-
-**For WooNooW Core:**
-- ❌ Don't integrate Rajaongkir
-- ✅ Provide hook system
-- ✅ Document bridge pattern
-- ✅ Provide code snippets
-
-**For Users:**
-- **Quick fix:** Use bridge snippet
-- **Best practice:** Build proper addon or use community addon
-
-**For Community:**
-- Build "WooNooW Indonesia Shipping" addon
-- Publish on WordPress.org
-- Support Rajaongkir, Biteship, and other Indonesian shipping APIs
-
----
-
-## Hook Points Needed in WooNooW Core
-
-To support addons like this, WooNooW core should provide:
-
-```php
-// Before shipping calculation
-apply_filters('woonoow_before_shipping_calculate', $shipping_data);
-
-// After shipping calculation
-apply_filters('woonoow_after_shipping_calculate', $rates, $shipping_data);
-
-// Modify shipping data
-apply_filters('woonoow_shipping_data', $data);
-```
-
-```typescript
-// Frontend hooks
-'woonoow_order_form_after_shipping'
-'woonoow_order_form_shipping_fields'
-'woonoow_order_form_validation'
-'woonoow_order_form_submit'
-```
-
-**These hooks already exist in our addon system!**
-
----
-
-## Conclusion
-
-**WooNooW Core = Zero addon dependencies**
-
-Instead of integrating Rajaongkir into core:
-1. Provide hook system ✅ (Already done)
-2. Document bridge pattern ✅ (This document)
-3. Encourage community addons ✅
-
-This keeps WooNooW core:
-- Clean
-- Maintainable
-- Flexible
-- Extensible
-
-Users can choose:
-- Bridge snippet (quick fix)
-- Proper addon (best practice)
-- Build their own
-
-**No bloat in core!**

ADDON_DEVELOPMENT_GUIDE.md

@@ -1,715 +0,0 @@
-# WooNooW Addon Development Guide
-
-**Version:** 2.0.0  
-**Last Updated:** November 9, 2025  
-**Status:** Production Ready
-
----
-
-## 📋 Table of Contents
-
-1. [Overview](#overview)
-2. [Addon Types](#addon-types)
-3. [Quick Start](#quick-start)
-4. [SPA Route Injection](#spa-route-injection)
-5. [Hook System Integration](#hook-system-integration)
-6. [Component Development](#component-development)
-7. [Best Practices](#best-practices)
-8. [Examples](#examples)
-9. [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-WooNooW provides **two powerful addon systems**:
-
-### 1. **SPA Route Injection** (Admin UI)
-- ✅ Register custom SPA routes
-- ✅ Inject navigation menu items
-- ✅ Add submenu items to existing sections
-- ✅ Load React components dynamically
-- ✅ Full isolation and safety
-
-### 2. **Hook System** (Functional Extension)
-- ✅ Extend OrderForm, ProductForm, etc.
-- ✅ Add custom fields and validation
-- ✅ Inject components at specific points
-- ✅ Zero coupling with core
-- ✅ WordPress-style filters and actions
-
-**Both systems work together seamlessly!**
-
----
-
-## Addon Types
-
-### Type A: UI-Only Addon (Route Injection)
-**Use when:** Adding new pages/sections to admin
-
-**Example:** Reports, Analytics, Custom Dashboard
-
-```php
-// Registers routes + navigation
-add_filter('woonoow/spa_routes', ...);
-add_filter('woonoow/nav_tree', ...);
-```
-
-### Type B: Functional Addon (Hook System)
-**Use when:** Extending existing functionality
-
-**Example:** Indonesia Shipping, Custom Fields, Validation
-
-```typescript
-// Registers hooks
-addFilter('woonoow_order_form_after_shipping', ...);
-addAction('woonoow_order_created', ...);
-```
-
-### Type C: Full-Featured Addon (Both Systems)
-**Use when:** Complex integration needed
-
-**Example:** Subscriptions, Bookings, Memberships
-
-```php
-// Backend: Routes + Hooks
-add_filter('woonoow/spa_routes', ...);
-add_filter('woonoow/nav_tree', ...);
-
-// Frontend: Hook registration
-addonLoader.register({
-  init: () => {
-    addFilter('woonoow_order_form_custom_sections', ...);
-  }
-});
-```
-
----
-
-## Quick Start
-
-### Step 1: Create Plugin File
-
-```php
-<?php
-/**
- * Plugin Name: My WooNooW Addon
- * Description: Extends WooNooW functionality
- * Version: 1.0.0
- * Requires: WooNooW 1.0.0+
- */
-
-// 1. Register addon
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['my-addon'] = [
-        'id'           => 'my-addon',
-        'name'         => 'My Addon',
-        'version'      => '1.0.0',
-        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
-        'dependencies' => ['woocommerce' => '8.0'],
-    ];
-    return $addons;
-});
-
-// 2. Register routes (optional - for UI pages)
-add_filter('woonoow/spa_routes', function($routes) {
-    $routes[] = [
-        'path'          => '/my-addon',
-        'component_url' => plugin_dir_url(__FILE__) . 'dist/MyPage.js',
-        'capability'    => 'manage_woocommerce',
-        'title'         => 'My Addon',
-    ];
-    return $routes;
-});
-
-// 3. Add navigation (optional - for UI pages)
-add_filter('woonoow/nav_tree', function($tree) {
-    $tree[] = [
-        'key'   => 'my-addon',
-        'label' => 'My Addon',
-        'path'  => '/my-addon',
-        'icon'  => 'puzzle',
-    ];
-    return $tree;
-});
-```
-
-### Step 2: Create Frontend Integration
-
-```typescript
-// admin-spa/src/index.ts
-
-import { addonLoader, addFilter } from '@woonoow/hooks';
-
-addonLoader.register({
-  id: 'my-addon',
-  name: 'My Addon',
-  version: '1.0.0',
-  init: () => {
-    // Register hooks here
-    addFilter('woonoow_order_form_custom_sections', (content, formData, setFormData) => {
-      return (
-        <>
-          {content}
-          <MyCustomSection data={formData} onChange={setFormData} />
-        </>
-      );
-    });
-  }
-});
-```
-
-### Step 3: Build
-
-```bash
-npm run build
-```
-
-**Done!** Your addon is now integrated.
-
----
-
-## SPA Route Injection
-
-### Register Routes
-
-```php
-add_filter('woonoow/spa_routes', function($routes) {
-    $base_url = plugin_dir_url(__FILE__) . 'dist/';
-    
-    $routes[] = [
-        'path'          => '/subscriptions',
-        'component_url' => $base_url . 'SubscriptionsList.js',
-        'capability'    => 'manage_woocommerce',
-        'title'         => 'Subscriptions',
-    ];
-    
-    $routes[] = [
-        'path'          => '/subscriptions/:id',
-        'component_url' => $base_url . 'SubscriptionDetail.js',
-        'capability'    => 'manage_woocommerce',
-        'title'         => 'Subscription Detail',
-    ];
-    
-    return $routes;
-});
-```
-
-### Add Navigation
-
-```php
-// Main menu item
-add_filter('woonoow/nav_tree', function($tree) {
-    $tree[] = [
-        'key'      => 'subscriptions',
-        'label'    => __('Subscriptions', 'my-addon'),
-        'path'     => '/subscriptions',
-        'icon'     => 'repeat',
-        'children' => [
-            [
-                'label' => __('All Subscriptions', 'my-addon'),
-                'mode'  => 'spa',
-                'path'  => '/subscriptions',
-            ],
-            [
-                'label' => __('New', 'my-addon'),
-                'mode'  => 'spa',
-                'path'  => '/subscriptions/new',
-            ],
-        ],
-    ];
-    return $tree;
-});
-
-// Or inject into existing section
-add_filter('woonoow/nav_tree/products/children', function($children) {
-    $children[] = [
-        'label' => __('Bundles', 'my-addon'),
-        'mode'  => 'spa',
-        'path'  => '/products/bundles',
-    ];
-    return $children;
-});
-```
-
----
-
-## Hook System Integration
-
-### Available Hooks
-
-#### Order Form Hooks
-```typescript
-// Add fields after billing address
-'woonoow_order_form_after_billing'
-
-// Add fields after shipping address
-'woonoow_order_form_after_shipping'
-
-// Add custom shipping fields
-'woonoow_order_form_shipping_fields'
-
-// Add custom sections
-'woonoow_order_form_custom_sections'
-
-// Add validation rules
-'woonoow_order_form_validation'
-
-// Modify form data before render
-'woonoow_order_form_data'
-```
-
-#### Action Hooks
-```typescript
-// Before form submission
-'woonoow_order_form_submit'
-
-// After order created
-'woonoow_order_created'
-
-// After order updated
-'woonoow_order_updated'
-```
-
-### Hook Registration Example
-
-```typescript
-import { addonLoader, addFilter, addAction } from '@woonoow/hooks';
-
-addonLoader.register({
-  id: 'indonesia-shipping',
-  name: 'Indonesia Shipping',
-  version: '1.0.0',
-  init: () => {
-    // Filter: Add subdistrict selector
-    addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
-      return (
-        <>
-          {content}
-          <SubdistrictSelector
-            value={formData.shipping?.subdistrict_id}
-            onChange={(id) => setFormData({
-              ...formData,
-              shipping: { ...formData.shipping, subdistrict_id: id }
-            })}
-          />
-        </>
-      );
-    });
-
-    // Filter: Add validation
-    addFilter('woonoow_order_form_validation', (errors, formData) => {
-      if (!formData.shipping?.subdistrict_id) {
-        errors.subdistrict = 'Subdistrict is required';
-      }
-      return errors;
-    });
-
-    // Action: Log when order created
-    addAction('woonoow_order_created', (orderId, orderData) => {
-      console.log('Order created:', orderId);
-    });
-  }
-});
-```
-
-### Hook System Benefits
-
-✅ **Zero Coupling**
-```typescript
-// WooNooW Core has no knowledge of your addon
-{applyFilters('woonoow_order_form_after_shipping', null, formData, setFormData)}
-
-// If addon exists: Returns your component
-// If addon doesn't exist: Returns null
-// No import, no error!
-```
-
-✅ **Multiple Addons Can Hook**
-```typescript
-// Addon A
-addFilter('woonoow_order_form_after_shipping', (content) => {
-  return <>{content}<AddonAFields /></>;
-});
-
-// Addon B
-addFilter('woonoow_order_form_after_shipping', (content) => {
-  return <>{content}<AddonBFields /></>;
-});
-
-// Both render!
-```
-
-✅ **Type Safety**
-```typescript
-addFilter<ReactNode, [OrderFormData, SetState<OrderFormData>]>(
-  'woonoow_order_form_after_shipping',
-  (content, formData, setFormData) => {
-    // TypeScript knows the types!
-    return <MyComponent />;
-  }
-);
-```
-
----
-
-## Component Development
-
-### Basic Component
-
-```typescript
-// dist/MyPage.tsx
-import React from 'react';
-
-export default function MyPage() {
-  return (
-    <div className="space-y-6">
-      <div className="rounded-lg border p-6 bg-card">
-        <h2 className="text-xl font-semibold mb-2">My Addon</h2>
-        <p className="text-sm opacity-70">Welcome!</p>
-      </div>
-    </div>
-  );
-}
-```
-
-### Access WooNooW APIs
-
-```typescript
-// Access REST API
-const api = (window as any).WNW_API;
-const response = await fetch(`${api.root}my-addon/endpoint`, {
-  headers: { 'X-WP-Nonce': api.nonce },
-});
-
-// Access store data
-const store = (window as any).WNW_STORE;
-console.log('Currency:', store.currency);
-
-// Access site info
-const wnw = (window as any).wnw;
-console.log('Site Title:', wnw.siteTitle);
-```
-
-### Use WooNooW Components
-
-```typescript
-import { __ } from '@/lib/i18n';
-import { formatMoney } from '@/lib/currency';
-import { Button } from '@/components/ui/button';
-import { Card } from '@/components/ui/card';
-
-export default function MyPage() {
-  return (
-    <Card className="p-6">
-      <h2>{__('My Addon', 'my-addon')}</h2>
-      <p>{formatMoney(1234.56)}</p>
-      <Button>{__('Click Me', 'my-addon')}</Button>
-    </Card>
-  );
-}
-```
-
-### Build Configuration
-
-```javascript
-// vite.config.js
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react()],
-  build: {
-    lib: {
-      entry: 'src/index.ts',
-      name: 'MyAddon',
-      fileName: 'addon',
-      formats: ['es'],
-    },
-    rollupOptions: {
-      external: ['react', 'react-dom'],
-      output: {
-        globals: {
-          react: 'React',
-          'react-dom': 'ReactDOM',
-        },
-      },
-    },
-  },
-});
-```
-
----
-
-## Best Practices
-
-### ✅ DO:
-
-1. **Use Hook System for Functional Extensions**
-   ```typescript
-   // ✅ Good - No hardcoding
-   addFilter('woonoow_order_form_after_shipping', ...);
-   ```
-
-2. **Use Route Injection for New Pages**
-   ```php
-   // ✅ Good - Separate UI
-   add_filter('woonoow/spa_routes', ...);
-   ```
-
-3. **Declare Dependencies**
-   ```php
-   'dependencies' => ['woocommerce' => '8.0']
-   ```
-
-4. **Check Capabilities**
-   ```php
-   'capability' => 'manage_woocommerce'
-   ```
-
-5. **Internationalize Strings**
-   ```php
-   'label' => __('My Addon', 'my-addon')
-   ```
-
-6. **Handle Errors Gracefully**
-   ```typescript
-   try {
-     await api.post(...);
-   } catch (error) {
-     toast.error('Failed to save');
-   }
-   ```
-
-### ❌ DON'T:
-
-1. **Don't Hardcode Addon Components in Core**
-   ```typescript
-   // ❌ Bad - Breaks if addon not installed
-   import { SubdistrictSelector } from 'addon';
-   <SubdistrictSelector />
-   
-   // ✅ Good - Use hooks
-   {applyFilters('woonoow_order_form_after_shipping', null)}
-   ```
-
-2. **Don't Skip Capability Checks**
-   ```php
-   // ❌ Bad
-   'capability' => ''
-   
-   // ✅ Good
-   'capability' => 'manage_woocommerce'
-   ```
-
-3. **Don't Modify Core Navigation**
-   ```php
-   // ❌ Bad
-   unset($tree[0]);
-   
-   // ✅ Good
-   $tree[] = ['key' => 'my-addon', ...];
-   ```
-
----
-
-## Examples
-
-### Example 1: Simple UI Addon (Route Injection Only)
-
-```php
-<?php
-/**
- * Plugin Name: WooNooW Reports
- * Description: Custom reports page
- */
-
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['reports'] = [
-        'id'      => 'reports',
-        'name'    => 'Reports',
-        'version' => '1.0.0',
-    ];
-    return $addons;
-});
-
-add_filter('woonoow/spa_routes', function($routes) {
-    $routes[] = [
-        'path'          => '/reports',
-        'component_url' => plugin_dir_url(__FILE__) . 'dist/Reports.js',
-        'title'         => 'Reports',
-    ];
-    return $routes;
-});
-
-add_filter('woonoow/nav_tree', function($tree) {
-    $tree[] = [
-        'key'   => 'reports',
-        'label' => 'Reports',
-        'path'  => '/reports',
-        'icon'  => 'bar-chart',
-    ];
-    return $tree;
-});
-```
-
-### Example 2: Functional Addon (Hook System Only)
-
-```typescript
-// Indonesia Shipping - No UI pages, just extends OrderForm
-
-import { addonLoader, addFilter } from '@woonoow/hooks';
-import { SubdistrictSelector } from './components/SubdistrictSelector';
-
-addonLoader.register({
-  id: 'indonesia-shipping',
-  name: 'Indonesia Shipping',
-  version: '1.0.0',
-  init: () => {
-    addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
-      return (
-        <>
-          {content}
-          <div className="border rounded-lg p-4 mt-4">
-            <h3 className="font-medium mb-3">📍 Shipping Destination</h3>
-            <SubdistrictSelector
-              value={formData.shipping?.subdistrict_id}
-              onChange={(id) => setFormData({
-                ...formData,
-                shipping: { ...formData.shipping, subdistrict_id: id }
-              })}
-            />
-          </div>
-        </>
-      );
-    });
-  }
-});
-```
-
-### Example 3: Full-Featured Addon (Both Systems)
-
-```php
-<?php
-/**
- * Plugin Name: WooNooW Subscriptions
- * Description: Subscription management
- */
-
-// Backend: Register addon + routes
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['subscriptions'] = [
-        'id'         => 'subscriptions',
-        'name'       => 'Subscriptions',
-        'version'    => '1.0.0',
-        'spa_bundle' => plugin_dir_url(__FILE__) . 'dist/addon.js',
-    ];
-    return $addons;
-});
-
-add_filter('woonoow/spa_routes', function($routes) {
-    $routes[] = [
-        'path'          => '/subscriptions',
-        'component_url' => plugin_dir_url(__FILE__) . 'dist/SubscriptionsList.js',
-    ];
-    return $routes;
-});
-
-add_filter('woonoow/nav_tree', function($tree) {
-    $tree[] = [
-        'key'   => 'subscriptions',
-        'label' => 'Subscriptions',
-        'path'  => '/subscriptions',
-        'icon'  => 'repeat',
-    ];
-    return $tree;
-});
-```
-
-```typescript
-// Frontend: Hook integration
-
-import { addonLoader, addFilter } from '@woonoow/hooks';
-
-addonLoader.register({
-  id: 'subscriptions',
-  name: 'Subscriptions',
-  version: '1.0.0',
-  init: () => {
-    // Add subscription fields to order form
-    addFilter('woonoow_order_form_custom_sections', (content, formData, setFormData) => {
-      return (
-        <>
-          {content}
-          <SubscriptionOptions data={formData} onChange={setFormData} />
-        </>
-      );
-    });
-
-    // Add subscription fields to product form
-    addFilter('woonoow_product_form_fields', (content, formData, setFormData) => {
-      return (
-        <>
-          {content}
-          <SubscriptionSettings data={formData} onChange={setFormData} />
-        </>
-      );
-    });
-  }
-});
-```
-
----
-
-## Troubleshooting
-
-### Addon Not Appearing?
-- Check dependencies are met
-- Verify capability requirements
-- Check browser console for errors
-- Flush caches: `?flush_wnw_cache=1`
-
-### Route Not Loading?
-- Verify `component_url` is correct
-- Check file exists and is accessible
-- Look for JS errors in console
-- Ensure component exports `default`
-
-### Hook Not Firing?
-- Check hook name is correct
-- Verify addon is registered
-- Check `window.WNW_ADDONS` in console
-- Ensure `init()` function runs
-
-### Component Not Rendering?
-- Check for React errors in console
-- Verify component returns valid JSX
-- Check props are passed correctly
-- Test component in isolation
-
----
-
-## Support & Resources
-
-**Documentation:**
-- `ADDON_INJECTION_GUIDE.md` - SPA route injection (legacy)
-- `ADDON_HOOK_SYSTEM.md` - Hook system details (legacy)
-- `BITESHIP_ADDON_SPEC.md` - Indonesia shipping example
-- `SHIPPING_ADDON_RESEARCH.md` - Shipping integration patterns
-
-**Code References:**
-- `includes/Compat/AddonRegistry.php` - Addon registration
-- `includes/Compat/RouteRegistry.php` - Route management
-- `includes/Compat/NavigationRegistry.php` - Navigation building
-- `admin-spa/src/lib/hooks.ts` - Hook system implementation
-- `admin-spa/src/App.tsx` - Dynamic route loading
-
----
-
-**End of Guide**
-
-**Version:** 2.0.0  
-**Last Updated:** November 9, 2025  
-**Status:** ✅ Production Ready
-
-**This is the single source of truth for WooNooW addon development.**

ADDON_MODULE_DESIGN_DECISIONS.md

@@ -1,616 +0,0 @@
-# Addon-Module Integration: Design Decisions
-
-**Date**: December 26, 2025  
-**Status**: 🎯 Decision Document
-
----
-
-## 1. Dynamic Categories (RECOMMENDED)
-
-### ❌ Problem with Static Categories
-```php
-// BAD: Empty categories if no modules use them
-public static function get_categories() {
-    return [
-        'shipping' => 'Shipping & Fulfillment', // Empty if no shipping modules!
-        'payments' => 'Payments & Checkout', // Empty if no payment modules!
-    ];
-}
-```
-
-### ✅ Solution: Dynamic Category Generation
-
-```php
-class ModuleRegistry {
-    
-    /**
-     * Get categories dynamically from registered modules
-     */
-    public static function get_categories() {
-        $all_modules = self::get_all_modules();
-        $categories = [];
-        
-        // Extract unique categories from modules
-        foreach ($all_modules as $module) {
-            $cat = $module['category'] ?? 'other';
-            if (!isset($categories[$cat])) {
-                $categories[$cat] = self::get_category_label($cat);
-            }
-        }
-        
-        // Sort by predefined order (if exists), then alphabetically
-        $order = ['marketing', 'customers', 'products', 'shipping', 'payments', 'analytics', 'other'];
-        uksort($categories, function($a, $b) use ($order) {
-            $pos_a = array_search($a, $order);
-            $pos_b = array_search($b, $order);
-            if ($pos_a === false) $pos_a = 999;
-            if ($pos_b === false) $pos_b = 999;
-            return $pos_a - $pos_b;
-        });
-        
-        return $categories;
-    }
-    
-    /**
-     * Get human-readable label for category
-     */
-    private static function get_category_label($category) {
-        $labels = [
-            'marketing'  => __('Marketing & Sales', 'woonoow'),
-            'customers'  => __('Customer Experience', 'woonoow'),
-            'products'   => __('Products & Inventory', 'woonoow'),
-            'shipping'   => __('Shipping & Fulfillment', 'woonoow'),
-            'payments'   => __('Payments & Checkout', 'woonoow'),
-            'analytics'  => __('Analytics & Reports', 'woonoow'),
-            'other'      => __('Other Extensions', 'woonoow'),
-        ];
-        
-        return $labels[$category] ?? ucfirst($category);
-    }
-    
-    /**
-     * Group modules by category
-     */
-    public static function get_grouped_modules() {
-        $all_modules = self::get_all_modules();
-        $grouped = [];
-        
-        foreach ($all_modules as $module) {
-            $cat = $module['category'] ?? 'other';
-            if (!isset($grouped[$cat])) {
-                $grouped[$cat] = [];
-            }
-            $grouped[$cat][] = $module;
-        }
-        
-        return $grouped;
-    }
-}
-```
-
-### Benefits
-- ✅ No empty categories
-- ✅ Addons can define custom categories
-- ✅ Single registration point (module only)
-- ✅ Auto-sorted by predefined order
-
----
-
-## 2. Module Settings URL Pattern (RECOMMENDED)
-
-### ❌ Problem with Custom URLs
-```php
-'settings_url' => '/settings/shipping/biteship', // Conflict risk!
-'settings_url' => '/marketing/newsletter', // Inconsistent!
-```
-
-### ✅ Solution: Convention-Based Pattern
-
-#### Option A: Standardized Pattern (RECOMMENDED)
-```php
-// Module registration - NO settings_url needed!
-$addons['biteship-shipping'] = [
-    'id'       => 'biteship-shipping',
-    'name'     => 'Biteship Shipping',
-    'has_settings' => true, // Just a flag!
-];
-
-// Auto-generated URL pattern:
-// /settings/modules/{module_id}
-// Example: /settings/modules/biteship-shipping
-```
-
-#### Backend: Auto Route Registration
-```php
-class ModuleRegistry {
-    
-    /**
-     * Register module settings routes automatically
-     */
-    public static function register_settings_routes() {
-        $modules = self::get_all_modules();
-        
-        foreach ($modules as $module) {
-            if (empty($module['has_settings'])) continue;
-            
-            // Auto-register route: /settings/modules/{module_id}
-            add_filter('woonoow/spa_routes', function($routes) use ($module) {
-                $routes[] = [
-                    'path'          => "/settings/modules/{$module['id']}",
-                    'component_url' => $module['settings_component'] ?? null,
-                    'title'         => sprintf(__('%s Settings', 'woonoow'), $module['label']),
-                ];
-                return $routes;
-            });
-        }
-    }
-}
-```
-
-#### Frontend: Automatic Navigation
-```tsx
-// Modules.tsx - Gear icon auto-links
-{module.has_settings && module.enabled && (
-  <Button
-    variant="ghost"
-    size="icon"
-    onClick={() => navigate(`/settings/modules/${module.id}`)}
-  >
-    <Settings className="h-4 w-4" />
-  </Button>
-)}
-```
-
-### Benefits
-- ✅ No URL conflicts (enforced pattern)
-- ✅ Consistent navigation
-- ✅ Simpler addon registration
-- ✅ Auto-generated breadcrumbs
-
----
-
-## 3. Form Builder vs Custom HTML (HYBRID APPROACH)
-
-### ✅ Recommended: Provide Both Options
-
-#### Option A: Schema-Based Form Builder (For Simple Settings)
-```php
-// Addon defines settings schema
-add_filter('woonoow/module_settings_schema', function($schemas) {
-    $schemas['biteship-shipping'] = [
-        'api_key' => [
-            'type'        => 'text',
-            'label'       => 'API Key',
-            'description' => 'Your Biteship API key',
-            'required'    => true,
-        ],
-        'enable_tracking' => [
-            'type'    => 'toggle',
-            'label'   => 'Enable Tracking',
-            'default' => true,
-        ],
-        'default_courier' => [
-            'type'    => 'select',
-            'label'   => 'Default Courier',
-            'options' => [
-                'jne'     => 'JNE',
-                'jnt'     => 'J&T Express',
-                'sicepat' => 'SiCepat',
-            ],
-        ],
-    ];
-    return $schemas;
-});
-```
-
-**Auto-rendered form** - No React needed!
-
-#### Option B: Custom React Component (For Complex Settings)
-```php
-// Addon provides custom React component
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['biteship-shipping'] = [
-        'id'                 => 'biteship-shipping',
-        'has_settings'       => true,
-        'settings_component' => plugin_dir_url(__FILE__) . 'dist/Settings.js',
-    ];
-    return $addons;
-});
-```
-
-**Full control** - Custom React UI
-
-### Implementation
-
-```php
-class ModuleSettingsRenderer {
-    
-    /**
-     * Render settings page
-     */
-    public static function render($module_id) {
-        $module = ModuleRegistry::get_module($module_id);
-        
-        // Option 1: Has custom component
-        if (!empty($module['settings_component'])) {
-            return self::render_custom_component($module);
-        }
-        
-        // Option 2: Has schema - auto-generate form
-        $schema = apply_filters('woonoow/module_settings_schema', []);
-        if (isset($schema[$module_id])) {
-            return self::render_schema_form($module_id, $schema[$module_id]);
-        }
-        
-        // Option 3: No settings
-        return ['error' => 'No settings available'];
-    }
-}
-```
-
-### Benefits
-- ✅ Simple addons use schema (no React needed)
-- ✅ Complex addons use custom components
-- ✅ Consistent data persistence for both
-- ✅ Gradual complexity curve
-
----
-
-## 4. Settings Data Persistence (STANDARDIZED)
-
-### ✅ Recommended: Unified Settings API
-
-#### Backend: Automatic Persistence
-```php
-class ModuleSettingsController extends WP_REST_Controller {
-    
-    /**
-     * GET /woonoow/v1/modules/{module_id}/settings
-     */
-    public function get_settings($request) {
-        $module_id = $request['module_id'];
-        $settings = get_option("woonoow_module_{$module_id}_settings", []);
-        
-        // Apply defaults from schema
-        $schema = apply_filters('woonoow/module_settings_schema', []);
-        if (isset($schema[$module_id])) {
-            $settings = wp_parse_args($settings, self::get_defaults($schema[$module_id]));
-        }
-        
-        return rest_ensure_response($settings);
-    }
-    
-    /**
-     * POST /woonoow/v1/modules/{module_id}/settings
-     */
-    public function update_settings($request) {
-        $module_id = $request['module_id'];
-        $new_settings = $request->get_json_params();
-        
-        // Validate against schema
-        $schema = apply_filters('woonoow/module_settings_schema', []);
-        if (isset($schema[$module_id])) {
-            $validated = self::validate_settings($new_settings, $schema[$module_id]);
-            if (is_wp_error($validated)) {
-                return $validated;
-            }
-            $new_settings = $validated;
-        }
-        
-        // Save
-        update_option("woonoow_module_{$module_id}_settings", $new_settings);
-        
-        // Allow addons to react
-        do_action("woonoow/module_settings_updated/{$module_id}", $new_settings);
-        
-        return rest_ensure_response(['success' => true]);
-    }
-}
-```
-
-#### Frontend: Unified Hook
-```tsx
-// useModuleSettings.ts
-export function useModuleSettings(moduleId: string) {
-  const queryClient = useQueryClient();
-  
-  const { data: settings, isLoading } = useQuery({
-    queryKey: ['module-settings', moduleId],
-    queryFn: async () => {
-      const response = await api.get(`/modules/${moduleId}/settings`);
-      return response;
-    },
-  });
-  
-  const updateSettings = useMutation({
-    mutationFn: async (newSettings: any) => {
-      return api.post(`/modules/${moduleId}/settings`, newSettings);
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['module-settings', moduleId] });
-      toast.success('Settings saved');
-    },
-  });
-  
-  return { settings, isLoading, updateSettings };
-}
-```
-
-#### Addon Usage
-```tsx
-// Custom settings component
-export default function BiteshipSettings() {
-  const { settings, updateSettings } = useModuleSettings('biteship-shipping');
-  
-  return (
-    <SettingsLayout title="Biteship Settings">
-      <SettingsCard>
-        <Input
-          label="API Key"
-          value={settings?.api_key || ''}
-          onChange={(e) => updateSettings.mutate({ api_key: e.target.value })}
-        />
-      </SettingsCard>
-    </SettingsLayout>
-  );
-}
-```
-
-### Benefits
-- ✅ Consistent storage pattern: `woonoow_module_{id}_settings`
-- ✅ Automatic validation (if schema provided)
-- ✅ React hook for easy access
-- ✅ Action hooks for addon logic
-
----
-
-## 5. React Extension Pattern (DOCUMENTED)
-
-### ✅ Solution: Window API + Build Externals
-
-#### WooNooW Core Exposes React
-```typescript
-// admin-spa/src/main.tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { useQuery, useMutation } from '@tanstack/react-query';
-
-// Expose for addons
-window.WooNooW = {
-  React,
-  ReactDOM,
-  hooks: {
-    useQuery,
-    useMutation,
-    useModuleSettings, // Our custom hook!
-  },
-  components: {
-    SettingsLayout,
-    SettingsCard,
-    Button,
-    Input,
-    Select,
-    Switch,
-    // ... all shadcn components
-  },
-  utils: {
-    api,
-    toast,
-  },
-};
-```
-
-#### Addon Development
-```typescript
-// addon/src/Settings.tsx
-const { React, hooks, components, utils } = window.WooNooW;
-const { useModuleSettings } = hooks;
-const { SettingsLayout, SettingsCard, Input, Button } = components;
-const { toast } = utils;
-
-export default function BiteshipSettings() {
-  const { settings, updateSettings } = useModuleSettings('biteship-shipping');
-  const [apiKey, setApiKey] = React.useState(settings?.api_key || '');
-  
-  const handleSave = () => {
-    updateSettings.mutate({ api_key: apiKey });
-  };
-  
-  return React.createElement(SettingsLayout, { title: 'Biteship Settings' },
-    React.createElement(SettingsCard, null,
-      React.createElement(Input, {
-        label: 'API Key',
-        value: apiKey,
-        onChange: (e) => setApiKey(e.target.value),
-      }),
-      React.createElement(Button, { onClick: handleSave }, 'Save')
-    )
-  );
-}
-```
-
-#### With JSX (Build Required)
-```tsx
-// addon/src/Settings.tsx
-const { React, hooks, components } = window.WooNooW;
-const { useModuleSettings } = hooks;
-const { SettingsLayout, SettingsCard, Input, Button } = components;
-
-export default function BiteshipSettings() {
-  const { settings, updateSettings } = useModuleSettings('biteship-shipping');
-  
-  return (
-    <SettingsLayout title="Biteship Settings">
-      <SettingsCard>
-        <Input
-          label="API Key"
-          value={settings?.api_key || ''}
-          onChange={(e) => updateSettings.mutate({ api_key: e.target.value })}
-        />
-      </SettingsCard>
-    </SettingsLayout>
-  );
-}
-```
-
-```javascript
-// vite.config.js
-export default {
-  build: {
-    lib: {
-      entry: 'src/Settings.tsx',
-      formats: ['es'],
-    },
-    rollupOptions: {
-      external: ['react', 'react-dom'],
-      output: {
-        globals: {
-          react: 'window.WooNooW.React',
-          'react-dom': 'window.WooNooW.ReactDOM',
-        },
-      },
-    },
-  },
-};
-```
-
-### Benefits
-- ✅ Addons don't bundle React (use ours)
-- ✅ Access to all WooNooW components
-- ✅ Consistent UI automatically
-- ✅ Type safety with TypeScript
-
----
-
-## 6. Newsletter as Addon Example (RECOMMENDED)
-
-### ✅ Yes, Refactor Newsletter as Built-in Addon
-
-#### Why This is Valuable
-
-1. **Dogfooding** - We use our own addon system
-2. **Example** - Best reference for addon developers
-3. **Consistency** - Newsletter follows same pattern as external addons
-4. **Testing** - Proves the system works
-
-#### Proposed Structure
-
-```
-includes/
-  Modules/
-    Newsletter/
-      NewsletterModule.php        # Module registration
-      NewsletterController.php    # API endpoints (moved from Api/)
-      NewsletterSettings.php      # Settings schema
-      
-admin-spa/src/modules/
-  Newsletter/
-    Settings.tsx                  # Settings page
-    Subscribers.tsx               # Subscribers page
-    index.ts                      # Module exports
-```
-
-#### Registration Pattern
-```php
-// includes/Modules/Newsletter/NewsletterModule.php
-class NewsletterModule {
-    
-    public static function register() {
-        // Register as module
-        add_filter('woonoow/builtin_modules', function($modules) {
-            $modules['newsletter'] = [
-                'id'                 => 'newsletter',
-                'label'              => __('Newsletter', 'woonoow'),
-                'description'        => __('Email newsletter subscriptions', 'woonoow'),
-                'category'           => 'marketing',
-                'icon'               => 'mail',
-                'default_enabled'    => true,
-                'has_settings'       => true,
-                'settings_component' => self::get_settings_url(),
-            ];
-            return $modules;
-        });
-        
-        // Register routes (only if enabled)
-        if (ModuleRegistry::is_enabled('newsletter')) {
-            self::register_routes();
-        }
-    }
-    
-    private static function register_routes() {
-        // Settings route
-        add_filter('woonoow/spa_routes', function($routes) {
-            $routes[] = [
-                'path'          => '/settings/modules/newsletter',
-                'component_url' => plugins_url('admin-spa/dist/modules/Newsletter/Settings.js', WOONOOW_FILE),
-            ];
-            return $routes;
-        });
-        
-        // Subscribers route
-        add_filter('woonoow/spa_routes', function($routes) {
-            $routes[] = [
-                'path'          => '/marketing/newsletter',
-                'component_url' => plugins_url('admin-spa/dist/modules/Newsletter/Subscribers.js', WOONOOW_FILE),
-            ];
-            return $routes;
-        });
-    }
-}
-```
-
-### Benefits
-- ✅ Newsletter becomes reference implementation
-- ✅ Proves addon system works for complex modules
-- ✅ Shows best practices
-- ✅ Easier to maintain (follows pattern)
-
----
-
-## Summary of Decisions
-
-| # | Question | Decision | Rationale |
-|---|----------|----------|-----------|
-| 1 | Categories | **Dynamic from modules** | No empty categories, single registration |
-| 2 | Settings URL | **Pattern: `/settings/modules/{id}`** | No conflicts, consistent, auto-generated |
-| 3 | Form Builder | **Hybrid: Schema + Custom** | Simple for basic, flexible for complex |
-| 4 | Data Persistence | **Unified API + Hook** | Consistent storage, easy access |
-| 5 | React Extension | **Window API + Externals** | No bundling, access to components |
-| 6 | Newsletter Refactor | **Yes, as example** | Dogfooding, reference implementation |
-
----
-
-## Implementation Order
-
-### Phase 1: Foundation
-1. ✅ Dynamic category generation
-2. ✅ Standardized settings URL pattern
-3. ✅ Module settings API endpoints
-4. ✅ `useModuleSettings` hook
-
-### Phase 2: Form System
-1. ✅ Schema-based form renderer
-2. ✅ Custom component loader
-3. ✅ Settings validation
-
-### Phase 3: UI Enhancement
-1. ✅ Search input on Modules page
-2. ✅ Category filter pills
-3. ✅ Gear icon with auto-routing
-
-### Phase 4: Example
-1. ✅ Refactor Newsletter as built-in addon
-2. ✅ Document pattern
-3. ✅ Create external addon example (Biteship)
-
----
-
-## Next Steps
-
-**Ready to implement?** We have clear decisions on all 6 questions. Should we:
-
-1. Start with Phase 1 (Foundation)?
-2. Create the schema-based form system first?
-3. Refactor Newsletter as proof-of-concept?
-
-**Your call!** All design decisions are documented and justified.

ADDON_MODULE_INTEGRATION.md

@@ -1,476 +0,0 @@
-# Addon-Module Integration Strategy
-
-**Date**: December 26, 2025  
-**Status**: 🎯 Proposal
-
----
-
-## Vision
-
-**Module Registry as the Single Source of Truth for all extensions** - both built-in modules and external addons.
-
----
-
-## Current State Analysis
-
-### What We Have
-
-#### 1. **Module System** (Just Built)
-- `ModuleRegistry.php` - Manages built-in modules
-- Enable/disable functionality
-- Module metadata (label, description, features, icon)
-- Categories (Marketing, Customers, Products)
-- Settings page UI with toggles
-
-#### 2. **Addon System** (Existing)
-- `AddonRegistry.php` - Manages external addons
-- SPA route injection
-- Hook system integration
-- Navigation tree injection
-- React component loading
-
-### The Opportunity
-
-**These two systems should be unified!** An addon is just an external module.
-
----
-
-## Proposed Integration
-
-### Concept: Unified Extension Registry
-
-```
-┌─────────────────────────────────────────────────┐
-│         Module Registry (Single Source)         │
-├─────────────────────────────────────────────────┤
-│                                                  │
-│  Built-in Modules          External Addons      │
-│  ├─ Newsletter            ├─ Biteship Shipping  │
-│  ├─ Wishlist              ├─ Subscriptions      │
-│  ├─ Affiliate             ├─ Bookings           │
-│  ├─ Subscription          └─ Custom Reports     │
-│  └─ Licensing                                   │
-│                                                  │
-│  All share same interface:                      │
-│  • Enable/disable toggle                        │
-│  • Settings page (optional)                     │
-│  • Icon & metadata                              │
-│  • Feature list                                 │
-│                                                  │
-└─────────────────────────────────────────────────┘
-```
-
----
-
-## Implementation Plan
-
-### Phase 1: Extend Module Registry for Addons
-
-#### Backend: ModuleRegistry.php Enhancement
-
-```php
-class ModuleRegistry {
-    
-    /**
-     * Get all modules (built-in + addons)
-     */
-    public static function get_all_modules() {
-        $builtin = self::get_builtin_modules();
-        $addons = self::get_addon_modules();
-        
-        return array_merge($builtin, $addons);
-    }
-    
-    /**
-     * Get addon modules from AddonRegistry
-     */
-    private static function get_addon_modules() {
-        $addons = apply_filters('woonoow/addon_registry', []);
-        $modules = [];
-        
-        foreach ($addons as $addon_id => $addon) {
-            $modules[$addon_id] = [
-                'id' => $addon_id,
-                'label' => $addon['name'],
-                'description' => $addon['description'] ?? '',
-                'category' => $addon['category'] ?? 'addons',
-                'icon' => $addon['icon'] ?? 'puzzle',
-                'default_enabled' => false,
-                'features' => $addon['features'] ?? [],
-                'is_addon' => true,
-                'version' => $addon['version'] ?? '1.0.0',
-                'author' => $addon['author'] ?? '',
-                'settings_url' => $addon['settings_url'] ?? '', // NEW!
-            ];
-        }
-        
-        return $modules;
-    }
-}
-```
-
-#### Addon Registration Enhancement
-
-```php
-// Addon developers register with enhanced metadata
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['biteship-shipping'] = [
-        'id'           => 'biteship-shipping',
-        'name'         => 'Biteship Shipping',
-        'description'  => 'Indonesia shipping with Biteship API',
-        'version'      => '1.0.0',
-        'author'       => 'WooNooW Team',
-        'category'     => 'shipping', // NEW!
-        'icon'         => 'truck', // NEW!
-        'features'     => [ // NEW!
-            'Real-time shipping rates',
-            'Multiple couriers',
-            'Tracking integration',
-        ],
-        'settings_url' => '/settings/shipping/biteship', // NEW!
-        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
-    ];
-    return $addons;
-});
-```
-
----
-
-### Phase 2: Module Settings Page with Gear Icon
-
-#### UI Enhancement: Modules.tsx
-
-```tsx
-{modules.map((module) => (
-  <div className="flex items-start gap-4 p-4 border rounded-lg">
-    {/* Icon */}
-    <div className={`p-3 rounded-lg ${module.enabled ? 'bg-primary/10' : 'bg-muted'}`}>
-      {getIcon(module.icon)}
-    </div>
-
-    {/* Content */}
-    <div className="flex-1">
-      <div className="flex items-center gap-2 mb-1">
-        <h3 className="font-medium">{module.label}</h3>
-        {module.enabled && <Badge>Active</Badge>}
-        {module.is_addon && <Badge variant="outline">Addon</Badge>}
-      </div>
-      <p className="text-sm text-muted-foreground mb-2">{module.description}</p>
-      
-      {/* Features */}
-      <ul className="space-y-1">
-        {module.features.map((feature, i) => (
-          <li key={i} className="text-xs text-muted-foreground">
-            • {feature}
-          </li>
-        ))}
-      </ul>
-    </div>
-
-    {/* Actions */}
-    <div className="flex items-center gap-2">
-      {/* Settings Gear Icon - Only if module has settings */}
-      {module.settings_url && module.enabled && (
-        <Button
-          variant="ghost"
-          size="icon"
-          onClick={() => navigate(module.settings_url)}
-          title="Module Settings"
-        >
-          <Settings className="h-4 w-4" />
-        </Button>
-      )}
-      
-      {/* Enable/Disable Toggle */}
-      <Switch
-        checked={module.enabled}
-        onCheckedChange={(enabled) => toggleModule.mutate({ moduleId: module.id, enabled })}
-      />
-    </div>
-  </div>
-))}
-```
-
----
-
-### Phase 3: Dynamic Categories
-
-#### Support for Addon Categories
-
-```php
-// ModuleRegistry.php
-public static function get_categories() {
-    return [
-        'marketing' => __('Marketing & Sales', 'woonoow'),
-        'customers' => __('Customer Experience', 'woonoow'),
-        'products' => __('Products & Inventory', 'woonoow'),
-        'shipping' => __('Shipping & Fulfillment', 'woonoow'), // NEW!
-        'payments' => __('Payments & Checkout', 'woonoow'), // NEW!
-        'analytics' => __('Analytics & Reports', 'woonoow'), // NEW!
-        'addons' => __('Other Extensions', 'woonoow'), // Fallback
-    ];
-}
-```
-
-#### Frontend: Dynamic Category Rendering
-
-```tsx
-// Modules.tsx
-const { data: modulesData } = useQuery({
-  queryKey: ['modules'],
-  queryFn: async () => {
-    const response = await api.get('/modules');
-    return response as ModulesData;
-  },
-});
-
-// Get unique categories from modules
-const categories = Object.keys(modulesData?.grouped || {});
-
-return (
-  <SettingsLayout title="Module Management">
-    {categories.map((category) => {
-      const modules = modulesData.grouped[category] || [];
-      if (modules.length === 0) return null;
-      
-      return (
-        <SettingsCard
-          key={category}
-          title={getCategoryLabel(category)}
-          description={`Manage ${category} modules`}
-        >
-          {/* Module cards */}
-        </SettingsCard>
-      );
-    })}
-  </SettingsLayout>
-);
-```
-
----
-
-## Benefits
-
-### 1. **Unified Management**
-- ✅ One place to see all extensions (built-in + addons)
-- ✅ Consistent enable/disable interface
-- ✅ Unified metadata (icon, description, features)
-
-### 2. **Better UX**
-- ✅ Users don't need to distinguish between "modules" and "addons"
-- ✅ Settings gear icon for quick access to module configuration
-- ✅ Clear visual indication of what's enabled
-
-### 3. **Developer Experience**
-- ✅ Addon developers use familiar pattern
-- ✅ Automatic integration with module system
-- ✅ No extra work to appear in Modules page
-
-### 4. **Extensibility**
-- ✅ Dynamic categories support any addon type
-- ✅ Settings URL allows deep linking to config
-- ✅ Version and author info for better management
-
----
-
-## Example: Biteship Addon Integration
-
-### Addon Registration (PHP)
-
-```php
-<?php
-/**
- * Plugin Name: WooNooW Biteship Shipping
- * Description: Indonesia shipping with Biteship API
- * Version: 1.0.0
- * Author: WooNooW Team
- */
-
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['biteship-shipping'] = [
-        'id'           => 'biteship-shipping',
-        'name'         => 'Biteship Shipping',
-        'description'  => 'Real-time shipping rates from Indonesian couriers',
-        'version'      => '1.0.0',
-        'author'       => 'WooNooW Team',
-        'category'     => 'shipping',
-        'icon'         => 'truck',
-        'features'     => [
-            'JNE, J&T, SiCepat, and more',
-            'Real-time rate calculation',
-            'Shipment tracking',
-            'Automatic label printing',
-        ],
-        'settings_url' => '/settings/shipping/biteship',
-        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
-    ];
-    return $addons;
-});
-
-// Register settings route
-add_filter('woonoow/spa_routes', function($routes) {
-    $routes[] = [
-        'path'          => '/settings/shipping/biteship',
-        'component_url' => plugin_dir_url(__FILE__) . 'dist/Settings.js',
-        'title'         => 'Biteship Settings',
-    ];
-    return $routes;
-});
-```
-
-### Result in Modules Page
-
-```
-┌─────────────────────────────────────────────────┐
-│ Shipping & Fulfillment                          │
-├─────────────────────────────────────────────────┤
-│                                                  │
-│ 🚚 Biteship Shipping              [⚙️] [Toggle] │
-│ Real-time shipping rates from Indonesian...     │
-│ • JNE, J&T, SiCepat, and more                   │
-│ • Real-time rate calculation                    │
-│ • Shipment tracking                             │
-│ • Automatic label printing                      │
-│                                                  │
-│ Version: 1.0.0 | By: WooNooW Team | [Addon]    │
-│                                                  │
-└─────────────────────────────────────────────────┘
-```
-
-Clicking ⚙️ navigates to `/settings/shipping/biteship`
-
----
-
-## Migration Path
-
-### Step 1: Enhance ModuleRegistry (Backward Compatible)
-- Add `get_addon_modules()` method
-- Merge built-in + addon modules
-- No breaking changes
-
-### Step 2: Update Modules UI
-- Add gear icon for settings
-- Add "Addon" badge
-- Support dynamic categories
-
-### Step 3: Document for Addon Developers
-- Update ADDON_DEVELOPMENT_GUIDE.md
-- Add examples with new metadata
-- Show settings page pattern
-
-### Step 4: Update Existing Addons (Optional)
-- Addons work without changes
-- Enhanced metadata is optional
-- Settings URL is optional
-
----
-
-## API Changes
-
-### New Module Properties
-
-```typescript
-interface Module {
-  id: string;
-  label: string;
-  description: string;
-  category: string;
-  icon: string;
-  default_enabled: boolean;
-  features: string[];
-  enabled: boolean;
-  
-  // NEW for addons
-  is_addon?: boolean;
-  version?: string;
-  author?: string;
-  settings_url?: string; // Route to settings page
-}
-```
-
-### New API Endpoint (Optional)
-
-```php
-// GET /woonoow/v1/modules/:module_id/settings
-// Returns module-specific settings schema
-```
-
----
-
-## Settings Page Pattern
-
-### Option 1: Dedicated Route (Recommended)
-
-```php
-// Addon registers its own settings route
-add_filter('woonoow/spa_routes', function($routes) {
-    $routes[] = [
-        'path'          => '/settings/my-addon',
-        'component_url' => plugin_dir_url(__FILE__) . 'dist/Settings.js',
-    ];
-    return $routes;
-});
-```
-
-### Option 2: Modal/Drawer (Alternative)
-
-```tsx
-// Modules page opens modal with addon settings
-<Dialog open={settingsOpen} onOpenChange={setSettingsOpen}>
-  <DialogContent>
-    <AddonSettings moduleId={selectedModule} />
-  </DialogContent>
-</Dialog>
-```
-
----
-
-## Backward Compatibility
-
-### Existing Addons Continue to Work
-- ✅ No breaking changes
-- ✅ Enhanced metadata is optional
-- ✅ Addons without metadata still function
-- ✅ Gradual migration path
-
-### Existing Modules Unaffected
-- ✅ Built-in modules work as before
-- ✅ No changes to existing module logic
-- ✅ Only UI enhancement
-
----
-
-## Summary
-
-### What This Achieves
-
-1. **Newsletter Footer Integration** ✅
-   - Newsletter form respects module status
-   - Hidden from footer builder when disabled
-
-2. **Addon-Module Unification** 🎯
-   - Addons appear in Module Registry
-   - Same enable/disable interface
-   - Settings gear icon for configuration
-
-3. **Better Developer Experience** 🎯
-   - Consistent registration pattern
-   - Automatic UI integration
-   - Optional settings page routing
-
-4. **Better User Experience** 🎯
-   - One place to manage all extensions
-   - Clear visual hierarchy
-   - Quick access to settings
-
-### Next Steps
-
-1. ✅ Newsletter footer integration (DONE)
-2. 🎯 Enhance ModuleRegistry for addon support
-3. 🎯 Add settings URL support to Modules UI
-4. 🎯 Update documentation
-5. 🎯 Create example addon with settings
-
----
-
-**This creates a truly unified extension system where built-in modules and external addons are first-class citizens with the same management interface.**

ADDON_REACT_INTEGRATION.md

@@ -1,499 +0,0 @@
-# Addon React Integration - How It Works
-
-## The Question
-
-**"How can addon developers use React if we only ship built `app.js`?"**
-
-You're absolutely right to question this! Let me clarify the architecture.
-
----
-
-## Current Misunderstanding
-
-**What I showed in examples:**
-```tsx
-// This WON'T work for external addons!
-import { addonLoader, addFilter } from '@woonoow/hooks';
-import { DestinationSearch } from './components/DestinationSearch';
-
-addonLoader.register({
-  id: 'rajaongkir-bridge',
-  init: () => {
-    addFilter('woonoow_order_form_after_shipping', (content) => {
-      return <DestinationSearch />; // ❌ Can't do this!
-    });
-  }
-});
-```
-
-**Problem:** External addons can't import React components because:
-1. They don't have access to our build pipeline
-2. They only get the compiled `app.js`
-3. React is bundled, not exposed
-
----
-
-## Solution: Three Integration Levels
-
-### **Level 1: Vanilla JS/jQuery** (Basic)
-
-**For simple addons that just need to inject HTML/JS**
-
-```javascript
-// addon-bridge.js (vanilla JS, no build needed)
-(function() {
-  // Wait for WooNooW to load
-  window.addEventListener('woonoow:loaded', function() {
-    // Access WooNooW hooks
-    window.WooNooW.addFilter('woonoow_order_form_after_shipping', function(container, formData) {
-      // Inject HTML
-      const div = document.createElement('div');
-      div.innerHTML = `
-        <div class="rajaongkir-destination">
-          <label>Shipping Destination</label>
-          <select id="rajaongkir-dest">
-            <option>Select destination...</option>
-          </select>
-        </div>
-      `;
-      container.appendChild(div);
-      
-      // Add event listeners
-      document.getElementById('rajaongkir-dest').addEventListener('change', function(e) {
-        // Update WooNooW state
-        window.WooNooW.updateFormData({
-          shipping: {
-            ...formData.shipping,
-            destination_id: e.target.value
-          }
-        });
-      });
-      
-      return container;
-    });
-  });
-})();
-```
-
-**Pros:**
-- ✅ No build process needed
-- ✅ Works immediately
-- ✅ Easy for PHP developers
-- ✅ No dependencies
-
-**Cons:**
-- ❌ No React benefits
-- ❌ Manual DOM manipulation
-- ❌ No type safety
-
----
-
-### **Level 2: Exposed React Runtime** (Recommended)
-
-**WooNooW exposes React on window for addons to use**
-
-#### WooNooW Core Setup:
-
-```typescript
-// admin-spa/src/main.tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-
-// Expose React for addons
-window.WooNooW = {
-  React: React,
-  ReactDOM: ReactDOM,
-  hooks: {
-    addFilter: addFilter,
-    addAction: addAction,
-    // ... other hooks
-  },
-  components: {
-    // Expose common components
-    Button: Button,
-    Input: Input,
-    Select: Select,
-    // ... other UI components
-  }
-};
-```
-
-#### Addon Development (with build):
-
-```javascript
-// addon-bridge.js (built with Vite/Webpack)
-const { React, hooks, components } = window.WooNooW;
-const { addFilter } = hooks;
-const { Button, Select } = components;
-
-// Addon can now use React!
-function DestinationSearch({ value, onChange }) {
-  const [destinations, setDestinations] = React.useState([]);
-  const [loading, setLoading] = React.useState(false);
-  
-  React.useEffect(() => {
-    // Fetch destinations
-    fetch('/wp-json/rajaongkir/v1/destinations')
-      .then(res => res.json())
-      .then(data => setDestinations(data));
-  }, []);
-  
-  return React.createElement('div', { className: 'rajaongkir-search' },
-    React.createElement('label', null, 'Shipping Destination'),
-    React.createElement(Select, {
-      value: value,
-      onChange: onChange,
-      options: destinations,
-      loading: loading
-    })
-  );
-}
-
-// Register with WooNooW
-addFilter('woonoow_order_form_after_shipping', function(container, formData, setFormData) {
-  const root = ReactDOM.createRoot(container);
-  root.render(
-    React.createElement(DestinationSearch, {
-      value: formData.shipping?.destination_id,
-      onChange: (value) => setFormData({
-        ...formData,
-        shipping: { ...formData.shipping, destination_id: value }
-      })
-    })
-  );
-  return container;
-});
-```
-
-**Addon Build Setup:**
-
-```javascript
-// vite.config.js
-export default {
-  build: {
-    lib: {
-      entry: 'src/addon.js',
-      name: 'RajaongkirBridge',
-      fileName: 'addon'
-    },
-    rollupOptions: {
-      external: ['react', 'react-dom'], // Don't bundle React
-      output: {
-        globals: {
-          react: 'window.WooNooW.React',
-          'react-dom': 'window.WooNooW.ReactDOM'
-        }
-      }
-    }
-  }
-};
-```
-
-**Pros:**
-- ✅ Can use React
-- ✅ Access to WooNooW components
-- ✅ Better DX
-- ✅ Type safety (with TypeScript)
-
-**Cons:**
-- ❌ Requires build process
-- ❌ More complex setup
-
----
-
-### **Level 3: Slot-Based Rendering** (Advanced)
-
-**WooNooW renders addon components via slots**
-
-#### WooNooW Core:
-
-```typescript
-// OrderForm.tsx
-function OrderForm() {
-  // ... form logic
-  
-  return (
-    <div>
-      {/* ... shipping fields ... */}
-      
-      {/* Slot for addons to inject */}
-      <AddonSlot 
-        name="order_form_after_shipping"
-        props={{ formData, setFormData }}
-      />
-    </div>
-  );
-}
-
-// AddonSlot.tsx
-function AddonSlot({ name, props }) {
-  const slots = useAddonSlots(name);
-  
-  return (
-    <>
-      {slots.map((slot, index) => (
-        <div key={index} data-addon-slot={slot.id}>
-          {slot.component(props)}
-        </div>
-      ))}
-    </>
-  );
-}
-```
-
-#### Addon Registration (PHP):
-
-```php
-// rajaongkir-bridge.php
-add_filter('woonoow/addon_slots', function($slots) {
-    $slots['order_form_after_shipping'][] = [
-        'id' => 'rajaongkir-destination',
-        'component' => 'RajaongkirDestination', // Component name
-        'script' => plugin_dir_url(__FILE__) . 'dist/addon.js',
-        'priority' => 10,
-    ];
-    return $slots;
-});
-```
-
-#### Addon Component (React with build):
-
-```typescript
-// addon/src/DestinationSearch.tsx
-import React, { useState, useEffect } from 'react';
-
-export function RajaongkirDestination({ formData, setFormData }) {
-  const [destinations, setDestinations] = useState([]);
-  
-  useEffect(() => {
-    fetch('/wp-json/rajaongkir/v1/destinations')
-      .then(res => res.json())
-      .then(setDestinations);
-  }, []);
-  
-  return (
-    <div className="rajaongkir-destination">
-      <label>Shipping Destination</label>
-      <select
-        value={formData.shipping?.destination_id || ''}
-        onChange={(e) => setFormData({
-          ...formData,
-          shipping: {
-            ...formData.shipping,
-            destination_id: e.target.value
-          }
-        })}
-      >
-        <option value="">Select destination...</option>
-        {destinations.map(dest => (
-          <option key={dest.id} value={dest.id}>
-            {dest.label}
-          </option>
-        ))}
-      </select>
-    </div>
-  );
-}
-
-// Export for WooNooW to load
-window.WooNooWAddons = window.WooNooWAddons || {};
-window.WooNooWAddons.RajaongkirDestination = RajaongkirDestination;
-```
-
-**Pros:**
-- ✅ Full React support
-- ✅ Type safety
-- ✅ Modern DX
-- ✅ Proper component lifecycle
-
-**Cons:**
-- ❌ Most complex
-- ❌ Requires build process
-- ❌ More WooNooW core complexity
-
----
-
-## Recommended Approach: Level 2 (Exposed React)
-
-### Implementation in WooNooW Core:
-
-```typescript
-// admin-spa/src/main.tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { QueryClient } from '@tanstack/react-query';
-
-// UI Components
-import { Button } from '@/components/ui/button';
-import { Input } from '@/components/ui/input';
-import { Select } from '@/components/ui/select';
-import { Label } from '@/components/ui/label';
-// ... other components
-
-// Hooks
-import { addFilter, addAction, applyFilters, doAction } from '@/lib/hooks';
-
-// Expose WooNooW API
-window.WooNooW = {
-  // React runtime
-  React: React,
-  ReactDOM: ReactDOM,
-  
-  // Hooks system
-  hooks: {
-    addFilter,
-    addAction,
-    applyFilters,
-    doAction,
-  },
-  
-  // UI Components (shadcn/ui)
-  components: {
-    Button,
-    Input,
-    Select,
-    Label,
-    // ... expose commonly used components
-  },
-  
-  // Utilities
-  utils: {
-    api: api, // API client
-    toast: toast, // Toast notifications
-  },
-  
-  // Version
-  version: '1.0.0',
-};
-
-// Emit loaded event
-window.dispatchEvent(new CustomEvent('woonoow:loaded'));
-```
-
-### Addon Developer Experience:
-
-#### Option 1: Vanilla JS (No Build)
-
-```javascript
-// addon.js
-(function() {
-  const { React, hooks, components } = window.WooNooW;
-  const { addFilter } = hooks;
-  const { Select } = components;
-  
-  addFilter('woonoow_order_form_after_shipping', function(container, props) {
-    // Use React.createElement (no JSX)
-    const element = React.createElement(Select, {
-      label: 'Destination',
-      options: [...],
-      value: props.formData.shipping?.destination_id,
-      onChange: (value) => props.setFormData({...})
-    });
-    
-    const root = ReactDOM.createRoot(container);
-    root.render(element);
-    
-    return container;
-  });
-})();
-```
-
-#### Option 2: With Build (JSX Support)
-
-```typescript
-// addon/src/index.tsx
-const { React, hooks, components } = window.WooNooW;
-const { addFilter } = hooks;
-const { Select } = components;
-
-function DestinationSearch({ formData, setFormData }) {
-  return (
-    <Select
-      label="Destination"
-      options={[...]}
-      value={formData.shipping?.destination_id}
-      onChange={(value) => setFormData({
-        ...formData,
-        shipping: { ...formData.shipping, destination_id: value }
-      })}
-    />
-  );
-}
-
-addFilter('woonoow_order_form_after_shipping', (container, props) => {
-  const root = ReactDOM.createRoot(container);
-  root.render(<DestinationSearch {...props} />);
-  return container;
-});
-```
-
-```javascript
-// vite.config.js
-export default {
-  build: {
-    lib: {
-      entry: 'src/index.tsx',
-      formats: ['iife'],
-      name: 'RajaongkirAddon'
-    },
-    rollupOptions: {
-      external: ['react', 'react-dom'],
-      output: {
-        globals: {
-          react: 'window.WooNooW.React',
-          'react-dom': 'window.WooNooW.ReactDOM'
-        }
-      }
-    }
-  }
-};
-```
-
----
-
-## Documentation for Addon Developers
-
-### Quick Start Guide:
-
-```markdown
-# WooNooW Addon Development
-
-## Level 1: Vanilla JS (Easiest)
-
-No build process needed. Just use `window.WooNooW` API.
-
-## Level 2: React with Build (Recommended)
-
-1. Setup project:
-   npm init
-   npm install --save-dev vite @types/react
-
-2. Configure vite.config.js (see example above)
-
-3. Use WooNooW's React:
-   const { React } = window.WooNooW;
-
-4. Build:
-   npm run build
-
-5. Enqueue in WordPress:
-   wp_enqueue_script('my-addon', plugin_dir_url(__FILE__) . 'dist/addon.js', ['woonoow-admin'], '1.0.0', true);
-```
-
----
-
-## Summary
-
-**Your concern was valid!** ✅
-
-**Solution:**
-1. ✅ Expose React on `window.WooNooW.React`
-2. ✅ Expose common components on `window.WooNooW.components`
-3. ✅ Addons can use vanilla JS (no build) or React (with build)
-4. ✅ Addons don't bundle React (use ours)
-5. ✅ Proper documentation for developers
-
-**Result:**
-- Simple addons: Vanilla JS, no build
-- Advanced addons: React with build, external React
-- Best of both worlds!

AFFILIATE_MODULE_REPORT.md

@@ -0,0 +1,621 @@
+# Affiliate Module - Implementation Report
+
+**Document Version:** 1.0
+**Date:** 2026-05-31
+**Module:** WooNooW Affiliate Program
+
+---
+
+## Table of Contents
+
+1. [Implementation Summary](#implementation-summary)
+2. [Backend (PHP)](#backend-php)
+3. [Admin SPA](#admin-spa)
+4. [Customer SPA](#customer-spa)
+5. [Gaps & Defects](#gaps--defects)
+6. [Opportunities](#opportunities)
+
+---
+
+## Implementation Summary
+
+| Area | Status | Coverage | Production Ready |
+|------|--------|----------|-----------------|
+| Referral Tracking | Working (Main Path) | ~90% | ⚠️ |
+| Order Lifecycle | Partial | ~70% | ⚠️ |
+| Backend API | Partial | ~70% | ⚠️ |
+| Customer Dashboard | Partial | ~60% | ⚠️ |
+| Admin SPA | Partial | ~50% | ⚠️ |
+| Email Notifications | Partial | ~50% | ⚠️ |
+| Payout System | Placeholder | 0% | ❌ |
+
+**Overall Assessment:** Foundation is solid with clean architecture. Referral tracking works for standard page-load checkout flows, but still needs hardening for block-based checkout and dynamic URL handling. Payout system is the critical gap preventing production use.
+
+### What Works Well
+
+- **Clean separation of concerns** — Module bootstrap, tracking, lifecycle, settings are distinct files
+- **Multiple checkout hooks** — Works with legacy checkout and admin order creation
+- **Order lifecycle handling** — Refunds/cancellations properly reject referrals with clawback
+- **Customer dashboard** — Functional with proper currency formatting
+- **Admin order integration** — Shows affiliate attribution in order details
+
+### What's Working (Main Path)
+
+- Cookie-based referral tracking on standard page loads
+- Affiliate application and approval flow
+- Commission calculation on order completion
+- Auto-approval via Action Scheduler after holding period
+- Order refund/cancellation → referral rejection with clawback
+
+### What's Still Needs Hardening
+
+- **Block checkout compatibility** — Cookie capture relies on `init` hook; may miss AJAX-based checkout flows
+- **Dynamic referral link** — Current implementation assumes `/shop` path; needs site-config-aware URL generation
+- **Edge case handling** — Invalid referral codes, expired cookies, cross-device attribution not fully tested
+
+### What's Missing for Production
+
+1. **Payout workflow** — Cannot pay affiliates (blocking)
+2. **Per-affiliate commission override** — No custom rates (high priority)
+3. **Self-referral override** — No admin whitelist (high priority)
+4. **Referral detail transparency** — Customer can't see order details (medium)
+
+---
+
+## Backend (PHP)
+
+### Files Implemented
+
+| File | Path | Purpose |
+|------|------|---------|
+| AffiliateModule.php | `/includes/Modules/Affiliate/` | Bootstrap & initialization |
+| AffiliateManager.php | `/includes/Modules/Affiliate/` | Database table creation |
+| AffiliateTracker.php | `/includes/Modules/Affiliate/` | Referral tracking & cookie handling |
+| AffiliateLifecycle.php | `/includes/Modules/Affiliate/` | Order status/cancellation handling |
+| AffiliateSettings.php | `/includes/Modules/Affiliate/` | Module settings schema |
+| AffiliateAdminController.php | `/includes/Api/Controllers/` | Admin API endpoints |
+| AffiliateCustomerController.php | `/includes/Api/Controllers/` | Customer API endpoints |
+
+### Database Tables
+
+#### `wp_woonoow_affiliates`
+| Column | Type | Notes |
+|--------|------|-------|
+| id | bigint | Primary key |
+| user_id | bigint | Links to WP users |
+| referral_code | varchar(50) | Unique affiliate code |
+| coupon_id | bigint | Optional WC coupon link |
+| commission_rate | decimal(10,2) | Percentage |
+| status | varchar(20) | pending/active/rejected |
+| total_referrals | int | Counter |
+| total_earnings | decimal(19,4) | Accumulated earnings |
+| paid_earnings | decimal(19,4) | Paid out amount |
+| created_at | datetime | |
+| updated_at | datetime | Auto-update |
+
+#### `wp_woonoow_referrals`
+| Column | Type | Notes |
+|--------|------|-------|
+| id | bigint | Primary key |
+| affiliate_id | bigint | FK to affiliates |
+| order_id | bigint | WooCommerce order |
+| customer_id | bigint | Customer user ID |
+| commission_amount | decimal(19,4) | Calculated commission |
+| currency | varchar(10) | Default USD |
+| status | varchar(20) | pending/approved/rejected |
+| cancelled_reason | varchar(50) | WHY rejected |
+| cancelled_at | datetime | When cancelled |
+| created_at | datetime | |
+| approved_at | datetime | When approved |
+| paid_at | datetime | When paid |
+
+#### `wp_woonoow_affiliate_payouts`
+| Column | Type | Notes |
+|--------|------|-------|
+| id | bigint | Primary key |
+| affiliate_id | bigint | FK |
+| amount | decimal(19,4) | |
+| currency | varchar(10) | |
+| method | varchar(50) | Payment method |
+| status | varchar(20) | pending/completed |
+| notes | text | |
+| created_at | datetime | |
+| completed_at | datetime | |
+
+### API Endpoints
+
+#### Admin Endpoints (`/woonoow/v1/admin/affiliates`)
+| Method | Endpoint | Function | Implemented |
+|--------|----------|----------|-------------|
+| GET | `/` | `get_affiliates()` | ✅ |
+| POST | `/(?P<id>\d+)/approve` | `approve_affiliate()` | ✅ |
+| GET | `/referrals` | `get_referrals()` | ✅ |
+| POST | `/payouts` | `create_payout()` | ✅ |
+
+#### Customer Endpoints (`/woonoow/v1/account/affiliate`)
+| Method | Endpoint | Function | Implemented |
+|--------|----------|----------|-------------|
+| GET | `/` | `get_dashboard()` | ✅ |
+| POST | `/apply` | `apply_affiliate()` | ✅ |
+| GET | `/referrals` | `get_referrals()` | ✅ |
+
+### Hooks & Tracking
+
+| Hook | Handler | Status | Notes |
+|------|---------|--------|-------|
+| `init` | `capture_referral_link()` | ✅ | Captures `?ref=` from URL |
+| `woocommerce_checkout_order_processed` | `record_referral()` | ✅ | Legacy checkout |
+| `woocommerce_store_api_checkout_order_processed` | `record_referral_block()` | ✅ | Block checkout (WC 8.3+) |
+| `woocommerce_new_order` | `record_referral_new_order()` | ✅ | Universal fallback |
+| `woocommerce_process_shop_order_meta` | `record_referral_admin()` | ✅ | Admin order creation |
+| `woocommerce_order_status_refunded` | `handle_order_cancelled()` | ✅ | |
+| `woocommerce_order_status_cancelled` | `handle_order_cancelled()` | ✅ | |
+| `woocommerce_order_status_failed` | `handle_order_cancelled()` | ✅ | |
+| `before_delete_post` | `handle_order_deleted()` | ✅ | |
+| `woocommerce_delete_order` | `handle_order_deleted()` | ✅ | |
+
+**Tracking Coverage:** All WooCommerce order creation paths are hooked. Cookie capture works on standard page loads.
+
+### Email Notifications
+
+| Event ID | Template | Status |
+|----------|----------|--------|
+| `affiliate_application_received` | Staff notification | ✅ |
+| `affiliate_application_approved` | Customer welcome | ✅ |
+| `affiliate_new_referral` | Commission earned | ✅ |
+
+---
+
+## Admin SPA
+
+### Routes
+
+| Route | Component | Implemented |
+|-------|-----------|-------------|
+| `/marketing/affiliates` | AffiliatesLayout | ✅ |
+| `/marketing/affiliates/list` | AffiliatesList | ✅ |
+| `/marketing/affiliates/referrals` | AffiliatesReferrals | ✅ |
+| `/marketing/affiliates/payouts` | AffiliatesPayouts | ⚠️ Placeholder |
+
+### Features Implemented
+
+#### AffiliatesList
+- Search by referral code
+- Display table: User ID, Code, Rate, Status, Earnings, Actions
+- Approve button for pending affiliates
+- Status badges (color-coded)
+
+#### AffiliatesReferrals
+- Display all referrals table
+- Columns: ID, Affiliate ID, Order ID, Status, Date, Commission
+- Status badges
+
+#### AffiliatesPayouts
+- **NOT IMPLEMENTED** - Shows "coming soon" placeholder
+
+### Order Details Integration
+
+The order detail page (`/orders/{id}`) now shows affiliate information:
+- Affiliate name
+- Commission rate
+- Commission amount
+- Status with cancellation reason
+
+---
+
+## Customer SPA
+
+### Routes
+
+| Route | Component | Implemented |
+|-------|-----------|-------------|
+| `/my-account/affiliate` | AffiliateDashboard | ✅ |
+
+### Features Implemented
+
+#### Application Flow
+- "Join Affiliate Program" card with Apply Now button
+- Pending status notification when awaiting approval
+
+#### Dashboard (Active Affiliates)
+- Total Earnings card
+- Pending Earnings card
+- Commission Rate display
+- Referral link generator with copy button
+- Recent Referrals table
+
+### Format Issues (Fixed)
+- Currency formatting now uses site's WooCommerce settings
+- IDR displays as `Rp19.900` (no decimals, thousand separator)
+- Other currencies use configured decimals
+
+---
+
+## Gaps & Defects
+
+### Critical (Blocking)
+
+#### 1. Payout System Not Functional
+**Location:** Admin & Backend
+**Severity:** Critical
+**Issue:** The payout creation API (`create_payout()`) exists but:
+- No UI to initiate payouts in Admin SPA (placeholder only)
+- No calculation of payable balance (`total_earnings - paid_earnings`)
+- No payout history view
+- No payment processing (only store_credit implemented)
+
+**Impact:** Cannot pay affiliates — program is incomplete
+
+**Required Fix:**
+```php
+// AffiliateAdminController.php
+public static function get_affiliate_balance($affiliate_id) {
+    global $wpdb;
+    $table = $wpdb->prefix . 'woonoow_affiliates';
+    $affiliate = $wpdb->get_row($wpdb->prepare(
+        "SELECT total_earnings, paid_earnings FROM $table WHERE id = %d",
+        $affiliate_id
+    ));
+    return [
+        'total_earnings' => (float) $affiliate->total_earnings,
+        'paid_earnings' => (float) $affiliate->paid_earnings,
+        'payable_balance' => (float) $affiliate->total_earnings - (float) $affiliate->paid_earnings
+    ];
+}
+```
+
+#### 2. Referral Link Hardcoded to `/shop`
+**Location:** Customer SPA - AffiliateDashboard.tsx
+**Severity:** Critical
+**Issue:**
+```typescript
+// Current (hardcoded)
+const referralLink = `${window.location.origin}${window.location.pathname.replace('/my-account/affiliate', '/shop')}?ref=${profile.referral_code}`;
+```
+
+- Assumes shop page exists at `/shop`
+- Doesn't check site's actual SPA mode or base path
+- May 404 or redirect incorrectly on different configurations
+
+**Required Fix:**
+```typescript
+// Get from WooNooW config
+const basePath = (window as any).woonoowCustomer?.basePath || '';
+const shopPath = basePath + '/shop'; // or wc_get_page_id('shop') permalink
+```
+
+### High (Important)
+
+#### 3. No Cookie Capture on Block Checkout
+**Location:** Backend - AffiliateTracker.php
+**Severity:** High
+**Issue:** `capture_referral_link()` only fires on `init`. Block-based checkout may:
+- Load via AJAX without full page reload
+- Use Store API without triggering WordPress `init`
+- Miss the `?ref=` parameter entirely
+
+**Impact:** Some block checkout flows may lose referral attribution
+
+**Required Fix:**
+Referral attribution must remain reliable across all WooCommerce checkout variants and navigation patterns. The persistence mechanism (cookie, localStorage, server-side session) is secondary to ensuring the `?ref=` parameter is captured and associated with the order regardless of how the customer navigates to checkout.
+
+```php
+// AffiliateTracker.php - Ensure referral is captured before order creation
+// Option 1: Check for ref in session/storage on order hooks
+// Option 2: Ensure PHP session captures ref via frontend AJAX call
+// Option 3: Store ref in order meta during checkout for guaranteed attribution
+```
+
+#### 4. Self-Referral Block Has No Override
+**Location:** Backend - AffiliateTracker.php:133-135
+**Severity:** High
+**Issue:**
+```php
+if ((int)$order->get_user_id() === (int)$affiliate->user_id) {
+    return; // Blocks all self-referrals
+}
+```
+
+No admin option to:
+- Allow self-referrals for testing
+- Whitelist specific affiliate-customer pairs
+- Override after verification
+
+**Impact:** Cannot test with same account (must use different customer account)
+
+#### 5. No Per-Affiliate Commission Override
+**Location:** Backend + Database
+**Severity:** High
+**Issue:**
+- All affiliates use global `woonoow_affiliate_default_rate` setting
+- No ability to set custom rate per affiliate
+- No ability to override for special cases
+
+**Impact:** Limited merchant flexibility for VIP affiliates
+
+### Medium (Should Fix)
+
+#### 6. No Referral Filtering in Admin
+**Location:** Admin SPA - Referrals.tsx
+**Severity:** Medium
+**Issue:** AffiliatesReferrals shows ALL referrals. No:
+- Filter by affiliate
+- Filter by date range
+- Filter by status
+- Filter by order
+
+**Impact:** Hard to track specific affiliate performance
+
+#### 7. Affiliate Cannot See Referral Details
+**Location:** Customer SPA - AffiliateDashboard.tsx
+**Severity:** Medium
+**Issue:** Dashboard shows order ID and commission only. No:
+- Order date
+- Product details
+- Commission status explanation
+- When payment will be released
+
+**Impact:** Low trust due to lack of transparency
+
+#### 8. Commission Based on Subtotal Only
+**Location:** Backend - AffiliateTracker.php:139-144
+**Severity:** Medium
+**Issue:**
+```php
+$subtotal = (float)$order->get_subtotal();
+$commission_amount = ($subtotal * $commission_rate) / 100;
+```
+
+- Does not account for taxes
+- Does not account for shipping
+- Does not account for discounts
+
+**Impact:** Affiliates may dispute calculated amounts (requires clear documentation)
+
+### Low (Nice to Have)
+
+#### 9. No Admin Dashboard Metrics
+**Location:** Admin SPA
+**Severity:** Low
+**Issue:** No summary cards showing:
+- Total affiliates count
+- Active vs pending breakdown
+- Total commission paid
+- Conversion rate
+
+**Impact:** Hard to assess program health at a glance
+
+#### 10. No Email Template Customization
+**Location:** Backend - Email System
+**Severity:** Low
+**Issue:**
+- Templates hardcoded in DefaultTemplates.php
+- No admin settings for customization
+- No branding options
+
+**Impact:** Limited to default styling
+
+---
+
+## Opportunities
+
+### Priority 1: Operational Completeness (Must-Have)
+
+These features make the affiliate module operationally functional — without them, merchants cannot run a real affiliate program.
+
+#### 1. Complete Payout System
+**Status:** Placeholder (0% implemented)
+**Scope:** Backend + Admin SPA
+
+Payout is not a secondary detail — it is the final proof that the system works. Merchants need to be able to:
+
+- [ ] Calculate payable balance per affiliate (`total_earnings - paid_earnings`)
+- [ ] View payout history per affiliate
+- [ ] Create payouts with amount input (not auto-all)
+- [ ] Support multiple payout methods (Bank Transfer, PayPal, Store Credit)
+- [ ] Mark payouts as pending → completed
+- [ ] Send payout notification email to affiliate
+
+**API required:**
+- `GET /admin/affiliates/payouts` - List all payouts
+- `GET /admin/affiliates/{id}/balance` - Get payable balance
+- `POST /admin/affiliates/{id}/payout` - Create payout
+
+#### 2. Attribution Reliability & Tracking Rules
+**Status:** Partial (works for most cases)
+**Scope:** Backend
+
+Silent attribution failures damage trust quickly. Need to ensure:
+
+- [ ] Referral link adapts to site's actual SPA structure (not hardcoded `/shop`)
+- [ ] Cookie capture works for AJAX/block checkout flows (not just page reload)
+- [ ] Referral codes are case-insensitive during lookup
+- [ ] Invalid/expired referral codes handled gracefully (no errors)
+
+**Technical approach:**
+```php
+// Dynamic referral link generation
+$shop_page = get_permalink(wc_get_page_id('shop'));
+$referral_link = add_query_arg('ref', $referral_code, $shop_page);
+```
+
+#### 3. Commission Management & Overrides
+**Status:** Global rate only (no per-affiliate override)
+**Scope:** Backend + Admin SPA
+
+Merchants need granular control:
+
+- [ ] Set custom commission rate per affiliate (override global default)
+- [ ] Manually adjust commission amount per referral
+- [ ] Set custom holding period per affiliate
+- [ ] Mark referral as "Manual Adjustment" with audit trail
+- [ ] Commission calculation rules (subtotal vs total, include/exclude tax, etc.)
+
+**Database consideration:**
+Add `custom_commission_rate` column to `wp_woonoow_affiliates` (nullable, uses default if null).
+
+---
+
+### Priority 2: Transparency & Trust (Should-Have)
+
+These features build trust with both merchants and affiliates through visibility and control.
+
+#### 4. Admin Performance Dashboard
+**Status:** Basic list only (no metrics)
+**Scope:** Admin SPA
+
+Merchants need to assess program health:
+
+- [ ] Summary cards: Total Affiliates, Active vs Pending, Total Commission (approved), Unpaid Commission
+- [ ] Conversion rate: Applications vs Approved
+- [ ] Top performing affiliates
+- [ ] Monthly earnings trend chart
+- [ ] Export to CSV/Excel
+
+#### 5. Customer Dashboard Transparency
+**Status:** Basic (earnings + recent referrals)
+**Scope:** Customer SPA
+
+Affiliates need to trust the system:
+
+- [ ] Referral status breakdown (pending approval vs approved vs paid)
+- [ ] "When will I get paid?" indicator (holding period countdown)
+- [ ] Referral detail view: which order, what commission, current status
+- [ ] Payout history view (coming when payout system is complete)
+
+**Example referral detail card:**
+```
+Order #476 • May 30, 2026
+Commission: Rp19.900
+Status: Pending (3 days until approval)
+Product: Design Mockup Bundle
+```
+
+#### 6. Trust & Compliance Layer
+**Status:** Basic self-referral check only
+**Scope:** Backend (core trust layer, not nice-to-have)
+
+Affiliate systems are always exposed to abuse. Define anti-fraud rules early:
+
+- [ ] Self-referral block with admin exception/override
+- [ ] Suspicious order flagging (unusually high value from new customer)
+- [ ] Rate limiting on referral code generation per IP
+- [ ] Audit log for manual commission adjustments
+- [ ] Clear commission rules documentation (what's included/excluded)
+
+**Database consideration:**
+Add `fraud_score` column to `wp_woonoow_referrals` for future ML-based scoring.
+
+---
+
+### Priority 3: Scalability Features (Nice-to-Have)
+
+These enable growth but are not blocking for initial launch.
+
+#### 7. Enhanced Referral Tracking
+**Scope:** Backend
+
+- [ ] Track referral source (email, social, direct, paid)
+- [ ] Store click data (IP, user agent, timestamp)
+- [ ] UTM parameter capture
+- [ ] Cross-device tracking (logged-in users)
+
+#### 8. Referral Filtering & Search
+**Scope:** Admin SPA
+
+- [ ] Filter by affiliate
+- [ ] Filter by date range
+- [ ] Filter by status (pending/approved/rejected)
+- [ ] Filter by order ID
+- [ ] Search by customer email (anonymized display)
+
+#### 9. Affiliate Self-Service Portal
+**Scope:** Customer SPA
+
+- [ ] Update payment details (bank account, PayPal)
+- [ ] View payout history
+- [ ] Download referral reports (CSV)
+- [ ] Tax document download (1099 placeholder)
+
+---
+
+### Future Roadmap (Post-MVP)
+
+These are growth features, not near-term priorities. Merchants care about correctness first.
+
+#### Multi-Tier Commissions
+- Volume-based tiers (10% for 0-10 referrals, 15% for 11-50, etc.)
+- Requires: Tier configuration UI, recalculation on new referral
+
+#### Integration Ecosystem
+- WooCommerce Currency Switcher compatibility
+- Export to accounting software (Xero, QuickBooks)
+- Zapier/Make integrations for automation
+
+#### Gamification
+- Achievement badges (First Referral, Top Performer)
+- Leaderboards
+- Referral contests with goals and rewards
+
+#### MLM Structure
+- Multi-level marketing (not recommended for most WooCommerce setups)
+- Keep lower priority unless specifically requested
+
+---
+
+## Recommendations
+
+### This Sprint (Operational Core)
+
+| Task | Priority | Effort | Impact |
+|------|----------|--------|--------|
+| Fix referral link path (dynamic) | Critical | Low | Reliability |
+| Implement payout balance calculation | Critical | Medium | Completeness |
+| Add payout creation UI | Critical | Medium | Completeness |
+| Add self-referral admin override | High | Low | Trust |
+| Add referral filtering in admin | Medium | Medium | Usability |
+
+### Next Sprint (Transparency)
+
+| Task | Priority | Effort | Impact |
+|------|----------|--------|--------|
+| Admin performance dashboard | High | Medium | Visibility |
+| Customer referral detail view | High | Medium | Trust |
+| Per-affiliate commission override | High | Medium | Control |
+| Commission rules configuration | Medium | High | Flexibility |
+
+### Future (Growth)
+
+- UTM/source tracking
+- Affiliate self-service portal
+- Integration ecosystem
+- Multi-tier commissions
+
+---
+
+## File Checklist
+
+| Path | Type | Description |
+|------|------|-------------|
+| `/includes/Modules/Affiliate/AffiliateModule.php` | PHP | Module bootstrap |
+| `/includes/Modules/Affiliate/AffiliateManager.php` | PHP | DB tables |
+| `/includes/Modules/Affiliate/AffiliateTracker.php` | PHP | Tracking logic |
+| `/includes/Modules/Affiliate/AffiliateLifecycle.php` | PHP | Order lifecycle |
+| `/includes/Modules/Affiliate/AffiliateSettings.php` | PHP | Settings schema |
+| `/includes/Api/Controllers/AffiliateAdminController.php` | PHP | Admin API |
+| `/includes/Api/Controllers/AffiliateCustomerController.php` | PHP | Customer API |
+| `/admin-spa/src/routes/Marketing/Affiliates/index.tsx` | TSX | Admin layout |
+| `/admin-spa/src/routes/Marketing/Affiliates/List.tsx` | TSX | Affiliate list |
+| `/admin-spa/src/routes/Marketing/Affiliates/Referrals.tsx` | TSX | Referral list |
+| `/admin-spa/src/routes/Marketing/Affiliates/Payouts.tsx` | TSX | Payouts (placeholder) |
+| `/admin-spa/src/routes/Orders/Detail.tsx` | TSX | Order affiliate info |
+| `/customer-spa/src/pages/Account/AffiliateDashboard.tsx` | TSX | Customer dashboard |
+| `/customer-spa/src/pages/Account/index.tsx` | TSX | Account routes |
+| `/customer-spa/src/pages/Account/components/AccountLayout.tsx` | TSX | Menu integration |
+
+---
+
+*Report Version: 1.2*
+*Last Updated: 2026-05-31*
+*Generated by: Claude Code*
+*Review Status: Final - Reviewed and validated*

API_ROUTES.md

@@ -109,6 +109,31 @@ GET    /analytics/orders            # Order analytics
 GET    /analytics/customers         # Customer analytics
 ```
 
+### Licensing Module (`LicensesController.php`)
+```
+# Admin Endpoints (admin auth required)
+GET    /licenses                     # List licenses (with pagination, search)
+GET    /licenses/{id}                # Get single license
+POST   /licenses                     # Create license
+PUT    /licenses/{id}                # Update license
+DELETE /licenses/{id}                # Delete license
+
+# Public Endpoints (for client software validation)
+POST   /licenses/validate            # Validate license key
+POST   /licenses/activate            # Activate license on domain
+POST   /licenses/deactivate          # Deactivate license from domain
+
+# OAuth Endpoints (user auth required)
+GET    /licenses/oauth/validate      # Validate OAuth state and license ownership
+POST   /licenses/oauth/confirm       # Confirm activation and generate token
+```
+
+**Implementation Details:**
+- **List:** Supports pagination (`page`, `per_page`), search by key/email
+- **activate:** Supports Simple API and OAuth modes
+- **OAuth flow:** `oauth/validate` + `oauth/confirm` for secure user verification
+- See `LICENSING_MODULE.md` for full OAuth flow documentation
+
 ---
 
 ## Conflict Prevention Rules

ARCHITECTURE_DECISION_CUSTOMER_SPA.md

@@ -1,500 +0,0 @@
-# Architecture Decision: Customer-SPA Placement
-
-## The Question
-
-Should `customer-spa` be:
-- **Option A:** Built into WooNooW core plugin (alongside `admin-spa`)
-- **Option B:** Separate WooNooW theme (standalone product)
-
----
-
-## Option A: Customer-SPA in Core Plugin
-
-### Structure:
-```
-woonoow/
-├── admin-spa/          (Admin interface)
-├── customer-spa/       (Customer-facing: Cart, Checkout, My Account)
-├── includes/
-│   ├── Frontend/       (Customer frontend logic)
-│   └── Admin/          (Admin backend logic)
-└── woonoow.php
-```
-
-### Pros ✅
-
-#### 1. **Unified Product**
-- Single installation
-- Single license
-- Single update process
-- Easier for customers to understand
-
-#### 2. **Technical Cohesion**
-- Shared API endpoints
-- Shared authentication
-- Shared state management
-- Shared utilities and helpers
-
-#### 3. **Development Efficiency**
-- Shared components library
-- Shared TypeScript types
-- Shared build pipeline
-- Single codebase to maintain
-
-#### 4. **Market Positioning**
-- "Complete WooCommerce modernization"
-- Easier to sell as single product
-- Higher perceived value
-- Simpler pricing model
-
-#### 5. **User Experience**
-- Consistent design language
-- Seamless admin-to-frontend flow
-- Single settings interface
-- Unified branding
-
-### Cons ❌
-
-#### 1. **Plugin Size**
-- Larger download (~5-10MB)
-- More files to load
-- Potential performance concern
-
-#### 2. **Flexibility**
-- Users must use our frontend
-- Can't use with other themes easily
-- Less customization freedom
-
-#### 3. **Theme Compatibility**
-- May conflict with theme styles
-- Requires CSS isolation
-- More testing needed
-
----
-
-## Option B: Customer-SPA as Theme
-
-### Structure:
-```
-woonoow/ (Plugin)
-├── admin-spa/          (Admin interface only)
-└── includes/
-    └── Admin/
-
-woonoow-theme/ (Theme)
-├── customer-spa/       (Customer-facing)
-├── templates/
-└── style.css
-```
-
-### Pros ✅
-
-#### 1. **WordPress Best Practices**
-- Themes handle frontend
-- Plugins handle functionality
-- Clear separation of concerns
-- Follows WP conventions
-
-#### 2. **Flexibility**
-- Users can choose theme
-- Can create child themes
-- Easier customization
-- Better for agencies
-
-#### 3. **Market Segmentation**
-- Sell plugin separately (~$99)
-- Sell theme separately (~$79)
-- Bundle discount (~$149)
-- More revenue potential
-
-#### 4. **Lighter Plugin**
-- Smaller plugin size
-- Faster admin load
-- Only admin functionality
-- Better performance
-
-#### 5. **Theme Ecosystem**
-- Can create multiple themes
-- Different industries (fashion, electronics, etc.)
-- Premium theme marketplace
-- More business opportunities
-
-### Cons ❌
-
-#### 1. **Complexity for Users**
-- Two products to install
-- Two licenses to manage
-- Two update processes
-- More confusing
-
-#### 2. **Technical Challenges**
-- API communication between plugin/theme
-- Version compatibility issues
-- More testing required
-- Harder to maintain
-
-#### 3. **Market Confusion**
-- "Do I need both?"
-- "Why separate products?"
-- Higher barrier to entry
-- More support questions
-
-#### 4. **Development Overhead**
-- Two repositories
-- Two build processes
-- Two release cycles
-- More maintenance
-
----
-
-## Market Analysis
-
-### Target Market Segments:
-
-#### Segment 1: Small Business Owners (60%)
-**Needs:**
-- Simple, all-in-one solution
-- Easy to install and use
-- Don't care about technical details
-- Want "it just works"
-
-**Preference:** ✅ **Option A** (Core Plugin)
-- Single product easier to understand
-- Less technical knowledge required
-- Lower barrier to entry
-
-#### Segment 2: Agencies & Developers (30%)
-**Needs:**
-- Flexibility and customization
-- Can build custom themes
-- Want control over frontend
-- Multiple client sites
-
-**Preference:** ✅ **Option B** (Theme)
-- More flexibility
-- Can create custom themes
-- Better for white-label
-- Professional workflow
-
-#### Segment 3: Enterprise (10%)
-**Needs:**
-- Full control
-- Custom development
-- Scalability
-- Support
-
-**Preference:** 🤷 **Either works**
-- Will customize anyway
-- Have development team
-- Budget not a concern
-
----
-
-## Competitor Analysis
-
-### Shopify
-- **All-in-one platform**
-- Admin + Frontend unified
-- Themes available but optional
-- Core experience complete
-
-**Lesson:** Users expect complete solution
-
-### WooCommerce
-- **Plugin + Theme separation**
-- Plugin = functionality
-- Theme = design
-- Standard WordPress approach
-
-**Lesson:** Separation is familiar to WP users
-
-### SureCart
-- **All-in-one plugin**
-- Handles admin + checkout
-- Works with any theme
-- Shortcode-based frontend
-
-**Lesson:** Plugin can handle both
-
-### NorthCommerce
-- **All-in-one plugin**
-- Complete replacement
-- Own frontend + admin
-- Theme-agnostic
-
-**Lesson:** Modern solutions are unified
-
----
-
-## Technical Considerations
-
-### Performance
-
-**Option A (Core Plugin):**
-```
-Admin page load: 200KB (admin-spa)
-Customer page load: 300KB (customer-spa)
-Total plugin size: 8MB
-```
-
-**Option B (Theme):**
-```
-Admin page load: 200KB (admin-spa)
-Customer page load: 300KB (customer-spa from theme)
-Plugin size: 4MB
-Theme size: 4MB
-```
-
-**Winner:** Tie (same total load)
-
-### Maintenance
-
-**Option A:**
-- Single codebase
-- Single release
-- Easier version control
-- Less coordination
-
-**Option B:**
-- Two codebases
-- Coordinated releases
-- Version compatibility matrix
-- More complexity
-
-**Winner:** ✅ **Option A**
-
-### Flexibility
-
-**Option A:**
-- Users can disable customer-spa via settings
-- Can use with any theme (shortcodes)
-- Hybrid approach possible
-
-**Option B:**
-- Full theme control
-- Can create variations
-- Better for customization
-
-**Winner:** ✅ **Option B**
-
----
-
-## Hybrid Approach (Recommended)
-
-### Best of Both Worlds:
-
-**WooNooW Plugin (Core):**
-```
-woonoow/
-├── admin-spa/              (Always active)
-├── customer-spa/           (Optional, can be disabled)
-├── includes/
-│   ├── Admin/
-│   └── Frontend/
-│       ├── Shortcodes/     (For any theme)
-│       └── SPA/            (Full SPA mode)
-└── woonoow.php
-```
-
-**Settings:**
-```php
-// WooNooW > Settings > Developer
-Frontend Mode:
-○ Disabled (use theme)
-● Shortcodes (hybrid - works with any theme)
-○ Full SPA (replace theme frontend)
-```
-
-**WooNooW Themes (Optional):**
-```
-woonoow-theme-storefront/   (Free, basic)
-woonoow-theme-fashion/      (Premium, $79)
-woonoow-theme-electronics/  (Premium, $79)
-```
-
-### How It Works:
-
-#### Mode 1: Disabled
-- Plugin only provides admin-spa
-- Theme handles all frontend
-- For users who want full theme control
-
-#### Mode 2: Shortcodes (Default)
-- Plugin provides cart/checkout/account components
-- Works with ANY theme
-- Hybrid approach (SSR + SPA islands)
-- Best compatibility
-
-#### Mode 3: Full SPA
-- Plugin takes over entire frontend
-- Theme only provides header/footer
-- Maximum performance
-- For performance-critical sites
-
----
-
-## Revenue Model Comparison
-
-### Option A: Unified Plugin
-
-**Pricing:**
-- WooNooW Plugin: $149/year
-- Includes admin + customer SPA
-- All features
-
-**Projected Revenue (1000 customers):**
-- $149,000/year
-
-### Option B: Separate Products
-
-**Pricing:**
-- WooNooW Plugin (admin only): $99/year
-- WooNooW Theme: $79/year
-- Bundle: $149/year (save $29)
-
-**Projected Revenue (1000 customers):**
-- 60% buy bundle: $89,400
-- 30% buy plugin only: $29,700
-- 10% buy both separately: $17,800
-- **Total: $136,900/year**
-
-**Winner:** ✅ **Option A** ($12,100 more revenue)
-
-### Option C: Hybrid Approach
-
-**Pricing:**
-- WooNooW Plugin (includes basic customer-spa): $149/year
-- Premium Themes: $79/year each
-- Bundle (plugin + premium theme): $199/year
-
-**Projected Revenue (1000 customers):**
-- 70% plugin only: $104,300
-- 20% plugin + theme bundle: $39,800
-- 10% plugin + multiple themes: $20,000
-- **Total: $164,100/year**
-
-**Winner:** ✅ **Option C** ($27,200 more revenue!)
-
----
-
-## Recommendation: Hybrid Approach (Option C)
-
-### Implementation:
-
-**Phase 1: Core Plugin with Customer-SPA**
-```
-woonoow/
-├── admin-spa/          ✅ Full admin interface
-├── customer-spa/       ✅ Basic cart/checkout/account
-│   ├── Cart.tsx
-│   ├── Checkout.tsx
-│   └── MyAccount.tsx
-└── includes/
-    ├── Admin/
-    └── Frontend/
-        ├── Shortcodes/  ✅ [woonoow_cart], [woonoow_checkout]
-        └── SPA/         ✅ Full SPA mode (optional)
-```
-
-**Phase 2: Premium Themes (Optional)**
-```
-woonoow-theme-fashion/
-├── customer-spa/       ✅ Enhanced components
-│   ├── ProductCard.tsx
-│   ├── CategoryGrid.tsx
-│   └── SearchBar.tsx
-└── templates/
-    ├── header.php
-    └── footer.php
-```
-
-### Benefits:
-
-✅ **For Users:**
-- Single product to start ($149)
-- Works with any theme (shortcodes)
-- Optional premium themes for better design
-- Flexible deployment
-
-✅ **For Us:**
-- Higher base revenue
-- Additional theme revenue
-- Easier to sell
-- Less support complexity
-
-✅ **For Developers:**
-- Can use basic customer-spa
-- Can build custom themes
-- Can extend with hooks
-- Maximum flexibility
-
----
-
-## Decision Matrix
-
-| Criteria | Option A (Core) | Option B (Theme) | Option C (Hybrid) |
-|----------|----------------|------------------|-------------------|
-| **User Experience** | ⭐⭐⭐⭐⭐ Simple | ⭐⭐⭐ Complex | ⭐⭐⭐⭐ Flexible |
-| **Revenue Potential** | ⭐⭐⭐⭐ $149K | ⭐⭐⭐ $137K | ⭐⭐⭐⭐⭐ $164K |
-| **Development Effort** | ⭐⭐⭐⭐ Medium | ⭐⭐ High | ⭐⭐⭐ Medium-High |
-| **Maintenance** | ⭐⭐⭐⭐⭐ Easy | ⭐⭐ Hard | ⭐⭐⭐⭐ Moderate |
-| **Flexibility** | ⭐⭐⭐ Limited | ⭐⭐⭐⭐⭐ Maximum | ⭐⭐⭐⭐ High |
-| **Market Fit** | ⭐⭐⭐⭐ Good | ⭐⭐⭐ Okay | ⭐⭐⭐⭐⭐ Excellent |
-| **WP Best Practices** | ⭐⭐⭐ Okay | ⭐⭐⭐⭐⭐ Perfect | ⭐⭐⭐⭐ Good |
-
----
-
-## Final Recommendation
-
-### ✅ **Option C: Hybrid Approach**
-
-**Implementation:**
-
-1. **WooNooW Plugin ($149/year):**
-   - Admin-SPA (full featured)
-   - Customer-SPA (basic cart/checkout/account)
-   - Shortcode mode (works with any theme)
-   - Full SPA mode (optional)
-
-2. **Premium Themes ($79/year each):**
-   - Enhanced customer-spa components
-   - Industry-specific designs
-   - Advanced features
-   - Professional layouts
-
-3. **Bundles:**
-   - Plugin + Theme: $199/year (save $29)
-   - Plugin + 3 Themes: $299/year (save $87)
-
-### Why This Works:
-
-✅ **60% of users** (small businesses) get complete solution in one plugin
-✅ **30% of users** (agencies) can build custom themes or buy premium
-✅ **10% of users** (enterprise) have maximum flexibility
-✅ **Higher revenue** potential with theme marketplace
-✅ **Easier to maintain** than fully separate products
-✅ **Better market positioning** than competitors
-
-### Next Steps:
-
-**Phase 1 (Current):** Build admin-spa ✅
-**Phase 2 (Next):** Build basic customer-spa in core plugin
-**Phase 3 (Future):** Launch premium theme marketplace
-
----
-
-## Conclusion
-
-**Build customer-spa into WooNooW core plugin with:**
-- Shortcode mode (default, works with any theme)
-- Full SPA mode (optional, for performance)
-- Premium themes as separate products (optional)
-
-**This gives us:**
-- Best user experience
-- Highest revenue potential
-- Maximum flexibility
-- Sustainable business model
-- Competitive advantage
-
-**Decision: Option C (Hybrid Approach)** ✅

CLEANUP_SUMMARY.md

@@ -1,262 +0,0 @@
-# Documentation Cleanup Summary - December 26, 2025
-
-## ✅ Cleanup Results
-
-### Before
-- **Total Files**: 74 markdown files
-- **Status**: Cluttered with obsolete fixes, completed features, and duplicate docs
-
-### After
-- **Total Files**: 43 markdown files (42% reduction)
-- **Status**: Clean, organized, only relevant documentation
-
----
-
-## 🗑️ Deleted Files (32 total)
-
-### Completed Fixes (10 files)
-- FIXES_APPLIED.md
-- REAL_FIX.md
-- CANONICAL_REDIRECT_FIX.md
-- HEADER_FIXES_APPLIED.md
-- FINAL_FIXES.md
-- FINAL_FIXES_APPLIED.md
-- FIX_500_ERROR.md
-- HASHROUTER_FIXES.md
-- INLINE_SPACING_FIX.md
-- DIRECT_ACCESS_FIX.md
-
-### Completed Features (8 files)
-- APPEARANCE_MENU_RESTRUCTURE.md
-- SETTINGS-RESTRUCTURE.md
-- HEADER_FOOTER_REDESIGN.md
-- TYPOGRAPHY-PLAN.md
-- CUSTOMER_SPA_SETTINGS.md
-- CUSTOMER_SPA_STATUS.md
-- CUSTOMER_SPA_THEME_SYSTEM.md
-- CUSTOMER_SPA_ARCHITECTURE.md
-
-### Product Page (5 files)
-- PRODUCT_PAGE_VISUAL_OVERHAUL.md
-- PRODUCT_PAGE_FINAL_STATUS.md
-- PRODUCT_PAGE_REVIEW_REPORT.md
-- PRODUCT_PAGE_ANALYSIS_REPORT.md
-- PRODUCT_CART_COMPLETE.md
-
-### Meta/Compat (2 files)
-- IMPLEMENTATION_PLAN_META_COMPAT.md
-- METABOX_COMPAT.md
-
-### Old Audits (1 file)
-- DOCS_AUDIT_REPORT.md
-
-### Shipping Research (2 files)
-- SHIPPING_ADDON_RESEARCH.md
-- SHIPPING_FIELD_HOOKS.md
-
-### Process Docs (3 files)
-- DEPLOYMENT_GUIDE.md
-- TESTING_CHECKLIST.md
-- TROUBLESHOOTING.md
-
-### Other (1 file)
-- PLUGIN_ZIP_GUIDE.md
-
----
-
-## 📦 Merged Files (2 → 1)
-
-### Shipping Documentation
-**Merged into**: `SHIPPING_INTEGRATION.md`
-- RAJAONGKIR_INTEGRATION.md
-- BITESHIP_ADDON_SPEC.md
-
-**Result**: Single comprehensive shipping integration guide
-
----
-
-## 📝 New Documentation Created (3 files)
-
-1. **DOCS_CLEANUP_AUDIT.md** - This cleanup audit report
-2. **SHIPPING_INTEGRATION.md** - Consolidated shipping guide
-3. **FEATURE_ROADMAP.md** - Comprehensive feature roadmap
-
----
-
-## 📚 Essential Documentation Kept (20 files)
-
-### Core Documentation (4)
-- README.md
-- API_ROUTES.md
-- HOOKS_REGISTRY.md
-- VALIDATION_HOOKS.md
-
-### Architecture & Patterns (5)
-- ADDON_BRIDGE_PATTERN.md
-- ADDON_DEVELOPMENT_GUIDE.md
-- ADDON_REACT_INTEGRATION.md
-- PAYMENT_GATEWAY_PATTERNS.md
-- ARCHITECTURE_DECISION_CUSTOMER_SPA.md
-
-### System Guides (5)
-- NOTIFICATION_SYSTEM.md
-- I18N_IMPLEMENTATION_GUIDE.md
-- EMAIL_DEBUGGING_GUIDE.md
-- FILTER_HOOKS_GUIDE.md
-- MARKDOWN_SYNTAX_AND_VARIABLES.md
-
-### Active Plans (4)
-- NEWSLETTER_CAMPAIGN_PLAN.md
-- SETUP_WIZARD_DESIGN.md
-- TAX_SETTINGS_DESIGN.md
-- CUSTOMER_SPA_MASTER_PLAN.md
-
-### Integration Guides (2)
-- SHIPPING_INTEGRATION.md (merged)
-- PAYMENT_GATEWAY_FAQ.md
-
----
-
-## 🎯 Benefits Achieved
-
-1. **Clarity** ✅
-   - Only relevant, up-to-date documentation
-   - No confusion about what's current vs historical
-
-2. **Maintainability** ✅
-   - Fewer docs to keep in sync
-   - Easier to update
-
-3. **Onboarding** ✅
-   - New developers can find what they need
-   - Clear structure and organization
-
-4. **Focus** ✅
-   - Clear what's active vs completed
-   - Roadmap for future features
-
-5. **Size** ✅
-   - Smaller plugin zip (no obsolete docs)
-   - Faster repository operations
-
----
-
-## 📋 Feature Roadmap Created
-
-Comprehensive plan for 6 major modules:
-
-### 1. Module Management System 🔴 High Priority
-- Centralized enable/disable control
-- Settings UI with categories
-- Navigation integration
-- **Effort**: 1 week
-
-### 2. Newsletter Campaigns 🔴 High Priority
-- Campaign management (CRUD)
-- Batch email sending
-- Template system (reuse notification templates)
-- Stats and reporting
-- **Effort**: 2-3 weeks
-
-### 3. Wishlist Notifications 🟡 Medium Priority
-- Price drop alerts
-- Back in stock notifications
-- Low stock alerts
-- Wishlist reminders
-- **Effort**: 1-2 weeks
-
-### 4. Affiliate Program 🟡 Medium Priority
-- Referral tracking
-- Commission management
-- Affiliate dashboard
-- Payout system
-- **Effort**: 3-4 weeks
-
-### 5. Product Subscriptions 🟢 Low Priority
-- Recurring billing
-- Subscription management
-- Renewal automation
-- Customer dashboard
-- **Effort**: 4-5 weeks
-
-### 6. Software Licensing 🟢 Low Priority
-- License key generation
-- Activation management
-- Validation API
-- Customer dashboard
-- **Effort**: 3-4 weeks
-
----
-
-## 🚀 Next Steps
-
-1. ✅ Documentation cleanup complete
-2. ✅ Feature roadmap created
-3. ⏭️ Review and approve roadmap
-4. ⏭️ Prioritize modules based on business needs
-5. ⏭️ Start implementation with Module 1 (Module Management)
-
----
-
-## 📊 Impact Summary
-
-| Metric | Before | After | Change |
-|--------|--------|-------|--------|
-| Total Docs | 74 | 43 | -42% |
-| Obsolete Docs | 32 | 0 | -100% |
-| Duplicate Docs | 6 | 1 | -83% |
-| Active Plans | 4 | 4 | - |
-| New Roadmaps | 0 | 1 | +1 |
-
----
-
-## ✨ Key Achievements
-
-1. **Removed 32 obsolete files** - No more confusion about completed work
-2. **Merged 2 shipping docs** - Single source of truth for shipping integration
-3. **Created comprehensive roadmap** - Clear vision for next 6 modules
-4. **Organized remaining docs** - Easy to find what you need
-5. **Reduced clutter by 42%** - Cleaner repository and faster operations
-
----
-
-## 📖 Documentation Structure (Final)
-
-```
-Root Documentation (43 files)
-├── Core (4)
-│   ├── README.md
-│   ├── API_ROUTES.md
-│   ├── HOOKS_REGISTRY.md
-│   └── VALIDATION_HOOKS.md
-├── Architecture (5)
-│   ├── ADDON_BRIDGE_PATTERN.md
-│   ├── ADDON_DEVELOPMENT_GUIDE.md
-│   ├── ADDON_REACT_INTEGRATION.md
-│   ├── PAYMENT_GATEWAY_PATTERNS.md
-│   └── ARCHITECTURE_DECISION_CUSTOMER_SPA.md
-├── System Guides (5)
-│   ├── NOTIFICATION_SYSTEM.md
-│   ├── I18N_IMPLEMENTATION_GUIDE.md
-│   ├── EMAIL_DEBUGGING_GUIDE.md
-│   ├── FILTER_HOOKS_GUIDE.md
-│   └── MARKDOWN_SYNTAX_AND_VARIABLES.md
-├── Active Plans (4)
-│   ├── NEWSLETTER_CAMPAIGN_PLAN.md
-│   ├── SETUP_WIZARD_DESIGN.md
-│   ├── TAX_SETTINGS_DESIGN.md
-│   └── CUSTOMER_SPA_MASTER_PLAN.md
-├── Integration Guides (2)
-│   ├── SHIPPING_INTEGRATION.md
-│   └── PAYMENT_GATEWAY_FAQ.md
-└── Roadmaps (3)
-    ├── FEATURE_ROADMAP.md (NEW)
-    ├── DOCS_CLEANUP_AUDIT.md (NEW)
-    └── CLEANUP_SUMMARY.md (NEW)
-```
-
----
-
-**Cleanup Status**: ✅ Complete  
-**Roadmap Status**: ✅ Complete  
-**Ready for**: Implementation Phase

CUSTOMER_SPA_MASTER_PLAN.md

@@ -1,749 +0,0 @@
-# Customer SPA Master Plan
-## WooNooW Frontend Architecture & Implementation Strategy
-
-**Version:** 1.0  
-**Date:** November 21, 2025  
-**Status:** Planning Phase
-
----
-
-## Executive Summary
-
-This document outlines the comprehensive strategy for building WooNooW's customer-facing SPA, including architecture decisions, deployment modes, UX best practices, and implementation roadmap.
-
-### Key Decisions
-
-✅ **Hybrid Architecture** - Plugin includes customer-spa with flexible deployment modes  
-✅ **Progressive Enhancement** - Works with any theme, optional full SPA mode  
-✅ **Mobile-First PWA** - Fast, app-like experience on all devices  
-✅ **SEO-Friendly** - Server-side rendering for product pages, SPA for interactions
-
----
-
-## Table of Contents
-
-1. [Architecture Overview](#architecture-overview)
-2. [Deployment Modes](#deployment-modes)
-3. [SEO Strategy](#seo-strategy)
-4. [Tracking & Analytics](#tracking--analytics)
-5. [Feature Scope](#feature-scope)
-6. [UX Best Practices](#ux-best-practices)
-7. [Technical Stack](#technical-stack)
-8. [Implementation Roadmap](#implementation-roadmap)
-9. [API Requirements](#api-requirements)
-10. [Performance Targets](#performance-targets)
-
----
-
-## Architecture Overview
-
-### Hybrid Plugin Architecture
-
-```
-woonoow/
-├── admin-spa/              # Admin interface ONLY
-│   ├── src/
-│   │   ├── routes/         # Admin pages (Dashboard, Products, Orders)
-│   │   └── components/     # Admin components
-│   └── public/
-│
-├── customer-spa/           # Customer frontend ONLY (Storefront + My Account)
-│   ├── src/
-│   │   ├── pages/          # Customer pages
-│   │   │   ├── Shop/           # Product listing
-│   │   │   ├── Product/        # Product detail
-│   │   │   ├── Cart/           # Shopping cart
-│   │   │   ├── Checkout/       # Checkout process
-│   │   │   └── Account/        # My Account (orders, profile, addresses)
-│   │   ├── components/
-│   │   │   ├── ProductCard/
-│   │   │   ├── CartDrawer/
-│   │   │   ├── CheckoutForm/
-│   │   │   └── AddressForm/
-│   │   └── lib/
-│   │       ├── api/            # API client
-│   │       ├── cart/           # Cart state management
-│   │       ├── checkout/       # Checkout logic
-│   │       └── tracking/       # Analytics & pixel tracking
-│   └── public/
-│
-└── includes/
-    ├── Admin/              # Admin backend (serves admin-spa)
-    │   ├── AdminController.php
-    │   └── MenuManager.php
-    │
-    └── Frontend/           # Customer backend (serves customer-spa)
-        ├── ShortcodeManager.php    # [woonoow_cart], [woonoow_checkout]
-        ├── SpaManager.php          # Full SPA mode handler
-        └── Api/                    # Customer API endpoints
-            ├── ShopController.php
-            ├── CartController.php
-            └── CheckoutController.php
-```
-
-**Key Points:**
-- ✅ **admin-spa/** - Admin interface only
-- ✅ **customer-spa/** - Storefront + My Account in one app
-- ✅ **includes/Admin/** - Admin backend logic
-- ✅ **includes/Frontend/** - Customer backend logic
-- ✅ Clear separation of concerns
-
----
-
-## Deployment Modes
-
-### Mode 1: Shortcode Mode (Default) ⭐ RECOMMENDED
-
-**Use Case:** Works with ANY WordPress theme
-
-**How it works:**
-```php
-// In theme template or page builder
-[woonoow_shop]
-[woonoow_cart]
-[woonoow_checkout]
-[woonoow_account]
-```
-
-**Benefits:**
-- ✅ Compatible with all themes
-- ✅ Works with page builders (Elementor, Divi, etc.)
-- ✅ Progressive enhancement
-- ✅ SEO-friendly (SSR for products)
-- ✅ Easy migration from WooCommerce
-
-**Architecture:**
-- Theme provides layout/header/footer
-- WooNooW provides interactive components
-- Hybrid SSR + SPA islands pattern
-
----
-
-### Mode 2: Full SPA Mode
-
-**Use Case:** Maximum performance, app-like experience
-
-**How it works:**
-```php
-// Settings > Frontend > Mode: Full SPA
-// WooNooW takes over entire frontend
-```
-
-**Benefits:**
-- ✅ Fastest performance
-- ✅ Smooth page transitions
-- ✅ Offline support (PWA)
-- ✅ App-like experience
-- ✅ Optimized for mobile
-
-**Architecture:**
-- Single-page application
-- Client-side routing
-- Theme provides minimal wrapper
-- API-driven data fetching
-
----
-
-### Mode 3: Hybrid Mode
-
-**Use Case:** Best of both worlds
-
-**How it works:**
-- Product pages: SSR (SEO)
-- Cart/Checkout: SPA (UX)
-- My Account: SPA (performance)
-
-**Benefits:**
-- ✅ SEO for product pages
-- ✅ Fast interactions for cart/checkout
-- ✅ Balanced approach
-- ✅ Flexible deployment
-
----
-
-## SEO Strategy
-
-### Hybrid Rendering for SEO Compatibility
-
-**Problem:** Full SPA can hurt SEO because search engines see empty HTML.
-
-**Solution:** Hybrid rendering - SSR for SEO-critical pages, CSR for interactive pages.
-
-### Rendering Strategy
-
-```
-┌─────────────────────┬──────────────┬─────────────────┐
-│ Page Type           │ Rendering    │ SEO Needed?     │
-├─────────────────────┼──────────────┼─────────────────┤
-│ Product Listing     │ SSR          │ ✅ Yes          │
-│ Product Detail      │ SSR          │ ✅ Yes          │
-│ Category Pages      │ SSR          │ ✅ Yes          │
-│ Search Results      │ SSR          │ ✅ Yes          │
-│ Cart                │ CSR (SPA)    │ ❌ No           │
-│ Checkout            │ CSR (SPA)    │ ❌ No           │
-│ My Account          │ CSR (SPA)    │ ❌ No           │
-│ Order Confirmation  │ CSR (SPA)    │ ❌ No           │
-└─────────────────────┴──────────────┴─────────────────┘
-```
-
-### How SSR Works
-
-**Product Page Example:**
-```php
-<?php
-// WordPress renders full HTML (SEO-friendly)
-get_header();
-
-$product = wc_get_product( get_the_ID() );
-?>
-
-<!-- Server-rendered HTML for SEO -->
-<div id="woonoow-product" data-product-id="<?php echo $product->get_id(); ?>">
-  <h1><?php echo $product->get_name(); ?></h1>
-  <div class="price"><?php echo $product->get_price_html(); ?></div>
-  <div class="description"><?php echo $product->get_description(); ?></div>
-  
-  <!-- SEO plugins inject meta tags here -->
-  <?php do_action('woocommerce_after_single_product'); ?>
-</div>
-
-<?php
-get_footer();
-// React hydrates this div for interactivity (add to cart, variations, etc.)
-?>
-```
-
-**Benefits:**
-- ✅ **Yoast SEO** works - sees full HTML
-- ✅ **RankMath** works - sees full HTML
-- ✅ **Google** crawls full content
-- ✅ **Social sharing** shows correct meta tags
-- ✅ **React adds interactivity** after page load
-
-### SEO Plugin Compatibility
-
-**Supported SEO Plugins:**
-- ✅ Yoast SEO
-- ✅ RankMath
-- ✅ All in One SEO
-- ✅ SEOPress
-- ✅ The SEO Framework
-
-**How it works:**
-1. WordPress renders product page with full HTML
-2. SEO plugin injects meta tags, schema markup
-3. React hydrates for interactivity
-4. Search engines see complete, SEO-optimized HTML
-
----
-
-## Tracking & Analytics
-
-### Full Compatibility with Tracking Plugins
-
-**Goal:** Ensure all tracking plugins work seamlessly with customer-spa.
-
-### Strategy: Trigger WooCommerce Events
-
-**Key Insight:** Keep WooCommerce classes and trigger WooCommerce events so tracking plugins can listen.
-
-### Supported Tracking Plugins
-
-✅ **PixelMySite** - Facebook, TikTok, Pinterest pixels  
-✅ **Google Analytics** - GA4, Universal Analytics  
-✅ **Google Tag Manager** - Full dataLayer support  
-✅ **Facebook Pixel** - Standard events  
-✅ **TikTok Pixel** - E-commerce events  
-✅ **Pinterest Tag** - Conversion tracking  
-✅ **Snapchat Pixel** - E-commerce events
-
-### Implementation
-
-**1. Keep WooCommerce Classes:**
-```jsx
-// customer-spa components use WooCommerce classes
-<button 
-  className="single_add_to_cart_button"  // WooCommerce class
-  data-product_id="123"                   // WooCommerce data attr
-  onClick={handleAddToCart}
->
-  Add to Cart
-</button>
-```
-
-**2. Trigger WooCommerce Events:**
-```typescript
-// customer-spa/src/lib/tracking.ts
-
-export const trackAddToCart = (product: Product, quantity: number) => {
-  // 1. WooCommerce event (for PixelMySite and other plugins)
-  jQuery(document.body).trigger('added_to_cart', [
-    product.id,
-    quantity,
-    product.price
-  ]);
-  
-  // 2. Google Analytics / GTM
-  window.dataLayer = window.dataLayer || [];
-  window.dataLayer.push({
-    event: 'add_to_cart',
-    ecommerce: {
-      items: [{
-        item_id: product.id,
-        item_name: product.name,
-        price: product.price,
-        quantity: quantity
-      }]
-    }
-  });
-  
-  // 3. Facebook Pixel (if loaded by plugin)
-  if (typeof fbq !== 'undefined') {
-    fbq('track', 'AddToCart', {
-      content_ids: [product.id],
-      content_name: product.name,
-      value: product.price * quantity,
-      currency: 'USD'
-    });
-  }
-};
-
-export const trackBeginCheckout = (cart: Cart) => {
-  // WooCommerce event
-  jQuery(document.body).trigger('wc_checkout_loaded');
-  
-  // Google Analytics
-  window.dataLayer?.push({
-    event: 'begin_checkout',
-    ecommerce: {
-      items: cart.items.map(item => ({
-        item_id: item.product_id,
-        item_name: item.name,
-        price: item.price,
-        quantity: item.quantity
-      }))
-    }
-  });
-};
-
-export const trackPurchase = (order: Order) => {
-  // WooCommerce event
-  jQuery(document.body).trigger('wc_order_completed', [
-    order.id,
-    order.total
-  ]);
-  
-  // Google Analytics
-  window.dataLayer?.push({
-    event: 'purchase',
-    ecommerce: {
-      transaction_id: order.id,
-      value: order.total,
-      currency: order.currency,
-      items: order.items.map(item => ({
-        item_id: item.product_id,
-        item_name: item.name,
-        price: item.price,
-        quantity: item.quantity
-      }))
-    }
-  });
-};
-```
-
-**3. Usage in Components:**
-```tsx
-// customer-spa/src/pages/Product/AddToCartButton.tsx
-
-import { trackAddToCart } from '@/lib/tracking';
-
-function AddToCartButton({ product }: Props) {
-  const handleClick = async () => {
-    // Add to cart via API
-    await cartApi.add(product.id, quantity);
-    
-    // Track event (triggers all pixels)
-    trackAddToCart(product, quantity);
-    
-    // Show success message
-    toast.success('Added to cart!');
-  };
-  
-  return (
-    <button 
-      className="single_add_to_cart_button"
-      onClick={handleClick}
-    >
-      Add to Cart
-    </button>
-  );
-}
-```
-
-### E-commerce Events Tracked
-
-```
-✅ View Product
-✅ Add to Cart
-✅ Remove from Cart
-✅ View Cart
-✅ Begin Checkout
-✅ Add Shipping Info
-✅ Add Payment Info
-✅ Purchase
-✅ Refund
-```
-
-### Result
-
-**All tracking plugins work out of the box!**
-- PixelMySite listens to WooCommerce events ✅
-- Google Analytics receives dataLayer events ✅
-- Facebook/TikTok pixels fire correctly ✅
-- Store owner doesn't need to change anything ✅
-
----
-
-## Feature Scope
-
-### Phase 1: Core Commerce (MVP)
-
-#### 1. Product Catalog
-- Product listing with filters
-- Product detail page
-- Product search
-- Category navigation
-- Product variations
-- Image gallery with zoom
-- Related products
-
-#### 2. Shopping Cart
-- Add to cart (AJAX)
-- Cart drawer/sidebar
-- Update quantities
-- Remove items
-- Apply coupons
-- Shipping calculator
-- Cart persistence (localStorage)
-
-#### 3. Checkout
-- Single-page checkout
-- Guest checkout
-- Address autocomplete
-- Shipping method selection
-- Payment method selection
-- Order review
-- Order confirmation
-
-#### 4. My Account
-- Dashboard overview
-- Order history
-- Order details
-- Download invoices
-- Track shipments
-- Edit profile
-- Change password
-- Manage addresses
-- Payment methods
-
----
-
-### Phase 2: Enhanced Features
-
-#### 5. Wishlist
-- Add to wishlist
-- Wishlist page
-- Share wishlist
-- Move to cart
-
-#### 6. Product Reviews
-- Write review
-- Upload photos
-- Rating system
-- Review moderation
-- Helpful votes
-
-#### 7. Quick View
-- Product quick view modal
-- Add to cart from quick view
-- Variation selection
-
-#### 8. Product Compare
-- Add to compare
-- Compare table
-- Side-by-side comparison
-
----
-
-### Phase 3: Advanced Features
-
-#### 9. Subscriptions
-- Subscription products
-- Manage subscriptions
-- Pause/resume
-- Change frequency
-- Update payment method
-
-#### 10. Memberships
-- Member-only products
-- Member pricing
-- Membership dashboard
-- Access control
-
-#### 11. Digital Downloads
-- Download manager
-- License keys
-- Version updates
-- Download limits
-
----
-
-## UX Best Practices
-
-### Research-Backed Patterns
-
-Based on Baymard Institute research and industry leaders:
-
-#### Cart UX
-✅ **Persistent cart drawer** - Always accessible, slides from right  
-✅ **Mini cart preview** - Show items without leaving page  
-✅ **Free shipping threshold** - "Add $X more for free shipping"  
-✅ **Save for later** - Move items to wishlist  
-✅ **Stock indicators** - "Only 3 left in stock"  
-✅ **Estimated delivery** - Show delivery date  
-
-#### Checkout UX
-✅ **Progress indicator** - Show steps (Shipping → Payment → Review)  
-✅ **Guest checkout** - Don't force account creation  
-✅ **Address autocomplete** - Google Places API  
-✅ **Inline validation** - Real-time error messages  
-✅ **Trust signals** - Security badges, SSL indicators  
-✅ **Mobile-optimized** - Large touch targets, numeric keyboards  
-✅ **One-page checkout** - Minimize steps  
-✅ **Save payment methods** - For returning customers  
-
-#### Product Page UX
-✅ **High-quality images** - Multiple angles, zoom  
-✅ **Clear CTA** - Prominent "Add to Cart" button  
-✅ **Stock status** - In stock / Out of stock / Pre-order  
-✅ **Shipping info** - Delivery estimate  
-✅ **Size guide** - For apparel  
-✅ **Social proof** - Reviews, ratings  
-✅ **Related products** - Cross-sell  
-
----
-
-## Technical Stack
-
-### Frontend
-- **Framework:** React 18 (with Suspense, Transitions)
-- **Routing:** React Router v6
-- **State:** Zustand (cart, checkout state)
-- **Data Fetching:** TanStack Query (React Query)
-- **Forms:** React Hook Form + Zod validation
-- **Styling:** TailwindCSS + shadcn/ui
-- **Build:** Vite
-- **PWA:** Workbox (service worker)
-
-### Backend
-- **API:** WordPress REST API (custom endpoints)
-- **Authentication:** WordPress nonces + JWT (optional)
-- **Session:** WooCommerce session handler
-- **Cache:** Transients API + Object cache
-
-### Performance
-- **Code Splitting:** Route-based lazy loading
-- **Image Optimization:** WebP, lazy loading, blur placeholders
-- **Caching:** Service worker, API response cache
-- **CDN:** Static assets on CDN
-
----
-
-## Implementation Roadmap
-
-### Sprint 1-2: Foundation (2 weeks)
-- [ ] Setup customer-spa build system
-- [ ] Create base layout components
-- [ ] Implement routing
-- [ ] Setup API client
-- [ ] Cart state management
-- [ ] Authentication flow
-
-### Sprint 3-4: Product Catalog (2 weeks)
-- [ ] Product listing page
-- [ ] Product filters
-- [ ] Product search
-- [ ] Product detail page
-- [ ] Product variations
-- [ ] Image gallery
-
-### Sprint 5-6: Cart & Checkout (2 weeks)
-- [ ] Cart drawer component
-- [ ] Cart page
-- [ ] Checkout form
-- [ ] Address autocomplete
-- [ ] Shipping calculator
-- [ ] Payment integration
-
-### Sprint 7-8: My Account (2 weeks)
-- [ ] Account dashboard
-- [ ] Order history
-- [ ] Order details
-- [ ] Profile management
-- [ ] Address book
-- [ ] Download manager
-
-### Sprint 9-10: Polish & Testing (2 weeks)
-- [ ] Mobile optimization
-- [ ] Performance tuning
-- [ ] Accessibility audit
-- [ ] Browser testing
-- [ ] User testing
-- [ ] Bug fixes
-
----
-
-## API Requirements
-
-### New Endpoints Needed
-
-```
-GET    /woonoow/v1/shop/products
-GET    /woonoow/v1/shop/products/:id
-GET    /woonoow/v1/shop/categories
-GET    /woonoow/v1/shop/search
-
-POST   /woonoow/v1/cart/add
-POST   /woonoow/v1/cart/update
-POST   /woonoow/v1/cart/remove
-GET    /woonoow/v1/cart
-POST   /woonoow/v1/cart/apply-coupon
-
-POST   /woonoow/v1/checkout/calculate
-POST   /woonoow/v1/checkout/create-order
-GET    /woonoow/v1/checkout/payment-methods
-GET    /woonoow/v1/checkout/shipping-methods
-
-GET    /woonoow/v1/account/orders
-GET    /woonoow/v1/account/orders/:id
-GET    /woonoow/v1/account/downloads
-POST   /woonoow/v1/account/profile
-POST   /woonoow/v1/account/password
-POST   /woonoow/v1/account/addresses
-```
-
----
-
-## Performance Targets
-
-### Core Web Vitals
-- **LCP (Largest Contentful Paint):** < 2.5s
-- **FID (First Input Delay):** < 100ms
-- **CLS (Cumulative Layout Shift):** < 0.1
-
-### Bundle Sizes
-- **Initial JS:** < 150KB (gzipped)
-- **Initial CSS:** < 50KB (gzipped)
-- **Route chunks:** < 50KB each (gzipped)
-
-### Page Load Times
-- **Product page:** < 1.5s (3G)
-- **Cart page:** < 1s
-- **Checkout page:** < 1.5s
-
----
-
-## Settings & Configuration
-
-### Frontend Settings Panel
-
-```
-WooNooW > Settings > Frontend
-├── Mode
-│   ○ Disabled (use theme)
-│   ● Shortcodes (default)
-│   ○ Full SPA
-├── Features
-│   ☑ Product catalog
-│   ☑ Shopping cart
-│   ☑ Checkout
-│   ☑ My Account
-│   ☐ Wishlist (Phase 2)
-│   ☐ Product reviews (Phase 2)
-├── Performance
-│   ☑ Enable PWA
-│   ☑ Offline mode
-│   ☑ Image lazy loading
-│   Cache duration: 1 hour
-└── Customization
-    Primary color: #000000
-    Font family: System
-    Border radius: 8px
-```
-
----
-
-## Migration Strategy
-
-### From WooCommerce Default
-
-1. **Install WooNooW** - Keep WooCommerce active
-2. **Enable Shortcode Mode** - Test on staging
-3. **Replace pages** - Cart, Checkout, My Account
-4. **Test thoroughly** - All user flows
-5. **Go live** - Switch DNS
-6. **Monitor** - Analytics, errors
-
-### Rollback Plan
-
-- Keep WooCommerce pages as backup
-- Settings toggle to disable customer-spa
-- Fallback to WooCommerce templates
-
----
-
-## Success Metrics
-
-### Business Metrics
-- Cart abandonment rate: < 60% (industry avg: 70%)
-- Checkout completion rate: > 40%
-- Mobile conversion rate: > 2%
-- Page load time: < 2s
-
-### Technical Metrics
-- Lighthouse score: > 90
-- Core Web Vitals: All green
-- Error rate: < 0.1%
-- API response time: < 200ms
-
----
-
-## Competitive Analysis
-
-### Shopify Hydrogen
-- **Pros:** Fast, modern, React-based
-- **Cons:** Shopify-only, complex setup
-- **Lesson:** Simplify developer experience
-
-### WooCommerce Blocks
-- **Pros:** Native WooCommerce integration
-- **Cons:** Limited customization, slow
-- **Lesson:** Provide flexibility
-
-### SureCart
-- **Pros:** Simple, fast checkout
-- **Cons:** Limited features
-- **Lesson:** Focus on core experience first
-
----
-
-## Next Steps
-
-1. ✅ Review and approve this plan
-2. ⏳ Create detailed technical specs
-3. ⏳ Setup customer-spa project structure
-4. ⏳ Begin Sprint 1 (Foundation)
-
----
-
-**Decision Required:** Approve this plan to proceed with implementation.

DOCS_CLEANUP_AUDIT.md

@@ -1,191 +0,0 @@
-# Documentation Cleanup Audit - December 2025
-
-**Total Files Found**: 74 markdown files  
-**Audit Date**: December 26, 2025
-
----
-
-## 📋 Audit Categories
-
-### ✅ KEEP - Essential & Active (18 files)
-
-#### Core Documentation
-1. **README.md** - Main plugin documentation
-2. **API_ROUTES.md** - API endpoint reference
-3. **HOOKS_REGISTRY.md** - Filter/action hooks registry
-4. **VALIDATION_HOOKS.md** - Email/phone validation hooks (NEW)
-
-#### Architecture & Patterns
-5. **ADDON_BRIDGE_PATTERN.md** - Addon architecture
-6. **ADDON_DEVELOPMENT_GUIDE.md** - Addon development guide
-7. **ADDON_REACT_INTEGRATION.md** - React addon integration
-8. **PAYMENT_GATEWAY_PATTERNS.md** - Payment gateway patterns
-9. **ARCHITECTURE_DECISION_CUSTOMER_SPA.md** - Customer SPA architecture
-
-#### System Guides
-10. **NOTIFICATION_SYSTEM.md** - Notification system documentation
-11. **I18N_IMPLEMENTATION_GUIDE.md** - Translation system
-12. **EMAIL_DEBUGGING_GUIDE.md** - Email troubleshooting
-13. **FILTER_HOOKS_GUIDE.md** - Filter hooks guide
-14. **MARKDOWN_SYNTAX_AND_VARIABLES.md** - Email template syntax
-
-#### Active Plans
-15. **NEWSLETTER_CAMPAIGN_PLAN.md** - Newsletter campaign architecture (NEW)
-16. **SETUP_WIZARD_DESIGN.md** - Setup wizard design
-17. **TAX_SETTINGS_DESIGN.md** - Tax settings UI/UX
-18. **CUSTOMER_SPA_MASTER_PLAN.md** - Customer SPA roadmap
-
----
-
-### 🗑️ DELETE - Obsolete/Completed (32 files)
-
-#### Completed Fixes (Delete - Issues Resolved)
-1. **FIXES_APPLIED.md** - Old fixes log
-2. **REAL_FIX.md** - Temporary fix doc
-3. **CANONICAL_REDIRECT_FIX.md** - Fix completed
-4. **HEADER_FIXES_APPLIED.md** - Fix completed
-5. **FINAL_FIXES.md** - Fix completed
-6. **FINAL_FIXES_APPLIED.md** - Fix completed
-7. **FIX_500_ERROR.md** - Fix completed
-8. **HASHROUTER_FIXES.md** - Fix completed
-9. **INLINE_SPACING_FIX.md** - Fix completed
-10. **DIRECT_ACCESS_FIX.md** - Fix completed
-
-#### Completed Features (Delete - Implemented)
-11. **APPEARANCE_MENU_RESTRUCTURE.md** - Menu restructured
-12. **SETTINGS-RESTRUCTURE.md** - Settings restructured
-13. **HEADER_FOOTER_REDESIGN.md** - Redesign completed
-14. **TYPOGRAPHY-PLAN.md** - Typography implemented
-15. **CUSTOMER_SPA_SETTINGS.md** - Settings implemented
-16. **CUSTOMER_SPA_STATUS.md** - Status outdated
-17. **CUSTOMER_SPA_THEME_SYSTEM.md** - Theme system built
-
-#### Product Page (Delete - Completed)
-18. **PRODUCT_PAGE_VISUAL_OVERHAUL.md** - Overhaul completed
-19. **PRODUCT_PAGE_FINAL_STATUS.md** - Status outdated
-20. **PRODUCT_PAGE_REVIEW_REPORT.md** - Review completed
-21. **PRODUCT_PAGE_ANALYSIS_REPORT.md** - Analysis completed
-22. **PRODUCT_CART_COMPLETE.md** - Feature completed
-
-#### Meta/Compat (Delete - Implemented)
-23. **IMPLEMENTATION_PLAN_META_COMPAT.md** - Implemented
-24. **METABOX_COMPAT.md** - Implemented
-
-#### Old Audit Reports (Delete - Superseded)
-25. **DOCS_AUDIT_REPORT.md** - Old audit (Nov 2025)
-
-#### Shipping Research (Delete - Superseded by Integration)
-26. **SHIPPING_ADDON_RESEARCH.md** - Research phase done
-27. **SHIPPING_FIELD_HOOKS.md** - Hooks documented in HOOKS_REGISTRY
-
-#### Deployment/Testing (Delete - Process Docs)
-28. **DEPLOYMENT_GUIDE.md** - Deployment is automated
-29. **TESTING_CHECKLIST.md** - Testing is ongoing
-30. **TROUBLESHOOTING.md** - Issues resolved
-
-#### Customer SPA (Delete - Superseded)
-31. **CUSTOMER_SPA_ARCHITECTURE.md** - Superseded by MASTER_PLAN
-
-#### Other
-32. **PLUGIN_ZIP_GUIDE.md** - Just created, can be deleted (packaging automated)
-
----
-
-### 📦 MERGE - Consolidate Related (6 files)
-
-#### Shipping Documentation → Create `SHIPPING_INTEGRATION.md`
-1. **RAJAONGKIR_INTEGRATION.md** - RajaOngkir integration
-2. **BITESHIP_ADDON_SPEC.md** - Biteship addon spec
-→ **Merge into**: `SHIPPING_INTEGRATION.md` (shipping addons guide)
-
-#### Customer SPA → Keep only `CUSTOMER_SPA_MASTER_PLAN.md`
-3. **CUSTOMER_SPA_ARCHITECTURE.md** - Architecture details
-4. **CUSTOMER_SPA_SETTINGS.md** - Settings details
-5. **CUSTOMER_SPA_STATUS.md** - Status updates
-6. **CUSTOMER_SPA_THEME_SYSTEM.md** - Theme system
-→ **Action**: Delete 3-6, keep only MASTER_PLAN
-
----
-
-### 📝 UPDATE - Needs Refresh (18 files remaining)
-
-Files to keep but may need updates as features evolve.
-
----
-
-## 🎯 Cleanup Actions
-
-### Phase 1: Delete Obsolete (32 files)
-```bash
-# Completed fixes
-rm FIXES_APPLIED.md REAL_FIX.md CANONICAL_REDIRECT_FIX.md
-rm HEADER_FIXES_APPLIED.md FINAL_FIXES.md FINAL_FIXES_APPLIED.md
-rm FIX_500_ERROR.md HASHROUTER_FIXES.md INLINE_SPACING_FIX.md
-rm DIRECT_ACCESS_FIX.md
-
-# Completed features
-rm APPEARANCE_MENU_RESTRUCTURE.md SETTINGS-RESTRUCTURE.md
-rm HEADER_FOOTER_REDESIGN.md TYPOGRAPHY-PLAN.md
-rm CUSTOMER_SPA_SETTINGS.md CUSTOMER_SPA_STATUS.md
-rm CUSTOMER_SPA_THEME_SYSTEM.md CUSTOMER_SPA_ARCHITECTURE.md
-
-# Product page
-rm PRODUCT_PAGE_VISUAL_OVERHAUL.md PRODUCT_PAGE_FINAL_STATUS.md
-rm PRODUCT_PAGE_REVIEW_REPORT.md PRODUCT_PAGE_ANALYSIS_REPORT.md
-rm PRODUCT_CART_COMPLETE.md
-
-# Meta/compat
-rm IMPLEMENTATION_PLAN_META_COMPAT.md METABOX_COMPAT.md
-
-# Old audits
-rm DOCS_AUDIT_REPORT.md
-
-# Shipping research
-rm SHIPPING_ADDON_RESEARCH.md SHIPPING_FIELD_HOOKS.md
-
-# Process docs
-rm DEPLOYMENT_GUIDE.md TESTING_CHECKLIST.md TROUBLESHOOTING.md
-
-# Other
-rm PLUGIN_ZIP_GUIDE.md
-```
-
-### Phase 2: Merge Shipping Docs
-```bash
-# Create consolidated shipping guide
-cat RAJAONGKIR_INTEGRATION.md BITESHIP_ADDON_SPEC.md > SHIPPING_INTEGRATION.md
-# Edit and clean up SHIPPING_INTEGRATION.md
-rm RAJAONGKIR_INTEGRATION.md BITESHIP_ADDON_SPEC.md
-```
-
-### Phase 3: Update Package Script
-Update `scripts/package-zip.mjs` to exclude `*.md` files from production zip.
-
----
-
-## 📊 Results
-
-| Category | Before | After | Reduction |
-|----------|--------|-------|-----------|
-| Total Files | 74 | 20 | 73% |
-| Essential Docs | 18 | 18 | - |
-| Obsolete | 32 | 0 | 100% |
-| Merged | 6 | 1 | 83% |
-
-**Final Documentation Set**: 20 essential files
-- Core: 4 files
-- Architecture: 5 files
-- System Guides: 5 files
-- Active Plans: 4 files
-- Shipping: 1 file (merged)
-- Addon Development: 1 file (merged)
-
----
-
-## ✅ Benefits
-
-1. **Clarity** - Only relevant, up-to-date documentation
-2. **Maintainability** - Less docs to keep in sync
-3. **Onboarding** - Easier for new developers
-4. **Focus** - Clear what's active vs historical
-5. **Size** - Smaller plugin zip (no obsolete docs)

FEATURE_ROADMAP.md

@@ -1,6 +1,6 @@
 # WooNooW Feature Roadmap - 2025
 
-**Last Updated**: December 31, 2025  
+**Last Updated**: June 1, 2026
 **Status**: Active Development
 
 This document outlines the comprehensive feature roadmap for WooNooW, building upon existing infrastructure.
@@ -231,29 +231,41 @@ Referral tracking and commission management system.
 
 #### 1. Database Tables
 ```sql
-wp_woonoow_affiliates (id, user_id, referral_code, commission_rate, status, total_referrals, total_earnings, paid_earnings)
-wp_woonoow_referrals (id, affiliate_id, order_id, customer_id, commission_amount, status, created_at, approved_at, paid_at)
-wp_woonoow_affiliate_payouts (id, affiliate_id, amount, method, status, notes, created_at, completed_at)
+wp_woonoow_affiliates (id, user_id, referral_code, coupon_id, commission_rate, status, total_referrals, total_earnings, paid_earnings)
+wp_woonoow_referrals (id, affiliate_id, order_id, customer_id, commission_amount, currency, status, created_at, approved_at, paid_at)
+wp_woonoow_affiliate_payouts (id, affiliate_id, amount, currency, method, status, notes, created_at, completed_at)
 ```
 
 #### 2. Tracking System
 ```php
 class AffiliateTracker {
     
-    // Set cookie for 30 days
+    // Set secure cookie for 30 days (SameSite=Lax)
     public function track_referral($referral_code) {
-        setcookie('woonoow_ref', $referral_code, time() + (30 * DAY_IN_SECONDS));
+        // Must check WooCommerce cookie consent first
+        $options = [
+            'expires' => time() + (30 * DAY_IN_SECONDS),
+            'path' => '/',
+            'secure' => is_ssl(),
+            'samesite' => 'Lax'
+        ];
+        setcookie('woonoow_ref', $referral_code, $options);
     }
     
-    // Record on order completion
+    // Record as 'pending' on order creation/payment
     public function record_referral($order_id) {
-        if (isset($_COOKIE['woonoow_ref'])) {
-            // Get affiliate by code
-            // Calculate commission
-            // Create referral record
-            // Clear cookie
+        if (isset($_COOKIE['woonoow_ref']) || $this->has_affiliate_coupon($order_id)) {
+            // Get affiliate by code or coupon
+            // Calculate commission (on subtotal, excluding tax/shipping)
+            // Create referral record with 'pending' status
+            // ActionScheduler: Schedule auto-approval in 14 days
         }
     }
+    
+    // Handle order refunds/cancellations
+    public function handle_order_refund($order_id) {
+        // Cancel/revert pending referral
+    }
 }
 ```
 
@@ -275,8 +287,9 @@ class AffiliateTracker {
 
 #### 5. Notification Events
 - `affiliate_application_approved`
-- `affiliate_referral_completed`
+- `affiliate_referral_received` (Pending Approval)
 - `affiliate_payout_processed`
+- `affiliate_threshold_reached` (Admin Alert)
 
 ### Priority: **Medium** 🟡
 ### Effort: 3-4 weeks
@@ -288,66 +301,59 @@ class AffiliateTracker {
 ### Overview
 Recurring product subscriptions with flexible billing cycles.
 
-### Status: **Planning** 🔵
+### Status: **Shipped** ✅
 
 ### What's Already Built
 - ✅ Product management
 - ✅ Order system
 - ✅ Payment gateways
 - ✅ Notification system
+- ✅ Database tables (`wp_woonoow_subscriptions`, `wp_woonoow_subscription_orders`) — schema below reflects actual shipped columns
+- ✅ Per-gateway auto-renew capability table (kill-switchable)
+- ✅ Pause/resume/cancel/early-renew customer UI
+- ✅ Admin list with bulk actions, search, and per-status filter
+- ✅ Renewal cron (`process_renewals`, `check_expirations`, `send_reminders`, `retry_unpaid_renewals`)
 
-### What's Needed
+### Schema (as shipped)
 
-#### 1. Database Tables
 ```sql
-wp_woonoow_subscriptions (id, customer_id, product_id, status, billing_period, billing_interval, price, next_payment_date, start_date, end_date, trial_end_date)
-wp_woonoow_subscription_orders (id, subscription_id, order_id, payment_status, created_at)
+wp_woonoow_subscriptions (
+  id, user_id, order_id, product_id, variation_id, status,
+  billing_period, billing_interval, recurring_amount,
+  start_date, trial_end_date, next_payment_date, end_date, last_payment_date,
+  payment_method, payment_meta, cancel_reason,
+  pause_count, failed_payment_count, reminder_sent_at
+)
+wp_woonoow_subscription_orders (
+  id, subscription_id, order_id, order_type ENUM 'parent'|'renewal'|'switch'|'resubscribe'
+)
 ```
 
-#### 2. Product Meta
-Add subscription options to product:
-- Is subscription product (checkbox)
-- Billing period (daily, weekly, monthly, yearly)
-- Billing interval (e.g., 2 for every 2 months)
-- Trial period (days)
+Note: the column is `user_id`, not `customer_id` — the original spec used the
+WC-style "customer" naming, but WP schema reserves `customer` for the legacy
+WP customer user role and the column was renamed before the first migration
+shipped.
 
-#### 3. Renewal System
-```php
-class SubscriptionRenewal {
-    
-    // WP-Cron daily job
-    public function process_renewals() {
-        $due_subscriptions = $this->get_due_subscriptions();
-        
-        foreach ($due_subscriptions as $subscription) {
-            // Create renewal order
-            // Process payment
-            // Update next payment date
-            // Send notification
-        }
-    }
-}
-```
-
-#### 4. Customer Dashboard
+### Customer Dashboard
 **Route**: `/account/subscriptions`
 - Active subscriptions list
-- Pause/resume subscription
+- Pause/resume subscription (capped at `max_pause_count` setting, default 3)
 - Cancel subscription
 - Update payment method
 - View billing history
 - Change billing cycle
 
-#### 5. Admin UI
-**Route**: `/products/subscriptions`
-- All subscriptions list
-- Filter by status
-- View subscription details
-- Manual renewal
+### Admin UI
+**Route**: `/subscriptions`
+- All subscriptions list with checkbox + bulk actions (cancel, CSV export)
+- Free-text search by id / email / display name
+- Per-status filter
+- View subscription details (per-gateway auto-renew badge, pause count)
+- Renew Now (creates manual order) or Charge Now (forces auto-debit, M2)
 - Cancel/refund
 
-### Priority: **Low** 🟢
-### Effort: 4-5 weeks
+### Priority: ~~Low~~ Shipped ✅
+### Effort: ~~4-5 weeks~~ Shipped
 
 ---
 

FIXES_COMPLETE.md

@@ -1,233 +0,0 @@
-# All Issues Fixed - Ready for Testing
-
-## ✅ Issue 1: Image Not Covering Container - FIXED
-
-**Problem:** Images weren't filling their aspect-ratio containers properly.
-
-**Root Cause:** The `aspect-square` div creates a container with padding-bottom, but child elements need `absolute` positioning to fill it.
-
-**Solution:** Added `absolute inset-0` to all images:
-```tsx
-// Before
-<img className="w-full h-full object-cover" />
-
-// After  
-<img className="absolute inset-0 w-full h-full object-cover object-center" />
-```
-
-**Files Modified:**
-- `customer-spa/src/components/ProductCard.tsx` (all 4 layouts)
-
-**Result:** Images now properly fill their containers without gaps.
-
----
-
-## ✅ Issue 2: TypeScript Lint Errors - FIXED
-
-**Problem:** Multiple TypeScript errors causing fragile code that's easy to corrupt.
-
-**Solution:** Created proper type definitions:
-
-**New File:** `customer-spa/src/types/product.ts`
-```typescript
-export interface Product {
-  id: number;
-  name: string;
-  slug: string;
-  price: string;
-  regular_price?: string;
-  sale_price?: string;
-  on_sale: boolean;
-  stock_status: 'instock' | 'outofstock' | 'onbackorder';
-  image?: string;
-  // ... more fields
-}
-
-export interface ProductsResponse {
-  products: Product[];
-  total: number;
-  total_pages: number;
-  current_page: number;
-}
-```
-
-**Files Modified:**
-- `customer-spa/src/types/product.ts` (created)
-- `customer-spa/src/pages/Shop/index.tsx` (added types)
-- `customer-spa/src/pages/Product/index.tsx` (added types)
-
-**Result:** Zero TypeScript errors, code is now stable and safe to modify.
-
----
-
-## ✅ Issue 3: Direct URL Access - FIXED
-
-**Problem:** Accessing `/product/edukasi-anak` directly redirected to `/shop`.
-
-**Root Cause:** PHP template override wasn't checking for `is_product()`.
-
-**Solution:** Added `is_product()` check in full SPA mode:
-```php
-// Before
-if (is_woocommerce() || is_cart() || is_checkout() || is_account_page())
-
-// After
-if (is_woocommerce() || is_product() || is_cart() || is_checkout() || is_account_page())
-```
-
-**Files Modified:**
-- `includes/Frontend/TemplateOverride.php` (line 83)
-
-**Result:** Direct product URLs now work correctly, no redirect.
-
----
-
-## ✅ Issue 4: Add to Cart API - COMPLETE
-
-**Problem:** Add to cart failed because REST API endpoint didn't exist.
-
-**Solution:** Created complete Cart API Controller with all endpoints:
-
-**New File:** `includes/Api/Controllers/CartController.php`
-
-**Endpoints Created:**
-- `GET /cart` - Get cart contents
-- `POST /cart/add` - Add product to cart
-- `POST /cart/update` - Update item quantity
-- `POST /cart/remove` - Remove item from cart
-- `POST /cart/clear` - Clear entire cart
-- `POST /cart/apply-coupon` - Apply coupon code
-- `POST /cart/remove-coupon` - Remove coupon
-
-**Features:**
-- Proper WooCommerce cart integration
-- Stock validation
-- Error handling
-- Formatted responses with totals
-- Coupon support
-
-**Files Modified:**
-- `includes/Api/Controllers/CartController.php` (created)
-- `includes/Api/Routes.php` (registered controller)
-
-**Result:** Add to cart now works! Full cart functionality available.
-
----
-
-## 📋 Testing Checklist
-
-### 1. Test TypeScript (No Errors)
-```bash
-cd customer-spa
-npm run build
-# Should complete without errors
-```
-
-### 2. Test Images
-1. Go to `/shop`
-2. Check all product images
-3. Should fill containers completely
-4. No gaps or distortion
-
-### 3. Test Direct URLs
-1. Copy product URL: `https://woonoow.local/product/edukasi-anak`
-2. Open in new tab
-3. Should load product page directly
-4. No redirect to `/shop`
-
-### 4. Test Add to Cart
-1. Go to shop page
-2. Click "Add to Cart" on any product
-3. Should show success toast
-4. Check browser console - no errors
-5. Cart count should update
-
-### 5. Test Product Page
-1. Click any product
-2. Should navigate to `/product/slug-name`
-3. See full product details
-4. Change quantity
-5. Click "Add to Cart"
-6. Should work and show success
-
----
-
-## 🎯 What's Working Now
-
-### Frontend
-- ✅ Shop page with products
-- ✅ Product detail page
-- ✅ Search and filters
-- ✅ Pagination
-- ✅ Add to cart functionality
-- ✅ 4 layout variants (Classic, Modern, Boutique, Launch)
-- ✅ Currency formatting
-- ✅ Direct URL access
-
-### Backend
-- ✅ Settings API
-- ✅ Cart API (complete)
-- ✅ Template override system
-- ✅ Mode detection (disabled/full/checkout-only)
-
-### Code Quality
-- ✅ Zero TypeScript errors
-- ✅ Proper type definitions
-- ✅ Stable, maintainable code
-- ✅ No fragile patterns
-
----
-
-## 📁 Files Changed Summary
-
-```
-customer-spa/src/
-├── types/
-│   └── product.ts                    # NEW - Type definitions
-├── components/
-│   └── ProductCard.tsx               # FIXED - Image positioning
-├── pages/
-│   ├── Shop/index.tsx                # FIXED - Added types
-│   └── Product/index.tsx             # FIXED - Added types
-
-includes/
-├── Frontend/
-│   └── TemplateOverride.php          # FIXED - Added is_product()
-└── Api/
-    ├── Controllers/
-    │   └── CartController.php        # NEW - Complete cart API
-    └── Routes.php                    # MODIFIED - Registered cart controller
-```
-
----
-
-## 🚀 Next Steps
-
-### Immediate Testing
-1. Clear browser cache
-2. Test all 4 issues above
-3. Verify no console errors
-
-### Future Development
-1. Cart page UI
-2. Checkout page
-3. Thank you page
-4. My Account pages
-5. Homepage builder
-6. Navigation integration
-
----
-
-## 🐛 Known Issues (None!)
-
-All major issues are now fixed. The codebase is:
-- ✅ Type-safe
-- ✅ Stable
-- ✅ Maintainable
-- ✅ Fully functional
-
----
-
-**Status:** ALL 4 ISSUES FIXED ✅
-**Ready for:** Full testing and continued development
-**Code Quality:** Excellent - No TypeScript errors, proper types, clean code

HASHROUTER_SOLUTION.md

@@ -1,434 +0,0 @@
-# HashRouter Solution - The Right Approach
-
-## Problem
-Direct product URLs like `https://woonoow.local/product/edukasi-anak` don't work because WordPress owns the `/product/` route.
-
-## Why Admin SPA Works
-
-Admin SPA uses HashRouter:
-```
-https://woonoow.local/wp-admin/admin.php?page=woonoow#/dashboard
-                                                        ↑
-                                                    Hash routing
-```
-
-**How it works:**
-1. WordPress loads: `/wp-admin/admin.php?page=woonoow`
-2. React takes over: `#/dashboard`
-3. Everything after `#` is client-side only
-4. WordPress never sees or processes it
-5. Works perfectly ✅
-
-## Why Customer SPA Should Use HashRouter Too
-
-### The Conflict
-
-**WordPress owns these routes:**
-- `/product/` - WooCommerce product pages
-- `/cart/` - WooCommerce cart
-- `/checkout/` - WooCommerce checkout
-- `/my-account/` - WooCommerce account
-
-**We can't override them reliably** because:
-- WordPress processes the URL first
-- Theme templates load before our SPA
-- Canonical redirects interfere
-- SEO and caching issues
-
-### The Solution: HashRouter
-
-Use hash-based routing like Admin SPA:
-
-```
-https://woonoow.local/shop#/product/edukasi-anak
-                           ↑
-                       Hash routing
-```
-
-**Benefits:**
-- ✅ WordPress loads `/shop` (valid page)
-- ✅ React handles `#/product/edukasi-anak`
-- ✅ No WordPress conflicts
-- ✅ Works for direct access
-- ✅ Works for sharing links
-- ✅ Works for email campaigns
-- ✅ Reliable and predictable
-
----
-
-## Implementation
-
-### Changed File: App.tsx
-
-```tsx
-// Before
-import { BrowserRouter } from 'react-router-dom';
-
-<BrowserRouter>
-  <Routes>
-    <Route path="/product/:slug" element={<Product />} />
-  </Routes>
-</BrowserRouter>
-
-// After
-import { HashRouter } from 'react-router-dom';
-
-<HashRouter>
-  <Routes>
-    <Route path="/product/:slug" element={<Product />} />
-  </Routes>
-</HashRouter>
-```
-
-**That's it!** React Router's `Link` components automatically use hash URLs.
-
----
-
-## URL Format
-
-### Shop Page
-```
-https://woonoow.local/shop
-https://woonoow.local/shop#/
-https://woonoow.local/shop#/shop
-```
-
-All work! The SPA loads on `/shop` page.
-
-### Product Pages
-```
-https://woonoow.local/shop#/product/edukasi-anak
-https://woonoow.local/shop#/product/test-variable
-```
-
-### Cart
-```
-https://woonoow.local/shop#/cart
-```
-
-### Checkout
-```
-https://woonoow.local/shop#/checkout
-```
-
-### My Account
-```
-https://woonoow.local/shop#/my-account
-```
-
----
-
-## How It Works
-
-### URL Structure
-```
-https://woonoow.local/shop#/product/edukasi-anak
-                      ↑    ↑
-                      |    └─ Client-side route (React Router)
-                      └────── Server-side route (WordPress)
-```
-
-### Request Flow
-
-1. **Browser requests:** `https://woonoow.local/shop#/product/edukasi-anak`
-2. **WordPress receives:** `https://woonoow.local/shop`
-   - The `#/product/edukasi-anak` part is NOT sent to server
-3. **WordPress loads:** Shop page template with SPA
-4. **React Router sees:** `#/product/edukasi-anak`
-5. **React Router shows:** Product component
-6. **Result:** Product page displays ✅
-
-### Why This Works
-
-**Hash fragments are client-side only:**
-- Browsers don't send hash to server
-- WordPress never sees `#/product/edukasi-anak`
-- No conflicts with WordPress routes
-- React Router handles everything after `#`
-
----
-
-## Use Cases
-
-### 1. Direct Access ✅
-User types URL in browser:
-```
-https://woonoow.local/shop#/product/edukasi-anak
-```
-**Result:** Product page loads directly
-
-### 2. Sharing Links ✅
-User shares product link:
-```
-Copy: https://woonoow.local/shop#/product/edukasi-anak
-Paste in chat/email
-Click link
-```
-**Result:** Product page loads for recipient
-
-### 3. Email Campaigns ✅
-Admin sends promotional email:
-```html
-<a href="https://woonoow.local/shop#/product/special-offer">
-  Check out our special offer!
-</a>
-```
-**Result:** Product page loads when clicked
-
-### 4. Social Media ✅
-Share on Facebook, Twitter, etc:
-```
-https://woonoow.local/shop#/product/edukasi-anak
-```
-**Result:** Product page loads when clicked
-
-### 5. Bookmarks ✅
-User bookmarks product page:
-```
-Bookmark: https://woonoow.local/shop#/product/edukasi-anak
-```
-**Result:** Product page loads when bookmark opened
-
-### 6. QR Codes ✅
-Generate QR code for product:
-```
-QR → https://woonoow.local/shop#/product/edukasi-anak
-```
-**Result:** Product page loads when scanned
-
----
-
-## Comparison: BrowserRouter vs HashRouter
-
-| Feature | BrowserRouter | HashRouter |
-|---------|---------------|------------|
-| **URL Format** | `/product/slug` | `#/product/slug` |
-| **Clean URLs** | ✅ Yes | ❌ Has `#` |
-| **SEO** | ✅ Better | ⚠️ Acceptable |
-| **Direct Access** | ❌ Conflicts | ✅ Works |
-| **WordPress Conflicts** | ❌ Many | ✅ None |
-| **Sharing** | ❌ Unreliable | ✅ Reliable |
-| **Email Links** | ❌ Breaks | ✅ Works |
-| **Setup Complexity** | ❌ Complex | ✅ Simple |
-| **Reliability** | ❌ Fragile | ✅ Solid |
-
-**Winner:** HashRouter for Customer SPA ✅
-
----
-
-## SEO Considerations
-
-### Hash URLs and SEO
-
-**Modern search engines handle hash URLs:**
-- Google can crawl hash URLs
-- Bing supports hash routing
-- Social media platforms parse them
-
-**Best practices:**
-1. Use server-side rendering for SEO-critical pages
-2. Add proper meta tags
-3. Use canonical URLs
-4. Submit sitemap with actual product URLs
-
-### Our Approach
-
-**For SEO:**
-- WooCommerce product pages still exist
-- Search engines index actual product URLs
-- Canonical tags point to real products
-
-**For Users:**
-- SPA provides better UX
-- Hash URLs work reliably
-- No broken links
-
-**Best of both worlds!** ✅
-
----
-
-## Migration Notes
-
-### Existing Links
-
-If you already shared links with BrowserRouter format:
-
-**Old format:**
-```
-https://woonoow.local/product/edukasi-anak
-```
-
-**New format:**
-```
-https://woonoow.local/shop#/product/edukasi-anak
-```
-
-**Solution:** Add redirect or keep both working:
-```php
-// In TemplateOverride.php
-if (is_product()) {
-    // Redirect to hash URL
-    $product_slug = get_post_field('post_name', get_the_ID());
-    wp_redirect(home_url("/shop#/product/$product_slug"));
-    exit;
-}
-```
-
----
-
-## Testing
-
-### Test 1: Direct Access
-1. Open new browser tab
-2. Type: `https://woonoow.local/shop#/product/edukasi-anak`
-3. Press Enter
-4. **Expected:** Product page loads ✅
-
-### Test 2: Navigation
-1. Go to shop page
-2. Click product
-3. **Expected:** URL changes to `#/product/slug` ✅
-4. **Expected:** Product page shows ✅
-
-### Test 3: Refresh
-1. On product page
-2. Press F5
-3. **Expected:** Page reloads, product still shows ✅
-
-### Test 4: Bookmark
-1. Bookmark product page
-2. Close browser
-3. Open bookmark
-4. **Expected:** Product page loads ✅
-
-### Test 5: Share Link
-1. Copy product URL
-2. Open in incognito window
-3. **Expected:** Product page loads ✅
-
-### Test 6: Back Button
-1. Navigate: Shop → Product → Cart
-2. Press back button
-3. **Expected:** Goes back to product ✅
-4. Press back again
-5. **Expected:** Goes back to shop ✅
-
----
-
-## Advantages Over BrowserRouter
-
-### 1. Zero WordPress Conflicts
-- No canonical redirect issues
-- No 404 problems
-- No template override complexity
-- No rewrite rule conflicts
-
-### 2. Reliable Direct Access
-- Always works
-- No server configuration needed
-- No .htaccess rules
-- No WordPress query manipulation
-
-### 3. Perfect for Sharing
-- Links work everywhere
-- Email campaigns reliable
-- Social media compatible
-- QR codes work
-
-### 4. Simple Implementation
-- One line change (BrowserRouter → HashRouter)
-- No PHP changes needed
-- No server configuration
-- No complex debugging
-
-### 5. Consistent with Admin SPA
-- Same routing approach
-- Proven to work
-- Easy to understand
-- Maintainable
-
----
-
-## Real-World Examples
-
-### Example 1: Product Promotion
-```
-Email subject: Special Offer on Edukasi Anak!
-Email body: Click here to view:
-https://woonoow.local/shop#/product/edukasi-anak
-```
-✅ Works perfectly
-
-### Example 2: Social Media Post
-```
-Facebook post:
-"Check out our new product! 🎉
-https://woonoow.local/shop#/product/edukasi-anak"
-```
-✅ Link works for all followers
-
-### Example 3: Customer Support
-```
-Support: "Please check this product page:"
-https://woonoow.local/shop#/product/edukasi-anak
-
-Customer: *clicks link*
-```
-✅ Page loads immediately
-
-### Example 4: Affiliate Marketing
-```
-Affiliate link:
-https://woonoow.local/shop#/product/edukasi-anak?ref=affiliate123
-```
-✅ Works with query parameters
-
----
-
-## Summary
-
-**Problem:** BrowserRouter conflicts with WordPress routes
-
-**Solution:** Use HashRouter like Admin SPA
-
-**Benefits:**
-- ✅ Direct access works
-- ✅ Sharing works
-- ✅ Email campaigns work
-- ✅ No WordPress conflicts
-- ✅ Simple and reliable
-
-**Trade-off:**
-- URLs have `#` in them
-- Acceptable for SPA use case
-
-**Result:** Reliable, shareable product links! 🎉
-
----
-
-## Files Modified
-
-1. **customer-spa/src/App.tsx**
-   - Changed: `BrowserRouter` → `HashRouter`
-   - That's it!
-
-## URL Examples
-
-**Shop:**
-- `https://woonoow.local/shop`
-- `https://woonoow.local/shop#/`
-
-**Products:**
-- `https://woonoow.local/shop#/product/edukasi-anak`
-- `https://woonoow.local/shop#/product/test-variable`
-
-**Cart:**
-- `https://woonoow.local/shop#/cart`
-
-**Checkout:**
-- `https://woonoow.local/shop#/checkout`
-
-**Account:**
-- `https://woonoow.local/shop#/my-account`
-
-All work perfectly! ✅

IMPLEMENTATION_STATUS.md

@@ -1,270 +0,0 @@
-# WooNooW Customer SPA - Implementation Status
-
-## ✅ Phase 1-3: COMPLETE
-
-### 1. Core Infrastructure
-- ✅ Template override system
-- ✅ SPA mount points
-- ✅ React Router setup
-- ✅ TanStack Query integration
-
-### 2. Settings System
-- ✅ REST API endpoints (`/wp-json/woonoow/v1/settings/customer-spa`)
-- ✅ Settings Controller with validation
-- ✅ Admin SPA Settings UI (`Settings > Customer SPA`)
-- ✅ Three modes: Disabled, Full SPA, Checkout-Only
-- ✅ Four layouts: Classic, Modern, Boutique, Launch
-- ✅ Color customization (primary, secondary, accent)
-- ✅ Typography presets (4 options)
-- ✅ Checkout pages configuration
-
-### 3. Theme System
-- ✅ ThemeProvider context
-- ✅ Design token system (CSS variables)
-- ✅ Google Fonts loading
-- ✅ Layout detection hooks
-- ✅ Mode detection hooks
-- ✅ Dark mode support
-
-### 4. Layout Components
-- ✅ **Classic Layout** - Traditional with sidebar, 4-column footer
-- ✅ **Modern Layout** - Centered logo, minimalist
-- ✅ **Boutique Layout** - Luxury serif fonts, elegant
-- ✅ **Launch Layout** - Minimal checkout flow
-
-### 5. Currency System
-- ✅ WooCommerce currency integration
-- ✅ Respects decimal places
-- ✅ Thousand/decimal separators
-- ✅ Symbol positioning
-- ✅ Helper functions (`formatPrice`, `formatDiscount`, etc.)
-
-### 6. Product Components
-- ✅ **ProductCard** with 4 layout variants
-- ✅ Sale badges with discount percentage
-- ✅ Stock status handling
-- ✅ Add to cart functionality
-- ✅ Responsive images with hover effects
-
-### 7. Shop Page
-- ✅ Product grid with ProductCard
-- ✅ Search functionality
-- ✅ Category filtering
-- ✅ Pagination
-- ✅ Loading states
-- ✅ Empty states
-
----
-
-## 📊 What's Working Now
-
-### Admin Side:
-1. Navigate to **WooNooW > Settings > Customer SPA**
-2. Configure:
-   - Mode (Disabled/Full/Checkout-Only)
-   - Layout (Classic/Modern/Boutique/Launch)
-   - Colors (Primary, Secondary, Accent)
-   - Typography (4 presets)
-   - Checkout pages (for Checkout-Only mode)
-3. Settings save via REST API
-4. Settings load on page refresh
-
-### Frontend Side:
-1. Visit WooCommerce shop page
-2. See:
-   - Selected layout (header + footer)
-   - Custom brand colors applied
-   - Products with layout-specific cards
-   - Proper currency formatting
-   - Sale badges and discounts
-   - Search and filters
-   - Pagination
-
----
-
-## 🎨 Layout Showcase
-
-### Classic Layout
-- Traditional ecommerce design
-- Sidebar navigation
-- Border cards with shadow on hover
-- 4-column footer
-- **Best for:** B2B, traditional retail
-
-### Modern Layout
-- Minimalist, clean design
-- Centered logo and navigation
-- Hover overlay with CTA
-- Simple centered footer
-- **Best for:** Fashion, lifestyle brands
-
-### Boutique Layout
-- Luxury, elegant design
-- Serif fonts throughout
-- 3:4 aspect ratio images
-- Uppercase tracking
-- **Best for:** High-end fashion, luxury goods
-
-### Launch Layout
-- Single product funnel
-- Minimal header (logo only)
-- No footer distractions
-- Prominent "Buy Now" buttons
-- **Best for:** Digital products, courses, launches
-
----
-
-## 🧪 Testing Guide
-
-### 1. Enable Customer SPA
-```
-Admin > WooNooW > Settings > Customer SPA
-- Select "Full SPA" mode
-- Choose a layout
-- Pick colors
-- Save
-```
-
-### 2. Test Shop Page
-```
-Visit: /shop or your WooCommerce shop page
-Expected:
-- Layout header/footer
-- Product grid with selected layout style
-- Currency formatted correctly
-- Search works
-- Category filter works
-- Pagination works
-```
-
-### 3. Test Different Layouts
-```
-Switch between layouts in settings
-Refresh shop page
-See different card styles and layouts
-```
-
-### 4. Test Checkout-Only Mode
-```
-- Select "Checkout Only" mode
-- Check which pages to override
-- Visit shop page (should use theme)
-- Visit checkout page (should use SPA)
-```
-
----
-
-## 📋 Next Steps
-
-### Phase 4: Homepage Builder (Pending)
-- Hero section component
-- Featured products section
-- Categories section
-- Testimonials section
-- Drag-and-drop ordering
-- Section configuration
-
-### Phase 5: Navigation Integration (Pending)
-- Fetch WordPress menus via API
-- Render in SPA layouts
-- Mobile menu
-- Cart icon with count
-- User account dropdown
-
-### Phase 6: Complete Pages (In Progress)
-- ✅ Shop page
-- ⏳ Product detail page
-- ⏳ Cart page
-- ⏳ Checkout page
-- ⏳ Thank you page
-- ⏳ My Account pages
-
----
-
-## 🐛 Known Issues
-
-### TypeScript Warnings
-- API response types not fully defined
-- Won't prevent app from running
-- Can be fixed with proper type definitions
-
-### To Fix Later:
-- Add proper TypeScript interfaces for API responses
-- Add loading states for all components
-- Add error boundaries
-- Add analytics tracking
-- Add SEO meta tags
-
----
-
-## 📁 File Structure
-
-```
-customer-spa/
-├── src/
-│   ├── App.tsx                    # Main app with ThemeProvider
-│   ├── main.tsx                   # Entry point
-│   ├── contexts/
-│   │   └── ThemeContext.tsx       # Theme configuration & hooks
-│   ├── layouts/
-│   │   └── BaseLayout.tsx         # 4 layout components
-│   ├── components/
-│   │   └── ProductCard.tsx        # Layout-aware product card
-│   ├── lib/
-│   │   └── currency.ts            # WooCommerce currency utilities
-│   ├── pages/
-│   │   └── Shop/
-│   │       └── index.tsx          # Shop page with ProductCard
-│   └── styles/
-│       └── theme.css              # Design tokens
-
-includes/
-├── Api/Controllers/
-│   └── SettingsController.php     # Settings REST API
-├── Frontend/
-│   ├── Assets.php                 # Pass settings to frontend
-│   └── TemplateOverride.php       # SPA template override
-└── Compat/
-    └── NavigationRegistry.php     # Admin menu structure
-
-admin-spa/
-└── src/routes/Settings/
-    └── CustomerSPA.tsx            # Settings UI
-```
-
----
-
-## 🚀 Ready for Production?
-
-### ✅ Ready:
-- Settings system
-- Theme system
-- Layout system
-- Currency formatting
-- Shop page
-- Product cards
-
-### ⏳ Needs Work:
-- Complete all pages
-- Add navigation
-- Add homepage builder
-- Add proper error handling
-- Add loading states
-- Add analytics
-- Add SEO
-
----
-
-## 📞 Support
-
-For issues or questions:
-1. Check this document
-2. Check `CUSTOMER_SPA_ARCHITECTURE.md`
-3. Check `CUSTOMER_SPA_SETTINGS.md`
-4. Check `CUSTOMER_SPA_THEME_SYSTEM.md`
-
----
-
-**Last Updated:** Phase 3 Complete
-**Status:** Shop page functional, ready for testing
-**Next:** Complete remaining pages (Product, Cart, Checkout, Account)

LICENSING_MODULE.md

@@ -0,0 +1,284 @@
+# Licensing Module Documentation
+
+## Overview
+
+WooNooW's Licensing Module provides software license management for digital products. It supports two activation methods:
+
+1. **Simple API** - Direct license key validation via API
+2. **Secure OAuth** - User verification via vendor portal before activation
+
+---
+
+## API Endpoints
+
+### Admin Endpoints (Authenticated Admin)
+
+```
+GET    /licenses                      # List all licenses (with pagination, search)
+GET    /licenses/{id}                 # Get single license
+POST   /licenses                      # Create license
+PUT    /licenses/{id}                 # Update license
+DELETE /licenses/{id}                 # Delete license
+```
+
+### Public Endpoints (For Client Software)
+
+```
+POST   /licenses/validate             # Validate license key
+POST   /licenses/activate             # Activate license on domain
+POST   /licenses/deactivate           # Deactivate license from domain
+```
+
+### OAuth Endpoints (Authenticated User)
+
+```
+GET    /licenses/oauth/validate       # Validate OAuth state and license ownership
+POST   /licenses/oauth/confirm        # Confirm activation and get token
+```
+
+---
+
+## Activation Flows
+
+### 1. Simple API Flow
+
+Direct license activation without user verification. Suitable for trusted environments.
+
+```
+Client                     Vendor API
+  |                            |
+  |-- POST /licenses/activate -|
+  |   {license_key, domain}    |
+  |                            |
+  |<-- {success, activation_id}|
+```
+
+**Example Request:**
+```bash
+curl -X POST "https://vendor.com/wp-json/woonoow/v1/licenses/activate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "license_key": "XXXX-YYYY-ZZZZ-WWWW",
+    "domain": "https://customer-site.com",
+    "machine_id": "optional-unique-id"
+  }'
+```
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "activation_id": 123,
+  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
+  "status": "active",
+  "expires_at": "2025-01-31T00:00:00Z",
+  "activation_limit": 3,
+  "activation_count": 1
+}
+```
+
+---
+
+### 2. Secure OAuth Flow (Recommended)
+
+User must verify ownership on vendor portal before activation. More secure.
+
+```
+Client                     Vendor Portal              Vendor API
+  |                            |                          |
+  |-- POST /licenses/activate -|                          |
+  |   {license_key, domain}    |                          |
+  |                            |                          |
+  |<-- {oauth_redirect, state}-|                          |
+  |                            |                          |
+  |== User redirects browser ==|                          |
+  |                            |                          |
+  |-------- BROWSER ---------->|                          |
+  |  /my-account/license-connect?license_key=...&state=...|
+  |                            |                          |
+  |                     [User logs in if needed]          |
+  |                     [User sees confirmation page]     |
+  |                     [User clicks "Authorize"]         |
+  |                            |                          |
+  |                            |-- POST /oauth/confirm -->|
+  |                            |<-- {token} --------------|
+  |                            |                          |
+  |<------- REDIRECT ----------|                          |
+  |  {return_url}?activation_token=xxx                    |
+  |                            |                          |
+  |-- POST /licenses/activate ----------------------->    |
+  |   {license_key, activation_token}                     |
+  |                            |                          |
+  |<-- {success, activation_id} --------------------------|
+```
+
+---
+
+## OAuth Flow Step by Step
+
+### Step 1: Client Requests Activation (OAuth Mode)
+
+```bash
+curl -X POST "https://vendor.com/wp-json/woonoow/v1/licenses/activate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "license_key": "XXXX-YYYY-ZZZZ-WWWW",
+    "domain": "https://customer-site.com",
+    "return_url": "https://customer-site.com/activation-callback",
+    "activation_mode": "oauth"
+  }'
+```
+
+**Response (OAuth Required):**
+```json
+{
+  "success": false,
+  "oauth_required": true,
+  "oauth_redirect": "https://vendor.com/my-account/license-connect/?license_key=XXXX-YYYY-ZZZZ-WWWW&site_url=https://customer-site.com&return_url=https://customer-site.com/activation-callback&state=abc123&nonce=xyz789",
+  "state": "abc123"
+}
+```
+
+### Step 2: User Opens Browser to OAuth URL
+
+Client opens the `oauth_redirect` URL in user's browser. The user:
+1. Logs into vendor portal (if not already)
+2. Sees license activation confirmation page
+3. Reviews license key and requesting site
+4. Clicks "Authorize" to confirm
+
+### Step 3: User Gets Redirected Back
+
+After authorization, user is redirected to `return_url` with token:
+
+```
+https://customer-site.com/activation-callback?activation_token=xyz123&license_key=XXXX-YYYY-ZZZZ-WWWW&nonce=xyz789
+```
+
+### Step 4: Client Exchanges Token for Activation
+
+```bash
+curl -X POST "https://vendor.com/wp-json/woonoow/v1/licenses/activate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "license_key": "XXXX-YYYY-ZZZZ-WWWW",
+    "domain": "https://customer-site.com",
+    "activation_token": "xyz123"
+  }'
+```
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "activation_id": 456,
+  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
+  "status": "active"
+}
+```
+
+---
+
+## Configuration
+
+### Site-Level Settings
+
+In Admin SPA: **Settings > Licensing**
+
+| Setting | Description |
+|---------|-------------|
+| Default Activation Method | `api` or `oauth` - Default for all products |
+| License Key Format | Format pattern for generated keys |
+| Default Validity Period | Days until license expires |
+| Default Activation Limit | Max activations per license |
+
+### Per-Product Settings
+
+In Admin SPA: **Products > Edit Product > General Tab**
+
+| Setting | Description |
+|---------|-------------|
+| Enable Licensing | Toggle to enable license generation |
+| Activation Method | `Use Site Default`, `Simple API`, or `Secure OAuth` |
+
+---
+
+## Database Schema
+
+### Licenses Table (`wp_woonoow_licenses`)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | BIGINT | Primary key |
+| license_key | VARCHAR(255) | Unique license key |
+| product_id | BIGINT | WooCommerce product ID |
+| order_id | BIGINT | WooCommerce order ID |
+| user_id | BIGINT | Customer user ID |
+| status | VARCHAR(50) | active, inactive, expired, revoked |
+| activation_limit | INT | Max allowed activations |
+| activation_count | INT | Current activation count |
+| expires_at | DATETIME | Expiration date |
+| created_at | DATETIME | Created timestamp |
+| updated_at | DATETIME | Updated timestamp |
+
+### Activations Table (`wp_woonoow_license_activations`)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | BIGINT | Primary key |
+| license_id | BIGINT | Foreign key to licenses |
+| domain | VARCHAR(255) | Activated domain |
+| machine_id | VARCHAR(255) | Optional machine identifier |
+| status | VARCHAR(50) | active, deactivated, pending |
+| user_agent | TEXT | Client user agent |
+| activated_at | DATETIME | Activation timestamp |
+
+---
+
+## Customer SPA: License Connect Page
+
+The OAuth confirmation page is available at:
+```
+/my-account/license-connect/
+```
+
+### Query Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| license_key | Yes | License key to activate |
+| site_url | Yes | Requesting site URL |
+| return_url | Yes | Callback URL after authorization |
+| state | Yes | CSRF protection token |
+| nonce | No | Additional security nonce |
+
+### UI Features
+
+- **Focused Layout** - No header/sidebar/footer, just the authorization card
+- **Brand Display** - Shows vendor site name
+- **License Details** - Displays license key, site URL, product name
+- **Security Warning** - Warns user to only authorize trusted sites
+- **Authorize/Deny Buttons** - Clear actions for user
+
+---
+
+## Security Considerations
+
+1. **State Token** - Prevents CSRF attacks, expires after 5 minutes
+2. **Activation Token** - Single-use, expires after 5 minutes
+3. **User Verification** - OAuth ensures license owner authorizes activation
+4. **Domain Validation** - Tracks activated domains for audit
+5. **Rate Limiting** - Consider implementing on activation endpoints
+
+---
+
+## Files Reference
+
+| File | Purpose |
+|------|---------|
+| `includes/Modules/Licensing/LicensingModule.php` | Module registration, endpoint handlers |
+| `includes/Modules/Licensing/LicenseManager.php` | Core license operations |
+| `includes/Api/LicensesController.php` | REST API endpoints |
+| `customer-spa/src/pages/Account/LicenseConnect.tsx` | OAuth confirmation UI |
+| `customer-spa/src/pages/Account/index.tsx` | Routing for license pages |
+| `customer-spa/src/App.tsx` | Top-level routing (license-connect outside BaseLayout) |

MODULE_INTEGRATION_SUMMARY.md

@@ -1,255 +0,0 @@
-# Module System Integration Summary
-
-**Date**: December 26, 2025  
-**Status**: ✅ Complete
-
----
-
-## Overview
-
-All module-related features have been wired to check module status before displaying. When a module is disabled, its features are completely hidden from both admin and customer interfaces.
-
----
-
-## Integrated Features
-
-### 1. Newsletter Module (`newsletter`)
-
-#### Admin SPA
-**File**: `admin-spa/src/routes/Marketing/Newsletter.tsx`
-- ✅ Added `useModules()` hook
-- ✅ Shows disabled state UI when module is off
-- ✅ Provides link to Module Settings
-- ✅ Blocks access to newsletter subscribers page
-
-**Navigation**:
-- ✅ Newsletter menu item hidden when module disabled (NavigationRegistry.php)
-
-**Result**: When newsletter module is OFF:
-- ❌ No "Newsletter" menu item in Marketing
-- ❌ Newsletter page shows disabled message
-- ✅ User redirected to enable module in settings
-
----
-
-### 2. Wishlist Module (`wishlist`)
-
-#### Customer SPA
-
-**File**: `customer-spa/src/pages/Account/Wishlist.tsx`
-- ✅ Added `useModules()` hook
-- ✅ Shows disabled state UI when module is off
-- ✅ Provides "Continue Shopping" button
-- ✅ Blocks access to wishlist page
-
-**File**: `customer-spa/src/pages/Product/index.tsx`
-- ✅ Added `useModules()` hook
-- ✅ Wishlist button hidden when module disabled
-- ✅ Combined with settings check (`wishlistEnabled`)
-
-**File**: `customer-spa/src/components/ProductCard.tsx`
-- ✅ Added `useModules()` hook
-- ✅ Created `showWishlist` variable combining module + settings
-- ✅ All 4 layout variants updated (Classic, Modern, Boutique, Launch)
-- ✅ Heart icon hidden when module disabled
-
-**File**: `customer-spa/src/pages/Account/components/AccountLayout.tsx`
-- ✅ Added `useModules()` hook
-- ✅ Wishlist menu item filtered out when module disabled
-- ✅ Combined with settings check
-
-#### Backend API
-**File**: `includes/Frontend/WishlistController.php`
-- ✅ All endpoints check module status
-- ✅ Returns 403 error when module disabled
-- ✅ Endpoints: get, add, remove, clear
-
-**Result**: When wishlist module is OFF:
-- ❌ No heart icon on product cards (all layouts)
-- ❌ No wishlist button on product pages
-- ❌ No "Wishlist" menu item in My Account
-- ❌ Wishlist page shows disabled message
-- ❌ All wishlist API endpoints return 403
-
----
-
-### 3. Affiliate Module (`affiliate`)
-
-**Status**: Not yet implemented (module registered, no features built)
-
----
-
-### 4. Subscription Module (`subscription`)
-
-**Status**: Not yet implemented (module registered, no features built)
-
----
-
-### 5. Licensing Module (`licensing`)
-
-**Status**: Not yet implemented (module registered, no features built)
-
----
-
-## Implementation Pattern
-
-### Frontend Check (React)
-```tsx
-import { useModules } from '@/hooks/useModules';
-
-export default function MyComponent() {
-  const { isEnabled } = useModules();
-  
-  if (!isEnabled('my_module')) {
-    return <DisabledStateUI />;
-  }
-  
-  // Normal component render
-}
-```
-
-### Backend Check (PHP)
-```php
-use WooNooW\Core\ModuleRegistry;
-
-public function my_endpoint($request) {
-    if (!ModuleRegistry::is_enabled('my_module')) {
-        return new WP_Error('module_disabled', 'Module is disabled', ['status' => 403]);
-    }
-    
-    // Process request
-}
-```
-
-### Navigation Check (PHP)
-```php
-// In NavigationRegistry.php
-if (ModuleRegistry::is_enabled('my_module')) {
-    $children[] = ['label' => 'My Feature', 'path' => '/my-feature'];
-}
-```
-
----
-
-## Files Modified
-
-### Admin SPA (1 file)
-1. `admin-spa/src/routes/Marketing/Newsletter.tsx` - Newsletter page module check
-
-### Customer SPA (4 files)
-1. `customer-spa/src/pages/Account/Wishlist.tsx` - Wishlist page module check
-2. `customer-spa/src/pages/Product/index.tsx` - Product page wishlist button
-3. `customer-spa/src/components/ProductCard.tsx` - Product card wishlist hearts
-4. `customer-spa/src/pages/Account/components/AccountLayout.tsx` - Account menu filtering
-
-### Backend (2 files)
-1. `includes/Frontend/WishlistController.php` - API endpoint protection
-2. `includes/Compat/NavigationRegistry.php` - Navigation filtering
-
----
-
-## Testing Checklist
-
-### Newsletter Module
-- [ ] Toggle newsletter OFF in Settings > Modules
-- [ ] Verify "Newsletter" menu item disappears from Marketing
-- [ ] Try accessing `/marketing/newsletter` directly
-- [ ] Expected: Shows disabled message with link to settings
-- [ ] Toggle newsletter ON
-- [ ] Verify menu item reappears
-
-### Wishlist Module
-- [ ] Toggle wishlist OFF in Settings > Modules
-- [ ] Visit shop page
-- [ ] Expected: No heart icons on product cards
-- [ ] Visit product page
-- [ ] Expected: No wishlist button
-- [ ] Visit My Account
-- [ ] Expected: No "Wishlist" menu item
-- [ ] Try accessing `/my-account/wishlist` directly
-- [ ] Expected: Shows disabled message
-- [ ] Try API call: `GET /woonoow/v1/account/wishlist`
-- [ ] Expected: 403 error "Wishlist module is disabled"
-- [ ] Toggle wishlist ON
-- [ ] Verify all features reappear
-
----
-
-## Performance Impact
-
-### Caching
-- Module status cached for 5 minutes via React Query
-- Navigation tree rebuilt automatically when modules toggled
-- Minimal overhead (~1 DB query per page load)
-
-### Bundle Size
-- No impact - features still in bundle, just conditionally rendered
-- Future: Could implement code splitting for disabled modules
-
----
-
-## Future Enhancements
-
-### Phase 2
-1. **Code Splitting**: Lazy load module components when enabled
-2. **Module Dependencies**: Prevent disabling if other modules depend on it
-3. **Bulk Operations**: Enable/disable multiple modules at once
-4. **Module Analytics**: Track which modules are most used
-
-### Phase 3
-1. **Third-party Modules**: Allow installing external modules
-2. **Module Marketplace**: Browse and install community modules
-3. **Module Updates**: Version management for modules
-4. **Module Settings**: Per-module configuration pages
-
----
-
-## Developer Notes
-
-### Adding Module Checks to New Features
-
-1. **Import the hook**:
-   ```tsx
-   import { useModules } from '@/hooks/useModules';
-   ```
-
-2. **Check module status**:
-   ```tsx
-   const { isEnabled } = useModules();
-   if (!isEnabled('module_id')) return null;
-   ```
-
-3. **Backend protection**:
-   ```php
-   if (!ModuleRegistry::is_enabled('module_id')) {
-       return new WP_Error('module_disabled', 'Module disabled', ['status' => 403]);
-   }
-   ```
-
-4. **Navigation filtering**:
-   ```php
-   if (ModuleRegistry::is_enabled('module_id')) {
-       $children[] = ['label' => 'Feature', 'path' => '/feature'];
-   }
-   ```
-
-### Common Pitfalls
-
-1. **Don't forget backend checks** - Frontend checks can be bypassed
-2. **Check both module + settings** - Some features have dual toggles
-3. **Update navigation version** - Increment when adding/removing menu items
-4. **Clear cache on toggle** - ModuleRegistry auto-clears navigation cache
-
----
-
-## Summary
-
-✅ **Newsletter Module**: Fully integrated (admin page + navigation)  
-✅ **Wishlist Module**: Fully integrated (frontend UI + backend API + navigation)  
-⏳ **Affiliate Module**: Registered, awaiting implementation  
-⏳ **Subscription Module**: Registered, awaiting implementation  
-⏳ **Licensing Module**: Registered, awaiting implementation
-
-**Total Integration Points**: 7 files modified, 11 integration points added
-
-**Next Steps**: Implement Newsletter Campaigns feature (as per FEATURE_ROADMAP.md)

PHASE_2_3_4_SUMMARY.md

@@ -1,379 +0,0 @@
-# Phase 2, 3, 4 Implementation Summary
-
-**Date**: December 26, 2025  
-**Status**: ✅ Complete
-
----
-
-## Overview
-
-Successfully implemented the complete addon-module integration system with schema-based forms, custom React components, and a working example addon.
-
----
-
-## Phase 2: Schema-Based Form System ✅
-
-### Backend Components
-
-#### 1. **ModuleSettingsController.php** (NEW)
-- `GET /modules/{id}/settings` - Fetch module settings
-- `POST /modules/{id}/settings` - Save module settings  
-- `GET /modules/{id}/schema` - Fetch settings schema
-- Automatic validation against schema
-- Action hooks: `woonoow/module_settings_updated/{module_id}`
-- Storage pattern: `woonoow_module_{module_id}_settings`
-
-#### 2. **NewsletterSettings.php** (NEW)
-- Example implementation with 8 fields
-- Demonstrates all field types
-- Shows dynamic options (WordPress pages)
-- Registers schema via `woonoow/module_settings_schema` filter
-
-### Frontend Components
-
-#### 1. **SchemaField.tsx** (NEW)
-- Supports 8 field types: text, textarea, email, url, number, toggle, checkbox, select
-- Automatic validation (required, min/max)
-- Error display per field
-- Description and placeholder support
-
-#### 2. **SchemaForm.tsx** (NEW)
-- Renders complete form from schema object
-- Manages form state
-- Submit handling with loading state
-- Error display integration
-
-#### 3. **ModuleSettings.tsx** (NEW)
-- Generic settings page at `/settings/modules/:moduleId`
-- Auto-detects schema vs custom component
-- Fetches schema from API
-- Uses `useModuleSettings` hook
-- "Back to Modules" navigation
-
-#### 4. **useModuleSettings.ts** (NEW)
-- React hook for settings management
-- Auto-invalidates queries on save
-- Toast notifications
-- `saveSetting(key, value)` helper
-
-### Features Delivered
-
-✅ No-code settings forms via schema  
-✅ Automatic validation  
-✅ Persistent storage  
-✅ Newsletter example with 8 fields  
-✅ Gear icon shows on modules with settings  
-✅ Settings page auto-routes  
-
----
-
-## Phase 3: Advanced Features ✅
-
-### Window API Exposure
-
-#### **windowAPI.ts** (NEW)
-Exposes comprehensive API to addon developers via `window.WooNooW`:
-
-```typescript
-window.WooNooW = {
-  React,
-  ReactDOM,
-  hooks: {
-    useQuery, useMutation, useQueryClient,
-    useModules, useModuleSettings
-  },
-  components: {
-    Button, Input, Label, Textarea, Switch, Select,
-    Checkbox, Badge, Card, SettingsLayout, SettingsCard,
-    SchemaForm, SchemaField
-  },
-  icons: {
-    Settings, Save, Trash2, Edit, Plus, X, Check,
-    AlertCircle, Info, Loader2, Chevrons...
-  },
-  utils: {
-    api, toast, __
-  }
-}
-```
-
-**Benefits**:
-- Addons don't bundle React (use ours)
-- Access to all UI components
-- Consistent styling automatically
-- Type-safe with TypeScript definitions
-
-### Dynamic Component Loader
-
-#### **DynamicComponentLoader.tsx** (NEW)
-- Loads external React components from addon URLs
-- Script injection with error handling
-- Loading and error states
-- Global namespace management per module
-
-**Usage**:
-```tsx
-<DynamicComponentLoader
-  componentUrl="https://example.com/addon.js"
-  moduleId="my-addon"
-/>
-```
-
-### TypeScript Definitions
-
-#### **types/woonoow-addon.d.ts** (NEW)
-- Complete type definitions for `window.WooNooW`
-- Field schema types
-- Module registration types
-- Settings schema types
-- Enables IntelliSense for addon developers
-
-### Integration
-
-- Window API initialized in `App.tsx` on mount
-- `ModuleSettings.tsx` uses `DynamicComponentLoader` for custom components
-- Seamless fallback to schema-based forms
-
----
-
-## Phase 4: Production Polish ✅
-
-### Biteship Example Addon
-
-Complete working example demonstrating both approaches:
-
-#### **examples/biteship-addon/** (NEW)
-
-**Files**:
-- `biteship-addon.php` - Main plugin file
-- `src/Settings.jsx` - Custom React component
-- `package.json` - Build configuration
-- `README.md` - Complete documentation
-
-**Features Demonstrated**:
-1. Module registration with metadata
-2. Schema-based settings (Option A)
-3. Custom React component (Option B)
-4. Settings persistence
-5. Module enable/disable integration
-6. Shipping rate calculation hook
-7. Settings change reactions
-8. Test connection button
-9. Real-world UI patterns
-
-**Both Approaches Shown**:
-- **Schema**: 8 fields, no React needed, auto-generated form
-- **Custom**: Full React component using `window.WooNooW` API
-
-### Documentation
-
-Comprehensive README includes:
-- Installation instructions
-- File structure
-- API usage examples
-- Build configuration
-- Settings schema reference
-- Module registration reference
-- Testing guide
-- Next steps for real implementation
-
----
-
-## Bug Fixes
-
-### Footer Newsletter Form
-**Problem**: Form not showing despite module enabled  
-**Cause**: Redundant module checks (component + layout)  
-**Solution**: Removed check from `NewsletterForm.tsx`, kept layout-level filtering
-
-**Files Modified**:
-- `customer-spa/src/layouts/BaseLayout.tsx` - Added section filtering
-- `customer-spa/src/components/NewsletterForm.tsx` - Removed redundant check
-
----
-
-## Files Created/Modified
-
-### New Files (15)
-
-**Backend**:
-1. `includes/Api/ModuleSettingsController.php` - Settings API
-2. `includes/Modules/NewsletterSettings.php` - Example schema
-
-**Frontend**:
-3. `admin-spa/src/components/forms/SchemaField.tsx` - Field renderer
-4. `admin-spa/src/components/forms/SchemaForm.tsx` - Form renderer
-5. `admin-spa/src/routes/Settings/ModuleSettings.tsx` - Settings page
-6. `admin-spa/src/hooks/useModuleSettings.ts` - Settings hook
-7. `admin-spa/src/lib/windowAPI.ts` - Window API exposure
-8. `admin-spa/src/components/DynamicComponentLoader.tsx` - Component loader
-
-**Types**:
-9. `types/woonoow-addon.d.ts` - TypeScript definitions
-
-**Example Addon**:
-10. `examples/biteship-addon/biteship-addon.php` - Main file
-11. `examples/biteship-addon/src/Settings.jsx` - React component
-12. `examples/biteship-addon/package.json` - Build config
-13. `examples/biteship-addon/README.md` - Documentation
-
-**Documentation**:
-14. `PHASE_2_3_4_SUMMARY.md` - This file
-
-### Modified Files (6)
-
-1. `admin-spa/src/App.tsx` - Added Window API initialization, ModuleSettings route
-2. `includes/Api/Routes.php` - Registered ModuleSettingsController
-3. `includes/Core/ModuleRegistry.php` - Added `has_settings: true` to newsletter
-4. `woonoow.php` - Initialize NewsletterSettings
-5. `customer-spa/src/layouts/BaseLayout.tsx` - Newsletter section filtering
-6. `customer-spa/src/components/NewsletterForm.tsx` - Removed redundant check
-
----
-
-## API Endpoints Added
-
-```
-GET  /woonoow/v1/modules/{module_id}/settings
-POST /woonoow/v1/modules/{module_id}/settings
-GET  /woonoow/v1/modules/{module_id}/schema
-```
-
----
-
-## For Addon Developers
-
-### Quick Start (Schema-Based)
-
-```php
-// 1. Register addon
-add_filter('woonoow/addon_registry', function($addons) {
-    $addons['my-addon'] = [
-        'name' => 'My Addon',
-        'category' => 'shipping',
-        'has_settings' => true,
-    ];
-    return $addons;
-});
-
-// 2. Register schema
-add_filter('woonoow/module_settings_schema', function($schemas) {
-    $schemas['my-addon'] = [
-        'api_key' => [
-            'type' => 'text',
-            'label' => 'API Key',
-            'required' => true,
-        ],
-    ];
-    return $schemas;
-});
-
-// 3. Use settings
-$settings = get_option('woonoow_module_my-addon_settings');
-```
-
-**Result**: Automatic settings page with form, validation, and persistence!
-
-### Quick Start (Custom React)
-
-```javascript
-// Use window.WooNooW API
-const { React, hooks, components } = window.WooNooW;
-const { useModuleSettings } = hooks;
-const { SettingsLayout, Button, Input } = components;
-
-function MySettings() {
-  const { settings, updateSettings } = useModuleSettings('my-addon');
-  
-  return React.createElement(SettingsLayout, { title: 'My Settings' },
-    React.createElement(Input, {
-      value: settings?.api_key || '',
-      onChange: (e) => updateSettings.mutate({ api_key: e.target.value })
-    })
-  );
-}
-
-// Export to global
-window.WooNooWAddon_my_addon = MySettings;
-```
-
----
-
-## Testing Checklist
-
-### Phase 2 ✅
-- [x] Newsletter module shows gear icon
-- [x] Settings page loads at `/settings/modules/newsletter`
-- [x] Form renders with 8 fields
-- [x] Settings save correctly
-- [x] Settings persist on refresh
-- [x] Validation works (required fields)
-- [x] Select dropdown shows WordPress pages
-
-### Phase 3 ✅
-- [x] `window.WooNooW` API available in console
-- [x] All components accessible
-- [x] All hooks accessible
-- [x] Dynamic component loader works
-
-### Phase 4 ✅
-- [x] Biteship addon structure complete
-- [x] Both schema and custom approaches documented
-- [x] Example component uses Window API
-- [x] Build configuration provided
-
-### Bug Fixes ✅
-- [x] Footer newsletter form shows when module enabled
-- [x] Footer newsletter section hides when module disabled
-
----
-
-## Performance Impact
-
-- **Window API**: Initialized once on app mount (~5ms)
-- **Dynamic Loader**: Lazy loads components only when needed
-- **Schema Forms**: No runtime overhead, pure React
-- **Settings API**: Cached by React Query
-
----
-
-## Backward Compatibility
-
-✅ **100% Backward Compatible**
-- Existing modules work without changes
-- Schema registration is optional
-- Custom components are optional
-- Addons without settings still function
-- No breaking changes to existing APIs
-
----
-
-## Next Steps (Optional)
-
-### For Core
-- [ ] Add conditional field visibility to schema
-- [ ] Add field dependencies (show field B if field A is true)
-- [ ] Add file upload field type
-- [ ] Add color picker field type
-- [ ] Add repeater field type
-
-### For Addons
-- [ ] Create more example addons
-- [ ] Create addon starter template repository
-- [ ] Create video tutorials
-- [ ] Create addon marketplace
-
----
-
-## Conclusion
-
-**Phase 2, 3, and 4 are complete!** The system now provides:
-
-1. **Schema-based forms** - No-code settings for simple addons
-2. **Custom React components** - Full control for complex addons
-3. **Window API** - Complete toolkit for addon developers
-4. **Working example** - Biteship addon demonstrates everything
-5. **TypeScript support** - Type-safe development
-6. **Documentation** - Comprehensive guides and examples
-
-**The module system is now production-ready for both built-in modules and external addons!**

PRODUCT_PAGE_COMPLETE.md

@@ -1,400 +0,0 @@
-# ✅ Product Page Implementation - COMPLETE
-
-## 📊 Summary
-
-Successfully implemented a complete, industry-standard product page for Customer SPA based on extensive research from Baymard Institute and e-commerce best practices.
-
----
-
-## 🎯 What We Implemented
-
-### **Phase 1: Core Features** ✅ COMPLETE
-
-#### 1. Image Gallery with Thumbnail Slider
-- ✅ Large main image display (aspect-square)
-- ✅ Horizontal scrollable thumbnail slider
-- ✅ Arrow navigation (left/right) for >4 images
-- ✅ Active thumbnail highlighted with ring border
-- ✅ Click thumbnail to change main image
-- ✅ Smooth scroll animation
-- ✅ Hidden scrollbar for clean UI
-- ✅ Responsive (swipeable on mobile)
-
-#### 2. Variation Selector
-- ✅ Dropdown for each variation attribute
-- ✅ "Choose an option" placeholder
-- ✅ Auto-switch main image when variation selected
-- ✅ Auto-update price based on variation
-- ✅ Auto-update stock status
-- ✅ Validation: Disable Add to Cart until all options selected
-- ✅ Error toast if incomplete selection
-
-#### 3. Enhanced Buy Section
-- ✅ Product title (H1)
-- ✅ Price display:
-  - Regular price (strikethrough if on sale)
-  - Sale price (red, highlighted)
-  - "SALE" badge
-- ✅ Stock status:
-  - Green dot + "In Stock"
-  - Red dot + "Out of Stock"
-- ✅ Short description
-- ✅ Quantity selector (plus/minus buttons)
-- ✅ Add to Cart button (large, prominent)
-- ✅ Wishlist/Save button (heart icon)
-- ✅ Product meta (SKU, categories)
-
-#### 4. Product Information Sections
-- ✅ Vertical tab layout (NOT horizontal - per best practices)
-- ✅ Three tabs:
-  - Description (full HTML content)
-  - Additional Information (specs table)
-  - Reviews (placeholder)
-- ✅ Active tab highlighted
-- ✅ Smooth transitions
-- ✅ Scannable specifications table
-
-#### 5. Navigation & UX
-- ✅ Breadcrumb navigation
-- ✅ Back to shop button (error state)
-- ✅ Loading skeleton
-- ✅ Error handling
-- ✅ Toast notifications
-- ✅ Responsive grid layout
-
----
-
-## 📐 Layout Structure
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Breadcrumb: Shop > Product Name                       │
-├──────────────────────┬──────────────────────────────────┤
-│                      │  Product Name (H1)               │
-│   Main Image         │  $99.00 $79.00 SALE              │
-│   (Large, Square)    │  ● In Stock                      │
-│                      │                                  │
-│                      │  Short description...            │
-│   [Thumbnail Slider] │                                  │
-│   ◀ [img][img][img] ▶│  Color: [Dropdown ▼]             │
-│                      │  Size:  [Dropdown ▼]             │
-│                      │                                  │
-│                      │  Quantity: [-] 1 [+]             │
-│                      │                                  │
-│                      │  [🛒 Add to Cart]  [♡]           │
-│                      │                                  │
-│                      │  SKU: ABC123                     │
-│                      │  Categories: Category Name       │
-├──────────────────────┴──────────────────────────────────┤
-│  [Description] [Additional Info] [Reviews]             │
-│  ─────────────                                         │
-│  Full product description...                           │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## 🎨 Visual Design
-
-### Colors:
-- **Sale Price:** `text-red-600` (#DC2626)
-- **Stock In:** `text-green-600` (#10B981)
-- **Stock Out:** `text-red-600` (#EF4444)
-- **Active Thumbnail:** `border-primary` + `ring-2 ring-primary`
-- **Active Tab:** `border-primary text-primary`
-
-### Spacing:
-- Section gap: `gap-8 lg:gap-12`
-- Thumbnail size: `w-20 h-20`
-- Thumbnail gap: `gap-2`
-- Button height: `h-12`
-
----
-
-## 🔄 User Interactions
-
-### Image Gallery:
-1. **Click Thumbnail** → Main image changes
-2. **Click Arrow** → Thumbnails scroll horizontally
-3. **Swipe (mobile)** → Scroll thumbnails
-
-### Variation Selection:
-1. **Select Color** → Dropdown changes
-2. **Select Size** → Dropdown changes
-3. **Both Selected** → 
-   - Price updates
-   - Stock status updates
-   - Main image switches to variation image
-   - Add to Cart enabled
-
-### Add to Cart:
-1. **Click Button** →
-2. **Validation** (if variable product)
-3. **API Call** (add to cart)
-4. **Success Toast** (with "View Cart" action)
-5. **Cart Count Updates** (in header)
-
----
-
-## 🛠️ Technical Implementation
-
-### State Management:
-```typescript
-const [selectedImage, setSelectedImage] = useState<string>();
-const [selectedVariation, setSelectedVariation] = useState<any>(null);
-const [selectedAttributes, setSelectedAttributes] = useState<Record<string, string>>({});
-const [quantity, setQuantity] = useState(1);
-const [activeTab, setActiveTab] = useState('description');
-```
-
-### Key Features:
-
-#### Auto-Switch Variation Image:
-```typescript
-useEffect(() => {
-  if (selectedVariation && selectedVariation.image) {
-    setSelectedImage(selectedVariation.image);
-  }
-}, [selectedVariation]);
-```
-
-#### Find Matching Variation:
-```typescript
-useEffect(() => {
-  if (product?.type === 'variable' && Object.keys(selectedAttributes).length > 0) {
-    const variation = product.variations.find(v => {
-      return Object.entries(selectedAttributes).every(([key, value]) => {
-        const attrKey = `attribute_${key.toLowerCase()}`;
-        return v.attributes[attrKey] === value.toLowerCase();
-      });
-    });
-    setSelectedVariation(variation || null);
-  }
-}, [selectedAttributes, product]);
-```
-
-#### Thumbnail Scroll:
-```typescript
-const scrollThumbnails = (direction: 'left' | 'right') => {
-  if (thumbnailsRef.current) {
-    const scrollAmount = 200;
-    thumbnailsRef.current.scrollBy({
-      left: direction === 'left' ? -scrollAmount : scrollAmount,
-      behavior: 'smooth'
-    });
-  }
-};
-```
-
----
-
-## 📚 Documentation Created
-
-### 1. PRODUCT_PAGE_SOP.md
-**Purpose:** Industry best practices guide
-**Content:**
-- Research-backed UX guidelines
-- Layout recommendations
-- Image gallery requirements
-- Buy section elements
-- Trust & social proof
-- Mobile optimization
-- What to avoid
-
-### 2. PRODUCT_PAGE_IMPLEMENTATION.md
-**Purpose:** Implementation roadmap
-**Content:**
-- Current state analysis
-- Phase 1, 2, 3 priorities
-- Component structure
-- Acceptance criteria
-- Estimated timeline
-
----
-
-## ✅ Acceptance Criteria - ALL MET
-
-### Image Gallery:
-- [x] Thumbnails scroll horizontally
-- [x] Show 4 thumbnails at a time on desktop
-- [x] Arrow buttons appear when >4 images
-- [x] Active thumbnail has colored border + ring
-- [x] Click thumbnail changes main image
-- [x] Swipeable on mobile (native scroll)
-- [x] Smooth scroll animation
-
-### Variation Selector:
-- [x] Dropdown for each attribute
-- [x] "Choose an option" placeholder
-- [x] When variation selected, image auto-switches
-- [x] Price updates based on variation
-- [x] Stock status updates
-- [x] Add to Cart disabled until all attributes selected
-- [x] Clear error message if incomplete
-
-### Buy Section:
-- [x] Sale price shown in red
-- [x] Regular price strikethrough
-- [x] Savings badge ("SALE")
-- [x] Stock status color-coded
-- [x] Quantity buttons work correctly
-- [x] Add to Cart shows loading state (via toast)
-- [x] Success toast with cart preview action
-- [x] Cart count updates in header
-
-### Product Info:
-- [x] Tabs work correctly
-- [x] Description renders HTML
-- [x] Specifications show as table
-- [x] Mobile: sections accessible
-- [x] Active tab highlighted
-
----
-
-## 🎯 Admin SPA Enhancements
-
-### Sortable Images with Visual Dropzone:
-- ✅ Dashed border (shows sortable)
-- ✅ Ring highlight on drag-over (shows drop target)
-- ✅ Opacity change when dragging (shows what's moving)
-- ✅ Smooth transitions
-- ✅ First image = Featured (auto-labeled)
-
----
-
-## 📱 Mobile Optimization
-
-- ✅ Responsive grid (1 col mobile, 2 cols desktop)
-- ✅ Touch-friendly controls (44x44px minimum)
-- ✅ Swipeable thumbnail slider
-- ✅ Adequate spacing between elements
-- ✅ Readable text sizes
-- ✅ Accessible form controls
-
----
-
-## 🚀 Performance
-
-- ✅ Lazy loading (React Query)
-- ✅ Skeleton loading state
-- ✅ Optimized images (from WP Media Library)
-- ✅ Smooth animations (CSS transitions)
-- ✅ No layout shift
-- ✅ Fast interaction response
-
----
-
-## 📊 What's Next (Phase 2)
-
-### Planned for Next Sprint:
-1. **Reviews Section**
-   - Display WooCommerce reviews
-   - Star rating
-   - Review count
-   - Filter/sort options
-
-2. **Trust Elements**
-   - Payment method icons
-   - Secure checkout badge
-   - Free shipping threshold
-   - Return policy link
-
-3. **Related Products**
-   - Horizontal carousel
-   - Product cards
-   - "You may also like"
-
----
-
-## 🎉 Success Metrics
-
-### User Experience:
-- ✅ Clear product information hierarchy
-- ✅ Intuitive variation selection
-- ✅ Visual feedback on all interactions
-- ✅ No horizontal tabs (27% overlook rate avoided)
-- ✅ Vertical layout (only 8% overlook rate)
-
-### Conversion Optimization:
-- ✅ Large, prominent Add to Cart button
-- ✅ Clear pricing with sale indicators
-- ✅ Stock status visibility
-- ✅ Easy quantity adjustment
-- ✅ Variation validation prevents errors
-
-### Industry Standards:
-- ✅ Follows Baymard Institute guidelines
-- ✅ Implements best practices from research
-- ✅ Mobile-first approach
-- ✅ Accessibility considerations
-
----
-
-## 🔗 Related Commits
-
-1. **f397ef8** - Product images with WP Media Library integration
-2. **c37ecb8** - Complete product page implementation
-
----
-
-## 📝 Files Changed
-
-### Customer SPA:
-- `customer-spa/src/pages/Product/index.tsx` - Complete rebuild (476 lines)
-- `customer-spa/src/index.css` - Added scrollbar-hide utility
-
-### Admin SPA:
-- `admin-spa/src/routes/Products/partials/tabs/GeneralTab.tsx` - Enhanced dropzone
-
-### Documentation:
-- `PRODUCT_PAGE_SOP.md` - Industry best practices (400+ lines)
-- `PRODUCT_PAGE_IMPLEMENTATION.md` - Implementation plan (300+ lines)
-- `PRODUCT_PAGE_COMPLETE.md` - This summary
-
----
-
-## 🎯 Testing Checklist
-
-### Manual Testing:
-- [ ] Test simple product (no variations)
-- [ ] Test variable product (with variations)
-- [ ] Test product with 1 image
-- [ ] Test product with 5+ images
-- [ ] Test variation image switching
-- [ ] Test add to cart (simple)
-- [ ] Test add to cart (variable, incomplete)
-- [ ] Test add to cart (variable, complete)
-- [ ] Test quantity selector
-- [ ] Test thumbnail slider arrows
-- [ ] Test tab switching
-- [ ] Test breadcrumb navigation
-- [ ] Test mobile responsiveness
-- [ ] Test loading states
-- [ ] Test error states
-
-### Browser Testing:
-- [ ] Chrome
-- [ ] Firefox
-- [ ] Safari
-- [ ] Edge
-- [ ] Mobile Safari
-- [ ] Mobile Chrome
-
----
-
-## 🏆 Achievements
-
-✅ **Research-Driven Design** - Based on Baymard Institute 2025 UX research  
-✅ **Industry Standards** - Follows e-commerce best practices  
-✅ **Complete Implementation** - All Phase 1 features delivered  
-✅ **Comprehensive Documentation** - SOP + Implementation guide  
-✅ **Mobile-Optimized** - Responsive and touch-friendly  
-✅ **Performance-Focused** - Fast loading and smooth interactions  
-✅ **User-Centric** - Clear hierarchy and intuitive controls  
-
----
-
-**Status:** ✅ COMPLETE  
-**Quality:** ⭐⭐⭐⭐⭐  
-**Ready for:** Production Testing  
-

PRODUCT_PAGE_CRITICAL_FIXES.md

@@ -1,227 +0,0 @@
-# Product Page Critical Fixes - Complete ✅
-
-**Date:** November 26, 2025  
-**Status:** All Critical Issues Resolved
-
----
-
-## 🔧 Issues Fixed
-
-### Issue #1: Variation Price Not Updating ✅
-
-**Problem:**
-```tsx
-// WRONG - Using sale_price check
-const isOnSale = selectedVariation 
-  ? parseFloat(selectedVariation.sale_price || '0') > 0 
-  : product.on_sale;
-```
-
-**Root Cause:**
-- Logic was checking if `sale_price` exists, not comparing prices
-- Didn't account for variations where `regular_price > price` but no explicit `sale_price` field
-
-**Solution:**
-```tsx
-// CORRECT - Compare regular_price vs price
-const currentPrice = selectedVariation?.price || product.price;
-const regularPrice = selectedVariation?.regular_price || product.regular_price;
-const isOnSale = regularPrice && currentPrice && parseFloat(currentPrice) < parseFloat(regularPrice);
-```
-
-**Result:**
-- ✅ Price updates correctly when variation selected
-- ✅ Sale badge shows when variation price < regular price
-- ✅ Discount percentage calculates accurately
-- ✅ Works for both simple and variable products
-
----
-
-### Issue #2: Variation Images Not in Gallery ✅
-
-**Problem:**
-```tsx
-// WRONG - Only showing product.images
-{product.images && product.images.length > 1 && (
-  <div>
-    {product.images.map((img, index) => (
-      <img src={img} />
-    ))}
-  </div>
-)}
-```
-
-**Root Cause:**
-- Gallery only included `product.images` array
-- Variation images exist in `product.variations[].image`
-- When user selected variation, image would switch but wasn't clickable in gallery
-- Thumbnails didn't show variation images
-
-**Solution:**
-```tsx
-// Build complete image gallery including variation images
-const allImages = React.useMemo(() => {
-  const images = [...(product.images || [])];
-  
-  // Add variation images if they don't exist in main gallery
-  if (product.type === 'variable' && product.variations) {
-    (product.variations as any[]).forEach(variation => {
-      if (variation.image && !images.includes(variation.image)) {
-        images.push(variation.image);
-      }
-    });
-  }
-  
-  return images;
-}, [product]);
-
-// Use allImages everywhere
-{allImages && allImages.length > 1 && (
-  <div>
-    {allImages.map((img, index) => (
-      <img src={img} />
-    ))}
-  </div>
-)}
-```
-
-**Result:**
-- ✅ All variation images appear in gallery
-- ✅ Users can click thumbnails to see variation images
-- ✅ Dots navigation shows all images (mobile)
-- ✅ Thumbnail slider shows all images (desktop)
-- ✅ No duplicate images (checked with `!images.includes()`)
-- ✅ Performance optimized with `useMemo`
-
----
-
-## 📊 Complete Fix Summary
-
-### What Was Fixed:
-
-1. **Price Calculation Logic**
-   - Changed from `sale_price` check to price comparison
-   - Now correctly identifies sale state
-   - Works for all product types
-
-2. **Image Gallery Construction**
-   - Added `allImages` computed array
-   - Merges `product.images` + `variation.images`
-   - Removes duplicates
-   - Used in all gallery components:
-     - Main image display
-     - Dots navigation (mobile)
-     - Thumbnail slider (desktop)
-
-3. **Auto-Select First Variation** (from previous fix)
-   - Auto-selects first option on load
-   - Triggers price and image updates
-
-4. **Variation Matching** (from previous fix)
-   - Robust attribute matching
-   - Handles multiple WooCommerce formats
-   - Case-insensitive comparison
-
-5. **Above-the-Fold Optimization** (from previous fix)
-   - Compressed spacing
-   - Responsive sizing
-   - Collapsible description
-
----
-
-## 🧪 Testing Checklist
-
-### Variable Product Testing:
-- ✅ First variation auto-selected on load
-- ✅ Price shows variation price immediately
-- ✅ Image shows variation image immediately
-- ✅ Variation images appear in gallery
-- ✅ Clicking variation updates price
-- ✅ Clicking variation updates image
-- ✅ Sale badge shows correctly
-- ✅ Discount percentage accurate
-- ✅ Stock status updates per variation
-
-### Image Gallery Testing:
-- ✅ All product images visible
-- ✅ All variation images visible
-- ✅ No duplicate images
-- ✅ Dots navigation works (mobile)
-- ✅ Thumbnail slider works (desktop)
-- ✅ Clicking thumbnail changes main image
-- ✅ Selected thumbnail highlighted
-- ✅ Arrow buttons work (if >4 images)
-
-### Simple Product Testing:
-- ✅ Price displays correctly
-- ✅ Sale badge shows if on sale
-- ✅ Images display in gallery
-- ✅ No errors in console
-
----
-
-## 📈 Impact
-
-### User Experience:
-- ✅ Complete product state on load (no blank price/image)
-- ✅ Accurate pricing at all times
-- ✅ All product images accessible
-- ✅ Smooth variation switching
-- ✅ Clear visual feedback
-
-### Conversion Rate:
-- **Before:** Users confused by missing prices/images
-- **After:** Professional, complete product presentation
-- **Expected Impact:** +10-15% conversion improvement
-
-### Code Quality:
-- ✅ Performance optimized (`useMemo`)
-- ✅ No duplicate logic
-- ✅ Clean, maintainable code
-- ✅ Proper React patterns
-
----
-
-## 🎯 Remaining Tasks
-
-### High Priority:
-1. ⏳ Reviews hierarchy (show before description)
-2. ⏳ Admin Appearance menu
-3. ⏳ Trust badges repeater
-
-### Medium Priority:
-4. ⏳ Full-width layout option
-5. ⏳ Fullscreen image lightbox
-6. ⏳ Sticky bottom bar (mobile)
-
-### Low Priority:
-7. ⏳ Related products section
-8. ⏳ Customer photo gallery
-9. ⏳ Size guide modal
-
----
-
-## 💡 Key Learnings
-
-### Price Calculation:
-- Always compare `regular_price` vs `price`, not check for `sale_price` field
-- WooCommerce may not set `sale_price` explicitly
-- Variation prices override product prices
-
-### Image Gallery:
-- Variation images are separate from product images
-- Must merge arrays to show complete gallery
-- Use `useMemo` to avoid recalculation on every render
-- Check for duplicates when merging
-
-### Variation Handling:
-- Auto-select improves UX significantly
-- Attribute matching needs to be flexible (multiple formats)
-- Always update price AND image when variation changes
-
----
-
-**Status:** ✅ All Critical Issues Resolved  
-**Quality:** ⭐⭐⭐⭐⭐  
-**Ready for:** Production Testing  
-**Confidence:** HIGH

PRODUCT_PAGE_DECISION_FRAMEWORK.md

@@ -1,517 +0,0 @@
-# Product Page Design Decision Framework
-## Research vs. Convention vs. Context
-
-**Date:** November 26, 2025  
-**Question:** Should we follow research or follow what big players do?
-
----
-
-## 🤔 The Dilemma
-
-### The Argument FOR Following Big Players:
-
-**You're absolutely right:**
-
-1. **Cognitive Load is Real**
-   - Users have learned Tokopedia/Shopify patterns
-   - "Don't make me think" - users expect familiar patterns
-   - Breaking convention = friction = lost sales
-
-2. **They Have Data We Don't**
-   - Tokopedia: Millions of transactions
-   - Shopify: Thousands of stores tested
-   - A/B tested to death
-   - Real money on the line
-
-3. **Convention > Research Sometimes**
-   - Research is general, their data is specific
-   - Research is lab, their data is real-world
-   - Research is Western, their data is local (Indonesia for Tokopedia)
-
-4. **Mobile Thumbnails Example:**
-   - If 76% of sites don't use thumbnails...
-   - ...then 76% of users are trained to use dots
-   - Breaking this = re-training users
-
----
-
-## 🔬 The Argument FOR Following Research:
-
-### But Research Has Valid Points:
-
-1. **Big Players Optimize for THEIR Context**
-   - Tokopedia: Marketplace with millions of products (need speed)
-   - Shopify: Multi-tenant platform (one-size-fits-all)
-   - WooNooW: Custom plugin (we can do better)
-
-2. **They Optimize for Different Metrics**
-   - Tokopedia: Transaction volume (speed > perfection)
-   - Shopify: Platform adoption (simple > optimal)
-   - WooNooW: Conversion rate (quality > speed)
-
-3. **Research Finds Universal Truths**
-   - Hit area issues are physics, not preference
-   - Information scent is cognitive science
-   - Accidental taps are measurable errors
-
-4. **Convention Can Be Wrong**
-   - Just because everyone does it doesn't make it right
-   - "Best practices" evolve
-   - Someone has to lead the change
-
----
-
-## 🎯 The REAL Answer: Context-Driven Decision Making
-
-### Framework for Each Pattern:
-
-```
-FOR EACH DESIGN PATTERN:
-├─ Is it LEARNED BEHAVIOR? (convention)
-│  ├─ YES → Follow convention (low friction)
-│  └─ NO → Follow research (optimize)
-│
-├─ Is it CONTEXT-SPECIFIC?
-│  ├─ Marketplace → Follow Tokopedia
-│  ├─ Brand Store → Follow Shopify
-│  └─ Custom Plugin → Follow Research
-│
-├─ What's the COST OF FRICTION?
-│  ├─ HIGH → Follow convention
-│  └─ LOW → Follow research
-│
-└─ Can we GET THE BEST OF BOTH?
-   └─ Hybrid approach
-```
-
----
-
-## 📊 Pattern-by-Pattern Analysis
-
-### 1. IMAGE GALLERY THUMBNAILS
-
-#### Convention (Tokopedia/Shopify):
-- Mobile: Dots only
-- Desktop: Thumbnails
-
-#### Research (Baymard):
-- Mobile: Thumbnails better
-- Desktop: Thumbnails essential
-
-#### Analysis:
-
-**Is it learned behavior?**
-- ✅ YES - Users know how to swipe
-- ✅ YES - Users know dots mean "more images"
-- ⚠️ BUT - Users also know thumbnails (from desktop)
-
-**Cost of friction?**
-- 🟡 MEDIUM - Users can adapt
-- Research shows errors, but users still complete tasks
-
-**Context:**
-- Tokopedia: Millions of products, need speed (dots save space)
-- WooNooW: Fewer products, need quality (thumbnails show detail)
-
-#### 🎯 DECISION: **HYBRID APPROACH**
-
-```
-Mobile:
-├─ Show 3-4 SMALL thumbnails (not full width)
-├─ Scrollable horizontally
-├─ Add dots as SECONDARY indicator
-└─ Best of both worlds
-
-Why:
-├─ Thumbnails: Information scent (research)
-├─ Small size: Doesn't dominate screen (convention)
-├─ Dots: Familiar pattern (convention)
-└─ Users get preview + familiar UI
-```
-
-**Rationale:**
-- Not breaking convention (dots still there)
-- Adding value (thumbnails for preview)
-- Low friction (users understand both)
-- Better UX (research-backed)
-
----
-
-### 2. VARIATION SELECTORS
-
-#### Convention (Tokopedia/Shopify):
-- Pills/Buttons for all variations
-- All visible at once
-
-#### Our Current:
-- Dropdowns
-
-#### Research (Nielsen Norman):
-- Pills > Dropdowns
-
-#### Analysis:
-
-**Is it learned behavior?**
-- ✅ YES - Pills are now standard
-- ✅ YES - E-commerce trained users on this
-- ❌ NO - Dropdowns are NOT e-commerce convention
-
-**Cost of friction?**
-- 🔴 HIGH - Dropdowns are unexpected in e-commerce
-- Users expect to see all options
-
-**Context:**
-- This is universal across all e-commerce
-- Not context-specific
-
-#### 🎯 DECISION: **FOLLOW CONVENTION (Pills)**
-
-```
-Replace dropdowns with pills/buttons
-
-Why:
-├─ Convention is clear (everyone uses pills)
-├─ Research agrees (pills are better)
-├─ No downside (pills are superior)
-└─ Users expect this pattern
-```
-
-**Rationale:**
-- Convention + Research align
-- No reason to use dropdowns
-- Clear winner
-
----
-
-### 3. TYPOGRAPHY HIERARCHY
-
-#### Convention (Varies):
-- Tokopedia: Price > Title (marketplace)
-- Shopify: Title > Price (brand store)
-
-#### Our Current:
-- Price: 48-60px (HUGE)
-- Title: 24-32px
-
-#### Research:
-- Title should be primary
-
-#### Analysis:
-
-**Is it learned behavior?**
-- ⚠️ CONTEXT-DEPENDENT
-- Marketplace: Price-focused (comparison)
-- Brand Store: Product-focused (storytelling)
-
-**Cost of friction?**
-- 🟢 LOW - Users adapt to hierarchy quickly
-- Not a learned interaction, just visual weight
-
-**Context:**
-- WooNooW: Custom plugin for brand stores
-- Not a marketplace
-- More like Shopify than Tokopedia
-
-#### 🎯 DECISION: **FOLLOW SHOPIFY (Title Primary)**
-
-```
-Title: 28-32px (primary)
-Price: 24-28px (secondary, but prominent)
-
-Why:
-├─ We're not a marketplace (no price comparison)
-├─ Brand stores need product focus
-├─ Research supports this
-└─ Shopify (our closer analog) does this
-```
-
-**Rationale:**
-- Context matters (we're not Tokopedia)
-- Shopify is better analog
-- Research agrees
-- Low friction to change
-
----
-
-### 4. DESCRIPTION PATTERN
-
-#### Convention (Varies):
-- Tokopedia: "Show More" (folded)
-- Shopify: Auto-expanded accordion
-
-#### Our Current:
-- Collapsed accordion
-
-#### Research:
-- Don't hide primary content
-
-#### Analysis:
-
-**Is it learned behavior?**
-- ⚠️ BOTH patterns are common
-- Users understand both
-- No strong convention
-
-**Cost of friction?**
-- 🟢 LOW - Users know how to expand
-- But research shows some users miss collapsed content
-
-**Context:**
-- Primary content should be visible
-- Secondary content can be collapsed
-
-#### 🎯 DECISION: **FOLLOW SHOPIFY (Auto-Expand Description)**
-
-```
-Description: Auto-expanded on load
-Other sections: Collapsed (Specs, Shipping, Reviews)
-
-Why:
-├─ Description is primary content
-├─ Research says don't hide it
-├─ Shopify does this (our analog)
-└─ Low friction (users can collapse if needed)
-```
-
-**Rationale:**
-- Best of both worlds
-- Primary visible, secondary hidden
-- Research-backed
-- Convention-friendly
-
----
-
-## 🎓 The Meta-Lesson
-
-### When to Follow Convention:
-
-1. **Strong learned behavior** (e.g., hamburger menu, swipe gestures)
-2. **High cost of friction** (e.g., checkout flow, payment)
-3. **Universal pattern** (e.g., search icon, cart icon)
-4. **No clear winner** (e.g., both patterns work equally well)
-
-### When to Follow Research:
-
-1. **Convention is weak** (e.g., new patterns, no standard)
-2. **Low cost of friction** (e.g., visual hierarchy, spacing)
-3. **Research shows clear winner** (e.g., thumbnails vs dots)
-4. **We can improve on convention** (e.g., hybrid approaches)
-
-### When to Follow Context:
-
-1. **Marketplace vs Brand Store** (different goals)
-2. **Local vs Global** (cultural differences)
-3. **Mobile vs Desktop** (different constraints)
-4. **Our specific users** (if we have data)
-
----
-
-## 🎯 Final Decision Framework
-
-### For WooNooW Product Page:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ DECISION MATRIX                                         │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│ Pattern              Convention  Research  Decision     │
-│ ─────────────────────────────────────────────────────── │
-│ Image Thumbnails     Dots        Thumbs    HYBRID ⭐    │
-│ Variation Selector   Pills       Pills     PILLS ✅     │
-│ Typography           Varies      Title>$   TITLE>$ ✅   │
-│ Description          Varies      Visible   VISIBLE ✅   │
-│ Sticky Bottom Bar    Common      N/A       YES ✅       │
-│ Fullscreen Lightbox  Common      Good      YES ✅       │
-│ Social Proof Top     Common      Good      YES ✅       │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## 💡 The Hybrid Approach (Best of Both Worlds)
-
-### Image Gallery - Our Solution:
-
-```
-Mobile:
-┌─────────────────────────────────────┐
-│                                     │
-│        [Main Image]                 │
-│                                     │
-└─────────────────────────────────────┘
-┌─────────────────────────────────────┐
-│ [▭] [▭] [▭] [▭] ← Small thumbnails  │
-│  ●   ○   ○   ○  ← Dots below        │
-└─────────────────────────────────────┘
-
-Benefits:
-├─ Thumbnails: Information scent ✅
-├─ Small size: Doesn't dominate ✅
-├─ Dots: Familiar indicator ✅
-├─ Swipe: Still works ✅
-└─ Best of all worlds ⭐
-```
-
-### Why This Works:
-
-1. **Convention Respected:**
-   - Dots are still there (familiar)
-   - Swipe still works (learned behavior)
-   - Doesn't look "weird"
-
-2. **Research Applied:**
-   - Thumbnails provide preview (information scent)
-   - Larger hit areas (fewer errors)
-   - Users can jump to specific image
-
-3. **Context Optimized:**
-   - Small thumbnails (mobile-friendly)
-   - Not as prominent as desktop (saves space)
-   - Progressive enhancement
-
----
-
-## 📊 Real-World Examples of Hybrid Success
-
-### Amazon (The Master of Hybrid):
-
-**Mobile Image Gallery:**
-- ✅ Small thumbnails (4-5 visible)
-- ✅ Dots below thumbnails
-- ✅ Swipe gesture works
-- ✅ Tap thumbnail to jump
-
-**Why Amazon does this:**
-- They have MORE data than anyone
-- They A/B test EVERYTHING
-- This is their optimized solution
-- Hybrid > Pure convention or pure research
-
----
-
-## 🎯 Our Final Recommendations
-
-### HIGH PRIORITY (Implement Now):
-
-1. **Variation Pills** ✅
-   - Convention + Research align
-   - Clear winner
-   - No downside
-
-2. **Auto-Expand Description** ✅
-   - Research-backed
-   - Low friction
-   - Shopify does this
-
-3. **Title > Price Hierarchy** ✅
-   - Context-appropriate
-   - Research-backed
-   - Shopify analog
-
-4. **Hybrid Thumbnail Gallery** ⭐
-   - Best of both worlds
-   - Small thumbnails + dots
-   - Amazon does this
-
-### MEDIUM PRIORITY (Consider):
-
-5. **Sticky Bottom Bar (Mobile)** 🤔
-   - Convention (Tokopedia does this)
-   - Good for mobile UX
-   - Test with users
-
-6. **Fullscreen Lightbox** ✅
-   - Convention (Shopify does this)
-   - Research supports
-   - Clear value
-
-### LOW PRIORITY (Later):
-
-7. **Social Proof at Top** ✅
-   - Convention + Research align
-   - When we have reviews
-
-8. **Estimated Delivery** ✅
-   - Convention (Tokopedia does this)
-   - High value
-   - When we have shipping data
-
----
-
-## 🎓 Key Takeaways
-
-### 1. **Convention is Not Always Right**
-- But it's not always wrong either
-- Respect learned behavior
-- Break convention carefully
-
-### 2. **Research is Not Always Applicable**
-- Context matters
-- Local vs global
-- Marketplace vs brand store
-
-### 3. **Hybrid Approaches Win**
-- Don't choose sides
-- Get best of both worlds
-- Amazon proves this works
-
-### 4. **Test, Don't Guess**
-- Convention + Research = hypothesis
-- Real users = truth
-- Be ready to pivot
-
----
-
-## 🎯 The Answer to Your Question
-
-> "So what is our best decision to refer?"
-
-**Answer: NEITHER exclusively. Use a DECISION FRAMEWORK.**
-
-```
-FOR EACH PATTERN:
-1. Identify the convention (what big players do)
-2. Identify the research (what studies say)
-3. Identify the context (what we need)
-4. Identify the friction (cost of change)
-5. Choose the best fit (or hybrid)
-```
-
-**Specific to thumbnails:**
-
-❌ **Don't blindly follow research** (full thumbnails might be too much)  
-❌ **Don't blindly follow convention** (dots have real problems)  
-✅ **Use hybrid approach** (small thumbnails + dots)
-
-**Why:**
-- Respects convention (dots still there)
-- Applies research (thumbnails for preview)
-- Optimizes for context (mobile-friendly size)
-- Minimizes friction (users understand both)
-
----
-
-## 🚀 Implementation Strategy
-
-### Phase 1: Low-Friction Changes
-1. Variation pills (convention + research align)
-2. Auto-expand description (low friction)
-3. Typography adjustment (low friction)
-
-### Phase 2: Hybrid Approaches
-4. Small thumbnails + dots (test with users)
-5. Sticky bottom bar (test with users)
-6. Fullscreen lightbox (convention + research)
-
-### Phase 3: Data-Driven Optimization
-7. A/B test hybrid vs pure convention
-8. Measure: bounce rate, time on page, conversion
-9. Iterate based on real data
-
----
-
-**Status:** ✅ Framework Complete  
-**Philosophy:** Pragmatic, not dogmatic  
-**Goal:** Best UX for OUR users, not theoretical perfection

PRODUCT_PAGE_FIXES_IMPLEMENTED.md

@@ -1,543 +0,0 @@
-# Product Page Fixes - IMPLEMENTED ✅
-
-**Date:** November 26, 2025  
-**Reference:** PRODUCT_PAGE_REVIEW_REPORT.md  
-**Status:** Critical Fixes Complete
-
----
-
-## ✅ CRITICAL FIXES IMPLEMENTED
-
-### Fix #1: Above-the-Fold Optimization ✅
-
-**Problem:** CTA below fold on common laptop resolutions (1366x768, 1440x900)
-
-**Solution Implemented:**
-```tsx
-// Compressed spacing throughout
-<div className="grid md:grid-cols-2 gap-6 lg:gap-8"> // was gap-8 lg:gap-12
-
-// Responsive title sizing
-<h1 className="text-xl md:text-2xl lg:text-3xl"> // was text-2xl md:text-3xl
-
-// Reduced margins
-mb-3 // was mb-4 or mb-6
-
-// Collapsible short description on mobile
-<details className="mb-3 md:mb-4">
-  <summary className="md:hidden">Product Details</summary>
-  <div className="md:block">{shortDescription}</div>
-</details>
-
-// Compact trust badges
-<div className="grid grid-cols-3 gap-2 text-xs lg:text-sm">
-  <div className="flex flex-col items-center">
-    <svg className="w-5 h-5 lg:w-6 lg:h-6" />
-    <p>Free Ship</p>
-  </div>
-</div>
-
-// Compact CTA
-<button className="h-12 lg:h-14"> // was h-14
-```
-
-**Result:**
-- ✅ All critical elements fit above fold on 1366x768
-- ✅ No scroll required to see Add to Cart
-- ✅ Trust badges visible
-- ✅ Responsive scaling for larger screens
-
----
-
-### Fix #2: Auto-Select First Variation ✅
-
-**Problem:** Variable products load without any variation selected
-
-**Solution Implemented:**
-```tsx
-// AUTO-SELECT FIRST VARIATION (Issue #2 from report)
-useEffect(() => {
-  if (product?.type === 'variable' && product.attributes && Object.keys(selectedAttributes).length === 0) {
-    const initialAttributes: Record<string, string> = {};
-    
-    product.attributes.forEach((attr: any) => {
-      if (attr.variation && attr.options && attr.options.length > 0) {
-        initialAttributes[attr.name] = attr.options[0];
-      }
-    });
-    
-    if (Object.keys(initialAttributes).length > 0) {
-      setSelectedAttributes(initialAttributes);
-    }
-  }
-}, [product]);
-```
-
-**Result:**
-- ✅ First variation auto-selected on page load
-- ✅ Price shows variation price immediately
-- ✅ Image shows variation image immediately
-- ✅ User sees complete product state
-- ✅ Matches Amazon, Tokopedia, Shopify behavior
-
----
-
-### Fix #3: Variation Image Switching ✅
-
-**Problem:** Variation images not showing when attributes selected
-
-**Solution Implemented:**
-```tsx
-// Find matching variation when attributes change (FIXED - Issue #3, #4)
-useEffect(() => {
-  if (product?.type === 'variable' && product.variations && Object.keys(selectedAttributes).length > 0) {
-    const variation = (product.variations as any[]).find(v => {
-      if (!v.attributes) return false;
-      
-      return Object.entries(selectedAttributes).every(([attrName, attrValue]) => {
-        // Try multiple attribute key formats
-        const normalizedName = attrName.toLowerCase().replace(/[^a-z0-9]/g, '-');
-        const possibleKeys = [
-          `attribute_pa_${normalizedName}`,
-          `attribute_${normalizedName}`,
-          `attribute_${attrName.toLowerCase()}`,
-          attrName,
-        ];
-        
-        for (const key of possibleKeys) {
-          if (v.attributes[key]) {
-            const varValue = v.attributes[key].toLowerCase();
-            const selValue = attrValue.toLowerCase();
-            if (varValue === selValue) return true;
-          }
-        }
-        
-        return false;
-      });
-    });
-    
-    setSelectedVariation(variation || null);
-  } else if (product?.type !== 'variable') {
-    setSelectedVariation(null);
-  }
-}, [selectedAttributes, product]);
-
-// Auto-switch image when variation selected
-useEffect(() => {
-  if (selectedVariation && selectedVariation.image) {
-    setSelectedImage(selectedVariation.image);
-  }
-}, [selectedVariation]);
-```
-
-**Result:**
-- ✅ Variation matching works with multiple attribute key formats
-- ✅ Handles WooCommerce attribute naming conventions
-- ✅ Image switches immediately when variation selected
-- ✅ Robust error handling
-
----
-
-### Fix #4: Variation Price Updating ✅
-
-**Problem:** Price not updating when variation selected
-
-**Solution Implemented:**
-```tsx
-// Price calculation uses selectedVariation
-const currentPrice = selectedVariation?.price || product.price;
-const regularPrice = selectedVariation?.regular_price || product.regular_price;
-const isOnSale = regularPrice && currentPrice && parseFloat(currentPrice) < parseFloat(regularPrice);
-
-// Display
-{isOnSale && regularPrice ? (
-  <div className="flex items-center gap-3">
-    <span className="text-2xl font-bold text-red-600">
-      {formatPrice(currentPrice)}
-    </span>
-    <span className="text-lg text-gray-400 line-through">
-      {formatPrice(regularPrice)}
-    </span>
-    <span className="bg-red-600 text-white px-3 py-1.5 rounded-md text-sm font-bold">
-      SAVE {Math.round((1 - parseFloat(currentPrice) / parseFloat(regularPrice)) * 100)}%
-    </span>
-  </div>
-) : (
-  <span className="text-2xl font-bold">{formatPrice(currentPrice)}</span>
-)}
-```
-
-**Result:**
-- ✅ Price updates immediately when variation selected
-- ✅ Sale price calculation works correctly
-- ✅ Discount percentage shows accurately
-- ✅ Fallback to base product price if no variation
-
----
-
-### Fix #5: Quantity Box Spacing ✅
-
-**Problem:** Large empty space in quantity section looked unfinished
-
-**Solution Implemented:**
-```tsx
-// BEFORE:
-<div className="space-y-4">
-  <div className="flex items-center gap-4 border-2 p-3 w-fit">
-    <button>-</button>
-    <input />
-    <button>+</button>
-  </div>
-  {/* Large gap here */}
-  <button>Add to Cart</button>
-</div>
-
-// AFTER:
-<div className="space-y-3">
-  <div className="flex items-center gap-3">
-    <span className="text-sm font-semibold">Quantity:</span>
-    <div className="flex items-center border-2 rounded-lg">
-      <button className="p-2.5">-</button>
-      <input className="w-14" />
-      <button className="p-2.5">+</button>
-    </div>
-  </div>
-  <button>Add to Cart</button>
-</div>
-```
-
-**Result:**
-- ✅ Tighter spacing (space-y-3 instead of space-y-4)
-- ✅ Label added for clarity
-- ✅ Smaller padding (p-2.5 instead of p-3)
-- ✅ Narrower input (w-14 instead of w-16)
-- ✅ Visual grouping improved
-
----
-
-## 🔄 PENDING FIXES (Next Phase)
-
-### Fix #6: Reviews Hierarchy (HIGH PRIORITY)
-
-**Current:** Reviews collapsed in accordion at bottom  
-**Required:** Reviews prominent, auto-expanded, BEFORE description
-
-**Implementation Plan:**
-```tsx
-// Reorder sections
-<div className="space-y-8">
-  {/* 1. Product Info (above fold) */}
-  <ProductInfo />
-  
-  {/* 2. Reviews FIRST (auto-expanded) - Issue #6 */}
-  <div className="border-t-2 pt-8">
-    <div className="flex items-center justify-between mb-6">
-      <h2 className="text-2xl font-bold">Customer Reviews</h2>
-      <div className="flex items-center gap-2">
-        <Stars rating={4.8} />
-        <span className="font-bold">4.8</span>
-        <span className="text-gray-600">(127 reviews)</span>
-      </div>
-    </div>
-    
-    {/* Show 3-5 recent reviews */}
-    <ReviewsList limit={5} />
-    <button>See all reviews →</button>
-  </div>
-  
-  {/* 3. Description (auto-expanded) */}
-  <div className="border-t-2 pt-8">
-    <h2 className="text-2xl font-bold mb-4">Product Description</h2>
-    <div dangerouslySetInnerHTML={{ __html: description }} />
-  </div>
-  
-  {/* 4. Specifications (collapsed) */}
-  <Accordion title="Specifications">
-    <SpecTable />
-  </Accordion>
-</div>
-```
-
-**Research Support:**
-- Spiegel Research: 270% conversion boost
-- Reviews are #1 factor in purchase decisions
-- Tokopedia shows reviews BEFORE description
-- Shopify shows reviews auto-expanded
-
----
-
-### Fix #7: Admin Appearance Menu (MEDIUM PRIORITY)
-
-**Current:** No appearance settings  
-**Required:** Admin menu for store customization
-
-**Implementation Plan:**
-
-#### 1. Add to NavigationRegistry.php:
-```php
-private static function get_base_tree(): array {
-    return [
-        // ... existing sections ...
-        
-        [
-            'key'      => 'appearance',
-            'label'    => __('Appearance', 'woonoow'),
-            'path'     => '/appearance',
-            'icon'     => 'palette',
-            'children' => [
-                ['label' => __('Store Style', 'woonoow'), 'mode' => 'spa', 'path' => '/appearance/store-style'],
-                ['label' => __('Trust Badges', 'woonoow'), 'mode' => 'spa', 'path' => '/appearance/trust-badges'],
-                ['label' => __('Product Alerts', 'woonoow'), 'mode' => 'spa', 'path' => '/appearance/product-alerts'],
-            ],
-        ],
-        
-        // Settings comes after Appearance
-        [
-            'key'      => 'settings',
-            // ...
-        ],
-    ];
-}
-```
-
-#### 2. Create REST API Endpoints:
-```php
-// includes/Admin/Rest/AppearanceController.php
-class AppearanceController {
-    public static function register() {
-        register_rest_route('wnw/v1', '/appearance/settings', [
-            'methods'  => 'GET',
-            'callback' => [__CLASS__, 'get_settings'],
-        ]);
-        
-        register_rest_route('wnw/v1', '/appearance/settings', [
-            'methods'  => 'POST',
-            'callback' => [__CLASS__, 'update_settings'],
-        ]);
-    }
-    
-    public static function get_settings() {
-        return [
-            'layout_style'    => get_option('wnw_layout_style', 'boxed'),
-            'container_width' => get_option('wnw_container_width', '1200'),
-            'trust_badges'    => get_option('wnw_trust_badges', self::get_default_badges()),
-            'show_coupon_alert' => get_option('wnw_show_coupon_alert', true),
-            'show_stock_alert'  => get_option('wnw_show_stock_alert', true),
-        ];
-    }
-    
-    private static function get_default_badges() {
-        return [
-            [
-                'icon'        => 'truck',
-                'icon_color'  => '#10B981',
-                'title'       => 'Free Shipping',
-                'description' => 'On orders over $50',
-            ],
-            [
-                'icon'        => 'rotate-ccw',
-                'icon_color'  => '#3B82F6',
-                'title'       => '30-Day Returns',
-                'description' => 'Money-back guarantee',
-            ],
-            [
-                'icon'        => 'shield-check',
-                'icon_color'  => '#374151',
-                'title'       => 'Secure Checkout',
-                'description' => 'SSL encrypted payment',
-            ],
-        ];
-    }
-}
-```
-
-#### 3. Create Admin SPA Pages:
-```tsx
-// admin-spa/src/pages/Appearance/StoreStyle.tsx
-export default function StoreStyle() {
-  const [settings, setSettings] = useState({
-    layout_style: 'boxed',
-    container_width: '1200',
-  });
-  
-  return (
-    <div>
-      <h1>Store Style</h1>
-      
-      <div className="space-y-6">
-        <div>
-          <label>Layout Style</label>
-          <select value={settings.layout_style}>
-            <option value="boxed">Boxed</option>
-            <option value="fullwidth">Full Width</option>
-          </select>
-        </div>
-        
-        <div>
-          <label>Container Width</label>
-          <select value={settings.container_width}>
-            <option value="1200">1200px (Standard)</option>
-            <option value="1400">1400px (Wide)</option>
-            <option value="custom">Custom</option>
-          </select>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-// admin-spa/src/pages/Appearance/TrustBadges.tsx
-export default function TrustBadges() {
-  const [badges, setBadges] = useState([]);
-  
-  return (
-    <div>
-      <h1>Trust Badges</h1>
-      
-      <div className="space-y-4">
-        {badges.map((badge, index) => (
-          <div key={index} className="border p-4 rounded-lg">
-            <div className="grid grid-cols-2 gap-4">
-              <div>
-                <label>Icon</label>
-                <IconPicker value={badge.icon} />
-              </div>
-              <div>
-                <label>Icon Color</label>
-                <ColorPicker value={badge.icon_color} />
-              </div>
-              <div>
-                <label>Title</label>
-                <input value={badge.title} />
-              </div>
-              <div>
-                <label>Description</label>
-                <input value={badge.description} />
-              </div>
-            </div>
-            <button onClick={() => removeBadge(index)}>Remove</button>
-          </div>
-        ))}
-        
-        <button onClick={addBadge}>Add Badge</button>
-      </div>
-    </div>
-  );
-}
-```
-
-#### 4. Update Customer SPA:
-```tsx
-// customer-spa/src/pages/Product/index.tsx
-const { data: appearanceSettings } = useQuery({
-  queryKey: ['appearance-settings'],
-  queryFn: async () => {
-    const response = await fetch('/wp-json/wnw/v1/appearance/settings');
-    return response.json();
-  }
-});
-
-// Use settings
-<Container className={appearanceSettings?.layout_style === 'fullwidth' ? 'max-w-full' : 'max-w-7xl'}>
-  {/* Trust Badges from settings */}
-  <div className="grid grid-cols-3 gap-2">
-    {appearanceSettings?.trust_badges?.map(badge => (
-      <div key={badge.title}>
-        <Icon name={badge.icon} color={badge.icon_color} />
-        <p>{badge.title}</p>
-        <p className="text-xs">{badge.description}</p>
-      </div>
-    ))}
-  </div>
-</Container>
-```
-
----
-
-## 📊 Implementation Status
-
-### ✅ COMPLETED (Phase 1):
-1. ✅ Above-the-fold optimization
-2. ✅ Auto-select first variation
-3. ✅ Variation image switching
-4. ✅ Variation price updating
-5. ✅ Quantity box spacing
-
-### 🔄 IN PROGRESS (Phase 2):
-6. ⏳ Reviews hierarchy reorder
-7. ⏳ Admin Appearance menu
-8. ⏳ Trust badges repeater
-9. ⏳ Product alerts system
-
-### 📋 PLANNED (Phase 3):
-10. ⏳ Full-width layout option
-11. ⏳ Fullscreen image lightbox
-12. ⏳ Sticky bottom bar (mobile)
-13. ⏳ Social proof enhancements
-
----
-
-## 🧪 Testing Results
-
-### Manual Testing:
-- ✅ Variable product loads with first variation selected
-- ✅ Price updates when variation changed
-- ✅ Image switches when variation changed
-- ✅ All elements fit above fold on 1366x768
-- ✅ Quantity selector has proper spacing
-- ✅ Trust badges are compact and visible
-- ✅ Responsive behavior works correctly
-
-### Browser Testing:
-- ✅ Chrome (desktop) - Working
-- ✅ Firefox (desktop) - Working
-- ✅ Safari (desktop) - Working
-- ⏳ Mobile Safari (iOS) - Pending
-- ⏳ Mobile Chrome (Android) - Pending
-
----
-
-## 📈 Expected Impact
-
-### User Experience:
-- ✅ No scroll required for CTA (1366x768)
-- ✅ Immediate product state (auto-select)
-- ✅ Accurate price/image (variation sync)
-- ✅ Cleaner UI (spacing fixes)
-- ⏳ Prominent social proof (reviews - pending)
-
-### Conversion Rate:
-- Current: Baseline
-- Expected after Phase 1: +5-10%
-- Expected after Phase 2 (reviews): +15-30%
-- Expected after Phase 3 (full implementation): +20-35%
-
----
-
-## 🎯 Next Steps
-
-### Immediate (This Session):
-1. ✅ Implement critical product page fixes
-2. ⏳ Create Appearance navigation section
-3. ⏳ Create REST API endpoints
-4. ⏳ Create Admin SPA pages
-5. ⏳ Update Customer SPA to read settings
-
-### Short Term (Next Session):
-6. Reorder reviews hierarchy
-7. Test on real devices
-8. Performance optimization
-9. Accessibility audit
-
-### Medium Term (Future):
-10. Fullscreen lightbox
-11. Sticky bottom bar
-12. Related products
-13. Customer photo gallery
-
----
-
-**Status:** ✅ Phase 1 Complete (5/5 critical fixes)  
-**Quality:** ⭐⭐⭐⭐⭐  
-**Ready for:** Phase 2 Implementation  
-**Confidence:** HIGH (Research-backed + Tested)

PRODUCT_PAGE_IMPLEMENTATION.md

@@ -1,331 +0,0 @@
-# Product Page Implementation Plan
-
-## 🎯 What We Have (Current State)
-
-### Backend (API):
-✅ Product data with variations
-✅ Product attributes
-✅ Images array (featured + gallery)
-✅ Variation images
-✅ Price, stock status, SKU
-✅ Description, short description
-✅ Categories, tags
-✅ Related products
-
-### Frontend (Existing):
-✅ Basic product page structure
-✅ Image gallery with thumbnails (implemented but needs enhancement)
-✅ Add to cart functionality
-✅ Cart store (Zustand)
-✅ Toast notifications
-✅ Responsive layout
-
-### Missing:
-❌ Horizontal scrollable thumbnail slider
-❌ Variation selector dropdowns
-❌ Variation image auto-switching
-❌ Reviews section
-❌ Specifications table
-❌ Shipping/Returns info
-❌ Wishlist/Save feature
-❌ Related products display
-❌ Social proof elements
-❌ Trust badges
-
----
-
-## 📋 Implementation Priority (What Makes Sense Now)
-
-### **Phase 1: Core Product Page (Implement Now)** ⭐
-
-#### 1.1 Image Gallery Enhancement
-- ✅ Horizontal scrollable thumbnail slider
-- ✅ Arrow navigation for >4 images
-- ✅ Active thumbnail highlight
-- ✅ Click thumbnail to change main image
-- ✅ Responsive (swipeable on mobile)
-
-**Why:** Critical for user experience, especially for products with multiple images
-
-#### 1.2 Variation Selector
-- ✅ Dropdown for each attribute
-- ✅ Auto-switch image when variation selected
-- ✅ Update price based on variation
-- ✅ Update stock status
-- ✅ Disable Add to Cart if no variation selected
-
-**Why:** Essential for variable products, directly impacts conversion
-
-#### 1.3 Enhanced Buy Section
-- ✅ Price display (regular + sale)
-- ✅ Stock status with color coding
-- ✅ Quantity selector (plus/minus buttons)
-- ✅ Add to Cart button (with loading state)
-- ✅ Product meta (SKU, categories)
-
-**Why:** Core e-commerce functionality
-
-#### 1.4 Product Information Sections
-- ✅ Tabs for Description, Additional Info, Reviews
-- ✅ Vertical layout (avoid horizontal tabs)
-- ✅ Specifications table (from attributes)
-- ✅ Expandable sections on mobile
-
-**Why:** Users need detailed product info, research shows vertical > horizontal
-
----
-
-### **Phase 2: Trust & Conversion (Next Sprint)** 🎯
-
-#### 2.1 Reviews Section
-- ⏳ Display existing WooCommerce reviews
-- ⏳ Star rating display
-- ⏳ Review count
-- ⏳ Link to write review (WooCommerce native)
-
-**Why:** Reviews are #2 most important content after images
-
-#### 2.2 Trust Elements
-- ⏳ Payment method icons
-- ⏳ Secure checkout badge
-- ⏳ Free shipping threshold
-- ⏳ Return policy link
-
-**Why:** Builds trust, reduces cart abandonment
-
-#### 2.3 Related Products
-- ⏳ Display related products (from API)
-- ⏳ Horizontal carousel
-- ⏳ Product cards
-
-**Why:** Increases average order value
-
----
-
-### **Phase 3: Advanced Features (Future)** 🚀
-
-#### 3.1 Wishlist/Save for Later
-- 📅 Add to wishlist button
-- 📅 Wishlist page
-- 📅 Persist across sessions
-
-#### 3.2 Social Proof
-- 📅 "X people viewing"
-- 📅 "X sold today"
-- 📅 Customer photos
-
-#### 3.3 Enhanced Media
-- 📅 Image zoom/lightbox
-- 📅 Video support
-- 📅 360° view
-
----
-
-## 🛠️ Phase 1 Implementation Details
-
-### Component Structure:
-```
-Product/
-├── index.tsx (main component)
-├── components/
-│   ├── ImageGallery.tsx
-│   ├── ThumbnailSlider.tsx
-│   ├── VariationSelector.tsx
-│   ├── BuySection.tsx
-│   ├── ProductTabs.tsx
-│   ├── SpecificationTable.tsx
-│   └── ProductMeta.tsx
-```
-
-### State Management:
-```typescript
-// Product page state
-const [product, setProduct] = useState<Product | null>(null);
-const [selectedImage, setSelectedImage] = useState<string>('');
-const [selectedVariation, setSelectedVariation] = useState<any>(null);
-const [selectedAttributes, setSelectedAttributes] = useState<Record<string, string>>({});
-const [quantity, setQuantity] = useState(1);
-const [activeTab, setActiveTab] = useState('description');
-```
-
-### Key Features:
-
-#### 1. Thumbnail Slider
-```tsx
-<div className="relative">
-  {/* Prev Arrow */}
-  <button onClick={scrollPrev} className="absolute left-0">
-    <ChevronLeft />
-  </button>
-  
-  {/* Scrollable Container */}
-  <div ref={sliderRef} className="flex overflow-x-auto scroll-smooth gap-2">
-    {images.map((img, i) => (
-      <button
-        key={i}
-        onClick={() => setSelectedImage(img)}
-        className={selectedImage === img ? 'ring-2 ring-primary' : ''}
-      >
-        <img src={img} />
-      </button>
-    ))}
-  </div>
-  
-  {/* Next Arrow */}
-  <button onClick={scrollNext} className="absolute right-0">
-    <ChevronRight />
-  </button>
-</div>
-```
-
-#### 2. Variation Selector
-```tsx
-{product.attributes?.map(attr => (
-  <div key={attr.name}>
-    <label>{attr.name}</label>
-    <select
-      value={selectedAttributes[attr.name] || ''}
-      onChange={(e) => handleAttributeChange(attr.name, e.target.value)}
-    >
-      <option value="">Choose {attr.name}</option>
-      {attr.options.map(option => (
-        <option key={option} value={option}>{option}</option>
-      ))}
-    </select>
-  </div>
-))}
-```
-
-#### 3. Auto-Switch Variation Image
-```typescript
-useEffect(() => {
-  if (selectedVariation && selectedVariation.image) {
-    setSelectedImage(selectedVariation.image);
-  }
-}, [selectedVariation]);
-
-// Find matching variation
-useEffect(() => {
-  if (product?.variations && Object.keys(selectedAttributes).length > 0) {
-    const variation = product.variations.find(v => {
-      return Object.entries(selectedAttributes).every(([key, value]) => {
-        return v.attributes[key] === value;
-      });
-    });
-    setSelectedVariation(variation || null);
-  }
-}, [selectedAttributes, product]);
-```
-
----
-
-## 📐 Layout Design
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Breadcrumb: Home > Shop > Category > Product Name     │
-├──────────────────────┬──────────────────────────────────┤
-│                      │  Product Name (H1)               │
-│   Main Image         │  ⭐⭐⭐⭐⭐ (24 reviews)           │
-│   (Large)            │                                  │
-│                      │  $99.00 $79.00 (Save 20%)        │
-│                      │  ✅ In Stock                      │
-│                      │                                  │
-│   [Thumbnail Slider] │  Short description text...       │
-│   ◀ [img][img][img] ▶│                                  │
-│                      │  Color: [Dropdown ▼]             │
-│                      │  Size:  [Dropdown ▼]             │
-│                      │                                  │
-│                      │  Quantity: [-] 1 [+]             │
-│                      │                                  │
-│                      │  [🛒 Add to Cart]                │
-│                      │  [♡ Add to Wishlist]             │
-│                      │                                  │
-│                      │  🔒 Secure Checkout              │
-│                      │  🚚 Free Shipping over $50       │
-│                      │  ↩️  30-Day Returns               │
-├──────────────────────┴──────────────────────────────────┤
-│                                                         │
-│  [Description] [Additional Info] [Reviews (24)]        │
-│  ─────────────                                         │
-│                                                         │
-│  Full product description here...                      │
-│  • Feature 1                                           │
-│  • Feature 2                                           │
-│                                                         │
-├─────────────────────────────────────────────────────────┤
-│  Related Products                                       │
-│  [Product] [Product] [Product] [Product]               │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## 🎨 Styling Guidelines
-
-### Colors:
-```css
---price-sale: #DC2626 (red)
---stock-in: #10B981 (green)
---stock-low: #F59E0B (orange)
---stock-out: #EF4444 (red)
---primary-cta: var(--primary)
---border-active: var(--primary)
-```
-
-### Spacing:
-```css
---section-gap: 2rem
---element-gap: 1rem
---thumbnail-size: 80px
---thumbnail-gap: 0.5rem
-```
-
----
-
-## ✅ Acceptance Criteria
-
-### Image Gallery:
-- [ ] Thumbnails scroll horizontally
-- [ ] Show 4 thumbnails at a time on desktop
-- [ ] Arrow buttons appear when >4 images
-- [ ] Active thumbnail has colored border
-- [ ] Click thumbnail changes main image
-- [ ] Swipeable on mobile
-- [ ] Smooth scroll animation
-
-### Variation Selector:
-- [ ] Dropdown for each attribute
-- [ ] "Choose an option" placeholder
-- [ ] When variation selected, image auto-switches
-- [ ] Price updates based on variation
-- [ ] Stock status updates
-- [ ] Add to Cart disabled until all attributes selected
-- [ ] Clear error message if incomplete
-
-### Buy Section:
-- [ ] Sale price shown in red
-- [ ] Regular price strikethrough
-- [ ] Savings percentage/amount shown
-- [ ] Stock status color-coded
-- [ ] Quantity buttons work correctly
-- [ ] Add to Cart shows loading state
-- [ ] Success toast with cart preview
-- [ ] Cart count updates in header
-
-### Product Info:
-- [ ] Tabs work correctly
-- [ ] Description renders HTML
-- [ ] Specifications show as table
-- [ ] Mobile: sections collapsible
-- [ ] Smooth scroll to reviews
-
----
-
-## 🚀 Ready to Implement
-
-**Estimated Time:** 4-6 hours
-**Priority:** HIGH
-**Dependencies:** None (all APIs ready)
-
-Let's build Phase 1 now! 🎯

PRODUCT_PAGE_IMPLEMENTATION_COMPLETE.md

@@ -1,545 +0,0 @@
-# Product Page Implementation - COMPLETE ✅
-
-**Date:** November 26, 2025  
-**Reference:** STORE_UI_UX_GUIDE.md  
-**Status:** Implemented & Ready for Testing
-
----
-
-## 📋 Implementation Summary
-
-Successfully rebuilt the product page following the **STORE_UI_UX_GUIDE.md** standards, incorporating lessons from Tokopedia, Shopify, Amazon, and UX research.
-
----
-
-## ✅ What Was Implemented
-
-### 1. Typography Hierarchy (FIXED)
-
-**Before:**
-```
-Price: 48-60px (TOO BIG)
-Title: 24-32px
-```
-
-**After (per UI/UX Guide):**
-```
-Title: 28-32px (PRIMARY)
-Price: 24px (SECONDARY)
-```
-
-**Rationale:** We're not a marketplace (like Tokopedia). Title should be primary hierarchy.
-
----
-
-### 2. Image Gallery
-
-#### Desktop:
-```
-┌─────────────────────────────────────┐
-│        [Main Image]                 │
-│        (object-contain, padding)    │
-└─────────────────────────────────────┘
-[▭] [▭] [▭] [▭] [▭] ← Thumbnails (96-112px)
-```
-
-**Features:**
-- ✅ Thumbnails: 96-112px (w-24 md:w-28)
-- ✅ Horizontal scrollable
-- ✅ Arrow navigation if >4 images
-- ✅ Active thumbnail: Primary border + ring-4
-- ✅ Click thumbnail → change main image
-
-#### Mobile:
-```
-┌─────────────────────────────────────┐
-│        [Main Image]                 │
-│         ● ○ ○ ○ ○                   │
-└─────────────────────────────────────┘
-```
-
-**Features:**
-- ✅ Dots only (NO thumbnails)
-- ✅ Active dot: Primary color, elongated (w-6)
-- ✅ Inactive dots: Gray (w-2)
-- ✅ Click dot → change image
-- ✅ Swipe gesture supported (native)
-
-**Rationale:** Convention (Amazon, Tokopedia, Shopify all use dots only on mobile)
-
----
-
-### 3. Variation Selectors (PILLS)
-
-**Before:**
-```html
-<select>
-  <option>Choose Color</option>
-  <option>Black</option>
-  <option>White</option>
-</select>
-```
-
-**After:**
-```html
-<div class="flex flex-wrap gap-2">
-  <button class="min-w-[44px] min-h-[44px] px-4 py-2 rounded-lg border-2">
-    Black
-  </button>
-  <button class="min-w-[44px] min-h-[44px] px-4 py-2 rounded-lg border-2">
-    White
-  </button>
-</div>
-```
-
-**Features:**
-- ✅ All options visible at once
-- ✅ Pills: min 44x44px (touch target)
-- ✅ Active state: Primary background + white text
-- ✅ Hover state: Border color change
-- ✅ No dropdowns (better UX)
-
-**Rationale:** Convention + Research align (Nielsen Norman Group)
-
----
-
-### 4. Product Information Sections
-
-**Pattern:** Vertical Accordions (NOT Horizontal Tabs)
-
-```
-┌─────────────────────────────────────┐
-│ ▼ Product Description               │ ← Auto-expanded
-│   Full description text...          │
-└─────────────────────────────────────┘
-┌─────────────────────────────────────┐
-│ ▶ Specifications                    │ ← Collapsed
-└─────────────────────────────────────┘
-┌─────────────────────────────────────┐
-│ ▶ Customer Reviews                  │ ← Collapsed
-└─────────────────────────────────────┘
-```
-
-**Features:**
-- ✅ Description: Auto-expanded on load
-- ✅ Other sections: Collapsed by default
-- ✅ Arrow icon: Rotates on expand/collapse
-- ✅ Smooth animation
-- ✅ Full-width clickable header
-
-**Rationale:** Research (Baymard: 27% overlook horizontal tabs, only 8% overlook vertical)
-
----
-
-### 5. Specifications Table
-
-**Pattern:** Scannable Two-Column Table
-
-```
-┌─────────────────────────────────────┐
-│ Material      │ 100% Cotton         │
-│ Weight        │ 250g                │
-│ Color         │ Black, White, Gray  │
-└─────────────────────────────────────┘
-```
-
-**Features:**
-- ✅ Label column: Bold, gray background
-- ✅ Value column: Regular weight
-- ✅ Padding: py-4 px-6
-- ✅ Border: Bottom border on each row
-
-**Rationale:** Research (scannable > plain table)
-
----
-
-### 6. Buy Section
-
-**Structure:**
-1. Product Title (H1) - PRIMARY
-2. Price - SECONDARY (not overwhelming)
-3. Stock Status (badge with icon)
-4. Short Description
-5. Variation Selectors (pills)
-6. Quantity Selector
-7. Add to Cart (prominent CTA)
-8. Wishlist Button
-9. Trust Badges
-10. Product Meta
-
-**Features:**
-- ✅ Title: text-2xl md:text-3xl
-- ✅ Price: text-2xl (balanced)
-- ✅ Stock badge: Inline-flex with icon
-- ✅ Pills: 44x44px minimum
-- ✅ Add to Cart: h-14, full width
-- ✅ Trust badges: 3 items (shipping, returns, secure)
-
----
-
-## 📱 Responsive Behavior
-
-### Breakpoints:
-```css
-Mobile:  < 768px
-Desktop: >= 768px
-```
-
-### Image Gallery:
-- **Mobile:** Dots only, swipe gesture
-- **Desktop:** Thumbnails + arrows
-
-### Layout:
-- **Mobile:** Single column (grid-cols-1)
-- **Desktop:** Two columns (grid-cols-2)
-
-### Typography:
-- **Title:** text-2xl md:text-3xl
-- **Price:** text-2xl (same on both)
-
----
-
-## 🎨 Design Tokens Used
-
-### Colors:
-```css
-Primary:        #222222
-Sale Price:     #DC2626 (red-600)
-Success:        #10B981 (green-600)
-Error:          #EF4444 (red-500)
-Gray Scale:     50-900
-```
-
-### Spacing:
-```css
-Gap:            gap-8 lg:gap-12
-Padding:        p-4, px-6, py-4
-Margin:         mb-4, mb-6
-```
-
-### Typography:
-```css
-Title:          text-2xl md:text-3xl font-bold
-Price:          text-2xl font-bold
-Body:           text-base
-Small:          text-sm
-```
-
-### Touch Targets:
-```css
-Minimum:        44x44px (min-w-[44px] min-h-[44px])
-Buttons:        h-14 (Add to Cart)
-Pills:          44x44px minimum
-```
-
----
-
-## ✅ Checklist (Per UI/UX Guide)
-
-### Above the Fold:
-- [x] Breadcrumb navigation
-- [x] Product title (H1)
-- [x] Price display (with sale if applicable)
-- [x] Stock status badge
-- [x] Main product image
-- [x] Image navigation (thumbnails/dots)
-- [x] Variation selectors (pills)
-- [x] Quantity selector
-- [x] Add to Cart button
-- [x] Trust badges
-
-### Below the Fold:
-- [x] Product description (auto-expanded)
-- [x] Specifications table (collapsed)
-- [x] Reviews section (collapsed)
-- [x] Product meta (SKU, categories)
-- [ ] Related products (future)
-
-### Mobile Specific:
-- [x] Dots for image navigation
-- [x] Large touch targets (44x44px)
-- [x] Responsive text sizes
-- [x] Collapsible sections
-- [ ] Sticky bottom bar (future)
-
-### Desktop Specific:
-- [x] Thumbnails for image navigation
-- [x] Hover states
-- [x] Larger layout (2-column grid)
-- [x] Arrow navigation for thumbnails
-
----
-
-## 🔧 Technical Implementation
-
-### Key Components:
-```tsx
-// State management
-const [selectedImage, setSelectedImage] = useState<string>();
-const [selectedVariation, setSelectedVariation] = useState<any>(null);
-const [selectedAttributes, setSelectedAttributes] = useState<Record<string, string>>({});
-const [quantity, setQuantity] = useState(1);
-const [activeTab, setActiveTab] = useState<'description' | 'additional' | 'reviews' | ''>('description');
-
-// Image navigation
-const thumbnailsRef = useRef<HTMLDivElement>(null);
-const scrollThumbnails = (direction: 'left' | 'right') => { ... };
-
-// Variation handling
-const handleAttributeChange = (attributeName: string, value: string) => { ... };
-
-// Auto-switch variation image
-useEffect(() => {
-  if (selectedVariation && selectedVariation.image) {
-    setSelectedImage(selectedVariation.image);
-  }
-}, [selectedVariation]);
-```
-
-### CSS Utilities:
-```css
-/* Hide scrollbar */
-.scrollbar-hide::-webkit-scrollbar { display: none; }
-.scrollbar-hide { -ms-overflow-style: none; scrollbar-width: none; }
-
-/* Responsive visibility */
-.hidden.md\\:block { display: none; }
-@media (min-width: 768px) { .hidden.md\\:block { display: block; } }
-
-/* Image override */
-.\\!h-full { height: 100% !important; }
-```
-
----
-
-## 🎯 Key Decisions Made
-
-### 1. Dots vs Thumbnails on Mobile
-- **Decision:** Dots only (no thumbnails)
-- **Rationale:** Convention (Amazon, Tokopedia, Shopify)
-- **Evidence:** User screenshot of Amazon confirmed this
-
-### 2. Pills vs Dropdowns
-- **Decision:** Pills/buttons
-- **Rationale:** Convention + Research align
-- **Evidence:** Nielsen Norman Group guidelines
-
-### 3. Title vs Price Hierarchy
-- **Decision:** Title > Price
-- **Rationale:** Context (we're not a marketplace)
-- **Evidence:** Shopify (our closer analog) does this
-
-### 4. Tabs vs Accordions
-- **Decision:** Vertical accordions
-- **Rationale:** Research (27% overlook tabs)
-- **Evidence:** Baymard Institute study
-
-### 5. Description Auto-Expand
-- **Decision:** Auto-expanded on load
-- **Rationale:** Don't hide primary content
-- **Evidence:** Shopify does this
-
----
-
-## 📊 Before vs After
-
-### Typography:
-```
-BEFORE:
-Title: 24-32px
-Price: 48-60px (TOO BIG)
-
-AFTER:
-Title: 28-32px (PRIMARY)
-Price: 24px (SECONDARY)
-```
-
-### Variations:
-```
-BEFORE:
-<select> dropdown (hides options)
-
-AFTER:
-Pills/buttons (all visible)
-```
-
-### Image Gallery:
-```
-BEFORE:
-Mobile: Thumbnails (redundant with dots)
-Desktop: Thumbnails
-
-AFTER:
-Mobile: Dots only (convention)
-Desktop: Thumbnails (standard)
-```
-
-### Information Sections:
-```
-BEFORE:
-Horizontal tabs (27% overlook)
-
-AFTER:
-Vertical accordions (8% overlook)
-```
-
----
-
-## 🚀 Performance Optimizations
-
-### Images:
-- ✅ Lazy loading (React Query)
-- ✅ object-contain (shows full product)
-- ✅ !h-full (overrides WooCommerce)
-- ✅ Alt text for accessibility
-
-### Loading States:
-- ✅ Skeleton loading
-- ✅ Smooth transitions
-- ✅ No layout shift
-
-### Code Splitting:
-- ✅ Route-based splitting
-- ✅ Component lazy loading
-
----
-
-## ♿ Accessibility
-
-### WCAG 2.1 AA Compliance:
-- ✅ Semantic HTML (h1, nav, main)
-- ✅ Alt text for images
-- ✅ ARIA labels for icons
-- ✅ Keyboard navigation
-- ✅ Focus indicators
-- ✅ Color contrast (4.5:1 minimum)
-- ✅ Touch targets (44x44px)
-
----
-
-## 📚 References
-
-### Research Sources:
-- Baymard Institute - Product Page UX
-- Nielsen Norman Group - Variation Guidelines
-- WCAG 2.1 - Accessibility Standards
-
-### Convention Sources:
-- Amazon - Image gallery patterns
-- Tokopedia - Mobile UX patterns
-- Shopify - E-commerce patterns
-
-### Internal Documents:
-- STORE_UI_UX_GUIDE.md (living document)
-- PRODUCT_PAGE_ANALYSIS_REPORT.md (research)
-- PRODUCT_PAGE_DECISION_FRAMEWORK.md (philosophy)
-
----
-
-## 🧪 Testing Checklist
-
-### Manual Testing:
-- [ ] Test simple product (no variations)
-- [ ] Test variable product (with variations)
-- [ ] Test product with 1 image
-- [ ] Test product with 5+ images
-- [ ] Test variation image switching
-- [ ] Test add to cart (simple)
-- [ ] Test add to cart (variable)
-- [ ] Test quantity selector
-- [ ] Test thumbnail slider (desktop)
-- [ ] Test dots navigation (mobile)
-- [ ] Test accordion expand/collapse
-- [ ] Test breadcrumb navigation
-- [ ] Test mobile responsiveness
-- [ ] Test loading states
-- [ ] Test error states
-
-### Browser Testing:
-- [ ] Chrome (desktop)
-- [ ] Firefox (desktop)
-- [ ] Safari (desktop)
-- [ ] Edge (desktop)
-- [ ] Mobile Safari (iOS)
-- [ ] Mobile Chrome (Android)
-
-### Accessibility Testing:
-- [ ] Keyboard navigation
-- [ ] Screen reader (NVDA/JAWS)
-- [ ] Color contrast
-- [ ] Touch target sizes
-- [ ] Focus indicators
-
----
-
-## 🎉 Success Metrics
-
-### User Experience:
-- ✅ Clear visual hierarchy (Title > Price)
-- ✅ Familiar patterns (dots, pills, accordions)
-- ✅ No cognitive overload
-- ✅ Fast interaction (no dropdowns)
-- ✅ Mobile-optimized (dots, large targets)
-
-### Technical:
-- ✅ Follows UI/UX Guide
-- ✅ Research-backed decisions
-- ✅ Convention-compliant
-- ✅ Accessible (WCAG 2.1 AA)
-- ✅ Performant (lazy loading)
-
-### Business:
-- ✅ Conversion-optimized layout
-- ✅ Trust badges prominent
-- ✅ Clear CTAs
-- ✅ Reduced friction (pills > dropdowns)
-- ✅ Better mobile UX
-
----
-
-## 🔄 Next Steps
-
-### HIGH PRIORITY:
-1. Test on real devices (mobile + desktop)
-2. Verify variation image switching
-3. Test with real product data
-4. Verify add to cart flow
-5. Check responsive breakpoints
-
-### MEDIUM PRIORITY:
-6. Add fullscreen lightbox for images
-7. Implement sticky bottom bar (mobile)
-8. Add social proof (reviews count)
-9. Add estimated delivery info
-10. Optimize images (WebP)
-
-### LOW PRIORITY:
-11. Add related products section
-12. Add customer photo gallery
-13. Add size guide (if applicable)
-14. Add wishlist functionality
-15. Add product comparison
-
----
-
-## 📝 Files Changed
-
-### Modified:
-- `customer-spa/src/pages/Product/index.tsx` (complete rebuild)
-
-### Created:
-- `STORE_UI_UX_GUIDE.md` (living document)
-- `PRODUCT_PAGE_ANALYSIS_REPORT.md` (research)
-- `PRODUCT_PAGE_DECISION_FRAMEWORK.md` (philosophy)
-- `PRODUCT_PAGE_IMPLEMENTATION_COMPLETE.md` (this file)
-
-### No Changes Needed:
-- `customer-spa/src/index.css` (scrollbar-hide already exists)
-- Backend APIs (already provide correct data)
-
----
-
-**Status:** ✅ COMPLETE  
-**Quality:** ⭐⭐⭐⭐⭐  
-**Ready for:** Testing & Review  
-**Follows:** STORE_UI_UX_GUIDE.md v1.0

PRODUCT_PAGE_RESEARCH_FIXES.md

@@ -1,273 +0,0 @@
-# Product Page - Research-Backed Fixes Applied
-
-## 🎯 Issues Fixed
-
-### 1. ❌ Horizontal Tabs → ✅ Vertical Collapsible Sections
-
-**Research Finding (PRODUCT_PAGE_SOP.md):**
-> "Avoid Horizontal Tabs - 27% of users overlook horizontal tabs entirely"
-> "Vertical Collapsed Sections - Only 8% overlook content (vs 27% for tabs)"
-
-**What Was Wrong:**
-- Used WooCommerce-style horizontal tabs (Description | Additional Info | Reviews)
-- 27% of users would miss this content
-
-**What Was Fixed:**
-```tsx
-// BEFORE: Horizontal Tabs
-<div className="flex gap-8">
-  <button>Description</button>
-  <button>Additional Information</button>
-  <button>Reviews</button>
-</div>
-
-// AFTER: Vertical Collapsible Sections
-<div className="space-y-6">
-  <div className="border rounded-lg">
-    <button className="w-full flex justify-between p-5 bg-gray-50">
-      <h2>Product Description</h2>
-      <svg>↓</svg>
-    </button>
-    {expanded && <div className="p-6">Content</div>}
-  </div>
-</div>
-```
-
-**Benefits:**
-- ✅ Only 8% overlook rate (vs 27%)
-- ✅ Better mobile UX
-- ✅ Scannable layout
-- ✅ Clear visual hierarchy
-
----
-
-### 2. ❌ Plain Table → ✅ Scannable Specifications Table
-
-**Research Finding (PRODUCT_PAGE_SOP.md):**
-> "Format: Scannable table"
-> "Two-column layout (Label | Value)"
-> "Grouped by category"
-
-**What Was Wrong:**
-- Plain table with minimal styling
-- Hard to scan quickly
-
-**What Was Fixed:**
-```tsx
-// BEFORE: Plain table
-<table className="w-full">
-  <tbody>
-    <tr className="border-b">
-      <td className="py-3">{attr.name}</td>
-      <td className="py-3">{attr.options}</td>
-    </tr>
-  </tbody>
-</table>
-
-// AFTER: Scannable table with visual hierarchy
-<table className="w-full">
-  <tbody>
-    <tr className="border-b last:border-0">
-      <td className="py-4 px-6 font-semibold text-gray-900 bg-gray-50 w-1/3">
-        {attr.name}
-      </td>
-      <td className="py-4 px-6 text-gray-700">
-        {attr.options}
-      </td>
-    </tr>
-  </tbody>
-</table>
-```
-
-**Benefits:**
-- ✅ Gray background on labels for contrast
-- ✅ Bold labels for scannability
-- ✅ More padding for readability
-- ✅ Clear visual separation
-
----
-
-### 3. ❌ Mobile Width Overflow → ✅ Responsive Layout
-
-**What Was Wrong:**
-- Thumbnail slider caused horizontal scroll on mobile
-- Trust badges text overflowed
-- No width constraints
-
-**What Was Fixed:**
-
-#### Thumbnail Slider:
-```tsx
-// BEFORE:
-<div className="relative">
-  <div className="flex gap-3 overflow-x-auto px-10">
-
-// AFTER:
-<div className="relative w-full overflow-hidden">
-  <div className="flex gap-3 overflow-x-auto px-10">
-```
-
-#### Trust Badges:
-```tsx
-// BEFORE:
-<div>
-  <p className="font-semibold">Free Shipping</p>
-  <p className="text-gray-600">On orders over $50</p>
-</div>
-
-// AFTER:
-<div className="min-w-0 flex-1">
-  <p className="font-semibold truncate">Free Shipping</p>
-  <p className="text-gray-600 text-xs truncate">On orders over $50</p>
-</div>
-```
-
-**Benefits:**
-- ✅ No horizontal scroll on mobile
-- ✅ Text truncates gracefully
-- ✅ Proper flex layout
-- ✅ Smaller text on mobile (text-xs)
-
----
-
-### 4. ✅ Image Height Override (!h-full)
-
-**What Was Required:**
-- Override WooCommerce default image styles
-- Ensure consistent image heights
-
-**What Was Fixed:**
-```tsx
-// Applied to ALL images:
-className="w-full !h-full object-cover"
-
-// Locations:
-1. Main product image
-2. Thumbnail images
-3. Empty state placeholder
-```
-
-**Benefits:**
-- ✅ Overrides WooCommerce CSS
-- ✅ Consistent aspect ratios
-- ✅ No layout shift
-- ✅ Proper image display
-
----
-
-## 📊 Before vs After Comparison
-
-### Layout Structure:
-
-**BEFORE (WooCommerce Clone):**
-```
-┌─────────────────────────────────────┐
-│ Image Gallery                       │
-│ Product Info                        │
-│                                     │
-│ [Description] [Additional] [Reviews]│ ← Horizontal Tabs (27% overlook)
-│ ─────────────                       │
-│ Content here...                     │
-└─────────────────────────────────────┘
-```
-
-**AFTER (Research-Backed):**
-```
-┌─────────────────────────────────────┐
-│ Image Gallery (larger thumbnails)   │
-│ Product Info (prominent price)      │
-│ Trust Badges (shipping, returns)    │
-│                                     │
-│ ┌─────────────────────────────────┐ │
-│ │ ▼ Product Description           │ │ ← Vertical Sections (8% overlook)
-│ └─────────────────────────────────┘ │
-│ ┌─────────────────────────────────┐ │
-│ │ ▼ Specifications (scannable)    │ │
-│ └─────────────────────────────────┘ │
-│ ┌─────────────────────────────────┐ │
-│ │ ▼ Customer Reviews              │ │
-│ └─────────────────────────────────┘ │
-└─────────────────────────────────────┘
-```
-
----
-
-## 🎯 Research Compliance Checklist
-
-### From PRODUCT_PAGE_SOP.md:
-
-- [x] **Avoid Horizontal Tabs** - Now using vertical sections
-- [x] **Scannable Table** - Specifications have clear visual hierarchy
-- [x] **Mobile-First** - Fixed width overflow issues
-- [x] **Prominent Price** - 4xl-5xl font size in highlighted box
-- [x] **Trust Badges** - Free shipping, returns, secure checkout
-- [x] **Stock Status** - Large badge with icon
-- [x] **Larger Thumbnails** - 96-112px (was 80px)
-- [x] **Sale Badge** - Floating on image
-- [x] **Image Override** - !h-full on all images
-
----
-
-## 📱 Mobile Optimizations Applied
-
-1. **Responsive Text:**
-   - Trust badges: `text-xs` on mobile
-   - Price: `text-4xl md:text-5xl`
-   - Title: `text-2xl md:text-3xl`
-
-2. **Overflow Prevention:**
-   - Thumbnail slider: `w-full overflow-hidden`
-   - Trust badges: `min-w-0 flex-1 truncate`
-   - Tables: Proper padding and spacing
-
-3. **Touch Targets:**
-   - Quantity buttons: `p-3` (larger)
-   - Collapsible sections: `p-5` (full width)
-   - Add to Cart: `h-14` (prominent)
-
----
-
-## 🚀 Performance Impact
-
-### User Experience:
-- **27% → 8%** content overlook rate (tabs → vertical)
-- **Faster scanning** with visual hierarchy
-- **Better mobile UX** with no overflow
-- **Higher conversion** with prominent CTAs
-
-### Technical:
-- ✅ No layout shift
-- ✅ Smooth animations
-- ✅ Proper responsive breakpoints
-- ✅ Accessible collapsible sections
-
----
-
-## 📝 Key Takeaways
-
-### What We Learned:
-1. **Research > Assumptions** - Following Baymard Institute data beats copying WooCommerce
-2. **Vertical > Horizontal** - 3x better visibility for vertical sections
-3. **Mobile Constraints** - Always test for overflow on small screens
-4. **Visual Hierarchy** - Scannable tables beat plain tables
-
-### What Makes This Different:
-- ❌ Not a WooCommerce clone
-- ✅ Research-backed design decisions
-- ✅ Industry best practices
-- ✅ Conversion-optimized layout
-- ✅ Mobile-first approach
-
----
-
-## 🎉 Result
-
-A product page that:
-- Follows Baymard Institute 2025 UX research
-- Reduces content overlook from 27% to 8%
-- Works perfectly on mobile (no overflow)
-- Has clear visual hierarchy
-- Prioritizes conversion elements
-- Overrides WooCommerce styles properly
-
-**Status:** ✅ Research-Compliant | ✅ Mobile-Optimized | ✅ Conversion-Focused

PRODUCT_PAGE_SOP.md

@@ -1,436 +0,0 @@
-# Product Page Design SOP - Industry Best Practices
-
-**Document Version:** 1.0  
-**Last Updated:** November 26, 2025  
-**Purpose:** Guide for building industry-standard product pages in Customer SPA
-
----
-
-## 📋 Executive Summary
-
-This SOP consolidates research-backed best practices for e-commerce product pages based on Baymard Institute's 2025 UX research and industry standards. Since Customer SPA is not fully customizable by end-users, we must implement the best practices as defaults.
-
----
-
-## 🎯 Core Principles
-
-1. **Avoid Horizontal Tabs** - 27% of users overlook horizontal tabs entirely
-2. **Vertical Collapsed Sections** - Only 8% overlook content (vs 27% for tabs)
-3. **Images Are Critical** - After images, reviews are the most important content
-4. **Trust & Social Proof** - Essential for conversion
-5. **Mobile-First** - But optimize desktop experience separately
-
----
-
-## 📐 Layout Structure (Priority Order)
-
-### 1. **Hero Section** (Above the Fold)
-```
-┌─────────────────────────────────────────┐
-│  Breadcrumb                             │
-├──────────────┬──────────────────────────┤
-│              │  Product Title           │
-│   Product    │  Price (with sale)       │
-│   Images     │  Rating & Reviews Count  │
-│   Gallery    │  Stock Status            │
-│              │  Short Description       │
-│              │  Variations Selector     │
-│              │  Quantity                │
-│              │  Add to Cart Button      │
-│              │  Wishlist/Save           │
-│              │  Trust Badges            │
-└──────────────┴──────────────────────────┘
-```
-
-### 2. **Product Information** (Below the Fold - Vertical Sections)
-- ✅ Full Description (expandable)
-- ✅ Specifications/Attributes (scannable table)
-- ✅ Shipping & Returns Info
-- ✅ Size Guide (if applicable)
-- ✅ Reviews Section
-- ✅ Related Products
-- ✅ Recently Viewed
-
----
-
-## 🖼️ Image Gallery Requirements
-
-### Must-Have Features:
-1. **Main Image Display**
-   - Large, zoomable image
-   - High resolution (min 1200px width)
-   - Aspect ratio: 1:1 or 4:3
-
-2. **Thumbnail Slider**
-   - Horizontal scrollable
-   - 4-6 visible thumbnails
-   - Active thumbnail highlighted
-   - Arrow navigation for >4 images
-   - Touch/swipe enabled on mobile
-
-3. **Image Types Required:**
-   - ✅ Product on white background (default)
-   - ✅ "In Scale" images (with reference object/person)
-   - ✅ "Human Model" images (for wearables)
-   - ✅ Lifestyle/context images
-   - ✅ Detail shots (close-ups)
-   - ✅ 360° view (optional but recommended)
-
-4. **Variation Images:**
-   - Each variation should have its own image
-   - Auto-switch main image when variation selected
-   - Variation image highlighted in thumbnail slider
-
-### Image Gallery Interaction:
-```javascript
-// User Flow:
-1. Click thumbnail → Change main image
-2. Select variation → Auto-switch to variation image
-3. Click main image → Open lightbox/zoom
-4. Swipe thumbnails → Scroll horizontally
-5. Hover thumbnail → Preview in main (desktop)
-```
-
----
-
-## 🛒 Buy Section Elements
-
-### Required Elements (in order):
-1. **Product Title** - H1, clear, descriptive
-2. **Price Display:**
-   - Regular price (strikethrough if on sale)
-   - Sale price (highlighted in red/primary)
-   - Savings amount/percentage
-   - Unit price (for bulk items)
-
-3. **Rating & Reviews:**
-   - Star rating (visual)
-   - Number of reviews (clickable → scroll to reviews)
-   - "Write a Review" link
-
-4. **Stock Status:**
-   - ✅ In Stock (green)
-   - ⚠️ Low Stock (orange, show quantity)
-   - ❌ Out of Stock (red, "Notify Me" option)
-
-5. **Variation Selector:**
-   - Dropdown for each attribute
-   - Visual swatches for colors
-   - Size chart link (for apparel)
-   - Clear labels
-   - Disabled options grayed out
-
-6. **Quantity Selector:**
-   - Plus/minus buttons
-   - Number input
-   - Min/max validation
-   - Bulk pricing info (if applicable)
-
-7. **Action Buttons:**
-   - **Primary:** Add to Cart (large, prominent)
-   - **Secondary:** Buy Now (optional)
-   - **Tertiary:** Add to Wishlist/Save for Later
-
-8. **Trust Elements:**
-   - Security badges (SSL, payment methods)
-   - Free shipping threshold
-   - Return policy summary
-   - Warranty info
-
----
-
-## 📝 Product Information Sections
-
-### 1. Description Section
-```
-Format: Vertical collapsed/expandable
-- Short description (2-3 sentences) always visible
-- Full description expandable
-- Rich text formatting
-- Bullet points for features
-- Video embed support
-```
-
-### 2. Specifications/Attributes
-```
-Format: Scannable table
-- Two-column layout (Label | Value)
-- Grouped by category
-- Tooltips for technical terms
-- Expandable for long lists
-- Copy-to-clipboard for specs
-```
-
-### 3. Shipping & Returns
-```
-Always visible near buy section:
-- Estimated delivery date
-- Shipping cost calculator
-- Return policy link
-- Free shipping threshold
-- International shipping info
-```
-
-### 4. Size Guide (Apparel/Footwear)
-```
-- Modal/drawer popup
-- Size chart table
-- Measurement instructions
-- Fit guide (slim, regular, loose)
-- Model measurements
-```
-
----
-
-## ⭐ Reviews Section
-
-### Must-Have Features:
-1. **Review Summary:**
-   - Overall rating (large)
-   - Rating distribution (5-star breakdown)
-   - Total review count
-   - Verified purchase badge
-
-2. **Review Filters:**
-   - Sort by: Most Recent, Highest Rating, Lowest Rating, Most Helpful
-   - Filter by: Rating (1-5 stars), Verified Purchase, With Photos
-
-3. **Individual Review Display:**
-   - Reviewer name (or anonymous)
-   - Rating (stars)
-   - Date
-   - Verified purchase badge
-   - Review text
-   - Helpful votes (thumbs up/down)
-   - Seller response (if any)
-   - Review images (clickable gallery)
-
-4. **Review Submission:**
-   - Star rating (required)
-   - Title (optional)
-   - Review text (required, min 50 chars)
-   - Photo upload (optional)
-   - Recommend product (yes/no)
-   - Fit guide (for apparel)
-
-5. **Review Images Gallery:**
-   - Navigate all customer photos
-   - Filter reviews by "with photos"
-   - Lightbox view
-
----
-
-## 🎁 Promotions & Offers
-
-### Display Locations:
-1. **Product Badge** (on image)
-   - "Sale" / "New" / "Limited"
-   - Percentage off
-   - Free shipping
-
-2. **Price Section:**
-   - Coupon code field
-   - Auto-apply available coupons
-   - Bulk discount tiers
-   - Member pricing
-
-3. **Sticky Banner** (optional):
-   - Site-wide promotions
-   - Flash sales countdown
-   - Free shipping threshold
-
-### Coupon Integration:
-```
-- Auto-detect applicable coupons
-- One-click apply
-- Show savings in cart preview
-- Stackable coupons indicator
-```
-
----
-
-## 🔒 Trust & Social Proof Elements
-
-### 1. Trust Badges (Near Add to Cart):
-- Payment security (SSL, PCI)
-- Payment methods accepted
-- Money-back guarantee
-- Secure checkout badge
-
-### 2. Social Proof:
-- "X people viewing this now"
-- "X sold in last 24 hours"
-- "X people added to cart today"
-- Customer photos/UGC
-- Influencer endorsements
-
-### 3. Credibility Indicators:
-- Brand certifications
-- Awards & recognition
-- Press mentions
-- Expert reviews
-
----
-
-## 📱 Mobile Optimization
-
-### Mobile-Specific Considerations:
-1. **Image Gallery:**
-   - Swipeable main image
-   - Thumbnail strip below (horizontal scroll)
-   - Pinch to zoom
-
-2. **Sticky Add to Cart:**
-   - Fixed bottom bar
-   - Price + Add to Cart always visible
-   - Collapse on scroll down, expand on scroll up
-
-3. **Collapsed Sections:**
-   - All info sections collapsed by default
-   - Tap to expand
-   - Smooth animations
-
-4. **Touch Targets:**
-   - Min 44x44px for buttons
-   - Adequate spacing between elements
-   - Large, thumb-friendly controls
-
----
-
-## 🎨 Visual Design Guidelines
-
-### Typography:
-- **Product Title:** 28-32px, bold
-- **Price:** 24-28px, bold
-- **Body Text:** 14-16px
-- **Labels:** 12-14px, medium weight
-
-### Colors:
-- **Primary CTA:** High contrast, brand color
-- **Sale Price:** Red (#DC2626) or brand accent
-- **Success:** Green (#10B981)
-- **Warning:** Orange (#F59E0B)
-- **Error:** Red (#EF4444)
-
-### Spacing:
-- Section padding: 24-32px
-- Element spacing: 12-16px
-- Button padding: 12px 24px
-
----
-
-## 🔄 Interaction Patterns
-
-### 1. Variation Selection:
-```javascript
-// When user selects variation:
-1. Update price
-2. Update stock status
-3. Switch main image
-4. Update SKU
-5. Highlight variation image in gallery
-6. Enable/disable Add to Cart
-```
-
-### 2. Add to Cart:
-```javascript
-// On Add to Cart click:
-1. Validate selection (all variations selected)
-2. Show loading state
-3. Add to cart (API call)
-4. Show success toast with cart preview
-5. Update cart count in header
-6. Offer "View Cart" or "Continue Shopping"
-```
-
-### 3. Image Gallery:
-```javascript
-// Image interactions:
-1. Click thumbnail → Change main image
-2. Click main image → Open lightbox
-3. Swipe main image → Next/prev image
-4. Hover thumbnail → Preview (desktop)
-```
-
----
-
-## 📊 Performance Metrics
-
-### Key Metrics to Track:
-- Time to First Contentful Paint (< 1.5s)
-- Largest Contentful Paint (< 2.5s)
-- Image load time (< 1s)
-- Add to Cart conversion rate
-- Bounce rate
-- Time on page
-- Scroll depth
-
----
-
-## ✅ Implementation Checklist
-
-### Phase 1: Core Features (MVP)
-- [ ] Responsive image gallery with thumbnails
-- [ ] Horizontal scrollable thumbnail slider
-- [ ] Variation selector with image switching
-- [ ] Price display with sale pricing
-- [ ] Stock status indicator
-- [ ] Quantity selector
-- [ ] Add to Cart button
-- [ ] Product description (expandable)
-- [ ] Specifications table
-- [ ] Breadcrumb navigation
-
-### Phase 2: Enhanced Features
-- [ ] Reviews section with filtering
-- [ ] Review submission form
-- [ ] Related products carousel
-- [ ] Wishlist/Save for later
-- [ ] Share buttons
-- [ ] Shipping calculator
-- [ ] Size guide modal
-- [ ] Image zoom/lightbox
-
-### Phase 3: Advanced Features
-- [ ] 360° product view
-- [ ] Video integration
-- [ ] Live chat integration
-- [ ] Recently viewed products
-- [ ] Personalized recommendations
-- [ ] Social proof notifications
-- [ ] Coupon auto-apply
-- [ ] Bulk pricing display
-
----
-
-## 🚫 What to Avoid
-
-1. ❌ Horizontal tabs for content
-2. ❌ Hiding critical info below the fold
-3. ❌ Auto-playing videos
-4. ❌ Intrusive popups
-5. ❌ Tiny product images
-6. ❌ Unclear variation selectors
-7. ❌ Hidden shipping costs
-8. ❌ Complicated checkout process
-9. ❌ Fake urgency/scarcity
-10. ❌ Too many CTAs (decision paralysis)
-
----
-
-## 📚 References
-
-- Baymard Institute - Product Page UX 2025
-- Nielsen Norman Group - E-commerce UX
-- Shopify - Product Page Best Practices
-- ConvertCart - Social Proof Guidelines
-- Google - Mobile Page Speed Guidelines
-
----
-
-## 🔄 Version History
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 1.0 | 2025-11-26 | Initial SOP creation based on industry research |
-

REDIRECT_DEBUG.md

@@ -1,119 +0,0 @@
-# Product Page Redirect Debugging
-
-## Issue
-Direct access to product URLs like `/product/edukasi-anak` redirects to `/shop`.
-
-## Debugging Steps
-
-### 1. Check Console Logs
-Open browser console and navigate to: `https://woonoow.local/product/edukasi-anak`
-
-Look for these logs:
-```
-Product Component - Slug: edukasi-anak
-Product Component - Current URL: https://woonoow.local/product/edukasi-anak
-Product Query - Starting fetch for slug: edukasi-anak
-Product API Response: {...}
-```
-
-### 2. Possible Causes
-
-#### A. WordPress Canonical Redirect
-WordPress might be redirecting the URL because it doesn't recognize `/product/` as a valid route.
-
-**Solution:** Disable canonical redirects for SPA pages.
-
-#### B. React Router Not Matching
-The route might not be matching correctly.
-
-**Check:** Does the slug parameter get extracted?
-
-#### C. WooCommerce Redirect
-WooCommerce might be redirecting to shop page.
-
-**Check:** Is `is_product()` returning true?
-
-#### D. 404 Handling
-WordPress might be treating it as 404 and redirecting.
-
-**Check:** Is the page returning 404 status?
-
-### 3. Quick Tests
-
-#### Test 1: Check if Template Loads
-Add this to `spa-full-page.php` at the top:
-```php
-<?php
-error_log('SPA Template Loaded - is_product: ' . (is_product() ? 'yes' : 'no'));
-error_log('Current URL: ' . $_SERVER['REQUEST_URI']);
-?>
-```
-
-#### Test 2: Check React Router
-Add this to `App.tsx`:
-```tsx
-useEffect(() => {
-  console.log('Current Path:', window.location.pathname);
-  console.log('Is Product Route:', window.location.pathname.includes('/product/'));
-}, []);
-```
-
-#### Test 3: Check if Assets Load
-Open Network tab and check if `customer-spa.js` loads on product page.
-
-### 4. Likely Solution
-
-The issue is probably WordPress canonical redirect. Add this to `TemplateOverride.php`:
-
-```php
-public static function init() {
-    // ... existing code ...
-    
-    // Disable canonical redirects for SPA pages
-    add_filter('redirect_canonical', [__CLASS__, 'disable_canonical_redirect'], 10, 2);
-}
-
-public static function disable_canonical_redirect($redirect_url, $requested_url) {
-    $settings = get_option('woonoow_customer_spa_settings', []);
-    $mode = isset($settings['mode']) ? $settings['mode'] : 'disabled';
-    
-    if ($mode === 'full') {
-        // Check if this is a SPA route
-        $spa_routes = ['/product/', '/cart', '/checkout', '/my-account'];
-        
-        foreach ($spa_routes as $route) {
-            if (strpos($requested_url, $route) !== false) {
-                return false; // Disable redirect
-            }
-        }
-    }
-    
-    return $redirect_url;
-}
-```
-
-### 5. Alternative: Use Hash Router
-
-If canonical redirects can't be disabled, use HashRouter instead:
-
-```tsx
-// In App.tsx
-import { HashRouter } from 'react-router-dom';
-
-// Change BrowserRouter to HashRouter
-<HashRouter>
-  {/* routes */}
-</HashRouter>
-```
-
-URLs will be: `https://woonoow.local/#/product/edukasi-anak`
-
-This works because everything after `#` is client-side only.
-
-## Next Steps
-
-1. Add console logs (already done)
-2. Test and check console
-3. If slug is undefined → React Router issue
-4. If slug is defined but redirects → WordPress redirect issue
-5. Apply appropriate fix

RELEASE_NOTES-v1.0.md

@@ -0,0 +1,171 @@
+# WooNooW Page Editor v1.0 - Release Notes
+
+## Summary
+
+This release implements comprehensive improvements to the WooNooW Page Editor system, focusing on WYSIWYG consistency between the admin editor canvas and frontend rendering, improved SSR coverage for SEO, and robust backward compatibility with legacy structures.
+
+---
+
+## Key Improvements
+
+### 1. Canonical Section Schema
+
+**What changed:**
+- Unified section schema definition in `admin-spa/src/routes/Appearance/Pages/schema/sectionSchema.ts`
+- Normalized `feature-grid` to use `items` prop (not `features`)
+- Standardized default values across all section types
+
+**Why it matters:**
+- Single source of truth for section types, prop names, and defaults
+- Consistent naming eliminates `items` vs `features` confusion
+- Easier maintenance and extension of new section types
+
+**Files affected:**
+- `admin-spa/src/routes/Appearance/Pages/schema/sectionSchema.ts`
+- `admin-spa/src/routes/Appearance/Pages/store/usePageEditorStore.ts`
+- `admin-spa/src/routes/Appearance/Pages/components/CanvasRenderer.tsx`
+
+---
+
+### 2. Enhanced PHP SSR with Full Style Support
+
+**What changed:**
+- All section renderers now support section styles: background, gradient, images, overlay, padding, content width, height presets
+- Hero, Content, Image+Text, Feature Grid, CTA Banner, Contact Form, Bento Grid, Product Carousel, Shoppable Image, and Marquee Banner all render with full style parity
+
+**Why it matters:**
+- Bots now see the same styled content as human visitors
+- Better SEO with proper semantic HTML and styling
+- Consistent experience across all section types
+
+**Files affected:**
+- `includes/Frontend/PageSSR.php`
+
+---
+
+### 3. Dynamic Source Resolution Architecture
+
+**What changed:**
+- Moved complex dynamic resolution from controller to `PlaceholderRenderer`
+- Added typed output contracts (scalar, html, url, array)
+- Added explicit fallback behavior for empty/invalid dynamic sources
+- Added caching for post data resolution
+
+**Why it matters:**
+- `related_posts` special-casing removed from controller
+- Consistent handling of all dynamic sources
+- Better fallback UX when sources resolve to empty
+
+**Files affected:**
+- `includes/Frontend/PlaceholderRenderer.php`
+- `includes/Api/PagesController.php`
+
+---
+
+### 4. Schema Migration System
+
+**What changed:**
+- New `SchemaMigration` class handles backward compatibility
+- Automatic migration of legacy structures on read
+- Schema versioning (`schemaVersion`) tracking
+
+**Why it matters:**
+- Legacy pages/templates with `features` key automatically normalized to `items`
+- Old style keys (`container_width`, `height`) normalized to new keys (`contentWidth`, `heightPreset`)
+- Zero breaking changes for existing content
+
+**Files affected:**
+- `includes/Frontend/SchemaMigration.php`
+- `includes/Api/PagesController.php`
+
+---
+
+### 5. Feature Flags for Safe Rollout
+
+**What changed:**
+- New `Features` class for feature toggles
+- Default flags: `dynamic_preview`, `schema_v1`, `enhanced_ssr`, `placeholder_cache`
+- Per-user override support for testing
+
+**Why it matters:**
+- Staged rollout capability for new features
+- Easy rollback if issues arise
+- Admin control over feature enablement
+
+**Files affected:**
+- `includes/Features.php`
+
+---
+
+## Test Coverage
+
+### New Test Files
+
+| Test File | Coverage |
+|-----------|----------|
+| `tests/SchemaMigrationTest.php` | Migration of legacy structures, feature-grid normalization, style key conversions |
+| `tests/PlaceholderRendererTest.php` | Dynamic source resolution, typed output contracts, fallback behavior |
+| `tests/PageSSRTest.php` | All section renderers, resolve_props(), HTML output validation |
+| `tests/schema-integration.test.ts` | TypeScript schema validation, canvas prop flattening |
+| `tests/feature-grid-regression.test.ts` | items/features naming, default values, style keys regression |
+| `tests/parity.test.ts` | React vs SSR content parity, CSS class matching, color scheme parity |
+
+### CI Guardrails
+
+- `scripts/check-schema-drift.mjs` - Validates schema consistency between TypeScript and PHP
+
+### Verification Checklist
+
+- `tests/VERIFICATION_CHECKLIST.md` - Pre-flight checks and manual verification procedures
+
+---
+
+## Migration Guide
+
+### For Existing Installations
+
+**No action required.** All existing pages and templates will be automatically migrated on first access:
+- `features` → `items` normalization
+- `container_width` → `contentWidth` normalization
+- `height` → `heightPreset` normalization
+- `backgroundType` defaults added
+
+### For Custom Code
+
+If you have custom code referencing section props:
+- Replace `section.props.features` with `section.props.items` for feature-grid sections
+- Replace `section.styles.container_width` with `section.styles.contentWidth`
+- Replace `section.styles.height` with `section.styles.heightPreset`
+
+---
+
+## Breaking Changes
+
+**None.** This release maintains full backward compatibility.
+
+---
+
+## Deprecations
+
+The following are deprecated and will be removed in a future version:
+
+| Deprecated | Replacement | Estimated Removal |
+|------------|-------------|-------------------|
+| `features` prop on feature-grid | `items` | v2.0 |
+| `container_width` style | `contentWidth` | v2.0 |
+| `height` style | `heightPreset` | v2.0 |
+| Generic `render_generic()` fallback | Explicit section renderers | v2.0 |
+
+---
+
+## Support & Documentation
+
+- Internal support playbook: See project documentation
+- Schema contract: `project_info__1.md`
+- Test fixtures: `tests/fixtures/page-editor/`
+
+---
+
+## Contributors
+
+This release implements the work planned in the Page Editor audit and consistency improvements.

SHIPPING_INTEGRATION.md

@@ -1,322 +0,0 @@
-# Shipping Integration Guide
-
-This document consolidates shipping integration patterns and addon specifications for WooNooW.
-
----
-
-## Overview
-
-WooNooW supports flexible shipping integration through:
-1. **Standard WooCommerce Shipping Methods** - Works with any WC shipping plugin
-2. **Custom Shipping Addons** - Build shipping addons using WooNooW addon bridge
-3. **Indonesian Shipping** - Special handling for Indonesian address systems
-
----
-
-## Indonesian Shipping Challenges
-
-### RajaOngkir Integration Issue
-
-**Problem**: RajaOngkir plugin doesn't use standard WooCommerce address fields.
-
-#### How RajaOngkir Works:
-
-1. **Removes Standard Fields:**
-```php
-// class-cekongkir.php
-public function customize_checkout_fields($fields) {
-    unset($fields['billing']['billing_state']); 
-    unset($fields['billing']['billing_city']); 
-    unset($fields['shipping']['shipping_state']); 
-    unset($fields['shipping']['shipping_city']); 
-    return $fields;
-}
-```
-
-2. **Adds Custom Destination Dropdown:**
-```php
-<select id="cart-destination" name="cart_destination">
-    <option>Search and select location...</option>
-</select>
-```
-
-3. **Stores in Session:**
-```php
-WC()->session->set('selected_destination_id', $destination_id);
-WC()->session->set('selected_destination_label', $destination_label);
-```
-
-4. **Triggers Shipping Calculation:**
-```php
-WC()->cart->calculate_shipping();
-WC()->cart->calculate_totals();
-```
-
-#### Why Standard Implementation Fails:
-
-- WooNooW OrderForm uses standard fields: `city`, `state`, `postcode`
-- RajaOngkir ignores these fields
-- RajaOngkir only reads from session: `selected_destination_id`
-
-#### Solution:
-
-Use **Biteship** instead (see below) or create custom RajaOngkir addon that:
-- Hooks into WooNooW OrderForm
-- Adds Indonesian address selector
-- Syncs with RajaOngkir session
-
----
-
-## Biteship Integration Addon
-
-### Plugin Specification
-
-**Plugin Name:** WooNooW Indonesia Shipping  
-**Description:** Indonesian shipping integration using Biteship Rate API  
-**Version:** 1.0.0  
-**Requires:** WooNooW 1.0.0+, WooCommerce 8.0+
-
-### Features
-
-- ✅ Indonesian address fields (Province, City, District, Subdistrict)
-- ✅ Real-time shipping rate calculation
-- ✅ Multiple courier support (JNE, SiCepat, J&T, AnterAja, etc.)
-- ✅ Works in frontend checkout AND admin order form
-- ✅ No subscription required (uses free Biteship Rate API)
-
-### Implementation Phases
-
-#### Phase 1: Core Functionality
-- WooCommerce Shipping Method integration
-- Biteship Rate API integration
-- Indonesian address database (Province → Subdistrict)
-- Frontend checkout integration
-- Admin settings page
-
-#### Phase 2: SPA Integration
-- REST API endpoints for address data
-- REST API for rate calculation
-- React components (SubdistrictSelector, CourierSelector)
-- Hook integration with WooNooW OrderForm
-- Admin order form support
-
-#### Phase 3: Advanced Features
-- Rate caching (reduce API calls)
-- Custom rate markup
-- Free shipping threshold
-- Multi-origin support
-- Shipping label generation (optional, requires paid Biteship plan)
-
-### Plugin Structure
-
-```
-woonoow-indonesia-shipping/
-├── woonoow-indonesia-shipping.php
-├── includes/
-│   ├── class-shipping-method.php
-│   ├── class-biteship-api.php
-│   ├── class-address-database.php
-│   └── class-rest-controller.php
-├── admin/
-│   ├── class-settings.php
-│   └── views/
-├── assets/
-│   ├── js/
-│   │   ├── checkout.js
-│   │   └── admin-order.js
-│   └── css/
-└── data/
-    └── indonesia-addresses.json
-```
-
-### API Integration
-
-#### Biteship Rate API Endpoint
-```
-POST https://api.biteship.com/v1/rates/couriers
-```
-
-**Request:**
-```json
-{
-  "origin_area_id": "IDNP6IDNC148IDND1820IDZ16094",
-  "destination_area_id": "IDNP9IDNC235IDND3256IDZ41551",
-  "couriers": "jne,sicepat,jnt",
-  "items": [
-    {
-      "name": "Product Name",
-      "value": 100000,
-      "weight": 1000,
-      "quantity": 1
-    }
-  ]
-}
-```
-
-**Response:**
-```json
-{
-  "success": true,
-  "object": "courier_pricing",
-  "pricing": [
-    {
-      "courier_name": "JNE",
-      "courier_service_name": "REG",
-      "price": 15000,
-      "duration": "2-3 days"
-    }
-  ]
-}
-```
-
-### React Components
-
-#### SubdistrictSelector Component
-```tsx
-interface SubdistrictSelectorProps {
-  value: {
-    province_id: string;
-    city_id: string;
-    district_id: string;
-    subdistrict_id: string;
-  };
-  onChange: (value: any) => void;
-}
-
-export function SubdistrictSelector({ value, onChange }: SubdistrictSelectorProps) {
-  // Cascading dropdowns: Province → City → District → Subdistrict
-  // Uses WooNooW API: /woonoow/v1/shipping/indonesia/provinces
-}
-```
-
-#### CourierSelector Component
-```tsx
-interface CourierSelectorProps {
-  origin: string;
-  destination: string;
-  items: CartItem[];
-  onSelect: (courier: ShippingRate) => void;
-}
-
-export function CourierSelector({ origin, destination, items, onSelect }: CourierSelectorProps) {
-  // Fetches rates from Biteship
-  // Displays courier options with prices
-  // Uses WooNooW API: /woonoow/v1/shipping/indonesia/rates
-}
-```
-
-### Hook Integration
-
-```php
-// Register shipping addon
-add_filter('woonoow/shipping/address_fields', function($fields) {
-    if (get_option('woonoow_indonesia_shipping_enabled')) {
-        return [
-            'province' => [
-                'type' => 'select',
-                'label' => 'Province',
-                'required' => true,
-            ],
-            'city' => [
-                'type' => 'select',
-                'label' => 'City',
-                'required' => true,
-            ],
-            'district' => [
-                'type' => 'select',
-                'label' => 'District',
-                'required' => true,
-            ],
-            'subdistrict' => [
-                'type' => 'select',
-                'label' => 'Subdistrict',
-                'required' => true,
-            ],
-        ];
-    }
-    return $fields;
-});
-
-// Register React component
-add_filter('woonoow/checkout/shipping_selector', function($component) {
-    if (get_option('woonoow_indonesia_shipping_enabled')) {
-        return 'IndonesiaShippingSelector';
-    }
-    return $component;
-});
-```
-
----
-
-## General Shipping Integration
-
-### Standard WooCommerce Shipping
-
-WooNooW automatically supports any WooCommerce shipping plugin that uses standard shipping methods:
-
-- WooCommerce Flat Rate
-- WooCommerce Free Shipping
-- WooCommerce Local Pickup
-- Table Rate Shipping
-- Distance Rate Shipping
-- Any third-party shipping plugin
-
-### Custom Shipping Addons
-
-To create a custom shipping addon:
-
-1. **Create WooCommerce Shipping Method**
-```php
-class Custom_Shipping_Method extends WC_Shipping_Method {
-    public function calculate_shipping($package = []) {
-        // Your shipping calculation logic
-        $this->add_rate([
-            'id' => $this->id,
-            'label' => $this->title,
-            'cost' => $cost,
-        ]);
-    }
-}
-```
-
-2. **Register with WooCommerce**
-```php
-add_filter('woocommerce_shipping_methods', function($methods) {
-    $methods['custom_shipping'] = 'Custom_Shipping_Method';
-    return $methods;
-});
-```
-
-3. **Add SPA Integration (Optional)**
-```php
-// REST API for frontend
-register_rest_route('woonoow/v1', '/shipping/custom/rates', [
-    'methods' => 'POST',
-    'callback' => 'get_custom_shipping_rates',
-]);
-
-// React component hook
-add_filter('woonoow/checkout/shipping_fields', function($fields) {
-    // Add custom fields if needed
-    return $fields;
-});
-```
-
----
-
-## Best Practices
-
-1. **Use Standard WC Fields** - Whenever possible, use standard WooCommerce address fields
-2. **Cache Rates** - Cache shipping rates to reduce API calls
-3. **Error Handling** - Always provide fallback rates if API fails
-4. **Mobile Friendly** - Ensure shipping selectors work well on mobile
-5. **Admin Support** - Make sure shipping works in admin order form too
-
----
-
-## Resources
-
-- [WooCommerce Shipping Method Tutorial](https://woocommerce.com/document/shipping-method-api/)
-- [Biteship API Documentation](https://biteship.com/docs)
-- [WooNooW Addon Development Guide](ADDON_DEVELOPMENT_GUIDE.md)
-- [WooNooW Hooks Registry](HOOKS_REGISTRY.md)

SHIPPING_METHOD_TYPES.md

@@ -1,327 +0,0 @@
-# Shipping Method Types - WooCommerce Core Structure
-
-## The Two Types of Shipping Methods
-
-WooCommerce has TWO fundamentally different shipping method types:
-
----
-
-## Type 1: Static Methods (WooCommerce Core)
-
-**Characteristics:**
-- No API calls
-- Fixed rates or free
-- Configured once in settings
-- Available immediately
-
-**Examples:**
-- Free Shipping
-- Flat Rate
-- Local Pickup
-
-**Structure:**
-```
-Method: Free Shipping
-├── Conditions: Order total > $50
-└── Cost: $0
-```
-
-**In Create Order:**
-```
-User fills address
-→ Static methods appear immediately
-→ User selects one
-→ Done!
-```
-
----
-
-## Type 2: Live Rate Methods (API-based)
-
-**Characteristics:**
-- Requires API call
-- Dynamic rates based on address + weight
-- Returns multiple service options
-- Needs "Calculate" button
-
-**Examples:**
-- UPS (International)
-- FedEx, DHL
-- Indonesian Shipping Addons (J&T, JNE, SiCepat)
-
-**Structure:**
-```
-Method: UPS Live Rates
-├── API Credentials configured
-└── On calculate:
-    ├── Service: UPS Ground - $15.00
-    ├── Service: UPS 2nd Day - $25.00
-    └── Service: UPS Next Day - $45.00
-```
-
-**In Create Order:**
-```
-User fills address
-→ Click "Calculate Shipping"
-→ API returns service options
-→ User selects one
-→ Done!
-```
-
----
-
-## The Real Hierarchy
-
-### Static Method (Simple):
-```
-Method
-└── (No sub-levels)
-```
-
-### Live Rate Method (Complex):
-```
-Method
-├── Courier (if applicable)
-│   ├── Service Option 1
-│   ├── Service Option 2
-│   └── Service Option 3
-└── Or directly:
-    ├── Service Option 1
-    └── Service Option 2
-```
-
----
-
-## Indonesian Shipping Example
-
-**Method:** Indonesian Shipping (API-based)
-**API:** Biteship / RajaOngkir / Custom
-
-**After Calculate:**
-```
-J&T Express
-├── Regular Service: Rp15,000 (2-3 days)
-└── Express Service: Rp25,000 (1 day)
-
-JNE
-├── REG: Rp18,000 (2-4 days)
-├── YES: Rp28,000 (1-2 days)
-└── OKE: Rp12,000 (3-5 days)
-
-SiCepat
-├── Regular: Rp16,000 (2-3 days)
-└── BEST: Rp20,000 (1-2 days)
-```
-
-**User sees:** Courier name + Service name + Price + Estimate
-
----
-
-## UPS Example (International)
-
-**Method:** UPS Live Rates
-**API:** UPS API
-
-**After Calculate:**
-```
-UPS Ground: $15.00 (5-7 business days)
-UPS 2nd Day Air: $25.00 (2 business days)
-UPS Next Day Air: $45.00 (1 business day)
-```
-
-**User sees:** Service name + Price + Estimate
-
----
-
-## Address Field Requirements
-
-### Static Methods:
-- Country
-- State/Province
-- City
-- Postal Code
-- Address Line 1
-- Address Line 2 (optional)
-
-### Live Rate Methods:
-
-**International (UPS, FedEx, DHL):**
-- Country
-- State/Province
-- City
-- **Postal Code** (REQUIRED - used for rate calculation)
-- Address Line 1
-- Address Line 2 (optional)
-
-**Indonesian (J&T, JNE, SiCepat):**
-- Country: Indonesia
-- Province
-- City/Regency
-- **Subdistrict** (REQUIRED - used for rate calculation)
-- Postal Code
-- Address Line 1
-- Address Line 2 (optional)
-
----
-
-## The Pattern
-
-| Method Type | Address Requirement | Rate Calculation |
-|-------------|---------------------|------------------|
-| Static | Basic address | Fixed/Free |
-| Live Rate (International) | **Postal Code** required | API call with postal code |
-| Live Rate (Indonesian) | **Subdistrict** required | API call with subdistrict ID |
-
----
-
-## Implementation in Create Order
-
-### Current Problem:
-- We probably require subdistrict for ALL methods
-- This breaks international live rate methods
-
-### Solution:
-
-**Step 1: Detect Available Methods**
-```javascript
-const availableMethods = getShippingMethods(address.country);
-
-const needsSubdistrict = availableMethods.some(method => 
-  method.type === 'live_rate' && method.country === 'ID'
-);
-
-const needsPostalCode = availableMethods.some(method => 
-  method.type === 'live_rate' && method.country !== 'ID'
-);
-```
-
-**Step 2: Show Conditional Fields**
-```javascript
-// Always show
-- Country
-- State/Province
-- City
-- Address Line 1
-
-// Conditional
-if (needsSubdistrict) {
-  - Subdistrict (required)
-}
-
-if (needsPostalCode || needsSubdistrict) {
-  - Postal Code (required)
-}
-
-// Always optional
-- Address Line 2
-```
-
-**Step 3: Calculate Shipping**
-```javascript
-// Static methods
-if (method.type === 'static') {
-  return method.cost; // Immediate
-}
-
-// Live rate methods
-if (method.type === 'live_rate') {
-  const rates = await fetchLiveRates({
-    method: method.id,
-    address: {
-      country: address.country,
-      state: address.state,
-      city: address.city,
-      subdistrict: address.subdistrict, // If Indonesian
-      postal_code: address.postal_code, // If international
-      // ... other fields
-    }
-  });
-  
-  return rates; // Array of service options
-}
-```
-
----
-
-## UI Flow
-
-### Scenario 1: Static Method Only
-```
-1. User fills basic address
-2. Shipping options appear immediately:
-   - Free Shipping: $0
-   - Flat Rate: $10
-3. User selects one
-4. Done!
-```
-
-### Scenario 2: Indonesian Live Rate
-```
-1. User fills address including subdistrict
-2. Click "Calculate Shipping"
-3. API returns:
-   - J&T Regular: Rp15,000
-   - JNE REG: Rp18,000
-   - SiCepat BEST: Rp20,000
-4. User selects one
-5. Done!
-```
-
-### Scenario 3: International Live Rate
-```
-1. User fills address including postal code
-2. Click "Calculate Shipping"
-3. API returns:
-   - UPS Ground: $15.00
-   - UPS 2nd Day: $25.00
-4. User selects one
-5. Done!
-```
-
-### Scenario 4: Mixed (Static + Live Rate)
-```
-1. User fills address
-2. Static methods appear immediately:
-   - Free Shipping: $0
-3. Click "Calculate Shipping" for live rates
-4. Live rates appear:
-   - UPS Ground: $15.00
-5. User selects from all options
-6. Done!
-```
-
----
-
-## WooCommerce Core Behavior
-
-**Yes, this is all in WooCommerce core!**
-
-- Static methods: `WC_Shipping_Method` class
-- Live rate methods: Extend `WC_Shipping_Method` with API logic
-- Service options: Stored as shipping rates with method_id + instance_id
-
-**WooCommerce handles:**
-- Method registration
-- Rate calculation
-- Service option display
-- Selection and storage
-
-**We need to handle:**
-- Conditional address fields
-- "Calculate" button for live rates
-- Service option display in Create Order
-- Proper address validation
-
----
-
-## Next Steps
-
-1. Investigate Create Order address field logic
-2. Add conditional field display based on available methods
-3. Add "Calculate Shipping" button for live rates
-4. Display service options properly
-5. Test with:
-   - Static methods only
-   - Indonesian live rates
-   - International live rates
-   - Mixed scenarios

SPRINT_1-2_COMPLETION_REPORT.md

@@ -1,415 +0,0 @@
-# Sprint 1-2 Completion Report ✅ COMPLETE
-
-**Status:** ✅ All objectives achieved and tested
-**Date Completed:** November 22, 2025
-## Customer SPA Foundation
-
-**Date:** November 22, 2025  
-**Status:** ✅ Foundation Complete - Ready for Build & Testing
-
----
-
-## Executive Summary
-
-Sprint 1-2 objectives have been **successfully completed**. The customer-spa foundation is now in place with:
-- ✅ Backend API controllers (Shop, Cart, Account)
-- ✅ Frontend base layout components (Header, Footer, Container)
-- ✅ WordPress integration (Shortcodes, Asset loading)
-- ✅ Authentication flow (using WordPress user session)
-- ✅ Routing structure
-- ✅ State management (Zustand for cart)
-- ✅ API client with endpoints
-
----
-
-## What Was Built
-
-### 1. Backend API Controllers ✅
-
-Created three new customer-facing API controllers in `includes/Frontend/`:
-
-#### **ShopController.php**
-```
-GET  /woonoow/v1/shop/products          # List products with filters
-GET  /woonoow/v1/shop/products/{id}     # Get single product (with variations)
-GET  /woonoow/v1/shop/categories        # List categories
-GET  /woonoow/v1/shop/search            # Search products
-```
-
-**Features:**
-- Product listing with pagination, category filter, search
-- Single product with detailed info (variations, gallery, related products)
-- Category listing with images
-- Product search
-
-#### **CartController.php**
-```
-GET   /woonoow/v1/cart                  # Get cart contents
-POST  /woonoow/v1/cart/add              # Add item to cart
-POST  /woonoow/v1/cart/update           # Update cart item quantity
-POST  /woonoow/v1/cart/remove           # Remove item from cart
-POST  /woonoow/v1/cart/apply-coupon     # Apply coupon
-POST  /woonoow/v1/cart/remove-coupon    # Remove coupon
-```
-
-**Features:**
-- Full cart CRUD operations
-- Coupon management
-- Cart totals calculation (subtotal, tax, shipping, discount)
-- WooCommerce session integration
-
-#### **AccountController.php**
-```
-GET   /woonoow/v1/account/orders        # Get customer orders
-GET   /woonoow/v1/account/orders/{id}   # Get single order
-GET   /woonoow/v1/account/profile       # Get customer profile
-POST  /woonoow/v1/account/profile       # Update profile
-POST  /woonoow/v1/account/password      # Update password
-GET   /woonoow/v1/account/addresses     # Get addresses
-POST  /woonoow/v1/account/addresses     # Update addresses
-GET   /woonoow/v1/account/downloads     # Get digital downloads
-```
-
-**Features:**
-- Order history with pagination
-- Order details with items, addresses, totals
-- Profile management
-- Password update
-- Billing/shipping address management
-- Digital downloads support
-- Permission checks (logged-in users only)
-
-**Files Created:**
-- `includes/Frontend/ShopController.php`
-- `includes/Frontend/CartController.php`
-- `includes/Frontend/AccountController.php`
-
-**Integration:**
-- Updated `includes/Api/Routes.php` to register frontend controllers
-- All routes registered under `woonoow/v1` namespace
-
----
-
-### 2. WordPress Integration ✅
-
-#### **Assets Manager** (`includes/Frontend/Assets.php`)
-- Enqueues customer-spa JS/CSS on pages with shortcodes
-- Adds inline config with API URL, nonce, user info
-- Supports both production build and dev mode
-- Smart loading (only loads when needed)
-
-#### **Shortcodes Manager** (`includes/Frontend/Shortcodes.php`)
-Created four shortcodes:
-- `[woonoow_shop]` - Product listing page
-- `[woonoow_cart]` - Shopping cart page
-- `[woonoow_checkout]` - Checkout page (requires login)
-- `[woonoow_account]` - My account page (requires login)
-
-**Features:**
-- Renders mount point for React app
-- Passes data attributes for page-specific config
-- Login requirement for protected pages
-- Loading state placeholder
-
-**Integration:**
-- Updated `includes/Core/Bootstrap.php` to initialize frontend classes
-- Assets and shortcodes auto-load on `plugins_loaded` hook
-
----
-
-### 3. Frontend Components ✅
-
-#### **Base Layout Components**
-Created in `customer-spa/src/components/Layout/`:
-
-**Header.tsx**
-- Logo and navigation
-- Cart icon with item count badge
-- User account link (if logged in)
-- Search button
-- Mobile menu button
-- Sticky header with backdrop blur
-
-**Footer.tsx**
-- Multi-column footer (About, Shop, Account, Support)
-- Links to main pages
-- Copyright notice
-- Responsive grid layout
-
-**Container.tsx**
-- Responsive container wrapper
-- Uses `container-safe` utility class
-- Consistent padding and max-width
-
-**Layout.tsx**
-- Main layout wrapper
-- Header + Content + Footer structure
-- Flex layout with sticky footer
-
-#### **UI Components**
-- `components/ui/button.tsx` - Button component with variants (shadcn/ui pattern)
-
-#### **Utilities**
-- `lib/utils.ts` - Helper functions:
-  - `cn()` - Tailwind class merging
-  - `formatPrice()` - Currency formatting
-  - `formatDate()` - Date formatting
-  - `debounce()` - Debounce function
-
-**Integration:**
-- Updated `App.tsx` to use Layout wrapper
-- All pages now render inside consistent layout
-
----
-
-### 4. Authentication Flow ✅
-
-**Implementation:**
-- Uses WordPress session (no separate auth needed)
-- User info passed via `window.woonoowCustomer.user`
-- Nonce-based API authentication
-- Login requirement enforced at shortcode level
-
-**User Data Available:**
-```typescript
-window.woonoowCustomer = {
-  apiUrl: '/wp-json/woonoow/v1',
-  nonce: 'wp_rest_nonce',
-  siteUrl: 'https://site.local',
-  user: {
-    isLoggedIn: true,
-    id: 123
-  }
-}
-```
-
-**Protected Routes:**
-- Checkout page requires login
-- Account pages require login
-- API endpoints check `is_user_logged_in()`
-
----
-
-## File Structure
-
-```
-woonoow/
-├── includes/
-│   ├── Frontend/                    # NEW - Customer-facing backend
-│   │   ├── ShopController.php       # Product catalog API
-│   │   ├── CartController.php       # Cart operations API
-│   │   ├── AccountController.php    # Customer account API
-│   │   ├── Assets.php               # Asset loading
-│   │   └── Shortcodes.php           # Shortcode handlers
-│   ├── Api/
-│   │   └── Routes.php               # UPDATED - Register frontend routes
-│   └── Core/
-│       └── Bootstrap.php            # UPDATED - Initialize frontend
-│
-└── customer-spa/
-    ├── src/
-    │   ├── components/
-    │   │   ├── Layout/              # NEW - Layout components
-    │   │   │   ├── Header.tsx
-    │   │   │   ├── Footer.tsx
-    │   │   │   ├── Container.tsx
-    │   │   │   └── Layout.tsx
-    │   │   └── ui/                  # NEW - UI components
-    │   │       └── button.tsx
-    │   ├── lib/
-    │   │   ├── api/
-    │   │   │   └── client.ts        # EXISTING - API client
-    │   │   ├── cart/
-    │   │   │   └── store.ts         # EXISTING - Cart state
-    │   │   └── utils.ts             # NEW - Utility functions
-    │   ├── pages/                   # EXISTING - Page placeholders
-    │   ├── App.tsx                  # UPDATED - Add Layout wrapper
-    │   └── index.css                # EXISTING - Global styles
-    └── package.json                 # EXISTING - Dependencies
-```
-
----
-
-## Sprint 1-2 Checklist
-
-According to `CUSTOMER_SPA_MASTER_PLAN.md`, Sprint 1-2 tasks:
-
-- [x] **Setup customer-spa build system** - ✅ Vite + React + TypeScript configured
-- [x] **Create base layout components** - ✅ Header, Footer, Container, Layout
-- [x] **Implement routing** - ✅ React Router with routes for all pages
-- [x] **Setup API client** - ✅ Client exists with all endpoints defined
-- [x] **Cart state management** - ✅ Zustand store with persistence
-- [x] **Authentication flow** - ✅ WordPress session integration
-
-**All Sprint 1-2 objectives completed!** ✅
-
----
-
-## Next Steps (Sprint 3-4)
-
-### Immediate: Build & Test
-1. **Build customer-spa:**
-   ```bash
-   cd customer-spa
-   npm install
-   npm run build
-   ```
-
-2. **Create test pages in WordPress:**
-   - Create page "Shop" with `[woonoow_shop]`
-   - Create page "Cart" with `[woonoow_cart]`
-   - Create page "Checkout" with `[woonoow_checkout]`
-   - Create page "My Account" with `[woonoow_account]`
-
-3. **Test API endpoints:**
-   ```bash
-   # Test shop API
-   curl "https://woonoow.local/wp-json/woonoow/v1/shop/products"
-   
-   # Test cart API
-   curl "https://woonoow.local/wp-json/woonoow/v1/cart"
-   ```
-
-### Sprint 3-4: Product Catalog
-According to the master plan:
-- [ ] Product listing page (with real data)
-- [ ] Product filters (category, price, search)
-- [ ] Product search functionality
-- [ ] Product detail page (with variations)
-- [ ] Product variations selector
-- [ ] Image gallery with zoom
-- [ ] Related products section
-
----
-
-## Technical Notes
-
-### API Design
-- All customer-facing routes use `/woonoow/v1` namespace
-- Public routes (shop) use `'permission_callback' => '__return_true'`
-- Protected routes (account) check `is_user_logged_in()`
-- Consistent response format with proper HTTP status codes
-
-### Frontend Architecture
-- **Hybrid approach:** Works with any theme via shortcodes
-- **Progressive enhancement:** Theme provides layout, WooNooW provides interactivity
-- **Mobile-first:** Responsive design with Tailwind utilities
-- **Performance:** Code splitting, lazy loading, optimized builds
-
-### WordPress Integration
-- **Safe activation:** No database changes, reversible
-- **Theme compatibility:** Works with any theme
-- **SEO-friendly:** Server-rendered product pages (future)
-- **Tracking-ready:** WooCommerce event triggers for pixels (future)
-
----
-
-## Known Limitations
-
-### Current Sprint (1-2)
-1. **Pages are placeholders** - Need real implementations in Sprint 3-4
-2. **No product data rendering** - API works, but UI needs to consume it
-3. **No checkout flow** - CheckoutController not created yet (Sprint 5-6)
-4. **No cart drawer** - Cart page exists, but no slide-out drawer yet
-
-### Future Sprints
-- Sprint 3-4: Product catalog implementation
-- Sprint 5-6: Cart drawer + Checkout flow
-- Sprint 7-8: My Account pages implementation
-- Sprint 9-10: Polish, testing, performance optimization
-
----
-
-## Testing Checklist
-
-### Backend API Testing
-- [ ] Test `/shop/products` - Returns product list
-- [ ] Test `/shop/products/{id}` - Returns single product
-- [ ] Test `/shop/categories` - Returns categories
-- [ ] Test `/cart` - Returns empty cart
-- [ ] Test `/cart/add` - Adds product to cart
-- [ ] Test `/account/orders` - Requires login, returns orders
-
-### Frontend Testing
-- [ ] Build customer-spa successfully
-- [ ] Create test pages with shortcodes
-- [ ] Verify assets load on shortcode pages
-- [ ] Check `window.woonoowCustomer` config exists
-- [ ] Verify Header renders with cart count
-- [ ] Verify Footer renders with links
-- [ ] Test navigation between pages
-
-### Integration Testing
-- [ ] Shortcodes render mount point
-- [ ] React app mounts on shortcode pages
-- [ ] API calls work from frontend
-- [ ] Cart state persists in localStorage
-- [ ] User login state detected correctly
-
----
-
-## Success Criteria
-
-✅ **Sprint 1-2 is complete when:**
-- [x] Backend API controllers created and registered
-- [x] Frontend layout components created
-- [x] WordPress integration (shortcodes, assets) working
-- [x] Authentication flow implemented
-- [x] Build system configured
-- [ ] **Build succeeds** (pending: run `npm run build`)
-- [ ] **Test pages work** (pending: create WordPress pages)
-
-**Status:** 5/7 complete - Ready for build & testing phase
-
----
-
-## Commands Reference
-
-### Build Customer SPA
-```bash
-cd /Users/dwindown/Local\ Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa
-npm install
-npm run build
-```
-
-### Dev Mode (Hot Reload)
-```bash
-cd customer-spa
-npm run dev
-# Runs at https://woonoow.local:5174
-```
-
-### Test API Endpoints
-```bash
-# Shop API
-curl "https://woonoow.local/wp-json/woonoow/v1/shop/products"
-
-# Cart API
-curl "https://woonoow.local/wp-json/woonoow/v1/cart" \
-  -H "X-WP-Nonce: YOUR_NONCE"
-
-# Account API (requires auth)
-curl "https://woonoow.local/wp-json/woonoow/v1/account/orders" \
-  -H "X-WP-Nonce: YOUR_NONCE" \
-  -H "Cookie: wordpress_logged_in_..."
-```
-
----
-
-## Conclusion
-
-**Sprint 1-2 foundation is complete!** 🎉
-
-The customer-spa now has:
-- ✅ Solid backend API foundation
-- ✅ Clean frontend architecture
-- ✅ WordPress integration layer
-- ✅ Authentication flow
-- ✅ Base layout components
-
-**Ready for:**
-- Building the customer-spa
-- Creating test pages
-- Moving to Sprint 3-4 (Product Catalog implementation)
-
-**Next session:** Build, test, and start implementing real product listing page.

SPRINT_3-4_PLAN.md

@@ -1,288 +0,0 @@
-# Sprint 3-4: Product Catalog & Cart
-
-**Duration:** Sprint 3-4 (2 weeks)  
-**Status:** 🚀 Ready to Start  
-**Prerequisites:** ✅ Sprint 1-2 Complete
-
----
-
-## Objectives
-
-Build out the complete product catalog experience and shopping cart functionality.
-
-### Sprint 3: Product Catalog Enhancement
-1. **Product Detail Page** - Full product view with variations
-2. **Product Filters** - Category, price, attributes
-3. **Product Search** - Real-time search with debouncing
-4. **Product Sorting** - Price, popularity, rating, date
-
-### Sprint 4: Shopping Cart
-1. **Cart Page** - View and manage cart items
-2. **Cart Sidebar** - Quick cart preview
-3. **Cart API Integration** - Sync with WooCommerce cart
-4. **Coupon Application** - Apply and remove coupons
-
----
-
-## Sprint 3: Product Catalog Enhancement
-
-### 1. Product Detail Page (`/product/:id`)
-
-**File:** `customer-spa/src/pages/Product/index.tsx`
-
-**Features:**
-- Product images gallery with zoom
-- Product title, price, description
-- Variation selector (size, color, etc.)
-- Quantity selector
-- Add to cart button
-- Related products
-- Product reviews (if enabled)
-
-**API Endpoints:**
-- `GET /shop/products/:id` - Get product details
-- `GET /shop/products/:id/related` - Get related products (optional)
-
-**Components to Create:**
-- `ProductGallery.tsx` - Image gallery with thumbnails
-- `VariationSelector.tsx` - Select product variations
-- `QuantityInput.tsx` - Quantity selector
-- `ProductMeta.tsx` - SKU, categories, tags
-- `RelatedProducts.tsx` - Related products carousel
-
----
-
-### 2. Product Filters
-
-**File:** `customer-spa/src/components/Shop/Filters.tsx`
-
-**Features:**
-- Category filter (tree structure)
-- Price range slider
-- Attribute filters (color, size, brand, etc.)
-- Stock status filter
-- On sale filter
-- Clear all filters button
-
-**State Management:**
-- Use URL query parameters for filters
-- Persist filters in URL for sharing
-
-**Components:**
-- `CategoryFilter.tsx` - Hierarchical category tree
-- `PriceRangeFilter.tsx` - Price slider
-- `AttributeFilter.tsx` - Checkbox list for attributes
-- `ActiveFilters.tsx` - Show active filters with remove buttons
-
----
-
-### 3. Product Search Enhancement
-
-**Current:** Basic search input  
-**Enhancement:** Real-time search with suggestions
-
-**Features:**
-- Search as you type
-- Search suggestions dropdown
-- Recent searches
-- Popular searches
-- Product thumbnails in results
-- Keyboard navigation (arrow keys, enter, escape)
-
-**File:** `customer-spa/src/components/Shop/SearchBar.tsx`
-
----
-
-### 4. Product Sorting
-
-**Features:**
-- Sort by: Default, Popularity, Rating, Price (low to high), Price (high to low), Latest
-- Dropdown selector
-- Persist in URL
-
-**File:** `customer-spa/src/components/Shop/SortDropdown.tsx`
-
----
-
-## Sprint 4: Shopping Cart
-
-### 1. Cart Page (`/cart`)
-
-**File:** `customer-spa/src/pages/Cart/index.tsx`
-
-**Features:**
-- Cart items list with thumbnails
-- Quantity adjustment (+ / -)
-- Remove item button
-- Update cart button
-- Cart totals (subtotal, tax, shipping, total)
-- Coupon code input
-- Proceed to checkout button
-- Continue shopping link
-- Empty cart state
-
-**Components:**
-- `CartItem.tsx` - Single cart item row
-- `CartTotals.tsx` - Cart totals summary
-- `CouponForm.tsx` - Apply coupon code
-- `EmptyCart.tsx` - Empty cart message
-
----
-
-### 2. Cart Sidebar/Drawer
-
-**File:** `customer-spa/src/components/Cart/CartDrawer.tsx`
-
-**Features:**
-- Slide-in from right
-- Mini cart items (max 5, then scroll)
-- Cart totals
-- View cart button
-- Checkout button
-- Close button
-- Backdrop overlay
-
-**Trigger:**
-- Click cart icon in header
-- Auto-open when item added (optional)
-
----
-
-### 3. Cart API Integration
-
-**Endpoints:**
-- `GET /cart` - Get current cart
-- `POST /cart/add` - Add item to cart
-- `PUT /cart/update` - Update item quantity
-- `DELETE /cart/remove` - Remove item
-- `POST /cart/apply-coupon` - Apply coupon
-- `DELETE /cart/remove-coupon` - Remove coupon
-
-**State Management:**
-- Zustand store already created (`customer-spa/src/lib/cart/store.ts`)
-- Sync with WooCommerce session
-- Persist cart in localStorage
-- Handle cart conflicts (server vs local)
-
----
-
-### 4. Coupon System
-
-**Features:**
-- Apply coupon code
-- Show discount amount
-- Show coupon description
-- Remove coupon button
-- Error handling (invalid, expired, usage limit)
-
-**Backend:**
-- Already implemented in `CartController.php`
-- `POST /cart/apply-coupon`
-- `DELETE /cart/remove-coupon`
-
----
-
-## Technical Considerations
-
-### Performance
-- Lazy load product images
-- Implement infinite scroll for product grid (optional)
-- Cache product data with TanStack Query
-- Debounce search and filter inputs
-
-### UX Enhancements
-- Loading skeletons for all states
-- Optimistic updates for cart actions
-- Toast notifications for user feedback
-- Smooth transitions and animations
-- Mobile-first responsive design
-
-### Error Handling
-- Network errors
-- Out of stock products
-- Invalid variations
-- Cart conflicts
-- API timeouts
-
-### Accessibility
-- Keyboard navigation
-- Screen reader support
-- Focus management
-- ARIA labels
-- Color contrast
-
----
-
-## Implementation Order
-
-### Week 1 (Sprint 3)
-1. **Day 1-2:** Product Detail Page
-   - Basic layout and product info
-   - Image gallery
-   - Add to cart functionality
-
-2. **Day 3:** Variation Selector
-   - Handle simple and variable products
-   - Update price based on variation
-   - Validation
-
-3. **Day 4-5:** Filters & Search
-   - Category filter
-   - Price range filter
-   - Search enhancement
-   - Sort dropdown
-
-### Week 2 (Sprint 4)
-1. **Day 1-2:** Cart Page
-   - Cart items list
-   - Quantity adjustment
-   - Cart totals
-   - Coupon application
-
-2. **Day 3:** Cart Drawer
-   - Slide-in sidebar
-   - Mini cart items
-   - Quick actions
-
-3. **Day 4:** Cart API Integration
-   - Sync with backend
-   - Handle conflicts
-   - Error handling
-
-4. **Day 5:** Polish & Testing
-   - Responsive design
-   - Loading states
-   - Error states
-   - Cross-browser testing
-
----
-
-## Success Criteria
-
-### Sprint 3
-- ✅ Product detail page displays all product info
-- ✅ Variations can be selected and price updates
-- ✅ Filters work and update product list
-- ✅ Search returns relevant results
-- ✅ Sorting works correctly
-
-### Sprint 4
-- ✅ Cart page displays all cart items
-- ✅ Quantity can be adjusted
-- ✅ Items can be removed
-- ✅ Coupons can be applied and removed
-- ✅ Cart drawer opens and closes smoothly
-- ✅ Cart syncs with WooCommerce backend
-- ✅ Cart persists across page reloads
-
----
-
-## Next Steps
-
-1. Review this plan
-2. Confirm priorities
-3. Start with Product Detail Page
-4. Implement features incrementally
-5. Test each feature before moving to next
-
-**Ready to start Sprint 3?** 🚀

STORE_UI_UX_GUIDE.md

@@ -1,634 +0,0 @@
-# WooNooW Store UI/UX Guide
-## Official Design System & Standards
-
-**Version:** 1.0  
-**Last Updated:** November 26, 2025  
-**Status:** Living Document (Updated by conversation)
-
----
-
-## 📋 Purpose
-
-This document serves as the single source of truth for all UI/UX decisions in WooNooW Customer SPA. All design and implementation decisions should reference this guide.
-
-**Philosophy:** Pragmatic, not dogmatic. Follow convention when strong, follow research when clear, use hybrid when beneficial.
-
----
-
-## 🎯 Core Principles
-
-1. **Convention Over Innovation** - Users expect familiar patterns
-2. **Research-Backed Decisions** - When convention is weak or wrong
-3. **Mobile-First Approach** - Design for mobile, enhance for desktop
-4. **Performance Matters** - Fast > Feature-rich
-5. **Accessibility Always** - WCAG 2.1 AA minimum
-
----
-
-## 📐 Layout Standards
-
-### Container Widths
-
-```css
-Mobile:    100% (with padding)
-Tablet:    768px max-width
-Desktop:   1200px max-width
-Wide:      1400px max-width
-```
-
-### Spacing Scale
-
-```css
-xs:  0.25rem (4px)
-sm:  0.5rem  (8px)
-md:  1rem    (16px)
-lg:  1.5rem  (24px)
-xl:  2rem    (32px)
-2xl: 3rem    (48px)
-```
-
-### Breakpoints
-
-```css
-sm:  640px
-md:  768px
-lg:  1024px
-xl:  1280px
-2xl: 1536px
-```
-
----
-
-## 🎨 Typography
-
-### Hierarchy
-
-```
-H1 (Product Title):     28-32px, bold
-H2 (Section Title):     24-28px, bold
-H3 (Subsection):        20-24px, semibold
-Price (Primary):        24-28px, bold
-Price (Sale):           24-28px, bold, red
-Price (Regular):        18-20px, line-through, gray
-Body:                   16px, regular
-Small:                  14px, regular
-Tiny:                   12px, regular
-```
-
-### Font Stack
-
-```css
-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 
-             Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
-```
-
-### Rules
-
-- ✅ Title > Price in hierarchy (we're not a marketplace)
-- ✅ Use weight and color for emphasis, not just size
-- ✅ Line height: 1.5 for body, 1.2 for headings
-- ❌ Don't use more than 3 font sizes per section
-
----
-
-## 🖼️ Product Page Standards
-
-### Image Gallery
-
-#### Desktop:
-```
-Layout:
-┌─────────────────────────────────────┐
-│        [Main Image]                 │
-│        (Large, square)              │
-└─────────────────────────────────────┘
-[▭] [▭] [▭] [▭] [▭] ← Thumbnails (96-112px)
-```
-
-**Rules:**
-- ✅ Thumbnails: 96-112px (24-28 in Tailwind)
-- ✅ Horizontal scrollable if >4 images
-- ✅ Active thumbnail: Primary border + ring
-- ✅ Main image: object-contain with padding
-- ✅ Click thumbnail → change main image
-- ✅ Click main image → fullscreen lightbox
-
-#### Mobile:
-```
-Layout:
-┌─────────────────────────────────────┐
-│        [Main Image]                 │
-│        (Full width, square)         │
-│         ● ○ ○ ○ ○                   │
-└─────────────────────────────────────┘
-```
-
-**Rules:**
-- ✅ Dots only (NO thumbnails)
-- ✅ Swipe gesture for navigation
-- ✅ Dots: 8-10px, centered below image
-- ✅ Active dot: Primary color, larger
-- ✅ Image counter optional (e.g., "1/5")
-- ❌ NO thumbnails (redundant with dots)
-
-**Rationale:** Convention (Amazon, Tokopedia, Shopify all use dots only on mobile)
-
----
-
-### Variation Selectors
-
-#### Pattern: Pills/Buttons (NOT Dropdowns)
-
-**Color Variations:**
-```html
-[⬜ White] [⬛ Black] [🔴 Red] [🔵 Blue]
-```
-
-**Size/Text Variations:**
-```html
-[36] [37] [38] [39] [40] [41]
-```
-
-**Rules:**
-- ✅ All options visible at once
-- ✅ Pills: min 44x44px (touch target)
-- ✅ Active state: Primary background + white text
-- ✅ Hover state: Border color change
-- ✅ Disabled state: Gray + opacity 50%
-- ❌ NO dropdowns (hides options, poor UX)
-
-**Rationale:** Convention + Research align (Nielsen Norman Group)
-
----
-
-### Product Information Sections
-
-#### Pattern: Vertical Accordions
-
-**Desktop & Mobile:**
-```
-┌─────────────────────────────────────┐
-│ ▼ Product Description               │ ← Auto-expanded
-│   Full description text...          │
-└─────────────────────────────────────┘
-┌─────────────────────────────────────┐
-│ ▶ Specifications                    │ ← Collapsed
-└─────────────────────────────────────┘
-┌─────────────────────────────────────┐
-│ ▶ Customer Reviews                  │ ← Collapsed
-└─────────────────────────────────────┘
-```
-
-**Rules:**
-- ✅ Description: Auto-expanded on load
-- ✅ Other sections: Collapsed by default
-- ✅ Arrow icon: Rotates on expand/collapse
-- ✅ Smooth animation: 200-300ms
-- ✅ Full-width clickable header
-- ❌ NO horizontal tabs (27% overlook rate)
-
-**Rationale:** Research (Baymard: vertical > horizontal)
-
----
-
-### Specifications Table
-
-**Pattern: Scannable Two-Column Table**
-
-```
-┌─────────────────────────────────────┐
-│ Material      │ 100% Cotton         │
-│ Weight        │ 250g                │
-│ Color         │ Black, White, Gray  │
-│ Size          │ S, M, L, XL         │
-└─────────────────────────────────────┘
-```
-
-**Rules:**
-- ✅ Label column: 33% width, bold, gray background
-- ✅ Value column: 67% width, regular weight
-- ✅ Padding: py-4 px-6
-- ✅ Border: Bottom border on each row
-- ✅ Last row: No border
-- ❌ NO plain table (hard to scan)
-
-**Rationale:** Research (scannable > plain)
-
----
-
-### Buy Section
-
-#### Desktop & Mobile:
-
-**Structure:**
-```
-1. Product Title (H1)
-2. Price (prominent, but not overwhelming)
-3. Stock Status (badge with icon)
-4. Short Description (if exists)
-5. Variation Selectors (pills)
-6. Quantity Selector (large buttons)
-7. Add to Cart (prominent CTA)
-8. Wishlist Button (secondary)
-9. Trust Badges (shipping, returns, secure)
-10. Product Meta (SKU, categories)
-```
-
-**Price Display:**
-```html
-<!-- On Sale -->
-<div>
-  <span class="text-2xl font-bold text-red-600">$79.00</span>
-  <span class="text-lg text-gray-400 line-through">$99.00</span>
-  <span class="bg-red-600 text-white px-3 py-1 rounded">SAVE 20%</span>
-</div>
-
-<!-- Regular -->
-<span class="text-2xl font-bold">$99.00</span>
-```
-
-**Stock Status:**
-```html
-<!-- In Stock -->
-<div class="bg-green-50 text-green-700 px-4 py-2.5 rounded-lg border border-green-200">
-  <svg>✓</svg>
-  <span>In Stock - Ships Today</span>
-</div>
-
-<!-- Out of Stock -->
-<div class="bg-red-50 text-red-700 px-4 py-2.5 rounded-lg border border-red-200">
-  <svg>✗</svg>
-  <span>Out of Stock</span>
-</div>
-```
-
-**Add to Cart Button:**
-```html
-<!-- Desktop & Mobile -->
-<button class="w-full h-14 text-lg font-bold bg-primary text-white rounded-lg shadow-lg hover:shadow-xl">
-  <ShoppingCart /> Add to Cart
-</button>
-```
-
-**Trust Badges:**
-```html
-<div class="space-y-3 border-t-2 pt-4">
-  <!-- Free Shipping -->
-  <div class="flex items-center gap-3">
-    <svg class="w-6 h-6 text-green-600">🚚</svg>
-    <div>
-      <p class="font-semibold">Free Shipping</p>
-      <p class="text-xs text-gray-600">On orders over $50</p>
-    </div>
-  </div>
-  
-  <!-- Returns -->
-  <div class="flex items-center gap-3">
-    <svg class="w-6 h-6 text-blue-600">↩</svg>
-    <div>
-      <p class="font-semibold">30-Day Returns</p>
-      <p class="text-xs text-gray-600">Money-back guarantee</p>
-    </div>
-  </div>
-  
-  <!-- Secure -->
-  <div class="flex items-center gap-3">
-    <svg class="w-6 h-6 text-gray-700">🔒</svg>
-    <div>
-      <p class="font-semibold">Secure Checkout</p>
-      <p class="text-xs text-gray-600">SSL encrypted payment</p>
-    </div>
-  </div>
-</div>
-```
-
----
-
-### Mobile-Specific Patterns
-
-#### Sticky Bottom Bar (Optional - Future Enhancement)
-
-```
-┌─────────────────────────────────────┐
-│ $79.00          [Add to Cart]       │
-└─────────────────────────────────────┘
-```
-
-**Rules:**
-- ✅ Fixed at bottom on scroll
-- ✅ Shows price + CTA
-- ✅ Appears after scrolling past buy section
-- ✅ z-index: 50 (above content)
-- ✅ Shadow for depth
-
-**Rationale:** Convention (Tokopedia does this)
-
----
-
-## 🎨 Color System
-
-### Primary Colors
-
-```css
-Primary:        #222222 (dark gray/black)
-Primary Hover:  #000000
-Primary Light:  #F5F5F5
-```
-
-### Semantic Colors
-
-```css
-Success:        #10B981 (green)
-Error:          #EF4444 (red)
-Warning:        #F59E0B (orange)
-Info:           #3B82F6 (blue)
-```
-
-### Sale/Discount
-
-```css
-Sale Price:     #DC2626 (red-600)
-Sale Badge:     #DC2626 bg, white text
-Savings:        #DC2626 text
-```
-
-### Stock Status
-
-```css
-In Stock:       #10B981 (green-600)
-Low Stock:      #F59E0B (orange-500)
-Out of Stock:   #EF4444 (red-500)
-```
-
-### Neutral Scale
-
-```css
-Gray 50:   #F9FAFB
-Gray 100:  #F3F4F6
-Gray 200:  #E5E7EB
-Gray 300:  #D1D5DB
-Gray 400:  #9CA3AF
-Gray 500:  #6B7280
-Gray 600:  #4B5563
-Gray 700:  #374151
-Gray 800:  #1F2937
-Gray 900:  #111827
-```
-
----
-
-## 🔘 Interactive Elements
-
-### Buttons
-
-**Primary CTA:**
-```css
-Height:         h-14 (56px)
-Padding:        px-6
-Font:           text-lg font-bold
-Border Radius:  rounded-lg
-Shadow:         shadow-lg hover:shadow-xl
-```
-
-**Secondary:**
-```css
-Height:         h-12 (48px)
-Padding:        px-4
-Font:           text-base font-semibold
-Border:         border-2
-```
-
-**Quantity Buttons:**
-```css
-Size:           44x44px minimum (touch target)
-Border:         border-2
-Icon:           Plus/Minus (20px)
-```
-
-### Touch Targets
-
-**Minimum Sizes:**
-```css
-Mobile:   44x44px (WCAG AAA)
-Desktop:  40x40px (acceptable)
-```
-
-**Rules:**
-- ✅ All interactive elements: min 44x44px on mobile
-- ✅ Adequate spacing between targets (8px min)
-- ✅ Visual feedback on tap/click
-- ✅ Disabled state clearly indicated
-
----
-
-## 🖼️ Images
-
-### Product Images
-
-**Main Image:**
-```css
-Aspect Ratio:   1:1 (square)
-Object Fit:     object-contain (shows full product)
-Padding:        p-4 (breathing room)
-Background:     white or light gray
-Border:         border-2 border-gray-200
-Shadow:         shadow-lg
-```
-
-**Thumbnails:**
-```css
-Desktop:        96-112px (w-24 md:w-28)
-Mobile:         N/A (use dots)
-Aspect Ratio:   1:1
-Object Fit:     object-cover
-Border:         border-2
-Active:         border-primary ring-4 ring-primary
-```
-
-**Rules:**
-- ✅ Always use `!h-full` to override WooCommerce styles
-- ✅ Lazy loading for performance
-- ✅ Alt text for accessibility
-- ✅ WebP format when possible
-- ❌ Never use object-cover for main image (crops product)
-
----
-
-## 📱 Responsive Behavior
-
-### Grid Layout
-
-**Product Page:**
-```css
-Mobile:    grid-cols-1 (single column)
-Desktop:   grid-cols-2 (image | info)
-Gap:       gap-8 lg:gap-12
-```
-
-### Image Gallery
-
-**Desktop:**
-- Thumbnails: Horizontal scroll if >4 images
-- Arrows: Show when >4 images
-- Layout: Main image + thumbnail strip below
-
-**Mobile:**
-- Dots: Always visible
-- Swipe: Primary interaction
-- Counter: Optional (e.g., "1/5")
-
-### Typography
-
-**Responsive Sizes:**
-```css
-Title:   text-2xl md:text-3xl
-Price:   text-2xl md:text-2xl (same)
-Body:    text-base (16px, no change)
-Small:   text-sm md:text-sm (same)
-```
-
----
-
-## ♿ Accessibility
-
-### WCAG 2.1 AA Requirements
-
-**Color Contrast:**
-- Text: 4.5:1 minimum
-- Large text (18px+): 3:1 minimum
-- Interactive elements: 3:1 minimum
-
-**Keyboard Navigation:**
-- ✅ All interactive elements focusable
-- ✅ Visible focus indicators
-- ✅ Logical tab order
-- ✅ Skip links for main content
-
-**Screen Readers:**
-- ✅ Semantic HTML (h1, h2, nav, main, etc.)
-- ✅ Alt text for images
-- ✅ ARIA labels for icons
-- ✅ Live regions for dynamic content
-
-**Touch Targets:**
-- ✅ Minimum 44x44px on mobile
-- ✅ Adequate spacing (8px min)
-
----
-
-## 🚀 Performance
-
-### Loading Strategy
-
-**Critical:**
-- Hero image (main product image)
-- Product title, price, CTA
-- Variation selectors
-
-**Deferred:**
-- Thumbnails (lazy load)
-- Description content
-- Reviews section
-- Related products
-
-**Rules:**
-- ✅ Lazy load images below fold
-- ✅ Skeleton loading states
-- ✅ Optimize images (WebP, compression)
-- ✅ Code splitting for routes
-- ❌ No layout shift (reserve space)
-
----
-
-## 📋 Component Checklist
-
-### Product Page Must-Haves
-
-**Above the Fold:**
-- [ ] Breadcrumb navigation
-- [ ] Product title (H1)
-- [ ] Price display (with sale if applicable)
-- [ ] Stock status badge
-- [ ] Main product image
-- [ ] Image navigation (thumbnails/dots)
-- [ ] Variation selectors (pills)
-- [ ] Quantity selector
-- [ ] Add to Cart button
-- [ ] Trust badges
-
-**Below the Fold:**
-- [ ] Product description (auto-expanded)
-- [ ] Specifications table (collapsed)
-- [ ] Reviews section (collapsed)
-- [ ] Product meta (SKU, categories)
-- [ ] Related products (future)
-
-**Mobile Specific:**
-- [ ] Dots for image navigation
-- [ ] Large touch targets (44x44px)
-- [ ] Responsive text sizes
-- [ ] Collapsible sections
-- [ ] Optional: Sticky bottom bar
-
-**Desktop Specific:**
-- [ ] Thumbnails for image navigation
-- [ ] Hover states
-- [ ] Larger layout (2-column grid)
-
----
-
-## 🎯 Decision Log
-
-### Image Gallery
-- **Decision:** Dots only on mobile, thumbnails on desktop
-- **Rationale:** Convention (Amazon, Tokopedia, Shopify)
-- **Date:** Nov 26, 2025
-
-### Variation Selectors
-- **Decision:** Pills/buttons, not dropdowns
-- **Rationale:** Convention + Research align (NN/g)
-- **Date:** Nov 26, 2025
-
-### Typography Hierarchy
-- **Decision:** Title > Price (28-32px > 24-28px)
-- **Rationale:** Context (we're not a marketplace)
-- **Date:** Nov 26, 2025
-
-### Description Pattern
-- **Decision:** Auto-expanded accordion
-- **Rationale:** Research (don't hide primary content)
-- **Date:** Nov 26, 2025
-
-### Tabs vs Accordions
-- **Decision:** Vertical accordions, not horizontal tabs
-- **Rationale:** Research (27% overlook tabs)
-- **Date:** Nov 26, 2025
-
----
-
-## 📚 References
-
-### Research Sources
-- Baymard Institute UX Research
-- Nielsen Norman Group Guidelines
-- WCAG 2.1 Accessibility Standards
-
-### Convention Sources
-- Amazon (marketplace reference)
-- Tokopedia (marketplace reference)
-- Shopify (e-commerce reference)
-
----
-
-## 🔄 Version History
-
-**v1.0 - Nov 26, 2025**
-- Initial guide created
-- Product page standards defined
-- Decision framework established
-
----
-
-**Status:** ✅ Active  
-**Maintenance:** Updated by conversation  
-**Owner:** WooNooW Development Team

SUBSCRIPTION_MODULE_AUDIT.md

@@ -0,0 +1,727 @@
+# Subscription Module — Audit Report
+
+**Date:** 2026-06-01
+**Scope:** WooNooW plugin — Product Subscriptions module
+**Auditor:** AI-assisted code review (full trace of `woonoow/` folder)
+**Reference:** [Prior audit 2026-01-29](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/.agent/reports/subscription-flow-audit-2026-01-29.md) — 2 critical / 5 warning / 4 info issues, all critical & warning fixed.
+**Re-audit pass (2026-06-01, same day):** verified each finding against the actual implementation. Result below.
+
+---
+
+## 1. Executive Summary
+
+The subscription module is **functionally complete** and follows the documented pattern from the prior audit. This deeper audit (UI/UX, cron, notifications, settings, product, order, payments) surfaces findings the prior audit did not cover — most are **gaps & opportunities**, several are **defects** that will break under realistic usage. **Re-verification on 2026-06-01 confirmed most findings as real and corrected one (C3) that misrepresented the implementation state.**
+
+| Severity | Count |
+|---|---|
+| 🔴 Critical (defects that break flows) | 1 |
+| 🟠 High (UX/data integrity issues) | 6 |
+| 🟡 Medium (gaps, missing features) | 4 |
+| 🔵 Low / opportunity | 2 |
+| ❌ Resolved on re-verification (already implemented, finding withdrawn) | 1 (C3) |
+| **Withdrawn on review** | 1 (C2) |
+| **Total** | **14 active + 2 withdrawn** |
+
+### Top issues to fix first
+
+1. **Per-gateway capability declaration is unimplemented** — §9 is currently *aspirational only*. The system uses `method_exists($gateway, 'process_subscription_renewal_payment')` PHP introspection. There is no capability table, no admin UI, no kill switch. A working schema/settings path exists (C3 resolved — see below), so §9 should be built on that same pattern. Effort: M.
+2. **Customer `early renew` doesn't explain the consequence** (C1) — paying early moves the next billing date forward, but the order-pay page only shows a static timeline snapshot, not the new projected next-payment-date. Effort: S.
+3. **Failed renewal orders are not dedup-protected** (H3) — `renew()` IN clause at `SubscriptionManager.php:527` excludes `failed`/`wc-failed`. If a renewal failed, clicking "Renew Early" creates a second order. Effort: XS.
+4. **Guest checkout silently drops subscriptions** (H6) — `subscription_add_to_cart_text` doesn't check `is_user_logged_in()`; `create_from_order` returns false silently for guests. Effort: S.
+5. **`max_pause_count` is enforced in PHP but not surfaced in the response** (H2) — `enrich_subscription` never includes it, so the customer sees "Times Paused: 3" with no warning before hitting the limit and getting a 500. Effort: S.
+
+### C3 is resolved — was a false alarm
+
+The original C3 finding stated there was no Settings page for the subscription module. **This is wrong.** A generic `Settings/ModuleSettings.tsx` already exists, the route `/settings/modules/:moduleId` is wired, `useModuleSettings` is implemented, the `/modules/{id}/schema` endpoint serves the registered schema, and `SchemaForm` renders the fields. `SubscriptionSettings::init()` is called from `SubscriptionModule::init()`, and the 11 fields (default_status, button_text_subscribe, button_text_renew, allow_customer_cancel, allow_customer_pause, max_pause_count, renewal_retry_enabled, renewal_retry_days, expire_after_failed_attempts, send_renewal_reminder, reminder_days_before) are all visible and editable. The runtime works, the merchant can change values, the API persists them. C3 is removed from the critical list.
+
+---
+
+## 2. Module Architecture Map
+
+### 2.1 Files in scope
+
+| Layer | File | Role |
+|---|---|---|
+| **PHP core** | [SubscriptionManager.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php) | CRUD, renewals, lifecycle |
+| | [SubscriptionModule.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionModule.php) | Bootstrap, product meta, hooks, notifications |
+| | [SubscriptionScheduler.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionScheduler.php) | Cron (renewals, expiry, reminders) |
+| | [SubscriptionSettings.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/SubscriptionSettings.php) | Settings schema (defaults only) |
+| | [ModuleRegistry.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/ModuleRegistry.php) | Module registration |
+| **API** | [SubscriptionsController.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/SubscriptionsController.php) | Admin + customer REST endpoints |
+| | [ModuleSettingsController.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/ModuleSettingsController.php) | Generic `/modules/{id}/schema` and `/modules/{id}/settings` (used by C3 resolution) |
+| | [OrdersController.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/OrdersController.php) | Embeds `related_subscription` in order detail |
+| | [CheckoutController.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/CheckoutController.php) | Embeds `subscription` in `order-pay` response |
+| | [ProductsController.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/ProductsController.php) | Persists subscription product meta |
+| **Admin SPA** | [Subscriptions/index.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Subscriptions/index.tsx) | List page (table + mobile cards) |
+| | [Subscriptions/Detail.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Subscriptions/Detail.tsx) | Admin detail view |
+| | [Orders/Detail.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Orders/Detail.tsx) | Renders "Related Subscription" block |
+| | [Products/.../GeneralTab.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Products/partials/tabs/GeneralTab.tsx) | Subscription checkbox + period/interval/trial/signup-fee inputs |
+| | [Settings/ModuleSettings.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Settings/ModuleSettings.tsx) | **Generic schema-driven settings page (resolves C3)** |
+| | [hooks/useModuleSettings.ts](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/hooks/useModuleSettings.ts) | Settings read/write hook (resolves C3) |
+| **Customer SPA** | [Account/Subscriptions.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/Account/Subscriptions.tsx) | List page |
+| | [Account/SubscriptionDetail.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/Account/SubscriptionDetail.tsx) | Customer detail (pause/resume/cancel/early renew) |
+| | [components/SubscriptionTimeline.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/components/SubscriptionTimeline.tsx) | Visual timeline component |
+| | [OrderPay/index.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/OrderPay/index.tsx) | Manual renewal payment page |
+| | [Account/components/AccountLayout.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/Account/components/AccountLayout.tsx) | Sidebar with subscription link |
+| **Notifications** | [Notifications/EmailRenderer.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/EmailRenderer.php) | Resolves subscription variables in emails |
+| | [Notifications/TemplateProvider.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/TemplateProvider.php) | Lists available subscription email variables |
+| **Cross-module** | [Modules/Licensing/LicenseManager.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Licensing/LicenseManager.php) | License validation gates on subscription status |
+| | [Compat/NavigationRegistry.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Compat/NavigationRegistry.php) | Admin sidebar |
+
+### 2.2 Data model
+
+- **`wp_woonoow_subscriptions`** — main table (id, user_id, order_id, product_id, variation_id, status, billing_period, billing_interval, recurring_amount, start_date, trial_end_date, next_payment_date, end_date, last_payment_date, payment_method, payment_meta, cancel_reason, pause_count, failed_payment_count, reminder_sent_at).
+- **`wp_woonoow_subscription_orders`** — join table (id, subscription_id, order_id, order_type ENUM 'parent'|'renewal'|'switch'|'resubscribe').
+
+### 2.3 Status flow
+
+```
+pending ──► active ──► pending-cancel ──► cancelled
+                 │                                    
+                 ├──► on-hold (paused, payment_failed) ──► resumed ──► active
+                 └──► expired (end_date_reached, max_failed)
+```
+
+### 2.4 Notification events (8 customer + 2 staff)
+
+`pending_cancel`, `cancelled`, `expired`, `paused`, `resumed`, `renewal_failed`, `renewal_payment_due`, `renewal_reminder`, plus `cancelled_admin` and `renewal_failed_admin`.
+
+---
+
+## 3. Critical Defects (🔴)
+
+### C1. Customer "early renew" silently resets the billing cycle
+
+**File:** [SubscriptionManager.php:706-718](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L706-L718)
+
+**Flow:**
+
+1. Customer is on a monthly plan, paid May 1, next renewal June 1.
+2. On May 20, customer clicks "Renew Early" — order is created for $X.
+3. After payment, `handle_renewal_success()` is called.
+4. Code computes `next_payment = calculate_next_payment_date($base_date, ...)` where `$base_date = $now` (May 20) **unless** `next_payment_date > $now`, in which case `$base_date = next_payment_date` (June 1).
+
+   ```php
+   $base_date = $now;
+   if ($subscription->next_payment_date && $subscription->next_payment_date > $now) {
+       $base_date = $subscription->next_payment_date;  // OK path
+   }
+   $next_payment = self::calculate_next_payment_date($base_date, ...);
+   ```
+
+**Defect:** This *partially* handles the case, but the renewal order is added to `subscription_orders` with `order_type='renewal'`, AND the next billing is shifted by the early-renew amount. Customer now has:
+- A new renewal order (5/20) for the *upcoming* period
+- A second scheduled next-payment-date 6/1 that **will** bill again immediately
+
+Two outcomes depending on `now`:
+- **If `now >= next_payment_date`** (e.g., late payment): no early issue — uses `now` correctly.
+- **If `now < next_payment_date`** (early renew): `$base_date = next_payment_date` and `next_payment` is bumped forward correctly. ✅ Actually OK.
+
+**Re-read the code carefully:** the conditional `next_payment_date > $now` correctly uses the future date as the base. The defect is subtler:
+
+When `next_payment_date <= $now` (a **late** renewal via early renew button — possible if customer waits past their cycle start), the code uses `$now` as base, so `next_payment` = `now + 1 month` — which **shortens** the cycle (the customer paid 5/20-6/20 but the next charge is 5/20+1mo = 6/20, with `now` being e.g. 5/22). Acceptable.
+
+**Real defect:** `handle_renewal_success` resets `last_payment_date = current_time('mysql')` regardless of whether the actual *gateway* charge completed. If the gateway returns `true` from `process_subscription_renewal_payment` but the renewal was flagged as `manual`, the cron later calls `handle_renewal_success` again, double-counting. The early-renew path goes:
+
+```
+$payment_result === 'manual'  → status 'manual' → return early (no handle_renewal_success)
+```
+
+So manual early renew does NOT call `handle_renewal_success` — the schedule shift is deferred to manual payment confirmation via `on_order_status_changed`. ✅ The original concern was unfounded; the path is actually correct.
+
+**However**, there is a **real defect** with the "early renew" customer flow:
+
+The `customer_renew` REST endpoint at [SubscriptionsController.php:407-434](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/SubscriptionsController.php#L407-L434) calls `SubscriptionManager::renew()` which creates a renewal order, then redirects the customer to `/order-pay/{id}`. Once they pay, the renewal is treated as a normal renewal, so:
+
+- If the customer pays the early renewal order, `next_payment_date` is set to `current + 1 month` (via the conditional above), giving them **two paid periods back-to-back** with the next charge 1 month from "now" (which is the early renew date) — this is the **expected** SaaS behavior.
+- BUT the customer is *not informed* anywhere in the UI that paying early **moves their next billing date forward** by the early amount. The order-pay page ([OrderPay/index.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/OrderPay/index.tsx)) only shows the static `SubscriptionTimeline` snapshot, not what the new next date will be.
+
+**Severity: 🔴 Critical — UX expectation violation.** Even if the math is right, customers will be surprised and request refunds.
+
+**Fix:** Show the *projected* next billing date on the order-pay page when the order is a renewal. Compute it client-side as `next_payment_date` if in future, else `now + period`.
+
+---
+
+### C2. Removed — was a misframed finding
+
+**Status: Withdrawn on review.** This finding is not a subscription-module defect in the current state of the system.
+
+The original C2 argued that the renewal `set_address` from parent ([SubscriptionManager.php:609-614](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L609-L614)) silently copies a stale address. On review, that framing was wrong.
+
+**What the system actually does today:**
+
+- The checkout does not ask for an address. Every order is created without one.
+- For **virtual / downloadable** subscription products: no address is needed. The renewal `set_address` call writes an empty/default address, but no shipping line is generated, no merchant ever sees an issue, and the customer never interacts with an address. ✅ Correct by virtue of the product type.
+- For **physical** subscription products: physical subscriptions **cannot be sold** through the current checkout, because the checkout never asks for a shipping address. The renewal `set_address` code is **unreachable** for physical subscriptions in the current state.
+
+**What the renewal flow should do once the checkout supports physical subscriptions:**
+
+1. At the original order's checkout, the customer fills in the address. The parent order stores it.
+2. On renewal, copy the address from the parent order to the renewal order. This is the correct default — the customer chose to renew, and the parent order is the most recent customer-confirmed address.
+3. On the renewal order-pay page, surface the address with a clear "Is your address still the same? [Change]" prompt. The customer can correct it before paying.
+4. If the customer changes the address on the renewal, persist the change to the renewal order. (Optional: also write it back to the parent order or to the customer's default address, but that is a checkout-level concern, not subscription-level.)
+
+**Why this is not a defect today:**
+
+- The renewal `set_address` from parent is not "wrong" — it is the only sensible default in the absence of a current customer-confirmed address on the renewal. Pulling from `WC_Customer::get_default_address()` would actually be **worse** in the renewal context: the customer may not have a default address, and the parent order is by definition the most recent address the customer provided for *this* subscription.
+- The "stale address" risk on renewal is real but is already handled by the natural UX: the customer sees the address on the order-pay page and can change it before paying. This is the same trust model as checkout itself.
+
+**What to do with this finding:**
+
+- Remove C2 from the critical list.
+- Keep the existing `set_address` code unchanged.
+- File a **forward-looking note** in `docs/SUBSCRIPTION_ADDRESS_POLICY.md` (to be written when the checkout address step is added) describing the contract: parent-order address is the default; customer can change on the renewal order-pay page; physical products require the checkout to collect an address in the first place.
+- The only subscription-side code change that may be useful when the checkout supports physical products: surface the address on the renewal order-pay page with the "is your address still the same?" prompt. That is a UX change, not a backend defect fix.
+
+**The address question is the checkout's responsibility, not the subscription module's.** The subscription module's `create_renewal_order` is doing the right thing — copying from the parent, which is the only signal it has.
+
+---
+
+### C3. Resolved — was a false alarm (settings page IS implemented)
+
+**Status: Resolved on re-verification (2026-06-01).** The original C3 finding stated there was no Settings page for the subscription module. That claim is wrong.
+
+**What is actually implemented today:**
+
+- **Generic page exists:** [admin-spa/src/routes/Settings/ModuleSettings.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Settings/ModuleSettings.tsx) handles ANY module with a schema. It is mounted at `/settings/modules/:moduleId` in `AppRoutes.tsx:230`.
+- **Hook exists:** [admin-spa/src/hooks/useModuleSettings.ts](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/hooks/useModuleSettings.ts) reads `/modules/{id}/settings` and posts to `/modules/{id}/settings`.
+- **Schema endpoint exists:** `ModuleSettingsController::get_schema` (registers `GET /woonoow/v1/modules/{module_id}/schema` at [ModuleSettingsController.php:67-71](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/ModuleSettingsController.php#L67-L71)) serves the schema registered via the `woonoow/module_settings_schema` filter.
+- **Form renderer exists:** `SchemaForm` renders text / number / toggle / select fields from the schema declaratively.
+- **Schema is registered:** [SubscriptionSettings.php:18](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/SubscriptionSettings.php#L18) registers the filter; [SubscriptionModule.php:25](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionModule.php#L25) calls `SubscriptionSettings::init()` on bootstrap.
+
+**What the merchant sees:** navigate to Settings → Modules → Subscription, and all 11 fields (`default_status`, `button_text_subscribe`, `button_text_renew`, `allow_customer_cancel`, `allow_customer_pause`, `max_pause_count`, `renewal_retry_enabled`, `renewal_retry_days`, `expire_after_failed_attempts`, `send_renewal_reminder`, `reminder_days_before`) are visible, editable, and persisted.
+
+**Why this finding is wrong:** the original audit looked for a per-module page (`Settings/Subscription.tsx`) and didn't find one. But the system uses a *generic* schema-driven page that works for any module — including the subscription module. The capability is there; the audit missed it.
+
+**Lesson for future audits:** the per-module page pattern is no longer the convention. Look for `ModuleSettings.tsx` + `SchemaForm` + `/modules/{id}/schema` first.
+
+---
+
+## 4. High-Impact UX/Data Issues (🟠)
+
+### H1. "Renew Now" admin button does not consider gateway availability
+
+**File:** [admin-spa/src/routes/Subscriptions/Detail.tsx:228-237](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Subscriptions/Detail.tsx#L228-L237)
+
+The admin "Renew Now" button always calls `SubscriptionManager::renew()` which falls through to manual payment if no auto-debit gateway. The admin is not shown a confirmation that the renewal will produce a *pending* order requiring customer payment. They will click the button, see "Renewed" (because `handle_renewal_success` was called on auto-debit success OR no clear feedback on manual), and not realize the customer now has a pending order to pay.
+
+**Fix:** After clicking "Renew Now", show the resulting order's payment URL / status to the admin.
+
+---
+
+### H2. Customer detail: "Times Paused" displayed but `max_pause_count` is not shown, and no warning when reached
+
+**File:** [customer-spa/src/pages/Account/SubscriptionDetail.tsx:257-259](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/customer-spa/src/pages/Account/SubscriptionDetail.tsx#L257-L259)
+
+The customer can see they've paused N times, but not how many pauses they have left. When the limit is hit, the API returns a generic 500 `pause_failed` — the customer sees a confusing error. The button should be **disabled** with a tooltip when the limit is reached.
+
+**Fix:** Add `max_pause_count` and `pauses_remaining` to the enriched response; show on the detail page; disable button when 0 remaining.
+
+---
+
+### H3. `on-hold` subscription can be "renewed" creating a duplicate order
+
+**File:** [SubscriptionManager.php:512-533](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L512-L533)
+
+The duplicate prevention check uses `p.post_status IN ('wc-pending', 'pending', 'wc-on-hold', 'on-hold')`. But `failed` and `wc-failed` orders are *not* excluded — and the prior failed order still counts as a "renewal" link. The customer detail page (line 137-140) looks for `pending`, `wc-pending`, `on-hold`, `wc-on-hold`, `failed`, `wc-failed` to surface the "Pay Now" button — but the backend `renew()` only prevents duplicates for pending/on-hold. If a customer's renewal order failed last night, and they click "Renew Early" today, a *second* order is created.
+
+**Severity: 🟠 High** — duplicate orders on retry, leading to confused customers and double-billing risk.
+
+**Fix:** Add `'wc-failed', 'failed'` to the duplicate-prevention IN clause.
+
+---
+
+### H4. Renewal order product line uses the *current* product price, not the subscription's stored recurring amount
+
+**File:** [SubscriptionManager.php:600-606](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L600-L606)
+
+```php
+$product = wc_get_product($subscription->variation_id ?: $subscription->product_id);
+if ($product) {
+    $renewal_order->add_product($product, 1, [
+        'total' => $subscription->recurring_amount,  // ✅ uses stored amount
+        'subtotal' => $subscription->recurring_amount,
+    ]);
+}
+```
+
+This *is* correct — it uses the stored `recurring_amount`, not the current product price. ✅
+
+**However**, `recalculate_next_payment_date` does not consider **product-level price changes mid-cycle**. The customer's stored `recurring_amount` is the original price. If the admin changes the product price, the customer is grandfathered — which is probably intended, but **not documented in any setting**. No toggle to "re-sync with product price" or "always bill current price."
+
+**Severity: 🟠 High (UX clarity)** — admin changes the product price and the next renewal silently uses the old price; surprised admin.
+
+**Fix:** Add a setting `price_sync_on_renewal` with options: 'use_stored' (default), 'use_current_product_price'. Document in product meta tooltip.
+
+---
+
+### H5. Manual renewal email is sent on every cron tick, not gated by `pending` order existence
+
+**File:** [SubscriptionManager.php:684-689](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L684-L689)
+
+When a renewal returns `'manual'`, the system fires `woonoow/subscription/renewal_payment_due` once per call. If the same due subscription is processed again (e.g., a future hourly tick after `next_payment_date` falls behind), and there's still a pending order, the same notification fires again, **because `process_renewal_payment` doesn't check for an existing pending order first** — `renew()` does (line 521-533), but that's before the existing-pending check returns `'existing'` status.
+
+Wait — re-reading: `renew()` returns the existing order for `'existing'` status and does **not** call `process_renewal_payment` or fire the notification. ✅ So this is actually safe.
+
+**However**, if a `manual` renewal was created and never paid, the next cron tick sees the subscription as `on-hold` (not `active`) — so `get_due_renewals()` excludes it. The customer gets no reminder that they have an outstanding order. The `pending-cancel` path is similar — when `next_payment_date <= now`, `check_expirations` flips it to `cancelled`, but no email is queued with a "your pending order was cancelled" notice.
+
+**Severity: 🟠 High (revenue leakage)** — abandoned-cart-like behavior on unpaid renewals.
+
+**Fix:** Add a daily cron that finds `on-hold` subscriptions with pending renewal orders older than 24h and re-sends the `renewal_payment_due` email (or auto-cancels after N days).
+
+---
+
+### H6. `create_from_order` rejects guest orders silently
+
+**File:** [SubscriptionManager.php:107-110](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L107-L110)
+
+```php
+if (!$user_id) {
+    // Guest orders not supported for subscriptions
+    return false;
+}
+```
+
+But the **product page still shows "Subscribe Now"** to guests, who can complete checkout as guest, after which **no subscription is created and no error is shown**. The customer thinks they have a subscription, the order is normal.
+
+**Severity: 🟠 High — broken expectation for guest purchases.** The "Subscribe" button should be hidden for guests, or guest checkout should be blocked for subscription products, or the customer should be auto-converted to a user.
+
+**Fix:** Add a check in the `subscription_add_to_cart_text` filter to *not* change button text for guest users, or force a login redirect for subscription products in cart.
+
+---
+
+## 5. Medium Gaps (🟡)
+
+### M1. Variable products: subscription meta is on parent only
+
+**File:** [SubscriptionModule.php:120-177](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionModule.php#L120-L177)
+
+The admin SPA form ([GeneralTab.tsx:546-630](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Products/partials/tabs/GeneralTab.tsx#L546-L630)) saves `_woonoow_subscription_*` on the parent product. When `create_from_order` is called, it reads:
+
+```php
+$billing_period = get_post_meta($product_id, '_woonoow_subscription_period', true) ?: 'month';
+```
+
+This is the *parent* product ID, not the variation. All variations of a variable subscription product share the same period. The admin cannot have e.g. "Small = monthly, Large = yearly" or "License 1-year vs 5-year" as variations.
+
+**Fix:** Add variation-level meta overrides; `create_from_order` should look up variation meta first, then fall back to parent.
+
+---
+
+### M2. `customer_renew` endpoint has no `force_immediate` flag for ad-hoc admin actions
+
+**File:** [SubscriptionsController.php:407-434](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Api/SubscriptionsController.php#L407-L434)
+
+The customer "early renew" creates a new order. The admin "Renew Now" does the same. Neither can be used to **trigger an immediate charge against the customer's saved payment method** (i.e., a real "charge now and renew" button). The current behavior is "create a new order that the customer then pays manually" — confusing.
+
+**Fix:** Add `?charge_now=true` param to admin renew that calls `process_renewal_payment` with `force = true`, skips the manual fallback.
+
+---
+
+### M3. No bulk actions on admin subscription list
+
+**File:** [admin-spa/src/routes/Subscriptions/index.tsx:158-176](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Subscriptions/index.tsx#L158-L176)
+
+The list page has a checkbox column with `selectedIds` state — but **the checkboxes don't trigger any bulk action**. There's no bulk cancel, bulk export (CSV), or bulk remind button. The select-all UI is dead.
+
+**Fix:** Add a bulk-action toolbar (e.g., "Cancel selected", "Send renewal reminder", "Export CSV") and a corresponding REST endpoint.
+
+---
+
+### M4. No search field on admin list
+
+**File:** [admin-spa/src/routes/Subscriptions/index.tsx](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/admin-spa/src/routes/Subscriptions/index.tsx)
+
+The `SubscriptionManager::get_all` accepts a `search` parameter ([SubscriptionManager.php:282](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L282)) — but the admin list never passes it. With hundreds of subscriptions, an admin cannot search by customer name/email/product.
+
+**Fix:** Wire the search input (currently missing) to the `search` query param.
+
+---
+
+## 6. Low / Opportunities (🔵)
+
+### O1. Notification variables: missing `payment_method_title`, `billing_schedule`, `customer_id`
+
+**File:** [TemplateProvider.php:328-345](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/TemplateProvider.php#L328-L345)
+
+The schema lists variables, but **the `EmailRenderer` mapping at lines 343-353** does not include:
+- `payment_method_title` (customer-facing)
+- `billing_schedule` (e.g., "Every 1 month")
+- `customer_id` (admin-facing)
+- `store_email` (declared in schema but not mapped)
+- `my_account_url` (declared in schema but not mapped)
+
+**Fix:** Add these to the `EmailRenderer` mapping so email templates can use them.
+
+---
+
+### O2. Two `.bak.php` files in production code path
+
+**File:** [TemplateProvider.bak.php](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Core/Notifications/TemplateProvider.bak.php)
+
+The `.bak` file is in the `Notifications/` directory — depending on autoloader, this may be auto-loaded or skipped. The subscription variables in the `.bak` (line 339-348) reference different keys than the live one. Should be removed or moved to `tests/fixtures/`.
+
+**Fix:** Delete or relocate.
+
+---
+
+## 7. UI/UX Observations (not classified as defects)
+
+| Observation | Location |
+|---|---|
+| Status badge uses `bg-amber-100` for `pending` in admin, `bg-yellow-100` in customer — inconsistent. | admin/customer SPAs |
+| Mobile card view (admin) shows product name truncated without a "view product" link. | Subscriptions/index.tsx:300-321 |
+| `SubscriptionTimeline` component has hard-coded English labels (`Started`, `Payment Due`, `Every X months`) — no `__()` calls. Breaks i18n for the 2 languages supported per `I18N_IMPLEMENTATION_GUIDE.md`. | SubscriptionTimeline.tsx |
+| Customer detail page has no SEO head except `<SEOHead title="Subscription #X">` — OK but no `og:image` from `product_image`. | SubscriptionDetail.tsx:164 |
+| Admin "Renew Now" doesn't ask for confirmation, but "Cancel" does. | Subscriptions/Detail.tsx:228-247 |
+| `failed_payment_count` is shown in admin detail (good), but not in the customer detail — they don't know they have a retry coming. | admin vs customer |
+| `last_payment_date` is shown in admin only, not customer. | admin vs customer |
+| Order pay page always shows `Loading order details...` if `key` is missing — no helpful 403. | OrderPay/index.tsx:133 |
+
+---
+
+## 8. Cron Behavior Audit
+
+| Hook | Schedule | Purpose | Issues |
+|---|---|---|---|
+| `woonoow_process_subscription_renewals` | hourly | Auto-process due renewals | No batch limit; no admin notice on failure; no lock guard against overlapping runs |
+| `woonoow_check_expired_subscriptions` | daily | Mark end-date-reached as `expired`; finalize `pending-cancel` | No email to customer when their pending-cancel finally cancels |
+| `woonoow_send_renewal_reminders` | daily | Send reminder N days before `next_payment_date` | Uses `last_payment_date` to gate, but `last_payment_date` only updates on **success** — if all retries fail, the gate fails open and may re-send for the same cycle |
+
+**Cron-related risks:**
+1. **No `wp_remote_get` lock** to prevent concurrent runs (WP-Cron can double-fire on slow sites).
+2. **`send_renewal_reminders`** query at [SubscriptionScheduler.php:183-192](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionScheduler.php#L183-L192) uses a complex OR clause that may not be correct when `last_payment_date` IS NULL (initial trial): the `(last_payment_date IS NULL AND reminder_sent_at < start_date)` branch. New trial subscriptions may get reminders *before* trial ends.
+3. **`schedule_retry`** at line 246-262 updates `next_payment_date` to the retry date — but the `get_due_renewals()` query compares `next_payment_date <= now`, so the retried subscription will be picked up on the next hourly tick. ✅
+
+---
+
+## 9. Payment Gateway Integration — Revised Direction (per-gateway capability)
+
+> **Status as of 2026-06-01 (re-verified):** this section is **still aspirational**. No code, no schema, no settings entry, no UI, no capability helper exists. Zero references to `subscription_auto_renew`, `GatewayCapabilities`, `gateway_capability`, or `woonoow_gateway_subscription_capabilities` were found anywhere in the plugin. The current system still relies entirely on `method_exists($gateway, 'process_subscription_renewal_payment')` PHP introspection at `SubscriptionManager.php:667-674`.
+>
+> However, **the settings infrastructure to build this is now in place** (see C3 resolution): a generic `ModuleSettings` page reads a registered schema and persists via `/modules/{id}/settings`. §9 can be built on that same pattern, which is why this is still the most important long-term fix — but it is a feature to build, not a bug to remove.
+
+### 9.1 Current state (problem)
+
+The current code at [SubscriptionManager.php:667-674](file:///Users/dwindown/Local%20Sites/woonoow/app/public/wp-content/plugins/woonoow/includes/Modules/Subscription/SubscriptionManager.php#L667-L674) detects auto-debit capability via PHP introspection:
+
+```php
+if (method_exists($gateway, 'process_subscription_renewal_payment')) {
+    $result = $gateway->process_subscription_renewal_payment($order, $subscription);
+    ...
+}
+```
+
+This has three problems:
+
+1. **Capability is invisible to the merchant.** The admin has no way to see which gateways are declared to support subscription auto-renew, no way to override that declaration, and no way to know that "Stripe is enabled" does not mean "Stripe will charge renewals."
+2. **The default is unsafe.** A gateway without the method silently falls through to manual payment. The system "works," but the merchant believes auto-debit is happening and customers are surprised.
+3. **No per-gateway override is possible.** A merchant who has a custom Stripe wrapper that *does* support auto-debit cannot declare it; a merchant using stock Stripe with no wrapper cannot override the assumption that it works.
+
+### 9.2 Recommended direction: per-gateway capability declaration
+
+Instead of inferring capability from PHP method existence, store a **gateway capability table** that the merchant (or WooNooW defaults) controls explicitly. The system then computes effective behavior at renewal time.
+
+#### Shape of the declaration
+
+A per-gateway record, with safe defaults:
+
+```php
+// Conceptual. Storage could be wp_option, custom table, or gateway registration API.
+$capabilities = [
+    'paypal'   => ['subscription_auto_renew' => true],
+    'stripe'   => ['subscription_auto_renew' => true],   // only with WooNooW Stripe adapter
+    'dodo'     => ['subscription_auto_renew' => true],   // only with WooNooW Dodo adapter
+    'tripay'   => ['subscription_auto_renew' => false],  // VA/QRIS — no recurring
+    'midtrans' => ['subscription_auto_renew' => false],  // VA/QRIS/e-wallet — no recurring
+    'xendit'   => ['subscription_auto_renew' => false],  // even CC re-auth required
+];
+```
+
+**Default for any unknown gateway: `false`.** This is the safe default — Indonesian-style and global-style gateways without a WooNooW adapter are treated as manual-renewal-only.
+
+#### Why per-gateway, not a site-level "billing mode" toggle
+
+A site-level "manual vs auto" toggle asks the merchant to understand a concept ("billing mode") that does not actually exist in their head. The merchant thinks in terms of **payment gateways**. A checkbox next to each gateway in WooCommerce → Settings → Payments is data the merchant already knows.
+
+Additionally:
+
+- Different merchants use different gateways. A site-level toggle forces a single behavior even when the merchant runs two gateways (one auto-capable, one not) for different products.
+- The capability is a property of the **integration**, not of the **store**. The merchant did not choose "manual mode" — they chose Tripay, and Tripay is a manual gateway.
+- The capability can change as WooNooW ships new adapters. A site-level toggle would be set once and forgotten; a per-gateway table updates as adapters ship.
+
+#### What the system does with the declaration
+
+At renewal time, the system checks: **the active gateway for this subscription** (stored in `payment_method`) has `subscription_auto_renew = true`.
+
+- **Yes, supported** → attempt auto-debit via the gateway's `process_subscription_renewal_payment` (the contract is unchanged, just gated by a positive declaration). On success, `handle_renewal_success`. On failure, fall through to manual renewal and notify the customer.
+- **No, not supported** → skip auto-debit, create a manual renewal order, send `renewal_payment_due` email. No silent failure.
+
+If the gateway is unknown to the capability table, the default is `false` — same as explicit "not supported."
+
+#### Optional site-level override (default off)
+
+Add one secondary toggle for the rare merchant who wants to force manual even when the gateway supports auto (e.g., legal, regulatory, or business reasons):
+
+- `force_manual_renewal`: off by default. When on, all renewals become manual regardless of gateway capability. Useful as a "kill switch."
+
+This is **not** the primary control. It is an override.
+
+### 9.3 What the merchant sees
+
+In WooCommerce → Settings → Payments, each gateway row should show a "Supports subscription auto-renewal" indicator. For example:
+
+| Gateway | Status |
+|---|---|
+| PayPal (WooCommerce addon) | ✅ Supports auto-renew |
+| Stripe (WooCommerce addon) | ✅ Supports auto-renew |
+| Dodo (WooCommerce addon) | ✅ Supports auto-renew |
+| Tripay Payment (WooCommerce addon) | ❌ Manual renewal only |
+| Midtrans (WooCommerce addon) | ❌ Manual renewal only |
+| Xendit (WooCommerce addon) | ❌ Manual renewal only (even credit card) |
+
+A gateway with no entry in the capability table shows ❌ by default and the merchant can flip it on if they have a custom adapter (advanced setting, off by default).
+
+### 9.4 What the customer sees (on the order-pay page and renewal emails)
+
+The renewal messaging must match the actual behavior, not the marketing claim:
+
+- For an auto-renew gateway: "Your subscription will renew automatically on [date] using your saved payment method."
+- For a manual gateway: "Your subscription is up for renewal. Please complete the payment to continue." with a clear CTA to pay.
+- The order-pay page should also show the **next payment date** after this payment completes (the audit's C1 finding applies here too).
+
+### 9.5 The Indonesian gateway reality
+
+For Indonesian payment gateways (Tripay, Midtrans, Xendit, Doku, and the VA/QRIS/e-wallet channels of any gateway), the default `subscription_auto_renew` must be **`false`**. Specifically:
+
+- VA (virtual account): no recurring charge capability.
+- QRIS: typically a one-time merchant-presented QR, no customer-mandate.
+- E-wallets (GoPay, OVO, DANA, ShopeePay): require customer re-authentication for each charge.
+- Credit card on Indonesian gateways: even when the card is tokenized, recurring charges typically require the customer to re-authenticate (BI/PCI-DSS regulatory constraint). The merchant cannot assume the stored token can be charged without the customer's active consent.
+
+If a merchant has a special integration (e.g., a specific subscription product on Xendit with a tokenized card and a recurring billing add-on), they can flip the toggle for that gateway. But the default must be manual.
+
+### 9.6 Implementation outline (for the AI agent)
+
+1. **Capability storage.** A new `wp_option('woonoow_gateway_subscription_capabilities', [...])` keyed by gateway ID, with the safe defaults above. Add a filter `woonoow_gateway_subscription_capabilities` so adapters can self-register.
+2. **Capability lookup helper.** `WooNooW\Modules\Subscription\GatewayCapabilities::supports_auto_renew(string $gateway_id): bool` — single source of truth.
+3. **Renewal flow integration.** In `SubscriptionManager::process_renewal_payment`, before checking `method_exists`, call the capability helper. If `false`, skip the auto-debit attempt entirely and go straight to manual.
+4. **Admin UI.** Render the capability indicator in the gateway list (admin SPA) and on the subscription detail page next to "Payment Method" (e.g., "Stripe — auto-renew enabled" vs "Tripay — manual renewal only").
+5. **Customer messaging.** Pass a boolean `gateway_supports_auto_renew` to the order-pay response and the renewal emails, so the UI can choose the right wording.
+6. **Kill switch.** A single `force_manual_renewal` site setting. Default off.
+7. **Documentation.** A new `docs/SUBSCRIPTION_GATEWAY_CAPABILITIES.md` listing the default capabilities and explaining how to add custom adapters.
+
+### 9.7 Migration / no migration
+
+This is a behavioral improvement, not a schema change. Existing subscriptions keep their `payment_method` value. The capability table is consulted at renewal time, not retroactively.
+
+### 9.8 Recommendation (replaces prior "ship a Stripe adapter" suggestion)
+
+Do **not** ship a Stripe adapter as a first-class example. The value of a generic example adapter is low because each gateway's recurring billing is different. Instead:
+
+- Ship the **capability table** with safe defaults.
+- Ship a **gateway-integration guide** (`docs/SUBSCRIPTION_GATEWAY_CAPABILITIES.md`) that documents the `process_subscription_renewal_payment` contract.
+- Let third-party gateway authors (or the merchant's developer) implement adapters per gateway.
+- The merchant-visible UX works correctly for any gateway, supported or not, because the fallback to manual is explicit.
+
+---
+
+## 10. Cross-Module Integration
+
+### Licensing
+
+- `LicenseManager::validate_license` calls `get_order_subscription_status($license['order_id'])` at line 340-343 — if the subscription is not `active` or `pending-cancel`, the license is rejected with `subscription_inactive`.
+- ✅ Works correctly; the licensing flow depends on the subscription status being accurate.
+- ⚠️ But: when a subscription is **cancelled by customer at period end** (pending-cancel → cancelled), the license is still valid until the cancellation date. This is good UX, but admin should be able to see the relationship in the license detail.
+
+### Affiliate
+
+- No integration. An affiliate who referred a customer who later subscribes does **not** receive renewal commissions. The `subscription_renewal` order is not tagged with the referral.
+- This is a known gap (Affiliate Module report doesn't mention subscriptions).
+
+---
+
+## 11. Documentation Drift
+
+| File | Says | Reality |
+|---|---|---|
+| [FEATURE_ROADMAP.md:299-363](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/FEATURE_ROADMAP.md#L299-L363) | "Status: Planning" | Module is **fully implemented**; update to "Shipped" |
+| FEATURE_ROADMAP.md lists `customer_id` column | actually `user_id` in schema | Drift |
+| `.agent/plans/subscription-module.md` | Original design | Now stale (e.g., `reminder_sent_at` was added later) |
+
+---
+
+## 12. Test Coverage
+
+**No subscription-specific tests** found in [tests/](file:///Users/dwindown/Local Sites/woonoow/app/public/wp-content/plugins/woonoow/tests/). Only generic schema/parity/page tests exist. The subscription module's complex state machine (status transitions, retry logic, renewal math) is untested.
+
+**Recommendation:** Add `tests/Subscription/` with at minimum:
+- `SubscriptionManagerTest.php`: state machine coverage (pending → active → on-hold → resumed, etc.)
+- `SubscriptionSchedulerTest.php`: cron logic with frozen time
+- `SubscriptionsControllerTest.php`: REST endpoint auth and validation
+- `e2e/subscription-checkout.test.ts`: full buy → renew → cancel flow
+
+---
+
+## 13. Recommended Fix Priority
+
+| # | Issue | Severity | Effort | Priority |
+|---|---|---|---|---|
+| 1 | C1 — Early renew UX clarity (show projected next-payment-date on order-pay page) | 🔴 | S | **P0 — this week** |
+| 2 | H3 — Failed orders bypass dedup (add `'wc-failed', 'failed'` to IN clause at `SubscriptionManager.php:527`) | 🟠 | XS | **P0 — this week** |
+| 3 | H6 — Guest checkout silently drops subscription (gate `subscription_add_to_cart_text` on `is_user_logged_in`) | 🟠 | S | **P0 — this week** |
+| 4 | H2 — `max_pause_count` not surfaced in enriched response (add to `enrich_subscription`, disable button in customer detail) | 🟠 | S | **P0 — this week** |
+| 5 | §9 — Per-gateway capability declaration (NEW FEATURE: capability table + settings UI + filter) | 🔴 (architectural) | M | **P1 — this sprint** |
+| 6 | H1 — Admin "Renew Now" feedback (show resulting order URL) | 🟠 | S | P2 |
+| 7 | H4 — Price sync on renewal (add `price_sync_on_renewal` setting) | 🟠 | M | P2 |
+| 8 | H5 — Unpaid renewal recovery (daily cron for `on-hold` with pending order > 24h) | 🟠 | M | P2 |
+| 9 | M1 — Variation-level subscription meta | 🟡 | M | P3 |
+| 10 | M2 — `?charge_now=true` for admin renew | 🟡 | S | P3 |
+| 11 | M3 — Bulk actions on admin subscription list | 🟡 | M | P3 |
+| 12 | M4 — Search field on admin subscription list | 🟡 | S | P3 |
+| 13 | O1 — Missing email variables (`payment_method_title`, `billing_schedule` in subscription block) | 🔵 | XS | P4 |
+| 14 | O2 — Delete `TemplateProvider.bak.php` | 🔵 | XS | P4 |
+| 15 | Doc drift — `FEATURE_ROADMAP.md` (status planning→shipped; column `customer_id`→`user_id`) | 🔵 | XS | P4 |
+| 16 | Test coverage — `tests/Subscription/` | — | L | P4 |
+| — | C2 — **Withdrawn** (not a subscription-module concern) | — | — | Defer to checkout work |
+| — | C3 — **Resolved.** Settings page is implemented (generic schema-driven). | — | — | Done |
+
+**Effort key:** XS < 1h, S = 1-4h, M = 1-2 days, L = 3+ days
+
+### Why P0 is now 4 small items, not 3 big ones
+
+The original P0 was "build §9, build the settings page, fix the order-pay UX." The settings page is **done** — that work is reusable for §9. The remaining P0 work is four small UX-correctness fixes that can be shipped in a single afternoon:
+
+- C1: ~2-4h to add a projected-date line to `OrderPay/index.tsx` (compute client-side from `subscription.billing_period`/`billing_interval`).
+- H3: ~30min — add two strings to an IN clause.
+- H6: ~1-2h — early-return in `subscription_add_to_cart_text` for guests, plus a checkout-side guard or friendly error.
+- H2: ~2-3h — add `max_pause_count` and `pauses_remaining` to `enrich_subscription`, conditional disable in `SubscriptionDetail.tsx`.
+
+§9 itself is the largest remaining work, but it is now in P1 because the settings infrastructure is reusable. §9.6 (the implementation outline) is unchanged; it now correctly reads as "do this on top of the existing module settings pattern."
+
+### 10.2 Address policy — explicitly not a subscription-module concern
+
+Earlier drafts of this audit proposed two address-related recommendations: (1) a `needs_shipping()` gate inside `create_renewal_order`, and (2) a site-level address collection mode. **Both are withdrawn.**
+
+- The `needs_shipping()` gate is unnecessary. For virtual products, the empty/default address on the renewal is harmless by virtue of the product type. The existing code is already correct.
+- A site-level address collection mode is the wrong layer. The address question is a **checkout-level** concern. Once the checkout collects an address for physical products, the renewal should copy it from the parent and let the customer change it on the order-pay page.
+
+**What the subscription module should do today:** nothing. The renewal `set_address` from parent is correct given the current checkout.
+
+**What the subscription module should do when the checkout supports physical products:** surface the parent order's address on the renewal order-pay page with a "Is your address still the same? [Change]" prompt. This is a UX change, not a backend defect fix.
+
+The address question does not belong in the subscription module's settings. It belongs in the checkout.
+
+---
+
+## 14. What's Working Well (positive findings)
+
+- The state machine handles edge cases (trial, signup-fee, fixed-length, failed payments).
+- The duplicate-prevention check in `renew()` correctly returns existing pending orders.
+- The reminder `reminder_sent_at` DB column (prior audit fix) is properly indexed and used.
+- `handle_renewal_success` correctly sets status to `active` (prior audit fix).
+- The notification event registry cleanly separates customer and admin events.
+- The product form conditionally shows the subscription block only when the module is enabled.
+- The customer account sidebar hides the subscription link when the module is disabled.
+- The order-pay page shows the `SubscriptionTimeline` for renewal orders — nice UX touch.
+- The "Pay Now (#id)" button on customer detail for unpaid renewals is a great recovery path.
+- Hooks are well-named and consistent (`woonoow/subscription/<event>`).
+- The renewal flow **already has the right hook points** (`woonoow_pre_process_subscription_payment` and `woonoow_process_subscription_payment`) to plug the per-gateway capability check into. No architectural rewrite needed.
+
+---
+
+## 15. Summary of Revised Direction
+
+The two material changes from the original draft of this audit:
+
+### Payment: per-gateway capability, not a site-level billing mode
+
+The original draft of §9 recommended documenting the gateway contract and shipping a sample adapter. The revised direction (§9) is to introduce an **explicit, merchant-visible capability declaration per gateway** with safe defaults (`false` for any gateway without a known adapter, `false` for all Indonesian-style VA/QRIS/e-wallet gateways, `true` for gateways with a working WooNooW adapter).
+
+The system then computes effective behavior at renewal time from the **intersection** of (the gateway's declared capability) and (the gateway's actual `process_subscription_renewal_payment` implementation). A site-level "force manual" kill switch exists as a secondary override, default off.
+
+The merchant thinks in payment gateways, not in "billing modes." A per-gateway checkbox next to each payment method in WooCommerce → Settings → Payments is data the merchant already has. A site-level toggle is a concept they have to learn.
+
+### Address: not a subscription-module concern
+
+**Withdrawn entirely.** On re-review, the renewal `set_address` from parent is the correct default for any product type. The original C2 finding, the `needs_shipping()` gate, and the site-level address-mode proposal are all withdrawn.
+
+The right model is:
+
+- **Virtual product** → checkout shows no address fields → no address anywhere → no problem.
+- **Physical product** → checkout requires address at first order → parent order stores it → on renewal, copy from parent and surface "Is your address still the same? [Change]" on the order-pay page.
+
+The address question is a **checkout-level** concern, not a subscription-module concern. The subscription module's `create_renewal_order` is doing the right thing — copying from the parent, which is the only signal it has. The only forward-looking UX change is to surface the address on the renewal order-pay page once the checkout supports it.
+
+### What this means for the audit's existing findings
+
+- **C2 is withdrawn** (see finding body). The renewal `set_address` is correct.
+- **C1** (early renew UX) is unchanged in spirit; the order-pay page needs to show the projected next-payment-date.
+- **C3** (settings page missing) is unchanged; the settings page is still the most visible P0.
+- **H1** (admin "Renew Now" feedback) becomes more important once the gateway capability is explicit — the admin needs to see "this renewal will be a manual order because the gateway is Tripay."
+
+---
+
+## 16. Appendix: Full File Inventory
+
+### PHP backend
+- `includes/Modules/Subscription/SubscriptionManager.php` (894 lines)
+- `includes/Modules/Subscription/SubscriptionModule.php` (564 lines)
+- `includes/Modules/Subscription/SubscriptionScheduler.php` (264 lines)
+- `includes/Modules/SubscriptionSettings.php` (110 lines)
+- `includes/Api/SubscriptionsController.php` (502 lines)
+- `includes/Api/ModuleSettingsController.php` (210+ lines, generic settings read/write/schema)
+- `includes/Core/ModuleRegistry.php` (subscription block at line 68-82)
+- `includes/Compat/NavigationRegistry.php` (lines 262-284)
+- `includes/Core/Notifications/EmailRenderer.php` (lines 339-376)
+- `includes/Core/Notifications/TemplateProvider.php` (lines 240-345)
+- `includes/Core/Notifications/TemplateProvider.bak.php` ⚠️ **still present, should be removed** (O2)
+
+### Frontend (TSX)
+- `admin-spa/src/routes/Subscriptions/index.tsx` (505 lines)
+- `admin-spa/src/routes/Subscriptions/Detail.tsx` (456 lines)
+- `admin-spa/src/routes/Orders/Detail.tsx` (related_subscription block 320-345)
+- `admin-spa/src/routes/Products/partials/tabs/GeneralTab.tsx` (subscription block 546-630)
+- `admin-spa/src/routes/Settings/ModuleSettings.tsx` (149 lines, **generic schema-driven settings page**)
+- `admin-spa/src/hooks/useModuleSettings.ts` (46 lines, settings read/write)
+- `customer-spa/src/pages/Account/Subscriptions.tsx` (244 lines)
+- `customer-spa/src/pages/Account/SubscriptionDetail.tsx` (377 lines)
+- `customer-spa/src/components/SubscriptionTimeline.tsx` (86 lines)
+- `customer-spa/src/pages/OrderPay/index.tsx` (subscription block 35-44, 142-162)
+- `customer-spa/src/pages/Account/components/AccountLayout.tsx` (line 53, 66)
+
+### Docs
+- `.agent/reports/subscription-flow-audit-2026-01-29.md` (prior audit)
+- `.agent/plans/subscription-module.md` (original design)
+- `FEATURE_ROADMAP.md` (stale)
+- `HOOKS_REGISTRY.md` (subsections at 104-117, 215, 222, 261, 285-289, 658)
+- `MODULE_SYSTEM_IMPLEMENTATION.md`
+
+---
+
+## 17. Re-verification matrix (2026-06-01)
+
+Each finding in this audit was re-checked against the actual implementation today. The table is the source of truth for "documented vs. implemented."
+
+| # | Finding | Original severity | Re-verified status | Notes |
+|---|---|---|---|---|
+| C1 | Early-renew UX lacks projected next-payment-date | 🔴 | ✅ **Confirmed** | `OrderPay/index.tsx` only renders static `SubscriptionTimeline` snapshot; no projection |
+| C2 | Stale address on renewal | 🔴 | ✅ **Withdrawn** | Address is checkout's responsibility, not subscription's. Already resolved in this document. |
+| C3 | Settings page missing | 🔴 | ❌ **Withdrawn — false alarm** | Generic `ModuleSettings.tsx` + `/modules/{id}/schema` + `useModuleSettings` + `SchemaForm` all exist and work. See C3 resolution section. |
+| H1 | Admin "Renew Now" lacks feedback | 🟠 | ✅ Confirmed | Real |
+| H2 | `max_pause_count` not surfaced | 🟠 | ✅ Confirmed | `enrich_subscription()` (lines 439-500) does not add `max_pause_count` or `pauses_remaining` |
+| H3 | Failed orders bypass dedup | 🟠 | ✅ Confirmed | Line 527 IN clause: `('wc-pending', 'pending', 'wc-on-hold', 'on-hold')` — no `failed` |
+| H4 | Renewal uses stored price; no "use current" toggle | 🟠 | ✅ Confirmed (mixed) | Code is correct (uses stored); the missing toggle is the actual fix |
+| H5 | Unpaid renewal not re-notified | 🟠 | ✅ Confirmed | Real revenue-leakage path |
+| H6 | Guest checkout silently drops | 🟠 | ✅ Confirmed | `subscription_add_to_cart_text` does not check `is_user_logged_in`; `create_from_order` returns false silently |
+| M1 | Variable product meta on parent only | 🟡 | ✅ Confirmed | `create_from_order` reads parent product meta; GeneralTab has no variation UI |
+| M2 | No `force_immediate` flag | 🟡 | ✅ Confirmed | Neither endpoint has it |
+| M3 | No bulk actions on admin list | 🟡 | ✅ Confirmed | `selectedIds` state exists but no toolbar |
+| M4 | No search field on admin list | 🟡 | ✅ Confirmed | No search input element |
+| O1 | Missing email variables | 🔵 | ⚠️ **Partially confirmed** | `payment_method_title`, `billing_schedule` not in subscription block (lines 343-353). `my_account_url` is mapped in a different branch. |
+| O2 | `.bak.php` in production | 🔵 | ✅ Confirmed | `TemplateProvider.bak.php` 11464 bytes, present |
+| §9 | Per-gateway capability | 🔴 (architectural) | ⚠️ **Confirmed aspirational, no work done** | Zero references in codebase. Settings infrastructure now reusable, so it can be built on existing patterns. |
+
+---
+
+**End of report.**

admin-spa/BUGFIXES.md

@@ -1,242 +0,0 @@
-# Bug Fixes & User Feedback Resolution
-
-## All 7 Issues Resolved ✅
-
----
-
-### 1. WordPress Media Library Not Loading
-
-**Issue:**
-- Error: "WordPress media library is not loaded. Please refresh the page."
-- Blocking users from inserting images
-
-**Root Cause:**
-- WordPress Media API (`window.wp.media`) not available in some contexts
-- No fallback mechanism
-
-**Solution:**
-```typescript
-// Added fallback to URL prompt
-if (typeof window.wp === 'undefined' || typeof window.wp.media === 'undefined') {
-  const url = window.prompt('WordPress Media library is not loaded. Please enter image URL:');
-  if (url) {
-    onSelect({ url, id: 0, title: 'External Image', filename: url.split('/').pop() || 'image' });
-  }
-  return;
-}
-```
-
-**Result:**
-- Users can still insert images via URL if WP Media fails
-- Better error handling
-- No blocking errors
-
----
-
-### 2. Button Variables - Too Many Options
-
-**Issue:**
-- All variables shown in button link field
-- Confusing for users (why show customer_name for a link?)
-
-**Solution:**
-```typescript
-// Filter to only show URL variables
-{variables.filter(v => v.includes('_url')).map((variable) => (
-  <code onClick={() => setButtonHref(buttonHref + `{${variable}}`)}>{`{${variable}}`}</code>
-))}
-```
-
-**Before:**
-```
-{order_number} {order_total} {customer_name} {customer_email} ...
-```
-
-**After:**
-```
-{order_url} {store_url}
-```
-
-**Files Modified:**
-- `components/ui/rich-text-editor.tsx`
-- `components/EmailBuilder/EmailBuilder.tsx`
-
----
-
-### 3. Color Customization - Future Feature
-
-**Issue:**
-- Colors are hardcoded:
-  - Hero card gradient: `#667eea` to `#764ba2`
-  - Button primary: `#7f54b3`
-  - Button secondary border: `#7f54b3`
-
-**Plan:**
-- Will be added to email customization form
-- Allow users to set brand colors
-- Apply to all email templates
-- Store in settings
-
-**Note:**
-Confirmed for future implementation. Not blocking current release.
-
----
-
-### 4 & 5. Headings Not Visible in Editor & Builder
-
-**Issue:**
-- Headings (H1-H4) looked like paragraphs
-- No visual distinction
-- Confusing for users
-
-**Root Cause:**
-- No CSS styles applied to heading elements
-- Default browser styles insufficient
-
-**Solution:**
-Added Tailwind utility classes for heading styles:
-
-```typescript
-// RichTextEditor
-className="prose prose-sm max-w-none [&_h1]:text-3xl [&_h1]:font-bold [&_h1]:mt-4 [&_h1]:mb-2 [&_h2]:text-2xl [&_h2]:font-bold [&_h2]:mt-3 [&_h2]:mb-2 [&_h3]:text-xl [&_h3]:font-bold [&_h3]:mt-2 [&_h3]:mb-1 [&_h4]:text-lg [&_h4]:font-bold [&_h4]:mt-2 [&_h4]:mb-1"
-
-// BlockRenderer (builder preview)
-className="prose prose-sm max-w-none [&_h1]:text-3xl [&_h1]:font-bold [&_h1]:mt-0 [&_h1]:mb-4 [&_h2]:text-2xl [&_h2]:font-bold [&_h2]:mt-0 [&_h2]:mb-3 [&_h3]:text-xl [&_h3]:font-bold [&_h3]:mt-0 [&_h3]:mb-2 [&_h4]:text-lg [&_h4]:font-bold [&_h4]:mt-0 [&_h4]:mb-2"
-```
-
-**Heading Sizes:**
-- **H1**: 3xl (1.875rem / 30px), bold
-- **H2**: 2xl (1.5rem / 24px), bold
-- **H3**: xl (1.25rem / 20px), bold
-- **H4**: lg (1.125rem / 18px), bold
-
-**Result:**
-- Headings now visually distinct
-- Clear hierarchy
-- Matches email preview
-
-**Files Modified:**
-- `components/ui/rich-text-editor.tsx`
-- `components/EmailBuilder/BlockRenderer.tsx`
-
----
-
-### 6. Missing Order Items Variable
-
-**Issue:**
-- No variable for product list/table
-- Users can't show ordered products in emails
-
-**Solution:**
-Added `order_items` variable to order variables:
-
-```php
-'order_items' => __('Order Items (formatted table)', 'woonoow'),
-```
-
-**Usage:**
-```html
-[card]
-<h2>Order Summary</h2>
-{order_items}
-[/card]
-```
-
-**Will Render:**
-```html
-<table>
-  <tr>
-    <td>Product Name</td>
-    <td>Quantity</td>
-    <td>Price</td>
-  </tr>
-  <!-- ... product rows ... -->
-</table>
-```
-
-**File Modified:**
-- `includes/Core/Notifications/TemplateProvider.php`
-
----
-
-### 7. Edit Icon on Spacer & Divider
-
-**Issue:**
-- Edit button (✎) shown for spacer and divider
-- No options to edit (they have no configurable properties)
-- Clicking does nothing
-
-**Solution:**
-Conditional rendering of edit button:
-
-```typescript
-{/* Only show edit button for card and button blocks */}
-{(block.type === 'card' || block.type === 'button') && (
-  <button onClick={onEdit} title={__('Edit')}>✎</button>
-)}
-```
-
-**Controls Now:**
-- **Card**: ↑ ↓ ✎ × (all controls)
-- **Button**: ↑ ↓ ✎ × (all controls)
-- **Spacer**: ↑ ↓ × (no edit)
-- **Divider**: ↑ ↓ × (no edit)
-
-**File Modified:**
-- `components/EmailBuilder/BlockRenderer.tsx`
-
----
-
-## Testing Checklist
-
-### Issue 1: WP Media Fallback
-- [ ] Try inserting image when WP Media is loaded
-- [ ] Try inserting image when WP Media is not loaded
-- [ ] Verify fallback prompt appears
-- [ ] Verify image inserts correctly
-
-### Issue 2: Button Variables
-- [ ] Open button dialog in RichTextEditor
-- [ ] Verify only URL variables shown
-- [ ] Open button dialog in EmailBuilder
-- [ ] Verify only URL variables shown
-
-### Issue 3: Color Customization
-- [ ] Note documented for future implementation
-- [ ] Colors currently hardcoded (expected)
-
-### Issue 4 & 5: Heading Display
-- [ ] Create card with H1 heading
-- [ ] Verify H1 is large and bold in editor
-- [ ] Verify H1 is large and bold in builder
-- [ ] Test H2, H3, H4 similarly
-- [ ] Verify preview matches
-
-### Issue 6: Order Items Variable
-- [ ] Check variable list includes `order_items`
-- [ ] Insert `{order_items}` in template
-- [ ] Verify description shows "formatted table"
-
-### Issue 7: Edit Icon Removal
-- [ ] Hover over spacer block
-- [ ] Verify no edit button (only ↑ ↓ ×)
-- [ ] Hover over divider block
-- [ ] Verify no edit button (only ↑ ↓ ×)
-- [ ] Hover over card block
-- [ ] Verify edit button present (↑ ↓ ✎ ×)
-
----
-
-## Summary
-
-All 7 user-reported issues have been resolved:
-
-1. ✅ **WP Media Fallback** - No more blocking errors
-2. ✅ **Button Variables Filtered** - Only relevant variables shown
-3. ✅ **Color Customization Noted** - Future feature documented
-4. ✅ **Headings Visible in Editor** - Proper styling applied
-5. ✅ **Headings Visible in Builder** - Consistent with editor
-6. ✅ **Order Items Variable** - Product list support added
-7. ✅ **Edit Icon Removed** - Only on editable blocks
-
-**Status: Ready for Testing** 🚀

admin-spa/EMAIL_BUILDER_COMPLETE.md

@@ -1,329 +0,0 @@
-# Email Template & Builder System - Complete ✅
-
-## Overview
-The WooNooW email template and builder system is now production-ready with improved templates, enhanced markdown support, and a fully functional visual builder.
-
----
-
-## 🎉 What's Complete
-
-### 1. **Default Email Templates** ✅
-**File:** `includes/Email/DefaultTemplates.php`
-
-**Features:**
-- ✅ 16 production-ready email templates (9 customer + 7 staff)
-- ✅ Modern, clean markdown format (easy to read and edit)
-- ✅ Professional, friendly tone
-- ✅ Complete variable support
-- ✅ Ready to use without any customization
-
-**Templates Included:**
-
-**Customer Templates:**
-1. Order Placed - Initial order confirmation
-2. Order Confirmed - Payment confirmed, ready to ship
-3. Order Shipped - Tracking information
-4. Order Completed - Delivery confirmation with review request
-5. Order Cancelled - Cancellation notice with refund info
-6. Payment Received - Payment confirmation
-7. Payment Failed - Payment issue with resolution steps
-8. Customer Registered - Welcome email with account benefits
-9. Customer VIP Upgraded - VIP status announcement
-
-**Staff Templates:**
-1. Order Placed - New order notification
-2. Order Confirmed - Order ready to process
-3. Order Shipped - Shipment confirmation
-4. Order Completed - Order lifecycle complete
-5. Order Cancelled - Cancellation with action items
-6. Payment Received - Payment notification
-7. Payment Failed - Payment failure alert
-
-**Template Syntax:**
-```
-[card type="hero"]
-Welcome message here
-[/card]
-
-[card]
-**Order Number:** #{order_number}
-**Order Total:** {order_total}
-[/card]
-
-[button url="{order_url}"]View Order Details[/button]
-
----
-
-© {current_year} {site_name}
-```
-
----
-
-### 2. **Enhanced Markdown Parser** ✅
-**File:** `admin-spa/src/lib/markdown-parser.ts`
-
-**New Features:**
-- ✅ Button shortcode: `[button url="..."]Text[/button]`
-- ✅ Horizontal rules: `---`
-- ✅ Checkmarks and bullet points: `✓` `•` `-` `*`
-- ✅ Card blocks with types: `[card type="success"]...[/card]`
-- ✅ Bold, italic, headings, lists, links
-- ✅ Variable support: `{variable_name}`
-
-**Supported Markdown:**
-```markdown
-# Heading 1
-## Heading 2
-### Heading 3
-
-**Bold text**
-*Italic text*
-
-- List item
-• Bullet point
-✓ Checkmark item
-
-[Link text](url)
-
----
-
-[card type="hero"]
-Card content
-[/card]
-
-[button url="#"]Button Text[/button]
-```
-
----
-
-### 3. **Visual Email Builder** ✅
-**File:** `admin-spa/src/components/EmailBuilder/EmailBuilder.tsx`
-
-**Features:**
-- ✅ Drag-and-drop block editor
-- ✅ Card blocks (default, success, info, warning, hero)
-- ✅ Button blocks (solid/outline, width/alignment controls)
-- ✅ Image blocks with WordPress media library integration
-- ✅ Divider and spacer blocks
-- ✅ Rich text editor with variable insertion
-- ✅ Mobile fallback UI (desktop-only message)
-- ✅ WordPress media modal integration (z-index and pointer-events fixed)
-- ✅ Dialog outside-click prevention with WP media exception
-
-**Block Types:**
-1. **Card** - Content container with type variants
-2. **Button** - CTA button with style and layout options
-3. **Image** - Image with alignment and width controls
-4. **Divider** - Horizontal line separator
-5. **Spacer** - Vertical spacing control
-
----
-
-### 4. **Preview System** ✅
-**File:** `admin-spa/src/routes/Settings/Notifications/EditTemplate.tsx`
-
-**Features:**
-- ✅ Live preview with actual branding colors
-- ✅ Sample data for all variables
-- ✅ Mobile-responsive preview (reduced padding on small screens)
-- ✅ Button shortcode parsing
-- ✅ Card parsing with type support
-- ✅ Variable replacement with sample data
-
-**Mobile Responsive:**
-```css
-@media only screen and (max-width: 600px) {
-  body { padding: 8px; }
-  .card-gutter { padding: 0 8px; }
-  .card { padding: 20px 16px; }
-}
-```
-
----
-
-### 5. **Variable System** ✅
-
-**Complete Variable Support:**
-
-**Order Variables:**
-- `{order_number}` - Order number/ID
-- `{order_date}` - Order creation date
-- `{order_total}` - Total order amount
-- `{order_url}` - Link to view order
-- `{order_item_table}` - Formatted order items table
-- `{completion_date}` - Order completion date
-
-**Customer Variables:**
-- `{customer_name}` - Customer's full name
-- `{customer_email}` - Customer's email
-- `{customer_phone}` - Customer's phone
-
-**Payment Variables:**
-- `{payment_method}` - Payment method used
-- `{payment_status}` - Payment status
-- `{payment_date}` - Payment date
-- `{transaction_id}` - Transaction ID
-- `{payment_retry_url}` - URL to retry payment
-
-**Shipping Variables:**
-- `{tracking_number}` - Tracking number
-- `{tracking_url}` - Tracking URL
-- `{shipping_carrier}` - Carrier name
-- `{shipping_address}` - Full shipping address
-- `{billing_address}` - Full billing address
-
-**URL Variables:**
-- `{order_url}` - Order details page
-- `{review_url}` - Leave review page
-- `{shop_url}` - Shop homepage
-- `{my_account_url}` - Customer account page
-- `{vip_dashboard_url}` - VIP dashboard
-
-**Store Variables:**
-- `{site_name}` - Store name
-- `{store_url}` - Store URL
-- `{support_email}` - Support email
-- `{current_year}` - Current year
-
-**VIP Variables:**
-- `{vip_free_shipping_threshold}` - Free shipping threshold
-
----
-
-### 6. **Bug Fixes** ✅
-
-**WordPress Media Modal Integration:**
-- ✅ Fixed z-index conflict (WP media now appears above Radix components)
-- ✅ Fixed pointer-events blocking (WP media is now fully clickable)
-- ✅ Fixed dialog closing when selecting image (dialog stays open)
-- ✅ Added exception for WP media in outside-click prevention
-
-**CSS Fixes:**
-```css
-/* WordPress Media Modal z-index fix */
-.media-modal {
-  z-index: 999999 !important;
-  pointer-events: auto !important;
-}
-
-.media-modal-content {
-  z-index: 1000000 !important;
-  pointer-events: auto !important;
-}
-```
-
-**Dialog Fix:**
-```typescript
-onInteractOutside={(e) => {
-  const wpMediaOpen = document.querySelector('.media-modal');
-  if (wpMediaOpen) {
-    e.preventDefault(); // Keep dialog open when WP media is active
-    return;
-  }
-  e.preventDefault(); // Prevent closing for other outside clicks
-}}
-```
-
----
-
-## 📱 Mobile Strategy
-
-**Current Implementation (Optimal):**
-- ✅ **Preview Tab** - Works on mobile (read-only viewing)
-- ✅ **Code Tab** - Works on mobile (advanced users can edit)
-- ❌ **Builder Tab** - Desktop-only with clear message
-
-**Why This Works:**
-- Users can view email previews on any device
-- Power users can make quick code edits on mobile
-- Visual builder requires desktop for optimal UX
-
----
-
-## 🎨 Email Customization Features
-
-**Available in Settings:**
-1. **Brand Colors**
-   - Primary color
-   - Secondary color
-   - Hero gradient (start/end)
-   - Hero text color
-   - Button text color
-
-2. **Layout**
-   - Body background color
-   - Logo upload
-   - Header text
-   - Footer text
-
-3. **Social Links**
-   - Facebook, Twitter, Instagram, LinkedIn, YouTube, Website
-   - Custom icon color (white/color)
-
----
-
-## 🚀 Ready for Production
-
-**What Store Owners Get:**
-1. ✅ Professional email templates out-of-the-box
-2. ✅ Easy customization with visual builder
-3. ✅ Code mode for advanced users
-4. ✅ Live preview with branding
-5. ✅ Mobile-friendly emails
-6. ✅ Complete variable system
-7. ✅ WordPress media library integration
-
-**No Setup Required:**
-- Templates are ready to use immediately
-- Store owners can start selling without editing emails
-- Customization is optional but easy
-- However, backend integration is still required for full functionality
-
----
-
-## Next Steps (REQUIRED)
-
-**IMPORTANT: Backend Integration Still Needed**
-
-The new `DefaultTemplates.php` is ready but NOT YET WIRED to the backend!
-
-**Current State:**
-- New templates created: `includes/Email/DefaultTemplates.php`
-- Backend still using old: `includes/Core/Notifications/DefaultEmailTemplates.php`
-
-**To Complete Integration:**
-1. Update `includes/Core/Notifications/DefaultEmailTemplates.php` to use new `DefaultTemplates` class
-2. Or replace old class entirely with new one
-3. Update API controller to return correct event counts per recipient
-4. Wire up to database on plugin activation
-5. Hook into WooCommerce order status changes
-6. Test email sending
-
-**Example:**
-```php
-use WooNooW\Email\DefaultTemplates;
-
-// On plugin activation
-$templates = DefaultTemplates::get_all_templates();
-foreach ($templates['customer'] as $event => $body) {
-    $subject = DefaultTemplates::get_default_subject('customer', $event);
-    // Save to database
-}
-```
-
----
-
-## ✅ Phase Complete
-
-The email template and builder system is now **production-ready** and can be shipped to users!
-
-**Key Achievements:**
-- ✅ 16 professional email templates
-- ✅ Visual builder with drag-and-drop
-- ✅ WordPress media library integration
-- ✅ Mobile-responsive preview
-- ✅ Complete variable system
-- ✅ All bugs fixed
-- ✅ Ready for general store owners
-
-**Time to move on to the next phase!** 🎉

admin-spa/EMAIL_BUILDER_IMPROVEMENTS.md

@@ -1,388 +0,0 @@
-# Email Builder - All Improvements Complete! 🎉
-
-## Overview
-
-All 5 user-requested improvements have been successfully implemented, creating a professional, user-friendly email template builder that respects WordPress conventions.
-
----
-
-## ✅ 1. Heading Selector in RichTextEditor
-
-### Problem
-Users couldn't control heading levels without typing HTML manually.
-
-### Solution
-Added a dropdown selector in the RichTextEditor toolbar.
-
-**Features:**
-- Dropdown with options: Paragraph, H1, H2, H3, H4
-- Visual feedback (shows active heading level)
-- One-click heading changes
-- User controls document structure
-
-**UI Location:**
-```
-[Paragraph ▼] [B] [I] [List] [Link] ...
-     ↑
-  First item in toolbar
-```
-
-**Files Modified:**
-- `components/ui/rich-text-editor.tsx`
-
----
-
-## ✅ 2. Styled Buttons in Cards
-
-### Problem
-- Buttons in TipTap cards looked raw (unstyled)
-- Different appearance from standalone buttons
-- Not editable (couldn't change text/URL by clicking)
-
-### Solution
-Created a custom TipTap extension for buttons with proper styling.
-
-**Features:**
-- Same inline styles as standalone buttons
-- Solid & Outline styles available
-- Fully editable via dialog
-- Non-editable in editor (atomic node)
-- Click button icon → dialog opens
-
-**Button Styles:**
-```css
-Solid (Primary):
-  background: #7f54b3
-  color: white
-  padding: 14px 28px
-
-Outline (Secondary):
-  background: transparent
-  color: #7f54b3
-  border: 2px solid #7f54b3
-```
-
-**Files Created:**
-- `components/ui/tiptap-button-extension.ts`
-
-**Files Modified:**
-- `components/ui/rich-text-editor.tsx`
-
----
-
-## ✅ 3. Variable Pills for Button Links
-
-### Problem
-- Users had to type `{variable_name}` manually
-- Easy to make typos
-- No suggestions or discovery
-
-### Solution
-Added clickable variable pills under Button Link inputs.
-
-**Features:**
-- Visual display of available variables
-- One-click insertion
-- No typing errors
-- Works in both:
-  - RichTextEditor button dialog
-  - EmailBuilder button dialog
-
-**UI:**
-```
-Button Link
-┌─────────────────────────┐
-│ {order_url}             │
-└─────────────────────────┘
-
-{order_number} {order_total} {customer_name} ...
-     ↑ Click any pill to insert
-```
-
-**Files Modified:**
-- `components/ui/rich-text-editor.tsx`
-- `components/EmailBuilder/EmailBuilder.tsx`
-
----
-
-## ✅ 4. WordPress Media Modal for TipTap Images
-
-### Problem
-- Prompt dialog for image URL
-- Manual URL entry required
-- No access to media library
-
-### Solution
-Integrated WordPress native Media Modal for image selection.
-
-**Features:**
-- Native WordPress Media Modal
-- Browse existing uploads
-- Upload new images
-- Full media library features
-- Auto-sets: src, alt, title
-
-**User Flow:**
-1. Click image icon in RichTextEditor toolbar
-2. WordPress Media Modal opens
-3. Select from library OR upload new
-4. Image inserted with proper attributes
-
-**Files Created:**
-- `lib/wp-media.ts` (WordPress Media helper)
-
-**Files Modified:**
-- `components/ui/rich-text-editor.tsx`
-
----
-
-## ✅ 5. WordPress Media Modal for Store Logos/Favicon
-
-### Problem
-- Only drag-and-drop or file picker available
-- No access to existing media library
-- Couldn't reuse uploaded assets
-
-### Solution
-Added "Choose from Media Library" button to ImageUpload component.
-
-**Features:**
-- WordPress Media Modal integration
-- Filtered by media type:
-  - **Logo**: PNG, JPEG, SVG, WebP
-  - **Favicon**: PNG, ICO
-- Browse and reuse existing assets
-- Drag-and-drop still works
-
-**UI:**
-```
-┌─────────────────────────────────┐
-│         [Upload Icon]           │
-│                                 │
-│  Drop image here or click       │
-│  Max size: 2MB                  │
-│                                 │
-│  [Choose from Media Library]    │
-└─────────────────────────────────┘
-```
-
-**Files Modified:**
-- `components/ui/image-upload.tsx`
-- `routes/Settings/Store.tsx`
-
----
-
-## 📦 New Files Created
-
-### 1. `lib/wp-media.ts`
-WordPress Media Modal integration helper.
-
-**Functions:**
-- `openWPMedia()` - Core function with options
-- `openWPMediaImage()` - For general images
-- `openWPMediaLogo()` - For logos (filtered)
-- `openWPMediaFavicon()` - For favicons (filtered)
-
-**Interface:**
-```typescript
-interface WPMediaFile {
-  url: string;
-  id: number;
-  title: string;
-  filename: string;
-  alt?: string;
-  width?: number;
-  height?: number;
-}
-```
-
-### 2. `components/ui/tiptap-button-extension.ts`
-Custom TipTap node for styled buttons.
-
-**Features:**
-- Renders with inline styles
-- Atomic node (non-editable)
-- Data attributes for editing
-- Matches email rendering exactly
-
----
-
-## 🎨 User Experience Improvements
-
-### For Non-Technical Users
-- **Heading Control**: No HTML knowledge needed
-- **Visual Buttons**: Professional styling automatically
-- **Variable Discovery**: See all available variables
-- **Media Library**: Familiar WordPress interface
-
-### For Tech-Savvy Users
-- **Code Mode**: Still available with CodeMirror
-- **Full Control**: Can edit raw HTML
-- **Professional Tools**: Syntax highlighting, auto-completion
-
-### For Everyone
-- **Consistent UX**: Matches WordPress conventions
-- **No Learning Curve**: Familiar interfaces
-- **Professional Results**: Beautiful emails every time
-
----
-
-## 🙏 Respecting WordPress
-
-### Why This Matters
-
-**1. Familiar Interface**
-Users already know WordPress Media Modal from Posts/Pages.
-
-**2. Existing Assets**
-Access to all uploaded media, no re-uploading.
-
-**3. Better UX**
-No manual URL entry, visual selection.
-
-**4. Professional**
-Native WordPress integration, not a custom solution.
-
-**5. Consistent**
-Same experience across WordPress admin.
-
-### WordPress Integration Details
-
-**Uses:**
-- `window.wp.media` API
-- WordPress REST API for uploads
-- Proper nonce handling
-- User permissions respected
-
-**Compatible with:**
-- WordPress Media Library
-- Custom upload handlers
-- Media organization plugins
-- CDN integrations
-
----
-
-## 📋 Complete Feature List
-
-### Email Builder Features
-✅ Visual block-based editor
-✅ Drag-and-drop reordering
-✅ Card blocks with rich content
-✅ Standalone buttons (outside cards)
-✅ Dividers and spacers
-✅ Code mode with CodeMirror
-✅ Variable insertion
-✅ Preview mode
-✅ Responsive design
-
-### RichTextEditor Features
-✅ Heading selector (H1-H4, Paragraph)
-✅ Bold, Italic formatting
-✅ Bullet and numbered lists
-✅ Links
-✅ Text alignment (left, center, right)
-✅ Image insertion (WordPress Media)
-✅ Button insertion (styled)
-✅ Variable insertion (pills)
-✅ Undo/Redo
-
-### Store Settings Features
-✅ Logo upload (light mode)
-✅ Logo upload (dark mode)
-✅ Favicon upload
-✅ WordPress Media Modal integration
-✅ Drag-and-drop upload
-✅ File type filtering
-✅ Preview display
-
----
-
-## 🚀 Installation & Testing
-
-### Install Dependencies
-
-```bash
-cd admin-spa
-
-# TipTap Extensions
-npm install @tiptap/extension-text-align @tiptap/extension-image
-
-# CodeMirror
-npm install codemirror @codemirror/lang-html @codemirror/theme-one-dark
-
-# Radix UI
-npm install @radix-ui/react-radio-group
-```
-
-### Or Install All at Once
-```bash
-npm install @tiptap/extension-text-align @tiptap/extension-image codemirror @codemirror/lang-html @codemirror/theme-one-dark @radix-ui/react-radio-group
-```
-
-### Start Development Server
-```bash
-npm run dev
-```
-
-### Test Checklist
-
-**Email Builder:**
-- [ ] Add card with rich content
-- [ ] Use heading selector (H1-H4)
-- [ ] Insert styled button in card
-- [ ] Add standalone button
-- [ ] Click variable pills to insert
-- [ ] Insert image via WordPress Media
-- [ ] Test text alignment
-- [ ] Preview email
-- [ ] Switch to code mode
-- [ ] Save template
-
-**Store Settings:**
-- [ ] Upload logo (light) via drag-and-drop
-- [ ] Upload logo (dark) via Media Library
-- [ ] Upload favicon via Media Library
-- [ ] Remove and re-upload
-- [ ] Verify preview display
-
----
-
-## 📝 Summary
-
-### What We Built
-
-A **professional, user-friendly email template builder** that:
-- Respects WordPress conventions
-- Provides visual editing for beginners
-- Offers code mode for experts
-- Integrates seamlessly with WordPress Media
-- Produces beautiful, responsive emails
-
-### Key Achievements
-
-1. **No HTML Knowledge Required** - Visual builder handles everything
-2. **Professional Styling** - Buttons and content look great
-3. **WordPress Integration** - Native Media Modal support
-4. **Variable System** - Easy dynamic content insertion
-5. **Flexible** - Visual builder OR code mode
-
-### Production Ready
-
-All features tested and working:
-- ✅ Block structure optimized
-- ✅ Rich content editing
-- ✅ WordPress Media integration
-- ✅ Variable insertion
-- ✅ Professional styling
-- ✅ Code mode available
-- ✅ Responsive design
-
----
-
-## 🎉 Result
-
-**The PERFECT email template builder for WooCommerce!**
-
-Combines the simplicity of a visual builder with the power of code editing, all while respecting WordPress conventions and providing a familiar user experience.
-
-**Best of all worlds!** 🚀

admin-spa/EMAIL_CUSTOMIZATION_COMPLETE.md

@@ -1,310 +0,0 @@
-# Email Customization - Complete Implementation! 🎉
-
-## ✅ All 5 Tasks Completed
-
-### 1. Logo URL with WP Media Library
-**Status:** ✅ Complete
-
-**Features:**
-- "Select" button opens WordPress Media Library
-- Logo preview below input field
-- Can paste URL or select from media
-- Proper image sizing (200x60px recommended)
-
-**Implementation:**
-- Uses `openWPMediaLogo()` from wp-media.ts
-- Preview shows selected logo
-- Applied to email header in EmailRenderer
-
----
-
-### 2. Footer Text with {current_year} Variable
-**Status:** ✅ Complete
-
-**Features:**
-- Placeholder shows `© {current_year} Your Store`
-- Help text explains dynamic year variable
-- Backend replaces {current_year} with actual year
-
-**Implementation:**
-```php
-$footer_text = str_replace('{current_year}', date('Y'), $footer_text);
-```
-
-**Example:**
-```
-Input: © {current_year} My Store. All rights reserved.
-Output: © 2024 My Store. All rights reserved.
-```
-
----
-
-### 3. Social Links in Footer
-**Status:** ✅ Complete
-
-**Supported Platforms:**
-- Facebook
-- Twitter
-- Instagram
-- LinkedIn
-- YouTube
-- Website
-
-**Features:**
-- Add/remove social links
-- Platform dropdown with icons
-- URL input for each
-- Rendered as icons in email footer
-- Centered alignment
-
-**UI:**
-```
-[Facebook ▼] [https://facebook.com/yourpage]  [🗑️]
-[Twitter  ▼] [https://twitter.com/yourhandle] [🗑️]
-```
-
-**Email Output:**
-```html
-<div class="social-icons" style="margin-top: 16px; text-align: center;">
-  <a href="https://facebook.com/..."><img src="..." /></a>
-  <a href="https://twitter.com/..."><img src="..." /></a>
-</div>
-```
-
----
-
-### 4. Backend API & Integration
-**Status:** ✅ Complete
-
-**API Endpoints:**
-```
-GET    /woonoow/v1/notifications/email-settings
-POST   /woonoow/v1/notifications/email-settings
-DELETE /woonoow/v1/notifications/email-settings
-```
-
-**Database:**
-- Stored in wp_options as `woonoow_email_settings`
-- JSON structure with all settings
-- Defaults provided if not set
-
-**Security:**
-- Permission checks (manage_woocommerce)
-- Input sanitization (sanitize_hex_color, esc_url_raw)
-- Platform whitelist for social links
-- URL validation
-
-**Email Rendering:**
-- EmailRenderer.php applies settings
-- Logo/header text
-- Footer with {current_year}
-- Social icons
-- Hero card colors
-- Button colors (ready)
-
----
-
-### 5. Hero Card Text Color
-**Status:** ✅ Complete
-
-**Features:**
-- Separate color picker for hero text
-- Applied to headings and paragraphs
-- Live preview in settings
-- Usually white for dark gradients
-
-**Implementation:**
-```php
-if ($type === 'hero' || $type === 'success') {
-    $style .= sprintf(
-        ' background: linear-gradient(135deg, %s 0%%, %s 100%%);',
-        $hero_gradient_start,
-        $hero_gradient_end
-    );
-    $content_style .= sprintf(' color: %s;', $hero_text_color);
-}
-```
-
-**Preview:**
-```
-[#667eea] → [#764ba2]  [#ffffff]
-Gradient Start  End    Text Color
-
-Preview:
-┌─────────────────────────────┐
-│  Preview (white text)       │
-│  This is how your hero      │
-│  cards will look            │
-└─────────────────────────────┘
-```
-
----
-
-## Complete Settings Structure
-
-```typescript
-interface EmailSettings {
-  // Brand Colors
-  primary_color: string;        // #7f54b3
-  secondary_color: string;      // #7f54b3
-  
-  // Hero Card
-  hero_gradient_start: string;  // #667eea
-  hero_gradient_end: string;    // #764ba2
-  hero_text_color: string;      // #ffffff
-  
-  // Buttons
-  button_text_color: string;    // #ffffff
-  
-  // Branding
-  logo_url: string;             // https://...
-  header_text: string;          // Store Name
-  footer_text: string;          // © {current_year} ...
-  
-  // Social
-  social_links: SocialLink[];   // [{platform, url}]
-}
-```
-
----
-
-## How It Works
-
-### Frontend → Backend
-1. User customizes settings in UI
-2. Clicks "Save Settings"
-3. POST to `/notifications/email-settings`
-4. Backend sanitizes and stores in wp_options
-
-### Backend → Email
-1. Email triggered (order placed, etc.)
-2. EmailRenderer loads settings
-3. Applies colors, logo, footer
-4. Renders with custom branding
-5. Sends to customer
-
-### Preview
-1. EditTemplate loads settings
-2. Applies to preview iframe
-3. User sees real-time preview
-4. Colors, logo, footer all visible
-
----
-
-## Files Modified
-
-### Frontend
-- `routes/Settings/Notifications.tsx` - Added card
-- `routes/Settings/Notifications/EmailCustomization.tsx` - NEW
-- `App.tsx` - Added route
-
-### Backend
-- `includes/Api/NotificationsController.php` - API endpoints
-- `includes/Core/Notifications/EmailRenderer.php` - Apply settings
-
----
-
-## Testing Checklist
-
-### Settings Page
-- [ ] Navigate to Settings → Notifications → Email Customization
-- [ ] Change primary color → See button preview update
-- [ ] Change hero gradient → See preview update
-- [ ] Change hero text color → See preview text color change
-- [ ] Click "Select" for logo → Media library opens
-- [ ] Select logo → Preview shows below
-- [ ] Add footer text with {current_year}
-- [ ] Add social links (Facebook, Twitter, etc.)
-- [ ] Click "Save Settings" → Success message
-- [ ] Refresh page → Settings persist
-- [ ] Click "Reset to Defaults" → Confirm → Settings reset
-
-### Email Rendering
-- [ ] Trigger test email (place order)
-- [ ] Check email has custom logo (if set)
-- [ ] Check email has custom header text (if set)
-- [ ] Check hero cards have custom gradient
-- [ ] Check hero cards have custom text color
-- [ ] Check footer has {current_year} replaced with actual year
-- [ ] Check footer has social icons
-- [ ] Click social icons → Go to correct URLs
-
-### Preview
-- [ ] Edit email template
-- [ ] Switch to Preview tab
-- [ ] See custom colors applied
-- [ ] See logo/header
-- [ ] See footer with social icons
-
----
-
-## Next Steps (Optional Enhancements)
-
-### Button Color Application
-Currently ready but needs template update:
-```php
-$primary_color = $email_settings['primary_color'] ?? '#7f54b3';
-$button_text_color = $email_settings['button_text_color'] ?? '#ffffff';
-
-// Apply to .button class in template
-```
-
-### Social Icon Assets
-Need to create/host social icon images:
-- facebook.png
-- twitter.png
-- instagram.png
-- linkedin.png
-- youtube.png
-- website.png
-
-Or use Font Awesome / inline SVG.
-
-### Preview Integration
-Update EditTemplate preview to fetch and apply email settings:
-```typescript
-const { data: emailSettings } = useQuery({
-  queryKey: ['email-settings'],
-  queryFn: () => api.get('/notifications/email-settings'),
-});
-
-// Apply to preview styles
-```
-
----
-
-## Success Metrics
-
-✅ **User Experience:**
-- Easy logo selection (WP Media Library)
-- Visual color pickers
-- Live previews
-- One-click save
-- One-click reset
-
-✅ **Functionality:**
-- All settings saved to database
-- All settings applied to emails
-- Dynamic {current_year} variable
-- Social links rendered
-- Colors applied to cards
-
-✅ **Code Quality:**
-- Proper sanitization
-- Security checks
-- Type safety (TypeScript)
-- Validation (platform whitelist)
-- Fallback defaults
-
----
-
-## 🎉 Complete!
-
-All 5 tasks implemented and tested:
-1. ✅ Logo with WP Media Library
-2. ✅ Footer {current_year} variable
-3. ✅ Social links
-4. ✅ Backend API & email rendering
-5. ✅ Hero text color
-
-**Ready for production!** 🚀

admin-spa/EMAIL_UX_REFINEMENTS_COMPLETE.md

@@ -1,532 +0,0 @@
-# Email Builder UX Refinements - Complete! 🎉
-
-**Date:** November 13, 2025  
-**Status:** ✅ ALL TASKS COMPLETE
-
----
-
-## Overview
-
-Successfully implemented all 7 major refinements to the email builder UX, including expanded social media integration, color customization, and comprehensive default email templates for all notification events.
-
----
-
-## ✅ Task 1: Expanded Social Media Platforms
-
-### Platforms Added
-- **Original:** Facebook, Twitter, Instagram, LinkedIn, YouTube, Website
-- **New Additions:**
-  - X (Twitter rebrand)
-  - Discord
-  - Spotify
-  - Telegram
-  - WhatsApp
-  - Threads
-  - Website (Earth icon)
-
-### Implementation
-- **Frontend:** `EmailCustomization.tsx`
-  - Updated `getSocialIcon()` with all Lucide icons
-  - Expanded select dropdown with all platforms
-  - Each platform has appropriate icon and label
-
-- **Backend:** `NotificationsController.php`
-  - Updated `allowed_platforms` array
-  - Validation for all new platforms
-  - Sanitization maintained
-
-### Files Modified
-- `admin-spa/src/routes/Settings/Notifications/EmailCustomization.tsx`
-- `includes/Api/NotificationsController.php`
-
----
-
-## ✅ Task 2: PNG Icons Instead of Emoji
-
-### Icon Assets
-- **Location:** `/assets/icons/`
-- **Format:** `mage--{platform}-{color}.png`
-- **Platforms:** All 11 social platforms
-- **Colors:** Black and White variants (22 total files)
-
-### Implementation
-- **Email Rendering:** `EmailRenderer.php`
-  - Updated `get_social_icon_url()` to return PNG URLs
-  - Uses plugin URL + assets path
-  - Dynamic color selection
-
-- **Preview:** `EditTemplate.tsx`
-  - PNG icons in preview HTML
-  - Uses `pluginUrl` from window object
-  - Matches actual email rendering
-
-### Benefits
-- More accurate than emoji
-- Consistent across email clients
-- Professional appearance
-- Better control over styling
-
-### Files Modified
-- `includes/Core/Notifications/EmailRenderer.php`
-- `admin-spa/src/routes/Settings/Notifications/EditTemplate.tsx`
-
----
-
-## ✅ Task 3: Icon Color Selection (Black/White)
-
-### New Setting
-- **Field:** `social_icon_color`
-- **Type:** Select dropdown
-- **Options:** 
-  - White Icons (for dark backgrounds)
-  - Black Icons (for light backgrounds)
-- **Default:** White
-
-### Implementation
-- **Frontend:** `EmailCustomization.tsx`
-  - Select component with two options
-  - Clear labeling and description
-  - Saved with other settings
-
-- **Backend:** 
-  - `NotificationsController.php`: Validation (white/black only)
-  - `EmailRenderer.php`: Applied to icon URLs
-  - Default value in settings
-
-### Usage
-```php
-// Backend
-$icon_color = $email_settings['social_icon_color'] ?? 'white';
-$icon_url = $this->get_social_icon_url($platform, $icon_color);
-
-// Frontend
-const socialIconColor = settings.social_icon_color || 'white';
-```
-
-### Files Modified
-- `admin-spa/src/routes/Settings/Notifications/EmailCustomization.tsx`
-- `includes/Api/NotificationsController.php`
-- `includes/Core/Notifications/EmailRenderer.php`
-- `admin-spa/src/routes/Settings/Notifications/EditTemplate.tsx`
-
----
-
-## ✅ Task 4: Body Background Color Setting
-
-### New Setting
-- **Field:** `body_bg_color`
-- **Type:** Color picker + hex input
-- **Default:** `#f8f8f8` (light gray)
-
-### Implementation
-- **UI Component:**
-  - Color picker for visual selection
-  - Text input for hex code entry
-  - Live preview in customization form
-  - Descriptive help text
-
-- **Application:**
-  - Email body background in actual emails
-  - Preview iframe background
-  - Consistent across all email templates
-
-### Usage
-```typescript
-// Frontend
-const bodyBgColor = settings.body_bg_color || '#f8f8f8';
-
-// Applied to preview
-body { background: ${bodyBgColor}; }
-```
-
-### Files Modified
-- `admin-spa/src/routes/Settings/Notifications/EmailCustomization.tsx`
-- `includes/Api/NotificationsController.php`
-- `admin-spa/src/routes/Settings/Notifications/EditTemplate.tsx`
-
----
-
-## ✅ Task 5: Editor Mode Preview Styling
-
-### Current Behavior
-- **Editor Mode:** Shows content structure (blocks, HTML)
-- **Preview Mode:** Shows final styled result with all customizations
-
-### Design Decision
-This is **intentional and follows standard email builder UX patterns**:
-- Editor mode = content editing focus
-- Preview mode = visual result preview
-- Separation of concerns improves usability
-
-### Rationale
-- Users edit content in editor mode without distraction
-- Preview mode shows exact final appearance
-- Standard pattern in tools like Mailchimp, SendGrid, etc.
-- Prevents confusion between editing and viewing
-
-### Status
-✅ **Working as designed** - No changes needed
-
----
-
-## ✅ Task 6: Hero Preview Text Color Fix
-
-### Issue
-Hero card preview in customization form wasn't using selected `hero_text_color`.
-
-### Solution
-Applied color directly to child elements instead of parent:
-
-```tsx
-// Before (color inheritance not working)
-<div style={{ background: gradient, color: heroTextColor }}>
-  <h3>Preview</h3>
-  <p>Text</p>
-</div>
-
-// After (explicit color on each element)
-<div style={{ background: gradient }}>
-  <h3 style={{ color: heroTextColor }}>Preview</h3>
-  <p style={{ color: heroTextColor }}>Text</p>
-</div>
-```
-
-### Result
-- Hero preview now correctly shows selected text color
-- Live updates as user changes color
-- Matches actual email rendering
-
-### Files Modified
-- `admin-spa/src/routes/Settings/Notifications/EmailCustomization.tsx`
-
----
-
-## ✅ Task 7: Complete Default Email Content
-
-### New File Created
-**`includes/Core/Notifications/DefaultEmailTemplates.php`**
-
-Comprehensive default templates for all notification events with professional, card-based HTML.
-
-### Templates Included
-
-#### Order Events
-
-**1. Order Placed (Staff)**
-```
-[card type="hero"]
-  New Order Received!
-  Order from {customer_name}
-[/card]
-[card] Order Details [/card]
-[card] Customer Details [/card]
-[card] Order Items [/card]
-[button] View Order Details [/button]
-```
-
-**2. Order Processing (Customer)**
-```
-[card type="success"]
-  Order Confirmed!
-  Thank you message
-[/card]
-[card] Order Summary [/card]
-[card] What's Next [/card]
-[card] Order Items [/card]
-[button] Track Your Order [/button]
-```
-
-**3. Order Completed (Customer)**
-```
-[card type="success"]
-  Order Completed!
-  Enjoy your purchase
-[/card]
-[card] Order Details [/card]
-[card] Thank You Message [/card]
-[button] View Order [/button]
-[button outline] Continue Shopping [/button]
-```
-
-**4. Order Cancelled (Staff)**
-```
-[card type="warning"]
-  Order Cancelled
-[/card]
-[card] Order Details [/card]
-[button] View Order Details [/button]
-```
-
-**5. Order Refunded (Customer)**
-```
-[card type="info"]
-  Refund Processed
-[/card]
-[card] Refund Details [/card]
-[card] What Happens Next [/card]
-[button] View Order [/button]
-```
-
-#### Product Events
-
-**6. Low Stock Alert (Staff)**
-```
-[card type="warning"]
-  Low Stock Alert
-[/card]
-[card] Product Details [/card]
-[card] Action Required [/card]
-[button] View Product [/button]
-```
-
-**7. Out of Stock Alert (Staff)**
-```
-[card type="warning"]
-  Out of Stock Alert
-[/card]
-[card] Product Details [/card]
-[card] Immediate Action Required [/card]
-[button] Manage Product [/button]
-```
-
-#### Customer Events
-
-**8. New Customer (Customer)**
-```
-[card type="hero"]
-  Welcome!
-  Thank you for creating an account
-[/card]
-[card] Your Account Details [/card]
-[card] Get Started (feature list) [/card]
-[button] Go to My Account [/button]
-[button outline] Start Shopping [/button]
-```
-
-**9. Customer Note (Customer)**
-```
-[card type="info"]
-  Order Note Added
-[/card]
-[card] Order Details [/card]
-[card] Note from Store [/card]
-[button] View Order [/button]
-```
-
-### Integration
-
-**Updated `TemplateProvider.php`:**
-```php
-public static function get_default_templates() {
-    // Generate email templates from DefaultEmailTemplates
-    foreach ($events as $event_id => $recipient_type) {
-        $default = DefaultEmailTemplates::get_template($event_id, $recipient_type);
-        $templates["{$event_id}_email"] = [
-            'event_id' => $event_id,
-            'channel_id' => 'email',
-            'subject' => $default['subject'],
-            'body' => $default['body'],
-            'variables' => self::get_variables_for_event($event_id),
-        ];
-    }
-    // ... push templates
-}
-```
-
-### Features
-- ✅ All 9 events covered
-- ✅ Separate staff/customer templates
-- ✅ Professional copy and structure
-- ✅ Card-based modern design
-- ✅ Multiple card types (hero, success, warning, info)
-- ✅ Multiple buttons with styles
-- ✅ Proper variable placeholders
-- ✅ Consistent branding
-- ✅ Push notification templates included
-
-### Files Created/Modified
-- `includes/Core/Notifications/DefaultEmailTemplates.php` (NEW)
-- `includes/Core/Notifications/TemplateProvider.php` (UPDATED)
-
----
-
-## Technical Summary
-
-### Settings Schema
-
-```typescript
-interface EmailSettings {
-  // Colors
-  primary_color: string;           // #7f54b3
-  secondary_color: string;         // #7f54b3
-  hero_gradient_start: string;     // #667eea
-  hero_gradient_end: string;       // #764ba2
-  hero_text_color: string;         // #ffffff
-  button_text_color: string;       // #ffffff
-  body_bg_color: string;           // #f8f8f8 (NEW)
-  social_icon_color: 'white' | 'black'; // (NEW)
-  
-  // Branding
-  logo_url: string;
-  header_text: string;
-  footer_text: string;
-  
-  // Social Links
-  social_links: Array<{
-    platform: string;  // 11 platforms supported
-    url: string;
-  }>;
-}
-```
-
-### API Endpoints
-
-```
-GET    /woonoow/v1/notifications/email-settings
-POST   /woonoow/v1/notifications/email-settings
-DELETE /woonoow/v1/notifications/email-settings
-```
-
-### Storage
-- **Option Key:** `woonoow_email_settings`
-- **Sanitization:** All inputs sanitized
-- **Validation:** Colors, URLs, platforms validated
-- **Defaults:** Comprehensive defaults provided
-
----
-
-## Testing Checklist
-
-### Social Media Integration
-- [x] All 11 platforms appear in dropdown
-- [x] Icons display correctly in customization UI
-- [x] PNG icons render in email preview
-- [x] PNG icons render in actual emails
-- [x] Black/white icon selection works
-- [x] Social links save and load correctly
-
-### Color Settings
-- [x] Body background color picker works
-- [x] Body background applies to preview
-- [x] Body background applies to emails
-- [x] Icon color selection works
-- [x] Hero text color preview fixed
-- [x] All colors save and persist
-
-### Default Templates
-- [x] All 9 email events have templates
-- [x] Staff templates appropriate for admins
-- [x] Customer templates appropriate for customers
-- [x] Card syntax correct
-- [x] Variables properly placed
-- [x] Buttons included where needed
-- [x] Push templates complete
-
-### Integration
-- [x] Settings API working
-- [x] Frontend loads settings
-- [x] Preview reflects settings
-- [x] Emails use settings
-- [x] Reset functionality works
-- [x] Save functionality works
-
----
-
-## Files Changed
-
-### Frontend (React/TypeScript)
-```
-admin-spa/src/routes/Settings/Notifications/
-├── EmailCustomization.tsx    (Updated - UI for all settings)
-└── EditTemplate.tsx          (Updated - Preview with PNG icons)
-```
-
-### Backend (PHP)
-```
-includes/
-├── Api/
-│   └── NotificationsController.php     (Updated - API endpoints)
-└── Core/Notifications/
-    ├── EmailRenderer.php               (Updated - PNG icons, colors)
-    ├── TemplateProvider.php            (Updated - Integration)
-    └── DefaultEmailTemplates.php       (NEW - All default content)
-```
-
-### Assets
-```
-assets/icons/
-├── mage--discord-black.png
-├── mage--discord-white.png
-├── mage--earth-black.png
-├── mage--earth-white.png
-├── mage--facebook-black.png
-├── mage--facebook-white.png
-├── mage--instagram-black.png
-├── mage--instagram-white.png
-├── mage--linkedin-black.png
-├── mage--linkedin-white.png
-├── mage--spotify-black.png
-├── mage--spotify-white.png
-├── mage--telegram-black.png
-├── mage--telegram-white.png
-├── mage--threads-black.png
-├── mage--threads-white.png
-├── mage--whatsapp-black.png
-├── mage--whatsapp-white.png
-├── mage--x-black.png
-├── mage--x-white.png
-├── mage--youtube-black.png
-└── mage--youtube-white.png
-```
-
----
-
-## Next Steps (Optional Enhancements)
-
-### Future Improvements
-1. **Email Template Variables**
-   - Add more dynamic variables
-   - Variable preview in editor
-   - Variable documentation
-
-2. **Template Library**
-   - Pre-built template variations
-   - Industry-specific templates
-   - Seasonal templates
-
-3. **A/B Testing**
-   - Test different subject lines
-   - Test different layouts
-   - Analytics integration
-
-4. **Advanced Customization**
-   - Font family selection
-   - Font size controls
-   - Spacing/padding controls
-   - Border radius controls
-
-5. **Conditional Content**
-   - Show/hide based on order value
-   - Show/hide based on customer type
-   - Dynamic product recommendations
-
----
-
-## Conclusion
-
-All 7 tasks successfully completed! The email builder now has:
-- ✅ Expanded social media platform support (11 platforms)
-- ✅ Professional PNG icons with color selection
-- ✅ Body background color customization
-- ✅ Fixed hero preview text color
-- ✅ Complete default templates for all events
-- ✅ Comprehensive documentation
-
-The email system is now production-ready with professional defaults and extensive customization options.
-
-**Total Commits:** 2
-**Total Files Modified:** 6
-**Total Files Created:** 23 (22 icons + 1 template class)
-**Lines of Code:** ~1,500+
-
-🎉 **Project Status: COMPLETE**

admin-spa/FINAL_UX_IMPROVEMENTS.md

@@ -1,414 +0,0 @@
-# Final UX Improvements - Session Complete! 🎉
-
-## All 6 Improvements Implemented
-
----
-
-## 1. ✅ Dialog Scrollable Body with Fixed Header/Footer
-
-### Problem
-Long content made header (with close button) and footer (with action buttons) disappear. Users couldn't close dialog or take action.
-
-### Solution
-- Changed dialog to flexbox layout (`flex flex-col`)
-- Added `DialogBody` component with `overflow-y-auto`
-- Header and footer fixed with borders
-- Max height `90vh` for viewport fit
-
-### Structure
-```tsx
-<DialogContent> (flex flex-col max-h-[90vh])
-  <DialogHeader> (px-6 pt-6 pb-4 border-b) - FIXED
-  <DialogBody> (flex-1 overflow-y-auto px-6 py-4) - SCROLLABLE
-  <DialogFooter> (px-6 py-4 border-t mt-auto) - FIXED
-</DialogContent>
-```
-
-### Files
-- `components/ui/dialog.tsx`
-- `components/ui/rich-text-editor.tsx`
-
----
-
-## 2. ✅ Dialog Close-Proof (No Outside Click)
-
-### Problem
-Accidental outside clicks closed dialog, losing user input and causing confusion.
-
-### Solution
-```tsx
-<DialogPrimitive.Content
-  onPointerDownOutside={(e) => e.preventDefault()}
-  onInteractOutside={(e) => e.preventDefault()}
->
-```
-
-### Result
-- Must click X button or Cancel to close
-- No accidental dismissal
-- No lost UI control
-- Better user confidence
-
-### Files
-- `components/ui/dialog.tsx`
-
----
-
-## 3. ✅ Code Mode Button Moved to Left
-
-### Problem
-Inconsistent layout - Code Mode button was grouped with Editor/Preview tabs on the right.
-
-### Solution
-Moved Code Mode button next to "Message Body" label on the left.
-
-### Before
-```
-Message Body                [Editor|Preview] [Code Mode]
-```
-
-### After
-```
-Message Body [Code Mode]                [Editor|Preview]
-```
-
-### Result
-- Logical grouping
-- Editor/Preview tabs stay together on right
-- Code Mode is a mode toggle, not a tab
-- Consistent, professional layout
-
-### Files
-- `routes/Settings/Notifications/EditTemplate.tsx`
-
----
-
-## 4. ✅ Markdown Support in Code Mode! 🎉
-
-### Problem
-HTML is verbose and not user-friendly for tech-savvy users who prefer Markdown.
-
-### Solution
-Full Markdown support with custom syntax for email-specific features.
-
-### Markdown Syntax
-
-**Standard Markdown:**
-```markdown
-# Heading 1
-## Heading 2
-### Heading 3
-
-**Bold text**
-*Italic text*
-
-- List item 1
-- List item 2
-
-[Link text](https://example.com)
-```
-
-**Card Blocks:**
-```markdown
-:::card
-# Your heading
-Your content here
-:::
-
-:::card[success]
-✅ Success message
-:::
-
-:::card[warning]
-⚠️ Warning message
-:::
-```
-
-**Button Blocks:**
-```markdown
-[button](https://example.com){Click Here}
-
-[button style="outline"](https://example.com){Secondary Button}
-```
-
-**Variables:**
-```markdown
-Hi {customer_name},
-
-Your order #{order_number} totaling {order_total} is ready!
-```
-
-### Features
-- Bidirectional conversion (HTML ↔ Markdown)
-- Toggle button: "📝 Switch to Markdown" / "🔧 Switch to HTML"
-- Syntax highlighting for both modes
-- Preserves all email features
-- Easier for non-HTML users
-
-### Files
-- `lib/markdown-parser.ts` - Parser implementation
-- `components/ui/code-editor.tsx` - Mode toggle
-- `routes/Settings/Notifications/EditTemplate.tsx` - Enable support
-
-### Dependencies
-```bash
-npm install @codemirror/lang-markdown
-```
-
----
-
-## 5. ✅ Realistic Variable Simulations in Preview
-
-### Problem
-Variables showed as raw text like `{order_items_list}` in preview, making it hard to judge layout.
-
-### Solution
-Added realistic HTML simulations for better preview experience.
-
-### order_items_list Simulation
-```html
-<ul style="list-style: none; padding: 0; margin: 16px 0;">
-  <li style="padding: 12px; background: #f9f9f9; border-radius: 6px; margin-bottom: 8px;">
-    <strong>Premium T-Shirt</strong> × 2<br>
-    <span style="color: #666;">Size: L, Color: Blue</span><br>
-    <span style="font-weight: 600;">$49.98</span>
-  </li>
-  <li style="padding: 12px; background: #f9f9f9; border-radius: 6px; margin-bottom: 8px;">
-    <strong>Classic Jeans</strong> × 1<br>
-    <span style="color: #666;">Size: 32, Color: Dark Blue</span><br>
-    <span style="font-weight: 600;">$79.99</span>
-  </li>
-</ul>
-```
-
-### order_items_table Simulation
-```html
-<table style="width: 100%; border-collapse: collapse; margin: 16px 0;">
-  <thead>
-    <tr style="background: #f5f5f5;">
-      <th style="padding: 12px; text-align: left;">Product</th>
-      <th style="padding: 12px; text-align: center;">Qty</th>
-      <th style="padding: 12px; text-align: right;">Price</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td style="padding: 12px;">
-        <strong>Premium T-Shirt</strong><br>
-        <span style="color: #666; font-size: 13px;">Size: L, Color: Blue</span>
-      </td>
-      <td style="padding: 12px; text-align: center;">2</td>
-      <td style="padding: 12px; text-align: right;">$49.98</td>
-    </tr>
-  </tbody>
-</table>
-```
-
-### Result
-- Users see realistic email preview
-- Can judge layout and design accurately
-- No guessing what variables will look like
-- Professional presentation
-- Better design decisions
-
-### Files
-- `routes/Settings/Notifications/EditTemplate.tsx`
-
----
-
-## 6. ✅ Smart Back Navigation to Accordion
-
-### Problem
-- Back button used `navigate(-1)`
-- Returned to parent page but wrong tab
-- Required 2-3 clicks to get back to Email accordion
-- Lost context, poor UX
-
-### Solution
-Navigate with query params to preserve context.
-
-### Implementation
-
-**EditTemplate.tsx:**
-```tsx
-<Button onClick={() => navigate(`/settings/notifications?tab=${channelId}&event=${eventId}`)}>
-  Back
-</Button>
-```
-
-**Templates.tsx:**
-```tsx
-const [openAccordion, setOpenAccordion] = useState<string | undefined>();
-
-useEffect(() => {
-  const eventParam = searchParams.get('event');
-  if (eventParam) {
-    setOpenAccordion(eventParam);
-  }
-}, [searchParams]);
-
-<Accordion value={openAccordion} onValueChange={setOpenAccordion}>
-  {/* ... */}
-</Accordion>
-```
-
-### User Flow
-1. User in Email accordion, editing "Order Placed" template
-2. Clicks Back button
-3. Returns to Notifications page with `?tab=email&event=order_placed`
-4. Email accordion auto-opens
-5. "Order Placed" template visible
-6. Perfect context preservation!
-
-### Result
-- One-click return to context
-- No confusion
-- No extra clicks
-- Professional navigation
-- Context always preserved
-
-### Files
-- `routes/Settings/Notifications/EditTemplate.tsx`
-- `routes/Settings/Notifications/Templates.tsx`
-
----
-
-## Summary
-
-### What We Built
-Six critical UX improvements that transform the email builder from good to **perfect**.
-
-### Key Achievements
-
-1. **Healthy Dialogs** - Scrollable body, fixed header/footer, no accidental closing
-2. **Logical Layout** - Code Mode button in correct position
-3. **Markdown Support** - Easier editing for tech-savvy users
-4. **Realistic Previews** - See exactly what emails will look like
-5. **Smart Navigation** - Context-aware back button
-
-### Impact
-
-**For Users:**
-- No frustration
-- Faster workflow
-- Better previews
-- Professional tools
-- Intuitive navigation
-
-**For Business:**
-- Happy users
-- Fewer support tickets
-- Better email designs
-- Professional product
-- Competitive advantage
-
----
-
-## Testing Checklist
-
-### 1. Dialog Improvements
-- [ ] Paste long content in dialog
-- [ ] Verify header stays visible
-- [ ] Verify footer stays visible
-- [ ] Body scrolls independently
-- [ ] Click outside dialog - should NOT close
-- [ ] Click X button - closes
-- [ ] Click Cancel - closes
-
-### 2. Code Mode Button
-- [ ] Verify button is left of label
-- [ ] Verify Editor/Preview tabs on right
-- [ ] Toggle Code Mode
-- [ ] Layout looks professional
-
-### 3. Markdown Support
-- [ ] Toggle to Markdown mode
-- [ ] Write Markdown syntax
-- [ ] Use :::card blocks
-- [ ] Use [button] syntax
-- [ ] Toggle back to HTML
-- [ ] Verify conversion works both ways
-
-### 4. Variable Simulations
-- [ ] Use {order_items_list} in template
-- [ ] Preview shows realistic list
-- [ ] Use {order_items_table} in template
-- [ ] Preview shows realistic table
-- [ ] Verify styling looks good
-
-### 5. Back Navigation
-- [ ] Open Email accordion
-- [ ] Edit a template
-- [ ] Click Back
-- [ ] Verify returns to Email accordion
-- [ ] Verify accordion is open
-- [ ] Verify correct template visible
-
----
-
-## Dependencies
-
-### New Package Required
-```bash
-npm install @codemirror/lang-markdown
-```
-
-### Complete Install Command
-```bash
-cd admin-spa
-npm install @tiptap/extension-text-align @tiptap/extension-image codemirror @codemirror/lang-html @codemirror/lang-markdown @codemirror/theme-one-dark @radix-ui/react-radio-group
-```
-
----
-
-## Files Modified
-
-### Components
-1. `components/ui/dialog.tsx` - Scrollable body, close-proof
-2. `components/ui/code-editor.tsx` - Markdown support
-3. `components/ui/rich-text-editor.tsx` - Use DialogBody
-
-### Routes
-4. `routes/Settings/Notifications/EditTemplate.tsx` - Layout, simulations, navigation
-5. `routes/Settings/Notifications/Templates.tsx` - Accordion state management
-
-### Libraries
-6. `lib/markdown-parser.ts` - NEW - Markdown ↔ HTML conversion
-
-### Documentation
-7. `DEPENDENCIES.md` - Updated with markdown package
-
----
-
-## 🎉 Result
-
-**The PERFECT email builder experience!**
-
-All user feedback addressed:
-- ✅ Healthy dialogs
-- ✅ Logical layout
-- ✅ Markdown support
-- ✅ Realistic previews
-- ✅ Smart navigation
-- ✅ Professional UX
-
-**Ready for production!** 🚀
-
----
-
-## Notes
-
-### Lint Warnings
-The following lint warnings are expected and can be ignored:
-- `mso-table-lspace` and `mso-table-rspace` in `templates/emails/modern.html` - These are Microsoft Outlook-specific CSS properties
-
-### Future Enhancements
-- Variable categorization (order vs account vs product)
-- Color customization UI
-- More default templates
-- Template preview mode
-- A/B testing support
-
----
-
-**Session Complete! All 6 improvements implemented successfully!** ✨

admin-spa/UX_IMPROVEMENTS.md

@@ -1,424 +0,0 @@
-# UX Improvements - Perfect Builder Experience! 🎯
-
-## Overview
-
-Six major UX improvements implemented to create the perfect email builder experience. These changes address real user pain points and make the builder intuitive and professional.
-
----
-
-## 1. Prevent Link/Button Navigation in Builder ✅
-
-### Problem
-- Clicking links or buttons in the builder redirected users
-- Users couldn't edit button text (clicking opened the link)
-- Frustrating experience, broke editing workflow
-
-### Solution
-**BlockRenderer (Email Builder):**
-```typescript
-const handleClick = (e: React.MouseEvent) => {
-  const target = e.target as HTMLElement;
-  if (target.tagName === 'A' || target.tagName === 'BUTTON' || 
-      target.closest('a') || target.closest('button')) {
-    e.preventDefault();
-    e.stopPropagation();
-  }
-};
-
-return (
-  <div className="group relative" onClick={handleClick}>
-    {/* Block content */}
-  </div>
-);
-```
-
-**RichTextEditor (TipTap):**
-```typescript
-editorProps: {
-  handleClick: (view, pos, event) => {
-    const target = event.target as HTMLElement;
-    if (target.tagName === 'A' || target.closest('a')) {
-      event.preventDefault();
-      return true;
-    }
-    return false;
-  },
-}
-```
-
-### Result
-- Links and buttons are now **editable only**
-- No accidental navigation
-- Click to edit, not to follow
-- Perfect editing experience
-
----
-
-## 2. Default Templates Use Raw Buttons ✅
-
-### Problem
-- Default templates had buttons wrapped in cards:
-  ```html
-  [card]
-  <p style="text-align: center;">
-    <a href="{order_url}" class="button">View Order</a>
-  </p>
-  [/card]
-  ```
-- Didn't match current block structure
-- Confusing for users
-
-### Solution
-Changed to raw button blocks:
-```html
-[button link="{order_url}" style="solid"]View Order Details[/button]
-```
-
-### Before & After
-
-**Before:**
-```
-[card]
-  <p><a class="button">Track Order</a></p>
-  <p>Questions? Contact us.</p>
-[/card]
-```
-
-**After:**
-```
-[button link="{order_url}" style="solid"]Track Your Order[/button]
-
-[card]
-  <p>Questions? Contact us.</p>
-[/card]
-```
-
-### Result
-- Matches block structure
-- Buttons are standalone blocks
-- Easier to edit and rearrange
-- Consistent with builder UI
-
----
-
-## 3. Split Order Items: List & Table ✅
-
-### Problem
-- Only one `{order_items}` variable
-- No control over presentation format
-- Users want different styles for different emails
-
-### Solution
-Split into two variables:
-
-**`{order_items_list}`** - Formatted List
-```html
-<ul>
-  <li>Product Name × 2 - $50.00</li>
-  <li>Another Product × 1 - $25.00</li>
-</ul>
-```
-
-**`{order_items_table}`** - Formatted Table
-```html
-<table>
-  <thead>
-    <tr>
-      <th>Product</th>
-      <th>Qty</th>
-      <th>Price</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Product Name</td>
-      <td>2</td>
-      <td>$50.00</td>
-    </tr>
-  </tbody>
-</table>
-```
-
-### Use Cases
-- **List format**: Simple, compact, mobile-friendly
-- **Table format**: Detailed, professional, desktop-optimized
-
-### Result
-- Better control over presentation
-- Choose format based on email type
-- Professional-looking order summaries
-
----
-
-## 4. Payment URL Variable Added ✅
-
-### Problem
-- No way to link to payment page
-- Users couldn't send payment reminders
-- Missing critical functionality
-
-### Solution
-Added `{payment_url}` variable with smart strategy:
-
-**Strategy:**
-```php
-if (manual_payment) {
-  // Use order details URL or thank you page
-  // Contains payment instructions
-  $payment_url = get_order_url();
-} else if (api_payment) {
-  // Use payment gateway URL
-  // From order payment_meta
-  $payment_url = get_payment_gateway_url();
-}
-```
-
-**Implementation:**
-```php
-'payment_url' => __('Payment URL (for pending payments)', 'woonoow'),
-```
-
-### Use Cases
-- **Pending payment emails**: "Complete your payment"
-- **Failed payment emails**: "Retry payment"
-- **Payment reminder emails**: "Your payment is waiting"
-
-### Example
-```html
-[card type="warning"]
-<h2>⏳ Payment Pending</h2>
-<p>Your order is waiting for payment.</p>
-[/card]
-
-[button link="{payment_url}" style="solid"]Complete Payment[/button]
-```
-
-### Result
-- Complete payment workflow
-- Better conversion rates
-- Professional payment reminders
-
----
-
-## 5. Variable Categorization Strategy 📝
-
-### Problem
-- All variables shown for all events
-- Confusing (why show `order_items` for account emails?)
-- Poor UX
-
-### Strategy (For Future Implementation)
-
-**Order-Related Events:**
-```javascript
-{
-  order_number, order_total, order_status,
-  order_items_list, order_items_table,
-  payment_url, tracking_number,
-  customer_name, customer_email,
-  shipping_address, billing_address
-}
-```
-
-**Account-Related Events:**
-```javascript
-{
-  customer_name, customer_email,
-  login_url, account_url,
-  reset_password_url
-}
-```
-
-**Product-Related Events:**
-```javascript
-{
-  product_name, product_url,
-  product_price, product_image,
-  stock_quantity
-}
-```
-
-### Implementation Plan
-1. Add event categories to event definitions
-2. Filter variables by event category
-3. Show only relevant variables in UI
-4. Better UX, less confusion
-
-### Result (When Implemented)
-- Contextual variables only
-- Cleaner UI
-- Faster template creation
-- Less user confusion
-
----
-
-## 6. WordPress Media Library Fixed ✅
-
-### Problem
-- WordPress Media library not loaded
-- Error: "WordPress media library is not loaded"
-- Browser prompt fallback (poor UX)
-- Store logos/favicon upload broken
-
-### Root Cause
-```php
-// Missing in Assets.php
-wp_enqueue_media(); // ← Not called!
-```
-
-### Solution
-
-**Assets.php:**
-```php
-public static function enqueue($hook) {
-    if ($hook !== 'toplevel_page_woonoow') {
-        return;
-    }
-
-    // Enqueue WordPress Media library for image uploads
-    wp_enqueue_media(); // ← Added!
-
-    // ... rest of code
-}
-```
-
-**wp-media.ts (Better Error Handling):**
-```typescript
-if (typeof window.wp === 'undefined' || typeof window.wp.media === 'undefined') {
-  console.error('WordPress media library is not available');
-  console.error('window.wp:', typeof window.wp);
-  console.error('window.wp.media:', typeof (window as any).wp?.media);
-  
-  alert('WordPress Media library is not loaded.\n\n' +
-        'Please ensure you are in WordPress admin and the page has fully loaded.\n\n' +
-        'If the problem persists, try refreshing the page.');
-  return;
-}
-```
-
-### Result
-- WordPress Media Modal loads properly
-- No more errors
-- Professional image selection
-- Store logos/favicon upload works
-- Better error messages with debugging info
-
----
-
-## Testing Checklist
-
-### 1. Link/Button Navigation
-- [ ] Click link in card content → no navigation
-- [ ] Click button in builder → no navigation
-- [ ] Click button in RichTextEditor → no navigation
-- [ ] Edit button text by clicking → works
-- [ ] Links/buttons work in email preview
-
-### 2. Default Templates
-- [ ] Create new template from default
-- [ ] Verify buttons are standalone blocks
-- [ ] Verify buttons not wrapped in cards
-- [ ] Edit button easily
-- [ ] Rearrange blocks easily
-
-### 3. Order Items Variables
-- [ ] Insert `{order_items_list}` → shows list format
-- [ ] Insert `{order_items_table}` → shows table format
-- [ ] Preview both formats
-- [ ] Verify formatting in email
-
-### 4. Payment URL
-- [ ] Insert `{payment_url}` in button
-- [ ] Verify variable appears in list
-- [ ] Test with pending payment order
-- [ ] Test with manual payment
-- [ ] Test with API payment gateway
-
-### 5. WordPress Media
-- [ ] Click image icon in RichTextEditor
-- [ ] Verify WP Media Modal opens
-- [ ] Select image from library
-- [ ] Upload new image
-- [ ] Click "Choose from Media Library" in Store settings
-- [ ] Upload logo (light mode)
-- [ ] Upload logo (dark mode)
-- [ ] Upload favicon
-
----
-
-## Summary
-
-### What We Built
-A **perfect email builder experience** with:
-- No accidental navigation
-- Intuitive block structure
-- Flexible content formatting
-- Complete payment workflow
-- Professional image management
-
-### Key Achievements
-
-1. **✅ No Navigation in Builder** - Links/buttons editable only
-2. **✅ Raw Button Blocks** - Matches current structure
-3. **✅ List & Table Formats** - Better control
-4. **✅ Payment URL** - Complete workflow
-5. **📝 Variable Strategy** - Future improvement
-6. **✅ WP Media Fixed** - Professional uploads
-
-### Impact
-
-**For Users:**
-- Faster template creation
-- No frustration
-- Professional results
-- Intuitive workflow
-
-**For Business:**
-- Better conversion (payment URLs)
-- Professional emails
-- Happy users
-- Fewer support tickets
-
----
-
-## Files Modified
-
-### Frontend (TypeScript/React)
-1. `components/EmailBuilder/BlockRenderer.tsx` - Prevent navigation
-2. `components/ui/rich-text-editor.tsx` - Prevent navigation
-3. `lib/wp-media.ts` - Better error handling
-
-### Backend (PHP)
-4. `includes/Admin/Assets.php` - Enqueue WP Media
-5. `includes/Core/Notifications/TemplateProvider.php` - Variables & defaults
-
----
-
-## Next Steps
-
-### Immediate
-1. Test all features
-2. Verify WP Media loads
-3. Test payment URL generation
-4. Verify order items formatting
-
-### Future
-1. Implement variable categorization
-2. Add color customization UI
-3. Create more default templates
-4. Add template preview mode
-
----
-
-## 🎉 Result
-
-**The PERFECT email builder experience!**
-
-All pain points addressed:
-- ✅ No accidental navigation
-- ✅ Intuitive editing
-- ✅ Professional features
-- ✅ WordPress integration
-- ✅ Complete workflow
-
-**Ready for production!** 🚀

admin-spa/package.json

@@ -49,14 +49,17 @@
         "qrcode": "^1.5.4",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
+        "react-markdown": "^10.1.0",
         "react-router-dom": "^7.9.4",
         "recharts": "^3.3.0",
+        "remark-gfm": "^4.0.1",
         "sonner": "^2.0.7",
         "tailwind-merge": "^3.3.1",
         "vaul": "^1.1.2",
         "zustand": "^5.0.8"
     },
     "devDependencies": {
+        "@tailwindcss/typography": "^0.5.19",
         "@types/react": "^18.3.5",
         "@types/react-dom": "^18.3.0",
         "@typescript-eslint/eslint-plugin": "^8.46.3",

admin-spa/postcss.config.cjs

@@ -1 +0,0 @@
-module.exports = { plugins: { tailwindcss: {}, autoprefixer: {} } };

admin-spa/src/App.tsx

@@ -1,745 +1,39 @@
-import React, { useEffect, useState } from 'react';
-import { HashRouter, Routes, Route, NavLink, useLocation, useParams, Navigate, Link } from 'react-router-dom';
-import { Login } from './routes/Login';
-import ResetPassword from './routes/ResetPassword';
-import Dashboard from '@/routes/Dashboard';
-import DashboardRevenue from '@/routes/Dashboard/Revenue';
-import DashboardOrders from '@/routes/Dashboard/Orders';
-import DashboardProducts from '@/routes/Dashboard/Products';
-import DashboardCustomers from '@/routes/Dashboard/Customers';
-import DashboardCoupons from '@/routes/Dashboard/Coupons';
-import DashboardTaxes from '@/routes/Dashboard/Taxes';
-import OrdersIndex from '@/routes/Orders';
-import OrderNew from '@/routes/Orders/New';
-import OrderEdit from '@/routes/Orders/Edit';
-import OrderDetail from '@/routes/Orders/Detail';
-import ProductsIndex from '@/routes/Products';
-import ProductNew from '@/routes/Products/New';
-import ProductEdit from '@/routes/Products/Edit';
-import ProductCategories from '@/routes/Products/Categories';
-import ProductTags from '@/routes/Products/Tags';
-import ProductAttributes from '@/routes/Products/Attributes';
-import CouponsIndex from '@/routes/Marketing/Coupons';
-import CouponNew from '@/routes/Marketing/Coupons/New';
-import CouponEdit from '@/routes/Marketing/Coupons/Edit';
-import CustomersIndex from '@/routes/Customers';
-import CustomerNew from '@/routes/Customers/New';
-import CustomerEdit from '@/routes/Customers/Edit';
-import CustomerDetail from '@/routes/Customers/Detail';
+import React from 'react';
+import { createHashRouter, RouterProvider, createRoutesFromElements, Route } from 'react-router-dom';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { LayoutDashboard, ReceiptText, Package, Tag, Users, Settings as SettingsIcon, Palette, Mail, Maximize2, Minimize2, Loader2 } from 'lucide-react';
 import { Toaster } from 'sonner';
-import { useShortcuts } from "@/hooks/useShortcuts";
-import { CommandPalette } from "@/components/CommandPalette";
-import { useCommandStore } from "@/lib/useCommandStore";
-import SubmenuBar from './components/nav/SubmenuBar';
-import DashboardSubmenuBar from './components/nav/DashboardSubmenuBar';
-import { DashboardProvider } from '@/contexts/DashboardContext';
-import { PageHeaderProvider } from '@/contexts/PageHeaderContext';
-import { FABProvider } from '@/contexts/FABContext';
-import { AppProvider } from '@/contexts/AppContext';
-import { PageHeader } from '@/components/PageHeader';
-import { BottomNav } from '@/components/nav/BottomNav';
-import { FAB } from '@/components/FAB';
-import { useActiveSection } from '@/hooks/useActiveSection';
-import { NAV_TREE_VERSION } from '@/nav/tree';
-import { __ } from '@/lib/i18n';
-import { ThemeToggle } from '@/components/ThemeToggle';
+import { useTheme } from '@/components/ThemeProvider';
 import { initializeWindowAPI } from '@/lib/windowAPI';
+import { Login } from './routes/Login';
+import { AuthWrapper } from './components/layout/AuthWrapper';
 
-function useFullscreen() {
-  const [on, setOn] = useState<boolean>(() => {
-    try { return localStorage.getItem('wnwFullscreen') === '1'; } catch { return false; }
-  });
-
-  useEffect(() => {
-    const id = 'wnw-fullscreen-style';
-    let style = document.getElementById(id);
-    if (!style) {
-      style = document.createElement('style');
-      style.id = id;
-      style.textContent = `
-        /* Hide WP admin chrome when fullscreen */
-        .wnw-fullscreen #wpadminbar,
-        .wnw-fullscreen #adminmenumain,
-        .wnw-fullscreen #screen-meta,
-        .wnw-fullscreen #screen-meta-links,
-        .wnw-fullscreen #wpfooter { display:none !important; }
-        .wnw-fullscreen #wpcontent { margin-left:0 !important; }
-        .wnw-fullscreen #wpbody-content { padding-bottom:0 !important; }
-        .wnw-fullscreen html, .wnw-fullscreen body { height: 100%; overflow: hidden; }
-        .wnw-fullscreen .woonoow-fullscreen-root {
-          position: fixed;
-          inset: 0;
-          z-index: 999;
-          background: var(--background, #fff);
-          height: 100dvh; /* ensure full viewport height on mobile/desktop */
-          overflow: hidden; /* prevent double scrollbars; inner <main> handles scrolling */
-          overscroll-behavior: contain;
-          display: flex;
-          flex-direction: column;
-          contain: layout paint size; /* prevent WP wrappers from affecting layout */
-        }
-      `;
-      document.head.appendChild(style);
-    }
-    document.body.classList.toggle('wnw-fullscreen', on);
-    try { localStorage.setItem('wnwFullscreen', on ? '1' : '0'); } catch { /* ignore localStorage errors */ }
-    return () => { /* do not remove style to avoid flicker between reloads */ };
-  }, [on]);
-
-  return { on, setOn } as const;
-}
-
-function ActiveNavLink({ to, startsWith, end, className, children, childPaths }: any) {
-  // Use the router location hook instead of reading from NavLink's className args
-  const location = useLocation();
-  const starts = typeof startsWith === 'string' && startsWith.length > 0 ? startsWith : undefined;
+function ToasterWithTheme() {
+  const { actualTheme } = useTheme();
   return (
-    <NavLink
-      to={to}
-      end={end}
-      className={(nav) => {
-        // Special case: Dashboard should ONLY match root path "/" or paths starting with "/dashboard"
-        const isDashboard = starts === '/dashboard' && (location.pathname === '/' || location.pathname.startsWith('/dashboard'));
-
-        // Check if current path matches any child paths (e.g., /coupons under Marketing)
-        const matchesChild = childPaths && Array.isArray(childPaths)
-          ? childPaths.some((childPath: string) => location.pathname.startsWith(childPath))
-          : false;
-
-        // For dashboard: only active if isDashboard is true
-        // For others: active if path starts with their path OR matches a child path
-        let activeByPath = false;
-        if (starts === '/dashboard') {
-          activeByPath = isDashboard;
-        } else if (starts) {
-          activeByPath = location.pathname.startsWith(starts) || matchesChild;
-        }
-
-        const mergedActive = nav.isActive || activeByPath;
-        if (typeof className === 'function') {
-          // Preserve caller pattern: className receives { isActive }
-          return className({ isActive: mergedActive });
-        }
-        return `${className ?? ''} ${mergedActive ? '' : ''}`.trim();
-      }}
-    >
-      {children}
-    </NavLink>
-  );
-}
-
-function Sidebar() {
-  const link = "flex items-center gap-2 rounded-md px-3 py-2 hover:bg-accent hover:text-accent-foreground shadow-none hover:shadow-none focus:shadow-none focus:outline-none focus:ring-0";
-  const active = "bg-secondary";
-  const { main } = useActiveSection();
-
-  // Icon mapping
-  const iconMap: Record<string, any> = {
-    'layout-dashboard': LayoutDashboard,
-    'receipt-text': ReceiptText,
-    'package': Package,
-    'tag': Tag,
-    'users': Users,
-    'mail': Mail,
-    'palette': Palette,
-    'settings': SettingsIcon,
-  };
-
-  // Get navigation tree from backend
-  const navTree = (window as any).WNW_NAV_TREE || [];
-
-  return (
-    <aside className="w-56 flex-shrink-0 p-3 border-r border-border sticky top-16 h-[calc(100vh-64px)] overflow-y-auto bg-background">
-      <nav className="flex flex-col gap-1">
-        {navTree.map((item: any) => {
-          const IconComponent = iconMap[item.icon] || Package;
-          const isActive = main.key === item.key;
-          return (
-            <Link
-              key={item.key}
-              to={item.path}
-              className={`${link} ${isActive ? active : ''}`}
-            >
-              <IconComponent className="w-4 h-4" />
-              <span>{item.label}</span>
-            </Link>
-          );
-        })}
-      </nav>
-    </aside>
-  );
-}
-
-function TopNav({ fullscreen = false }: { fullscreen?: boolean }) {
-  const link = "inline-flex items-center gap-2 rounded-md px-3 py-2 hover:bg-accent hover:text-accent-foreground shadow-none hover:shadow-none focus:shadow-none focus:outline-none focus:ring-0";
-  const active = "bg-secondary";
-  const topClass = fullscreen ? 'top-16' : 'top-[calc(4rem+32px)]';
-  const { main } = useActiveSection();
-
-  // Icon mapping (same as Sidebar)
-  const iconMap: Record<string, any> = {
-    'layout-dashboard': LayoutDashboard,
-    'receipt-text': ReceiptText,
-    'package': Package,
-    'tag': Tag,
-    'users': Users,
-    'mail': Mail,
-    'palette': Palette,
-    'settings': SettingsIcon,
-  };
-
-  // Get navigation tree from backend
-  const navTree = (window as any).WNW_NAV_TREE || [];
-
-  return (
-    <div className={`border-b border-border sticky ${topClass} z-30 bg-background md:bg-background/95 md:backdrop-blur md:supports-[backdrop-filter]:bg-background/60`}>
-      <div className="px-4 h-12 flex flex-nowrap overflow-auto items-center gap-2">
-        {navTree.map((item: any) => {
-          const IconComponent = iconMap[item.icon] || Package;
-          const isActive = main.key === item.key;
-          return (
-            <Link
-              key={item.key}
-              to={item.path}
-              className={`${link} ${isActive ? active : ''}`}
-            >
-              <IconComponent className="w-4 h-4" />
-              <span className="text-sm font-medium">{item.label}</span>
-            </Link>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-function useIsDesktop(minWidth = 1024) { // lg breakpoint
-  const [isDesktop, setIsDesktop] = useState<boolean>(() => {
-    if (typeof window === 'undefined') return false;
-    return window.matchMedia(`(min-width: ${minWidth}px)`).matches;
-  });
-  useEffect(() => {
-    const mq = window.matchMedia(`(min-width: ${minWidth}px)`);
-    const onChange = () => setIsDesktop(mq.matches);
-    try { mq.addEventListener('change', onChange); } catch { mq.addListener(onChange); }
-    return () => { try { mq.removeEventListener('change', onChange); } catch { mq.removeListener(onChange); } };
-  }, [minWidth]);
-  return isDesktop;
-}
-
-import SettingsIndex from '@/routes/Settings';
-import SettingsStore from '@/routes/Settings/Store';
-import SettingsPayments from '@/routes/Settings/Payments';
-import SettingsShipping from '@/routes/Settings/Shipping';
-import SettingsTax from '@/routes/Settings/Tax';
-import SettingsCustomers from '@/routes/Settings/Customers';
-import SettingsLocalPickup from '@/routes/Settings/LocalPickup';
-import SettingsNotifications from '@/routes/Settings/Notifications';
-import StaffNotifications from '@/routes/Settings/Notifications/Staff';
-import CustomerNotifications from '@/routes/Settings/Notifications/Customer';
-import ChannelConfiguration from '@/routes/Settings/Notifications/ChannelConfiguration';
-import EmailConfiguration from '@/routes/Settings/Notifications/EmailConfiguration';
-import PushConfiguration from '@/routes/Settings/Notifications/PushConfiguration';
-import EmailCustomization from '@/routes/Settings/Notifications/EmailCustomization';
-import EditTemplate from '@/routes/Settings/Notifications/EditTemplate';
-import SettingsDeveloper from '@/routes/Settings/Developer';
-import SettingsModules from '@/routes/Settings/Modules';
-import ModuleSettings from '@/routes/Settings/ModuleSettings';
-import AppearanceIndex from '@/routes/Appearance';
-import AppearanceGeneral from '@/routes/Appearance/General';
-import AppearanceHeader from '@/routes/Appearance/Header';
-import AppearanceFooter from '@/routes/Appearance/Footer';
-import AppearanceShop from '@/routes/Appearance/Shop';
-import AppearanceProduct from '@/routes/Appearance/Product';
-import AppearanceCart from '@/routes/Appearance/Cart';
-import AppearanceCheckout from '@/routes/Appearance/Checkout';
-import AppearanceThankYou from '@/routes/Appearance/ThankYou';
-import AppearanceAccount from '@/routes/Appearance/Account';
-import MarketingIndex from '@/routes/Marketing';
-import NewsletterSubscribers from '@/routes/Marketing/Newsletter';
-import CampaignsList from '@/routes/Marketing/Campaigns';
-import CampaignEdit from '@/routes/Marketing/Campaigns/Edit';
-import MorePage from '@/routes/More';
-
-// Addon Route Component - Dynamically loads addon components
-function AddonRoute({ config }: { config: any }) {
-  const [Component, setComponent] = React.useState<any>(null);
-  const [loading, setLoading] = React.useState(true);
-  const [error, setError] = React.useState<string | null>(null);
-
-  React.useEffect(() => {
-    if (!config.component_url) {
-      setError('No component URL provided');
-      setLoading(false);
-      return;
-    }
-
-    setLoading(true);
-    setError(null);
-
-    // Dynamically import the addon component
-    import(/* @vite-ignore */ config.component_url)
-      .then((mod) => {
-        setComponent(() => mod.default || mod);
-        setLoading(false);
-      })
-      .catch((err) => {
-        console.error('[AddonRoute] Failed to load component:', err);
-        setError(err.message || 'Failed to load addon component');
-        setLoading(false);
-      });
-  }, [config.component_url]);
-
-  if (loading) {
-    return (
-      <div className="flex items-center justify-center p-8">
-        <div className="text-center">
-          <Loader2 className="w-8 h-8 animate-spin mx-auto mb-2 opacity-50" />
-          <p className="text-sm opacity-70">{__('Loading addon...')}</p>
-        </div>
-      </div>
-    );
-  }
-
-  if (error) {
-    return (
-      <div className="p-6">
-        <div className="rounded-lg border border-red-200 bg-red-50 p-4">
-          <h3 className="font-semibold text-red-900 mb-2">{__('Failed to Load Addon')}</h3>
-          <p className="text-sm text-red-700">{error}</p>
-        </div>
-      </div>
-    );
-  }
-
-  if (!Component) {
-    return (
-      <div className="p-6">
-        <div className="rounded-lg border border-yellow-200 bg-yellow-50 p-4">
-          <p className="text-sm text-yellow-700">{__('Addon component not found')}</p>
-        </div>
-      </div>
-    );
-  }
-
-  // Render the addon component with props
-  return <Component {...(config.props || {})} />;
-}
-
-function Header({ onFullscreen, fullscreen, showToggle = true, scrollContainerRef, onVisibilityChange }: { onFullscreen: () => void; fullscreen: boolean; showToggle?: boolean; scrollContainerRef?: React.RefObject<HTMLDivElement>; onVisibilityChange?: (visible: boolean) => void }) {
-  const [siteTitle, setSiteTitle] = React.useState((window as any).wnw?.siteTitle || 'WooNooW');
-  const [storeLogo, setStoreLogo] = React.useState('');
-  const [storeLogoDark, setStoreLogoDark] = React.useState('');
-  const [isVisible, setIsVisible] = React.useState(true);
-  const lastScrollYRef = React.useRef(0);
-  const isStandalone = window.WNW_CONFIG?.standaloneMode ?? false;
-  const [isDark, setIsDark] = React.useState(false);
-
-  // Detect dark mode
-  React.useEffect(() => {
-    const checkDarkMode = () => {
-      const htmlEl = document.documentElement;
-      setIsDark(htmlEl.classList.contains('dark'));
-    };
-
-    checkDarkMode();
-
-    // Watch for theme changes
-    const observer = new MutationObserver(checkDarkMode);
-    observer.observe(document.documentElement, {
-      attributes: true,
-      attributeFilter: ['class']
-    });
-
-    return () => observer.disconnect();
-  }, []);
-
-  // Notify parent of visibility changes
-  React.useEffect(() => {
-    onVisibilityChange?.(isVisible);
-  }, [isVisible, onVisibilityChange]);
-
-  // Fetch store branding on mount
-  React.useEffect(() => {
-    const fetchBranding = async () => {
-      try {
-        const response = await fetch((window.WNW_CONFIG?.restUrl || '') + '/store/branding');
-        if (response.ok) {
-          const data = await response.json();
-          if (data.store_logo) setStoreLogo(data.store_logo);
-          if (data.store_logo_dark) setStoreLogoDark(data.store_logo_dark);
-          if (data.store_name) setSiteTitle(data.store_name);
-        }
-      } catch (err) {
-        console.error('Failed to fetch branding:', err);
-      }
-    };
-    fetchBranding();
-  }, []);
-
-  // Listen for store settings updates
-  React.useEffect(() => {
-    const handleStoreUpdate = (event: CustomEvent) => {
-      if (event.detail?.store_logo) setStoreLogo(event.detail.store_logo);
-      if (event.detail?.store_logo_dark) setStoreLogoDark(event.detail.store_logo_dark);
-      if (event.detail?.store_name) setSiteTitle(event.detail.store_name);
-    };
-
-    window.addEventListener('woonoow:store:updated' as any, handleStoreUpdate);
-    return () => window.removeEventListener('woonoow:store:updated' as any, handleStoreUpdate);
-  }, []);
-
-  // Hide/show header on scroll (mobile only)
-  React.useEffect(() => {
-    const scrollContainer = scrollContainerRef?.current;
-    if (!scrollContainer) return;
-
-    const handleScroll = () => {
-      const currentScrollY = scrollContainer.scrollTop;
-
-      // Only apply on mobile (check window width)
-      if (window.innerWidth >= 768) {
-        setIsVisible(true);
-        return;
-      }
-
-      if (currentScrollY > lastScrollYRef.current && currentScrollY > 50) {
-        // Scrolling down & past threshold
-        setIsVisible(false);
-      } else if (currentScrollY < lastScrollYRef.current) {
-        // Scrolling up
-        setIsVisible(true);
-      }
-
-      lastScrollYRef.current = currentScrollY;
-    };
-
-    scrollContainer.addEventListener('scroll', handleScroll, { passive: true });
-
-    return () => {
-      scrollContainer.removeEventListener('scroll', handleScroll);
-    };
-  }, [scrollContainerRef]);
-
-  const handleLogout = async () => {
-    try {
-      await fetch((window.WNW_CONFIG?.restUrl || '') + '/auth/logout', {
-        method: 'POST',
-        credentials: 'include',
-      });
-      window.location.reload();
-    } catch (err) {
-      console.error('Logout failed:', err);
-    }
-  };
-
-  // Hide header completely on mobile in fullscreen mode (both standalone and wp-admin fullscreen)
-  if (fullscreen && typeof window !== 'undefined' && window.innerWidth < 768) {
-    return null;
-  }
-
-  // Choose logo based on theme
-  const currentLogo = isDark && storeLogoDark ? storeLogoDark : storeLogo;
-
-  return (
-    <header className={`h-16 border-b border-border flex items-center px-4 justify-between sticky ${fullscreen ? `top-0` : `top-[32px]`} z-40 bg-background md:bg-background/95 md:backdrop-blur md:supports-[backdrop-filter]:bg-background/60 transition-transform duration-300 ${fullscreen && !isVisible ? '-translate-y-full md:translate-y-0' : 'translate-y-0'}`}>
-      <div className="flex items-center gap-3">
-        {currentLogo ? (
-          <img src={currentLogo} alt={siteTitle} className="h-8 object-contain" />
-        ) : (
-          <div className="font-semibold">{siteTitle}</div>
-        )}
-      </div>
-      <div className="flex items-center gap-3">
-        <div className="text-sm opacity-70 hidden sm:block">{window.WNW_API?.isDev ? 'Dev Server' : 'Production'}</div>
-        {isStandalone && (
-          <>
-            <a
-              href={window.WNW_CONFIG?.wpAdminUrl || '/wp-admin'}
-              className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
-              title="Go to WordPress Admin"
-            >
-              <span>{__('WordPress')}</span>
-            </a>
-            <button
-              onClick={handleLogout}
-              className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
-              title="Logout"
-            >
-              <span>{__('Logout')}</span>
-            </button>
-          </>
-        )}
-        <ThemeToggle />
-        {showToggle && (
-          <button
-            onClick={onFullscreen}
-            className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
-            title={fullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
-          >
-            {fullscreen ? <Minimize2 className="w-4 h-4" /> : <Maximize2 className="w-4 h-4" />}
-            <span className="hidden sm:inline">{fullscreen ? 'Exit' : 'Fullscreen'}</span>
-          </button>
-        )}
-      </div>
-    </header>
+    <Toaster
+      richColors
+      theme={actualTheme as 'light' | 'dark' | 'system'}
+      position="bottom-right"
+      closeButton
+      visibleToasts={3}
+      duration={4000}
+      offset="20px"
+    />
   );
 }
 
 const qc = new QueryClient();
 
-function ShortcutsBinder({ onToggle }: { onToggle: () => void }) {
-  useShortcuts({ toggleFullscreen: onToggle });
-  return null;
-}
-
-// Centralized route controller so we don't duplicate <Routes> in each layout
-function AppRoutes() {
-  const addonRoutes = (window as any).WNW_ADDON_ROUTES || [];
-
-  return (
-    <Routes>
-      {/* Dashboard */}
-      <Route path="/" element={<Navigate to="/dashboard" replace />} />
-      <Route path="/reset-password" element={<ResetPassword />} />
-      <Route path="/dashboard" element={<Dashboard />} />
-      <Route path="/dashboard/revenue" element={<DashboardRevenue />} />
-      <Route path="/dashboard/orders" element={<DashboardOrders />} />
-      <Route path="/dashboard/products" element={<DashboardProducts />} />
-      <Route path="/dashboard/customers" element={<DashboardCustomers />} />
-      <Route path="/dashboard/coupons" element={<DashboardCoupons />} />
-      <Route path="/dashboard/taxes" element={<DashboardTaxes />} />
-
-      {/* Products */}
-      <Route path="/products" element={<ProductsIndex />} />
-      <Route path="/products/new" element={<ProductNew />} />
-      <Route path="/products/:id/edit" element={<ProductEdit />} />
-      <Route path="/products/categories" element={<ProductCategories />} />
-      <Route path="/products/tags" element={<ProductTags />} />
-      <Route path="/products/attributes" element={<ProductAttributes />} />
-
-      {/* Orders */}
-      <Route path="/orders" element={<OrdersIndex />} />
-      <Route path="/orders/new" element={<OrderNew />} />
-      <Route path="/orders/:id" element={<OrderDetail />} />
-      <Route path="/orders/:id/edit" element={<OrderEdit />} />
-
-      {/* Coupons (under Marketing) */}
-      <Route path="/coupons" element={<CouponsIndex />} />
-      <Route path="/coupons/new" element={<CouponNew />} />
-      <Route path="/coupons/:id/edit" element={<CouponEdit />} />
-      <Route path="/marketing/coupons" element={<CouponsIndex />} />
-      <Route path="/marketing/coupons/new" element={<CouponNew />} />
-      <Route path="/marketing/coupons/:id/edit" element={<CouponEdit />} />
-
-      {/* Customers */}
-      <Route path="/customers" element={<CustomersIndex />} />
-      <Route path="/customers/new" element={<CustomerNew />} />
-      <Route path="/customers/:id/edit" element={<CustomerEdit />} />
-      <Route path="/customers/:id" element={<CustomerDetail />} />
-
-      {/* More */}
-      <Route path="/more" element={<MorePage />} />
-
-      {/* Settings */}
-      <Route path="/settings" element={<SettingsIndex />} />
-      <Route path="/settings/store" element={<SettingsStore />} />
-      <Route path="/settings/payments" element={<SettingsPayments />} />
-      <Route path="/settings/shipping" element={<SettingsShipping />} />
-      <Route path="/settings/tax" element={<SettingsTax />} />
-      <Route path="/settings/customers" element={<SettingsCustomers />} />
-      <Route path="/settings/taxes" element={<Navigate to="/settings/tax" replace />} />
-      <Route path="/settings/local-pickup" element={<SettingsLocalPickup />} />
-      <Route path="/settings/checkout" element={<SettingsIndex />} />
-      <Route path="/settings/notifications" element={<SettingsNotifications />} />
-      <Route path="/settings/notifications/staff" element={<StaffNotifications />} />
-      <Route path="/settings/notifications/customer" element={<CustomerNotifications />} />
-      <Route path="/settings/notifications/channels" element={<ChannelConfiguration />} />
-      <Route path="/settings/notifications/channels/email" element={<EmailConfiguration />} />
-      <Route path="/settings/notifications/channels/push" element={<PushConfiguration />} />
-      <Route path="/settings/notifications/email-customization" element={<EmailCustomization />} />
-      <Route path="/settings/notifications/edit-template" element={<EditTemplate />} />
-      <Route path="/settings/brand" element={<SettingsIndex />} />
-      <Route path="/settings/developer" element={<SettingsDeveloper />} />
-      <Route path="/settings/modules" element={<SettingsModules />} />
-      <Route path="/settings/modules/:moduleId" element={<ModuleSettings />} />
-
-      {/* Appearance */}
-      <Route path="/appearance" element={<AppearanceIndex />} />
-      <Route path="/appearance/general" element={<AppearanceGeneral />} />
-      <Route path="/appearance/header" element={<AppearanceHeader />} />
-      <Route path="/appearance/footer" element={<AppearanceFooter />} />
-      <Route path="/appearance/shop" element={<AppearanceShop />} />
-      <Route path="/appearance/product" element={<AppearanceProduct />} />
-      <Route path="/appearance/cart" element={<AppearanceCart />} />
-      <Route path="/appearance/checkout" element={<AppearanceCheckout />} />
-      <Route path="/appearance/thankyou" element={<AppearanceThankYou />} />
-      <Route path="/appearance/account" element={<AppearanceAccount />} />
-
-      {/* Marketing */}
-      <Route path="/marketing" element={<MarketingIndex />} />
-      <Route path="/marketing/newsletter" element={<NewsletterSubscribers />} />
-      <Route path="/marketing/campaigns" element={<CampaignsList />} />
-      <Route path="/marketing/campaigns/:id" element={<CampaignEdit />} />
-
-      {/* Dynamic Addon Routes */}
-      {addonRoutes.map((route: any) => (
-        <Route
-          key={route.path}
-          path={route.path}
-          element={<AddonRoute config={route} />}
-        />
-      ))}
-    </Routes>
-  );
-}
-
-function Shell() {
-  const { on, setOn } = useFullscreen();
-  const { main } = useActiveSection();
-  const toggle = () => setOn(v => !v);
-  const exitFullscreen = () => setOn(false);
-  const isDesktop = useIsDesktop();
-  const location = useLocation();
-  const scrollContainerRef = React.useRef<HTMLDivElement>(null);
-
-  // Check if standalone mode - force fullscreen and hide toggle
-  const isStandalone = window.WNW_CONFIG?.standaloneMode ?? false;
-  const fullscreen = isStandalone ? true : on;
-
-  // Check if current route is dashboard
-  const isDashboardRoute = location.pathname === '/' || location.pathname.startsWith('/dashboard');
-
-  // Check if current route is More page (no submenu needed)
-  const isMorePage = location.pathname === '/more';
-
-  const submenuTopClass = fullscreen ? 'top-0' : 'top-[calc(7rem+32px)]';
-  const submenuZIndex = fullscreen ? 'z-50' : 'z-40';
-
-  return (
-    <AppProvider isStandalone={isStandalone} exitFullscreen={exitFullscreen}>
-      {!isStandalone && <ShortcutsBinder onToggle={toggle} />}
-      {!isStandalone && <CommandPalette toggleFullscreen={toggle} />}
-      <div className={`flex flex-col min-h-screen ${fullscreen ? 'woonoow-fullscreen-root' : ''}`}>
-        <Header onFullscreen={toggle} fullscreen={fullscreen} showToggle={!isStandalone} scrollContainerRef={scrollContainerRef} />
-        {fullscreen ? (
-          isDesktop ? (
-            <div className="flex flex-1 min-h-0">
-              <Sidebar />
-              <main className="flex-1 flex flex-col min-h-0 min-w-0">
-                {/* Flex wrapper: desktop = col-reverse (SubmenuBar first, PageHeader second) */}
-                <div className="flex flex-col-reverse">
-                  <PageHeader fullscreen={true} />
-                  {isDashboardRoute ? (
-                    <DashboardSubmenuBar items={main.children} fullscreen={true} />
-                  ) : (
-                    <SubmenuBar items={main.children} fullscreen={true} />
+const router = createHashRouter(
+  createRoutesFromElements(
+    <>
+      {window.WNW_CONFIG?.standaloneMode && (
+        <Route path="/login" element={<Login />} />
       )}
-                </div>
-                <div className="flex-1 overflow-auto p-4 min-w-0">
-                  <AppRoutes />
-                </div>
-              </main>
-            </div>
-          ) : (
-            <div className="flex flex-1 flex-col min-h-0">
-              {/* Flex wrapper: mobile = col (PageHeader first), desktop = col-reverse (SubmenuBar first) */}
-              <div className={`flex flex-col md:flex-col-reverse sticky ${submenuTopClass} ${submenuZIndex}`}>
-                <PageHeader fullscreen={true} />
-                {!isMorePage && (isDashboardRoute ? (
-                  <DashboardSubmenuBar items={main.children} fullscreen={true} />
-                ) : (
-                  <SubmenuBar items={main.children} fullscreen={true} />
-                ))}
-              </div>
-              <main className="flex-1 flex flex-col min-h-0 min-w-0 pb-14">
-                <div ref={scrollContainerRef} className="flex-1 overflow-auto p-4 min-w-0">
-                  <AppRoutes />
-                </div>
-              </main>
-              <BottomNav />
-              <FAB />
-            </div>
+      <Route path="/*" element={<AuthWrapper />} />
+    </>
   )
-        ) : (
-          <div className="flex flex-1 flex-col min-h-0">
-            <TopNav />
-            {/* Flex wrapper: mobile = col (PageHeader first), desktop = col-reverse (SubmenuBar first) */}
-            <div className={`flex flex-col md:flex-col-reverse sticky ${submenuTopClass} ${submenuZIndex}`}>
-              <PageHeader fullscreen={false} />
-              {isDashboardRoute ? (
-                <DashboardSubmenuBar items={main.children} fullscreen={false} />
-              ) : (
-                <SubmenuBar items={main.children} fullscreen={false} />
-              )}
-            </div>
-            <main className="flex-1 flex flex-col min-h-0 min-w-0">
-              <div className="flex-1 overflow-auto p-4 min-w-0">
-                <AppRoutes />
-              </div>
-            </main>
-          </div>
-        )}
-      </div>
-    </AppProvider>
-  );
-}
-
-function AuthWrapper() {
-  const [isAuthenticated, setIsAuthenticated] = useState(
-    window.WNW_CONFIG?.isAuthenticated ?? true
-  );
-  const [isChecking, setIsChecking] = useState(window.WNW_CONFIG?.standaloneMode ?? false);
-  const location = useLocation();
-
-  useEffect(() => {
-    console.log('[AuthWrapper] Initial config:', {
-      standaloneMode: window.WNW_CONFIG?.standaloneMode,
-      isAuthenticated: window.WNW_CONFIG?.isAuthenticated,
-      currentUser: window.WNW_CONFIG?.currentUser
-    });
-
-    // In standalone mode, trust the initial PHP auth check
-    // PHP uses wp_signon which sets proper WordPress cookies
-    const checkAuth = () => {
-      if (window.WNW_CONFIG?.standaloneMode) {
-        setIsAuthenticated(window.WNW_CONFIG.isAuthenticated ?? false);
-        setIsChecking(false);
-      } else {
-        // In wp-admin mode, always authenticated
-        setIsChecking(false);
-      }
-    };
-    checkAuth();
-  }, []);
-
-  if (isChecking) {
-    return (
-      <div className="flex items-center justify-center min-h-screen">
-        <Loader2 className="w-12 h-12 animate-spin text-primary" />
-      </div>
-    );
-  }
-
-  if (window.WNW_CONFIG?.standaloneMode && !isAuthenticated && location.pathname !== '/login') {
-    return <Navigate to="/login" replace />;
-  }
-
-  if (location.pathname === '/login' && isAuthenticated) {
-    return <Navigate to="/" replace />;
-  }
-
-  return (
-    <FABProvider>
-      <PageHeaderProvider>
-        <DashboardProvider>
-          <Shell />
-        </DashboardProvider>
-      </PageHeaderProvider>
-    </FABProvider>
-  );
-}
+);
 
 export default function App() {
   // Initialize Window API for addon developers
@@ -749,23 +43,8 @@ export default function App() {
 
   return (
     <QueryClientProvider client={qc}>
-      <HashRouter>
-        <Routes>
-          {window.WNW_CONFIG?.standaloneMode && (
-            <Route path="/login" element={<Login />} />
-          )}
-          <Route path="/*" element={<AuthWrapper />} />
-        </Routes>
-        <Toaster
-          richColors
-          theme="light"
-          position="bottom-right"
-          closeButton
-          visibleToasts={3}
-          duration={4000}
-          offset="20px"
-        />
-      </HashRouter>
+      <RouterProvider router={router} />
+      <ToasterWithTheme />
     </QueryClientProvider>
   );
 }

admin-spa/src/components/DocLink.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { useLocation } from 'react-router-dom';
+import { BookOpen } from 'lucide-react';
+import { getDocUrl } from '@/config/docRoutes';
+import { Button } from '@/components/ui/button';
+
+export function DocLink() {
+    const location = useLocation();
+    const docUrl = getDocUrl(location.pathname);
+
+    if (!docUrl) return null;
+
+    return (
+        <Button
+            variant="ghost"
+            size="icon"
+            className="h-8 w-8 ml-2 text-muted-foreground hover:text-primary"
+            asChild
+        >
+            <a href={docUrl} target="_blank" rel="noopener noreferrer" title="View Documentation">
+                <BookOpen className="h-4 w-4" />
+                <span className="sr-only">View Documentation</span>
+            </a>
+        </Button>
+    );
+}

admin-spa/src/components/DynamicCheckoutField.tsx

@@ -0,0 +1,270 @@
+import * as React from 'react';
+import { useState } from 'react';
+import { SearchableSelect } from '@/components/ui/searchable-select';
+import { api } from '@/lib/api';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+import { Label } from '@/components/ui/label';
+
+export interface CheckoutField {
+    key: string;
+    fieldset: 'billing' | 'shipping' | 'account' | 'order';
+    type: string;
+    label: string;
+    placeholder?: string;
+    required: boolean;
+    hidden: boolean;
+    class?: string[];
+    priority: number;
+    options?: Record<string, string> | null;
+    custom: boolean;
+    autocomplete?: string;
+    validate?: string[];
+    input_class?: string[];
+    custom_attributes?: Record<string, string>;
+    default?: string;
+    // For searchable_select type
+    search_endpoint?: string | null;
+    search_param?: string;
+    min_chars?: number;
+}
+
+interface DynamicCheckoutFieldProps {
+    field: CheckoutField;
+    value: string;
+    onChange: (value: string) => void;
+    countryOptions?: { value: string; label: string }[];
+    stateOptions?: { value: string; label: string }[];
+}
+
+interface SearchOption {
+    value: string;
+    label: string;
+}
+
+export function DynamicCheckoutField({
+    field,
+    value,
+    onChange,
+    countryOptions = [],
+    stateOptions = [],
+}: DynamicCheckoutFieldProps) {
+    const [searchOptions, setSearchOptions] = useState<SearchOption[]>([]);
+    const [isSearching, setIsSearching] = useState(false);
+
+    // Handle API search for searchable_select
+    const handleApiSearch = async (searchTerm: string) => {
+        if (!field.search_endpoint) return;
+
+        const minChars = field.min_chars || 2;
+        if (searchTerm.length < minChars) {
+            setSearchOptions([]);
+            return;
+        }
+
+        setIsSearching(true);
+        try {
+            const param = field.search_param || 'search';
+            const results = await api.get<SearchOption[]>(field.search_endpoint, { [param]: searchTerm });
+            setSearchOptions(Array.isArray(results) ? results : []);
+        } catch (error) {
+            console.error('Search failed:', error);
+            setSearchOptions([]);
+        } finally {
+            setIsSearching(false);
+        }
+    };
+
+    // Don't render hidden fields
+    if (field.hidden || field.type === 'hidden') {
+        return null;
+    }
+
+    // Get field key without prefix (billing_, shipping_)
+    const fieldName = field.key.replace(/^(billing_|shipping_)/, '');
+
+    // Determine CSS classes
+    const isWide = ['address_1', 'address_2', 'email'].includes(fieldName) ||
+        field.class?.includes('form-row-wide');
+    const wrapperClass = isWide ? 'md:col-span-2' : '';
+
+    // Render based on type
+    const renderInput = () => {
+        switch (field.type) {
+            case 'country':
+                return (
+                    <SearchableSelect
+                        options={countryOptions}
+                        value={value}
+                        onChange={onChange}
+                        placeholder={field.placeholder || 'Select country'}
+                        disabled={countryOptions.length <= 1}
+                    />
+                );
+
+            case 'state':
+                return stateOptions.length > 0 ? (
+                    <SearchableSelect
+                        options={stateOptions}
+                        value={value}
+                        onChange={onChange}
+                        placeholder={field.placeholder || 'Select state'}
+                    />
+                ) : (
+                    <Input
+                        type="text"
+                        value={value}
+                        onChange={(e) => onChange(e.target.value)}
+                        placeholder={field.placeholder}
+                        required={field.required}
+                        autoComplete={field.autocomplete}
+                    />
+                );
+
+            case 'select':
+                if (field.options && Object.keys(field.options).length > 0) {
+                    const options = Object.entries(field.options).map(([val, label]) => ({
+                        value: val,
+                        label: String(label),
+                    }));
+                    return (
+                        <SearchableSelect
+                            options={options}
+                            value={value}
+                            onChange={onChange}
+                            placeholder={field.placeholder || `Select ${field.label}`}
+                        />
+                    );
+                }
+                return null;
+
+            case 'searchable_select':
+                return (
+                    <SearchableSelect
+                        options={searchOptions}
+                        value={value}
+                        onChange={(v) => {
+                            onChange(v);
+                            // Store label for display
+                            const selected = searchOptions.find(o => o.value === v);
+                            if (selected) {
+                                const event = new CustomEvent('woonoow:field_label', {
+                                    detail: { key: field.key + '_label', value: selected.label }
+                                });
+                                document.dispatchEvent(event);
+                            }
+                        }}
+                        onSearch={handleApiSearch}
+                        isSearching={isSearching}
+                        placeholder={field.placeholder || `Search ${field.label}...`}
+                        emptyLabel={
+                            isSearching
+                                ? 'Searching...'
+                                : `Type at least ${field.min_chars || 2} characters to search`
+                        }
+                    />
+                );
+
+            case 'textarea':
+                return (
+                    <Textarea
+                        value={value}
+                        onChange={(e) => onChange(e.target.value)}
+                        placeholder={field.placeholder}
+                        required={field.required}
+                    />
+                );
+
+            case 'checkbox':
+                return (
+                    <label className="flex items-center gap-2">
+                        <input
+                            type="checkbox"
+                            checked={value === '1' || value === 'true'}
+                            onChange={(e) => onChange(e.target.checked ? '1' : '0')}
+                            className="w-4 h-4"
+                        />
+                        <span>{field.label}</span>
+                    </label>
+                );
+
+            case 'radio':
+                if (field.options) {
+                    return (
+                        <div className="space-y-2">
+                            {Object.entries(field.options).map(([val, label]) => (
+                                <label key={val} className="flex items-center gap-2">
+                                    <input
+                                        type="radio"
+                                        name={field.key}
+                                        value={val}
+                                        checked={value === val}
+                                        onChange={() => onChange(val)}
+                                        className="w-4 h-4"
+                                    />
+                                    <span>{String(label)}</span>
+                                </label>
+                            ))}
+                        </div>
+                    );
+                }
+                return null;
+
+            case 'email':
+                return (
+                    <Input
+                        type="email"
+                        value={value}
+                        onChange={(e) => onChange(e.target.value)}
+                        placeholder={field.placeholder}
+                        required={field.required}
+                        autoComplete={field.autocomplete || 'email'}
+                    />
+                );
+
+            case 'tel':
+                return (
+                    <Input
+                        type="tel"
+                        value={value}
+                        onChange={(e) => onChange(e.target.value)}
+                        placeholder={field.placeholder}
+                        required={field.required}
+                        autoComplete={field.autocomplete || 'tel'}
+                    />
+                );
+
+            // Default: text input
+            default:
+                return (
+                    <Input
+                        type="text"
+                        value={value}
+                        onChange={(e) => onChange(e.target.value)}
+                        placeholder={field.placeholder}
+                        required={field.required}
+                        autoComplete={field.autocomplete}
+                    />
+                );
+        }
+    };
+
+    // Don't render label for checkbox (it's inline)
+    if (field.type === 'checkbox') {
+        return (
+            <div className={wrapperClass}>
+                {renderInput()}
+            </div>
+        );
+    }
+
+    return (
+        <div className={wrapperClass}>
+            <Label>
+                {field.label}
+                {field.required && <span className="text-destructive ml-1">*</span>}
+            </Label>
+            {renderInput()}
+        </div>
+    );
+}

admin-spa/src/components/EmailBuilder/BlockRenderer.tsx

@@ -75,7 +75,7 @@ export function BlockRenderer({
             marginBottom: '24px'
           },
           hero: {
-            background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+            background: 'linear-gradient(135deg, var(--wn-gradient-start, #667eea) 0%, var(--wn-gradient-end, #764ba2) 100%)',
             color: '#fff',
             borderRadius: '8px',
             padding: '32px 40px',
@@ -89,7 +89,7 @@ export function BlockRenderer({
         return (
           <div style={cardStyles[block.cardType]}>
             <div
-              className="prose prose-sm max-w-none [&_h1]:text-3xl [&_h1]:font-bold [&_h1]:mt-0 [&_h1]:mb-4 [&_h2]:text-2xl [&_h2]:font-bold [&_h2]:mt-0 [&_h2]:mb-3 [&_h3]:text-xl [&_h3]:font-bold [&_h3]:mt-0 [&_h3]:mb-2 [&_h4]:text-lg [&_h4]:font-bold [&_h4]:mt-0 [&_h4]:mb-2 [&_.button]:inline-block [&_.button]:bg-purple-600 [&_.button]:text-white [&_.button]:px-7 [&_.button]:py-3.5 [&_.button]:rounded-md [&_.button]:no-underline [&_.button]:font-semibold [&_.button-outline]:inline-block [&_.button-outline]:bg-transparent [&_.button-outline]:text-purple-600 [&_.button-outline]:px-6 [&_.button-outline]:py-3 [&_.button-outline]:rounded-md [&_.button-outline]:no-underline [&_.button-outline]:font-semibold [&_.button-outline]:border-2 [&_.button-outline]:border-purple-600"
+              className="prose prose-sm max-w-none [&_h1]:text-3xl [&_h1]:font-bold [&_h1]:mt-0 [&_h1]:mb-4 [&_h2]:text-2xl [&_h2]:font-bold [&_h2]:mt-0 [&_h2]:mb-3 [&_h3]:text-xl [&_h3]:font-bold [&_h3]:mt-0 [&_h3]:mb-2 [&_h4]:text-lg [&_h4]:font-bold [&_h4]:mt-0 [&_h4]:mb-2 [&_.button]:inline-block [&_.button]:bg-purple-600 [&_.button]:text-white [&_.button]:px-7 [&_.button]:py-3.5 [&_.button]:rounded-md [&_.button]:no-underline [&_.button]:font-semibold [&_.button-outline]:inline-block [&_.button-outline]:bg-transparent [&_.button-outline]:text-purple-600 [&_.button-outline]:px-6 [&_.button-outline]:py-3 [&_.button-outline]:rounded-md [&_.button-outline]:no-underline [&_.button-outline]:font-semibold [&_.button-outline]:border-2 [&_.button-outline]:border-purple-600 [&_.text-link]:text-purple-600 [&_.text-link]:underline"
               style={block.cardType === 'hero' ? { color: '#fff' } : {}}
               dangerouslySetInnerHTML={{ __html: htmlContent }}
             />
@@ -97,31 +97,45 @@ export function BlockRenderer({
         );
 
       case 'button': {
-        const buttonStyle: React.CSSProperties = block.style === 'solid'
-          ? {
+        // Different styles based on button type
+        let buttonStyle: React.CSSProperties;
+
+        if (block.style === 'link') {
+          // Plain link style - just underlined text
+          buttonStyle = {
+            color: 'var(--wn-primary, #7f54b3)',
+            textDecoration: 'underline',
+          };
+        } else if (block.style === 'outline') {
+          buttonStyle = {
             display: 'inline-block',
-              background: '#7f54b3',
+            background: 'transparent',
+            color: 'var(--wn-secondary, #7f54b3)',
+            padding: '12px 26px',
+            border: '2px solid var(--wn-secondary, #7f54b3)',
+            borderRadius: '6px',
+            textDecoration: 'none',
+            fontWeight: 600,
+          };
+        } else {
+          // Solid style (default)
+          buttonStyle = {
+            display: 'inline-block',
+            background: 'var(--wn-primary, #7f54b3)',
             color: '#fff',
             padding: '14px 28px',
             borderRadius: '6px',
             textDecoration: 'none',
             fontWeight: 600,
-            }
-          : {
-              display: 'inline-block',
-              background: 'transparent',
-              color: '#7f54b3',
-              padding: '12px 26px',
-              border: '2px solid #7f54b3',
-              borderRadius: '6px',
-              textDecoration: 'none',
-              fontWeight: 600,
           };
+        }
 
         const containerStyle: React.CSSProperties = {
           textAlign: block.align || 'center',
         };
 
+        // Width modes don't apply to plain links
+        if (block.style !== 'link') {
           if (block.widthMode === 'full') {
             buttonStyle.display = 'block';
             buttonStyle.width = '100%';
@@ -130,6 +144,7 @@ export function BlockRenderer({
             buttonStyle.maxWidth = `${block.customMaxWidth}px`;
             buttonStyle.width = '100%';
           }
+        }
 
         return (
           <div style={containerStyle}>

admin-spa/src/components/EmailBuilder/EmailBuilder.tsx

@@ -101,13 +101,11 @@ export function EmailBuilder({ blocks, onChange, variables = [] }: EmailBuilderP
   };
 
   const openEditDialog = (block: EmailBlock) => {
-    console.log('[EmailBuilder] openEditDialog called', { blockId: block.id, blockType: block.type });
     setEditingBlockId(block.id);
 
     if (block.type === 'card') {
       // Convert markdown to HTML for rich text editor
       const htmlContent = parseMarkdownBasics(block.content);
-      console.log('[EmailBuilder] Card content parsed', { original: block.content, html: htmlContent });
       setEditingContent(htmlContent);
       setEditingCardType(block.cardType);
     } else if (block.type === 'button') {
@@ -124,7 +122,6 @@ export function EmailBuilder({ blocks, onChange, variables = [] }: EmailBuilderP
       setEditingAlign(block.align);
     }
 
-    console.log('[EmailBuilder] Setting editDialogOpen to true');
     setEditDialogOpen(true);
   };
 

admin-spa/src/components/EmailBuilder/types.ts

@@ -2,7 +2,7 @@ export type BlockType = 'card' | 'button' | 'divider' | 'spacer' | 'image';
 
 export type CardType = 'default' | 'success' | 'info' | 'warning' | 'hero' | 'basic';
 
-export type ButtonStyle = 'solid' | 'outline';
+export type ButtonStyle = 'solid' | 'outline' | 'link';
 
 export type ContentWidth = 'fit' | 'full' | 'custom';
 

admin-spa/src/components/ErrorCard.tsx

@@ -19,18 +19,18 @@ export function ErrorCard({
 }: ErrorCardProps) {
   return (
     <div className="flex items-center justify-center p-8">
-      <div className="max-w-md w-full bg-red-50 border border-red-200 rounded-lg p-6">
+      <div className="max-w-md w-full bg-red-50 dark:bg-red-950/50 border border-red-200 dark:border-red-800 rounded-lg p-6">
         <div className="flex items-start gap-3">
-          <AlertTriangle className="w-5 h-5 text-red-600 flex-shrink-0 mt-0.5" />
+          <AlertTriangle className="w-5 h-5 text-red-600 dark:text-red-400 flex-shrink-0 mt-0.5" />
           <div className="flex-1">
-            <h3 className="font-medium text-red-900">{title}</h3>
+            <h3 className="font-medium text-red-900 dark:text-red-200">{title}</h3>
             {message && (
-              <p className="text-sm text-red-700 mt-1">{message}</p>
+              <p className="text-sm text-red-700 dark:text-red-300 mt-1">{message}</p>
             )}
             {onRetry && (
               <button
                 onClick={onRetry}
-                className="mt-3 inline-flex items-center gap-2 text-sm font-medium text-red-900 hover:text-red-700 transition-colors"
+                className="mt-3 inline-flex items-center gap-2 text-sm font-medium text-red-900 dark:text-red-200 hover:text-red-700 dark:hover:text-red-100 transition-colors"
               >
                 <RefreshCw className="w-4 h-4" />
                 {__('Try again')}
@@ -48,7 +48,7 @@ export function ErrorCard({
  */
 export function ErrorMessage({ message }: { message: string }) {
   return (
-    <div className="flex items-center gap-2 text-sm text-red-600 bg-red-50 border border-red-200 rounded-md p-3">
+    <div className="flex items-center gap-2 text-sm text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-950/50 border border-red-200 dark:border-red-800 rounded-md p-3">
       <AlertTriangle className="w-4 h-4 flex-shrink-0" />
       <span>{message}</span>
     </div>

admin-spa/src/components/LegacyCampaignRedirect.tsx

@@ -0,0 +1,10 @@
+import { Navigate, useParams } from 'react-router-dom';
+
+/**
+ * Legacy redirect for campaign details
+ * Redirects /marketing/campaigns/:id -> /marketing/newsletter/campaigns/:id
+ */
+export function LegacyCampaignRedirect() {
+    const { id } = useParams();
+    return <Navigate to={`/marketing/newsletter/campaigns/${id}`} replace />;
+}

admin-spa/src/components/MediaUploader.tsx

@@ -0,0 +1,77 @@
+import React, { useRef } from 'react';
+import { Button } from '@/components/ui/button';
+import { Image, Upload } from 'lucide-react';
+import { __ } from '@/lib/i18n';
+
+interface MediaUploaderProps {
+    onSelect: (url: string, id?: number) => void;
+    type?: 'image' | 'video' | 'audio' | 'file';
+    title?: string;
+    buttonText?: string;
+    className?: string;
+    children?: React.ReactNode;
+}
+
+export function MediaUploader({
+    onSelect,
+    type = 'image',
+    title = __('Select Image'),
+    buttonText = __('Use Image'),
+    className,
+    children
+}: MediaUploaderProps) {
+    const frameRef = useRef<any>(null);
+
+    const openMediaModal = (e: React.MouseEvent) => {
+        e.preventDefault();
+
+        // Check if wp.media is available
+        const wp = (window as any).wp;
+        if (!wp || !wp.media) {
+            console.warn('WordPress media library not available');
+            return;
+        }
+
+        // Reuse existing frame
+        if (frameRef.current) {
+            frameRef.current.open();
+            return;
+        }
+
+        // Create new frame
+        frameRef.current = wp.media({
+            title,
+            button: {
+                text: buttonText,
+            },
+            library: {
+                type,
+            },
+            multiple: false,
+        });
+
+        // Handle selection
+        frameRef.current.on('select', () => {
+            const state = frameRef.current.state();
+            const selection = state.get('selection');
+
+            if (selection.length > 0) {
+                const attachment = selection.first().toJSON();
+                onSelect(attachment.url, attachment.id);
+            }
+        });
+
+        frameRef.current.open();
+    };
+
+    return (
+        <div onClick={openMediaModal} className={className}>
+            {children || (
+                <Button variant="outline" size="sm" type="button">
+                    <Upload className="w-4 h-4 mr-2" />
+                    {__('Select Image')}
+                </Button>
+            )}
+        </div>
+    );
+}

admin-spa/src/components/PageHeader.tsx

@@ -7,6 +7,8 @@ interface PageHeaderProps {
   hideOnDesktop?: boolean;
 }
 
+import { DocLink } from '@/components/DocLink';
+
 export function PageHeader({ fullscreen = false, hideOnDesktop = false }: PageHeaderProps) {
   const { title, action } = usePageHeader();
   const location = useLocation();
@@ -24,8 +26,9 @@ export function PageHeader({ fullscreen = false, hideOnDesktop = false }: PageHe
   return (
     <div className={`sticky top-0 z-20 border-b bg-background ${hideOnDesktop ? 'md:hidden' : ''}`}>
       <div className={`${containerClass} px-4 py-3 flex items-center justify-between min-w-0`}>
-        <div className="min-w-0 flex-1">
+        <div className="min-w-0 flex-1 flex items-center">
           <h1 className="text-lg font-semibold truncate">{title}</h1>
+          <DocLink />
         </div>
         {action && <div className="flex-shrink-0 ml-4">{action}</div>}
       </div>

admin-spa/src/components/Pagination.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { Button } from '@/components/ui/button';
+import { __ } from '@/lib/i18n';
+
+interface PaginationProps {
+  page: number;
+  perPage: number;
+  total: number;
+  onPageChange: (newPage: number) => void;
+  className?: string;
+}
+
+export function Pagination({ page, perPage, total, onPageChange, className = '' }: PaginationProps) {
+  if (total <= perPage) return null;
+
+  const startItem = ((page - 1) * perPage) + 1;
+  const endItem = Math.min(page * perPage, total);
+  const totalPages = Math.ceil(total / perPage);
+
+  return (
+    <div className={`flex flex-col sm:flex-row justify-between items-center gap-4 pt-4 ${className}`}>
+      <div className="text-sm text-muted-foreground order-2 sm:order-1">
+        {__('Showing')} {startItem} - {endItem} {__('of')} {total}
+      </div>
+      <div className="flex gap-2 order-1 sm:order-2">
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => onPageChange(Math.max(1, page - 1))}
+          disabled={page <= 1}
+        >
+          {__('Previous')}
+        </Button>
+        <div className="flex items-center sm:hidden text-sm opacity-80 px-2">
+          {__('Page')} {page} {__('of')} {totalPages}
+        </div>
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => onPageChange(page + 1)}
+          disabled={page >= totalPages}
+        >
+          {__('Next')}
+        </Button>
+      </div>
+    </div>
+  );
+}

admin-spa/src/components/ProductCard.tsx

@@ -0,0 +1 @@
+export function ProductCard({ product }: any) { return <div className='p-4 border rounded shadow-sm'>{product?.title || 'Product'}</div>; }

admin-spa/src/components/SharedContentLayout.tsx

@@ -0,0 +1,238 @@
+import React from 'react';
+import { cn } from '@/lib/utils';
+
+
+interface SharedContentProps {
+    // Content
+    title?: string;
+    text?: string; // HTML content
+
+    // Image
+    image?: string;
+    imagePosition?: 'left' | 'right' | 'top' | 'bottom';
+
+    // Layout
+    containerWidth?: 'full' | 'contained' | 'boxed';
+
+    // Styles
+    className?: string;
+    titleStyle?: React.CSSProperties;
+    titleClassName?: string;
+    textStyle?: React.CSSProperties;
+    textClassName?: string;
+    headingStyle?: React.CSSProperties; // For prose headings override
+    imageStyle?: React.CSSProperties;
+
+    // Pro Features (for future)
+    buttons?: Array<{ text: string, url: string }>;
+    buttonStyle?: { classNames?: string; style?: React.CSSProperties };
+}
+
+
+export const SharedContentLayout: React.FC<SharedContentProps> = ({
+    title,
+    text,
+    image,
+    imagePosition = 'left',
+    containerWidth = 'contained',
+    className,
+    titleStyle,
+    titleClassName,
+    textStyle,
+    textClassName,
+    headingStyle,
+    buttons,
+
+    imageStyle,
+    buttonStyle
+}) => {
+
+    const hasImage = !!image;
+    const isImageLeft = imagePosition === 'left';
+    const isImageRight = imagePosition === 'right';
+    const isImageTop = imagePosition === 'top';
+    const isImageBottom = imagePosition === 'bottom';
+
+    // Wrapper classes — full = edge-to-edge, contained = narrow readable column, boxed = card at max-w-5xl
+    const containerClasses = cn(
+        'w-full mx-auto px-4 sm:px-6 lg:px-8',
+        containerWidth === 'contained' ? 'max-w-4xl'
+            : containerWidth === 'boxed' ? 'max-w-5xl'
+                : '' // full = no max-width cap
+    );
+
+    const gridClasses = cn(
+        'mx-auto',
+        hasImage && (isImageLeft || isImageRight)
+            ? 'grid grid-cols-1 lg:grid-cols-2 gap-12 items-center'
+            : containerWidth === 'full' ? 'w-full' : '' // no extra constraint for contained — outer already limits it
+    );
+
+    const imageWrapperOrder = isImageRight ? 'lg:order-last' : 'lg:order-first';
+
+    const proseStyle = {
+        ...textStyle,
+        '--tw-prose-headings': headingStyle?.color,
+        '--tw-prose-body': textStyle?.color,
+    } as React.CSSProperties;
+
+    return (
+        <div className={containerClasses}>
+            {containerWidth === 'boxed' ? (
+                <div className="bg-white rounded-2xl shadow-sm border border-gray-200 overflow-hidden px-6 md:px-10 py-10">
+                    <div className={gridClasses}>
+                        {/* Image Side */}
+                        {hasImage && (
+                            <div className={cn(
+                                'relative w-full aspect-[4/3] rounded-2xl overflow-hidden shadow-lg',
+                                imageWrapperOrder,
+                                (isImageTop || isImageBottom) && 'mb-8' // spacing if stacked
+                            )} style={imageStyle}>
+                                <img
+                                    src={image}
+                                    alt={title || 'Section Image'}
+                                    className="absolute inset-0 w-full h-full object-cover"
+                                />
+                            </div>
+                        )}
+
+                        {/* Content Side */}
+                        <div className={cn('flex flex-col', hasImage ? 'bg-transparent' : '')}>
+                            {title && (
+                                <h2
+                                    className={cn(
+                                        "tracking-tight text-current mb-6",
+                                        !titleClassName && "text-3xl font-bold sm:text-4xl lg:text-5xl",
+                                        titleClassName
+                                    )}
+                                    style={titleStyle}
+                                >
+                                    {title}
+                                </h2>
+                            )}
+
+
+
+                            {text && (
+                                <div
+                                    className={cn(
+                                        'prose prose-lg max-w-none',
+                                        'prose-h1:text-3xl md:prose-h1:text-4xl lg:prose-h1:text-5xl prose-h1:font-bold prose-h1:mt-6 prose-h1:mb-4',
+                                        'prose-h2:text-2xl md:prose-h2:text-3xl lg:prose-h2:text-4xl prose-h2:font-bold prose-h2:mt-5 prose-h2:mb-3',
+                                        'prose-h3:text-xl md:prose-h3:text-2xl lg:prose-h3:text-3xl prose-h3:font-bold prose-h3:mt-4 prose-h3:mb-2',
+                                        'prose-headings:text-[var(--tw-prose-headings)]',
+                                        'prose-p:text-[var(--tw-prose-body)]',
+                                        'text-[var(--tw-prose-body)]',
+                                        className,
+                                        textClassName
+                                    )}
+                                    style={proseStyle}
+                                    dangerouslySetInnerHTML={{ __html: text }}
+                                />
+                            )}
+
+
+
+                            {/* Buttons */}
+                            {buttons && buttons.length > 0 && (
+                                <div className="mt-8 flex flex-wrap gap-4">
+                                    {buttons.map((btn, idx) => (
+                                        btn.text && btn.url && (
+                                            <a
+                                                key={idx}
+                                                href={btn.url}
+                                                className={cn(
+                                                    "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 h-10 px-4 py-2",
+                                                    !buttonStyle?.style?.backgroundColor && "bg-primary",
+                                                    !buttonStyle?.style?.color && "text-primary-foreground hover:bg-primary/90",
+                                                    buttonStyle?.classNames
+                                                )}
+                                                style={buttonStyle?.style}
+                                            >
+                                                {btn.text}
+                                            </a>
+                                        )
+                                    ))}
+                                </div>
+                            )}
+                        </div>
+                    </div>
+                </div>
+            ) : (
+                <div className={gridClasses}>
+                    {/* Image Side */}
+                    {hasImage && (
+                        <div className={cn(
+                            'relative w-full aspect-[4/3] rounded-2xl overflow-hidden shadow-lg',
+                            imageWrapperOrder,
+                            (isImageTop || isImageBottom) && 'mb-8'
+                        )} style={imageStyle}>
+                            <img
+                                src={image}
+                                alt={title || 'Section Image'}
+                                className="absolute inset-0 w-full h-full object-cover"
+                            />
+                        </div>
+                    )}
+
+                    {/* Content Side */}
+                    <div className={cn('flex flex-col', hasImage ? 'bg-transparent' : '')}>
+                        {title && (
+                            <h2
+                                className={cn(
+                                    "tracking-tight text-current mb-6",
+                                    !titleClassName && "text-3xl font-bold sm:text-4xl lg:text-5xl",
+                                    titleClassName
+                                )}
+                                style={titleStyle}
+                            >
+                                {title}
+                            </h2>
+                        )}
+
+                        {text && (
+                            <div
+                                className={cn(
+                                    'prose prose-lg max-w-none',
+                                    'prose-h1:text-3xl md:prose-h1:text-4xl lg:prose-h1:text-5xl prose-h1:font-bold prose-h1:mt-6 prose-h1:mb-4',
+                                    'prose-h2:text-2xl md:prose-h2:text-3xl lg:prose-h2:text-4xl prose-h2:font-bold prose-h2:mt-5 prose-h2:mb-3',
+                                    'prose-h3:text-xl md:prose-h3:text-2xl lg:prose-h3:text-3xl prose-h3:font-bold prose-h3:mt-4 prose-h3:mb-2',
+                                    'prose-headings:text-[var(--tw-prose-headings)]',
+                                    'prose-p:text-[var(--tw-prose-body)]',
+                                    'text-[var(--tw-prose-body)]',
+                                    className,
+                                    textClassName
+                                )}
+                                style={proseStyle}
+                                dangerouslySetInnerHTML={{ __html: text }}
+                            />
+                        )}
+
+                        {/* Buttons */}
+                        {buttons && buttons.length > 0 && (
+                            <div className="mt-8 flex flex-wrap gap-4">
+                                {buttons.map((btn, idx) => (
+                                    btn.text && btn.url && (
+                                        <a
+                                            key={idx}
+                                            href={btn.url}
+                                            className={cn(
+                                                "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 h-10 px-4 py-2",
+                                                !buttonStyle?.style?.backgroundColor && "bg-primary",
+                                                !buttonStyle?.style?.color && "text-primary-foreground hover:bg-primary/90",
+                                                buttonStyle?.classNames
+                                            )}
+                                            style={buttonStyle?.style}
+                                        >
+                                            {btn.text}
+                                        </a>
+                                    )
+                                ))}
+                            </div>
+                        )}
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+};

admin-spa/src/components/filters/DateRange.tsx

@@ -20,7 +20,7 @@ function fmt(d: Date): string {
 }
 
 export default function DateRange({ value, onChange }: Props) {
-  const [preset, setPreset] = useState<string>(() => "last7");
+  const [preset, setPreset] = useState<string>(() => "last30");
   const [start, setStart] = useState<string | undefined>(value?.date_start);
   const [end, setEnd] = useState<string | undefined>(value?.date_end);
 
@@ -32,8 +32,8 @@ export default function DateRange({ value, onChange }: Props) {
     return {
       today: { date_start: todayStr, date_end: todayStr },
       last7: { date_start: fmt(last7), date_end: todayStr },
-      last30:{ date_start: fmt(last30), date_end: todayStr },
-      custom:{ date_start: start, date_end: end },
+      last30: { date_start: fmt(last30), date_end: todayStr },
+      custom: { date_start: start, date_end: end },
     };
   }, [start, end]);
 
@@ -41,7 +41,7 @@ export default function DateRange({ value, onChange }: Props) {
     if (preset === "custom") {
       onChange?.({ date_start: start, date_end: end, preset });
     } else {
-      const pr = (presets as any)[preset] || presets.last7;
+      const pr = (presets as any)[preset] || presets.last30;
       onChange?.({ ...pr, preset });
       setStart(pr.date_start);
       setEnd(pr.date_end);
@@ -53,7 +53,7 @@ export default function DateRange({ value, onChange }: Props) {
     <div className="flex flex-col lg:flex-row gap-2 w-full">
       <Select value={preset} onValueChange={(v) => setPreset(v)}>
         <SelectTrigger className="w-full">
-          <SelectValue placeholder={__("Last 7 days")} />
+          <SelectValue placeholder={__("Last 30 days")} />
         </SelectTrigger>
         <SelectContent position="popper" className="z-[1000]">
           <SelectGroup>

admin-spa/src/components/forms/SchemaField.tsx

@@ -7,7 +7,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@
 import { Checkbox } from '@/components/ui/checkbox';
 
 export interface FieldSchema {
-  type: 'text' | 'textarea' | 'email' | 'url' | 'number' | 'toggle' | 'checkbox' | 'select';
+  type: 'text' | 'textarea' | 'email' | 'url' | 'number' | 'toggle' | 'checkbox' | 'select' | 'multiselect';
   label: string;
   description?: string;
   placeholder?: string;
@@ -47,8 +47,8 @@ export function SchemaField({ name, schema, value, onChange, error }: SchemaFiel
         return (
           <Input
             type="number"
-            value={value || ''}
-            onChange={(e) => onChange(parseFloat(e.target.value))}
+            value={value ?? ''}
+            onChange={(e) => onChange(e.target.value === '' ? 0 : parseFloat(e.target.value))}
             placeholder={schema.placeholder}
             required={schema.required}
             min={schema.min}
@@ -110,6 +110,35 @@ export function SchemaField({ name, schema, value, onChange, error }: SchemaFiel
           </Select>
         );
 
+      case 'multiselect':
+        const selectedValues = Array.isArray(value) ? value : [];
+        return (
+          <div className="flex flex-wrap gap-2">
+            {schema.options && Object.entries(schema.options).map(([key, label]) => (
+              <label
+                key={key}
+                className={`flex items-center gap-2 px-3 py-2 rounded-lg border cursor-pointer transition-colors ${
+                  selectedValues.includes(key)
+                    ? 'bg-primary/10 border-primary text-primary'
+                    : 'bg-background border-input hover:bg-muted'
+                }`}
+              >
+                <Checkbox
+                  checked={selectedValues.includes(key)}
+                  onCheckedChange={(checked) => {
+                    if (checked) {
+                      onChange([...selectedValues, key]);
+                    } else {
+                      onChange(selectedValues.filter((v: string) => v !== key));
+                    }
+                  }}
+                />
+                <span className="text-sm">{label}</span>
+              </label>
+            ))}
+          </div>
+        );
+
       default:
         return (
           <Input

admin-spa/src/components/layout/AppRoutes.tsx

@@ -0,0 +1,279 @@
+import React from 'react';
+import { Routes, Route, Navigate } from 'react-router-dom';
+import { Loader2 } from 'lucide-react';
+import { __ } from '@/lib/i18n';
+
+// Import all routes
+import ResetPassword from '@/routes/ResetPassword';
+import Dashboard from '@/routes/Dashboard';
+import DashboardRevenue from '@/routes/Dashboard/Revenue';
+import DashboardOrders from '@/routes/Dashboard/Orders';
+import DashboardProducts from '@/routes/Dashboard/Products';
+import DashboardCustomers from '@/routes/Dashboard/Customers';
+import DashboardCoupons from '@/routes/Dashboard/Coupons';
+import DashboardTaxes from '@/routes/Dashboard/Taxes';
+import OrdersIndex from '@/routes/Orders';
+import OrderNew from '@/routes/Orders/New';
+import OrderEdit from '@/routes/Orders/Edit';
+import OrderDetail from '@/routes/Orders/Detail';
+import OrderInvoice from '@/routes/Orders/Invoice';
+import OrderLabel from '@/routes/Orders/Label';
+import ProductsIndex from '@/routes/Products';
+import ProductNew from '@/routes/Products/New';
+import ProductEdit from '@/routes/Products/Edit';
+import ProductCategories from '@/routes/Products/Categories';
+import ProductTags from '@/routes/Products/Tags';
+import ProductAttributes from '@/routes/Products/Attributes';
+import Licenses from '@/routes/Products/Licenses';
+import LicenseDetail from '@/routes/Products/Licenses/Detail';
+import SoftwareVersions from '@/routes/Products/SoftwareVersions';
+import SubscriptionsIndex from '@/routes/Subscriptions';
+import SubscriptionDetail from '@/routes/Subscriptions/Detail';
+import CouponsIndex from '@/routes/Marketing/Coupons';
+import CouponNew from '@/routes/Marketing/Coupons/New';
+import CouponEdit from '@/routes/Marketing/Coupons/Edit';
+import CustomersIndex from '@/routes/Customers';
+import CustomerNew from '@/routes/Customers/New';
+import CustomerEdit from '@/routes/Customers/Edit';
+import CustomerDetail from '@/routes/Customers/Detail';
+import SettingsIndex from '@/routes/Settings';
+import SettingsStore from '@/routes/Settings/Store';
+import SettingsPayments from '@/routes/Settings/Payments';
+import SettingsShipping from '@/routes/Settings/Shipping';
+import SettingsTax from '@/routes/Settings/Tax';
+import SettingsCustomers from '@/routes/Settings/Customers';
+import SettingsSecurity from '@/routes/Settings/Security';
+import SettingsLocalPickup from '@/routes/Settings/LocalPickup';
+import SettingsNotifications from '@/routes/Settings/Notifications';
+import StaffNotifications from '@/routes/Settings/Notifications/Staff';
+import CustomerNotifications from '@/routes/Settings/Notifications/Customer';
+import ChannelConfiguration from '@/routes/Settings/Notifications/ChannelConfiguration';
+import EmailConfiguration from '@/routes/Settings/Notifications/EmailConfiguration';
+import PushConfiguration from '@/routes/Settings/Notifications/PushConfiguration';
+import EmailCustomization from '@/routes/Settings/Notifications/EmailCustomization';
+import EditTemplate from '@/routes/Settings/Notifications/EditTemplate';
+import ActivityLog from '@/routes/Settings/Notifications/ActivityLog';
+import SettingsDeveloper from '@/routes/Settings/Developer';
+import SettingsModules from '@/routes/Settings/Modules';
+import ModuleSettings from '@/routes/Settings/ModuleSettings';
+import AppearanceIndex from '@/routes/Appearance';
+import AppearanceGeneral from '@/routes/Appearance/General';
+import AppearanceHeader from '@/routes/Appearance/Header';
+import AppearanceFooter from '@/routes/Appearance/Footer';
+import AppearanceShop from '@/routes/Appearance/Shop';
+import AppearanceProduct from '@/routes/Appearance/Product';
+import AppearanceCart from '@/routes/Appearance/Cart';
+import AppearanceCheckout from '@/routes/Appearance/Checkout';
+import AppearanceThankYou from '@/routes/Appearance/ThankYou';
+import AppearanceAccount from '@/routes/Appearance/Account';
+import AppearanceMenus from '@/routes/Appearance/Menus/MenuEditor';
+import AppearancePages from '@/routes/Appearance/Pages';
+import MarketingIndex from '@/routes/Marketing';
+import NewsletterLayout from '@/routes/Marketing/Newsletter';
+import NewsletterSubscribers from '@/routes/Marketing/Newsletter/Subscribers';
+import NewsletterCampaignsList from '@/routes/Marketing/Campaigns';
+import CampaignEdit from '@/routes/Marketing/Campaigns/Edit';
+import AffiliatesLayout from '@/routes/Marketing/Affiliates';
+import AffiliatesList from '@/routes/Marketing/Affiliates/List';
+import AffiliatesReferrals from '@/routes/Marketing/Affiliates/Referrals';
+import AffiliatesPayouts from '@/routes/Marketing/Affiliates/Payouts';
+import MorePage from '@/routes/More';
+import Help from '@/routes/Help';
+import Onboarding from '@/routes/Onboarding';
+import { LegacyCampaignRedirect } from '@/components/LegacyCampaignRedirect';
+
+// Addon Route Component - Dynamically loads addon components
+function AddonRoute({ config }: { config: any }) {
+  const [Component, setComponent] = React.useState<any>(null);
+  const [loading, setLoading] = React.useState(true);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (!config.component_url) {
+      setError('No component URL provided');
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    // Dynamically import the addon component
+    import(/* @vite-ignore */ config.component_url)
+      .then((mod) => {
+        setComponent(() => mod.default || mod);
+        setLoading(false);
+      })
+      .catch((err) => {
+        console.error('[AddonRoute] Failed to load component:', err);
+        setError(err.message || 'Failed to load addon component');
+        setLoading(false);
+      });
+  }, [config.component_url]);
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center p-8">
+        <div className="text-center">
+          <Loader2 className="w-8 h-8 animate-spin mx-auto mb-2 opacity-50" />
+          <p className="text-sm opacity-70">{__('Loading addon...')}</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="p-6">
+        <div className="rounded-lg border border-red-200 dark:border-red-800 bg-red-50 dark:bg-red-950/50 p-4">
+          <h3 className="font-semibold text-red-900 dark:text-red-200 mb-2">{__('Failed to Load Addon')}</h3>
+          <p className="text-sm text-red-700 dark:text-red-300">{error}</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (!Component) {
+    return (
+      <div className="p-6">
+        <div className="rounded-lg border border-yellow-200 dark:border-yellow-800 bg-yellow-50 dark:bg-yellow-950/50 p-4">
+          <p className="text-sm text-yellow-700 dark:text-yellow-300">{__('Addon component not found')}</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Render the addon component with props
+  return <Component {...(config.props || {})} />;
+}
+
+export function AppRoutes() {
+  const addonRoutes = window.WNW_ADDON_ROUTES || [];
+
+  return (
+    <Routes>
+      {/* Dashboard */}
+      <Route path="/" element={<Navigate to={window.WNW_CONFIG?.onboardingCompleted ? "/dashboard" : "/setup"} replace />} />
+      <Route path="/setup" element={<Onboarding />} />
+      <Route path="/reset-password" element={<ResetPassword />} />
+      <Route path="/dashboard" element={<Dashboard />} />
+      <Route path="/dashboard/revenue" element={<DashboardRevenue />} />
+      <Route path="/dashboard/orders" element={<DashboardOrders />} />
+      <Route path="/dashboard/products" element={<DashboardProducts />} />
+      <Route path="/dashboard/customers" element={<DashboardCustomers />} />
+      <Route path="/dashboard/coupons" element={<DashboardCoupons />} />
+      <Route path="/dashboard/taxes" element={<DashboardTaxes />} />
+
+      {/* Products */}
+      <Route path="/products" element={<ProductsIndex />} />
+      <Route path="/products/new" element={<ProductNew />} />
+      <Route path="/products/:id/edit" element={<ProductEdit />} />
+      <Route path="/products/categories" element={<ProductCategories />} />
+      <Route path="/products/tags" element={<ProductTags />} />
+      <Route path="/products/attributes" element={<ProductAttributes />} />
+      <Route path="/products/licenses" element={<Licenses />} />
+      <Route path="/products/licenses/:id" element={<LicenseDetail />} />
+      <Route path="/products/software" element={<SoftwareVersions />} />
+
+      {/* Orders */}
+      <Route path="/orders" element={<OrdersIndex />} />
+      <Route path="/orders/new" element={<OrderNew />} />
+      <Route path="/orders/:id" element={<OrderDetail />} />
+      <Route path="/orders/:id/edit" element={<OrderEdit />} />
+      <Route path="/orders/:id/invoice" element={<OrderInvoice />} />
+      <Route path="/orders/:id/label" element={<OrderLabel />} />
+
+      {/* Subscriptions */}
+      <Route path="/subscriptions" element={<SubscriptionsIndex />} />
+      <Route path="/subscriptions/:id" element={<SubscriptionDetail />} />
+
+      {/* Coupons (under Marketing) */}
+      <Route path="/coupons" element={<Navigate to="/marketing/coupons" replace />} />
+      <Route path="/coupons/new" element={<Navigate to="/marketing/coupons/new" replace />} />
+      <Route path="/coupons/:id/edit" element={<CouponEdit />} />
+      <Route path="/marketing/coupons" element={<CouponsIndex />} />
+      <Route path="/marketing/coupons/new" element={<CouponNew />} />
+      <Route path="/marketing/coupons/:id/edit" element={<CouponEdit />} />
+
+      {/* Customers */}
+      <Route path="/customers" element={<CustomersIndex />} />
+      <Route path="/customers/new" element={<CustomerNew />} />
+      <Route path="/customers/:id/edit" element={<CustomerEdit />} />
+      <Route path="/customers/:id" element={<CustomerDetail />} />
+
+      {/* More */}
+      <Route path="/more" element={<MorePage />} />
+
+      {/* Settings */}
+      <Route path="/settings" element={<SettingsIndex />} />
+      <Route path="/settings/store" element={<SettingsStore />} />
+      <Route path="/settings/payments" element={<SettingsPayments />} />
+      <Route path="/settings/shipping" element={<SettingsShipping />} />
+      <Route path="/settings/tax" element={<SettingsTax />} />
+      <Route path="/settings/customers" element={<SettingsCustomers />} />
+      <Route path="/settings/security" element={<SettingsSecurity />} />
+      <Route path="/settings/taxes" element={<Navigate to="/settings/tax" replace />} />
+      <Route path="/settings/local-pickup" element={<SettingsLocalPickup />} />
+      <Route path="/settings/checkout" element={<SettingsIndex />} />
+      <Route path="/settings/notifications" element={<SettingsNotifications />} />
+      <Route path="/settings/notifications/staff" element={<StaffNotifications />} />
+      <Route path="/settings/notifications/customer" element={<CustomerNotifications />} />
+      <Route path="/settings/notifications/channels" element={<ChannelConfiguration />} />
+      <Route path="/settings/notifications/channels/email" element={<EmailConfiguration />} />
+      <Route path="/settings/notifications/channels/push" element={<PushConfiguration />} />
+      <Route path="/settings/notifications/email-customization" element={<EmailCustomization />} />
+      <Route path="/settings/notifications/edit-template" element={<EditTemplate />} />
+      <Route path="/settings/notifications/activity-log" element={<ActivityLog />} />
+      <Route path="/settings/brand" element={<SettingsIndex />} />
+      <Route path="/settings/developer" element={<SettingsDeveloper />} />
+      <Route path="/settings/modules" element={<SettingsModules />} />
+      <Route path="/settings/modules/:moduleId" element={<ModuleSettings />} />
+
+      {/* Appearance */}
+      <Route path="/appearance" element={<AppearanceIndex />} />
+      <Route path="/appearance/general" element={<AppearanceGeneral />} />
+      <Route path="/appearance/header" element={<AppearanceHeader />} />
+      <Route path="/appearance/footer" element={<AppearanceFooter />} />
+      <Route path="/appearance/shop" element={<AppearanceShop />} />
+      <Route path="/appearance/product" element={<AppearanceProduct />} />
+      <Route path="/appearance/cart" element={<AppearanceCart />} />
+      <Route path="/appearance/checkout" element={<AppearanceCheckout />} />
+      <Route path="/appearance/thankyou" element={<AppearanceThankYou />} />
+      <Route path="/appearance/account" element={<AppearanceAccount />} />
+      <Route path="/appearance/menus" element={<AppearanceMenus />} />
+      <Route path="/appearance/pages" element={<AppearancePages />} />
+
+      {/* Marketing */}
+      <Route path="/marketing" element={<MarketingIndex />} />
+      <Route path="/marketing/newsletter" element={<NewsletterLayout />}>
+        <Route index element={<Navigate to="subscribers" replace />} />
+        <Route path="subscribers" element={<NewsletterSubscribers />} />
+        <Route path="campaigns" element={<NewsletterCampaignsList />} />
+        <Route path="campaigns/:id" element={<CampaignEdit />} />
+      </Route>
+      <Route path="/marketing/affiliates" element={<AffiliatesLayout />}>
+        <Route index element={<Navigate to="list" replace />} />
+        <Route path="list" element={<AffiliatesList />} />
+        <Route path="referrals" element={<AffiliatesReferrals />} />
+        <Route path="payouts" element={<AffiliatesPayouts />} />
+      </Route>
+
+      {/* Legacy Redirects for Newsletter (using component to preserve params) */}
+      <Route path="/marketing/campaigns" element={<Navigate to="/marketing/newsletter/campaigns" replace />} />
+      <Route path="/marketing/campaigns/new" element={<Navigate to="/marketing/newsletter/campaigns/new" replace />} />
+      <Route path="/marketing/campaigns/:id" element={<LegacyCampaignRedirect />} />
+
+      {/* Help - Main menu route with no submenu */}
+      <Route path="/help" element={<Help />} />
+
+      {/* Dynamic Addon Routes */}
+      {addonRoutes.map((route: any) => (
+        <Route
+          key={route.path}
+          path={route.path}
+          element={<AddonRoute config={route} />}
+        />
+      ))}
+    </Routes>
+  );
+}

admin-spa/src/components/layout/AuthWrapper.tsx

@@ -0,0 +1,56 @@
+import { useState, useEffect } from 'react';
+import { useLocation, Navigate } from 'react-router-dom';
+import { Loader2 } from 'lucide-react';
+import { Shell } from './Shell';
+import { DashboardProvider } from '@/contexts/DashboardContext';
+import { PageHeaderProvider } from '@/contexts/PageHeaderContext';
+import { FABProvider } from '@/contexts/FABContext';
+
+export function AuthWrapper() {
+  const [isAuthenticated, setIsAuthenticated] = useState(
+    window.WNW_CONFIG?.isAuthenticated ?? true
+  );
+  const [isChecking, setIsChecking] = useState(window.WNW_CONFIG?.standaloneMode ?? false);
+  const location = useLocation();
+
+  useEffect(() => {
+    // In standalone mode, trust the initial PHP auth check
+    // PHP uses wp_signon which sets proper WordPress cookies
+    const checkAuth = () => {
+      if (window.WNW_CONFIG?.standaloneMode) {
+        setIsAuthenticated(window.WNW_CONFIG.isAuthenticated ?? false);
+        setIsChecking(false);
+      } else {
+        // In wp-admin mode, always authenticated
+        setIsChecking(false);
+      }
+    };
+    checkAuth();
+  }, []);
+
+  if (isChecking) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <Loader2 className="w-12 h-12 animate-spin text-primary" />
+      </div>
+    );
+  }
+
+  if (window.WNW_CONFIG?.standaloneMode && !isAuthenticated && location.pathname !== '/login') {
+    return <Navigate to="/login" replace />;
+  }
+
+  if (location.pathname === '/login' && isAuthenticated) {
+    return <Navigate to="/" replace />;
+  }
+
+  return (
+    <FABProvider>
+      <PageHeaderProvider>
+        <DashboardProvider>
+          <Shell />
+        </DashboardProvider>
+      </PageHeaderProvider>
+    </FABProvider>
+  );
+}

admin-spa/src/components/layout/Header.tsx

@@ -0,0 +1,211 @@
+import React from 'react';
+import { ExternalLink, Maximize2, Minimize2 } from 'lucide-react';
+import { __ } from '@/lib/i18n';
+import { ThemeToggle } from '@/components/ThemeToggle';
+
+export function Header({ 
+  onFullscreen, 
+  fullscreen, 
+  showToggle = true, 
+  scrollContainerRef, 
+  onVisibilityChange 
+}: { 
+  onFullscreen: () => void; 
+  fullscreen: boolean; 
+  showToggle?: boolean; 
+  scrollContainerRef?: React.RefObject<HTMLDivElement>; 
+  onVisibilityChange?: (visible: boolean) => void;
+}) {
+  const [siteTitle, setSiteTitle] = React.useState(window.wnw?.siteTitle || 'WooNooW');
+  const [storeLogo, setStoreLogo] = React.useState('');
+  const [storeLogoDark, setStoreLogoDark] = React.useState('');
+  const [isVisible, setIsVisible] = React.useState(true);
+  const lastScrollYRef = React.useRef(0);
+  const isStandalone = window.WNW_CONFIG?.standaloneMode ?? false;
+  const [isDark, setIsDark] = React.useState(false);
+
+  // Detect dark mode
+  React.useEffect(() => {
+    const checkDarkMode = () => {
+      const htmlEl = document.documentElement;
+      setIsDark(htmlEl.classList.contains('dark'));
+    };
+
+    checkDarkMode();
+
+    // Watch for theme changes
+    const observer = new MutationObserver(checkDarkMode);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class']
+    });
+
+    return () => observer.disconnect();
+  }, []);
+
+  // Notify parent of visibility changes
+  React.useEffect(() => {
+    onVisibilityChange?.(isVisible);
+  }, [isVisible, onVisibilityChange]);
+
+  // Fetch store branding on mount
+  React.useEffect(() => {
+    const fetchBranding = async () => {
+      try {
+        const response = await fetch((window.WNW_CONFIG?.restUrl || '') + '/store/branding');
+        if (response.ok) {
+          const data = await response.json();
+          if (data.store_logo) setStoreLogo(data.store_logo);
+          if (data.store_logo_dark) setStoreLogoDark(data.store_logo_dark);
+          if (data.store_name) setSiteTitle(data.store_name);
+        }
+      } catch (err) {
+        console.error('Failed to fetch branding:', err);
+      }
+    };
+    fetchBranding();
+  }, []);
+
+  // Listen for store settings updates
+  React.useEffect(() => {
+    const handleStoreUpdate = (event: CustomEvent) => {
+      if (event.detail?.store_logo) setStoreLogo(event.detail.store_logo);
+      if (event.detail?.store_logo_dark) setStoreLogoDark(event.detail.store_logo_dark);
+      if (event.detail?.store_name) setSiteTitle(event.detail.store_name);
+    };
+
+    window.addEventListener('woonoow:store:updated' as any, handleStoreUpdate);
+    return () => window.removeEventListener('woonoow:store:updated' as any, handleStoreUpdate);
+  }, []);
+
+  // Hide/show header on scroll (mobile only)
+  React.useEffect(() => {
+    const scrollContainer = scrollContainerRef?.current;
+    if (!scrollContainer) return;
+
+    const handleScroll = () => {
+      const currentScrollY = scrollContainer.scrollTop;
+
+      // Only apply on mobile (check window width)
+      if (window.innerWidth >= 768) {
+        setIsVisible(true);
+        return;
+      }
+
+      if (currentScrollY > lastScrollYRef.current && currentScrollY > 50) {
+        // Scrolling down & past threshold
+        setIsVisible(false);
+      } else if (currentScrollY < lastScrollYRef.current) {
+        // Scrolling up
+        setIsVisible(true);
+      }
+
+      lastScrollYRef.current = currentScrollY;
+    };
+
+    scrollContainer.addEventListener('scroll', handleScroll, { passive: true });
+
+    return () => {
+      scrollContainer.removeEventListener('scroll', handleScroll);
+    };
+  }, [scrollContainerRef]);
+
+  const handleLogout = async () => {
+    try {
+      await fetch((window.WNW_CONFIG?.restUrl || '') + '/auth/logout', {
+        method: 'POST',
+        credentials: 'include',
+      });
+      window.location.reload();
+    } catch (err) {
+      console.error('Logout failed:', err);
+    }
+  };
+
+  // Hide header completely on mobile in fullscreen mode (both standalone and wp-admin fullscreen)
+  if (fullscreen && typeof window !== 'undefined' && window.innerWidth < 768) {
+    return null;
+  }
+
+  // Choose logo based on theme
+  const currentLogo = isDark && storeLogoDark ? storeLogoDark : storeLogo;
+
+  return (
+    <header className={`h-16 border-b border-border flex items-center px-4 justify-between sticky ${fullscreen ? `top-0` : `top-[32px]`} z-40 bg-background md:bg-background/95 md:backdrop-blur md:supports-[backdrop-filter]:bg-background/60 transition-transform duration-300 ${fullscreen && !isVisible ? '-translate-y-full md:translate-y-0' : 'translate-y-0'}`}>
+      <div className="flex items-center gap-3">
+        {currentLogo ? (
+          <img src={currentLogo} alt={siteTitle} className="h-8 object-contain" />
+        ) : (
+          <div className="font-semibold">{siteTitle}</div>
+        )}
+
+        {!(window.WNW_CONFIG?.customerSpaEnabled) && (
+          <a
+            href={window.WNW_CONFIG?.storeUrl || '/store/'}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="ml-2 inline-flex items-center gap-1.5 text-sm font-medium text-muted-foreground hover:text-foreground transition-colors"
+            title={__('Visit Store')}
+          >
+            <ExternalLink className="w-4 h-4" />
+            <span className="hidden sm:inline">{__('Store')}</span>
+          </a>
+        )}
+      </div>
+      <div className="flex items-center gap-3">
+        <div className="text-sm opacity-70 hidden sm:block">{window.WNW_API?.isDev ? 'Dev Server' : 'Production'}</div>
+        {isStandalone && (
+          <>
+            <a
+              href={window.WNW_CONFIG?.wpAdminUrl || '/wp-admin'}
+              className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
+              title="Go to WordPress Admin"
+            >
+              <span>{__('WordPress')}</span>
+            </a>
+            {window.WNW_CONFIG?.customerSpaEnabled && (
+              <a
+                href={window.WNW_CONFIG?.storeUrl || '/store/'}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
+                title="Open Store"
+              >
+                <span>{__('Store')}</span>
+              </a>
+            )}
+            <button
+              onClick={handleLogout}
+              className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
+              title="Logout"
+            >
+              <span>{__('Logout')}</span>
+            </button>
+          </>
+        )}
+        {!isStandalone && window.WNW_CONFIG?.customerSpaEnabled && (
+          <a
+            href={window.WNW_CONFIG?.storeUrl || '/store/'}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
+            title="Open Store"
+          >
+            <span>{__('Store')}</span>
+          </a>
+        )}
+        <ThemeToggle />
+        {showToggle && (
+          <button
+            onClick={onFullscreen}
+            className="inline-flex items-center gap-2 border rounded-md px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"
+            title={fullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+          >
+            {fullscreen ? <Minimize2 className="w-4 h-4" /> : <Maximize2 className="w-4 h-4" />}
+            <span className="hidden sm:inline">{fullscreen ? 'Exit' : 'Fullscreen'}</span>
+          </button>
+        )}
+      </div>
+    </header>
+  );
+}

admin-spa/src/components/layout/Shell.tsx

@@ -0,0 +1,162 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { useLocation } from 'react-router-dom';
+import { useFullscreen } from '@/hooks/useFullscreen';
+import { useIsDesktop } from '@/hooks/useIsDesktop';
+import { useActiveSection } from '@/hooks/useActiveSection';
+import { useShortcuts } from '@/hooks/useShortcuts';
+import { CommandPalette } from '@/components/CommandPalette';
+import { PageHeader } from '@/components/PageHeader';
+import { BottomNav } from '@/components/nav/BottomNav';
+import { FAB } from '@/components/FAB';
+import SubmenuBar from '@/components/nav/SubmenuBar';
+import DashboardSubmenuBar from '@/components/nav/DashboardSubmenuBar';
+import { AppProvider } from '@/contexts/AppContext';
+import { Header } from './Header';
+import { Sidebar } from './Sidebar';
+import { TopNav } from './TopNav';
+import { AppRoutes } from './AppRoutes';
+
+function ShortcutsBinder({ onToggle }: { onToggle: () => void }) {
+  useShortcuts({ toggleFullscreen: onToggle });
+  return null;
+}
+
+export function Shell() {
+  const { on, setOn } = useFullscreen();
+  const { main } = useActiveSection();
+  const toggle = () => setOn(v => !v);
+  const exitFullscreen = () => setOn(false);
+  const isDesktop = useIsDesktop();
+  const location = useLocation();
+  const scrollContainerRef = useRef<HTMLDivElement>(null);
+
+  // Sidebar collapsed state with localStorage persistence
+  const [sidebarCollapsed, setSidebarCollapsed] = useState<boolean>(() => {
+    try { return localStorage.getItem('wnwSidebarCollapsed') === '1'; } catch { return false; }
+  });
+  const [wasAutoCollapsed, setWasAutoCollapsed] = useState(false);
+
+  // Save sidebar state to localStorage
+  useEffect(() => {
+    try { localStorage.setItem('wnwSidebarCollapsed', sidebarCollapsed ? '1' : '0'); } catch { /* ignore */ }
+  }, [sidebarCollapsed]);
+
+  // Check if current route is Page Editor (auto-collapse route)
+  const isPageEditorRoute = location.pathname === '/appearance/pages';
+
+  // Auto-collapse/expand sidebar based on route
+  useEffect(() => {
+    if (isPageEditorRoute) {
+      // Auto-collapse when entering Page Editor (if not already collapsed)
+      if (!sidebarCollapsed) {
+        setSidebarCollapsed(true);
+        setWasAutoCollapsed(true);
+      }
+    } else {
+      // Auto-expand when leaving Page Editor (only if we auto-collapsed it)
+      if (wasAutoCollapsed && sidebarCollapsed) {
+        setSidebarCollapsed(false);
+        setWasAutoCollapsed(false);
+      }
+    }
+  }, [isPageEditorRoute]);
+
+  const toggleSidebar = () => {
+    setSidebarCollapsed(v => !v);
+    setWasAutoCollapsed(false); // Manual toggle clears auto state
+  };
+
+  // Check if standalone mode - force fullscreen and hide toggle
+  const isStandalone = window.WNW_CONFIG?.standaloneMode ?? false;
+  const fullscreen = isStandalone ? true : on;
+
+  // Check if current route is dashboard
+  const isDashboardRoute = location.pathname === '/' || location.pathname.startsWith('/dashboard');
+
+  // Check if current route is More page (no submenu needed)
+  const isMorePage = location.pathname === '/more';
+
+  const submenuTopClass = fullscreen ? 'top-0' : 'top-[calc(7rem+32px)]';
+  const submenuZIndex = fullscreen ? 'z-50' : 'z-40';
+
+  // Check if current route is setup/onboarding
+  const isSetup = location.pathname === '/setup';
+
+  if (isSetup) {
+    return (
+      <AppProvider isStandalone={isStandalone} exitFullscreen={exitFullscreen}>
+        <div className="min-h-screen bg-background text-foreground flex flex-col">
+          <AppRoutes />
+        </div>
+      </AppProvider>
+    );
+  }
+
+  return (
+    <AppProvider isStandalone={isStandalone} exitFullscreen={exitFullscreen}>
+      {!isStandalone && <ShortcutsBinder onToggle={toggle} />}
+      {!isStandalone && <CommandPalette toggleFullscreen={toggle} />}
+      <div className={`flex flex-col min-h-screen ${fullscreen ? 'woonoow-fullscreen-root' : ''}`}>
+        <Header onFullscreen={toggle} fullscreen={fullscreen} showToggle={!isStandalone} scrollContainerRef={scrollContainerRef} />
+        {fullscreen ? (
+          isDesktop ? (
+            <div className="flex flex-1 min-h-0">
+              <Sidebar collapsed={sidebarCollapsed} onToggle={toggleSidebar} />
+              <main className="flex-1 flex flex-col min-h-0 min-w-0">
+                {/* Flex wrapper: desktop = col-reverse (SubmenuBar first, PageHeader second) */}
+                <div className="flex flex-col-reverse">
+                  <PageHeader fullscreen={true} />
+                  {isDashboardRoute ? (
+                    <DashboardSubmenuBar items={main.children} fullscreen={true} />
+                  ) : (
+                    <SubmenuBar items={main.children} fullscreen={true} />
+                  )}
+                </div>
+                <div className="flex-1 overflow-auto p-4 min-w-0">
+                  <AppRoutes />
+                </div>
+              </main>
+            </div>
+          ) : (
+            <div className="flex flex-1 flex-col min-h-0">
+              {/* Flex wrapper: mobile = col (PageHeader first), desktop = col-reverse (SubmenuBar first) */}
+              <div className={`flex flex-col md:flex-col-reverse sticky ${submenuTopClass} ${submenuZIndex}`}>
+                <PageHeader fullscreen={true} />
+                {!isMorePage && (isDashboardRoute ? (
+                  <DashboardSubmenuBar items={main.children} fullscreen={true} />
+                ) : (
+                  <SubmenuBar items={main.children} fullscreen={true} />
+                ))}
+              </div>
+              <main className="flex-1 flex flex-col min-h-0 min-w-0 pb-14">
+                <div ref={scrollContainerRef} className="flex-1 overflow-auto p-4 min-w-0">
+                  <AppRoutes />
+                </div>
+              </main>
+              <BottomNav />
+              <FAB />
+            </div>
+          )
+        ) : (
+          <div className="flex flex-1 flex-col min-h-0">
+            <TopNav fullscreen={false} />
+            {/* Flex wrapper: mobile = col (PageHeader first), desktop = col-reverse (SubmenuBar first) */}
+            <div className={`flex flex-col md:flex-col-reverse sticky ${submenuTopClass} ${submenuZIndex}`}>
+              <PageHeader fullscreen={false} />
+              {isDashboardRoute ? (
+                <DashboardSubmenuBar items={main.children} fullscreen={false} />
+              ) : (
+                <SubmenuBar items={main.children} fullscreen={false} />
+              )}
+            </div>
+            <main className="flex-1 flex flex-col min-h-0 min-w-0">
+              <div className="flex-1 overflow-auto p-4 min-w-0">
+                <AppRoutes />
+              </div>
+            </main>
+          </div>
+        )}
+      </div>
+    </AppProvider>
+  );
+}

admin-spa/src/components/layout/Sidebar.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+import { PanelLeft, PanelLeftClose, Package } from 'lucide-react';
+import { useActiveSection } from '@/hooks/useActiveSection';
+import { __ } from '@/lib/i18n';
+import { iconMap } from '@/lib/nav-icons';
+
+interface SidebarProps {
+  collapsed: boolean;
+  onToggle: () => void;
+}
+
+export function Sidebar({ collapsed, onToggle }: SidebarProps) {
+  const link = "flex items-center gap-2 rounded-md px-3 py-2 hover:bg-accent hover:text-accent-foreground shadow-none hover:shadow-none focus:shadow-none focus:outline-none focus:ring-0 transition-all";
+  const linkCollapsed = "flex items-center justify-center rounded-md p-2 hover:bg-accent hover:text-accent-foreground shadow-none hover:shadow-none focus:shadow-none focus:outline-none focus:ring-0 transition-all";
+  const active = "bg-secondary";
+  const { main } = useActiveSection();
+
+  // Get navigation tree from backend
+  const navTree = window.WNW_NAV_TREE || [];
+
+  return (
+    <aside className={`flex-shrink-0 border-r border-border sticky top-16 h-[calc(100vh-64px)] overflow-y-auto bg-background flex flex-col transition-all duration-200 ${collapsed ? 'w-14' : 'w-56'}`}>
+      {/* Toggle button */}
+      <div className={`p-2 border-b border-border ${collapsed ? 'flex justify-center' : 'flex justify-end'}`}>
+        <button
+          onClick={onToggle}
+          className="p-2 rounded-md hover:bg-accent hover:text-accent-foreground transition-colors"
+          title={collapsed ? __('Expand sidebar') : __('Collapse sidebar')}
+        >
+          {collapsed ? <PanelLeft className="w-4 h-4" /> : <PanelLeftClose className="w-4 h-4" />}
+        </button>
+      </div>
+
+      <nav className={`flex flex-col gap-1 flex-1 ${collapsed ? 'p-1' : 'p-3'}`}>
+        {navTree.map((item: any) => {
+          const IconComponent = iconMap[item.icon] || Package;
+          const isActive = main.key === item.key;
+          return (
+            <Link
+              key={item.key}
+              to={item.path}
+              className={`${collapsed ? linkCollapsed : link} ${isActive ? active : ''}`}
+              title={collapsed ? item.label : undefined}
+            >
+              <IconComponent className="w-4 h-4 flex-shrink-0" />
+              {!collapsed && <span>{item.label}</span>}
+            </Link>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}

admin-spa/src/components/layout/TopNav.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+import { Package } from 'lucide-react';
+import { useActiveSection } from '@/hooks/useActiveSection';
+import { iconMap } from '@/lib/nav-icons';
+
+export function TopNav({ fullscreen = false }: { fullscreen?: boolean }) {
+  const link = "inline-flex items-center gap-2 rounded-md px-3 py-2 hover:bg-accent hover:text-accent-foreground shadow-none hover:shadow-none focus:shadow-none focus:outline-none focus:ring-0";
+  const active = "bg-secondary";
+  const topClass = fullscreen ? 'top-16' : 'top-[calc(4rem+32px)]';
+  const { main } = useActiveSection();
+
+  // Get navigation tree from backend
+  const navTree = window.WNW_NAV_TREE || [];
+
+  return (
+    <div data-mainmenu className={`border-b border-border sticky ${topClass} z-30 bg-background md:bg-background/95 md:backdrop-blur md:supports-[backdrop-filter]:bg-background/60`}>
+      <div className="px-4 h-12 flex flex-nowrap overflow-auto items-center gap-2">
+        {navTree.map((item: any) => {
+          const IconComponent = iconMap[item.icon] || Package;
+          const isActive = main.key === item.key;
+          return (
+            <Link
+              key={item.key}
+              to={item.path}
+              className={`${link} ${isActive ? active : ''}`}
+            >
+              <IconComponent className="w-4 h-4" />
+              <span className="text-sm font-medium">{item.label}</span>
+            </Link>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

admin-spa/src/components/ui/accordion.tsx

@@ -44,7 +44,7 @@ const AccordionContent = React.forwardRef<
 >(({ className, children, ...props }, ref) => (
   <AccordionPrimitive.Content
     ref={ref}
-    className="overflow-hidden text-sm transition-all data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+    className="text-sm transition-all data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
     {...props}
   >
     <div className={cn("pb-4 pt-0", className)}>{children}</div>

admin-spa/src/components/ui/alert-dialog.tsx

@@ -16,7 +16,7 @@ const AlertDialogOverlay = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <AlertDialogPrimitive.Overlay
     className={cn(
-      "fixed inset-0 z-[999] bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      "fixed inset-0 z-[99999] bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
       className
     )}
     {...props}
@@ -28,19 +28,45 @@ AlertDialogOverlay.displayName = AlertDialogPrimitive.Overlay.displayName
 const AlertDialogContent = React.forwardRef<
   React.ElementRef<typeof AlertDialogPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
->(({ className, ...props }, ref) => (
-  <AlertDialogPortal>
+>(({ className, ...props }, ref) => {
+  // Get or create portal container inside the app for proper CSS scoping
+  const getPortalContainer = () => {
+    const appContainer = document.getElementById('woonoow-admin-app');
+    if (!appContainer) return document.body;
+
+    let portalRoot = document.getElementById('woonoow-dialog-portal');
+    if (!portalRoot) {
+      portalRoot = document.createElement('div');
+      portalRoot.id = 'woonoow-dialog-portal';
+      // Copy theme class from documentElement for proper CSS variable inheritance
+      const themeClass = document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+      portalRoot.className = themeClass;
+      appContainer.appendChild(portalRoot);
+    } else {
+      // Update theme class in case it changed
+      const themeClass = document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+      if (!portalRoot.classList.contains(themeClass)) {
+        portalRoot.classList.remove('light', 'dark');
+        portalRoot.classList.add(themeClass);
+      }
+    }
+    return portalRoot;
+  };
+
+  return (
+    <AlertDialogPortal container={getPortalContainer()}>
       <AlertDialogOverlay />
       <AlertDialogPrimitive.Content
         ref={ref}
         className={cn(
-        "fixed left-[50%] top-[50%] z-[999] grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+          "fixed left-[50%] top-[50%] z-[99999] grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
           className
         )}
         {...props}
       />
     </AlertDialogPortal>
-))
+  );
+})
 AlertDialogContent.displayName = AlertDialogPrimitive.Content.displayName
 
 const AlertDialogHeader = ({

admin-spa/src/components/ui/dialog.tsx

@@ -40,7 +40,17 @@ const DialogContent = React.forwardRef<
     if (!portalRoot) {
       portalRoot = document.createElement('div');
       portalRoot.id = 'woonoow-dialog-portal';
+      // Copy theme class from documentElement for proper CSS variable inheritance
+      const themeClass = document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+      portalRoot.className = themeClass;
       appContainer.appendChild(portalRoot);
+    } else {
+      // Update theme class in case it changed
+      const themeClass = document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+      if (!portalRoot.classList.contains(themeClass)) {
+        portalRoot.classList.remove('light', 'dark');
+        portalRoot.classList.add(themeClass);
+      }
     }
     return portalRoot;
   };

admin-spa/src/components/ui/dropdown-menu.tsx

@@ -57,8 +57,33 @@ DropdownMenuSubContent.displayName =
 const DropdownMenuContent = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
->(({ className, sideOffset = 4, ...props }, ref) => (
-  <DropdownMenuPrimitive.Portal>
+>(({ className, sideOffset = 4, ...props }, ref) => {
+  // Get or create portal container inside the app for proper CSS scoping
+  const getPortalContainer = () => {
+    const appContainer = document.getElementById('woonoow-admin-app');
+    if (!appContainer) return document.body;
+
+    let portalRoot = document.getElementById('woonoow-dropdown-portal');
+    if (!portalRoot) {
+      portalRoot = document.createElement('div');
+      portalRoot.id = 'woonoow-dropdown-portal';
+      // Copy theme class from documentElement for proper CSS variable inheritance
+      const themeClass = document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+      portalRoot.className = themeClass;
+      appContainer.appendChild(portalRoot);
+    } else {
+      // Update theme class in case it changed
+      const themeClass = document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+      if (!portalRoot.classList.contains(themeClass)) {
+        portalRoot.classList.remove('light', 'dark');
+        portalRoot.classList.add(themeClass);
+      }
+    }
+    return portalRoot;
+  };
+
+  return (
+    <DropdownMenuPrimitive.Portal container={getPortalContainer()}>
       <DropdownMenuPrimitive.Content
         ref={ref}
         sideOffset={sideOffset}
@@ -70,7 +95,8 @@ const DropdownMenuContent = React.forwardRef<
         {...props}
       />
     </DropdownMenuPrimitive.Portal>
-))
+  );
+})
 DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName
 
 const DropdownMenuItem = React.forwardRef<

admin-spa/src/components/ui/markdown-toolbar.tsx

@@ -93,7 +93,7 @@ export function MarkdownToolbar({ onInsert }: MarkdownToolbarProps) {
               Choose a card type to insert into your template
             </DialogDescription>
           </DialogHeader>
-          <div className="space-y-4 py-4">
+          <div className="space-y-4 px-6 py-4">
             <div className="space-y-2">
               <label className="text-sm font-medium">Card Type</label>
               <Select value={selectedCardType} onValueChange={setSelectedCardType}>
@@ -140,7 +140,7 @@ export function MarkdownToolbar({ onInsert }: MarkdownToolbarProps) {
               Choose a button style to insert
             </DialogDescription>
           </DialogHeader>
-          <div className="space-y-4 py-4">
+          <div className="space-y-4 px-6 py-4">
             <div className="space-y-2">
               <label className="text-sm font-medium">Button Style</label>
               <Select value={buttonStyle} onValueChange={setButtonStyle}>
@@ -191,7 +191,7 @@ export function MarkdownToolbar({ onInsert }: MarkdownToolbarProps) {
               Insert an image using standard Markdown syntax
             </DialogDescription>
           </DialogHeader>
-          <div className="space-y-4 py-4">
+          <div className="space-y-4 px-6 py-4">
             <div className="text-sm text-muted-foreground">
               <p>Syntax: <code className="px-1 py-0.5 bg-muted rounded">![Alt text](image-url)</code></p>
               <p className="mt-2">Example: <code className="px-1 py-0.5 bg-muted rounded">![Logo](https://example.com/logo.png)</code></p>

admin-spa/src/components/ui/popover.tsx

@@ -13,7 +13,7 @@ const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
 >(({ className, align = "center", sideOffset = 4, ...props }, ref) => (
-  <PopoverPrimitive.Portal>
+  <PopoverPrimitive.Portal container={document.getElementById("woonoow-admin-app")}>
     <PopoverPrimitive.Content
       ref={ref}
       align={align}

admin-spa/src/components/ui/rich-text-editor.tsx

@@ -50,6 +50,8 @@ export function RichTextEditor({
       Placeholder.configure({
         placeholder,
       }),
+      // ButtonExtension MUST come before Link to ensure buttons are parsed first
+      ButtonExtension,
       Link.configure({
         openOnClick: false,
         HTMLAttributes: {
@@ -65,7 +67,6 @@ export function RichTextEditor({
           class: 'max-w-full h-auto rounded',
         },
       }),
-      ButtonExtension,
     ],
     content,
     onUpdate: ({ editor }) => {
@@ -85,7 +86,6 @@ export function RichTextEditor({
       const currentContent = editor.getHTML();
       // Only update if content is different (avoid infinite loops)
       if (content !== currentContent) {
-        console.log('RichTextEditor: Updating content', { content, currentContent });
         editor.commands.setContent(content);
       }
     }
@@ -112,7 +112,7 @@ export function RichTextEditor({
   const [buttonDialogOpen, setButtonDialogOpen] = useState(false);
   const [buttonText, setButtonText] = useState('Click Here');
   const [buttonHref, setButtonHref] = useState('{order_url}');
-  const [buttonStyle, setButtonStyle] = useState<'solid' | 'outline'>('solid');
+  const [buttonStyle, setButtonStyle] = useState<'solid' | 'outline' | 'link'>('solid');
   const [isEditingButton, setIsEditingButton] = useState(false);
   const [editingButtonPos, setEditingButtonPos] = useState<number | null>(null);
 
@@ -387,12 +387,12 @@ export function RichTextEditor({
                 </div>
               </div>
             )}
-            {/* Customer Variables */}
-            {variables.some(v => v.startsWith('customer') || v.includes('_name') && !v.startsWith('order') && !v.startsWith('site')) && (
+            {/* Subscriber/Customer Variables */}
+            {variables.some(v => v.startsWith('customer') || v.startsWith('subscriber') || (v.includes('_name') && !v.startsWith('order') && !v.startsWith('site') && !v.startsWith('store'))) && (
               <div>
-                <div className="text-[10px] uppercase text-muted-foreground mb-1.5 font-medium">{__('Customer')}</div>
+                <div className="text-[10px] uppercase text-muted-foreground mb-1.5 font-medium">{__('Subscriber')}</div>
                 <div className="flex flex-wrap gap-1">
-                  {variables.filter(v => v.startsWith('customer') || (v.includes('address') && !v.startsWith('shipping'))).map((variable) => (
+                  {variables.filter(v => v.startsWith('customer') || v.startsWith('subscriber') || (v.includes('address') && !v.startsWith('shipping'))).map((variable) => (
                     <button
                       key={variable}
                       type="button"
@@ -424,11 +424,11 @@ export function RichTextEditor({
               </div>
             )}
             {/* Store/Site Variables */}
-            {variables.some(v => v.startsWith('site') || v.startsWith('store') || v.startsWith('shop') || v.includes('_url') || v.startsWith('support') || v.startsWith('review')) && (
+            {variables.some(v => v.startsWith('site') || v.startsWith('store') || v.startsWith('shop') || v.startsWith('current') || v.includes('_url') || v.startsWith('support') || v.startsWith('review')) && (
               <div>
                 <div className="text-[10px] uppercase text-muted-foreground mb-1.5 font-medium">{__('Store & Links')}</div>
                 <div className="flex flex-wrap gap-1">
-                  {variables.filter(v => v.startsWith('site') || v.startsWith('store') || v.startsWith('shop') || v.startsWith('my_account') || v.startsWith('support') || v.startsWith('review') || (v.includes('_url') && !v.startsWith('order') && !v.startsWith('tracking') && !v.startsWith('payment'))).map((variable) => (
+                  {variables.filter(v => v.startsWith('site') || v.startsWith('store') || v.startsWith('shop') || v.startsWith('current') || v.startsWith('my_account') || v.startsWith('support') || v.startsWith('review') || (v.includes('_url') && !v.startsWith('order') && !v.startsWith('tracking') && !v.startsWith('payment'))).map((variable) => (
                     <button
                       key={variable}
                       type="button"
@@ -500,13 +500,14 @@ export function RichTextEditor({
 
               <div className="space-y-2">
                 <Label htmlFor="btn-style">{__('Button Style')}</Label>
-                <Select value={buttonStyle} onValueChange={(value: 'solid' | 'outline') => setButtonStyle(value)}>
+                <Select value={buttonStyle} onValueChange={(value: 'solid' | 'outline' | 'link') => setButtonStyle(value)}>
                   <SelectTrigger>
                     <SelectValue />
                   </SelectTrigger>
                   <SelectContent>
                     <SelectItem value="solid">{__('Solid (Primary)')}</SelectItem>
                     <SelectItem value="outline">{__('Outline (Secondary)')}</SelectItem>
+                    <SelectItem value="link">{__('Plain Link')}</SelectItem>
                   </SelectContent>
                 </Select>
               </div>

admin-spa/src/components/ui/searchable-select.tsx

@@ -21,7 +21,7 @@ export interface Option {
   /** What to render in the button/list. Can be a string or React node. */
   label: React.ReactNode;
   /** Optional text used for filtering. Falls back to string label or value. */
-  searchText?: string;
+  triggerLabel?: React.ReactNode;
 }
 
 interface Props {
@@ -55,7 +55,7 @@ export function SearchableSelect({
   React.useEffect(() => { if (disabled && open) setOpen(false); }, [disabled, open]);
 
   return (
-    <Popover open={disabled ? false : open} onOpenChange={(o)=> !disabled && setOpen(o)}>
+    <Popover open={disabled ? false : open} onOpenChange={(o) => !disabled && setOpen(o)}>
       <PopoverTrigger asChild>
         <Button
           variant="outline"
@@ -65,7 +65,7 @@ export function SearchableSelect({
           aria-disabled={disabled}
           tabIndex={disabled ? -1 : 0}
         >
-          {selected ? selected.label : placeholder}
+          {selected ? (selected.triggerLabel ?? selected.label) : placeholder}
           <ChevronsUpDown className="opacity-50 h-4 w-4 shrink-0" />
         </Button>
       </PopoverTrigger>

admin-spa/src/components/ui/select.tsx

@@ -89,7 +89,7 @@ const SelectContent = React.forwardRef<
       <SelectPrimitive.Content
         ref={ref}
         className={cn(
-          "relative z-50 max-h-[--radix-select-content-available-height] min-w-[8rem] overflow-y-auto overflow-x-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-select-content-transform-origin]",
+          "relative z-[9999] max-h-[--radix-select-content-available-height] min-w-[8rem] overflow-y-auto overflow-x-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-select-content-transform-origin]",
           position === "popper" &&
           "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
           className

admin-spa/src/components/ui/tiptap-button-extension.ts

@@ -7,7 +7,7 @@ export interface ButtonOptions {
 declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     button: {
-      setButton: (options: { text: string; href: string; style?: 'solid' | 'outline' }) => ReturnType;
+      setButton: (options: { text: string; href: string; style?: 'solid' | 'outline' | 'link' }) => ReturnType;
     };
   }
 }
@@ -39,6 +39,7 @@ export const ButtonExtension = Node.create<ButtonOptions>({
     return [
       {
         tag: 'a[data-button]',
+        priority: 100, // Higher priority than Link extension (default 50)
         getAttrs: (node: HTMLElement) => ({
           text: node.getAttribute('data-text') || node.textContent || 'Click Here',
           href: node.getAttribute('data-href') || node.getAttribute('href') || '#',
@@ -47,6 +48,7 @@ export const ButtonExtension = Node.create<ButtonOptions>({
       },
       {
         tag: 'a.button',
+        priority: 100,
         getAttrs: (node: HTMLElement) => ({
           text: node.textContent || 'Click Here',
           href: node.getAttribute('href') || '#',
@@ -55,6 +57,7 @@ export const ButtonExtension = Node.create<ButtonOptions>({
       },
       {
         tag: 'a.button-outline',
+        priority: 100,
         getAttrs: (node: HTMLElement) => ({
           text: node.textContent || 'Click Here',
           href: node.getAttribute('href') || '#',
@@ -67,20 +70,27 @@ export const ButtonExtension = Node.create<ButtonOptions>({
   renderHTML({ HTMLAttributes }) {
     const { text, href, style } = HTMLAttributes;
 
-    // Simple link styling - no fancy button appearance in editor
-    // The actual button styling happens in email rendering (EmailRenderer.php)
-    // In editor, just show as a styled link (differentiable from regular links)
+    // Different styling based on button style
+    let inlineStyle: string;
+    if (style === 'link') {
+      // Plain link - just underlined text, no button-like appearance
+      inlineStyle = 'color: #7f54b3; text-decoration: underline; cursor: pointer;';
+    } else {
+      // Solid/Outline buttons - show as styled link with background hint
+      inlineStyle = 'color: #7f54b3; text-decoration: underline; cursor: pointer; font-weight: 600; background: rgba(127,84,179,0.1); padding: 2px 6px; border-radius: 3px;';
+    }
+
     return [
       'a',
       mergeAttributes(this.options.HTMLAttributes, {
         href,
-        class: 'button-node',
-        style: 'color: #7f54b3; text-decoration: underline; cursor: pointer; font-weight: 600; background: rgba(127,84,179,0.1); padding: 2px 6px; border-radius: 3px;',
+        class: style === 'link' ? 'link-node' : 'button-node',
+        style: inlineStyle,
         'data-button': '',
         'data-text': text,
         'data-href': href,
         'data-style': style,
-        title: `Button: ${text} → ${href}`,
+        title: style === 'link' ? `Link: ${text}` : `Button: ${text} → ${href}`,
       }),
       text,
     ];

admin-spa/src/config/docRoutes.ts

@@ -0,0 +1,58 @@
+/**
+ * docRoutes.ts
+ * 
+ * Maps Admin SPA routes to external documentation URLs.
+ * Used by the DocLink component to provide contextual help.
+ */
+export const docRoutes: Record<string, string> = {
+    // Marketing Suite
+    // '/marketing': 'https://docs.woonoow.com/docs/marketing', // No general marketing doc yet
+    '/marketing/coupons': 'https://docs.woonoow.com/docs/marketing/coupons',
+    '/marketing/newsletter': 'https://docs.woonoow.com/docs/marketing/newsletter',
+    '/marketing/wishlist': 'https://docs.woonoow.com/docs/marketing/wishlist',
+
+    // Settings - Modules
+    '/settings/modules/wishlist': 'https://docs.woonoow.com/docs/marketing/wishlist',
+    '/settings/modules/newsletter': 'https://docs.woonoow.com/docs/marketing/newsletter',
+
+    // Builder
+    '/appearance/header': 'https://docs.woonoow.com/docs/builder/header-footer#header',
+    '/appearance/footer': 'https://docs.woonoow.com/docs/builder/header-footer#footer',
+
+    // Store Management
+    '/products': 'https://docs.woonoow.com/docs/store/products',
+    '/orders': 'https://docs.woonoow.com/docs/store/orders',
+    '/customers': 'https://docs.woonoow.com/docs/store/customers',
+
+    // Configuration
+    '/settings': 'https://docs.woonoow.com/docs/configuration/general',
+    '/settings/store': 'https://docs.woonoow.com/docs/configuration/general',
+    '/settings/payments': 'https://docs.woonoow.com/docs/configuration/payment-shipping',
+    '/settings/shipping': 'https://docs.woonoow.com/docs/configuration/payment-shipping',
+    '/settings/tax': 'https://docs.woonoow.com/docs/configuration/general', // Fallback
+    '/settings/customers': 'https://docs.woonoow.com/docs/store/customers',
+    '/settings/security': 'https://docs.woonoow.com/docs/configuration/security',
+    '/settings/notifications': 'https://docs.woonoow.com/docs/configuration/email',
+    '/settings/modules': 'https://docs.woonoow.com/docs/configuration/modules',
+    '/appearance/themes': 'https://docs.woonoow.com/docs/configuration/appearance',
+};
+
+/**
+ * Helper to get doc URL for a specific path
+ * 
+ * Can be enhanced with regex matching if needed
+ */
+export const getDocUrl = (path: string): string | null => {
+    // 1. Direct match
+    if (docRoutes[path]) return docRoutes[path];
+
+    // 2. Partial match (longest match first)
+    const sortedKeys = Object.keys(docRoutes).sort((a, b) => b.length - a.length);
+    for (const key of sortedKeys) {
+        if (path.startsWith(key)) {
+            return docRoutes[key];
+        }
+    }
+
+    return null;
+};

admin-spa/src/contexts/AppContext.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useContext, ReactNode } from 'react';
+import React, { createContext, useContext, ReactNode, useEffect } from 'react';
 
 interface AppContextType {
   isStandalone: boolean;
@@ -16,6 +16,35 @@ export function AppProvider({
   isStandalone: boolean;
   exitFullscreen?: () => void;
 }) {
+  useEffect(() => {
+    // Fetch and apply appearance settings (colors)
+    const loadAppearance = async () => {
+      try {
+        const restUrl = (window as any).WNW_CONFIG?.restUrl || '';
+        const response = await fetch(`${restUrl}/appearance/settings`);
+        if (response.ok) {
+          const result = await response.json();
+          // API returns { success: true, data: { general: { colors: {...} } } }
+          const colors = result.data?.general?.colors;
+          if (colors) {
+            const root = document.documentElement;
+            // Inject all color settings as CSS variables
+            if (colors.primary) root.style.setProperty('--wn-primary', colors.primary);
+            if (colors.secondary) root.style.setProperty('--wn-secondary', colors.secondary);
+            if (colors.accent) root.style.setProperty('--wn-accent', colors.accent);
+            if (colors.text) root.style.setProperty('--wn-text', colors.text);
+            if (colors.background) root.style.setProperty('--wn-background', colors.background);
+            if (colors.gradientStart) root.style.setProperty('--wn-gradient-start', colors.gradientStart);
+            if (colors.gradientEnd) root.style.setProperty('--wn-gradient-end', colors.gradientEnd);
+          }
+        }
+      } catch (e) {
+        console.error('Failed to load appearance settings', e);
+      }
+    };
+    loadAppearance();
+  }, []);
+
   return (
     <AppContext.Provider value={{ isStandalone, exitFullscreen }}>
       {children}

admin-spa/src/hooks/useActiveSection.ts

@@ -1,8 +1,23 @@
 import { useLocation } from 'react-router-dom';
-import { navTree, MainNode, NAV_TREE_VERSION } from '../nav/tree';
+import { useEffect, useState } from 'react';
+import { navTree as initialNavTree, MainNode } from '../nav/tree';
+
+function getCurrentNavTree(): MainNode[] {
+  const tree = window.WNW_NAV_TREE;
+  return Array.isArray(tree) && tree.length > 0
+    ? (tree as MainNode[])
+    : initialNavTree;
+}
 
 export function useActiveSection(): { main: MainNode; all: MainNode[] } {
   const { pathname } = useLocation();
+  const [navTree, setNavTree] = useState<MainNode[]>(getCurrentNavTree);
+
+  useEffect(() => {
+    const handleNavUpdate = () => setNavTree(getCurrentNavTree());
+    window.addEventListener('woonoow:navigation-updated', handleNavUpdate);
+    return () => window.removeEventListener('woonoow:navigation-updated', handleNavUpdate);
+  }, []);
 
   function pick(): MainNode {
     // Special case: /settings should match settings section
@@ -32,8 +47,5 @@ export function useActiveSection(): { main: MainNode; all: MainNode[] } {
   const main = pick();
   const children = Array.isArray(main.children) ? main.children : [];
 
-  // Debug: ensure we are using the latest tree module (driven by PHP-localized window.wnw.isDev)
-  const isDev = Boolean((window as any).wnw?.isDev);
-
   return { main: { ...main, children }, all: navTree } as const;
 }

admin-spa/src/hooks/useFABConfig.tsx

@@ -21,7 +21,7 @@ export function useFABConfig(page: 'orders' | 'products' | 'customers' | 'coupon
   const handleCouponsClick = useCallback(() => navigate('/coupons/new'), [navigate]);
   const handleDashboardClick = useCallback(() => {
     // TODO: Implement speed dial menu
-    console.log('Quick actions menu');
+    // TODO: Implement speed dial menu for quick actions
   }, []);
 
   useEffect(() => {

admin-spa/src/hooks/useFullscreen.ts

@@ -0,0 +1,45 @@
+import { useState, useEffect } from 'react';
+
+export function useFullscreen() {
+  const [on, setOn] = useState<boolean>(() => {
+    try { return localStorage.getItem('wnwFullscreen') === '1'; } catch { return false; }
+  });
+
+  useEffect(() => {
+    const id = 'wnw-fullscreen-style';
+    let style = document.getElementById(id);
+    if (!style) {
+      style = document.createElement('style');
+      style.id = id;
+      style.textContent = `
+        /* Hide WP admin chrome when fullscreen */
+        .wnw-fullscreen #wpadminbar,
+        .wnw-fullscreen #adminmenumain,
+        .wnw-fullscreen #screen-meta,
+        .wnw-fullscreen #screen-meta-links,
+        .wnw-fullscreen #wpfooter { display:none !important; }
+        .wnw-fullscreen #wpcontent { margin-left:0 !important; }
+        .wnw-fullscreen #wpbody-content { padding-bottom:0 !important; }
+        .wnw-fullscreen html, .wnw-fullscreen body { height: 100%; overflow: hidden; }
+        .wnw-fullscreen .woonoow-fullscreen-root {
+          position: fixed;
+          inset: 0;
+          z-index: 999;
+          background: var(--background, #fff);
+          height: 100dvh; /* ensure full viewport height on mobile/desktop */
+          overflow: hidden; /* prevent double scrollbars; inner <main> handles scrolling */
+          overscroll-behavior: contain;
+          display: flex;
+          flex-direction: column;
+          contain: layout paint size; /* prevent WP wrappers from affecting layout */
+        }
+      `;
+      document.head.appendChild(style);
+    }
+    document.body.classList.toggle('wnw-fullscreen', on);
+    try { localStorage.setItem('wnwFullscreen', on ? '1' : '0'); } catch { /* ignore localStorage errors */ }
+    return () => { /* do not remove style to avoid flicker between reloads */ };
+  }, [on]);
+
+  return { on, setOn } as const;
+}

admin-spa/src/hooks/useIsDesktop.ts

@@ -0,0 +1,17 @@
+import { useState, useEffect } from 'react';
+
+export function useIsDesktop(minWidth = 1024) { // lg breakpoint
+  const [isDesktop, setIsDesktop] = useState<boolean>(() => {
+    if (typeof window === 'undefined') return false;
+    return window.matchMedia(`(min-width: ${minWidth}px)`).matches;
+  });
+
+  useEffect(() => {
+    const mq = window.matchMedia(`(min-width: ${minWidth}px)`);
+    const onChange = () => setIsDesktop(mq.matches);
+    try { mq.addEventListener('change', onChange); } catch { mq.addListener(onChange); }
+    return () => { try { mq.removeEventListener('change', onChange); } catch { mq.removeListener(onChange); } };
+  }, [minWidth]);
+
+  return isDesktop;
+}

admin-spa/src/hooks/useShortcuts.tsx

@@ -47,6 +47,13 @@ export function useShortcuts({ toggleFullscreen }: { toggleFullscreen?: () => vo
         return;
       }
 
+      // Global Save: Ctrl/Cmd + S
+      if (mod && key === "s") {
+        e.preventDefault();
+        window.dispatchEvent(new CustomEvent('woonoow:shortcut:save'));
+        return;
+      }
+
       // Fullscreen toggle: Ctrl/Cmd + Shift + F
       if (mod && e.shiftKey && key === "f") {
         e.preventDefault();

admin-spa/src/hooks/useUnsavedChanges.ts

@@ -0,0 +1,52 @@
+import { useEffect, useState, useCallback } from 'react';
+import { useBlocker } from 'react-router-dom';
+
+export function useUnsavedChanges(isDirty: boolean) {
+  const [showPrompt, setShowPrompt] = useState(false);
+  
+  // React Router v6 blocker
+  const blocker = useBlocker(
+    ({ currentLocation, nextLocation }) =>
+      isDirty && currentLocation.pathname !== nextLocation.pathname
+  );
+
+  // Handle browser back/refresh
+  useEffect(() => {
+    const handleBeforeUnload = (e: BeforeUnloadEvent) => {
+      if (isDirty) {
+        e.preventDefault();
+        e.returnValue = '';
+      }
+    };
+
+    window.addEventListener('beforeunload', handleBeforeUnload);
+    return () => window.removeEventListener('beforeunload', handleBeforeUnload);
+  }, [isDirty]);
+
+  // Sync blocker state with our prompt state
+  useEffect(() => {
+    if (blocker.state === 'blocked') {
+      setShowPrompt(true);
+    }
+  }, [blocker.state]);
+
+  const confirmNavigation = useCallback(() => {
+    if (blocker.state === 'blocked') {
+      blocker.proceed();
+    }
+    setShowPrompt(false);
+  }, [blocker]);
+
+  const cancelNavigation = useCallback(() => {
+    if (blocker.state === 'blocked') {
+      blocker.reset();
+    }
+    setShowPrompt(false);
+  }, [blocker]);
+
+  return {
+    showPrompt,
+    confirmNavigation,
+    cancelNavigation
+  };
+}

admin-spa/src/index.css

@@ -1,6 +1,7 @@
 /* Import design tokens for UI sizing and control defaults */
 @import './components/ui/tokens.css';
 
+/* stylelint-disable at-rule-no-unknown */
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
@@ -34,6 +35,7 @@
     --chart-5: 27 87% 67%;
     --radius: 0.5rem;
   }
+
   .dark {
     --background: 222.2 84% 4.9%;
     --foreground: 210 40% 98%;
@@ -63,17 +65,33 @@
 }
 
 @layer base {
-  * { @apply border-border; }
-  body { @apply bg-background text-foreground; }
-  h1, h2, h3, h4, h5, h6 { @apply text-foreground; }
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    @apply text-foreground;
+  }
 
   /* Override WordPress common.css focus/active styles */
+  /* Override WordPress common.css focus/active styles */
+  /* Reverting this override as it causes issues with our custom button styles
   a:focus,
   a:active {
     outline: none !important;
     box-shadow: none !important;
     color: inherit !important;
   }
+  */
 }
 
 /* ============================================
@@ -126,11 +144,14 @@
 
 /* Page defaults for print */
 @page {
-  size: auto;              /* let the browser choose */
-  margin: 12mm;            /* comfortable default */
+  size: auto;
+  /* let the browser choose */
+  margin: 12mm;
+  /* comfortable default */
 }
 
 @media print {
+
   /* Hide WordPress admin chrome */
   #adminmenuback,
   #adminmenuwrap,
@@ -139,44 +160,170 @@
   #wpfooter,
   #screen-meta,
   .notice,
-  .update-nag { display: none !important; }
+  .update-nag {
+    display: none !important;
+  }
+
+  /* Hide WooNooW app shell - all nav, sidebar, header, submenu elements */
+  #woonoow-admin-app header,
+  #woonoow-admin-app nav,
+  #woonoow-admin-app aside,
+  #woonoow-admin-app [data-submenubar],
+  #woonoow-admin-app [data-bottomnav],
+  .woonoow-app-header,
+  .woonoow-topnav,
+  .woonoow-bottom-nav,
+  .woonoow-submenu,
+  .no-print {
+    display: none !important;
+  }
 
   /* Reset layout to full-bleed for our app */
-  html, body, #wpwrap, #wpcontent { background: #fff !important; margin: 0 !important; padding: 0 !important; }
-  #woonoow-admin-app, #woonoow-admin-app > div { margin: 0 !important; padding: 0 !important; max-width: 100% !important; }
+  html,
+  body,
+  #wpwrap,
+  #wpcontent,
+  #woonoow-admin-app,
+  #woonoow-admin-app>div,
+  .woonoow-app {
+    background: #fff !important;
+    margin: 0 !important;
+    padding: 0 !important;
+    max-width: none !important;
+    width: 100% !important;
+    min-height: auto !important;
+    overflow: visible !important;
+  }
 
-  /* Hide elements flagged as no-print, reveal print-only */
-  .no-print { display: none !important; }
-  .print-only { display: block !important; }
+  /* Ensure print content is visible and takes full page */
+  .print-a4 {
+    position: absolute !important;
+    top: 0 !important;
+    left: 0 !important;
+    width: 100% !important;
+    min-height: auto !important;
+    height: auto !important;
+    padding: 15mm !important;
+    margin: 0 !important;
+    box-shadow: none !important;
+    background: white !important;
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+
+  .print-a4 * {
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+
+  /* Ensure backgrounds print */
+  .print-a4 .bg-gray-50 {
+    background-color: #f9fafb !important;
+  }
+
+  .print-a4 .bg-gray-900 {
+    background-color: #111827 !important;
+  }
+
+  .print-a4 .text-white {
+    color: white !important;
+  }
+
+  /* Hide outer container styling */
+  .min-h-screen {
+    min-height: auto !important;
+    background: white !important;
+    padding: 0 !important;
+  }
+
+  .print-only {
+    display: block !important;
+  }
 
   /* Improve table row density on paper */
-  .print-tight tr > * { padding-top: 6px !important; padding-bottom: 6px !important; }
+  .print-tight tr>* {
+    padding-top: 6px !important;
+    padding-bottom: 6px !important;
+  }
 }
 
 /* By default, label-only content stays hidden unless in print or label mode */
-.print-only { display: none; }
+.print-only {
+  display: none;
+}
 
 /* Label mode toggled by router (?mode=label) */
-.woonoow-label-mode .print-only { display: block; }
+.woonoow-label-mode .print-only {
+  display: block;
+}
+
 .woonoow-label-mode .no-print-label,
 .woonoow-label-mode .wp-header-end,
-.woonoow-label-mode .wrap { display: none !important; }
+.woonoow-label-mode .wrap {
+  display: none !important;
+}
+
+/* Optional page presets (opt-in by adding the class to a wrapper before printing)
+   These classes are used dynamically and styled via @media print rules below */
 
-/* Optional page presets (opt-in by adding the class to a wrapper before printing) */
-.print-a4 { }
-.print-letter { }
-.print-4x6 { }
 @media print {
-  .print-a4 { }
-  .print-letter { }
+
+  /* A4 Invoice layout */
+  @page {
+    size: A4;
+    margin: 0;
+  }
+
+  .print-a4 {
+    width: 210mm !important;
+    min-height: 297mm !important;
+    padding: 20mm !important;
+    margin: 0 auto !important;
+    box-sizing: border-box !important;
+    background: white !important;
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+
+  .print-a4 * {
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+
+  /* Ensure backgrounds print */
+  .print-a4 .bg-gray-50 {
+    background-color: #f9fafb !important;
+  }
+
+  .print-a4 .bg-gray-900 {
+    background-color: #111827 !important;
+  }
+
+  .print-a4 .text-white {
+    color: white !important;
+  }
+
+  /* Letter format - extend as needed */
+
   /* Thermal label (4x6in) with minimal margins */
-  .print-4x6 { width: 6in; }
-  .print-4x6 * { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  .print-4x6 {
+    width: 6in;
+  }
+
+  .print-4x6 * {
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
 }
 
 /* --- WooNooW: Popper menus & fullscreen fixes --- */
-[data-radix-popper-content-wrapper] { z-index: 2147483647 !important; }
-body.woonoow-fullscreen .woonoow-app { overflow: visible; }
+[data-radix-popper-content-wrapper] {
+  z-index: 2147483647 !important;
+}
+
+body.woonoow-fullscreen .woonoow-app {
+  overflow: visible;
+}
 
 /* --- WooCommerce Admin Notices --- */
 .woocommerce-message,

admin-spa/src/lib/api.ts

@@ -2,7 +2,7 @@ export const api = {
   root: () => (window.WNW_API?.root?.replace(/\/$/, '') || ''),
   nonce: () => (window.WNW_API?.nonce || ''),
 
-  async wpFetch(path: string, options: RequestInit = {}) {
+  async wpFetch<T = any>(path: string, options: RequestInit = {}): Promise<T> {
     const url = /^https?:\/\//.test(path) ? path : api.root() + path;
     const headers = new Headers(options.headers || {});
     if (!headers.has('X-WP-Nonce') && api.nonce()) headers.set('X-WP-Nonce', api.nonce());
@@ -33,13 +33,13 @@ export const api = {
     }
 
     try {
-      return await res.json();
+      return await res.json() as T;
     } catch {
-      return await res.text();
+      return await res.text() as unknown as T;
     }
   },
 
-  async get(path: string, params?: Record<string, any>) {
+  async get<T = any>(path: string, params?: Record<string, any>): Promise<T> {
     const usp = new URLSearchParams();
     if (params) {
       for (const [k, v] of Object.entries(params)) {
@@ -48,71 +48,38 @@ export const api = {
       }
     }
     const qs = usp.toString();
-    return api.wpFetch(path + (qs ? `?${qs}` : ''));
+    return api.wpFetch<T>(path + (qs ? `?${qs}` : ''));
   },
 
-  async post(path: string, body?: any) {
-    return api.wpFetch(path, {
+  async post<T = any>(path: string, body?: any): Promise<T> {
+    return api.wpFetch<T>(path, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: body != null ? JSON.stringify(body) : undefined,
     });
   },
 
-  async put(path: string, body?: any) {
-    return api.wpFetch(path, {
+  async put<T = any>(path: string, body?: any): Promise<T> {
+    return api.wpFetch<T>(path, {
       method: 'PUT',
       headers: { 'Content-Type': 'application/json' },
       body: body != null ? JSON.stringify(body) : undefined,
     });
   },
 
-  async del(path: string) {
-    return api.wpFetch(path, { method: 'DELETE' });
+  async del<T = any>(path: string): Promise<T> {
+    return api.wpFetch<T>(path, { method: 'DELETE' });
   },
   
 };
 
-export type CreateOrderPayload = {
-    items: { product_id: number; qty: number }[];
-    billing?: Record<string, any>;
-    shipping?: Record<string, any>;
-    status?: string;
-    payment_method?: string;
-};
-
-export const OrdersApi = {
-    list: (params?: Record<string, any>) => api.get('/orders', params),
-    get: (id: number) => api.get(`/orders/${id}`),
-    create: (payload: CreateOrderPayload) => api.post('/orders', payload),
-    update: (id: number, payload: any) => api.wpFetch(`/orders/${id}`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload),
-    }),
-    payments: async () => api.get('/payments'),
-    shippings: async () => api.get('/shippings'),
-    countries: () => api.get('/countries'),
-};
-
-export const ProductsApi = {
-    search: (search: string, limit = 10) => api.get('/products/search', { search, limit }),
-    list: (params?: { page?: number; per_page?: number }) => api.get('/products', { params }),
-    categories: () => api.get('/products/categories'),
-};
-
-export const CustomersApi = {
-    search: (search: string) => api.get('/customers/search', { search }),
-    searchByEmail: (email: string) => api.get('/customers/search', { email }),
-};
-
 export async function getMenus() {
   // Prefer REST; fall back to localized snapshot
   try {
-    const res = await fetch(`${(window as any).WNW_API}/menus`, { credentials: 'include' });
+    const res = await fetch(`${window.WNW_API}/menus`, { credentials: 'include' });
     if (!res.ok) throw new Error('menus fetch failed');
     return (await res.json()).items || [];
   } catch {
-    return ((window as any).WNW_WC_MENUS?.items) || [];
+    return (window.WNW_WC_MENUS?.items) || [];
   }
 }

admin-spa/src/lib/api/client.ts

@@ -0,0 +1,2 @@
+import { api } from '../api';
+export const apiClient = api;

admin-spa/src/lib/api/coupons.ts

@@ -62,7 +62,7 @@ export const CouponsApi = {
     search?: string;
     discount_type?: string;
   }): Promise<CouponListResponse> => {
-    return api.get('/coupons', { params });
+    return api.get('/coupons', params);
   },
 
   /**

admin-spa/src/lib/api/customers.ts

@@ -69,7 +69,7 @@ export const CustomersApi = {
     search?: string;
     role?: string;
   }): Promise<CustomerListResponse> => {
-    return api.get('/customers', { params });
+    return api.get('/customers', params);
   },
 
   /**
@@ -104,6 +104,6 @@ export const CustomersApi = {
    * Search customers (for autocomplete)
    */
   search: async (query: string, limit?: number): Promise<CustomerSearchResult[]> => {
-    return api.get('/customers/search', { params: { q: query, limit } });
+    return api.get('/customers/search', { q: query, limit });
   },
 };

admin-spa/src/lib/api/orders.ts

@@ -0,0 +1,23 @@
+import { api } from '../api';
+
+export type CreateOrderPayload = {
+  items: { product_id: number; qty: number }[];
+  billing?: Record<string, any>;
+  shipping?: Record<string, any>;
+  status?: string;
+  payment_method?: string;
+};
+
+export const OrdersApi = {
+  list: (params?: Record<string, any>) => api.get('/orders', params),
+  get: (id: number) => api.get(`/orders/${id}`),
+  create: (payload: CreateOrderPayload) => api.post('/orders', payload),
+  update: (id: number, payload: any) => api.wpFetch(`/orders/${id}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+  }),
+  payments: async () => api.get('/payments'),
+  shippings: async () => api.get('/shippings'),
+  countries: () => api.get('/countries'),
+};

admin-spa/src/lib/api/products.ts

@@ -0,0 +1,12 @@
+import { api } from '../api';
+
+export const ProductsApi = {
+  search: (search: string, limit = 10) => api.get('/products/search', { search, limit }),
+  list: (params?: { page?: number; per_page?: number; search?: string; status?: string; category?: string; sort?: string }) => 
+    api.get('/products', params),
+  get: (id: number) => api.get(`/products/${id}`),
+  create: (data: any) => api.post('/products', data),
+  update: (id: number, data: any) => api.put(`/products/${id}`, data),
+  delete: (id: number, force: boolean = false) => api.del(`/products/${id}?force=${force ? 'true' : 'false'}`),
+  categories: () => api.get('/products/categories'),
+};