# Asuka Product Designer

Complete WordPress and WooCommerce user guide for version 1.0.

This manual is written for store owners and administrators who have never used
a product configurator. It also contains the operational and technical details
needed by catalog managers, production teams, support staff, and integrators.

## How to Use This Guide

If this is your first installation, follow **Part I** in order. Do not begin
with pricing rules, custom portals, or 3D optimization before the first simple
product can be saved, reloaded, and ordered successfully.

When troubleshooting:

1. Record the product, view, browser, and exact action.
2. Open **Asuka Designer > QA & Diagnostics**.
3. Save the report before changing configuration.
4. Use the focused troubleshooting section in Part VI.
5. Change one thing at a time and repeat the same test.

## Contents

### Part I: First Successful Product

1. Requirements
2. Installation and activation
3. Licensing
4. Essential concepts
5. Administration map
6. First-product walkthrough

### Part II: Shared Catalog and Product Building

7. Designs and shapes
8. Fonts and typography
9. Colors and printing methods
10. Product configurations
11. Two-dimensional views
12. Three-dimensional views
13. Elements and variations
14. Drawing areas and markers

### Part III: Customer Experience

15. Product templates
16. Module reference
17. Layout zones, contextual tools, and portals
18. Client permissions
19. Validation guards and physical measurements

### Part IV: Pricing, Commerce, and Production

20. Pricing engine
21. Pricing Rules add-on
22. WooCommerce product binding
23. Cart and checkout
24. Orders, saved designs, and production

### Part V: Administration and Advanced Integration

25. Settings
26. External providers and AI
27. Import, export, and migration
28. Translations
29. Gutenberg and shortcode
30. Themes, portals, and advanced embedding
31. Licensing and premium add-ons

### Part VI: Operations

32. QA and diagnostics
33. Troubleshooting
34. Updates and rollback
35. Production launch checklist
36. Support report checklist
37. Private backend demos with WordPress Multisite
38. Newsletter studio
39. Production readiness and deployment

---

# Part I: First Successful Product

## 1. Requirements

### Required

- WordPress 6.6 or newer.
- PHP 8.1 or newer.
- A modern browser.
- Administrator access to WordPress.
- Permission to upload media.

### Required for Commerce

- WooCommerce 8.3 or newer.
- A configured cart and checkout.
- A test payment method for pre-production verification.

### Required for 3D

- A browser and device with WebGL2.
- A valid GLB file.
- A web server that accepts the GLB MIME type and file size.

### Required for Premium Modules

- An active AsukaDesigner license.
- A domain or site slot authorized by that license.
- Access from WordPress to the licensing API.
- The matching add-on JavaScript file in the deployed plugin.

### Recommended for Production

- HTTPS.
- A staging site.
- Database and media backups.
- Error logging that is not publicly visible.
- A tested rollback copy of the previous plugin ZIP.

## 2. Installation and Activation

1. Open **WordPress > Plugins > Add New > Upload Plugin**.
2. Choose the official `asuka-product-designer-1.0.0.zip`.
3. Click **Install Now**.
4. Activate **Asuka Product Designer**.
5. Open **Asuka Designer > Overview**.

### What Success Looks Like

- The Asuka Designer menu is visible.
- Overview loads without a PHP fatal error.
- The plugin version and bundled AsukaDesigner version are displayed.
- WooCommerce is reported as available when it is active.
- The launch checklist is visible.

### Common Installation Mistakes

- Uploading a folder instead of the original ZIP.
- Uploading a ZIP that contains another ZIP.
- Copying development folders such as `node_modules`.
- Using an old browser cache after replacing runtime bundles.
- Updating the plugin on production before testing the same archive on staging.

## 3. Licensing

Open **Asuka Designer > Settings > Licensing and Asuka API**.

1. Keep **Enable commercial license runtime** enabled.
2. Paste the license key.
3. Check that the informational **Commercial API** value is
   `https://api.asukadev.com`. It cannot be edited.
4. Save. The licensed domain is resolved by the server and cannot be edited by
   the customer.
5. Confirm the status is **Connected**.
6. Confirm the expected plan and add-on count.

### Security Model

The raw key remains on the WordPress server. The customer browser receives a
short-lived signed runtime token. That token contains:

- the product and plan;
- enabled features;
- limits and current usage;
- licensed domain;
- expiration;
- activation identity.

The browser does not receive the stored license key.

### Premium Availability Rule

A premium module is usable only when all applicable conditions are true:

1. Commercial licensing is enabled.
2. The license API accepts the key and domain.
3. The signed token grants the required feature.
4. The matching add-on file exists.
5. Product permissions allow the action.
6. The assigned template exposes the module.
7. Any required provider credential is configured.

Query parameters such as demo switches do not grant premium features.

### Domain Override

Leave the field empty to use the WordPress host. Use an override only when a
local or development hostname must intentionally match a domain stored on the
license.

Do not use a production customer domain as a casual local override. Site slots
and activations should be managed through the licensing service.

## 4. Essential Concepts

### Product Configuration

The complete rules and initial visual state for one customization experience.
It contains views, product elements, variations, drawing areas, markers,
permissions, validation, template assignment, pricing, and saved renderer
state.

### WooCommerce Product

The sellable catalog record containing title, price, stock, tax, shipping, and
checkout behavior. It is connected to an Asuka configuration through product
binding.

### Product Template

A reusable customer workspace. It controls which modules appear, where their
buttons live, where panels open, and which page portals are used.

### View

One product representation. A view may be:

- 2D, using Fabric and a product image;
- 3D, using Babylon.js and a GLB scene.

### Product Element

A configurable part of the product itself, such as Body, Handle, Sole, Label,
or Material.

### Variation

An allowed state of one product element, such as White, Blue, Leather, Large,
or Hidden.

### Layer

Customer content such as text, image, reusable design, or shape.

### Drawing Area

A permitted region for customer content. It may also provide the physical
measurement reference for dimensions, area, and DPI.

### Marker

A fixed insertion or replacement slot. It is not a drawing-area boundary.

### Portal

The HTML destination where a module panel or persistent module is mounted.

## 5. Administration Map

## Overview

Use Overview as the operational starting point.

- **Store status** summarizes license, WooCommerce, configurations, and
  production.
- **Launch checklist** shows the next incomplete setup action.
- **Runtime status** shows license runtime, domain, plan, and add-ons.
- **Recent configurations** opens work in progress.
- **Quick access** opens assets, commerce, settings, diagnostics, and tools.

## Products

Use Products to create and edit:

- product configurations;
- reusable product templates.

The Product configuration editor includes:

- Product builder;
- Template assignment;
- Client permissions;
- Validation guards;
- Catalog filters;
- Pricing rules;
- Config audit;
- View pagination.

## Assets

The Assets hub opens:

- Design library;
- Font library;
- Colors and printing;
- Shape library;
- Product templates.

## Commerce

The Commerce hub opens:

- WooCommerce products;
- Production orders;
- Saved customer designs;
- Pricing rules, when licensed.

## Documentation

The Documentation center contains:

- a recommended learning path;
- searchable task-based guides in read-only mode;
- the public documentation;
- this bundled technical guide;
- links to Settings and QA & Diagnostics.

