Fix template quirks and bump version to 0.1.0

Audit and fix 14 Twig templates for escaping bugs, CSS conflicts,
and missing Bootstrap styling:
- Fix nl2br/esc_html filter order in order details
- Add WC gallery modifier classes for zoom/photoswipe JS init
- Fix HTML entity double-encoding in headings (up-sells, cross-sells, related)
- Remove wrong 'is defined' guards on function calls
- Remove duplicate deprecated hooks in dashboard
- Add |raw to brand description HTML filter chain
- Add role="alert" for accessibility, |esc_attr on notification types
- Style mini-cart remove button as Bootstrap btn
- Make shipping form-check class conditional
- Add shop_table CSS reset and gallery opacity fallback

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(docker exec woocommerce *)",
+      "Bash(docker compose *)",
+      "Bash(composer *)",
+      "Bash(npm *)",
+      "Bash(ls *)",
+      "Bash(mkdir *)",
+      "Bash(cat *)",
+      "Bash(php *)"
+    ]
+  }
+}

CLAUDE.md

@@ -215,6 +215,10 @@ Recurring bugs and non-obvious behaviours discovered across sessions. **Read thi
 - **Twig autoescape + WordPress escape filters = double encoding** -- register all `esc_*` filters with `['is_safe' => ['html']]` option in the plugin's `Template.php`.
 - **`wp i18n make-pot` does NOT scan Twig templates** -- any string used exclusively in `.html.twig` files must be manually added to the `.pot` file.
 - **`#, fuzzy` silently skips translations at runtime** -- always remove fuzzy flags after verifying translations.
+- **`|nl2br|esc_html` is wrong filter order** -- `nl2br` outputs `<br>` tags, then `esc_html` escapes them to `&lt;br&gt;`. Correct: `|esc_html|nl2br`.
+- **`function() is defined` is semantically wrong** -- always evaluates truthy since the function is called regardless. Use `{% if function() %}` directly.
+- **HTML entities in translated strings get double-encoded** -- `&hellip;` in `__()` becomes `&amp;hellip;`. Use Unicode `…` directly or append `|raw` for trusted filter output.
+- **Filter chains producing HTML need `|raw`** -- e.g., `term_description()|wptexturize|wpautop|do_shortcode|raw`.
 
 ### Bootstrap 5 vs Plugin CSS Conflicts
 
@@ -222,6 +226,10 @@ Recurring bugs and non-obvious behaviours discovered across sessions. **Read thi
 - **CSS dependency chain**: `woocommerce` -> child theme overrides. Ensures correct cascade.
 - jQuery `.show()`/`.hide()` cannot override Bootstrap `!important` (`d-none`). Toggle both class and inline style.
 - `overflow: visible !important` on `.wp-block-navigation__container` is essential for dropdowns inside block theme navigation.
+- **WooCommerce `shop_table` borders conflict with Bootstrap `.table`** -- reset with `.woocommerce table.shop_table { border: 0 }` and cell `border-left/right: 0`.
+- **WooCommerce gallery JS requires modifier classes** -- `--with-images`, `--without-images`, `--columns-N` on `.woocommerce-product-gallery` + `style="opacity: 0"` for fade-in. Without these, zoom and photoswipe won't initialize.
+- **WooCommerce float layout fights Bootstrap grid** -- `div.product div.images/summary` have `float:left/right; width:48%` in `woocommerce-layout.css`. Override with `float: none; width: 100%`.
+- **Bootstrap `g-*` gutters add negative top margin** -- `g-4` sets both `--bs-gutter-x` and `--bs-gutter-y`; the `.row` gets `margin-top: calc(-1 * var(--bs-gutter-y))` pulling it upward. Use `gx-*` for horizontal-only gutters when vertical gap isn't desired.
 
 ### Double Heading Prevention
 
@@ -268,7 +276,7 @@ wp-bootstrap (parent theme, Bootstrap 5 FSE + Twig rendering)
 ### Important Constraints
 
 - **WooCommerce plugin is read-only.** We have no control over its source code. All customizations happen in the child theme via template overrides and hooks.
-- **Docker environment is not yet set up.** Commands referencing `docker exec` (e.g., in the translation workflow) are not currently available. Local alternatives or manual steps must be used until the container is configured.
+- **Docker environment:** Container name is `woocommerce`. Use `docker exec woocommerce ...` for commands and `docker exec woocommerce apache2ctl graceful` to clear OPcache after PHP changes.
 
 ### Cross-Project Workflow
 
