my-theme-v3.0.0.zip
├── manifest.json              // Theme metadata, templates, header/footer presets, starter content, chrome presets
├── templates/
│   ├── home.cw                // Home page template (directive-based)
│   ├── catalogue.default.cw   // Category/collection listing
│   ├── product.detail.cw      // Product detail page
│   ├── cart.cw                // Cart page
│   ├── checkout.cw            // Checkout page
│   ├── login.cw               // Customer login page
│   ├── register.cw            // Customer registration page
│   ├── maintenance.cw         // Maintenance/offline page
│   ├── blogs.default.cw       // Blog index
│   ├── post.default.cw        // Blog post
│   ├── page.default.cw        // Generic page
│   ├── page.not-found.cw      // 404 page
│   └── account/
│       ├── dashboard.cw       // Account dashboard
│       ├── orders.cw          // Order history
│       ├── order-detail.cw    // Single order view
│       ├── wishlist.cw        // Customer wishlist
│       ├── returns.cw         // Customer returns
│       ├── reviews.cw         // Customer reviews
│       ├── profile.cw         // Profile settings
│       ├── addresses.cw       // Saved addresses
│       ├── invoices.cw        // Customer invoices
│       └── documents.cw       // Customer documents
├── partials/
│   ├── header.cw              // Default header partial (fallback)
│   ├── footer.cw              // Default footer partial (fallback)
│   ├── header-light.cw        // Named header preset (@include via key)
│   ├── header-dark.cw         // Named header preset (@include via key)
│   ├── footer-dark.cw         // Named footer preset (@include via key)
│   └── footer-minimal.cw      // Named footer preset (@include via key)
├── sections/
│   ├── hero-banner.cw         // Reusable section
│   └── featured-products.cw   // Reusable section
├── assets/
│   ├── css/
│   │   ├── style.css
│   │   ├── responsive.css
│   │   └── bootstrap.min.css
│   ├── js/
│   │   └── main.js
│   └── images/
│       ├── logo.png
│       ├── thumbnail.png      // Theme thumbnail (for marketplace listing)
│       └── hero-bg.jpg
└── bundled-plugins/
    ├── whatsapp-chat-v2.0.0.zip  // Optional companion plugin
    └── reviews-summary-v2.0.0.zip

{
  "name":        "My Storefront Theme",
  "version":     "2.0.0",
  "description": "A modern, responsive storefront theme",
  "author":      "CoreWave",
  "formatVersion": 3,

  "thumbnail": "assets/images/thumbnail.png",

  "templates": {
    "catalogue.home":    { "label": "Home",      "icon": "home",    "format": "cw" },
    "catalogue.default": { "label": "Catalog",   "icon": "grid",   "format": "cw" },
    "product.detail":    { "label": "Product Detail", "icon": "box",    "format": "cw" },
    "cart.default":      { "label": "Cart",       "icon": "cart",   "format": "cw" },
    "checkout.default":  { "label": "Checkout",  "icon": "credit-card", "format": "cw" },
    "page.default":      { "label": "Page",       "icon": "file",   "format": "cw" },
    "page.not-found":   { "label": "404",        "icon": "alert-circle", "format": "cw" }
  },

  "headerPresets": [
    {
      "key":     "header-light",
      "label":   "Light Header",
      "partial": "partials/header-light.cw"
    },
    {
      "key":     "header-dark",
      "label":   "Dark Header",
      "partial": "partials/header-dark.cw"
    }
  ],

  "footerPresets": [
    {
      "key":     "footer-dark",
      "label":   "Dark Footer",
      "partial": "partials/footer-dark.cw"
    },
    {
      "key":     "footer-minimal",
      "label":   "Minimal Footer",
      "partial": "partials/footer-minimal.cw"
    }
  ],

  "defaultHeaderPresetKey": "header-light",
  "defaultFooterPresetKey": "footer-dark",

  "starterContent": {
    "catalogue.home": {
      "name":   "Home",
      "status": "Published"
    },

    "pages": [
      {
        "title":           "About Us",
        "handle":          "about-us",
        "templateKey":     "page.default",
        "headerPresetKey": "header-dark",
        "footerPresetKey": "footer-minimal",
        "showInNavigation": true,
        "sortOrder":       2,
        "publish":         true
      },
      {
        "title":           "Contact",
        "handle":          "contact",
        "templateKey":     "page.default",
        "headerPresetKey": "header-light",
        "showInNavigation": true,
        "sortOrder":       3,
        "publish":         true
      }
    ],

    "menus": {
      "main": [
        { "label": "Home", "url": "/", "sortOrder": 1 },
        { "label": "Shop", "url": "/shop", "sortOrder": 2 },
        { "label": "About", "pageHandle": "about-us", "sortOrder": 3 },
        { "label": "Blog", "url": "/blogs", "sortOrder": 4 },
        { "label": "Categories", "sortOrder": 5,
          "children": [
            { "label": "Clothing",  "pageHandle": "category-clothing",  "sortOrder": 1 },
            { "label": "Electronics", "pageHandle": "category-electronics", "sortOrder": 2 }
          ]
        }
      ],
      "footer": [
        { "label": "Contact", "pageHandle": "contact", "sortOrder": 1 }
      ],
      "secondary-nav": [
        { "label": "Support", "url": "/support", "sortOrder": 1 },
        { "label": "FAQ", "pageHandle": "faq", "sortOrder": 2 }
      ]
    }
  },

  "chromePresets": [
    {
      "name":      "Light",
      "thumbnail": "assets/images/light-preset.png",
      "header": { "partial": "partials/header-light.cw" },
      "footer": { "partial": "partials/footer-dark.cw" },
      "settings": {
        "backgroundColor": "#FFFFFF",
        "textColor":        "#1a202c",
        "primaryColor":    "#0833AB",
        "fontFamily":      "Nunito, sans-serif"
      }
    }
  ]
}

{
  "globalStyles": {
    "fontFamily":    "Nunito, sans-serif",
    "backgroundColor": "#FFFFFF",
    "textColor":      "#1e293b",
    "primaryColor":   "#0833AB",
    "accentColor":    "#FD1D1D",
    "borderRadius":   8,
    "presets": [
      {
        "key":   "header-light",
        "name":  "Light Header",
        "block": {
          "id": "sf-theme-header",
          "systemRole": "header"
        }
      },
      {
        "key":   "footer-dark",
        "name":  "Dark Footer",
        "block": {
          "id": "sf-theme-footer",
          "systemRole": "footer"
        }
      }
    ]
  },

  "customCss": "/* custom CSS injected at runtime */",

  "cssVars": {
    "--cw-font-family":    "Nunito, sans-serif",
    "--cw-primary":       "#0833AB",
    "--cw-accent":        "#FD1D1D",
    "--cw-background":    "#FFFFFF",
    "--cw-text-color":    "#1e293b",
    "--cw-border-radius":  "8px"
  }
}

{{--
  Template Name: Home Page
  Template Key: catalogue.home
--}}

@code
  __featured = cw_get_featured_products(8);
  __store = cw_get_store_info();
@endcode

@include('header')

{{-- Hero Section --}}
<section class="hero">
  <div class="container">
    <h1>@code echo __store.name; @endcode</h1>
    <p>@code echo __store.tagline; @endcode</p>
    <a href="@link('/shop')" class="btn btn--primary">Shop Now</a>
  </div>
</section>

{{-- Featured Products --}}
@if(__featured)
<section class="products">
  <div class="container">
    <h2>Featured Products</h2>
    <div class="product-grid">
      @each('product-card', __featured, 'product')
    </div>
  </div>
</section>
@endif

@include('footer')

{{-- This comment will not appear in the rendered HTML --}}

<!DOCTYPE html>
<html>
<head>
  @yield('head')
</head>
<body>
  @include('header')
  <main>
    @yield('content')
  </main>
  @include('footer')
  @stack('footer-scripts')