The distributable plugin never registers an editable documentation content
type. Customer administrators can read the help center and open the official
guides, but they cannot alter AsukaDesigner documentation from their site.

The vendor website owns the editorial content separately. On that site only,
the Asuka Studio theme registers a top-level **Documentation** workspace for
site administrators. It uses the normal WordPress block editor, revisions,
drafts, previews, featured images, sections, ordering, and search keywords.
The public `/documentation/` page contains `[asuka_documentation_hub]`, and
individual guide URLs use `/documentation/guide-slug/`.

This separation is intentional: product configuration belongs to the plugin;
official product documentation belongs to the Asuka website. Demo child sites
and customer installations never run the editorial migration.

## Settings

Settings contains:

- runtime defaults;
- admin appearance and feature flags;
- licensing and API;
- external providers;
- data retention.

## Focused Workspaces

These screens are opened from the hubs rather than kept in the main sidebar:

- individual design, font, color, printing method, shape, and pricing-rule
  editors;
- Designer Studio;
- Production;
- Tools;
- Translations;
- QA & Diagnostics.

## 6. First-Product Walkthrough

Use a simple 2D product for the first complete test.

### Step 1: Prepare Shared Assets

Open **Asuka Designer > Assets**.

1. Add one system font.
2. Add one printing method.
3. Add two compatible colors.
4. Optionally add one reusable design.

### Step 2: Create the Configuration

1. Open **Products > Add Product Config**.
2. Enter an internal title.
3. Keep the configuration in Draft.
4. Create one 2D view.
5. Select a product image.
6. Add one drawing area.
7. Save.
8. Reload the WordPress edit screen.

The view must still be present after reload.

### Step 3: Configure the Customer Experience

1. Select a Product template or keep the initial layout.
2. Enable Text, Images, Layers, Colors, and History.
3. Allow the required client permissions.
4. Restrict catalogs to the assets prepared for the product.
5. Configure validation guards.

### Step 4: Publish and Bind

1. Publish the configuration.
2. Open a WooCommerce product.
3. Select the configuration in the Asuka Designer panel.
4. Choose a display mode.
5. Update the WooCommerce product.

### Step 5: Test as a Customer

Use a private browser window.

1. Open the product page.
2. Add text.
3. Change its font and color.
4. Upload an image.
5. Move and scale objects near drawing-area edges.
6. Undo and redo.
7. Add to cart.
8. Refresh the cart.
9. Change quantity.
10. Complete checkout.

### Step 6: Verify Production

Open **Asuka Designer > Commerce > Production**.

Confirm:

- the customized order line exists;
- the preview is visible;
- configuration and saved-design references exist;
- price data is present;
- production status can be changed;
- the production pack can be generated or downloaded.

---

# Part II: Shared Catalog and Product Building

## 7. Designs and Shapes

## Design Library

Open **Assets > Design library**.

A design entry contains:

- stable ID;
- public label;
- category;
- optional extra price;
- asset URL;
- description;
- visibility.

### Recommended Procedure

1. Optimize the source file.
2. Upload it to the WordPress media library.
3. Create the design entry.
4. Use a clear public label.
5. Organize it with a consistent category.
6. Keep it hidden while testing.
7. Expose it in a test product Catalog filter.
8. Test insertion, selection, scaling, pricing, and deletion.
9. Enable visibility.

## Shape Library

Open **Assets > Shape library**.

Supported shape entries include:

- SVG shape;
- rectangle preset;
- circle preset.

Shape fields include:

- ID and label;
- category;
- viewBox;
- default fill;
- default stroke;
- optional extra price;
- source URL or SVG path;
- visibility.

### SVG Safety

Do not disable sanitization to make an unsafe SVG work. Remove:

- scripts;
- executable event attributes;
- unsafe external references;
- unsupported embedded content.

### Catalog Maintenance

- Hide an asset before deleting it.
- Duplicate an entry to create a close variant.
- Export before bulk edits.
- Keep production files required by historical orders.
- Use Product configuration Catalog filters to expose only appropriate entries.

## 8. Fonts and Typography

Open **Assets > Font library > Add font**.

## Google Fonts

1. Add a Google Fonts API key in Settings.
2. Choose **Google Fonts**.
3. Search the live catalog.
4. Select a result from autocomplete.
5. Choose only the required weights.
6. Choose normal and italic styles when supported.
7. Review the live preview.
8. Set public label, ID, category, and visibility.
9. Save.

The raw Google catalog is not exposed to customers. Saved font entries are.

## System Fonts

Choose a cross-platform preset. Presets use fallback stacks, for example:

- system UI;
- Arial/Helvetica;
- Verdana;
- Georgia;
- Times New Roman;
- Courier New;
- Impact.

A system font may render differently when the first family is not installed.
Use a webfont when exact brand appearance is required.

## Custom Fonts

### Direct File

1. Choose **Own font**.
2. Choose **Direct font file**.
3. Enter the exact CSS family name.
4. Upload WOFF2, WOFF, TTF, or OTF.
5. Confirm format, weight, and style.
6. Save one coherent entry for the variant.

WOFF2 is preferred for modern browsers.

### Stylesheet

Use a stylesheet when it already contains `@font-face`.

1. Enter the stylesheet URL.
2. Enter the exact family name declared by CSS.
3. Verify the stylesheet and font files return HTTP 200.
4. Verify cross-origin rules when hosted on another domain.

### Runtime Checklist

If a font is missing:

1. Confirm the font entry is enabled.
2. Confirm the product Catalog filter includes it.
3. Confirm Text and Font family modules are placed in the template.
4. Confirm permissions allow adding text and changing font family.
5. Confirm the file, CSS, or Google request succeeds.
6. Confirm family, weight, and style match.
7. Create and select a text object.
8. Test both the creation form and selected-text Font family tool.

## 9. Colors and Printing Methods

Create printing methods before colors when possible.

## Printing Method

Fields include:

- public label;
- stable ID;
- category;
- extra price;
- description;
- compatible color IDs;
- visibility.

Examples:

- Direct to garment;
- Screen printing;
- Embroidery;
- Sublimation;
- Vinyl.

## Color

Fields include:

- color type and display value;
- public label;
- stable ID;
- group;
- extra price;
- compatible printing methods;
- default status;
- visibility.

## Compatibility

Compatibility is bidirectional:

- saving a method updates its color palette;
- saving a color updates its available methods.

A color extra price applies only when it is compatible with the method used by
the layer.

### Testing

1. Change printing method.
2. Confirm the available palette changes.
3. Select a color.
4. Confirm the price breakdown.
5. Switch views.
6. Add to cart.
7. Compare the server pricing snapshot.
8. Inspect the order production data.

## 10. Product Configurations

A configuration contains:

- mode, theme, and layout;
- modules and permissions;
- views and drawing zones;
- fonts, colors, and upload behavior;
- pricing rules;
- selection menu and UI behavior;
- desktop and mobile behavior;
- initial document and state.

## Product Builder

Use the builder to create:

- views;
- product elements;
- variations;
- drawing areas;
- markers;
- initial customer layers;
- renderer-specific state;
- cameras and 3D mappings.

## Template Assignment

A template controls the storefront workspace. It does not replace product
geometry, views, elements, or initial artwork.

## Client Permissions

Permissions answer whether an action is allowed. Module placement answers how a
customer reaches the action.

