=== BSS 3D Product Viewer & AR for WooCommerce ===
Contributors: bssolnwp
Tags: woocommerce, 3d, ar, model-viewer, glb
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
WC requires at least: 8.0
WC tested up to: 10.9

Interactive 3D product viewer with AR support for WooCommerce. Upload GLB/GLTF models and let customers view products in their space.

== Description ==

Bring your WooCommerce products to life with an interactive 3D viewer and mobile AR. Upload GLB/GLTF models, configure camera, lighting, hotspots, dimensions, and material variants, then let customers spin and explore products on the product page or place them in their room with augmented reality.

**Features**

* Interactive 3D viewer on product pages, powered by Google's `<model-viewer>` web component
* Mobile AR via QR code (ARCore on Android, ARKit on iOS)
* GLB / GLTF model upload through the standard WordPress media library
* Fullscreen editor with tabs for Lighting, Camera, Materials, Animations, Hotspots, Camera Views, Dimensions, AR, Attribute Mapping, Best Practices, and Presentation
* Per-material color / metallic / roughness overrides
* Map WooCommerce product attributes (e.g. Color → Red) to material changes for instant variant previews
* Dimension overlay with cm / m / inches / feet units
* Signed, time-limited proxy URLs so the raw GLB attachment URL is never exposed
* Show the 3D viewer inside the WooCommerce product gallery (as the first image) or as a button that opens a pop-up — your choice
* `[bss3dv_viewer id="123"]` shortcode and a "BSS 3D Viewer" block to embed a model on any page or post
* Translation-ready, RTL-ready, HPOS-compatible, no external CDN runtime dependencies

**Privacy / Data**

This plugin does not call any external services at runtime. All assets (model-viewer, QR generator) are bundled locally.

**Bundled third-party libraries**

This plugin bundles two open-source libraries. Both are GPL-compatible and their unminified/source distributions are publicly available:

* Google &lt;model-viewer&gt; 4.0.0 (Apache-2.0) — source: https://github.com/google/model-viewer
* QR code generator (MIT) — source: https://github.com/davidshimjs/qrcodejs

== Installation ==

1. Upload the `bss-3d-viewer` folder to `/wp-content/plugins/`, or install the ZIP via *Plugins → Add New → Upload Plugin*.
2. Activate the plugin through the *Plugins* screen.
3. Make sure WooCommerce is installed and active.
4. Visit *WooCommerce → 3D Viewer* to configure global defaults.
5. Edit any product, switch to the *3D Model* tab, upload a `.glb` file, and configure.

== Frequently Asked Questions ==

= What 3D file formats are supported? =

GLB (binary glTF) and GLTF. GLB is recommended because it bundles geometry, materials, and textures into a single file.

= Where can I get GLB models from? =

You can scan real products with Polycam, Scaniverse, or KIRI Engine on a phone. Designers can export from Blender, Maya, 3ds Max, SketchUp, or any GLB-capable tool.

= Does AR work on iPhone and Android? =

Yes. The plugin uses standard `<model-viewer>` AR modes: WebXR and Scene Viewer on Android (ARCore), Quick Look on iOS (ARKit). On unsupported devices the customer sees the regular 3D viewer instead.

= Is the 3D model file protected from direct download? =

The plugin applies several layers to make casual download and reuse hard:

* Models are served only through a signed, short-lived proxy URL (HMAC token). The real `/wp-content/uploads/…glb` path is blocked from direct web access (an Apache `.htaccess` / IIS `web.config` rule is added automatically on activation).
* Cross-site hotlinking is blocked — the proxy only serves the model when the request comes from your own site.
* Right-click "save" and drag-save are disabled on the viewer.

Please note: any 3D model rendered in a browser must send its data to the visitor's device, so a determined user with developer tools can still capture it. This is friction against casual copying, not unbreakable DRM.

= I use Nginx — how do I block direct model downloads? =

The automatic `.htaccess` / `web.config` rules only apply to Apache and IIS. On Nginx, add this to your server block and reload:

`location ~* /wp-content/uploads/.*\.(glb|gltf)$ { deny all; }`

The plugin shows an admin notice with this snippet when it detects Nginx.

= Does it support HPOS (High-Performance Order Storage)? =

Yes. The plugin only touches product post meta and options, and declares HPOS compatibility.

= Does it support the new block-based product editor? =

Not in v1.0.0. The classic product data tab is supported. Block-editor support is planned for a future release.

= Can I show the 3D viewer inside the product gallery instead of a button? =

Yes. Go to *WooCommerce → 3D Viewer → Display Mode* and choose "Product gallery" — the model becomes the first gallery image and the "View in 3D" button is hidden. This uses the standard WooCommerce gallery; some themes or page builders that replace the gallery may not support it, in which case use Modal mode or the shortcode/block instead.

= Can I embed a 3D model on any page or post? =

Yes. Use the shortcode `[bss3dv_viewer id="123"]` (the product ID is shown in the product's 3D editor, on the *Output* tab), or add the "BSS 3D Viewer" block and enter the product ID. Both accept `width`, `height`, and `ar` options, e.g. `[bss3dv_viewer id="123" width="100%" height="480px" ar="yes"]`.

= The model sometimes fails to load on a heavily cached page. Why? =

For protection, each model URL is signed with a token that expires after a few minutes. If a full-page cache serves very old HTML, the token can be expired. Exclude single product pages (and any page using the shortcode/block) from full-page caching, or keep the cache lifetime short.

== Screenshots ==

1. The "View in 3D" and "View in Your Room" buttons on a product page.
2. The interactive 3D viewer modal, showing real-world product dimensions.
3. Mobile AR via a scannable QR code, with a copy-link fallback.
4. The admin settings — display mode, accent color, per-field tooltips, and a Custom CSS tab.
5. The product editor's "3D Model" tab — upload a GLB and open the editor.
6. The fullscreen 3D editor — lighting, camera, materials, hotspots, dimensions, and AR.

== Changelog ==

= 1.0.0 =
* Initial public release.

== Upgrade Notice ==

= 1.0.0 =
First public release.
