=== Models3D Studio for WooCommerce ===
Contributors: alkadristudio
Donate link: https://studio.medhatalkadri.com/
Tags: 3d-viewer, woocommerce-3d, glb-viewer, 3d-product, product-configurator
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
WC requires at least: 7.0
WC tested up to: 9.3
Stable tag: 1.1.21
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

A self-hosted, high-fidelity PBR 3D product configuration suite tailored for WooCommerce.

== Description ==

Models3D Studio brings high-fidelity interactive 3D product visualization, real-time variation mapping, and PBR material inspection directly into the WooCommerce store workflow.

Allow your customers to rotate, zoom, inspect, and configure products in photorealistic 3D before buying. Models3D Studio seamlessly connects WooCommerce variation attributes (colors, materials, finishes, and components) to 3D meshes in your GLB models, updating visuals instantly in the browser without server lag.

= Live Demo (Pro Edition) =

* **Storefront Product Page (Pro Demo):** https://models3d-demo.medhatalkadri.com/product/forged-performance-wheel-assembly/
* **3D Visual Studio Admin Sandbox (Pro Demo):** https://models3d-demo.medhatalkadri.com/wp-admin/admin.php?page=models3d-advanced-config&product_id=101 *(Showcases the Pro edition with all features unlocked — click "Free vs Pro" in the top header to compare Free and Pro features).*

= Key Features =