Both must be correct.

## Validation Guards

Use guards for:

- required content;
- required views;
- drawing-area containment;
- real size limits;
- minimum image DPI;
- allowed colors and methods;
- product-specific restrictions.

## Catalog Filters

Use filters to select the subset of global:

- designs;
- fonts;
- colors;
- printing methods;
- shapes.

## Pricing Rules

Attach reusable rules in a deliberate order. Test combinations, especially
percentage adjustments.

## Config Audit

Resolve:

- invalid JSON;
- missing IDs;
- broken references;
- unavailable templates;
- contradictory runtime data.

## Save and Reload Rule

Every authoring session should finish with:

1. Save.
2. Wait for WordPress.
3. Reload.
4. Confirm view count.
5. Confirm active view and initial product state.
6. Confirm side meta boxes.
7. Test undo and redo.

Do not publish when the builder returns to **No views yet** after reload.

## 11. Two-Dimensional Views

2D views use Fabric.

### Create a View

1. Create a stable ID such as `front`.
2. Set a customer-facing label.
3. Select the product image.
4. Set a canvas ratio matching the image.
5. Fit the product without distortion.
6. Choose initial zoom.

### Canvas Coordinates

The canvas is a logical coordinate space. Responsive display size may change
without changing stored object coordinates.

Do not infer centimeters from CSS pixels.

### Drawing Areas

Create an area over the printable region. Give it:

- stable ID;
- label;
- boundary;
- containment behavior;
- physical width and height;
- unit.

### Physical Measurement

Layer measurement may return:

- native width and height in canvas coordinates;
- relative width and height as percentages;
- physical width, height, and area in real units.

This enables:

- dimensions in Transform;
- area-based pricing;
- maximum-size validation;
- DPI warnings;
- exact production metadata;
- stable real size when responsive canvas size changes.

### Initial History

History should start after the product image, elements, and configured initial
layers load. Undo must return to the loaded product, not an empty canvas.

### 2D Test Matrix

- Text creation and editing.
- Font family, formatting, and curve.
- Upload, provider image, design, and shape.
- Move, scale, rotate, duplicate, delete.
- Lock, hide, and reorder.
- Drawing-area edges.
- Undo and redo.
- View and variation synchronization.
- Mobile and desktop.
- Save/reload and checkout.

## 12. Three-Dimensional Views

3D views use Babylon.js and GLB.

## GLB Preparation

Before export:

- apply model transforms;
- use consistent scale;
- center the product;
- use readable mesh and material names;
- remove hidden geometry;
- remove unused materials;
- reduce oversized textures;
- merge meshes that do not need independent behavior;
- keep meshes separate when they need independent selection, material,
  variation, or drawing-area behavior;
- export normals and UVs.

## Create the 3D View

1. Upload or select the GLB.
2. Wait for Babylon and the model to finish loading.
3. Confirm the view reports ready.
4. Check camera controls.
5. Save before detailed mapping.

Do not add 3D content while the renderer reports that the add-on is not loaded.

## Mesh Mapping

Map each configurable mesh set to a logical product element.

Test:

- clicking a mesh opens its element;
- changing its variation changes only that element;
- selecting another mesh updates the Variations module immediately;
- selection does not jump back after applying a variation.

## Materials

Material variations may change:

- color;
- texture;
- visibility;
- supported material properties.

Use stable variation IDs shared with related 2D and 3D views.

## Camera

Save:

- one root camera for the full scene;
- focused cameras for important parts when automatic framing is insufficient.

For a single product, prefer camera rotation over moving the product. For a
scene containing multiple products, move the camera target only enough to frame
the selected element.

Returning to a variation root should return the camera to the product center.

## Surface Placement

Customer artwork must follow:

- the clicked surface point;
- local surface tangent;
- local surface normal;
- selected mesh or drawn surface area;
- correct front-face orientation.

It must not remain aligned to the camera plane.

## Occlusion

Artwork attached to one mesh must:

- remain clipped to that mesh or area;
- be hidden by parts in front of it;
- not appear on unrelated meshes;
- not appear through the opposite side of the product.

## 3D Test Matrix

Test:

- front, side, rear, and oblique cameras;
- near and far zoom;
- insertion and live drag;
- pointer release;
- mesh boundaries;
- text and asymmetric images;
- rotation and mirroring;
- occlusion from every angle;
- multiple drawing areas;
- save/reload;
- long sessions and repeated view changes.

## 13. Elements and Variations

## Correct Model

- Element = real product part.
- Variation = allowed state of that part.
- Layer = customer content.

Do not create an element for every color. Create one element with color
variations.

## Stable IDs

Use IDs such as:

- `body`;
- `handle`;
- `white`;
- `blue`;
- `front`;
- `back`.

Reuse the same IDs across views when the state must synchronize.

## Selection Behavior

1. Click element A.
2. Confirm variations for A open.
3. Apply two variations.
4. Click element B without returning to root.
5. Confirm variations for B replace the previous group.
6. Apply a variation.
7. Confirm selection remains on B.

## Cross-View Synchronization

1. Change one variation.
2. Switch through every related view.
3. Confirm the new state is already active.
4. Save and reload.
5. Confirm pricing counts the logical choice once.

## 14. Drawing Areas and Markers

## Drawing Areas

A drawing area:

- constrains one or more layers;
- can be selected during object insertion;
- can be shown when an attached layer is selected;
- can provide physical measurement;
- can be rectangular in 2D;
- can be a mesh or drawn surface region in 3D.

### Several Areas

When several areas exist:

1. Show clear labels.
2. Ask which area receives the layer.
3. Store the area ID on the layer.
4. Show the attached area when the layer is selected.
5. Enforce boundaries during live drag.

## Markers

A marker:

- is centered on the click;
- can define an insertion or replacement slot;
- can accept configured replacement types;
- inherits the correct area and surface orientation.

Test markers with readable text and an asymmetric image.

## Authoring Permissions

Customers normally need:

- view drawing areas;
- view markers.

Customers normally do not need:

- create drawing areas;
- edit drawing areas;
- delete drawing areas;
- create markers;
- edit markers;
- delete markers.

---

# Part III: Customer Experience

## 15. Product Templates

Open **Assets > Product templates**.

Templates control:

- mode;
- theme;
- layout zones;
- modules;
- permissions;
- selection menu;
- UI behavior;
- desktop behavior;
- mobile behavior;
- portal destinations.

Create templates by purpose, for example:

- Simple apparel customer;
- Advanced 3D customer;
- Mobile kiosk;
- Administrator authoring;
- Minimal upload-only product.

## 16. Module Reference

## Creation and Editing

### Views

Switches product views.

### Designs

Opens the global reusable design catalog.

### Text

Creates text with approved fonts.

### Images

Provides upload, configured providers, QR code, and licensed AI workflows.

### Shapes

Opens reusable shape presets and SVG assets.

### Layers

Selects, reorders, locks, hides, and inspects customer objects.

### Elements

Browses reusable product elements.

### Variations

Selects variations for the active product element in 2D and 3D.

### Element Editor

Advanced element and variation authoring.

### Drawing Areas

Creates or uses printable regions. Premium entitlement may be required.

### Marker

Creates or uses fixed replacement slots. Premium entitlement may be required.

### Colors

