dev: extend tests

Author: Soare Robert-Daniel

AGENTS.md

@@ -59,15 +59,15 @@ You can read more about it on `./ARCHITECTURE.md`, but here’s a high-level ove
 
 `woocommerce-product-addon.php` — defines constants, loads Composer autoload, manually `require_once`s all class/include files (no PSR-4 autoloading for plugin code), then hooks `PPOM()` on `woocommerce_init`.
 
-### Core Classes (all singleton pattern via `get_instance()`)
+### Core Classes
 
 | Class | File | Role |
 |---|---|---|
 | `NM_PersonalizedProduct` | `classes/plugin.class.php` | Main plugin — registers all WooCommerce hooks, loads input types |
-| `NM_PersonalizedProduct_Admin` | `classes/admin.class.php` | Admin-only — loaded only in `is_admin()` |
-| `PPOM_Meta` | `classes/ppom.class.php` | Field group CRUD against custom DB table |
+| `NM_PersonalizedProduct_Admin` | `classes/admin.class.php` | Admin-only coordinator for menus, settings, attach flows, and admin AJAX |
+| `PPOM_Meta` | `classes/ppom.class.php` | Product-side field-group resolver that reads attached groups and loads settings/fields from the custom DB table |
 | `PPOM_Form` | `classes/form.class.php` | Frontend form rendering |
-| `PPOM_Fields_Meta` | `classes/fields.class.php` | Field type registry and metadata |
+| `PPOM_Fields_Meta` | `classes/fields.class.php` | Admin field-builder UI, modals, and builder asset loading |
 | `PPOM_Inputs` | `classes/input.class.php` | Input type manager |
 
 ### Input Type System

architecture.md

@@ -64,11 +64,13 @@ The plugin is not PSR-4 for its runtime code. The main file manually includes th
 | --- | --- | --- |
 | Bootstrap | [`woocommerce-product-addon.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/woocommerce-product-addon.php) | Defines constants, loads the plugin, registers top-level hooks |
 | Main runtime | [`classes/plugin.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/plugin.class.php) | Registers WooCommerce hooks for rendering, validation, pricing, cart, orders, admin AJAX, cron, and loop behavior |