@@ -313,7 +321,7 @@ The child theme inherits from `wp-bootstrap` via WordPress `Template: wp-bootstr
 
 ## Version History
 
-Current version: **v0.0.1**
+Current version: **v0.1.0**
 
 ## Session History
 
@@ -342,3 +350,32 @@ Current version: **v0.0.1**
 - **`bg-primary-subtle` for icon containers**: These Bootstrap 5.3 contextual utilities automatically adapt to dark mode, unlike hardcoded colors.
 - **Welcome message restructured**: Separated greeting from logout link instead of using WooCommerce's default inline-linked `__()` string. This gives full control over card layout and avoids translated strings containing HTML structure assumptions.
 - **Templates NOT changed** (already well-done): `orders.html.twig`, `my-address.html.twig`, `form-login.html.twig`, `payment-methods.html.twig`, `form-add-payment-method.html.twig`, `downloads.html.twig`
+
+### 2026-02-28 — Single Product Bootstrap 5 Layout + Template Quirks Audit
+
+**Scope:** Created Bootstrap 5 two-column layout for single product pages. Then audited all ~90 Twig templates for WooCommerce CSS quirks, Twig escaping bugs, and missing Bootstrap styling.
+
+**Single product layout (3 files):**
+
+- `woocommerce/content-single-product.php` — Bridge file for `wc_get_template_part()` interception
+- `templates/content-single-product.html.twig` — Two-column `row gx-4 gx-lg-5` grid (images left, summary right)
+- `assets/css/wc-bootstrap.css` — Float/width reset, sale badge positioning, shop_table border reset, gallery opacity fallback
+
+**Template quirks audit (14 files fixed):**
+
+- `order/order-details.html.twig` — Fixed `|nl2br|esc_html` filter order (was escaping `<br>` tags)
+- `single-product/product-image.html.twig` — Added WC gallery modifier classes + opacity:0 for JS init
+- `brands/brand-description.html.twig` — Added `|raw` to HTML-producing filter chain
+- `single-product/up-sells.html.twig`, `cart/cross-sells.html.twig`, `single-product/related.html.twig` — Fixed `&hellip;` double-encoding in headings
+- `myaccount/dashboard.html.twig` — Removed duplicate deprecated hook fires
+- `product-searchform.html.twig` — Replaced `&hellip;` entity with Unicode `…`
+- `cart/cart-totals.html.twig`, `checkout/review-order.html.twig`, `checkout/form-login.html.twig`, `checkout/terms.html.twig` — Removed wrong `function() is defined` guards
+- `wc-base.html.twig` — Added `|esc_attr` on notification type in class attribute
+- `global/form-login.html.twig` — Added `is defined` guard on `hidden` variable
+- `single-product/add-to-cart/variation.html.twig` — Added `role="alert"` for accessibility
+- `cart/mini-cart.html.twig` — Changed remove link to Bootstrap `btn btn-sm btn-outline-danger`
+- `cart/cart-shipping.html.twig` — Made `form-check` class conditional on multiple shipping methods
+
+**Infrastructure:**
+
+- Created `.claude/settings.json` with allowed commands (git, docker, composer, npm, etc.)

assets/css/wc-bootstrap.css

@@ -209,10 +209,13 @@
 
 /* ==========================================================================
    Sale Badge
-   Positioning for the sale overlay badge on product cards.
+   Position inside gallery area, not overlapping breadcrumb.
+   WooCommerce sets top: -.5em which bleeds above the containing block.
    ========================================================================== */
 
-.onsale {
+.woocommerce span.onsale {
+    top: 0.5em;
+    left: 0.5em;
     z-index: 1;
 }
 
@@ -263,6 +266,18 @@
     border-radius: var(--bs-border-radius);
 }
 
+/* ==========================================================================
+   Single Product Layout
+   Reset WooCommerce's float-based two-column layout for single product pages.
+   Bootstrap's row/col-lg-6 grid handles the layout instead.
+   ========================================================================== */
+
+.woocommerce div.product div.images,
+.woocommerce div.product div.summary {
+    float: none;
+    width: 100%;
+}
+
 /* ==========================================================================
    Variation Selectors
    Spacing for variable product attribute dropdowns.
@@ -502,3 +517,30 @@ header.sticky-top.is-stuck {
 .product-quantity {
     white-space: nowrap;
 }
+
+/* ==========================================================================
+   Shop Table
+   Reset WooCommerce's border styles on .shop_table to let Bootstrap's
+   .table class handle borders via --bs-table-* custom properties.
+   ========================================================================== */
+
+.woocommerce table.shop_table {
+    border: 0;
+    border-collapse: collapse;
+}
+
+.woocommerce table.shop_table td,
+.woocommerce table.shop_table th {
+    border-left: 0;
+    border-right: 0;
+}
+
+/* ==========================================================================
+   Product Gallery
+   WooCommerce JS sets opacity: 1 after initialization. Ensure the gallery
+   is visible even if WC JS doesn't run (e.g., gallery features disabled).
+   ========================================================================== */
+
+.woocommerce-product-gallery--without-images {
+    opacity: 1 !important;
+}

functions.php

@@ -23,7 +23,7 @@ if ( ! defined( 'ABSPATH' ) ) {
  * 2. This PHP constant — used internally by the theme
  * Both MUST be updated on every release.
  */
-define( 'WC_BOOTSTRAP_VERSION', '0.0.1' );
+define( 'WC_BOOTSTRAP_VERSION', '0.1.0' );
 define( 'WC_BOOTSTRAP_PATH', get_stylesheet_directory() . '/' );
 define( 'WC_BOOTSTRAP_URL', get_stylesheet_directory_uri() . '/' );
 
@@ -272,11 +272,27 @@ function wc_bootstrap_remove_default_sidebar(): void {
 add_action( 'init', 'wc_bootstrap_remove_default_sidebar' );
 
 /**
- * Prevent the parent theme from rendering product archives.
+ * Replace WooCommerce's content wrapper with a no-op.
+ *
+ * The parent theme's page shell already wraps content in a .container,
+ * so WooCommerce's default wrapper (another .container + #primary + <main>)
+ * creates a double-nested container that constrains width. Remove it and
+ * let the parent theme handle the outer layout.
+ *
+ * @since 0.1.0
+ */
+function wc_bootstrap_remove_content_wrappers(): void {
+    remove_action( 'woocommerce_before_main_content', 'woocommerce_output_content_wrapper', 10 );
+    remove_action( 'woocommerce_after_main_content', 'woocommerce_output_content_wrapper_end', 10 );
+}
+add_action( 'init', 'wc_bootstrap_remove_content_wrappers' );
+
+/**
+ * Prevent the parent theme from rendering WooCommerce pages.
  *
  * The parent theme's TemplateController hooks template_redirect at priority 10
- * and renders pages/archive.html.twig for all archives (then exits). For product
- * archives, we need to render our own WooCommerce-specific Bootstrap layout instead.
+ * and renders its own templates for all requests (then exits). For WooCommerce
+ * pages we need to render our own Bootstrap layouts instead.
  * Returning false tells the parent theme to skip rendering for this request.
  *
  * @param bool $should_render Whether the parent theme should render.
@@ -284,16 +300,38 @@ add_action( 'init', 'wc_bootstrap_remove_default_sidebar' );
  *
  * @since 0.1.0
  */
-function wc_bootstrap_skip_parent_archive( bool $should_render ): bool {
+function wc_bootstrap_skip_parent_template( bool $should_render ): bool {
     if ( is_post_type_archive( 'product' ) || is_page( wc_get_page_id( 'shop' ) ) ) {
         return false;
     }
     if ( function_exists( 'is_product_taxonomy' ) && is_product_taxonomy() ) {
         return false;
     }
+    if ( function_exists( 'is_product' ) && is_product() ) {
+        return false;
+    }
     return $should_render;
 }
-add_filter( 'wp_bootstrap_should_render_template', 'wc_bootstrap_skip_parent_archive' );
+add_filter( 'wp_bootstrap_should_render_template', 'wc_bootstrap_skip_parent_template' );
+
+/**
+ * Disable WooCommerce's block template compatibility layer.
+ *
+ * The parent theme has theme.json which makes wp_is_block_theme() return true.
+ * WooCommerce detects this and removes classic template hooks (title, price,
+ * add-to-cart, etc.) from single product and archive pages, expecting blocks
+ * to handle rendering instead. Since we render via classic hooks + Twig, we
+ * need the hooks to stay registered.
+ *
+ * @param bool $disabled Whether the compatibility layer is disabled.
+ * @return bool
+ *
+ * @since 0.1.0
+ */
+function wc_bootstrap_disable_block_compatibility( bool $disabled ): bool {
+    return true;
+}
+add_filter( 'woocommerce_disable_compatibility_layer', 'wc_bootstrap_disable_block_compatibility' );
 
 /**
  * Render product archive pages with Bootstrap 5 layout.
@@ -323,7 +361,7 @@ function wc_bootstrap_render_product_archive(): void {
 
     // Capture WooCommerce archive content via output buffering.
     ob_start();
-    include get_stylesheet_directory() . '/archive-product.php';
+    include get_stylesheet_directory() . '/woocommerce/archive-product.php';
     $content = ob_get_clean();
 
     // Build parent theme context and inject archive content into page shell.
@@ -344,3 +382,50 @@ function wc_bootstrap_render_product_archive(): void {
     exit;
 }
 add_action( 'template_redirect', 'wc_bootstrap_render_product_archive', 11 );
+
+/**
+ * Render single product pages with Bootstrap 5 layout.
+ *
+ * Since the parent theme's TemplateController is blocked for single products
+ * (via wp_bootstrap_should_render_template filter), we render the page ourselves
+ * at priority 11 using the parent theme's TwigService and page shell.
+ *
+ * The single-product.php file fires WooCommerce hooks and is captured via output
+ * buffering, then injected into the parent theme's page template — the same
+ * pattern as wc_bootstrap_render_product_archive().
+ *
+ * @since 0.1.0
+ */
+function wc_bootstrap_render_single_product(): void {
+    if ( ! function_exists( 'is_product' ) || ! is_product() ) {
+        return;
+    }
+
+    if ( ! class_exists( '\WPBootstrap\Twig\TwigService' )
+        || ! class_exists( '\WPBootstrap\Template\ContextBuilder' ) ) {
+        return;
+    }
+
+    // Capture WooCommerce single product content via output buffering.
+    ob_start();
+    include get_stylesheet_directory() . '/woocommerce/single-product.php';
+    $content = ob_get_clean();
+
+    // Build parent theme context and inject product content into page shell.
+    $context_builder = new \WPBootstrap\Template\ContextBuilder();
+    $theme_context   = $context_builder->build();
+    $twig            = \WPBootstrap\Twig\TwigService::getInstance();
+
+    $theme_context['post'] = array_merge(
+        $theme_context['post'] ?? [],
+        [
+            'content'   => $content,
+            'title'     => '',
+            'thumbnail' => '',
+        ]
+    );
+
+    echo $twig->render( 'pages/page.html.twig', $theme_context );
+    exit;
+}
+add_action( 'template_redirect', 'wc_bootstrap_render_single_product', 11 );

style.css

@@ -7,7 +7,7 @@ Description: A Bootstrap 5 child theme for WP Bootstrap that overrides all WooCo
 Requires at least: 6.7
 Tested up to: 6.7
 Requires PHP: 8.3
-Version: 0.0.1
+Version: 0.1.0
 License: GNU General Public License v2 or later
 License URI: http://www.gnu.org/licenses/gpl-2.0.html
 Template: wp-bootstrap

templates/brands/brand-description.html.twig

@@ -24,6 +24,6 @@
     {% endif %}
 
     <div class="text">
-        {{ term_description()|wptexturize|wpautop|do_shortcode }}
+        {{ term_description()|wptexturize|wpautop|do_shortcode|raw }}
     </div>
 </div>

templates/cart/cart-shipping.html.twig

@@ -24,7 +24,7 @@
     {% if available_methods is defined and available_methods|length > 0 %}
         <ul id="shipping_method_{{ index|default(0) }}" class="list-unstyled mb-2">
             {% for method_id, method in available_methods %}
-                <li class="form-check">
+                <li{% if available_methods|length > 1 %} class="form-check"{% endif %}>
                     {% if available_methods|length > 1 %}
                         <input type="radio"
                                name="shipping_method[{{ index|default(0) }}]"
@@ -40,7 +40,7 @@
                                class="shipping_method"
                                data-index="{{ index|default(0) }}" />
                     {% endif %}
-                    <label class="form-check-label" for="shipping_method_{{ index|default(0) }}_{{ method_id|esc_attr }}">
+                    <label class="{{ available_methods|length > 1 ? 'form-check-label' : '' }}" for="shipping_method_{{ index|default(0) }}_{{ method_id|esc_attr }}">
                         {{ method.get_label()|raw }}
                     </label>
                     {{ do_action('woocommerce_after_shipping_rate', method, index|default(0)) }}

templates/cart/cart-totals.html.twig

@@ -44,7 +44,7 @@
             {# Shipping #}
             {{ do_action('woocommerce_cart_totals_before_shipping') }}
 
-            {% if wc_shipping_enabled() is defined and wc_shipping_enabled() %}
+            {% if wc_shipping_enabled() %}
                 <li class="list-group-item cart-shipping">
                     {{ do_action('woocommerce_cart_totals_shipping') }}
                 </li>

templates/cart/cross-sells.html.twig

@@ -18,7 +18,7 @@
     <section class="cross-sells mt-5">
         {% set heading = heading|default(__('You may be interested in&hellip;')) %}
         {% if heading %}
-            <h2 class="h4 mb-4">{{ heading }}</h2>
+            <h2 class="h4 mb-4">{{ heading|raw }}</h2>
         {% endif %}
 
         {{ woocommerce_product_loop_start() }}

templates/cart/mini-cart.html.twig

@@ -26,7 +26,7 @@
                 <li class="woocommerce-mini-cart-item d-flex gap-3 py-2 border-bottom {{ item.css_class|default('') }}">
                     {# Remove link #}
                     <a href="{{ item.remove_url|esc_url }}"
-                       class="remove remove_from_cart_button text-danger"
+                       class="btn btn-sm btn-outline-danger remove remove_from_cart_button"
                        aria-label="{{ __('Remove this item') }}"
                        data-product_id="{{ item.product_id }}"
                        data-cart_item_key="{{ item.key }}">

templates/checkout/form-login.html.twig

@@ -9,7 +9,7 @@
  # @since 0.1.0
  #}
 
-{% if is_user_logged_in() is defined and not is_user_logged_in() %}
+{% if not is_user_logged_in() %}
     <div class="woocommerce-form-login-toggle mb-4">
         <div class="alert alert-info d-flex align-items-center" role="status">
             <i class="bi bi-person me-2" aria-hidden="true"></i>

templates/checkout/review-order.html.twig

@@ -62,7 +62,7 @@
 
                 {{ do_action('woocommerce_review_order_before_shipping') }}
 
-                {% if wc_shipping_enabled() is defined and wc_shipping_enabled() %}
+                {% if wc_shipping_enabled() %}
                     {{ do_action('woocommerce_review_order_shipping') }}
                 {% endif %}
 

templates/checkout/terms.html.twig

@@ -9,7 +9,7 @@
 
 {{ do_action('woocommerce_checkout_before_terms_and_conditions') }}
 
-{% if wc_terms_and_conditions_checkbox_enabled() is defined and wc_terms_and_conditions_checkbox_enabled() %}
+{% if wc_terms_and_conditions_checkbox_enabled() %}
     <div class="woocommerce-terms-and-conditions-wrapper mb-3">
         {{ do_action('woocommerce_checkout_terms_and_conditions') }}
 

templates/content-single-product.html.twig

@@ -0,0 +1,56 @@
+{#
+ # Single Product Content (Bootstrap 5 Override)
+ #
+ # Renders the single product page with a Bootstrap 5 two-column grid:
+ #   Left column (col-lg-6):  Product images (sale flash + gallery)
+ #   Right column (col-lg-6): Product summary (title, rating, price, excerpt,
+ #                             add-to-cart, meta, sharing)
+ #   Full-width rows below:   Tabs, upsells, related products
+ #
+ # All individual components are rendered via WooCommerce action hooks,
+ # which trigger the Bootstrap 5 sub-templates through TemplateOverride.
+ #
+ # Rendered via the content-single-product.php bridge file (not TemplateOverride)
+ # because wc_get_template_part() does not fire the template_part hooks.
+ #
+ # Hook output structure:
+ #   woocommerce_before_single_product_summary → sale flash (10), product images (20)
+ #   woocommerce_single_product_summary        → title (5), rating (10), price (10),
+ #                                               excerpt (20), add-to-cart (30),
+ #                                               meta (40), sharing (50)
+ #   woocommerce_after_single_product_summary  → tabs (10), upsells (15), related (20)
+ #
+ # Context (from bridge file):
+ #   product       - WC_Product object
+ #   product_id    - Product post ID
+ #   product_class - Space-separated CSS class string from wc_get_product_class()
+ #
+ # WooCommerce PHP equivalent: content-single-product.php
+ #
+ # @package WcBootstrap
+ # @since 0.1.0
+ #}
+
+<div id="product-{{ product_id }}" class="{{ product_class }}">
+
+    {# Two-column layout: images left, summary right #}
+    <div class="row gx-4 gx-lg-5 mb-5">
+        {# Left column: Sale flash + Product images #}
+        <div class="col-lg-6 position-relative">
+            {{ do_action('woocommerce_before_single_product_summary') }}
+        </div>
+
+        {# Right column: Product summary #}
+        <div class="col-lg-6">
+            <div class="summary entry-summary">
+                {{ do_action('woocommerce_single_product_summary') }}
+            </div>
+        </div>
+    </div>
+
+    {# Full-width sections: Tabs, Upsells, Related Products #}
+    {{ do_action('woocommerce_after_single_product_summary') }}
+
+</div>
+
+{{ do_action('woocommerce_after_single_product') }}

templates/global/form-login.html.twig

@@ -16,7 +16,7 @@
  #}
 
 {% if not is_user_logged_in() %}
-    <form class="woocommerce-form woocommerce-form-login login{% if hidden %} d-none{% endif %}" method="post">
+    <form class="woocommerce-form woocommerce-form-login login{% if hidden is defined and hidden %} d-none{% endif %}" method="post">
 
         {{ do_action('woocommerce_login_form_start') }}
 

templates/myaccount/dashboard.html.twig

@@ -63,5 +63,3 @@
 </div>
 
 {{ do_action('woocommerce_account_dashboard') }}
-{{ do_action('woocommerce_before_my_account') }}
-{{ do_action('woocommerce_after_my_account') }}

templates/order/order-details.html.twig

@@ -71,7 +71,7 @@
                     {% if order.get_customer_note() %}
                         <tr>
                             <th>{{ __('Note:') }}</th>
-                            <td class="text-end">{{ order.get_customer_note()|nl2br|esc_html }}</td>
+                            <td class="text-end">{{ order.get_customer_note()|esc_html|nl2br }}</td>
                         </tr>
                     {% endif %}
                 </tfoot>

templates/product-searchform.html.twig

@@ -20,7 +20,7 @@
         <input type="search"
                id="{{ field_id }}"
                class="form-control"
-               placeholder="{{ __('Search products&hellip;') }}"
+               placeholder="{{ __('Search products…') }}"
                value="{{ get_search_query() }}"
                name="s" />
         <button type="submit" class="btn btn-outline-primary" aria-label="{{ __('Search') }}">

templates/single-product/add-to-cart/variation.html.twig

@@ -11,6 +11,7 @@
  # @since 0.1.0
  #}
 
+{% verbatim %}
 <script type="text/template" id="tmpl-variation-template">
     <div class="woocommerce-variation-description mb-2">
         {{{ data.variation.variation_description }}}
@@ -22,9 +23,10 @@
         {{{ data.variation.availability_html }}}
     </div>
 </script>
+{% endverbatim %}
 
 <script type="text/template" id="tmpl-unavailable-variation-template">
-    <p class="alert alert-warning mb-0">
+    <p class="alert alert-warning mb-0" role="alert">
         {{ __('Sorry, this product is unavailable. Please choose a different combination.') }}
     </p>
 </script>

templates/single-product/meta.html.twig

@@ -4,12 +4,7 @@
  # Renders SKU, categories, and tags as a definition list.
  #
  # Expected context:
- #   product - WC_Product object with:
- #     .get_sku()          - SKU string
- #     .get_id()           - Product ID
- #   sku                   - SKU string (fallback)
- #   categories_html       - Pre-rendered category links HTML
- #   tags_html             - Pre-rendered tag links HTML
+ #   product - WC_Product object (from TemplateOverride)
  #
  # WooCommerce PHP equivalent: single-product/meta.php
  #
@@ -17,6 +12,14 @@
  # @since 0.1.0
  #}
 
+{# Compute categories/tags HTML when not passed as context. #}
+{% if categories_html is not defined %}
+    {% set categories_html = fn('wc_get_product_category_list', product.get_id(), ', ') %}
+{% endif %}
+{% if tags_html is not defined %}
+    {% set tags_html = fn('wc_get_product_tag_list', product.get_id(), ', ') %}
+{% endif %}
+
 <div class="product_meta border-top pt-3 mt-3">
     {{ do_action('woocommerce_product_meta_start') }}
 
@@ -26,13 +29,13 @@
             <dd class="col-sm-9">{{ product.get_sku()|esc_html }}</dd>
         {% endif %}
 
-        {% if categories_html is defined and categories_html %}
-            <dt class="col-sm-3 text-body-secondary">{{ __('Categories:') }}</dt>
+        {% if categories_html %}
+            <dt class="col-sm-3 text-body-secondary">{{ fn('_n', 'Category:', 'Categories:', product.get_category_ids()|length, 'woocommerce') }}</dt>
             <dd class="col-sm-9">{{ categories_html|raw }}</dd>
         {% endif %}
 
-        {% if tags_html is defined and tags_html %}
-            <dt class="col-sm-3 text-body-secondary">{{ __('Tags:') }}</dt>
+        {% if tags_html %}
+            <dt class="col-sm-3 text-body-secondary">{{ fn('_n', 'Tag:', 'Tags:', product.get_tag_ids()|length, 'woocommerce') }}</dt>
             <dd class="col-sm-9">{{ tags_html|raw }}</dd>
         {% endif %}
     </dl>

templates/single-product/product-image.html.twig

@@ -16,9 +16,16 @@
  # @since 0.1.0
  #}
 
-{% set gallery_classes = 'woocommerce-product-gallery' %}
+{% set cols = columns|default(4) %}
+{% set has_images = post_thumbnail_id is defined and post_thumbnail_id %}
+{% set gallery_classes = 'woocommerce-product-gallery woocommerce-product-gallery--columns-' ~ cols %}
+{% if has_images %}
+    {% set gallery_classes = gallery_classes ~ ' woocommerce-product-gallery--with-images' %}
+{% else %}
+    {% set gallery_classes = gallery_classes ~ ' woocommerce-product-gallery--without-images' %}
+{% endif %}
 
-<div class="{{ gallery_classes }}" data-columns="{{ columns|default(4) }}">
+<div class="{{ gallery_classes }}" data-columns="{{ cols }}" style="opacity: 0; transition: opacity .25s ease-in-out;">
     <div class="woocommerce-product-gallery__wrapper">
         {# Main product image #}
         {% if main_image_html is defined and main_image_html %}

templates/single-product/rating.html.twig

@@ -4,10 +4,7 @@
  # Renders the star rating with review count link on the single product page.
  #
  # Expected context:
- #   product       - WC_Product object
- #   rating_count  - Number of ratings
- #   review_count  - Number of reviews
- #   average       - Average rating (0-5)
+ #   product - WC_Product object (from TemplateOverride)
  #
  # WooCommerce PHP equivalent: single-product/rating.php
  #
@@ -15,7 +12,17 @@
  # @since 0.1.0
  #}
 
-{% if rating_count is defined and rating_count > 0 %}
+{# Guard: bail if ratings are disabled. #}
+{% if fn('wc_review_ratings_enabled') %}
+
+{# Compute rating data from product object when not passed as context. #}
+{% if rating_count is not defined %}
+    {% set rating_count = product.get_rating_count() %}
+    {% set review_count = product.get_review_count() %}
+    {% set average = product.get_average_rating() %}
+{% endif %}
+
+{% if rating_count > 0 %}
     <div class="woocommerce-product-rating d-flex align-items-center gap-2 mb-3">
         <div class="wc-star-rating d-flex align-items-center gap-1"
              role="img"
@@ -31,10 +38,12 @@
             {% endfor %}
         </div>
 
-        {% if review_count is defined and review_count > 0 %}
+        {% if review_count > 0 %}
             <a href="#reviews" class="woocommerce-review-link text-body-secondary text-decoration-none small" rel="nofollow">
-                {{ _n('%s customer review', '%s customer reviews', review_count)|format(review_count) }}
+                {{ fn('_n', '%s customer review', '%s customer reviews', review_count, 'woocommerce')|format(review_count) }}
             </a>
         {% endif %}
     </div>
 {% endif %}
+
+{% endif %}{# wc_review_ratings_enabled #}

templates/single-product/related.html.twig

@@ -18,7 +18,7 @@
     <section class="related products mt-5">
         {% set heading = heading|default(__('Related products')) %}
         {% if heading %}
-            <h2 class="h4 mb-4">{{ heading|esc_html }}</h2>
+            <h2 class="h4 mb-4">{{ heading|raw }}</h2>
         {% endif %}
 
         {{ woocommerce_product_loop_start() }}

templates/single-product/short-description.html.twig

@@ -2,7 +2,8 @@
  # Product Short Description (Bootstrap 5 Override)
  #
  # Expected context:
- #   short_description - Product short description HTML
+ #   product           - WC_Product object (from TemplateOverride)
+ #   short_description - Product short description HTML (optional)
  #
  # WooCommerce PHP equivalent: single-product/short-description.php
  #
@@ -10,7 +11,12 @@
  # @since 0.1.0
  #}
 
-{% if short_description is defined and short_description %}
+{# Compute short description when not passed as context. #}
+{% if short_description is not defined %}
+    {% set short_description = apply_filters('woocommerce_short_description', product.get_short_description()) %}
+{% endif %}
+
+{% if short_description %}
     <div class="woocommerce-product-details__short-description lead text-body-secondary mb-3">
         {{ short_description|raw }}
     </div>

templates/single-product/tabs/tabs.html.twig

@@ -16,7 +16,12 @@
  # @since 0.1.0
  #}
 
-{% if product_tabs is defined and product_tabs|length > 0 %}
+{# Compute tabs from filter when not passed as context (wc_get_template passes no args). #}
+{% if product_tabs is not defined %}
+    {% set product_tabs = apply_filters('woocommerce_product_tabs', {}) %}
+{% endif %}
+
+{% if product_tabs|length > 0 %}
     <div class="woocommerce-tabs wc-tabs-wrapper mt-5">
         {# Tab navigation #}
         <ul class="nav nav-tabs" id="productTabs" role="tablist">

templates/single-product/up-sells.html.twig

@@ -18,7 +18,7 @@
     <section class="up-sells upsells products mt-5">
         {% set heading = heading|default(__('You may also like&hellip;')) %}
         {% if heading %}
-            <h2 class="h4 mb-4">{{ heading }}</h2>
+            <h2 class="h4 mb-4">{{ heading|raw }}</h2>
         {% endif %}
 
         {{ woocommerce_product_loop_start() }}

templates/wc-base.html.twig

@@ -24,7 +24,7 @@
     {% block notifications %}
         {% if notifications is defined and notifications|length > 0 %}
             {% for notification in notifications %}
-                <div class="alert alert-{{ notification.type|default('info') }} alert-dismissible fade show" role="alert">
+                <div class="alert alert-{{ notification.type|default('info')|esc_attr }} alert-dismissible fade show" role="alert">
                     {{ notification.message|wp_kses_post }}
                     <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="{{ __('Close') }}"></button>
                 </div>
@@ -34,7 +34,7 @@
         {% if flash_messages is defined %}
             {% for type, messages in flash_messages %}
                 {% for message in messages %}
-                    <div class="alert alert-{{ type }} alert-dismissible fade show" role="alert">
+                    <div class="alert alert-{{ type|esc_attr }} alert-dismissible fade show" role="alert">
                         {{ message|wp_kses_post }}
                         <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="{{ __('Close') }}"></button>
                     </div>

woocommerce/content-single-product.php

@@ -0,0 +1,46 @@
+<?php
+/**
+ * Single Product Content — PHP Bridge to Twig
+ *
+ * Bridge file that renders the Bootstrap 5 single product template
+ * (content-single-product.html.twig) via the parent theme's TwigService
+ * instead of WooCommerce's default flat layout.
+ *
+ * WooCommerce's wc_get_template_part('content', 'single-product') uses
+ * locate_template() which finds this file in the child theme before falling
+ * back to the plugin template. Unlike wc_get_template(), wc_get_template_part()
+ * does NOT fire the woocommerce_before_template_part / woocommerce_after_template_part
+ * hooks, so the TemplateOverride class cannot intercept it — this bridge file
+ * is needed.
+ *
+ * @package WcBootstrap
+ * @since 0.1.0
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+global $product;
+
+/**
+ * Hook: woocommerce_before_single_product.
+ *
+ * @hooked woocommerce_output_all_notices - 10
+ */
+do_action( 'woocommerce_before_single_product' );
+
+if ( post_password_required() ) {
+	echo get_the_password_form(); // WPCS: XSS ok.
+	return;
+}
+
+if ( class_exists( '\WPBootstrap\Twig\TwigService' ) ) {
+	$twig = \WPBootstrap\Twig\TwigService::getInstance();
+	echo $twig->render( 'content-single-product.html.twig', [
+		'product'       => $product,
+		'product_id'    => $product->get_id(),
+		'product_class' => implode( ' ', wc_get_product_class( '', $product ) ),
+	] );
+} else {
+	// Fallback: include WooCommerce's default template directly.
+	include WC()->plugin_path() . '/templates/content-single-product.php';
+}

woocommerce/single-product.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * Single Product Page (Bootstrap 5 Layout)
+ *
+ * Renders the WooCommerce single product content. This file is NOT included
+ * directly by WordPress. Instead, it is captured via output buffering by
+ * wc_bootstrap_render_single_product() and injected into the parent theme's
+ * page shell (pages/page.html.twig). Therefore it does NOT call
+ * get_header()/get_footer() or render the wrapper hooks.
+ *
+ * @package WcBootstrap
+ * @since 0.1.0
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Hook: woocommerce_before_main_content.
+ *
+ * @hooked woocommerce_output_content_wrapper - 10 (outputs opening divs for the content)
+ * @hooked woocommerce_breadcrumb - 20
+ */
+do_action( 'woocommerce_before_main_content' );
+
+while ( have_posts() ) {
+	the_post();
+	wc_get_template_part( 'content', 'single-product' );
+}
+
+/**
+ * Hook: woocommerce_after_main_content.
+ *
+ * @hooked woocommerce_output_content_wrapper_end - 10 (outputs closing divs for the content)
+ */
+do_action( 'woocommerce_after_main_content' );