Opens the compatible product palette.

### Studio

Applies image and SVG effects. Requires the Studio add-on and entitlement.

## 3D Product Tools

### Product Parameters

Edits configured 3D product dimensions and parameters.

### Materials

Inspects and edits exposed 3D materials.

### Camera

Controls and saves the active 3D camera.

## Utilities and Output

### Zoom

Controls view zoom.

### Download

Exports current view, all views, selected objects, drawing zones, or supported
state according to permissions and license.

### Magnifier

Provides focused visual inspection.

### Ruler

Provides measurement tools.

### History

Shows undo and redo history.

### State

Provides state tools for supported workflows.

### Pricing

Shows pricing context and breakdown. Requires its licensed add-on when
configured as premium.

### Pricing Rules

Edits conditional rules. Premium.

### GLB Optimizer

Prepares and optimizes GLB files. Premium.

### License

Shows runtime license, quotas, and activation information. Normally used for
administration or support.

## Contextual Tools

### Font Family

Available for selected text.

### Text Formatting

Controls text style, alignment, spacing, and supported typography properties.

### Text Curve

Controls curved text.

### Transform

Controls object dimensions, position, rotation, and related properties.

## Image Shortcuts

- Upload image.
- QR code.
- AI image, licensed and server-configured.
- Pixabay, licensed and configured.
- Pexels, licensed and configured.
- Facebook, licensed and configured.

## 17. Layout Zones, Contextual Tools, and Portals

## Placement Types

An enabled module may appear in:

- Layout navigation.
- Selection menu.
- Embedded page content.

A module may use Layout navigation and Selection menu together.

An enabled but unplaced module remains available to custom API calls but has no
customer-facing entry point.

## Zones

- Top.
- Left.
- Right.
- Bottom.

Zone behavior:

- Default.
- Panels.
- Inline.

Each zone may start collapsed and may allow customer collapse.

## Open As

- Floating.
- Popover.
- Panel.
- Modal.
- Inline.
- Drawer.
- Overlay.

Use compact modes for frequent actions and larger modes for complex workflows.

## Portal Modes

### Inside the Designer

The plugin manages the host.

### Shared Page Portal

Several modules share one configured selector.

### Document Body

The module mounts under the page body.

### Custom CSS Selector

The module mounts in a theme or page-builder host.

Example:

```html
<div id="asuka-product-tools"></div>
```

Use `#asuka-product-tools` as the selector.

## Delayed Portals

WooCommerce blocks and page builders may render hosts after initial page load.
The plugin observes the page and mounts when the selector appears.

Test:

- hard reload;
- mobile layout;
- product variation change;
- AJAX fragment update;
- repeated open and close;
- duplicate mount prevention.

## 18. Client Permissions

Permission groups include:

### General Objects

- add;
- select;
- move;
- scale;
- rotate;
- duplicate;
- delete;
- lock;
- hide;
- reorder.

### Layers

- open Layers;
- reorder;
- lock;
- hide;
- select.

### Designs

- view;
- add.

### Images

- open Images;
- upload;
- use remote images;
- use external libraries;
- use configured provider integrations.

### Text

- edit text;
- change font family;
- edit formatting;
- edit curve.

### Colors and Studio

- use colors;
- edit supported colors;
- use Studio;
- apply Studio effects.

### Output

- download;
- current view;
- all views;
- objects;
- drawing zones;
- export/import JSON.

### Drawing Areas and Markers

Separate permissions exist for view, create, edit, and delete.

### Pricing and Elements

Separate permissions exist for view and administrative editing.

### Rule of Thumb

Customers should receive the minimum capabilities needed to complete the
product. Product-authoring capabilities should remain disabled.

## 19. Validation Guards and Physical Measurements

## Containment

Choose whether:

- the full object must remain inside;
- the object center must remain inside;
- the object may cross configured edges.

## Real Size

Calibrate the product or drawing area before using:

- centimeters;
- millimeters;
- inches;
- physical area;
- physical pricing thresholds.

## Effective DPI

Effective DPI depends on source pixel dimensions and printed physical size.

A high-resolution source may become insufficient when enlarged.

Use:

- warning thresholds for recoverable quality concerns;
- blocking thresholds for unacceptable production quality.

## Customer Messages

Messages should explain:

- what is wrong;
- which object is affected;
- which limit applies;
- how the customer can correct it.

---

# Part IV: Pricing, Commerce, and Production

## 20. Pricing Engine

The core pricing engine works for 2D and 3D state.

Possible inputs include:

- base product price;
- layer count;
- object type;
- text length;
- text line count;
- used color count;
- object scale;
- object width and height;
- physical area;
- canvas size;
- view;
- product element;
- variation;
- material;
- printing method;
- quantity;
- catalog asset extras.

The server validates the final price at cart and checkout.

## 21. Pricing Rules Add-on

The visual Pricing Rules editor is premium.

## Handlers

- Layers amount.
- Text length.
- Text lines.
- Used colors amount.
- Scale.
- Layer size.
- Canvas size.

## Scope

- Whole document.
- Current view.
- First matching layer.

## Match

- All conditions.
- Any condition.

## Presets

- Threshold to fixed amount.
- Threshold to percentage.
- Every N units to fixed amount.
- Every N units to percentage.
- Advanced JSON.

## Threshold Operators

- greater than or equal;
- greater than;
- less than or equal;
- less than;
- exactly equal.

## Size Axis

- main value;
- width;
- height.

## Test Boundary Values

For every threshold, test:

- just below;
- exactly equal;
- just above.

Also test:

- several rules together;
- quantity changes;
- cart refresh;
- coupon and tax behavior;
- 2D and equivalent 3D dimensions.

## 22. WooCommerce Product Binding

Open a WooCommerce product and locate the Asuka Designer panel.

1. Select the published configuration.
2. Choose a display mode.
3. Update the product.
4. Open the public page.

## Simple Products

Use one configuration for the product.

## Variable Products

Use a parent configuration by default. Add variation-level overrides only when
the variation requires a different structure.

Test changing product variations before and after opening the designer.

## Theme Fallback

The plugin can provide a fallback when the theme omits standard WooCommerce
gallery hooks.

Always test the actual production theme because:

- hooks may be removed;
- blocks may render late;
- page builders may replace DOM nodes;
- responsive templates may use different containers.

## 23. Cart and Checkout

A customized cart line should preserve:

- WooCommerce product and variation;
- configuration reference;
- serialized design state;
- preview;
- selected options;
- validated price snapshot;
- production metadata.

## Test Procedure

1. Create a valid design.
2. Add to cart.
3. Refresh.
4. Change quantity.
5. Navigate away and return.
6. Complete classic checkout when supported.
7. Complete Blocks checkout when used.
8. Open the resulting order.

## 24. Orders, Saved Designs, and Production

## Saved Customer Designs

Saved designs may include controlled resume access. Treat resume tokens as
private credentials.

## Order Data

The customized line item should preserve:

- configuration;
- design;
- preview;
- pricing;
- dimensions;
- production choices;
- internal production status.

## Production Workspace

Open **Commerce > Production**.

For each item:

1. Inspect preview.
2. Check dimensions and DPI.
3. Check colors and printing method.
4. Check element and variation choices.
5. Check price.
6. Add internal notes.
7. Set production status.
8. Download the production pack.
9. Inspect every output before manufacture.