-| Product field resolver | [`classes/ppom.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/ppom.class.php) | Resolves applicable PPOM field groups for a product and loads settings and fields from the custom DB table |
+| Product field resolver | [`classes/ppom.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/ppom.class.php) | Resolves applicable PPOM field groups for a product, merges their fields, and derives the runtime settings row from the custom DB table |
 | Frontend form renderer | [`classes/form.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/form.class.php) | Renders modern template-based product fields and hidden runtime state |
 | Input registry | [`classes/input.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/input.class.php) | Loads input-type classes and add-on input classes |
 | Admin field UI | [`classes/fields.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/fields.class.php) | Powers the field-group builder UI and admin-side assets |
+| Admin coordinator | [`classes/admin.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/admin.class.php) | Registers PPOM admin menus, settings integration, attach flows, and admin initialization hooks |
 | Frontend asset loader | [`classes/frontend-scripts.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/frontend-scripts.class.php) | Registers and localizes frontend JS and CSS for pricing, uploads, validation, conditions, and field widgets |
+| Script registry | [`classes/scripts.class.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/classes/scripts.class.php) | Shared wrapper for registering, enqueuing, localizing, and inlining PPOM frontend assets |
 | WooCommerce flow functions | [`inc/woocommerce.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/inc/woocommerce.php) | Product-page rendering, validation, cart item payloads, order item metadata, file finalization |
 | Pricing engine | [`inc/prices.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/inc/prices.php) | Server-side option pricing, matrix pricing, cart fee calculation, line-item price updates |
 | Upload subsystem | [`inc/files.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/inc/files.php) | AJAX upload and delete handlers, thumbnails, cropped files, confirmed-file storage, cleanup cron |
@@ -88,7 +90,7 @@ Each row contains both group-level settings and the full field definition payloa
 - `productmeta_style`
 - `productmeta_js`
 - `productmeta_categories`
-- `productmeta_tags`
+- `productmeta_tags` when extensions or add-ons use tag-aware assignment
 - `the_meta` as JSON
 
 Products are linked to PPOM groups through the normal post meta key:
@@ -97,14 +99,14 @@ Products are linked to PPOM groups through the normal post meta key:
 
 That value may contain one or more field-group IDs.
 
-`PPOM_Meta` is the resolution layer. For a given product, it:
+`PPOM_Meta` is the read-side resolution layer. For a given product, it:
 
 1. reads `_product_meta_id`
 2. checks category-linked groups
 3. merges or overrides group IDs through filters
 4. loads the matching row or rows from the custom table
-5. decodes `the_meta` into the active field list
-6. exposes group settings such as inline CSS, inline JS, price-display mode, and group title
+5. merges field definitions from all matched groups
+6. derives one active settings row for runtime values such as inline CSS, inline JS, price-display mode, and group title
 
 ```mermaid
 flowchart TD
@@ -116,8 +118,8 @@ flowchart TD
     E --> F["Apply merge / override filters"]
     F --> G["Load rows from {prefix}_nm_personalized"]
     G --> H["Decode the_meta JSON"]
-    H --> I["Active PPOM fields"]
-    H --> J["Group settings"]
+    H --> I["Merged active PPOM fields"]
+    H --> J["Derived runtime settings row"]
     I --> K["Frontend rendering"]
     I --> L["Validation and pricing lookup"]
     J --> M["Inline CSS / JS / display mode"]
@@ -220,7 +222,7 @@ The modern path renders:
 
 - the active field groups
 - a price-table container
-- hidden inputs for group IDs, current product ID, option-price state, conditional-hide state, and cart-edit state
+- hidden inputs and wrapper state through `PPOM_Form::form_contents()`
 
 That hidden form state is what keeps the frontend JS and backend PHP in sync.
 
@@ -361,12 +363,14 @@ The admin side has two main responsibilities:
 - field-group CRUD
 - settings and permissions
 
-Field-group management is provided by `NM_PersonalizedProduct_Admin`, `PPOM_Fields_Meta`, and the AJAX CRUD handlers in [`inc/admin.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/inc/admin.php). That layer lets admins:
+Field-group management is split across `NM_PersonalizedProduct_Admin`, `PPOM_Fields_Meta`, and the AJAX CRUD handlers in [`inc/admin.php`](/Users/robert/Desktop/sites/plugins-dev/web/app/plugins/woocommerce-product-addon/inc/admin.php):
 
 - create, edit, clone, and delete field groups
 - bulk-attach field groups to products
 - choose which group is attached on the product edit screen
 
+`PPOM_Meta` is not the CRUD layer. It resolves product-side field groups and reads their settings/fields at runtime.
+
 Settings use two storage models:
 
 - legacy WooCommerce settings-tab storage
@@ -435,7 +439,7 @@ The API supports:
 - updating order PPOM metadata
 - deleting order PPOM metadata
 
-The important implementation detail is that the routes use open permission callbacks, but write operations validate a PPOM secret key inside the handler. That makes the API optional and configuration-gated, but still part of the plugin's public integration surface.
+The important implementation detail is that the routes use open permission callbacks, while write operations validate a PPOM secret key inside the handler. That makes the API optional and configuration-gated, but still part of the plugin's public integration surface.
 
 ## Extension and Compatibility Model
 
@@ -473,7 +477,7 @@ PPOM stores data in several WordPress and WooCommerce persistence layers.
 ### Custom database table
 
 - `{prefix}_nm_personalized`
-  Stores PPOM field-group definitions and group-level settings such as `productmeta_name`, `dynamic_price_display`, `productmeta_style`, `productmeta_js`, category/tag assignment, and `the_meta` JSON.
+  Stores PPOM field-group definitions and group-level settings such as `productmeta_name`, `dynamic_price_display`, `productmeta_style`, `productmeta_js`, category assignment, optional tag data for extensions/add-ons, and `the_meta` JSON.
 
 ### WordPress post meta
 

classes/admin.class.php

@@ -16,7 +16,7 @@
 }
 
 /**
- * Coordinates the PPOM admin UI and field-group attachment workflows.
+ * Coordinates the PPOM admin UI, settings flows, and field-group attachment workflows.
  *
  * Registers the PPOM menu pages, AJAX attach handlers, legacy WooCommerce
  * settings tab, and admin initialization hooks that prepare the PPOM schema.

classes/form.class.php

@@ -17,33 +17,31 @@
  */
 class PPOM_Form {
 
-	private static $ins = null;
-
 	/**
-	 * Return all ppom attach meta data
+	 * Resolved PPOM metadata for the current product render.
 	 *
-	 * @var array
+	 * @var PPOM_Meta
 	 */
 	public static $ppom;
 
 	/**
-	 * Return the product ID
+	 * Current product ID.
 	 *
-	 * @var number
+	 * @var int
 	 */
 	public $product_id;
 
 	/**
-	 * Return wc product object
+	 * Current WooCommerce product object.
 	 *
-	 * @var object
+	 * @var WC_Product
 	 */
 	public $product;
 
 	/**
-	 * Return templates args
+	 * Rendering arguments passed to the form template.
 	 *
-	 * @var array
+	 * @var array|null
 	 */
 	public static $args;
 
@@ -58,14 +56,6 @@ function __construct( $product, $args ) {
 		self::$args = $args;
 	}
 
-	public static function get_instance() {
-
-		// create a new object if it doesn't exist.
-		is_null( self::$ins ) && self::$ins = new self();
-
-		return self::$ins;
-	}
-
 	/**
 	 * PPOM main wrapper 2 classes
 	 *

classes/input.class.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Loads PPOM input classes and frontend asset dependencies.
+ * Loads PPOM input classes and optional add-on input classes.
  *
  * @package PPOM
  * @subpackage Inputs
@@ -9,7 +9,7 @@
  */
 
 /**
- * Loads PPOM input classes and their script registrations.
+ * Loads PPOM input classes and related add-on integrations.
  */
 class PPOM_Inputs {
 

classes/ppom.class.php

@@ -7,7 +7,7 @@
  */
 
 /**
- * Resolves product-level PPOM metadata.
+ * Resolves product-level PPOM metadata for frontend and cart/order flows.
  *
  * @since version 15.0
  */
@@ -18,23 +18,26 @@ class PPOM_Meta {
 	public static $product_id;
 
 	/**
-	 * Plugin category data.
+	 * Resolved category-based PPOM group IDs for the current product.
 	 *
 	 * @var array $category_meta
 	 */
 	public $category_meta = array();
 
 	/**
-	 * Plugin category array.
+	 * Candidate group rows that include category or tag assignments.
+	 *
+	 * Tags are fetched here as stored data, but core resolution matches
+	 * categories directly and leaves tag-based behavior to extension filters.
 	 *
 	 * @var array $ppom_categories_and_tags_row
 	 */
 	public $ppom_categories_and_tags_row = array();
 
 	/**
-	 * Plugin settings.
+	 * Runtime settings row selected from the resolved PPOM groups.
 	 *
-	 * @var array $ppom_settings
+	 * @var object|array $ppom_settings
 	 */
 	public $ppom_settings = array();