</body>
</html>

@extends('layouts/main')

@section('head')
  <title>@code echo __page.title; @endcode</title>
  @css('assets/css/page.css')
@endsection

@section('content')
  <article>
    <h1>@code echo __page.title; @endcode</h1>
    @code echo __page.content; @endcode
  </article>
@endsection

@push('footer-scripts')
  <script src="@asset('assets/js/page.js')"></script>
@endpush

@code
  __products = cw_get_products(['category' => 'clothing', 'limit' => 12]);
  __store = cw_get_store_info();
  __cart_count = cw_get_cart_count();
  __is_logged_in = cw_user_logged_in();
@endcode

theme.zip
├── templates/
│   ├── catalogue.home.cw
│   └── product.detail.cw
├── sections/
│   ├── hero-banner.cw
│   └── featured-products.cw
└── partials/
    └── product-card.cw

{{-- sections/featured-products.cw --}}
<section class="featured-products">
  <header>
    <h2>{{ cw_default(__section_title, 'Featured Products') }}</h2>
  </header>

  @query(__products, ['type' => 'products', 'tag' => 'featured', 'limit' => 8, 'orderby' => 'price', 'order' => 'asc'])
    <div class="product-grid">
      @each('product-card', __products, 'product')
    </div>
  @else
    <p>No featured products are available yet.</p>
  @endquery
</section>

@extends('layouts/main')

@section('content')
  @include('hero-banner')

  @var(__section_title, 'Best sellers')
  @include('featured-products')
@endsection

@include('header')
@query(__products, ['type' => 'products', 'limit' => 8, 'orderby' => 'price'])
@hook('product.card.after', __product)
@filter(name: 'product.price_html', input: __html)
@var(__title, 'Featured Products')
@echo(__title)

@extends('layouts/main')

@section('title')Home@endsection

@section('content')
  <h1>{{ cw_get_store().name }}</h1>
@endsection

@query(__products, ['type' => 'products', 'limit' => 12])
  @each('product-card', __products, 'product')
@endquery

@code
  __store = cw_get_store();
  __featured = cw_get_featured_products(8);
  echo __store.name;
@endcode

@var(__cta, 'Shop now')
<a href="/products">@echo(__cta)</a>

@foreach(__products as __product)
  @if(__product.stockQuantity <= 0)
    @continue
  @endif

  @switch(__product.productType)
    @case('Digital')
      <span>Instant delivery</span>
      @break
    @default
      <span>Ships after checkout</span>
  @endswitch
@endforeach

@push('footer-scripts')
  <script src="@asset('assets/js/gallery.js')" defer></script>
@endpush

{{-- in layout --}}
@stack('footer-scripts')

@query(__products, [
  'type' => 'product',
  'category' => 'clothing',
  'limit' => 12,
  'order' => 'desc',
  'orderby' => 'price'
])
  @foreach(__products as __product)
    @include('product-card', ['product' => __product])
  @endforeach
@else
  <p>No products found.</p>
@endquery

@code
  __customer = cw_get_customer_profile().customer;
@endcode

@is_logged_in
  <div class="welcome-banner">
    <h3>Welcome back, { __customer.first_name } { __customer.last_name }!</h3>
    <a href="/account">My Account</a>
  </div>
@else
  <div class="login-prompt">
    <p>Sign in for personalised shopping.</p>
    <a href="/login" class="btn btn-primary">Sign In</a>
  </div>
@endis_logged_in

@if(cw_user_logged_in())
  <p>You are signed in.</p>
@else
  <p>Guest browsing.</p>
@endif

@query(__products, ['type' => 'products', 'limit' => 8, 'orderby' => 'price', 'order' => 'asc'])
@query(__categories, ['type' => 'categories', 'limit' => 20])
@query(__products_by_category, ['type' => 'products', 'category' => 'clothing', 'limit' => 12])
@query(__products_by_tag, ['type' => 'products', 'tag' => 'featured', 'limit' => 6])
@query(__products_by_ids, ['type' => 'products', 'ids' => '1,2,3,4,5'])

{{-- Single lookups (returns Tag collection) --}}
__product_tags = cw_get_product_tags(productId: __product.id);
__post_tags = cw_get_post_tags(postId: __post.id);
__tags = cw_get_tags(scope: 'products');
__tag = cw_get_tag(slug: 'featured');
__by_tag_products = cw_get_products_by_tag(tag: 'featured', limit: 10);
__by_tag_posts = cw_get_posts_by_tag(tag: 'news', limit: 10);

@query(__posts, ['type' => 'posts', 'limit' => 5, 'orderby' => 'published_at'])
@query(__posts_in_category, ['type' => 'posts', 'category' => 'news', 'limit' => 10])
@query(__blogs, ['type' => 'blogs'])
@query(__all_posts, ['type' => 'posts', 'limit' => 50])

@query(__discounts, ['type' => 'discounts', 'limit' => 10])

{{-- Single discount by code --}}
__discount = cw_get_discount(code: 'SAVE20');

{{-- Validate a discount code against a subtotal --}}
__validation = cw_validate_discount(code: 'SAVE20', subtotal: '150.00');
{{-- Returns: {"valid": true/false, "error": "...", "type": "...", "value": 20} --}}

@query(__tags, ['type' => 'tags', 'scope' => 'products', 'limit' => 20])
@query(__all_tags, ['type' => 'tags', 'scope' => 'both'])

{{-- Named tag functions --}}
__product_tags = cw_get_product_tags(productId: 42);
__post_tags = cw_get_post_tags(postId: 15);
__tags = cw_get_tags(scope: 'products');
__tag = cw_get_tag(slug: 'featured');
__tagged_products = cw_get_products_by_tag(tag: 'sale', limit: 10);
__tagged_posts = cw_get_posts_by_tag(tag: 'announcement', limit: 5);

__store = cw_get_store();
{{-- Returns store object with name, slug, logo, currency, contact info, brand colors --}}

cw_format_money(amount: '1500.00', currency: 'NGN');
{{-- Returns: "NGN 1,500.00" --}}

cw_format_date(date: '2024-01-15', format: 'M d, Y');
{{-- Returns: "Jan 15, 2024" --}}
{{-- Supported formats: M d, Y | Y-m-d | d/m/Y | F j, Y --}}

cw_slugify(input: 'Hello World');
{{-- Returns: "hello-world" --}}

cw_truncate(text: 'Long text here...', length: 100, ellipsis: '...');
{{-- Returns truncated string with ellipsis --}}

cw_default(value: '', default: 'No content');
{{-- Returns default if value is empty --}}

cw_echo('Any string');
{{-- Outputs the string directly --}}

cw_count(var: __products);
{{-- Returns the count of items in a collection --}}

{{-- Utility & conditional lookups --}}
cw_has_image(entity: __product);
{{-- Returns: "true" or "false" --}}

cw_get_store_name();
{{-- Returns: "My Store" (string) --}}

cw_get_store_currency_code();
{{-- Returns: "NGN" (string, from institution settings) --}}

cw_get_cart_count();
{{-- Returns: "3" (int as string, from session) --}}

cw_get_cart_applied_discounts();
{{-- Returns: JSON array of applied discount codes --}}

cw_user_logged_in();
{{-- Returns: "true" or "false" (checks session for customer_email) --}}

cw_get_related_products(productId: __product.id, limit: 4);
{{-- Returns: JSON array of related Product objects (shared categories) --}}