Keep internal production status separate from the customer-facing WooCommerce
order status when the business process requires it.

---

# Part V: Administration and Advanced Integration

## 25. Settings

## Runtime Defaults

### Default Designer Height

Used when a mount does not specify a height.

### Default Mode

- Standalone.
- Customer.
- Admin.

### Maximum Upload Size

This plugin limit cannot exceed:

- PHP `upload_max_filesize`;
- PHP `post_max_size`;
- web-server or proxy limits;
- WordPress media limits.

## Experience and Feature Flags

### Admin Theme

- Midnight.
- Light.
- Violet.

### Gutenberg Integration

Registers the Asuka Designer block.

### WooCommerce Product Bindings

Enables product binding workflows.

## Licensing and API

Configure:

- commercial runtime;
- license key;
- the fixed Asuka commercial API status;
- the server-resolved licensed domain status.

## External Providers

Configure:

- Pixabay;
- Pexels;
- Unsplash where supported;
- Google Fonts;
- Facebook.

## Data Retention

By default:

- deactivation keeps data;
- uninstall keeps data.

Permanent deletion must be explicitly enabled. Historical WooCommerce order
metadata remains preserved.

## 26. External Providers and AI

## Image Providers

A provider appears only when the applicable setup is complete:

- credential;
- license entitlement when required;
- module placement;
- permission;
- successful runtime configuration.

## AI Image Generation

The API server must configure a provider. A license feature alone is not a
provider configuration.

If the server returns `ai_provider_not_configured`, configure the AI provider
endpoint or supported server-side API key.

## Background Removal

Background removal is also server-backed. Check:

- API hostname;
- DNS;
- HTTPS;
- provider configuration;
- entitlement;
- quota;
- response format.

Never expose provider secrets in customer JavaScript.

## 27. Import, Export, and Migration

Open **Asuka Designer > Tools**.

## Export

1. Select a configuration.
2. Export the package.
3. Store version and environment notes.
4. Back up related media separately.

## Import

1. Use matching plugin versions.
2. Import on staging.
3. Review referenced assets.
4. Replace environment-specific URLs.
5. Reconnect templates and WooCommerce products.
6. Save/reload each configuration.
7. Run diagnostics.
8. Place a test order.

Do not include license keys or provider secrets in reusable packages.

## 28. Translations

Open **Asuka Designer > Translations**.

The page has two independent catalogs that share the same locale list:

- **JavaScript designer** contains every public label used by the 2D and 3D
  canvas, modules, contextual tools and messages;
- **WordPress plugin** contains the administration, storefront and WooCommerce
  strings discovered from the plugin PHP source.

The source English text is immutable. Enter only the strings that need an
override for the selected locale.

## Create and Complete a Locale

1. Enter a locale code such as `fr_FR` and a readable label.
2. Click **Create locale**.
3. Open **JavaScript designer**, search by key or namespace and complete the
   required values.
4. Save the designer translations.
5. Open **WordPress plugin**, search by text or area and complete the host
   strings.
6. Save the plugin translations.
7. Change the WordPress site or user language and verify both the administration
   and a customizable product page.

The visible-row counter confirms the current search result. Filtering the table
does not remove translations that are currently hidden.

## Automatic Locale Selection

The plugin uses the locale selected by WordPress. For `fr_FR`, resolution is:

1. exact `fr_FR` database overrides;
2. shared `fr` overrides when available;
3. the normal WordPress gettext result for plugin strings;
4. built-in English.

The resolved JavaScript dictionary is passed to every designer instance, in the
administration and storefront, including Fabric and Babylon views.

## Loco Translate and Language Packs

The WordPress catalog does not replace gettext. Database overrides run first;
an empty field deliberately falls back to WordPress language packs, `.po`/`.mo`
files and tools such as Loco Translate. This makes it possible to use Loco for a
distributable translation and the Asuka page for store-specific wording.

## Import, Export and Migration

Use **Export JSON** before deployment, migration or a large batch edit. The
designer importer accepts a flat dotted-key object, a nested runtime dictionary
or a previously exported payload. The WordPress importer accepts its exported
key/value payload. Imports update only known catalog keys.

Deleting a locale removes its saved overrides from both catalogs; it never
deletes WordPress language files.

## 29. Gutenberg and Shortcode

## Gutenberg

Insert the **Asuka Designer** block and set:

- product configuration ID;
- mode;
- height.

## Shortcode

```text
[asuka_designer id="123" mode="standalone" height="720px"]
```

Supported attributes:

- `id`;
- `product_id`;
- `variation_id`;
- `config`;
- `mode`;
- `height`;
- `class`;
- `resume_design_id`;
- `resume_token`.

Use WooCommerce product binding for normal product pages.

## 30. Themes, Portals, and Advanced Embedding

## Dedicated Portal

Add a stable container:

```html
<div class="product-customizer-tools" data-asuka-tools></div>
```

Use:

```css
[data-asuka-tools]
```

as the template portal selector.

## Avoid Duplicate Mounts

Do not combine:

- WooCommerce binding;
- shortcode;
- Gutenberg block;

for the same visible designer.

For multiple designers:

- use unique hosts;
- use unique portals;
- destroy instances when removed;
- test event and memory cleanup.

## Renderer Code Splitting

The distribution separates:

- main runtime;
- Fabric renderer;
- Babylon renderer;
- premium add-ons.

A 2D-only workflow should not load Babylon. A 3D-only workflow should not load
Fabric until a 2D view is opened. Mixed products load the active renderer first.

## 31. Licensing and Premium Add-ons

Premium add-ons are separate files, for example:

- drawing areas;
- marker;
- Studio;
- pricing;
- pricing rules;
- model optimizer.

The menu should not be usable when:

- the feature is not licensed;
- the file is missing;
- a required provider is not configured.

Removing a menu entry is an interface improvement, not the security boundary.
Server operations must still validate license, domain, quotas, and request
authorization.

---

# Part VI: Operations

## 32. QA and Diagnostics

Run diagnostics:

- after installation;
- after licensing changes;
- after migration;
- after plugin or WooCommerce updates;
- before launch;
- before requesting support.

Diagnostics should cover:

- runtime assets;
- license and domain;
- product configurations;
- shared catalogs;
- product binding;
- WooCommerce compatibility;
- cart and checkout integration;
- production data.

## 33. Troubleshooting

## Designer Missing

- Publish the configuration.
- Confirm binding.
- Check the mount.
- Check Console and Network.
- Test a default theme.
- Clear all caches.

## Premium Module Missing

- Confirm Connected.
- Confirm domain.
- Confirm entitlement.
- Confirm add-on file.
- Confirm permission.
- Confirm template placement.
- Confirm provider credential.

## Views Missing After Save

- Check admin notices.
- Wait for save completion.
- Reload immediately.
- Confirm the latest state payload was posted.
- Check custom integration for obsolete direct Fabric/Babylon calls.
- Test a new configuration.

## Renderer Not Loaded

- Confirm active view type.
- Wait for view-ready.
- Check renderer bundle.
- Check GLB.
- Check WebGL2 and GPU errors.

## Font Missing

- Enable font.
- Include it in Catalog filters.
- Expose Text and Font family.
- Enable permissions.
- Check API/file/CSS request.
- Check CORS and MIME.
- Check family, weight, style.