* **Photorealistic 3D Canvas**: Real-time WebGL rendering powered by Three.js and React Three Fiber with full PBR (Physically Based Rendering) material support.
* **Bi-Directional WooCommerce Variation Sync**: Instantly connects WooCommerce attribute swatches and select dropdowns to 3D meshes, textures, and material finishes.
* **Interactive 3D Visual Studio**: Dedicated full-screen admin editor to inspect GLB/glTF hierarchy, test lighting environments, configure camera angles, and bind product variations.
* **Dual-Channel Customization**: Independent controls for material properties (roughness, metalness, colors) in the Free edition, plus per-variation part visibility overrides (`Hide` / `Show` mesh layers) in the Pro edition.
* **Native 2D Fallback Protection**: Graceful degradation to standard WooCommerce product images if WebGL is unavailable or when JavaScript is disabled.
* **Zero External Rendering Fees**: 100% self-hosted client-side execution. No SaaS subscription or third-party cloud rendering required.
* **Universal Builder & Theme Compatibility**: Works smoothly with standard WooCommerce themes, Block themes (FSE), and major page builders.

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/models3d-studio-for-woocommerce` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Navigate to **WooCommerce -> 3D Studio** to configure global viewer display preferences.
4. Edit any WooCommerce product, open the **3D Studio** tab in the Product Data box, and upload your `.glb` model.
5. Launch the **3D Visual Studio** to map your WooCommerce attributes to 3D meshes and materials.

== Frequently Asked Questions ==

= Does this require an external rendering service or monthly subscription? =
No. All 3D rendering happens locally inside the customer's web browser using standard WebGL via Three.js. There are zero external rendering charges or ongoing cloud service requirements for the core viewer.

= Which 3D file formats are supported? =
Models3D Studio supports standard `.glb` and `.gltf` binary formats, including Google Draco compression and KHR material extensions.

= How do variable products work with 3D models? =
You upload a single multi-part or multi-variant GLB file. In the 3D Visual Studio, you connect each WooCommerce attribute (e.g. Color, Finish, Component) to specific mesh parts or materials. When customers pick variations on the product page, the 3D model automatically updates in real time.

= What happens if a customer visits with an older browser or device without WebGL? =
Models3D Studio includes an automated fail-safe fallback system. If WebGL is unsupported or encounters an error, the plugin automatically restores the standard 2D WooCommerce product gallery image.

= Where can I find documentation and tutorials? =
Full offline documentation is bundled inside the plugin under **WooCommerce -> 3D Studio -> Documentation**. You can also visit our online portal at https://studio.medhatalkadri.com/

== Screenshots ==

1. 3D Visual Studio editor with real-time PBR material inspection and viewport controls.
2. Storefront interactive 3D product viewer integrated with WooCommerce variations.
3. Dual-channel variation mapping for material properties and target mesh layers.
4. PBR material customization with metalness, roughness, and color swatches.
5. Scene lighting, HDR environment presets, and camera positioning controls.

== External services ==

This plugin connects to the following external services:

1. Freemius API (https://api.freemius.com)
* Service Used: Freemius SDK (https://freemius.com)
* Purpose: Optional user opt-in telemetry, account synchronization, and software license verification.
* Data Sent: Site URL, active theme name, WordPress and PHP versions, and administrator email (transmitted strictly upon explicit user opt-in or during license activation).
* Terms of Service: https://freemius.com/terms/
* Privacy Policy: https://freemius.com/privacy/

2. Drei HDRI Environment Repository (https://raw.githack.com/pmndrs/drei-assets/)
* Service Used: pmndrs/drei-assets via raw.githack.com (GitHub CDN)
* Purpose: Provides high dynamic range (HDR) radiance environment lighting maps for realistic 3D PBR material reflections when the user selects a preset studio or outdoor environment in the 3D Visual Studio editor.
* Data Sent: None. Only public read-only static .hdr radiance map assets are downloaded via HTTPS GET when a preset is chosen.
* Terms of Service: https://raw.githack.com/
* Privacy Policy: https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement

== Changelog ==

= 1.1.21 =
* Fix: Updated cross-attribute visibility rule evaluation order in `ModelViewer.jsx` (`show` Pass 1 followed by `hide` Pass 2 and ancestor shielding) so explicit `hide` overrides take precedence when other active attributes specify default `show` lists.
* Fix (Pro): Preserved Channel 1 target mesh selections when adding or removing Channel 2 `Hide` tags and exposed active variation switching (`_m3dsSetActiveVariation`) across scopes in `admin-init.js` for immediate 3D viewport preview.
* Documentation: Added Live Pro Demo links (`Storefront Product Page` and `3D Visual Studio Admin Sandbox`) and clarified Free vs Pro dual-channel customization capabilities in `readme.txt`.

= 1.1.20 =
* Fix: Replaced legacy inverse-square decay spotlights (`decay = 2` at distance 17.32) in `ModelViewer.jsx` with a scale-independent 3-Point Directional Studio Lighting Rig (`StudioLightingRig`), `ACESFilmicToneMapping`, and deeper ground contact shadows (`opacity = 0.85`) so 3D models are evenly illuminated and grounded regardless of bounding-box scale or HDR preset orientation.
* Enhancement: Added interactive "Light Angle (Azimuth)" (`0°–360°`) control to the Visual Editor in both Free and Pro editions (`admin-init.js`, `ModelViewer.jsx`).
* Enhancement (Pro): Added full Studio Lighting & HDR Suite controls in the Visual Editor: "Light Sources & Studio Rig" selector (`3_point`, `2_light`, `1_light`, `front_showcase`, `top_softbox`, and orbit-synced `headlamp`), "Light Elevation (Height)" (`10°–85°`), "HDR Reflection Rotation" (`0°–360°`), and "Tone Mapping Exposure" (`0.2x–3.0x`).
* Fix: Prevented duplicate `.glb` re-fetch and WebGL context reset during color picker and roughness/metalness slider drags (`AdminDashboardController.php`, `GalleryArchitect.php`, `AdminDashboard.jsx`, `admin-init.js`).
* Fix: Resolved Channel 2 part visibility search input binding and filtered WooCommerce Blocks script prefetch bursts on 3D product pages (`admin-init.js`, `GalleryArchitect.php`).

= 1.1.19 =
* Enhancement: Added de-branded 11-layer Forged Performance Wheel starter 3D model (`assets/models/forged-performance-wheel.glb`) with switchable spoke (`5-Spoke Twin` / `10-Spoke Competition`) and hub (`5-Lug OEM` / `GT3 Center-Lock`) geometry.
* Enhancement: Added a dedicated "View Product" / "Preview Product" header button and save-toast shortcut inside the 3D Visual Editor (`AdminDashboardController.php`, `admin-studio.css`).
* Enhancement: Added a 1-click "Auto-Enable Storefront Variation Dropdowns" helper in the Visual Editor for Simple or unpriced Variable products, plus automatic save-and-redirect when clicking "Launch Visual Editor" after uploading a `.glb` on the product edit screen (`AdminDashboardController.php`, `MetaBoxController.php`, `admin-init.js`).
* Fix: Refined cross-attribute visibility and material layering in `ModelViewer.jsx` so part-switching attributes (`visibility_rules.hide`) cleanly hide mesh layers targeted by shared finish attributes (`material_property`).
* Fix: Added a metabox dirty-state guard (`_models3d_metabox_dirty`) in `MetaBoxController.php` so saving an untouched product edit tab never overwrites newer 3D configurations saved in the Visual Editor.
* Demo: Added dedicated WordPress Playground blueprint preset (`demo/blueprint-wheel.json`) alongside the default sneaker demo (`demo/blueprint.json`).

= 1.1.18 =
* Fix: Eradicated "solid black model" FOUC and WebGL material override race condition.
* Fix: Purged upstream Drei ContactShadows VRAM memory leak during scale updates.
* Enhancement: Injected dynamic version string into the Visual Editor footer.

= 1.1.17 =
* Performance: Deployed intelligent WebWorker texture crunching. Files exceeding 3MB will now have their embedded lossless PNG/JPG textures automatically crushed into highly-optimized WebP directly inside the browser before uploading.
* Security: Implemented a hybrid file size safety net (15MB absolute PHP ceiling to prevent OOM timeouts) paired with dynamic JS UI warnings.

= 1.1.16 =
* UX: Streamlined WordPress admin update notification presentation according to directory standards.

= 1.1.15 =
* CI/CD: Automated native Freemius Pro deployment pipeline via official Freemius PHP SDK.
* Documentation: Enhanced WordPress.org Plugin Directory metadata, FAQ coverage, and screenshots guide.
* Build: Hardened physical code-splitting build transformations and clean packaging discipline.

= 1.1.14 =
* Compliance (WordPress.org Guideline 5 - Physical Code Splitting): Automated build transformations to completely strip inactive commercial layout code from the Free edition plugin files.

= 1.1.13 =
* Fix: Removed HTML markup from translation functions in models3d-studio.php to comply with WordPress i18n standards.

= 1.1.12 =
* Compliance (WordPress.org Guideline 8 - Enqueue Discipline): Refactored inline styles and scripts across PHP controllers to standard WordPress enqueue APIs.
* Compliance (WordPress.org Guideline 5 - Trialware Elimination): Removed developer JSON editor and custom rotation speed controls from Free edition DOM, replacing them with educational previews.
* Compliance (WordPress.org Guideline 8 - Local Dependencies): Bundled Google Draco WASM decoders locally in /assets/draco/ and eradicated remote CDN dependencies.
* Compliance (WordPress.org Guideline 6 - External Services Disclosure): Added full external services disclosures for pmndrs/drei-assets and Freemius.
* Compliance (WordPress.org Guideline 9 - Non-Destructive Protection): Ensured clean, non-destructive coexistence with companion extensions.

= 1.1.11 =
* Release Architecture: Bifurcated automated packaging pipelines for WordPress.org repository and Freemius distribution.
* Security: Sanitized cookie extraction and hardened query parameter validation across admin controllers.

= 1.1.0 =
* Initial WordPress.org repository release.

== Upgrade Notice ==

= 1.1.0 =
Initial release.

== Copyright and License Credits ==

* Three.js: MIT License, Copyright (c) 2010-2024 Three.js Authors, https://threejs.org
* Google Draco 3D Library: Apache License 2.0, Copyright Google Inc., https://github.com/google/draco
* React and React-DOM: MIT License, Copyright (c) Meta Platforms, Inc., https://react.dev
* React Three Fiber (@react-three/fiber): MIT License, Copyright (c) 2019 Paul Henschel, https://github.com/pmndrs/react-three-fiber
* React Three Drei (@react-three/drei): MIT License, Copyright (c) 2020 Paul Henschel, https://github.com/pmndrs/drei
* Inter Font: SIL Open Font License 1.1, Copyright (c) 2016-2020 Rasmus Andersson, https://rsms.me/inter/
* Freemius WordPress SDK: GPLv3 License, Copyright Freemius, Inc., https://freemius.com
* glTF-Transform (@gltf-transform/*): MIT License, Copyright (c) Don McCurdy, https://gltf-transform.dev
* meshoptimizer: MIT License, Copyright (c) Arseny Kapoulkine, https://github.com/zeux/meshoptimizer
* Bundled Starter 3D Models (High-Performance Sports Car, Sneaker, Sunglasses): Created and optimized locally by Alkadri Studio for Models3D Studio for WooCommerce, licensed under GPLv2 or later.
* Bundled Forged Performance Wheel 3D Model (`assets/models/forged-performance-wheel.glb`): Adapted and de-branded from "Lamborghini Murciélago Wheels" by César Vonc (https://sketchfab.com/3d-models/lamborghini-murcielago-wheels-61aefb66ec9541e09eecd2ce6b001f73), licensed under Creative Commons Attribution 4.0 International (CC BY 4.0, https://creativecommons.org/licenses/by/4.0/).
