=== 3D Product Customizer ===
Contributors: deosebitsoft, freemius
Tags:              woocommerce, 3d, product customizer, configurator, three.js
Requires at least: 6.0
Tested up to:      6.9
Requires PHP:      7.4
Stable tag:        3.4.3
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/customizer/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

= 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)
* **pdf-lib** — PDF generation for preview downloads (licensed under Apache 2.0)
* **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. Shortcode Display**
Display the customizer anywhere using the `[dprcu-customizer]` shortcode.

**Setting:** 3D Customizer → Global Settings → Display Method → "Shortcode Only"

Usage:
```
[dprcu-customizer]
```

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

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

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

Usage in your theme template:
```php
<?php do_action( 'dprcu_display_customizer' ); ?>
```

**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/customizer/documentation/#hooks)

== Changelog ==

= 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.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.
