=== 3D Product Customizer & Configurator for WooCommerce ===
Contributors: deosebitsoft, freemius
Tags:              woocommerce, 3d, product customizer, configurator, three.js
Requires at least: 6.0
Tested up to:      7.0
Requires PHP:      7.4
Stable tag:        3.6.6
License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

An interactive Three.js-powered 3D product configurator for WooCommerce — let customers customize materials, textures, and geometry in real time.

== Description ==

[DEMO](https://web-support.eu/showcase/?utm_source=wporg&utm_medium=plugin_listing&utm_campaign=demo)

Let customers build their perfect product in 3D — swap materials, hide parts, and share their design. Powered by Three.js, built for WooCommerce.

**Key features:**

* Real-time 3D model viewer powered by Three.js (WebGL)
* PBR (Physically Based Rendering) material support — base color, roughness, normal, AO, metalness, and displacement maps
* Per-step customization: define multiple configuration steps (e.g. Upper, Sole, Logo), each targeting specific model meshes
* Bulk material assignment in the admin
* Geometry visibility toggles — show or hide mesh groups per option
* Undo / redo history
* URL-based configuration sharing — customers can share their exact design via a link
* Download a PDF preview
* AR view on supported mobile devices
* HDR environment map for realistic lighting
* Background color switcher
* Customization data saved to the WooCommerce order as line-item meta
* Reusable texture library via a dedicated Custom Post Type


**Free vs Premium:**

The free version is fully functional for single-material customization. Premium unlocks advanced PBR workflows and productivity features for studios managing large product catalogs.

= Free =
* Upload & display a 3D model
* Base color texture or color picker per option
* Roughness & metalness sliders
* Customization steps
* Viewer Only Mode
* Camera, zoom & background settings
* HDR environment map
* Undo / redo, PDF, AR view
* Set custom icons (images) for every step / options of a step

= Premium (everything in Free, plus) =
* Material Preview
* Multiple textures per option
* Bulk Add Materials to a step
* Show / Hide mesh controls per option
* Normal, AO, metalness & displacement maps
* Reflection intensity & displacement scale
* Hotspots/Annotations

== Upgrade to Premium ==

1. Inside WordPress admin, go to **3D Customizer → Account** (added after activation).
2. Click **Upgrade to Premium** and complete the purchase on the checkout page.
3. Return to **3D Customizer → Account/Upgrade** and enter your license key to activate.
4. Then in the same page download and activate the Premium version.

Alternatively, click the **Upgrade to Premium** button that appears inside any locked premium feature panel.


== Source Code & Build Instructions ==

**All source code is human-readable and included in this plugin.**

The `/js/` folder contains the original, uncompiled JavaScript source files:

* `customizer.js` — Main 3D configurator frontend logic
* `model-scanner.js` — 3D model mesh detection and analysis
* `material-preview.js` — Material preview rendering
* `ui.js` — UI state management and interactions
* Admin scripts in `/admin/js/` — Dashboard-specific functionality

The `/dist/` folder contains pre-compiled, production-ready bundles. These are generated by bundling the source files with their dependencies (three.js, pdf-lib, lucide) using Webpack. **The `/dist/` folder is auto-generated output and not part of the source code.**

**Rebuilding from Source:**

This plugin uses Webpack to compile and minify JavaScript, bundling dependencies to keep the plugin size manageable (avoiding the need to distribute `node_modules`).

Requirements:

* Node.js (v14 or newer)
* npm (included with Node.js)

Build commands:
```
npm install              # Install dependencies from package.json
npm run dev             # Development build with watch mode (rebuilds on file changes)
npm run build           # Production build (minified and optimized)
```

**Dependencies:**

* **three.js** — WebGL 3D rendering library (licensed under MIT)
* **jspdf** — PDF generation for preview downloads (licensed under MIT)
* **lucide** — Icon library (licensed under MIT)
* **webpack** — Module bundler (licensed under MIT)

All original code is GPLv2 or later. Third-party dependencies follow their respective open-source licenses, listed in `package.json`.

== External Services ==

This plugin integrates with **Freemius** for license management, automatic updates, and premium feature delivery:

* **Service:** Freemius License Management
* **Server:** https://freemius.com
* **Purpose:** Validates premium licenses, manages plugin updates, delivers premium features, and provides usage analytics
* **Data Sent:** Plugin activation events, license key validation, and anonymized usage analytics
* **Account Required:** Optional — only if upgrading to Premium
* **Terms:** https://freemius.com/terms/

All other assets (JavaScript, CSS, images) are included locally within the plugin package. No other external services are used.

== Authors & Credits ==

**Development**: [deosebIT Soft](https://deosebitsoft.ro/)

This plugin was developed with attention to WordPress.org standards and is maintained by the deosebIT Soft team. For support, updates, and premium features, visit our website.

== Installation ==

1. Upload the `product-customizer` folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Ensure WooCommerce is installed and active.
4. Navigate to **Model Textures** in the WordPress admin and create texture entries. Each texture can include a base-color image (featured image) plus optional PBR maps and scalar material properties.
5. Open any WooCommerce product and locate the **3D Configurator** metabox.
6. Upload or select a `.glb` / `.gltf` model using the **Select Model** button.
7. Click **Scan Model** to auto-detect mesh names from the file.
8. Add one or more **Steps** and assign **Options** (textures or geometry toggles) to each step.
9. Save the product. The 3D configurator will now appear on the product's front-end page.
10. Visit **Model Textures → Global Settings** to configure camera position, zoom limits, background colors, and an optional HDR environment map.


== Frequently Asked Questions ==

= What 3D file formats are supported? =
GLB (binary GLTF) is the recommended format. GLTF (JSON-based) is also supported. The plugin registers these MIME types with WordPress so they can be uploaded through the standard Media Library.

= Can I use multiple HDR environment maps per product? =
The HDR environment map is a global setting. All products share the same HDR file. Per-product HDR support is planned for a future release.

= Why does the 3D viewer not appear on a product page? =
The configurator only renders when the product has a valid `.glb` model URL AND at least one configured step with at least one option. Check the **3D Configurator** metabox on the product.

= How is the customization saved to the order? =
When a customer clicks **Add to cart**, the current configuration is sent as a JSON payload. Each selected option (part → material name) is stored as a WooCommerce line-item meta entry and is visible on the order detail and in emails.

= Is this compatible with WooCommerce variable products? =
The plugin targets simple products. Variable product support is not officially tested.

= Are the bundled JavaScript files minified? =
Yes. The source files are included in the `js/` directory and the `webpack.config.js` build configuration is included in the plugin package.

== Screenshots ==

1. Front-end 3D configurator on a WooCommerce product page — rotate the model and switch materials in real time.
2. Product metabox in the WordPress admin — add steps, assign texture options, and target specific meshes.
3. Texture modal — browse the reusable texture library and assign materials to a step option.
4. Model Texture editor — upload base color and PBR maps (roughness, normal, AO, metalness), set roughness and metalness sliders.
5. Global Settings page — configure initial camera position, zoom range, background colors, and HDR environment map.

== Display Methods & Hooks ==

The 3D Customizer provides three flexible ways to display the customizer on your product pages:

**1. Automatic Display (Default)**
The customizer is automatically displayed before the product summary.

**Setting:** 3D Customizer → Global Settings → Display Method → "Automatic (before product summary)"

No code required — it just works!

**2. Block (Gutenberg)**

**Setting:** 3D Customizer → Global Settings → Display Method → "Manual Placement"
In FSE themes (Gutenberg) you can use the block `3D Product Customizer`

**3. Shortcode Display**
Display the customizer anywhere using the `[dprcu-customizer]` shortcode.

**Setting:** 3D Customizer → Global Settings → Display Method → "Manual Placement"

Usage:
```
[dprcu-customizer]               — uses the current product
[dprcu-customizer id="123"]      — uses a specific product ID
```

Perfect for custom layouts and page builders (Elementor, Divi, etc.)

**4. Manual Hook Display**
Display the customizer using the `dprcu_display_customizer` action hook.

**Setting:** 3D Customizer → Global Settings → Display Method → "Manual Hook"

Usage in your theme template:
```php
<?php do_action( 'dprcu_display_customizer' ); ?>          <!-- on a product page -->
<?php do_action( 'dprcu_display_customizer', 123 ); ?>     <!-- on any page with a specific product ID -->
```

**Developer Hooks**

The plugin provides 18+ action hooks for extending functionality. Common hooks include:

- `dprcu_before_customizer_output` — Before the customizer renders
- `dprcu_before_canvas_container` — Before the 3D canvas
- `dprcu_before_sidebar_container` — Before the sidebar
- `dprcu_display_customizer` — Manual display hook (see Display Methods above)

For the complete list of hooks, see the [Documentation](https://web-support.eu/documentation/#hooks)

== Changelog ==

= 3.6.6 =
Code quality

= 3.6.5 =
* Updated presentation site url in the codebase
* Added guard to manual placement setting
* Fixed support notice not staying dismissed

= 3.6.4 =
* Fixed `customizerData` already declared error on product pages when shortcode or FSE block is used
* Manual hook `dprcu_display_customizer` now accepts an optional product ID argument

= 3.6.3 =
* Added product ID attribute to shortcode — use `[dprcu-customizer id="123"]` on any page
* Added product search/select to the FSE block — pick any WooCommerce product from the sidebar
* Fixed FSE block not being clickable in the editor (added `useBlockProps`)

= 3.6.2 = 
* Fixed dismisable support notice
* Fixed encoding of special chars

= 3.6.1 = 
* Added docs / support notice to admin

= 3.6.0 =
* Replaced Lucide icon picker with WordPress media library for step and option icon selection
* Added per-option icon image field — each option can have its own icon shown in geometry swatches
* Option icon now takes priority over texture thumbnail/color in material swatches when set
* Cached icon images in IndexedDB to avoid re-fetching on every session load
* Fixed Bulk Add Options not working — added missing bulk modal HTML and #tmpl-option template
* UI refactor

= 3.5.10 =
* Fixed zoom keyboard shortcuts (+/-) ignoring admin-set zoom limits (minDistance/maxDistance)
* Fixed option selection forcing targeted meshes visible when no show/hide configured

= 3.5.9 =
* Added Demo, Docs, and Buy Premium links to the plugin row on the Plugins page
* Regenerated pot file
* Fixed position of the additional price input in the ajax response 

= 3.5.8 =
* Added per-option additional pricing — set a surcharge on any option within a step
* Live price display updates in real-time as the user selects different options
* Price badges shown on option swatches when a surcharge applies
* Option surcharge applied to cart total via WooCommerce before_calculate_totals
* Uses WooCommerce currency symbol and position settings

= 3.5.7 =
* Bug fixes and maintenance

= 3.5.6 =
* Renamed plugin to "3D Product Customizer & Configurator for WooCommerce" for better search visibility
* Updated plugin name references in watermarks, notices, and readme.txt
* Regenerated pot file
* Updated docs URL in the PDF

= 3.5.5 =
* Added 12 new i18n strings (adding, loading, PDF labels, alerts) — now translatable via `__()` in PHP
* Disabled OrbitControls damping for instant rotation stop on release
* Removed stale CSS selectors from metabox-styles.css
* Fixed deprecated `THREE.WebGLShadowMap` warning — switched to `PCFShadowMap`
* Increased shadow map resolution to 4096 and tightened shadow camera frustum for sharper ground shadows

= 3.5.4 =
* Added camera position/angle controls in admin 3D editor — save and reset the default camera view per product
* Fixed JSON corruption when saving camera position (`sanitize_text_field` no longer destroys JSON data)
* Front-end 3D viewer now applies the saved per-product camera position on load
* Fixed garbled character encoding in the help modal close button

= 3.5.3 =
* Fixed help modal rendering on mobile Safari — GPU compositing, dynamic viewport height, touch event handling
* Removed nested `position: fixed` on mobile modal to prevent layout issues

= 3.5.2 =
* Fixed all `_e()` output to use proper escaping functions (`esc_html_e`, `esc_attr_e`)
* Added ABSPATH guard to block render file
* Removed UTF-8 BOM from main plugin file
* Added nonce verification to review notice dismissal
* Added nonce compliance annotations to add-to-cart handler
* Fixed undefined variable warnings in PDF download and background toggle
* Normalized IndexedDB config key across URL variants
* Improved add-to-cart AJAX — applies WooCommerce fragments directly and fires proper events
* Use WooCommerce `wc_ajax_url` for add-to-cart requests (handles subdirectory installs)
* Replaced `filemtime()` fallback with `file_exists()` check to suppress PHP warnings
* Fixed extra `>` in checkbox HTML markup

= 3.5.1 =
* Switched PDF generation from pdf-lib to jsPDF for better clickable link support
* Renamed URL query parameter `cfg` to `dprcu_cfg` to avoid conflicts
* Cleaned `dprcu_cfg` parameter from the URL after configuration load
* Added multi-angle PDF captures with options summary page
* Added site logo, product name, timestamp, and URL to PDF output
* Added footer links (Plugin Page, Docs, Demo) to PDF pages
* Added option thumbnails and color swatches to the PDF options table
* Updated PDF column layout to full-width images proportional to canvas aspect ratio

= 3.5.0 =
* Fixed taxonomy slug in texture category filter dropdowns — categories now show up correctly in modals
* Fixed valid zero values (roughness 0.0, metalness 0.0, env intensity 0.0) being silently ignored on the frontend
* Fixed HTML validation: nonce field moved outside `<select>` element in admin texture filter
* Fixed duplicate `get_post_meta()` call in texture color swatch metabox
* Eliminated duplicate watermark rendering logic with a shared helper
* Added fallback version string for `filemtime()` to prevent PHP warnings when assets are missing
* Updated texture caching to correctly query the `dprcu_texture_category` taxonomy

= 3.4.8 =
Fixed the reset button
Fixed the position of the hotspots

= 3.4.7 = 
Saved current config in the IndexedDB

= 3.4.6 = 
Added indexDB cache for repeated loads
Added more debug to Android XR

= 3.4.5 = 
Added separate AR button with settings.

= 3.4.4 =
Improved Android AR View 

= 3.4.2 = 
Added FSE block to bypass content wrapping.

= 3.4.1 =
Improved asset caching

= 3.4.0 =
* Added three display methods (Automatic, Shortcode, Manual Hook) for flexible customizer placement
* Implemented 18+ WordPress action hooks for developer extensibility
* Fixed wpautop filter interfering with shortcode output
* Added Global Settings page with display method selection

= 3.3 = 
* Fixed premium notice css 
* Added auto framing to the customizer
* Updated admin model scanner layout


= 3.2 =
* Introduced Material preview metabox for Premium
* Introduced color picker for materials with only basic colors

= 3.0 =
* Introduced Free vs Premium tier via Freemius licensing.
* Premium: multiple textures per option (free tier limited to one per option).
* Premium: Bulk Add Materials button in the product metabox.
* Premium: Show/Hide mesh controls per customization option.
* Premium: full PBR map set — normal, AO, metalness, and displacement map uploads.
* Premium: reflection intensity and displacement scale sliders on texture entries.
* Added custom isometric cube icon in the WordPress admin sidebar.
* Added persistent upgrade prompts comparing free and premium features.
* Freemius account menu integrated into the 3D Customizer admin menu.

= 2.1 =
* Added glass/transmission material support.
* Added bulk material assignment in the product metabox.
* Added drag-to-reorder for steps and options.
* Added geometry visibility (show/hide meshes) per option.
* Improved undo/redo history system.
* Performance: texture list now cached with a transient.
* Security: fixed text domain inconsistency across all files.
* Security: attachment IDs now sanitized with absint() instead of sanitize_text_field().
* Security: ABSPATH guard moved to top of plugin-settings.php.
* Security: all HTML attribute echoes in settings render callbacks now escaped with esc_attr().

= 2.0 =
* Multi-texture options: assign multiple textures to a single option card.
* New step/option data structure with explicit target meshes.
* Added HDR environment map setting.
* Added URL-based configuration sharing.
* Added AR export with QR code.

= 1.0 =
* Initial release.

== Upgrade Notice ==

= 3.6.4 =
Fixed `customizerData` already declared conflict. Manual hook now accepts product ID.

= 3.6.3 =
Shortcode now accepts product ID for use on any page. FSE block includes product search.

= 3.6.2 =
Fixed dismisable support notice and fixed unescaped chars

= 3.6.1 =
Added docs/support notice to admin

= 3.6.0 =
Added the posibility to set img as icons for steps / options

= 3.5.10 =
Zoom keyboard shortcuts now respect admin-set zoom limits. Options no longer force targeted meshes visible unless show is explicitly configured.

= 3.5.9 =
Added Demo, Docs, and Buy Premium links to the plugin row on the Plugins page.

= 3.5.8 =
Added per-option pricing with live front-end display and cart surcharge.

= 3.5.7 =
Maintenance release with bug fixes.

= 3.5.6 =
Plugin renamed to "3D Product Customizer & Configurator for WooCommerce"

= 3.5.5 =
Added 12 new translatable strings for the front-end configurator, improved rotation feel, and higher-resolution ground shadows.

= 3.5.4 =
Added per-product camera position controls in the admin 3D editor, with improved JSON save handling.

= 3.5.3 =
Fixed help modal layout issues on mobile Safari.

= 3.5.2 =
Code quality and security improvements: escaping fixes, nonce verification, and cart reliability.

= 3.5.1 =
Updated PDF generation with jsPDF, multi-angle captures, options summary, and footer links.

= 3.5.0 =
Fixed texture category filters, frontend material property parsing with valid zero values, and several code quality improvements.

= 3.4.7 = 
Saved current config in the IndexedDB

= 3.4.6 = 
Added indexDB texture cache

= 3.4.5 =
Added separate AR button with settings.

= 3.4.4 = 
Improved Android AR View 

= 3.4 =
Introduced FSE block and material caching in the frontend

= 3.2 =
Introduces material preview (premium) and color picker for materials with only a basic color

= 3.0 =
Introduces the Free/Premium tier. Existing installs retain all previously available features. Premium features require a license key activated via 3D Customizer → Account/Upgrade.

= 2.1 =
Security and stability fixes. Update recommended for all users.