## Provider Missing

- Save credential.
- Start a fresh session.
- Confirm entitlement.
- Confirm module placement.
- Check network response.

## Upload Fails

- Compare all size limits.
- Check extension and real MIME.
- Check media permissions.
- Check GLB validity.
- Keep SVG sanitization enabled.

## Blink or Selection Drop

- Check whether the theme replaces the mount node.
- Check overlays that intercept pointer events.
- Confirm one designer instance.
- Disable unrelated optimization during isolation.
- Record video and errors.

## 34. Updates and Rollback

Before updating:

1. Back up database and uploads.
2. Export important configurations.
3. Store the current plugin ZIP.
4. Install the new ZIP on staging.
5. Test 2D, 3D, mixed views, mobile, cart, checkout, and production.
6. Verify versions.
7. Deploy the exact tested archive.

Rollback:

1. Restore the previous plugin files.
2. Restore the database only when the update changed incompatible data.
3. Clear caches.
4. Rerun diagnostics.
5. Retest one complete order.

## 35. Production Launch Checklist

- Requirements verified.
- HTTPS enabled.
- Official commercial API reachable at `https://api.asukadev.com`.
- License connected.
- Domain and site slot verified.
- Premium files match sold features.
- No localhost endpoint in production.
- Shared assets curated.
- Product configurations save and reload.
- Initial history state is correct.
- 2D tested.
- 3D tested when used.
- Mixed views tested when used.
- Mobile tested.
- Drawing-area containment tested.
- Physical measurements tested.
- DPI validation tested.
- Pricing boundary values tested.
- WooCommerce binding tested.
- Cart refresh tested.
- Checkout tested.
- Order data tested.
- Production pack inspected.
- Upload limits and MIME tested.
- Providers tested.
- Translation fallback tested.
- Caches tested.
- Backup and rollback tested.
- Legal and third-party notices available.

## 36. Support Report Checklist

Include:

- plugin version;
- bundled AsukaDesigner version;
- WordPress version;
- PHP version;
- WooCommerce version;
- browser and operating system;
- configuration ID;
- WooCommerce product ID;
- active theme and page builder;
- exact steps;
- expected result;
- actual result;
- QA & Diagnostics output;
- Console errors;
- failed Network requests;
- screenshot or short video;
- result with a default theme;
- result with cache and optimization disabled.

Never include:

- raw license keys;
- provider secrets;
- passwords;
- unrestricted resume tokens;
- private customer data not required for diagnosis.

## 37. Private Backend Demos with WordPress Multisite

The private backend demo feature lets a prospect request a temporary WordPress
workspace from a public form. After email verification, the plugin creates an
isolated child site, a restricted user, sample AsukaDesigner content, and a
24-hour session.

This feature is intended for a vendor-operated demonstration network. Do not
enable it on an ordinary customer store.

### What the Customer Receives

The customer receives one verification email containing a single-use link.
Opening it:

1. validates the request and its expiry;
2. reserves capacity atomically;
3. creates a new Multisite child site;
4. creates a unique temporary user;
5. assigns the restricted `apd_demo_manager` role;
6. installs the built-in minimal demo catalog, template, and product configuration;
7. creates and binds a sample WooCommerce product;
8. signs the customer in and opens **Asuka Designer > Overview**.

The authentication cookie remains available across browser restarts, but the
site and account stop working when the demo expires.

The verification email may already belong to a WordPress account. The demo
never reuses that account or its privileges: it creates a separate temporary
identity with an internal non-deliverable address and binds it only to the new
workspace.

### Requirements

- WordPress Multisite must be enabled.
- Asuka Product Designer must be network activated.
- WooCommerce must be installed when the storefront workflow is demonstrated.
- The plugin's bundled **Asuka Demo Workspace** theme must be present. It is
  registered and activated automatically; it does not need to be installed or
  enabled separately in Network Admin.
- WordPress cron or a real server cron must run regularly.
- A working transactional mail transport is required in production.
- HTTPS is required in production.
- The network must have enough database, disk, and PHP capacity for the chosen
  number of concurrent demos.

Subdirectory networks work without wildcard DNS. Subdomain networks additionally
require wildcard DNS and a wildcard TLS certificate.

### Prepare Multisite Safely

Before converting an existing WordPress installation:

1. Back up the complete database.
2. Back up `wp-config.php` and `.htaccess`.
3. Disable caches during the conversion.
4. Enable Multisite with the official WordPress network setup.
5. Confirm that the main site still loads.
6. Confirm that a manually created child site loads.
7. Network activate Asuka Product Designer.
8. Create one test demo and confirm that its public landing page uses the
   dedicated **Asuka Demo Workspace** interface.

Never convert a production store without first testing the exact conversion on
a staging copy.

### Enable the Demo Service

On the Asuka operator network, open the top-level **Demo operations** menu on
the main site, or **Network Admin > Asuka demos**. Both entries open the same
command center and are restricted to Multisite super administrators. The menu
is deliberately outside **Asuka Designer** and is absent from customer sites.

Configure:

- **Enable demo requests**: controls the public form and provisioning.
- **License source site**: site whose commercial runtime settings are inherited.
  Product content, pages, templates, and assets are never copied from it.
- **Demo duration**: limited to 24 hours by the plugin.
- **Verification lifetime**: how long the email link remains valid.
- **Maximum active demos**: global capacity limit.
- **Requests per IP per day**: abuse protection for one network connection.
- **Requests per email per day**: abuse protection for one address.
- **Retention**: delay before archived sites and temporary users are deleted.
- **Sender name and email**: identity passed to `wp_mail()`.

Save the settings, then place this shortcode on a public page:

```text
[apd_backend_demo]
```

The Asuka Studio starter content creates a **Backend demo** page with this
shortcode automatically. Any WordPress theme can use the shortcode.

The public form asks only for a first name, an email address, and the workflow
to evaluate. Company information is intentionally not required. Every child
site receives the same versioned `guided-product-v2` profile: one 2D
configuration, a visible T-shirt with two product variations, one calibrated
drawing area, one template, one WooCommerce product, two generic designs, three
system fonts, five colors, two printing methods, and two shapes.
The public pages and navigation of the main site are excluded.

The child site also uses a separate operational theme bundled with the plugin.
Its home page shows only the remaining session time and shortcuts to the demo
dashboard, sample configuration, asset library, and sample product. It never
renders the main site's marketing header, menus, homepage, backend-demo link,
or footer. Existing demo sites are upgraded to this theme automatically on
their next request.

### Configure Email Delivery

WordPress `wp_mail()` is only an interface. A production installation still
needs a reliable SMTP or transactional email provider.

For local development, Asuka Product Designer can connect `wp_mail()` directly
to Mailpit. Add the following values to `wp-config.php`:

```php
define('WP_ENVIRONMENT_TYPE', 'local');
define('APD_MAILPIT_ENABLED', true);
define('APD_MAILPIT_HOST', '127.0.0.1');
define('APD_MAILPIT_PORT', 1025);
define('APD_MAILPIT_UI_URL', 'http://127.0.0.1:8025');
```