{{-- ── Shopper Currency Switcher Functions ── --}}
cw_set_currency(code: 'USD');
{{-- Sets the shopper's preferred currency in the session. Returns: {"success": true, "code": "USD"} --}}
{{-- Call this when a shopper selects a currency from your switcher UI --}}

cw_get_current_currency();
{{-- Returns: {"code": "USD", "symbol": "$", "name": "US Dollar", "is_base": false} --}}
{{-- Returns the shopper's preferred currency, or the store's base currency if none is set --}}

cw_get_available_currencies();
{{-- Returns: JSON array of all active currencies available to the shopper --}}
{{-- Each entry: {"code": "USD", "symbol": "$", "name": "US Dollar", "is_base": false} --}}

cw_convert_price(amount: 1500.00, to: 'USD');
{{-- Converts an amount from the store's base currency to the target currency --}}
{{-- Uses exchange rates configured in the CurrencyRate system (BuyRate/SellRate) --}}
{{-- Returns: {"original_amount": 1500.00, "converted_amount": 1.04, "from_currency": "NGN", "to_currency": "USD", "rate": 1440.50} --}}
{{-- If 'to' is omitted, converts to the shopper's preferred currency (or base currency) --}}

cw_get_checkout_breakdown(subtotal: 5000, countryCode: 'NG', regionCode: 'LA', cityName: 'Lagos', deliveryMethodName: 'Standard', weight: 2.5, couponCode: 'WELCOME10', customerEmail: 'customer@example.com');
{{-- Returns full checkout pricing breakdown: {"subtotal":5000,"discountTotal":500,"deliveryTotal":1000,"taxTotal":350,"processingFee":250,"processingFeeTax":18.75,"shippingFeeTax":75,"grandTotal":6193.75,"currencyCode":"NGN","deliveryMethodName":"Standard","couponError":null} --}}
{{-- Parameters: subtotal, countryCode, regionCode, cityName (optional), deliveryMethodName (optional), weight (optional), couponCode (optional), customerEmail (optional) --}}
{{-- V2: Delivery total is resolved through the active API shipping provider, not zone-based rules --}}
{{-- V3 (Fee Overhaul): Pricing breakdown now includes processingFee, processingFeeTax (7.5% regulatory charge on processing fee), and shippingFeeTax (7.5% regulatory charge on shipping fee). The grandTotal formula is: subtotal - discount + deliveryTotal + taxTotal + processingFee + processingFeeTax + shippingFeeTax. --}}

cw_get_shipping_price(subtotal: 5000, countryCode: 'NG', cityName: 'Lagos', weight: 2.5);
{{-- Returns API-calculated shipping price: {"shippingCost":1000,"currencyCode":"NGN","error":null} --}}
{{-- Parameters: subtotal, countryCode, cityName (optional), weight (optional, default: 0.5) --}}
{{-- Uses the active shipping provider configured in Storefront > Shipping Settings. --}}
{{-- Returns shippingCost = 0 and an error message if no provider is active or rate cannot be calculated. --}}

cw_get_order_tracking(orderNumber: 'ORD-001');
{{-- V2 — Returns tracking data for a given order: {"trackingNumber":"1Z999AA10123456784","status":"in_transit","estimatedDeliveryDate":"2026-05-10","deliveredAt":null,"events":[...],"error":null} --}}
{{-- Parameters: orderNumber (required) --}}
{{-- Each event: {"status":"picked_up","location":"Lagos, NG","description":"Package picked up","occurredAt":"2026-05-01T10:00:00Z"} --}}
{{-- Returns error if order not found or no tracking available. --}}

@if(__products && cw_count(var: __products) > 0)
  {{-- Has products --}}
@endif

@if(cw_get_store().name)
  {{-- Store exists --}}
@endif

@isset(__product)
  {{-- Product page context --}}
@endisset

{{-- Submit a product review --}}
@code
  __result = cw_submit_product_review(
    productId: __product.id,
    rating: 5,
    comment: 'Great product!'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Get paginated product reviews --}}
@code
  __reviews = cw_product_reviews(productId: __product.id, page: 1, limit: 5);
@endcode

@foreach(__reviews as __review)
  <div class="review">
    <div class="review__rating">
      @for(__i=0; __i<__review.rating; __i++)★ @endfor
      @for(__i=__review.rating; __i<5; __i++)☆ @endfor
    </div>
    <p class="review__comment">@code echo __review.comment; @endcode</p>
    <span class="review__author">— @code echo __review.author; @endcode</span>
    <span class="review__date">@code echo __review.date; @endcode</span>
  </div>
@endforeach

{{-- On a product detail page — show the current customer's review if they've written one --}}
@if(cw_user_logged_in())
  @code
    __my_review = cw_get_customer_product_review(productId: __product.id);
  @endcode

  @if(__my_review)
    <div class="your-review">
      <h4>Your Review</h4>
      <div class="review__rating">
        @for(__i=0; __i<__my_review.rating; __i++★ @endfor
        @for(__i=__my_review.rating; __i<5; __i++☆ @endfor
      </div>
      <p>@code echo __my_review.reviewText; @endcode</p>
      <small>Reviewed on @code echo __my_review.createdAt; @endcode</small>

      {{-- Update your review --}}
      @code
        __updated = cw_submit_product_review(
          productId: __product.id,
          rating: 4,
          comment: 'Updated review text'
        );
      @endcode
    </div>
  @else
    <div class="write-review">
      <h4>Write a Review</h4>
      @code
        __result = cw_submit_product_review(
          productId: __product.id,
          rating: 5,
          comment: 'Great product!'
        );
      @endcode
    </div>
  @endif
@else
  <p><a href="{{ cw_route('login') }}">Sign in</a> to review this product.</p>
@endif

{{-- Submit a blog post comment --}}
@code
  __result = cw_submit_post_comments(
    postId: __post.id,
    name: 'John',
    email: 'john@example.com',
    comment: 'Great article! Thanks for sharing.'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Get paginated blog post comments --}}
@code
  __comments = cw_post_comments(postId: __post.id, page: 1, limit: 20);
@endcode

@if(cw_count(var: __comments) > 0)
  <h3>Comments</h3>
  @foreach(__comments as __comment)
    <div class="comment">
      <img src="@code echo __comment.avatar; @endcode"
           alt="@code echo __comment.author; @endcode"
           class="comment__avatar">
      <div class="comment__body">
        <strong>@code echo __comment.author; @endcode</strong>
        <p>@code echo __comment.comment; @endcode</p>
        <span>@code echo __comment.date; @endcode</span>
      </div>
    </div>
  @endforeach
@endif

{{-- Subscribe to the newsletter (email required, name optional) --}}
@code
  __result = cw_subscribe_newsletter(email: 'customer@example.com');
  {{-- __result.success == true, __result.message == "Subscribed successfully" --}}
@endcode

{{-- Subscribe with optional name --}}
@code
  __result = cw_subscribe_newsletter(
    email: 'john@example.com',
    name: 'John Doe'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Display a simple newsletter subscription form --}}
<form method="post" action="#">
  <input type="hidden" name="csrf_token" value="{ cw_csrf_token() }">
  <div class="newsletter-form">
    <input type="email" name="email" placeholder="Your email address" required>
    <input type="text" name="name" placeholder="Your name (optional)">
    <button type="submit">Subscribe</button>
  </div>
</form>

{{-- On form submission, call cw_subscribe_newsletter --}}
@if(__form_submitted)
  @code
    __newsletter_result = cw_subscribe_newsletter(
      email: __form_email,
      name: __form_name
    );
  @endcode
  @if(__newsletter_result.success)
    <p class="success">Thank you for subscribing!</p>
  @else
    <p class="error">{ __newsletter_result.message }</p>
  @endif
@endif

{{-- Step 1: Login with email and password (optional OTP) --}}
@code
  __result = cw_login_user(
    email: 'customer@example.com',
    password: 'secure-password',
    redirect_url: '/account/orders',
    send_login_otp: true,      {{-- optional: send OTP code via email --}}
    otp_required: false         {{-- optional: require OTP verification --}}
  );
  {{-- Password mode returns: { "token": "jwt...", "customer": {...}, "summary": {...}, "redirectUrl": "/account/orders" } --}}
  {{-- OTP mode returns: { "otpSent": true, "otpToken": "challenge...", "token": null } --}}
  __session_token = __result.token;
@endcode

{{-- Step 2: If OTP was sent, verify it --}}
@code
  __session = cw_verify_login(challenge_token: __result.otpToken, code: '123456');
  {{-- Returns: { "token": "jwt...", "customer": {...}, "summary": {...}, "redirectUrl": "/account/orders" } --}}
  {{-- The session token is now stored and available for subsequent calls --}}
@endcode

{{-- Step 3: Access customer data --}}
@code
  __profile = cw_get_customer_profile();
  __orders = cw_get_customer_orders(page: 1, limit: 10);
  __wishlist = cw_get_customer_wishlist();
@endcode

{{-- Step 4: Logout --}}
@code
  __result = cw_logout_user();
  {{-- Clears the customer session --}}
@endcode

{{-- Example: Meta-refresh redirect after successful verification --}}
@code
  __session = cw_verify_login(
    challenge_token: __challenge_token,
    code: '123456',
    redirect_url: '/account/orders'
  );
@endcode

{{-- If verification was successful, output a redirect --}}
@if(__session.token)
  {!! cw_auth_redirect() !!}
  {{-- Generates: <meta http-equiv="refresh" content="0;url=/account/orders"> --}}
  {{-- Plus a JavaScript fallback: <script>location.href='/account/orders'</script> --}}
@else
  <p>Invalid code. Please try again.</p>
@endif

{{-- Register a new customer with password and optional email verification --}}
@code
  __result = cw_register_user(
    first_name: 'John',
    last_name: 'Doe',
    email: 'john@example.com',
    password: 'secure-password',
    phone: '+2348012345678',            {{-- optional --}}
    country_id: 1,                      {{-- optional --}}
    region_id: 1,                       {{-- optional --}}
    city_id: 1,                         {{-- optional --}}
    address: '123 Main Street',         {{-- optional --}}
    zip_code: '10001',                  {{-- optional --}}
    redirect_url: '/account',           {{-- optional: redirect after login --}}
    send_welcome_mail: true,            {{-- optional: send welcome email --}}
    send_mail_verification_mail: true,  {{-- optional: send verification email --}}
    mail_verification_required: true    {{-- optional: require email verification --}}
  );
  {{-- Returns: { "token": "jwt...", "customer": {...}, "summary": {...}, "redirectUrl": "/account" } --}}
  {{-- If mail_verification_required is true, token is null until verified --}}
  __session_token = __result.token;
@endcode

{{-- Verify email to complete registration --}}
@code
  __session = cw_verify_register(
    email: 'john@example.com',
    verification_token: 'token-from-email',
    redirect_url: '/account'
  );
  {{-- Customer is now registered, email verified, and logged in --}}
  {{-- Response includes redirectUrl if redirect_url was provided --}}
@endcode

{{-- Get customer profile with summary --}}
@code
  __profile = cw_get_customer_profile();
  {{-- Returns: { "customer": {...}, "summary": {...} } --}}
  __customer = __profile.customer;
  __summary = __profile.summary;
@endcode

<h1>Welcome, { __customer.first_name } { __customer.last_name }</h1>
<p>Email: { __customer.email }</p>
<p>Phone: { __customer.phone }</p>
<p>Total Orders: { __summary.total_orders }</p>
<p>Total Spend: { cw_format_money(__summary.total_spend, __summary.currency) }</p>

{{-- Get customer dashboard with aggregated data --}}
@code
  __dashboard = cw_get_customer_dashboard();
  {{-- Returns: { "summary": {...}, "wishlist": [...], "returns": [...], "reviews": [...], "spendChart": [...] } --}}
  __dash_summary = __dashboard.summary;
@endcode

{{-- Update customer profile --}}
@code
  __updated = cw_update_customer_profile(
    first_name: 'John',
    last_name: 'Updated',
    phone: '+2348098765432',
    zip_code: '10001',
    billing_address: '456 New Street, Lagos',
    shipping_address: '456 New Street, Lagos'
  );
@endcode

{{-- Display current profile in an editable form --}}
@code
  __profile = cw_get_customer_profile();
  __customer = __profile.customer;
@endcode

@is_logged_in
  <form class="profile-form" method="post" action="@link('/account/profile/update')">
    

      First Name
      
    

    

      Last Name
      
    

    

      Other Names
      
    

    <div class="form-group">
      <label>Phone Number</label>
      <input type="tel" name="phone" value="{ __customer.phone }">
    </div>

    <div class="form-group">
      <label>Billing Address</label>
      <textarea name="billing_address" rows="3">{ __customer.billing_address }</textarea>
    </div>

    <div class="form-group">
      <label>Shipping Address</label>
      <textarea name="shipping_address" rows="3">{ __customer.shipping_address }</textarea>
    </div>

    <button type="submit" class="btn btn--primary">Save Profile</button>
  </form>

  {{-- Or use the cw function directly in @code blocks --}}
  @code
    __updated = cw_update_customer_profile(
      first_name: 'John',
      last_name: 'Updated',
      phone: '+2348098765432',
      zip_code: '10001',
      billing_address: '456 New Street, Lagos',
      shipping_address: '456 New Street, Lagos'
    );
    {{-- __updated.success == true --}}
  @endcode

  {{-- Update profile with custom extra info fields --}}
  @code
    __updated = cw_update_customer_profile(
      first_name: 'John',
      last_name: 'Doe',
      phone: '+2348012345678',
      zip_code: '10001',
      extra_info: '[{"title": "Company", "value": "Acme Ltd"}, {"title": "Tax ID", "value": "TX12345"}]'
    );
    {{-- extra_info is a JSON array of {title, value} objects --}}
  @endcode

  {{-- Update profile picture using a Media Library asset ID --}}
  @code
    __updated = cw_update_customer_profile(
      profile_picture_asset_id: 42
    );
    {{-- __updated.customer.profile_picture_url will contain the resolved URL --}}
    {{-- Pass 0 or omit to leave unchanged, set to a valid Media Library asset ID to update --}}
  @endcode
@else
  <p>Please <a href="@link('/account/login')">log in</a> to edit your profile.</p>
@endis_logged_in

{{-- Update billing address only --}}
@code
  __result = cw_update_customer_address(
    type: 'billing',
    address: '123 Main Street, Ikeja, Lagos'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Update shipping address only --}}
@code
  __result = cw_update_customer_address(
    type: 'shipping',
    address: '456 Warehouse Road, Apapa, Lagos'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Update both addresses to the same value --}}
@code
  __result = cw_update_customer_address(
    type: 'both',
    address: '789 New Home Ave, Victoria Island, Lagos'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Or use the full profile function for combined updates --}}
@code
  __result = cw_update_customer_profile(
    zip_code: '10001',
    billing_address: '123 Main Street, Ikeja, Lagos',
    shipping_address: '456 Warehouse Road, Apapa, Lagos'
  );
  {{-- __result.success == true --}}
@endcode

{{-- Get paginated orders --}}
@code
  __result = cw_get_customer_orders(page: 1, limit: 10);
  __orders = __result.orders;       {{-- PagedResponse with items, totalCount, page, pageSize --}}
  __summary = __result.summary;     {{-- Customer summary object --}}
@endcode

@if(cw_count(var: __orders.items) > 0)
  <table class="orders-table">
    <thead>
      <tr><th>Order #</th><th>Date</th><th>Status</th><th>Total</th><th></th></tr>
    </thead>
    <tbody>
      @foreach(__orders.items as __order)
      <tr>
        <td>{ __order.reference }</td>
        <td>{ cw_format_date(__order.created_at) }</td>
        <td><span class="badge badge-{ __order.status }">{ __order.status }</span></td>
        <td>{ cw_format_money(__order.amount, __order.currency_code) }</td>
        <td><a href="?order={ __order.id }">View</a></td>
      </tr>
      @endforeach
    </tbody>
  </table>

  {{-- Pagination --}}
  <div class="pagination">
    @if(__orders.page > 1)
      <a href="?page={ __orders.page - 1 }">Previous</a>
    @endif
    <span>Page { __orders.page } of { ceil(__orders.totalCount / 10) }</span>
    @if(__orders.page * 10 < __orders.totalCount)
      <a href="?page={ __orders.page + 1 }">Next</a>
    @endif
  </div>
@else
  <p>No orders found.</p>
@endif

{{-- Get a single order by ID --}}
@code
  __order = cw_get_customer_order(order_id: 123);
  {{-- Returns a single Order object or null --}}
@endcode

{{-- Get paginated invoices (orders with generated invoices) --}}
@code
  __result = cw_get_customer_invoices(page: 1, limit: 10);
  __invoices = __result.orders;     {{-- or __result.items --}}
@endcode

@foreach(__invoices.items as __invoice)
  <div class="invoice-row">
    <span>{ __invoice.invoice_reference }</span>
    <span>{ cw_format_money(__invoice.amount, __invoice.currency_code) }</span>
    <span>{ cw_format_date(__invoice.created_at) }</span>
    @if(__invoice.invoice_html)
      <a href="?download_invoice={ __invoice.id }">Download</a>
    @endif
  </div>
@endforeach

{{-- Get paginated receipts (paid orders) --}}
@code
  __result = cw_get_customer_receipts(page: 1, limit: 10);
  __receipts = __result.orders;     {{-- or __result.items --}}
@endcode

@foreach(__receipts.items as __receipt)
  <div class="receipt-row">
    <span>{ __receipt.reference }</span>
    <span>{ cw_format_money(__receipt.amount, __receipt.currency_code) }</span>
    <span>{ cw_format_date(__receipt.paid_at) }</span>
  </div>
@endforeach

{{-- Get documents for a specific order --}}
@code
  __documents = cw_get_customer_documents(order_id: 123);
@endcode

{{-- Get documents across all orders --}}
@code
  __all_docs = cw_get_customer_documents();
@endcode

@foreach(__all_docs as __doc)
  <div class="document-row">
    <span>Order #{ __doc.order_reference }</span>
    <span>{ __doc.document_type }</span>
    <span>{ cw_format_date(__doc.created_at) }</span>
    @if(__doc.rendered_html)
      <a href="?view_doc={ __doc.document_id }">View</a>
    @endif
  </div>
@endforeach

{{-- Get wishlist items --}}
@code
  __wishlist = cw_get_customer_wishlist();
@endcode

@if(cw_count(var: __wishlist) > 0)
  <div class="wishlist-grid">
    @foreach(__wishlist as __item)
      <div class="wishlist-item">
        @if(__item.product_image)
          <img src="{ __item.product_image }" alt="{ __item.product_name }" />
        @endif
        <h3>{ __item.product_name }</h3>
        <p>{ cw_format_money(__item.product_price) }</p>
        <p>Added: { cw_format_date(__item.added_at) }</p>
        <button onclick="cw_add_to_cart({ __item.product_id })">Add to Cart</button>
        <button onclick="cw_remove_from_wishlist({ __item.product_id })">Remove</button>
      </div>
    @endforeach
  </div>
@else
  <p>Your wishlist is empty.</p>
@endif

{{-- Add a product to wishlist --}}
@code
  __result = cw_add_to_customer_wishlist(product_id: 42);
  {{-- __result.success == true --}}
@endcode

{{-- Remove a product from wishlist --}}
@code
  __result = cw_remove_from_customer_wishlist(product_id: 42);
  {{-- __result.success == true --}}
@endcode

{{-- Get paginated return requests --}}
@code
  __result = cw_get_customer_returns(page: 1, limit: 10);
  __returns = __result.items;       {{-- or __result.returns --}}
@endcode

@foreach(__returns as __return)
  <div class="return-row">
    <span>Order #{ __return.order_reference }</span>
    <span>{ __return.product_name }</span>
    <span>Reason: { __return.reason }</span>
    <span class="badge badge-{ __return.status }">{ __return.status }</span>
    <span>{ cw_format_date(__return.created_at) }</span>
  </div>
@endforeach

{{-- Create a return request --}}
@code
  __result = cw_create_customer_return(
    order_id: 123,
    reason: 'Product is damaged',
    product_id: 42      {{-- optional, for specific item returns --}}
  );
  {{-- __result.success == true --}}
@endcode

{{-- Cancel a return request --}}
@code
  __result = cw_cancel_return_request(
    return_id: 7
  );
  {{-- __result.success == true --}}
@endcode

{{-- Get paginated customer reviews --}}
@code
  __result = cw_get_customer_reviews(page: 1, limit: 10);
  __reviews = __result.items;       {{-- or __result.reviews --}}
@endcode

@foreach(__reviews as __review)
  <div class="review-item">
    <h4>{ __review.product_name }</h4>
    <div class="rating">
      @for(__i=0; __i<__review.rating; __i++)★ @endfor
      @for(__i=__review.rating; __i<5; __i++)☆ @endfor
    </div>
    <p>{ __review.review_text }</p>
    <span>{ cw_format_date(__review.created_at) }</span>
  </div>
@endforeach

{{-- String filters --}}
@code echo '1500.00' | money; @endcode       {{-- "NGN 1,500.00" --}}
@code echo '2024-01-15' | date; @endcode      {{-- "Jan 15, 2024" --}}
@code echo 'Hello World' | slugify; @endcode  {{-- "hello-world" --}}
@code echo __post.content | truncate; @endcode
@code echo __product.title | default('Untitled'); @endcode

{{-- Filters with arguments --}}
@code echo __store.price | money(currency: 'USD'); @endcode
@code echo '2024-01-15' | date(format: 'Y-m-d'); @endcode
@code echo __post.excerpt | truncate(length: 50, ellipsis: '[...]'); @endcode

{{-- Example: sending a welcome email during registration --}}
@code
  __result = cw_register_user(
    first_name: 'Jane',
    last_name: 'Doe',
    email: 'jane@example.com',
    password: 'secure-password',
    send_welcome_mail: true,
    send_mail_verification_mail: true,
    mail_verification_required: true
  );
  {{-- If mail_verification_required is true, token is null until verified --}}
  {{-- __result.emailVerificationRequired == true --}}
@endcode

{{-- Example: verifying email with token --}}
@code
  __result = cw_verify_register(token: 'abc123def456...');
  {{-- On success: { "verified": true, "message": "Email verified successfully.", "email": "jane@example.com" } --}}
  {{-- On failure: { "verified": false, "error": "Invalid or expired verification token." } --}}
@endcode

{{-- Example: login with OTP via email --}}
@code
  __result = cw_login_user(
    email: 'jane@example.com',
    password: 'secure-password',
    send_login_otp: true,
    otp_required: true
  );
  {{-- OTP mode returns: { "otpSent": true, "otpToken": "challenge...", "token": null } --}}
  {{-- Pass the otpToken to cw_verify_login with the code from email --}}
@endcode

{{-- Then in a separate step, verify the OTP code --}}
@code
  __session = cw_verify_login(
    challenge_token: __otpToken,
    code: '123456'
  );
  {{-- __session.token contains the JWT session --}}
@endcode

@code
  __route = cw_current_route();
  __product_id = cw_current_product_id();
  __product_slug = cw_current_product_slug();
  __category_slug = cw_current_category_slug();
  __blog_id = cw_current_blog_id();
  __blog_slug = cw_current_blog_slug();
  __post_id = cw_current_post_id();
  __post_slug = cw_current_post_slug();
@endcode

@if(__route.kind == 'product')
  <p>Rendering product {{ __product_slug }}</p>
@endif

{{-- templates/product.detail.cw --}}
@extends('layouts/main')

@section('content')
  @code
    __product = cw_get_product(slug: cw_current_product_slug());
  @endcode

  @isset(__product)
    <article class="product-detail">
      <img src="{{ __product.image }}" alt="{{ __product.title }}">
      <h1>{{ __product.title }}</h1>
      <p>{{ cw_format_money(amount: __product.price) }}</p>
      <div>{{ __product.description }}</div>

      @query(__related, ['type' => 'products', 'category' => __product.categories.0.slug, 'limit' => 4])
        @each('product-card', __related, 'product')
      @endquery
    </article>
  @else
    @include('not-found')
  @endisset
@endsection

{{-- templates/blog.default.cw --}}
@extends('layouts/main')

@section('content')
  <h1>{{ __blog.name }}</h1>

  @query(__posts, ['type' => 'posts', 'blog' => cw_current_blog_slug(), 'limit' => 12, 'orderby' => 'published_at', 'order' => 'desc'])
    @each('post-card', __posts, 'post')
  @else
    <p>No posts have been published in this blog yet.</p>
  @endquery
@endsection

{{-- templates/post.default.cw --}}
@extends('layouts/main')

@section('content')
  @code
    __post = cw_get_post(slug: cw_current_post_slug(), blog: cw_current_blog_slug());
  @endcode

  <article class="blog-post">
    @code
      __paths = cw_base_paths();
    @endcode

    <p><a href="{{ __paths.blog }}/{{ cw_current_blog_slug() }}">{{ __blog.name }}</a></p>
    <h1>{{ __post.title }}</h1>
    <time>{{ cw_format_date(date: __post.published_at, format: 'M d, Y') }}</time>
    <div class="post-content">{{ __post.content }}</div>
  </article>
@endsection

@query(__products, [
  'type' => 'products',
  'category' => 'clothing',
  'tag' => 'sale,featured',
  'brand' => 'CoreWave',
  'min_price' => 1000,
  'max_price' => 50000,
  'in_stock' => true,
  'on_sale' => true,
  'orderby' => 'price',
  'order' => 'asc',
  'limit' => 24
])
  @each('product-card', __products, 'product')
@endquery

@query(__categories, ['type' => 'categories', 'active' => true, 'parent_id' => 0, 'orderby' => 'display_order', 'order' => 'asc'])
  @foreach(__categories as __category)
    <a href="/category/{{ __category.slug }}">{{ __category.name }}</a>
  @endforeach
@endquery

@query(__blogs, ['type' => 'blogs', 'q' => 'news', 'orderby' => 'published_at', 'order' => 'desc'])
  @each('blog-card', __blogs, 'blog')
@endquery

@query(__posts, ['type' => 'posts', 'blog' => 'news', 'tag' => 'announcement', 'orderby' => 'published_at', 'order' => 'desc'])
  @each('post-card', __posts, 'post')
@endquery

{{--
  Template Part: Product Card
  Usage: @include('product-card', ['product' => __product])
--}}
<div class="product-card">
  {{-- Sale badge --}}
  @if(__product.on_sale)
    <span class="product-card__badge">Sale!</span>
  @endif

  <a href="{{ __product.url }}" class="product-card__image">
    @has_image(__product)
      @image(__product, 'medium')
    @else
      <div class="product-card__placeholder">No Image</div>
    @endis
  </a>

  <div class="product-card__info">
    <h3><a href="{{ __product.url }}">@code echo __product.title; @endcode</a></h3>

    {{-- Star rating --}}
    @if(__product.rating > 0)
    <div class="product-card__rating">
      @for(__i=0; __i<5; __i++)
        @if(__i < cw_count(var: __product.rating))
          <span class="star star--filled">★</span>
        @else
          <span class="star star--empty">☆</span>
        @endif
      @endfor
      <span class="rating-count">(@code echo __product.review_count; @endcode)</span>
    </div>
    @endif

    <div class="product-card__price">
      @if(__product.on_sale && __product.compare_price)
        <span class="price--compare">@code echo cw_format_money(amount: __product.compare_price); @endcode</span>
      @endif
      <span class="price--current">@code echo cw_format_money(amount: __product.price); @endcode</span>
    </div>
  </div>
</div>

{{--
  Template Name: Cart Page
  Template Key: cart.default
--}}

@include('header')

<div class="cart-page">
  <div class="container">
    <h1>@code echo __('Shopping Cart'); @endcode</h1>

    {{-- Cart summary from session --}}
    <div class="cart-summary">
      <p>
        @code echo __('Items in cart:'); @endcode
        <strong>@code echo cw_get_cart_count(); @endcode</strong>
      </p>

      {{-- Applied discounts --}}
      @code
        __applied_discounts = cw_get_cart_applied_discounts();
      @endcode
      @if(cw_count(var: 'applied_discounts') > 0)
        <div class="cart-discounts">
          <h3>@code echo __('Applied Discounts'); @endcode</h3>
          @foreach(__applied_discounts as __discount)
            <div class="cart-discount">
              <span>@code echo __discount.code; @endcode</span>
              <span>-@code echo __discount.display_name; @endcode</span>
            </div>
          @endforeach
        </div>
      @endif
    </div>

    {{-- Featured products --}}
    @query(__featured_products, ['type' => 'products', 'limit' => 4, 'orderby' => 'created_at', 'order' => 'desc'])

    @if(cw_count(var: 'featured_products') > 0)
      <h2>@code echo __('Featured Products'); @endcode</h2>
      <div class="product-grid">
        @foreach(__featured_products as __product)
          @include('product-card', ['product' => __product])
        @endforeach
      </div>
    @else
      <div class="cart-empty">
        <p>@code echo __('Your cart is empty.'); @endcode</p>
        <a href="@link('/shop')" class="btn btn--primary">@code echo __('Continue Shopping'); @endcode</a>
      </div>
    @endif
  </div>
</div>

@include('footer')

{{--
  Template Name: Product Detail
  Template Key: product.detail
--}}

@code
  __related_products = cw_get_related_products(productId: __product.id, limit: 4);
  __reviews = cw_product_reviews(productId: __product.id, page: 1, limit: 5);
@endcode

@include('header')

<div class="product-detail">
  <div class="container">
    <div class="product-detail__gallery">
      @has_image(__product)
        <div class="product-gallery__main">
          @image(__product, 'large')
        </div>
      @else
        <div class="product-gallery__placeholder">No Image</div>
      @endis

      {{-- Gallery images --}}
      @if(cw_count(var: __product.images) > 1)
        <div class="product-gallery__thumbs">
          @foreach(__product.images as __image)
            <img src="@code echo __image.thumbnail; @endcode"
                 alt="@code echo __image.alt; @endcode"
                 class="@if(__image.is_cover) active @endif">
          @endforeach
        </div>
      @endif
    </div>

    <div class="product-detail__info">
      <h1>@code echo __product.title; @endcode</h1>

      {{-- Star rating --}}
      @if(__product.rating > 0)
      <div class="product-detail__rating">
        @for(__i=0; __i<5; __i++)
          @if(__i < cw_count(var: __product.rating))
            <span class="star star--filled">★</span>
          @else
            <span class="star star--empty">☆</span>
          @endif
        @endfor
        <a href="#reviews">@code echo __product.review_count; @endcode @code echo __('reviews'); @endcode</a>
      </div>
      @endif

      <div class="product-detail__price">
        @if(__product.on_sale && __product.compare_price)
          <span class="price--compare">@code echo cw_format_money(amount: __product.compare_price); @endcode</span>
          <span class="price--current price--sale">@code echo cw_format_money(amount: __product.price); @endcode</span>
          <span class="price--badge">Sale!</span>
        @else
          <span class="price--current">@code echo cw_format_money(amount: __product.price); @endcode</span>
        @endif
      </div>

      <div class="product-detail__description">
        @code echo __product.description; @endcode
      </div>

      <div class="product-detail__actions">
        @hook('product.add_to_cart', __product)
      </div>
    </div>
  </div>
</div>

{{-- Customer Reviews --}}
<section id="reviews" class="product-reviews">
  <div class="container">
    <h2>@code echo __('Customer Reviews'); @endcode
      (@code echo __product.review_count; @endcode)
    </h2>

    @if(cw_count(var: 'reviews') > 0)
      @foreach(__reviews as __review)
        <div class="review">
          <div class="review__rating">
            @for(__i=0; __i<__review.rating; __i++)★ @endfor
            @for(__i=__review.rating; __i<5; __i++)☆ @endfor
          </div>
          <p class="review__comment">@code echo __review.comment; @endcode</p>
          <span class="review__author">— @code echo __review.author; @endcode</span>
          <span class="review__date">@code echo __review.date; @endcode</span>
        </div>
      @endforeach
    @else
      <p>@code echo __('No reviews yet. Be the first to review!'); @endcode</p>
    @endif

    {{-- Submit review form --}}
    <div class="review-form">
      <h3>@code echo __('Write a Review'); @endcode</h3>
      <form method="post" action="@link('/reviews/submit')">
        <input type="hidden" name="product_id" value="@code echo __product.id; @endcode">
        <div class="form-group">
          <label>@code echo __('Rating'); @endcode</label>
          <select name="rating" required>
            <option value="5">★★★★★</option>
            <option value="4">★★★★☆</option>
            <option value="3">★★★☆☆</option>
            <option value="2">★★☆☆☆</option>
            <option value="1">★☆☆☆☆</option>
          </select>
        </div>
        <div class="form-group">
          <label>@code echo __('Review'); @endcode</label>
          <textarea name="comment" rows="4" required></textarea>
        </div>
        <button type="submit" class="btn btn--primary">
          @code echo __('Submit Review'); @endcode
        </button>
      </form>
    </div>
  </div>
</section>

{{-- Related Products --}}
@if(cw_count(var: 'related_products') > 0)
<section class="related-products">
  <div class="container">
    <h2>@code echo __('Related Products'); @endcode</h2>
    <div class="product-grid">
      @each('product-card', __related_products, 'product')
    </div>
  </div>
</section>
@endif

@include('footer')

{{-- Using the @asset directive --}}
<img src="@asset('assets/images/logo.png')" alt="Logo">

{{-- Using @css to enqueue stylesheets --}}
@css('assets/css/hero.css')
@css('assets/css/cart.css')

{{-- Using @js to enqueue scripts --}}
@js('assets/js/carousel.js')
@js('assets/js/main.js')

{{-- Using product image property --}}
<img src="@code echo __product.image; @endcode" alt="@code echo __product.title; @endcode">

{{--
  Template Part: Header
  Usage: @include('header')
--}}
@code __store = cw_get_store(); @endcode
<header class="site-header">
  <div class="container">
    <div class="header__logo">
      <a href="@link('/')">
        <img src="@asset('assets/images/logo.png')" alt="@code echo __store.name; @endcode">
      </a>
    </div>
    <nav class="header__nav">
      <ul>
        <li><a href="@link('/shop')">@code echo __('Shop'); @endcode</a></li>
        <li><a href="@link('/about')">@code echo __('About'); @endcode</a></li>
        <li><a href="@link('/blog')">@code echo __('Blog'); @endcode</a></li>
        <li><a href="@link('/contact')">@code echo __('Contact'); @endcode</a></li>
      </ul>
    </nav>
    <div class="header__actions">
      <a href="@link('/account')" class="header__icon">@code echo __('My Account'); @endcode</a>
      <a href="@link('/login')" class="header__icon">@code echo __('Login'); @endcode</a>
    </div>
  </div>
</header>

{{--
  Template Part: Footer
  Usage: @include('footer')
--}}
@code __store = cw_get_store(); @endcode
<footer class="site-footer">
  <div class="container">
    <div class="footer__grid">
      <div class="footer__col">
        <h4>@code echo __('Quick Links'); @endcode</h4>
        <ul>
          <li><a href="@link('/about')">@code echo __('About Us'); @endcode</a></li>
          <li><a href="@link('/contact')">@code echo __('Contact'); @endcode</a></li>
          <li><a href="@link('/privacy')">@code echo __('Privacy Policy'); @endcode</a></li>
        </ul>
      </div>
      <div class="footer__col">
        <h4>@code echo __('Contact'); @endcode</h4>
        <p>@code echo __store.email; @endcode</p>
        <p>@code echo __store.phone; @endcode</p>
      </div>
    </div>
    <div class="footer__bottom">
      <p>&copy; @code echo date('Y'); @endcode @code echo __store.name; @endcode. @code echo __('All rights reserved.'); @endcode</p>
    </div>
  </div>
  @hook('footer_injection')
</footer>

// manifest.json — headerPresets and footerPresets
{
  "name":        "My Storefront Theme",
  "version":     "2.0.0",
  "formatVersion": 3,

  "headerPresets": [
    {
      "key":      "header-light",
      "label":    "Light Header",
      "partial":  "partials/header-light.cw"
    },
    {
      "key":      "header-dark",
      "label":    "Dark Header",
      "partial":  "partials/header-dark.cw"
    }
  ],

  "footerPresets": [
    {
      "key":      "footer-dark",
      "label":    "Dark Footer",
      "partial":  "partials/footer-dark.cw"
    },
    {
      "key":      "footer-minimal",
      "label":    "Minimal Footer",
      "partial":  "partials/footer-minimal.cw"
    }
  ],

  "defaultHeaderPresetKey": "header-light",
  "defaultFooterPresetKey": "footer-dark"
}

{
  "corewavePseudoCode": {
    "engine": "corewave-pseudo/1.0",
    "blocks": [
      {
        "id":     "welcome-email",
        "hook":    "corewave.customer.after_signup",
        "action": "send_email",
        "args": {
          "template": "welcome",
          "subject": "Welcome to our store!"
        }
      }
    ]
  }
}

{
  "name":        "WhatsApp Chat",
  "pluginCode": "whatsapp-chat",
  "version":     "2.0.0",

  "corewavePseudoCode": {
    "engine": "corewave-pseudo/1.0",
    "blocks": [
      {
        "id":     "whatsapp-button",
        "hook":    "corewave.theme.page.render",
        "action": "inject_html",
        "args": {
          "position": "body_end",
          "html":    "
Chat with us"
        }
      }
    ]
  }
}

my-theme-v3.0.0.zip
├── manifest.json
├── design.json
├── templates/
├── assets/
└── bundled-plugins/
    ├── whatsapp-chat-v2.0.0.zip
    └── reviews-summary-v2.0.0.zip

{{-- Action hook — plugins can execute code here --}}
@hook('product.card.after', __product)

{{-- Filter hook — plugins can modify a value --}}
@code
  __html = '<span class="price">' . cw_format_price(__product.price) . '</span>';
  __html = @filter('product.price_html', __html);
  echo __html;
@endcode

{{-- Widget area — plugins can render UI components --}}
@widget('sidebar')

"widgets": {
  "featured-products": {
    "label":       "Featured Products",
    "description": "Displays a grid of featured products",
    "template":  "widgets/featured-products.cw",
    "fields": {
      "title":    { "label": "Section Title", "type": "text", "default": "Featured Products" },
      "limit":   { "label": "Product Count", "type": "number", "default": 4 },
      "category": { "label": "Category Filter", "type": "select", "default": "", "source": "categories" }
    }
  }
}

{-- widgets/featured-products.cw --}
{-- Load category options dynamically using cw_get_select_options --}
@code
  __category_opts = cw_get_select_options(['source' => 'categories', 'limit' => 100]);
  __selected_cat  = __widget.settings.category;
@endcode

{-- If admin selected a specific category, only show those products --}
@if(__selected_cat)
  @query(__products, [
    'category' => __selected_cat,
    'limit'    => __widget.settings.limit ?? 4
  ])
@else
  @query(__products, [
    'featured' => 1,
    'limit'    => __widget.settings.limit ?? 4
  ])
@endif

<section class="featured-products-widget">
  @if(__widget.settings.title)
    <h2>{ __widget.settings.title }</h2>
  @endif

  {-- Render a category filter dropdown using @foreach over dynamic options --}
  <form class="category-filter">
    <select name="category" onchange="this.form.submit()">
      <option value="">All Categories</option>
      @foreach(__category_opts as __opt)
        <option value="{ __opt.value }" @if(__opt.value == __selected_cat)selected</option>
      @endforeach
    </select>
  </form>

  <div class="product-grid">
    @foreach(__products as __product)
      <div class="product-card">
        <a href="{ __product.url }">
          <img src="{ __product.thumbnail }" alt="{ __product.title }" loading="lazy" />
          <h3>{ __product.title }</h3>
        </a>
        <span class="price">{ cw_format_price(__product.price) }</span>
      </div>
    @endforeach
  </div>
</section>

my-theme-v3.0.0.zip
├── manifest.json
├── design.json
├── templates/
├── widgets/                    // Custom widget .cw templates
│   ├── featured-products.cw
│   ├── newsletter-signup.cw
│   └── social-links.cw
├── assets/
└── bundled-plugins/

{-- Render widget with default settings --}
@widget('featured-products')

{-- Render widget with overridden settings --}
@widget('featured-products', [
  'title'    => 'Best Sellers',
  'limit'    => 8,
  'category' => 'best-sellers'
])

{-- Widget area — admins can place any widget here --}
<aside class="sidebar">
  @widget('blog-sidebar')
</aside>

{
  "fields": {
    "category": {
      "label":   "Category Filter",
      "type":    "select",
      "default": "",
      "options": [
        { "value": "clothing",   "label": "Clothing" },
        { "value": "electronics", "label": "Electronics" },
        { "value": "accessories", "label": "Accessories" }
      ]
    },
    "colors": {
      "label":   "Available Colors",
      "type":    "multi-select",
      "default": ["red"],
      "options": [
        { "value": "red",   "label": "Red" },
        { "value": "blue",  "label": "Blue" },
        { "value": "green", "label": "Green" }
      ]
    }
  }
}

@if(widget.settings.category == 'clothing')
  <div class="filter filter--clothing">Showing clothing items</div>
@elseif(widget.settings.category == 'electronics')
  <div class="filter filter--electronics">Showing electronics</div>
@else
  <div class="filter filter--all">Showing all categories</div>
@endif

{-- Decode multi-select value into an array --}
@code
  __selected_colors = cw_json_decode(widget.settings.colors);
@endcode

{-- Check if a specific value is selected --}
@if(in_array('red', __selected_colors))
  <div class="color-swatch color-swatch--red">Red is active</div>
@endif

{-- Iterate through all selected values --}
<ul class="selected-filters">
  @foreach(__selected_colors as __color)
    <li>{ __color }</li>
  @endforeach
</ul>

{
  "fields": {
    "category": {
      "label":   "Category Filter",
      "type":    "select",
      "default": "",
      "source": "categories"
    },
    "products": {
      "label":   "Featured Products",
      "type":    "multi-select",
      "default": [],
      "source": "products"
    }
  }
}

{-- Fetch select options from a data source --}
@code
  __category_opts = cw_get_select_options(['source' => 'categories', 'limit' => 100]);
  __product_opts  = cw_get_select_options(['source' => 'products', 'limit' => 50, 'order' => 'asc']);
  __blog_opts     = cw_get_select_options(['source' => 'blogs']);
  __country_opts  = cw_get_select_options(['source' => 'countries', 'orderBy' => 'name']);
  __tag_opts      = cw_get_select_options(['source' => 'tags', 'scope' => 'products']);
  __discount_opts = cw_get_select_options(['source' => 'discounts']);
@endcode

{-- Render a single-select dropdown using dynamic options --}
<select name="category">
  @foreach(__category_opts as __opt)
    <option value="{ __opt.value }">{ __opt.label }</option>
  @endforeach
</select>

{-- Render a multi-select checkbox group using dynamic options --}
@code
  __selected_cats = cw_json_decode(widget.settings.categories);
@endcode
<div class="checkbox-group">
  @foreach(__category_opts as __opt)
    <label>
      <input type="checkbox"
             value="{ __opt.value }"
             {{ in_array(__opt.value, __selected_cats) ? 'checked' : '' }}>
      { __opt.label }
    </label>
  @endforeach
</div>

{
  "schemaVersion": 3,
  "themeCode":      "my-storefront-theme",
  "version":        "1.0.0",
  "generatedAt":    "2025-01-15T10:30:00.000Z",

  "manifest":      { /* sanitized manifest.json */ },
  "defaultDesign": { /* design.json (if present) */ },

  "themeCssUrl": "https://storage.googleapis.com/.../style.css",
  "cssUrls": [ /* ordered CSS URLs */ ],
  "scriptUrls": [ /* ordered JS URLs */ ],

  "files": {
    "assets/css/style.css": "https://storage.googleapis.com/.../style.css",
    "assets/images/logo.png": "https://storage.googleapis.com/.../logo.png"
  },

  "templates": {
    "catalogue.home": { /* inlined .cw content */ },
    "page.default": "https://storage.googleapis.com/.../page.default.cw"
  },
  "templateFormats": {
    "catalogue.home": "cw",
    "cart.default": "json"
  }
}

curl -i 'https://api.books.corewave360.com/v1/public/storefront/ssr?host=corewave360.com&path=/blogs/news/spring-launch'

location / {
  proxy_pass https://api.books.corewave360.com/v1/public/storefront/ssr?host=$host&path=$request_uri;
  proxy_set_header Host api.books.corewave360.com;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

"starterContent": {
  "catalogue.home": {
    "name":   "Home",
    "status": "Published"
  },
  "catalogue.default": {
    "name":   "Catalog",
    "status": "Published"
  }
}

"starterContent": {
  "catalogue.home": { "name": "Home", "status": "Published" },

  "pages": [
    {
      "title":             "About Us",
      "handle":            "about-us",
      "templateKey":       "page.default",
      "headerPresetKey":   "header-dark",
      "footerPresetKey":   "footer-minimal",
      "showInNavigation":  true,
      "sortOrder":         2,
      "publish":           true
    },
    {
      "title":             "Contact",
      "handle":            "contact",
      "templateKey":       "page.default",
      "headerPresetKey":   "header-light",
      "showInNavigation":  true,
      "sortOrder":         3,
      "publish":           true
    }
  ]
}

"starterContent": {
  "catalogue.home": { "name": "Home", "status": "Published" },
  "catalogue.default": { "name": "Catalog", "status": "Published" },
  "menus": {
    "main": [
      { "label": "Home",   "url": "/",        "sortOrder": 1 },
      { "label": "Shop",   "url": "/shop",    "sortOrder": 2 },
      { "label": "About",  "pageHandle": "about-us", "sortOrder": 3 },
      { "label": "Blog",   "url": "/blogs",   "sortOrder": 4 },
      { "label": "Categories", "sortOrder": 5,
        "children": [
          { "label": "Clothing",  "pageHandle": "category-clothing",  "sortOrder": 1 },
          { "label": "Electronics", "pageHandle": "category-electronics", "sortOrder": 2 }
        ]
      }
    ],
    "footer": [
      { "label": "Contact", "pageHandle": "contact", "sortOrder": 1 }
    ],
    "secondary-nav": [
      { "label": "Support", "url": "/support", "sortOrder": 1 },
      { "label": "FAQ", "pageHandle": "faq", "sortOrder": 2 }
    ]
  }
}