Then open **Asuka Designer > Settings > Local email testing**. The card shows
whether SMTP is reachable, provides a test-send action, and links to the Mailpit
inbox. Developers can run the same end-to-end check from the plugin directory:

```bash
npm run check:mailpit
```

This command sends a unique message through WordPress and confirms through the
Mailpit API that the message was captured. The built-in transport accepts only
the WordPress `local` and `development` environment types. It disables itself on
`staging` and `production`, even when `APD_MAILPIT_ENABLED` was copied by
mistake.

Before launch:

1. Configure the provider through the host or a trusted SMTP plugin.
2. Use a sender address on a domain you control.
3. Configure SPF and DKIM.
4. Add DMARC after verifying delivery.
5. Send tests to Gmail, Outlook, and a custom business domain.
6. Confirm that links are not rewritten incorrectly by the provider.
7. Confirm that failed delivery is visible in the backend demo request log.

On a local XAMPP installation without Mailpit or another SMTP transport, the
request is stored but WordPress cannot deliver the email. When `WP_DEBUG` is
enabled and the environment is not production, Network Admin displays a
temporary development activation link. That link is never exposed in
production.

### Public Form Protection

The form uses several independent controls:

- WordPress nonce validation;
- a hidden honeypot field;
- a minimum and maximum completion time;
- explicit consent;
- normalized email validation;
- salted IP hashing;
- rate limits by email and IP;
- one active demo per email;
- a global active-site capacity limit;
- a cryptographically random 32-byte token;
- storage of only the SHA-256 token hash;
- a short verification window;
- atomic transition from `pending` to `provisioning`.

Do not remove one control merely because another control is present. They
protect against different failure and abuse modes.

### Isolation and Permissions

Every demo receives a separate WordPress site and a separate temporary user.
The customer can use:

- AsukaDesigner overview;
- product configurations and templates;
- designs, fonts, colors, printing methods, and shapes;
- the media library;
- the sample WooCommerce product;
- the storefront customization flow;
- the plugin documentation.

The customer cannot use:

- Network Admin;
- another child site or the main site's administration;
- plugins or themes;
- WordPress user management;
- global WordPress settings;
- AsukaDesigner license settings and raw keys;
- provider secrets;
- real customer orders;
- production operations belonging to another site;
- unrestricted administration actions.

The WordPress menu is pruned for clarity, and direct URL access is checked
server-side. Hiding a menu item is not considered a security boundary.

The demo storefront is private as well. Anonymous page requests return `404`,
and anonymous REST requests return `401`. The signed-in demo user and network
administrators can still test the full storefront.

### Data Available in a Demo

The provisioner deliberately builds a fresh, versioned sample dataset instead
of copying the main site's content:

- one built-in minimal asset catalog;
- one built-in sample template;
- one built-in sample product configuration;
- one new WooCommerce sample product;
- runtime defaults required to render the designer;
- only the server-side license connection fields required by the demo runtime.

Third-party image-provider keys, AI-provider secrets, production orders,
customers, main-site pages, navigation menus, media, and unrelated content are
not copied.

Review the safe setting allowlist whenever a new secret-bearing setting is added
to the plugin.

### Request Statuses

- `pending`: request stored; verification link can still be used.
- `provisioning`: one process claimed the link and is creating the site.
- `active`: site and user are available.
- `expired`: the 24-hour access window ended.
- `revoked`: an administrator ended access early.
- `failed`: provisioning failed and the error is available to Network Admin.

A single-use link cannot provision two sites, even when opened concurrently.

### Operate the Demo Fleet

Open the top-level **Demo operations** workspace to see:

- live, pending, available-slot, and expiring-soon totals;
- one operational card per active or provisioning workspace;
- requester identity and requested workflow;
- remaining time, expiration date, site health, and last recorded activity;
- direct links to the isolated site and its administration;
- a filterable audit history with mail and provisioning errors.

The command center offers three guarded actions:

- **+6 hours** or **+24 hours** synchronizes the new expiry across the request,
  temporary user, and child-site context;
- **Expire** archives the child site immediately and revokes subsequent access;
- **Run cleanup** executes the same lifecycle maintenance normally launched by
  cron.

All mutations require the Multisite network-management capability and a
WordPress nonce. The policy panel is collapsed below operational data so daily
support work does not require navigating through infrastructure settings.

Do not manually delete an active site's database tables. Let the lifecycle
service archive and remove the site so the request audit remains coherent.

### Expiry and Cleanup

The plugin schedules `apd_demo_cleanup` every 15 minutes.

Each cleanup run:

1. expires unused verification links;
2. marks provisioning jobs older than one hour as failed and removes any
   temporary site or user they already created;
3. archives active demos past their expiry;
4. retains archived request metadata for the configured period;
5. permanently deletes expired child sites after retention;
6. deletes temporary users that no longer belong to a site;
7. removes expired, revoked, and failed request rows after final cleanup.

For reliable production timing, call WordPress cron from the server scheduler
and disable traffic-driven cron only after that scheduler is working.

Example schedule:

```text
*/5 * * * * php /path/to/wordpress/wp-cron.php >/dev/null 2>&1
```

The exact PHP and WordPress paths depend on the server.

### Capacity Planning

Start with a low active-demo limit. Measure:

- average database size per child site;
- media generated during one session;
- PHP memory during site creation;
- provisioning duration;
- concurrent designer sessions;
- cron cleanup duration.

Increase capacity only after observing these values under realistic 2D and 3D
usage. Rate limits protect the request endpoint, but they do not replace server
capacity monitoring.

### Production Checklist

- Multisite main site and child-site routing tested.
- HTTPS and secure cookies verified.
- Transactional email delivered to several providers.
- SPF and DKIM passing.
- Public form nonce, honeypot, timing, and rate limits tested.
- Duplicate activation link rejected.
- Concurrent activation tested.
- Demo admin opens directly after activation.
- Demo survives a browser restart until expiry.
- Allowed product, asset, media, and storefront screens tested.
- Plugins, themes, users, settings, network admin, and main-site admin refused.
- Anonymous demo storefront returns `404`.
- Anonymous demo REST API returns `401`.
- Expiry notice visible.
- Manual revocation tested.
- Scheduled archive and permanent cleanup tested.
- Built-in demo content profile and expected asset counts verified.
- License source contains only the commercial runtime settings intended for demos.
- Safe setting allowlist reviewed.
- Backups and rollback procedure documented.

### Troubleshooting

**The request says that email delivery failed**

WordPress stored the request, but `wp_mail()` could not hand it to a transport.
Configure SMTP, inspect the mail provider log, and retry with a new address.

**The link is invalid**

The link expired, was already used, was revoked, or its token does not match.
Submit a new request.

**Provisioning remains in progress**

Inspect the PHP error log, request audit, and WordPress cron. The cleanup job
automatically marks provisioning attempts older than one hour as failed and
removes the temporary site and user IDs recorded during creation. If the status
remains unchanged, cron is not running or cleanup raised an error. Never reset
the request to `pending` in production because the verification token is
single-use by design.

**The customer is sent to My Account instead of WordPress admin**

Confirm that the `woocommerce_prevent_admin_access` integration is active.
Demo users intentionally lack broad editorial capabilities, so WooCommerce must
allow their restricted backend role explicitly.

**The storefront is not visible to the demo user**

Confirm that the customer is signed in to the temporary account, the child site
matches the `apd_demo_blog_id` user metadata, and the request has not expired.

**Cleanup does not run**

Inspect the scheduled `apd_demo_cleanup` event, WordPress cron health, server
cron logs, and PHP errors. Run cleanup manually only from a controlled
administrative context.

## 38. Newsletter Studio

The plugin includes a small native campaign system for product news. It is
designed for occasional updates to a modest, consented audience. It is not a
replacement for a high-volume marketing platform, customer segmentation
warehouse, bounce processor, or transactional email provider.

On Multisite, open **Network Admin > Asuka demos > Newsletter**. On a single
site, open **Asuka Designer > Newsletter**.

### How Demo Consent Works

The backend demo form contains two separate checkboxes:

- the transactional consent is required because WordPress must send the private
  demo verification link;
- the newsletter consent is optional and is never selected by default.

When the optional checkbox is selected, the address starts with the `pending`
status. Opening the demo verification link proves ownership of the email and
changes the subscription to `active`. A request that is never verified cannot
receive campaigns.

The same address is stored only once. A new explicit request can move an
unsubscribed address back to `pending`, but it must be verified again before it
can receive a campaign.

### Subscriber Statuses

- `pending`: consent was requested, but email ownership is not verified.
- `active`: confirmed and eligible for future campaigns.
- `unsubscribed`: excluded from every future audience snapshot.

The Subscribers tab supports search, status filtering, CSV export, manual
unsubscription, reactivation, and deletion. A manually added subscriber
requires the administrator to confirm that consent was collected elsewhere.
Do not use manual import for purchased or inferred contacts.

### Create and Test a Campaign

1. Open **Newsletter > Campaigns**.
2. Select **New campaign**.
3. Enter the internal name. Customers never see this value.
4. Enter the subject and optional preheader.
5. Enter the visible heading and message.
6. Optionally add one call-to-action label and HTTPS URL.
7. Save the draft.
8. Send a test to a controlled inbox.
9. Check desktop, mobile, links, sender identity, and spam placement.
10. Select **Send to confirmed audience** only after the test is correct.

The template automatically supplies:

- the AsukaDesigner brand header;
- a responsive white content panel;
- inbox preheader support;
- personalized greeting when a first name exists;
- an optional call-to-action button;
- the configured legal footer and company address;
- a signed subscription-management link.

Queued content is locked so the delivery audit always matches the message that
was sent.

### Background Delivery

When a campaign is queued, the plugin creates a fixed recipient snapshot from
currently active subscribers. `apd_newsletter_send_batch` then sends a
controlled batch through `wp_mail()`.

The default batch size is 20. Keep it conservative on shared hosting. The
Campaigns table reports:

- total recipients;
- accepted messages;
- failed messages;
- current status (`draft`, `sending`, `sent`, or `failed`).

Failed deliveries can be queued again without resending successful deliveries.
Unsubscribed contacts encountered in a queued batch are suppressed.

For predictable timing, configure a real server cron to call WordPress cron.
Traffic-driven WP-Cron can pause when the site receives no visitors.

### Email Transport and Deliverability

The campaign engine prepares consent, content, audience snapshots, batches,
delivery status, and unsubscribe links. It does not deliver email by itself.

Configure an authenticated SMTP or transactional provider that integrates with
`wp_mail()`. A free SMTP connector is sufficient for small campaigns when the
chosen provider's own quota permits it.

Before sending:

1. use a sender address on a controlled domain;
2. configure SPF and DKIM;
3. align the visible From address with the authenticated domain;
4. configure a monitored Reply-To address;
5. add a real company or postal address to the footer;
6. verify that WordPress cron runs;
7. send tests to multiple mailbox providers.

Local XAMPP does not provide SMTP by default. In that environment, campaign
records and lifecycle tests work, but a real inbox delivery requires an SMTP
transport.

### Unsubscribe Protection

Every campaign contains a subscriber-specific signed link. Opening the link
shows a confirmation screen; it does not immediately unsubscribe on a GET
request. This prevents automated email security scanners from accidentally
removing subscribers. The final POST is nonce-protected and immediately marks
the address as `unsubscribed`.

Transactional messages such as account access and demo verification are not
disabled by newsletter unsubscription.

### Newsletter Production Checklist

- Optional consent is unchecked by default.
- Consent copy and privacy policy reviewed for the target jurisdiction.
- Sender name, From address, Reply-To, footer, and company address configured.
- SPF and DKIM passing.
- SMTP delivery tested.
- Desktop and mobile template rendering checked.
- Test campaign links checked.
- WP-Cron or server cron working.
- Unsubscribe confirmation tested while signed out.
- Unsubscribed address excluded from the next campaign.
- CSV exports stored securely and deleted when no longer needed.

## 39. Production Readiness and Deployment

Open **Asuka Designer > QA & Diagnostics** and locate the
**Production readiness** panel. It is generated from the current WordPress
environment every time the page opens.

### Understand the Statuses

- **Passed** means the plugin could verify the requirement directly.
- **Warning** means the configuration may be valid, but a human or external
  service must still confirm it.
- **Failed** means the release must not be promoted until the issue is fixed.

Local XAMPP intentionally produces warnings for HTTP, missing release metadata,
SMTP, and production environment type. The commercial API remains fixed to its
official HTTPS host in every environment. These warnings are useful reminders,
not reasons to weaken the checks. Repeat the report on the actual staging host.

### What the Report Checks

The report validates:

- WordPress, PHP, and WooCommerce minimum versions;
- HTTPS and debug settings;
- dashboard file editing;
- fixed Asuka API URL and signed license token;
- core, Fabric, and Babylon bundle presence;
- a five-minute operational cron heartbeat;
- known SMTP or transactional mail integration;
- writable media uploads;
- permalink and privacy-policy setup;
- immutable release manifest and checksums.

The report never displays the raw license key or compact token.

### Cron Heartbeat

The plugin schedules `apd_operational_heartbeat` every five minutes. A recent
heartbeat proves that WordPress scheduled events are actually being executed,
not merely registered.

When `DISABLE_WP_CRON` is true, configure the server to call `wp-cron.php`
every five minutes. Wait for one run, then refresh Diagnostics. A stale
heartbeat means demo expiry, newsletters, and other scheduled work may be late.

### Command-Line Check

On a server with WP-CLI:

```bash
wp asuka production-preflight
wp asuka production-preflight --strict
wp asuka production-preflight --format=json
```

`--strict` treats warnings as failures and is useful as a final deployment
gate. JSON output can be archived by CI or attached to a support request.

### Remote Staging Smoke

From the plugin source directory:

```powershell
npm run check:staging -- `
  https://staging.example.com `
  https://staging-api.example.com `
  /product/custom-shirt/ `
  --production
```

This verifies the Symfony liveness/readiness endpoints, WordPress storefront,
REST API, AsukaDesigner namespace, and the optional product mount. It does not
replace the manual purchase-to-production workflow.

### Full Production Runbook

The release ZIP contains `docs/PRODUCTION.md`. Follow it for:

- staging topology;
- SMTP, SPF, DKIM, and DMARC;
- external cron;
- backup and restore drills;
- monitoring and alerts;
- privacy and legal review;
- immutable artifacts and checksums;
- rollback and final go/no-go rules.
