<?php

// Note: this namespace is `Frontend`, not `Public` — `public` is a
// reserved PHP keyword and can never be used as a namespace segment
// (confirmed the hard way: it parse-errors PHP outright, fatal on every
// page load, only ever caught once this plugin got a CI job that
// actually executes PHP — see tests.yml and the commit that fixed this).
// The `frontend/` directory name (and this namespace) exist to mean the
// same thing "public" was reaching for: front-end-facing code, as
// opposed to includes/ or admin/.
namespace ChargeForms\Frontend;

use ChargeForms\Includes\Draft_Service;
use ChargeForms\Includes\Form;
use ChargeForms\Includes\Logic\Context_Builder;
use ChargeForms\Includes\Logic\Evaluator;
use ChargeForms\Includes\Restrictions;
use ChargeForms\Includes\Settings;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class Shortcode {

	public function __construct() {
		add_shortcode( 'chargeforms', [ $this, 'render' ] );
		add_action( 'wp_enqueue_scripts', [ $this, 'register_assets' ] );
	}

	/** Set at the top of render_form_html() so render_field() can scope the Stripe config to the form actually being rendered — see render_field()'s 'payment_method' case. */
	private $current_form_id = 0;

	/** Reset at the top of render_form_html() — backs the "Enable Auto Tab-Index" Miscellaneous setting. */
	private $tabindex_counter = 0;

	public function register_assets() {
		wp_register_style( 'chargeforms-frontend', CHARGEFORMS_URL . 'assets/css/frontend.css', [], CHARGEFORMS_VERSION );
		wp_register_style(
			'chargeforms-frontend-tokens-refine',
			CHARGEFORMS_URL . 'assets/css/frontend-tokens-refine.css',
			[ 'chargeforms-frontend' ],
			CHARGEFORMS_VERSION
		);

		// Built via webpack (roadmap issue #28: previously split between
		// this hand-authored file with no build step and a separately-
		// built assets/build/frontend-conditional.js bundle, joined at
		// runtime via a `window.ChargeFormsConditional` global — now one
		// entry, assets/src/frontend/frontend-entry.js, importing the
		// conditional-logic engine directly instead).
		$frontend_asset_file = CHARGEFORMS_PATH . 'assets/build/frontend.asset.php';
		$frontend_asset      = file_exists( $frontend_asset_file )
			? include $frontend_asset_file
			: [ 'dependencies' => [], 'version' => CHARGEFORMS_VERSION ];
		wp_register_script(
			'chargeforms-frontend',
			CHARGEFORMS_URL . 'assets/build/frontend.js',
			$frontend_asset['dependencies'],
			$frontend_asset['version'],
			true
		);

		wp_register_script( 'chargeforms-stripe', CHARGEFORMS_URL . 'assets/js/stripe-payment.js', [ 'chargeforms-stripe-js' ], CHARGEFORMS_VERSION, true );
		// `null` is deliberate — Stripe.js is versioned/cache-busted by Stripe itself; this plugin has no version of its own to attach to a vendor-hosted URL.
		wp_register_script( 'chargeforms-stripe-js', 'https://js.stripe.com/v3/', [], null, true ); // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion

		// PayPal's own SDK loader URL carries the client id and currency as
		// query params (unlike Stripe.js, which is generic and configured at
		// runtime instead) — registered with whatever's saved right now;
		// re-registered per-request, so a key change in Settings takes effect
		// on the next page load with no cache to bust.
		$paypal_client_id = Settings::get( 'paypal_client_id' );
		wp_register_script( 'chargeforms-paypal', CHARGEFORMS_URL . 'assets/js/paypal-payment.js', [ 'chargeforms-paypal-js' ], CHARGEFORMS_VERSION, true );
		wp_register_script(
			'chargeforms-paypal-js',
			$paypal_client_id ? add_query_arg( [
				'client-id' => $paypal_client_id,
				'currency'  => strtoupper( Settings::get( 'paypal_currency', 'usd' ) ),
				'intent'    => 'capture',
			], 'https://www.paypal.com/sdk/js' ) : '',
			[],
			null, // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion -- PayPal's own SDK loader is versioned/cache-busted by PayPal itself.
			true
		);

		wp_register_style( 'chargeforms-address-autocomplete', CHARGEFORMS_URL . 'assets/css/address-autocomplete.css', [ 'chargeforms-frontend' ], CHARGEFORMS_VERSION );
		wp_register_script( 'chargeforms-address-autocomplete', CHARGEFORMS_URL . 'assets/js/address-autocomplete.js', [], CHARGEFORMS_VERSION, true );
	}

	/**
	 * Resolves the effective autocomplete provider for whatever Address
	 * field(s) exist on this form, or '' if none should get it. A
	 * per-field override ('none'/'osm'/'google') always wins over the
	 * site default (Settings::get('address_autocomplete_provider'));
	 * 'default' (or unset — every Address field predating this feature)
	 * falls through to the site setting. Only the FIRST resolved non-'none'
	 * provider is used — one script config per page, matching how the
	 * Stripe/PayPal keys above are also resolved once per page, not
	 * per-field; a form mixing google+osm across multiple Address fields
	 * is an edge case not worth a more complex per-field asset story for.
	 */
	private function active_address_autocomplete_provider( array $fields ) {
		$site_default = Settings::get( 'address_autocomplete_provider', 'none' );
		foreach ( $this->flatten_fields( $fields ) as $field ) {
			if ( 'address' !== $field['type'] ) {
				continue;
			}
			$provider = $field['autocompleteProvider'] ?? 'default';
			if ( 'default' === $provider ) {
				$provider = $site_default;
			}
			if ( in_array( $provider, [ 'osm', 'google' ], true ) ) {
				return $provider;
			}
		}
		return '';
	}

	/** Returns ' tabindex="N"' (incrementing) when the setting is on, '' otherwise — called once per field's primary input. */
	private function next_tabindex_attr() {
		if ( ! Settings::get( 'auto_tab_index_enabled' ) ) {
			return '';
		}
		$this->tabindex_counter++;
		return ' tabindex="' . (int) $this->tabindex_counter . '"';
	}

	/**
	 * the reference product parity: a Required field can show either the site-wide
	 * Global message (Global Settings > Validation Messages) or a per-field
	 * Custom one (Builder > Field Settings). Emits `required` plus, only
	 * when the field is actually required, a `data-required-message`
	 * carrying whichever one applies — `frontend-entry.js` reads this to
	 * call setCustomValidity() so the browser's native validation popup and
	 * this plugin's own inline error both show the configured message
	 * instead of the browser's untranslated default ("Please fill out this
	 * field"). Mirrors SubmissionHandler::required_message()'s server-side
	 * fallback logic exactly, so what a visitor sees client-side and what
	 * the server would say on a bypassed submit are always the same text.
	 */
	private function required_attr( array $field ) {
		if ( empty( $field['required'] ) ) {
			return $this->next_tabindex_attr();
		}
		if ( 'custom' === ( $field['requiredMessageMode'] ?? '' ) && '' !== trim( (string) ( $field['requiredMessage'] ?? '' ) ) ) {
			$message = $field['requiredMessage'];
		} else {
			$message = Settings::get( 'validation_msg_required', __( 'This field is required', 'chargeforms' ) );
		}
		return ' required data-required-message="' . esc_attr( $message ) . '"' . $this->next_tabindex_attr();
	}

	/**
	 * Same Global/Custom fallback as required_attr() above, generalized to
	 * the Email/Numeric/Url format-validation rules — mirrors
	 * SubmissionHandler::format_message()'s server-side logic exactly (same
	 * `{rule}MessageMode`/`{rule}Message` field keys) so the client-side
	 * setCustomValidity() text a visitor sees always matches what a
	 * bypassed direct POST would get back from the server.
	 */
	private function format_message_attr( array $field, $rule, $global_key ) {
		if ( 'custom' === ( $field[ $rule . 'MessageMode' ] ?? '' ) && '' !== trim( (string) ( $field[ $rule . 'Message' ] ?? '' ) ) ) {
			return $field[ $rule . 'Message' ];
		}
		return Settings::get( $global_key );
	}

	/**
	 * The builder's Developer settings (Field ID / HTML ID Override) let an
	 * author override the rendered element's id — e.g. to match an id a
	 * theme's CSS or a third-party script already targets. Falls back to
	 * the existing `chargeforms-{field-id}` convention when unset, so every
	 * pre-existing form keeps rendering exactly as before.
	 */
	private function field_html_id( array $field ) {
		return ! empty( $field['htmlId'] ) ? $field['htmlId'] : 'chargeforms-' . $field['id'];
	}

	/**
	 * Replaces every {query.param_name} placeholder in $raw with that
	 * param's real value from the CURRENT request's query string — an
	 * unmatched placeholder (param absent from the URL) is replaced with
	 * an empty string rather than left as literal `{query.x}` text, so a
	 * visitor who didn't arrive via the expected link sees a blank default
	 * instead of template syntax. Values already come sanitized via
	 * Context_Builder::current_request_query_params(); this only needs to
	 * additionally guard against a param value that itself happens to
	 * contain `{query.` (extremely unlikely, but str_replace with an
	 * array of needles/replacements is single-pass over the ORIGINAL
	 * string regardless, so this is actually already safe against that).
	 */
	private static function resolve_query_placeholders( $raw ) {
		$params = Context_Builder::current_request_query_params();

		return preg_replace_callback(
			'/\{query\.([a-zA-Z0-9_-]+)\}/',
			function ( $matches ) use ( $params ) {
				return $params[ $matches[1] ] ?? '';
			},
			$raw
		);
	}

	/**
	 * Id for the `.chargeforms-field-help` span render_field_row() renders
	 * below a field's control(s) — shared with extra_input_attrs() below so
	 * the control(s) and the span they're described by always agree on the
	 * same id without either side re-deriving it independently.
	 */
	private function field_help_id( array $field ) {
		return $this->field_html_id( $field ) . '-help';
	}

	/**
	 * Read Only / Disabled / Custom Attributes have been real, stored
	 * builder settings since Milestone 5 but were never enforced on the
	 * actual rendered input (roadmap: the reference product comparison, "Field
	 * Settings" — tracked as a known gap in FEATURE_STATUS.md). Builds one
	 * attribute string covering all three so every input-rendering call
	 * site only needs one insertion point rather than three.
	 *
	 * Custom attribute names are restricted to a safe HTML-attribute-name
	 * pattern (not escaped-and-trusted verbatim) so a stray typo in the
	 * builder can't emit malformed markup — the value itself is always
	 * esc_attr()'d regardless of the name.
	 */
	private function extra_input_attrs( array $field ) {
		$attrs = '';

		if ( ! empty( $field['readOnly'] ) ) {
			$attrs .= ' readonly';
		}
		if ( ! empty( $field['disabled'] ) ) {
			$attrs .= ' disabled';
		}

		// render_field_row() renders a `.chargeforms-field-help` span below
		// the control whenever helpMessage is set, but nothing ever pointed
		// a control at it — a screen-reader visitor never heard the help
		// text at all, unlike the beside-label tooltip (`?` icon), which
		// already carries its text via aria-label. A radio/checkbox group
		// gets this on every option (each printf in that switch threads the
		// same $extra through), which is intentional: they share one help
		// span the same way they'll share one error message on failed
		// validation (see frontend-entry.js's showFieldError).
		if ( ! empty( $field['helpMessage'] ) ) {
			$attrs .= sprintf( ' aria-describedby="%s"', esc_attr( $this->field_help_id( $field ) ) );
		}

		foreach ( $field['customAttributes'] ?? [] as $pair ) {
			$key = trim( $pair['key'] ?? '' );
			if ( '' === $key || ! preg_match( '/^[a-zA-Z][a-zA-Z0-9_:-]*$/', $key ) ) {
				continue;
			}
			$attrs .= sprintf( ' %s="%s"', $key, esc_attr( $pair['value'] ?? '' ) );
		}

		return $attrs;
	}

	/**
	 * The builder's own canvas preview (FieldPreview.js) shows a sensible
	 * default placeholder — "you@example.com", "Your Name" — whenever a
	 * field's own placeholder is blank, so the canvas never looks like a
	 * row of empty boxes while editing. That fallback never existed on
	 * this side: a real visitor got a genuinely blank input with no hint
	 * at all, a real gap found by comparing the builder's own preview
	 * against the actual rendered form side by side. Mirrors
	 * FieldPreview.js's switch exactly, type for type.
	 */
	private function default_placeholder_for( array $field ) {
		switch ( $field['type'] ) {
			case 'email':
				return 'you@example.com';
			case 'url':
				return 'https://';
			case 'phone':
				return '(555) 555-5555';
			case 'number':
				return '0';
			case 'mask_input':
				return $field['mask'] ?? '(999) 999-9999';
			case 'textarea':
			case 'post_content':
			case 'post_excerpt':
				return $field['label'] ?? '';
			default:
				return ! empty( $field['label'] ) ? 'Your ' . $field['label'] : '';
		}
	}

	public function render( $atts ) {
		$atts = shortcode_atts( [ 'id' => 0 ], $atts, 'chargeforms' );
		$form = Form::get( (int) $atts['id'] );

		if ( ! $form || 'published' !== $form['status'] ) {
			return '';
		}

		$blocked = Restrictions::check( $form );
		if ( null !== $blocked ) {
			// render_form_html() is what normally enqueues 'chargeforms-frontend'
			// (base stylesheet) — this early-return path skips it entirely, so
			// without this line a blocked visitor's card would render as bare,
			// unstyled text (a real, pre-existing bug found live while
			// verifying the new restriction-card styling: the CSS class names
			// were correct, but the stylesheet itself was never on the page).
			wp_enqueue_style( 'chargeforms-frontend' );
			wp_enqueue_style( 'chargeforms-frontend-tokens-refine' );
			return $this->render_restriction_card( $blocked );
		}

		return $this->render_form_html( $form );
	}

	/**
	 * A visitor-facing card for a blocked form — one distinct tone/icon per
	 * restriction type instead of a single generic gray box, matching
	 * design_handoff_chargeforms/ChargeForms Front-End.dc.html's isRestricted
	 * state. The "setting" hint always names the real Form Settings tab it
	 * came from (there's one "Restrictions" tab holding all three checks —
	 * see admin/class-form-settings-page.php — not per-restriction
	 * sub-pages, so the hint doesn't claim a deeper path than actually exists).
	 */
	private function render_restriction_card( array $blocked ) {
		$meta = [
			'login'             => [ 'glyph' => '🔒', 'tone' => 'info', 'title' => __( 'Login required', 'chargeforms' ) ],
			'schedule_pending'  => [ 'glyph' => '🕓', 'tone' => 'warn', 'title' => __( 'Not open yet', 'chargeforms' ) ],
			'schedule_expired'  => [ 'glyph' => '🕓', 'tone' => 'warn', 'title' => __( 'Closed', 'chargeforms' ) ],
			'limit_entries'     => [ 'glyph' => '⚠', 'tone' => 'warn', 'title' => __( 'Entry limit reached', 'chargeforms' ) ],
			'restricted_ip'     => [ 'glyph' => '🚫', 'tone' => 'warn', 'title' => __( 'Not available', 'chargeforms' ) ],
		];
		$type = $meta[ $blocked['type'] ] ?? [ 'glyph' => '⚠', 'tone' => 'warn', 'title' => __( 'Unavailable', 'chargeforms' ) ];

		return sprintf(
			'<div class="chargeforms-restriction-card chargeforms-restriction-%s"><span class="chargeforms-restriction-icon" aria-hidden="true">%s</span><div><div class="chargeforms-restriction-title">%s</div><div class="chargeforms-restriction-body">%s</div><div class="chargeforms-restriction-setting">%s</div></div></div>',
			esc_attr( $type['tone'] ),
			esc_html( $type['glyph'] ),
			esc_html( $type['title'] ),
			esc_html( $blocked['message'] ),
			esc_html__( 'Form Settings → Restrictions', 'chargeforms' )
		);
	}

	/**
	 * Builds the actual <form> markup for a given form record. Shared by the
	 * [chargeforms] shortcode and Forms_List_Page's "Preview" action — Preview
	 * needs to render a form regardless of its published/draft status, which
	 * the shortcode itself deliberately refuses to do.
	 */
	public function render_form_html( array $form, $is_preview = false ) {
		// The base stylesheet always loads — a form has to look usable out
		// of the box. "Default Style Template" (Global Settings >
		// Miscellaneous) is a separate, purely additive polish layer on
		// top of that, matching how the real product's own toggle behaves
		// (off by default still means a normal, styled form).
		wp_enqueue_style( 'chargeforms-frontend' );
		$this->current_form_id = (int) $form['id'];
		$this->tabindex_counter = 0;

		$pages      = $this->split_into_pages( $form['fields'] );
		$multi_step = count( $pages ) > 1;

		// Fallback matches Settings::defaults(). Save & Resume is opt-in so
		// forms do not gain draft controls until the site owner enables them.
		$save_resume_enabled = ! $is_preview && Settings::get( 'save_resume_enabled', false );

		// Every form renders with novalidate now (see the <form> tag below)
		// and relies on this script's initValidation() for the styled
		// error-summary/inline-error UI that replaces the browser's native
		// popups — so this can no longer be conditional on multi-step/
		// mask/signature/etc the way it used to be; a plain two-field form
		// needs it just as much as a complex one.
		wp_enqueue_script( 'chargeforms-frontend' );

		if ( $this->has_payment_field_for_gateway( $form['fields'], 'stripe' ) ) {
			wp_enqueue_script( 'chargeforms-stripe' );
		}
		if ( $this->has_payment_field_for_gateway( $form['fields'], 'paypal' ) && Settings::get( 'paypal_client_id' ) ) {
			wp_enqueue_script( 'chargeforms-paypal' );
		}

		$address_provider = $this->active_address_autocomplete_provider( $form['fields'] );
		if ( $address_provider ) {
			wp_enqueue_style( 'chargeforms-address-autocomplete' );
			wp_enqueue_script( 'chargeforms-address-autocomplete' );
			// The API key is only ever printed when a form on THIS page
			// actually resolved to the Google provider — never unconditionally
			// on every page load, same discipline as the Stripe/PayPal keys
			// above (only enqueued when a payment field for that gateway is
			// actually present).
			wp_localize_script( 'chargeforms-address-autocomplete', 'ChargeFormsAddress', [
				'provider' => $address_provider,
				'apiKey'   => 'google' === $address_provider ? Settings::get( 'google_maps_api_key' ) : '',
			] );
		}

		$notice = '';
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only display flags on our own post-submit redirect URL (set by Submission_Handler::redirect_back()), not a state-changing request.
		if ( ! $is_preview && isset( $_GET['chargeforms_submitted'] ) && (int) $_GET['chargeforms_submitted'] === (int) $form['id'] ) {
			// A double-opt-in submission is genuinely unfinished — showing
			// the same "your submission was received" wording a normal
			// success gets would be misleading, since nothing is actually
			// recorded as complete until the visitor clicks the emailed
			// confirmation link (see Submission_Handler::redirect_back()'s
			// $pending flag, the only thing that sets this query arg).
			if ( isset( $_GET['chargeforms_pending'] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only, see the ignore comment above.
				$notice = '<div class="chargeforms-success chargeforms-success-pending"><span class="chargeforms-success-icon" aria-hidden="true">✉</span><div><div class="chargeforms-success-title">' . esc_html__( 'Check your inbox', 'chargeforms' ) . '</div><div class="chargeforms-success-body">' . esc_html__( 'Your submission is held as pending until you click the confirmation link we just emailed you.', 'chargeforms' ) . '</div></div></div>';
			} else {
				// Conditional Confirmations (the reference product parity) — Submission_Handler::redirect_back()
				// puts only the matched row's INDEX on the URL, never its message text, so this looks
				// the real message up fresh from the form's own current settings rather than trusting
				// anything from the query string beyond "which row".
				$message = $form['settings']['success_message'] ?? __( 'Thanks — your submission was received.', 'chargeforms' );
				if ( isset( $_GET['chargeforms_confirmation'] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only, see the ignore comment above.
					$confirmation_index = (int) $_GET['chargeforms_confirmation']; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only, see the ignore comment above.
					$confirmation_row   = $form['settings']['confirmations'][ $confirmation_index ] ?? null;
					if ( is_array( $confirmation_row ) && 'message' === ( $confirmation_row['type'] ?? 'message' ) && '' !== ( $confirmation_row['message'] ?? '' ) ) {
						$message = $confirmation_row['message'];
					}
				}
				$notice  = '<div class="chargeforms-success"><span class="chargeforms-success-icon" aria-hidden="true">✓</span><div class="chargeforms-success-body">' . esc_html( $message ) . '</div></div>';
			}
		}

		// Real data for the conditional-logic data sources that need a
		// server round-trip to resolve (currentUser/userRole/postMeta/
		// userMeta) — scoped to only what this form's own rules reference
		// (Context_Builder never dumps more than that). urlParam/query and
		// cookie are deliberately NOT included here: both are natively
		// readable straight from the browser (window.location.search,
		// document.cookie), so assets/src/frontend/context.js resolves
		// those live instead of embedding a copy that would go stale the
		// moment the visitor navigates within a single-page-app-style page
		// without a full reload.
		$logic_context_attr = '';
		if ( $this->has_conditional_fields( $form['fields'] ) ) {
			$logic_rules = Evaluator::extract_field_rules( $this->flatten_fields( $form['fields'] ) );
			$logic_extra = Context_Builder::build_extra( $logic_rules, get_the_ID() ?: 0 );
			unset( $logic_extra['urlParams'], $logic_extra['cookies'] );
			if ( ! empty( $logic_extra ) ) {
				$logic_context_attr = ' data-fc-context="' . esc_attr( wp_json_encode( $logic_extra ) ) . '"';
			}
		}

		// Save & Resume config, embedded once here rather than fetched by a
		// second request — a resumable draft is detected server-side
		// (either an emailed ?chargeforms_resume= token, validated the same
		// way any other draft REST call validates one, or a logged-in
		// visitor's own prior draft for this exact form) and its
		// already-sanitized/re-validated values are handed straight to
		// save-resume.js, which only shows the "Resume?" banner — it never
		// applies them until the visitor explicitly confirms (this
		// feature's own "Restore confirmation" requirement).
		$draft_config = '';
		if ( $save_resume_enabled ) {
			$resume = null;
			$resume_token = isset( $_GET['chargeforms_resume'] ) ? sanitize_text_field( wp_unslash( $_GET['chargeforms_resume'] ) ) : ''; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- a bearer token, not a state-changing action; verified by hash lookup + expiry inside Draft_Service::restore(), not by a nonce.
			if ( $resume_token ) {
				$resume = Draft_Service::restore( $form, $resume_token );
			} elseif ( is_user_logged_in() ) {
				$resume = Draft_Service::restore_for_user( $form, get_current_user_id() );
			}

			$draft_config = wp_json_encode( [
				'enabled'         => true,
				'restUrl'         => esc_url_raw( rest_url( 'chargeforms/v1' ) ),
				'formId'          => $form['id'],
				'nonce'           => wp_create_nonce( 'chargeforms_draft_' . $form['id'] ),
				// The draft REST routes are registered public (permission_callback:
				// true) and rely on the ChargeForms-specific nonce above for CSRF
				// protection, not WordPress's own REST cookie auth — but WP core's
				// rest_cookie_check_errors() still silently treats ANY REST
				// request as anonymous (current_user = 0) whenever cookies are
				// present without this standard 'wp_rest' nonce header attached,
				// even on a fully public route. Left out, a logged-in visitor's
				// browser would generate this nonce as themselves (an ordinary
				// page render, unaffected by that REST-only rule) but then fail
				// verification on every draft save (the REST request re-checks it
				// as anonymous) — confirmed by live testing against a real
				// WordPress instance, not something a stubbed-wp_verify_nonce()
				// unit test can catch. save-resume.js sends this as the
				// X-WP-Nonce header on every draft request so verification runs
				// under the SAME user context it was generated in, for both
				// anonymous and logged-in visitors alike.
				'restNonce'       => wp_create_nonce( 'wp_rest' ),
				'autosaveSeconds' => (int) Settings::get( 'save_resume_autosave_seconds', 20 ),
				'token'           => $resume['token'] ?? '',
				'resume'          => $resume,
			] );
		}

		ob_start();
		?>
		<?php
		// Per-form layout overrides (v0.107.0, matching the reference product's real
		// per-form "Form Layout" tab — the plugin's internal reference-screenshot archive/
		// global-settings-layout--02.webp) — each defaults to 'default',
		// meaning "use the site-wide Global Settings value", so an existing
		// form with no override saved keeps its exact current look.
		// $form['settings'] is per-form, Settings::get() is the site-wide
		// fallback.
		$form_settings     = $form['settings'] ?: [];
		$label_placement   = 'default' !== ( $form_settings['label_placement'] ?? 'default' ) ? $form_settings['label_placement'] : Settings::get( 'label_placement', 'top' );
		$help_placement    = 'default' !== ( $form_settings['help_placement'] ?? 'default' ) ? $form_settings['help_placement'] : Settings::get( 'help_placement', 'below' );
		$error_placement   = 'default' !== ( $form_settings['error_placement'] ?? 'default' ) ? $form_settings['error_placement'] : Settings::get( 'error_placement', 'below' );
		$asterisk_position = 'default' !== ( $form_settings['asterisk_position'] ?? 'default' ) ? $form_settings['asterisk_position'] : Settings::get( 'asterisk_position', 'right' );
		$conversational_mode = ! empty( $form_settings['conversational_mode'] );

		$layout_classes = [
			'chargeforms-form',
			'chargeforms-form-' . (int) $form['id'],
			'chargeforms-label-' . $label_placement,
			'chargeforms-help-' . $help_placement,
			'chargeforms-error-' . $error_placement,
			'chargeforms-asterisk-' . $asterisk_position,
		];
		if ( $conversational_mode ) {
			$layout_classes[] = 'chargeforms-conversational';
		}
		if ( Settings::get( 'default_style_template_enabled' ) ) {
			$layout_classes[] = 'chargeforms-styled-theme';
		}
		if ( ! empty( $form_settings['extra_form_class'] ) ) {
			$layout_classes[] = sanitize_html_class( $form_settings['extra_form_class'] );
		}
		// Read by the always-enqueued frontend bundle's initAnalyticsTracking()
		// (assets/src/frontend/frontend-entry.js) — only printed when analytics
		// are actually enabled for this render, never unconditionally.
		$track_url_attr = ( ! $is_preview && ! Settings::get( 'disable_form_analytics' ) )
			? ' data-chargeforms-track-url="' . esc_url( rest_url( 'chargeforms/v1/forms/' . (int) $form['id'] . '/track-event' ) ) . '"'
			: '';
		// Read by frontend-entry.js's initSubmitNonce(): a page cached by a
		// caching plugin/CDN serves the same _wpnonce to everyone until the
		// cache entry expires, after which submissions fail the handler's
		// nonce check. The bundle re-fetches a fresh nonce from this URL on
		// load so a cached page keeps submitting. The wp_rest nonce travels
		// with that fetch as the X-WP-Nonce header: WP core's REST cookie
		// check resolves a cookie-bearing request as anonymous unless it is
		// sent, which would mint the submission nonce for the wrong user on
		// a logged-in visitor and make their (valid) submits fail.
		$nonce_url_attr = ' data-chargeforms-nonce-url="' . esc_url( rest_url( 'chargeforms/v1/forms/' . (int) $form['id'] . '/submit-nonce' ) ) . '"'
			. ' data-chargeforms-rest-nonce="' . esc_attr( wp_create_nonce( 'wp_rest' ) ) . '"';
		?>
		<form class="<?php echo esc_attr( implode( ' ', $layout_classes ) ); ?>" method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" novalidate<?php echo $this->has_file_field( $form['fields'] ) ? ' enctype="multipart/form-data"' : ''; ?><?php echo wp_kses( $logic_context_attr, [] ); ?><?php echo $draft_config ? ' data-fc-draft-config="' . esc_attr( $draft_config ) . '"' : ''; ?><?php echo wp_kses( $track_url_attr, [] ); ?><?php echo wp_kses( $nonce_url_attr, [] ); ?>>
			<input type="hidden" name="action" value="chargeforms_submit">
			<input type="hidden" name="form_id" value="<?php echo esc_attr( $form['id'] ); ?>">
			<input type="hidden" name="_wpnonce" value="<?php echo esc_attr( wp_create_nonce( 'chargeforms_submit_' . $form['id'] ) ); ?>">
			<?php if ( $save_resume_enabled ) : ?>
				<input type="hidden" name="chargeforms_draft_token" value="<?php echo esc_attr( $resume['token'] ?? '' ); ?>">
			<?php endif; ?>

			<?php if ( Settings::get( 'honeypot_enabled', true ) ) : ?>
				<input type="text" name="chargeforms_hp" value="" style="position:absolute;left:-9999px;" tabindex="-1" autocomplete="off">
			<?php endif; ?>

			<?php if ( $save_resume_enabled && $resume ) : ?>
				<div class="chargeforms-draft-banner" data-fc-draft-banner hidden>
					<p>
						<?php esc_html_e( 'You have a saved draft from', 'chargeforms' ); ?>
						<span data-fc-draft-saved-at></span>.
					</p>
					<button type="button" data-fc-draft-resume><?php esc_html_e( 'Resume', 'chargeforms' ); ?></button>
					<button type="button" data-fc-draft-discard><?php esc_html_e( 'Start Over', 'chargeforms' ); ?></button>
				</div>
			<?php endif; ?>

			<?php echo $notice; // phpcs:ignore ?>
			<?php echo $this->payment_wiring_notice( $form['fields'] ); // phpcs:ignore ?>

			<?php if ( $multi_step ) : ?>
				<?php
				// Numbered-dot stepper (design_handoff_chargeforms/ChargeForms
				// Front-End.dc.html's stepper()) — a done step gets a checkmark,
				// the current one a filled dot, everything after stays flat gray.
				// initSteps()'s show() in frontend-entry.js keeps the
				// is-done/is-active classes and the connector lines in sync as
				// the visitor moves between steps.
				?>
				<div class="chargeforms-progress">
					<?php foreach ( $pages as $step_index => $page ) : ?>
						<div class="chargeforms-progress-item<?php echo 0 === $step_index ? ' is-active' : ''; ?>">
							<span class="chargeforms-progress-dot" data-n="<?php echo (int) $step_index + 1; ?>"><?php echo (int) $step_index + 1; ?></span>
							<span class="chargeforms-progress-label"><?php echo esc_html( $page['title'] ); ?></span>
						</div>
						<?php if ( $step_index < count( $pages ) - 1 ) : ?>
							<div class="chargeforms-progress-line"></div>
						<?php endif; ?>
					<?php endforeach; ?>
				</div>
			<?php endif; ?>

			<?php foreach ( $pages as $step_index => $page ) : ?>
				<div class="chargeforms-step" data-step="<?php echo (int) $step_index; ?>"<?php echo 0 === $step_index ? '' : ' style="display:none;"'; ?>>
					<?php foreach ( $page['fields'] as $field ) : ?>
						<?php $this->render_field_row( $field ); ?>
					<?php endforeach; ?>

					<?php if ( $multi_step ) : ?>
						<div class="chargeforms-step-actions">
							<?php if ( $step_index > 0 ) : ?>
								<button type="button" class="chargeforms-step-prev"><?php esc_html_e( 'Previous', 'chargeforms' ); ?></button>
							<?php endif; ?>
							<?php if ( $step_index < count( $pages ) - 1 ) : ?>
								<button type="button" class="chargeforms-step-next"><?php esc_html_e( 'Next', 'chargeforms' ); ?></button>
							<?php endif; ?>
						</div>
					<?php endif; ?>
				</div>
			<?php endforeach; ?>

			<button type="submit" class="chargeforms-submit"<?php echo $multi_step ? ' style="display:none;"' : ''; ?>>
				<?php echo esc_html( $form_settings['submit_button_text'] ?? __( 'Submit', 'chargeforms' ) ); ?>
			</button>

			<?php if ( $save_resume_enabled ) : ?>
				<div class="chargeforms-draft-controls">
					<button type="button" data-fc-draft-save><?php esc_html_e( 'Save Draft', 'chargeforms' ); ?></button>
					<span data-fc-draft-status role="status"></span>
					<span class="chargeforms-draft-email">
						<input type="email" data-fc-draft-email-input placeholder="<?php esc_attr_e( 'Your email', 'chargeforms' ); ?>">
						<button type="button" data-fc-draft-email-btn><?php esc_html_e( 'Email me a link to finish later', 'chargeforms' ); ?></button>
					</span>
				</div>
			<?php endif; ?>
		</form>
		<?php
		return ob_get_clean();
	}

	/**
	 * Splits a form's flat field list into pages at each 'page_break' field.
	 * Returns [ [ 'title' => string, 'fields' => array ], ... ] — always at
	 * least one page, even for forms with no page breaks.
	 */
	private function split_into_pages( array $fields ) {
		$pages = [ [ 'title' => __( 'Step 1', 'chargeforms' ), 'fields' => [] ] ];

		foreach ( $fields as $field ) {
			if ( 'page_break' === $field['type'] ) {
				$pages[] = [
					'title'  => ! empty( $field['label'] ) ? $field['label'] : sprintf(
						/* translators: %d: step number */
						__( 'Step %d', 'chargeforms' ),
						count( $pages ) + 1
					),
					'fields' => [],
				];
				continue;
			}
			$pages[ count( $pages ) - 1 ]['fields'][] = $field;
		}

		return $pages;
	}

	/**
	 * Container node types the builder has supported since Milestone 2
	 * (unlimited nesting — see assets/src/builder/core/tree.js) that this
	 * file's rendering now walks recursively as of Milestone 5. Mirrors
	 * assets/src/builder/fields/classifications.js's CONTAINER_TYPES.
	 */
	const CONTAINER_TYPES = [ 'section', 'row', 'column', 'container', 'repeat_container', 'tabs', 'tab_pane', 'accordion', 'accordion_panel' ];

	/**
	 * Recursively flattens a field tree (including CONTAINER_TYPES'
	 * children) into one flat list — mirrors
	 * assets/src/builder/core/tree.js's flattenFields(). Needed because the
	 * enqueue/detection helpers below (has_field_type,
	 * has_conditional_fields, and by extension has_file_field/
	 * has_payment_field) previously only scanned top-level fields; a
	 * payment/file/mask/signature/conditional field nested inside a
	 * Section/Row/Column/Container would otherwise silently fail to
	 * trigger the script it needs.
	 */
	private function flatten_fields( array $fields ) {
		$flat = [];
		foreach ( $fields as $field ) {
			$flat[] = $field;
			if ( ! empty( $field['children'] ) && is_array( $field['children'] ) ) {
				$flat = array_merge( $flat, $this->flatten_fields( $field['children'] ) );
			}
		}
		return $flat;
	}

	private function has_field_type( array $fields, $type ) {
		foreach ( $this->flatten_fields( $fields ) as $field ) {
			if ( $type === $field['type'] ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Payment Item / Custom Amount only ever add a line item to the
	 * commerce total (see COMMERCE_FIELD_TYPES and assets/js/frontend.js's
	 * computeCommerce()) — neither one collects a card or actually charges
	 * anyone. That happens exclusively in a Payment Method field (Stripe
	 * or PayPal). A form with a priced field but no Payment Method field
	 * is real, confirmed dead weight: it shows a total, visitors fill it
	 * in, and nothing ever bills them — silently, with no error anywhere.
	 * Admin-only, same discipline as the missing-API-key notices above.
	 */
	private function payment_wiring_notice( array $fields ) {
		if ( ! current_user_can( 'chargeforms_manage_forms' ) ) {
			return '';
		}
		$has_priced_field = $this->has_field_type( $fields, 'payment_item' ) || $this->has_field_type( $fields, 'custom_amount' );
		if ( ! $has_priced_field || $this->has_field_type( $fields, 'payment_method' ) ) {
			return '';
		}
		return '<p class="chargeforms-notice">' . esc_html__( 'This form has a Payment Item or Custom Amount field but no Payment Method field — it will show a price, but nothing collects payment or charges the visitor. Add a Payment Method field (Stripe or PayPal) so the total is actually charged. This message only shows to admins.', 'chargeforms' ) . '</p>';
	}

	private function has_file_field( array $fields ) {
		return $this->has_field_type( $fields, 'file' ) || $this->has_field_type( $fields, 'image_upload' ) || $this->has_field_type( $fields, 'featured_image' );
	}

	/** `$gateway` defaults unset payment_method fields to 'stripe', same convention as render_payment_method() — a form saved before PayPal existed must still enqueue Stripe's script, not neither. */
	private function has_payment_field_for_gateway( array $fields, $gateway ) {
		foreach ( $this->flatten_fields( $fields ) as $field ) {
			if ( 'payment_method' === $field['type'] && $gateway === ( $field['gateway'] ?? 'stripe' ) ) {
				return true;
			}
		}
		return false;
	}

	/** Milestone 5C — any field type the client-side commerce calculator (assets/js/frontend.js's computeCommerce()) needs to run for. */
	const COMMERCE_FIELD_TYPES = [ 'product', 'quantity', 'shipping', 'tax', 'discount', 'subtotal', 'total', 'math_field', 'payment_summary' ];

	private function has_commerce_field( array $fields ) {
		foreach ( self::COMMERCE_FIELD_TYPES as $type ) {
			if ( $this->has_field_type( $fields, $type ) ) {
				return true;
			}
		}
		return false;
	}

	private function has_conditional_fields( array $fields ) {
		foreach ( $this->flatten_fields( $fields ) as $field ) {
			$rule = $field['logicRule'] ?? null;
			if ( ! empty( $rule['enabled'] ) && ! empty( $rule['trigger']['children'] ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Builds the inline style for one column node. The width is emitted as
	 * CSS custom properties rather than a direct flex-basis/max-width so the
	 * stylesheet can layer per-breakpoint overrides on top (see
	 * frontend.css's .chargeforms-column rules) - an inline flex-basis would
	 * outrank every media query in the sheet, which is exactly why
	 * per-device widths were impossible before.
	 *
	 * The desktop value lives in `width` (the key every form saved before
	 * this existed already has); `widthTablet`/`widthMobile` are optional
	 * overrides. A blank override means "inherit the next-wider device",
	 * which the CSS var() fallback chain handles without extra markup.
	 */
	private function column_width_style( array $column ) {
		$style  = '--fc-col:' . $this->normalize_column_width( $column['width'] ?? '', '50' ) . '%;';
		$tablet = $this->normalize_column_width( $column['widthTablet'] ?? '', '' );
		$mobile = $this->normalize_column_width( $column['widthMobile'] ?? '', '' );
		if ( '' !== $tablet ) {
			$style .= '--fc-col-tablet:' . $tablet . '%;';
		}
		if ( '' !== $mobile ) {
			$style .= '--fc-col-mobile:' . $mobile . '%;';
		}
		return $style;
	}

	/**
	 * Column widths are author-supplied but land in a style attribute, so
	 * they are clamped to 1-100 and rejected outright if non-numeric -
	 * never passed through as free text. Returns the fallback (itself ''
	 * to mean "inherit") when there is no usable value.
	 */
	private function normalize_column_width( $value, $fallback ) {
		$value = is_scalar( $value ) ? trim( (string) $value ) : '';
		if ( '' === $value || ! is_numeric( $value ) ) {
			return $fallback;
		}
		$width = (float) $value;
		$width = max( 1.0, min( 100.0, $width ) );
		// Trim the pointless trailing zeroes number_format adds (50.00 -> 50).
		return rtrim( rtrim( number_format( $width, 2, '.', '' ), '0' ), '.' );
	}

	/**
	 * Milestone 5 — real recursive rendering for the four container types
	 * the builder has supported since Milestone 2 but this file never
	 * rendered (confirmed gap, see FEATURE_STATUS.md's "Container Fields
	 * (0 of 4)" entry — not a regression). `row`'s children are always
	 * `column` nodes (enforced builder-side, see
	 * assets/src/builder/fields/classifications.js's CONTAINER_TYPES doc);
	 * everything else recurses back through render_field_row() exactly the
	 * way the top-level page loop in render_form_html() already does.
	 */
	private function render_container( array $field ) {
		$children = $field['children'] ?? [];

		if ( 'row' === $field['type'] ) {
			?>
			<div class="chargeforms-row"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
				<?php foreach ( $children as $column ) : ?>
					<div class="chargeforms-column" style="<?php echo esc_attr( $this->column_width_style( $column ) ); ?>">
						<?php foreach ( ( $column['children'] ?? [] ) as $child ) : ?>
							<?php $this->render_field_row( $child ); ?>
						<?php endforeach; ?>
					</div>
				<?php endforeach; ?>
			</div>
			<?php
			return;
		}

		if ( 'tabs' === $field['type'] ) {
			$this->render_tabs( $field );
			return;
		}

		if ( 'accordion' === $field['type'] ) {
			$this->render_accordion( $field );
			return;
		}

		if ( 'repeat_container' === $field['type'] ) {
			$this->render_repeater( $field );
			return;
		}

		$wrapper_classes = [ 'chargeforms-container', 'chargeforms-container-' . $field['type'] ];
		if ( ! empty( $field['containerClass'] ) ) {
			$wrapper_classes[] = $field['containerClass'];
		}
		?>
		<div class="<?php echo esc_attr( implode( ' ', $wrapper_classes ) ); ?>"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
			<?php if ( 'section' === $field['type'] && ! empty( $field['label'] ) ) : ?>
				<h3 class="chargeforms-container-title"><?php echo esc_html( $field['label'] ); ?></h3>
			<?php endif; ?>
			<?php foreach ( $children as $child ) : ?>
				<?php $this->render_field_row( $child ); ?>
			<?php endforeach; ?>
		</div>
		<?php
	}

	/** Real tab-switching needs JS (assets/js/frontend.js's initTabs()) — server renders every pane's markup with only the first visible, matching the no-flash-of-unstyled-content approach conditional_attrs() already uses elsewhere in this file. Works with JS disabled too: every pane's fields are still present and submittable, just all stacked visible (see the [data-fc-tabs] CSS fallback in frontend.css). */
/** role="tablist"/"tab"/"tabpanel" wiring (aria-selected, aria-controls/labelledby, roving tabindex) mirrors the WAI-ARIA APG tabs pattern — initTabs() in frontend.js keeps these attributes in sync on click/arrow-key activation. */
	private function render_tabs( array $field ) {
		$panes    = $field['children'] ?? [];
		$group_id = $field['id'];
		?>
		<div class="chargeforms-tabs" data-fc-tabs<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
			<div class="chargeforms-tabs-strip" role="tablist">
				<?php foreach ( $panes as $index => $pane ) :
					$is_active = 0 === $index;
					?>
					<button
						type="button"
						id="chargeforms-tab-<?php echo esc_attr( $group_id ); ?>-<?php echo (int) $index; ?>"
						class="chargeforms-tab-btn<?php echo $is_active ? ' is-active' : ''; ?>"
						role="tab"
						aria-selected="<?php echo $is_active ? 'true' : 'false'; ?>"
						aria-controls="chargeforms-tabpanel-<?php echo esc_attr( $group_id ); ?>-<?php echo (int) $index; ?>"
						tabindex="<?php echo $is_active ? '0' : '-1'; ?>"
						data-fc-tab-index="<?php echo (int) $index; ?>"
					><?php
					/* translators: %d: tab number, shown when the tab has no label of its own */
					echo esc_html( $pane['label'] ?: sprintf( __( 'Tab %d', 'chargeforms' ), $index + 1 ) );
					?></button>
				<?php endforeach; ?>
			</div>
			<?php foreach ( $panes as $index => $pane ) :
				$is_active = 0 === $index;
				?>
				<div
					id="chargeforms-tabpanel-<?php echo esc_attr( $group_id ); ?>-<?php echo (int) $index; ?>"
					class="chargeforms-tab-panel<?php echo $is_active ? ' is-active' : ''; ?>"
					role="tabpanel"
					aria-labelledby="chargeforms-tab-<?php echo esc_attr( $group_id ); ?>-<?php echo (int) $index; ?>"
					tabindex="0"
					data-fc-tab-panel="<?php echo (int) $index; ?>"
				>
					<?php foreach ( ( $pane['children'] ?? [] ) as $child ) : ?>
						<?php $this->render_field_row( $child ); ?>
					<?php endforeach; ?>
				</div>
			<?php endforeach; ?>
		</div>
		<?php
	}

	/** Native <details>/<summary> — real expand/collapse with zero JS required, full keyboard operability and screen-reader semantics for free from the browser itself. */
	private function render_accordion( array $field ) {
		$panels = $field['children'] ?? [];
		?>
		<div class="chargeforms-accordion"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
			<?php foreach ( $panels as $index => $panel ) : ?>
				<details class="chargeforms-accordion-panel"<?php echo 0 === $index ? ' open' : ''; ?>>
					<summary><?php
					/* translators: %d: panel number, shown when the panel has no label of its own */
					echo esc_html( $panel['label'] ?: sprintf( __( 'Panel %d', 'chargeforms' ), $index + 1 ) );
					?></summary>
					<div class="chargeforms-accordion-panel-body">
						<?php foreach ( ( $panel['children'] ?? [] ) as $child ) : ?>
							<?php $this->render_field_row( $child ); ?>
						<?php endforeach; ?>
					</div>
				</details>
			<?php endforeach; ?>
		</div>
		<?php
	}

	/**
	 * Milestone 5D — the hardest single piece of this milestone. `children`
	 * is the TEMPLATE (one instance of the repeated field group, built once
	 * in the builder); the front end needs to multiply it into `minRows`
	 * real rows (each with its own array-indexed field names so submission
	 * collects them as one array-of-rows per repeater, not N colliding
	 * single values) plus a JS-driven Add/Remove up to `maxRows`.
	 *
	 * Rather than threading a name-prefix parameter through render_field()'s
	 * ~30 cases (real risk of a typo silently breaking an unrelated field
	 * type elsewhere in the form), the template is rendered ONCE via output
	 * buffering and its `name="chargeforms_data[...]"` / `id="chargeforms-..."`
	 * attributes are rewritten per row with a regex — every existing field
	 * type's markup shape (plain name, array name, Address's nested
	 * `[id][sub]`) already matches the same `chargeforms_data[ID]` prefix
	 * pattern, so this needs no per-type awareness at all.
	 */
	private function render_repeater( array $field ) {
		$min_rows     = max( 1, (int) ( $field['minRows'] ?? 1 ) );
		$max_rows     = max( $min_rows, (int) ( $field['maxRows'] ?? 10 ) );
		$repeater_id  = $field['id'];
		$add_label    = $field['addButtonLabel'] ?? __( 'Add Another', 'chargeforms' );

		ob_start();
		foreach ( ( $field['children'] ?? [] ) as $child ) {
			$this->render_field_row( $child );
		}
		$template_html = ob_get_clean();
		?>
		<div class="chargeforms-repeater" data-fc-repeater="<?php echo esc_attr( $repeater_id ); ?>" data-fc-repeater-min="<?php echo (int) $min_rows; ?>" data-fc-repeater-max="<?php echo (int) $max_rows; ?>">
			<div class="chargeforms-repeater-rows">
				<?php for ( $i = 0; $i < $min_rows; $i++ ) : ?>
					<div class="chargeforms-repeater-row">
						<?php echo $this->rewrite_repeater_names( $template_html, $repeater_id, $i ); // phpcs:ignore ?>
						<button type="button" class="chargeforms-repeater-remove" <?php echo $min_rows >= $max_rows ? 'style="display:none;"' : ''; ?>><?php esc_html_e( 'Remove', 'chargeforms' ); ?></button>
					</div>
				<?php endfor; ?>
			</div>
			<template class="chargeforms-repeater-template">
				<div class="chargeforms-repeater-row">
					<?php echo $this->rewrite_repeater_names( $template_html, $repeater_id, '__INDEX__' ); // phpcs:ignore ?>
					<button type="button" class="chargeforms-repeater-remove"><?php esc_html_e( 'Remove', 'chargeforms' ); ?></button>
				</div>
			</template>
			<?php if ( $max_rows > $min_rows ) : ?>
				<button type="button" class="chargeforms-repeater-add"><?php echo esc_html( $add_label ); ?></button>
			<?php endif; ?>
		</div>
		<?php
	}

	/** See render_repeater()'s doc comment for why this is a regex rewrite rather than a threaded parameter. `$index` is either a real row number or the literal string '__INDEX__' for the <template> copy JS clones — assets/js/frontend.js's addRepeaterRow() does the same substitution client-side for a freshly-cloned row. */
	private function rewrite_repeater_names( $html, $repeater_id, $index ) {
		$html = preg_replace(
			'/chargeforms_data\[([a-zA-Z0-9_]+)\]/',
			'chargeforms_data[' . $repeater_id . '][' . $index . '][$1]',
			$html
		);
		return preg_replace(
			'/(id|for)="chargeforms-([a-zA-Z0-9_-]+)"/',
			'$1="chargeforms-' . $repeater_id . '-' . $index . '-$2"',
			$html
		);
	}

	/**
	 * Renders one node from the field tree: a container (recurses via
	 * render_container()) or a leaf field. `isHidden` (Milestone 5's
	 * per-instance "kept in the form, not shown to visitors" capability —
	 * see FieldSettings.js) short-circuits before either path; it's
	 * distinct from the existing `hidden` field TYPE (an actual HTML
	 * hidden input, still rendered) handled further down.
	 */
	private function render_field_row( array $field ) {
		if ( ! empty( $field['isHidden'] ) ) {
			return;
		}

		if ( in_array( $field['type'], self::CONTAINER_TYPES, true ) ) {
			$this->render_container( $field );
			return;
		}

		if ( 'section_break' === $field['type'] ) {
			?>
			<div class="chargeforms-section-break"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
				<h3><?php echo esc_html( $field['label'] ); ?></h3>
				<?php if ( ! empty( $field['description'] ) ) : ?>
					<p><?php echo esc_html( $field['description'] ); ?></p>
				<?php endif; ?>
			</div>
			<?php
			return;
		}

		if ( 'html' === $field['type'] || 'rich_text' === $field['type'] ) {
			?>
			<div class="chargeforms-html-block"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
				<?php echo wp_kses_post( $field['content'] ?? '' ); ?>
			</div>
			<?php
			return;
		}

		if ( 'hidden' === $field['type'] ) {
			$this->render_field( $field );
			return;
		}

		if ( 'payment_item' === $field['type'] ) {
			printf(
				'<div class="chargeforms-payment-item" data-fc-payment-amount="%s">
					<span>%s</span><strong>%s</strong>
				</div>',
				esc_attr( (float) ( $field['amount'] ?? 0 ) ),
				esc_html( $field['label'] ),
				esc_html( $this->format_money( (float) ( $field['amount'] ?? 0 ) ) )
			);
			return;
		}

		if ( 'payment_summary' === $field['type'] ) {
			printf(
				'<div class="chargeforms-payment-summary" data-fc-payment-total>%s <span>%s</span></div>',
				esc_html__( 'Total:', 'chargeforms' ),
				esc_html( $this->format_money( 0 ) )
			);
			return;
		}

		// Milestone 5C — Commerce & Calculation fields. Product/Price are
		// static "this costs $X" lines (same shape as the pre-existing
		// Payment Item above, just semantically distinct types); Subtotal/
		// Tax/Discount/Total are computed DISPLAY lines with no submitted
		// value of their own, live-updated by assets/js/frontend.js's
		// computeCommerce() via their data-fc-display attribute. Initial
		// server-rendered numbers are 0/blank — real values only exist
		// client-side once the visitor interacts with the form, same
		// honesty-about-what's-static-vs-live approach Payment Summary
		// above already established.
		if ( 'product' === $field['type'] || 'price' === $field['type'] ) {
			printf(
				'<div class="chargeforms-commerce-line" data-fc-commerce-amount="%s"><span>%s</span><strong>%s</strong></div>',
				esc_attr( (float) ( $field['price'] ?? 0 ) ),
				esc_html( $field['label'] ),
				esc_html( $this->format_money( (float) ( $field['price'] ?? 0 ) ) )
			);
			return;
		}

		if ( 'subtotal' === $field['type'] ) {
			printf(
				'<div class="chargeforms-commerce-line chargeforms-commerce-computed"><span>%s</span><strong data-fc-display="subtotal">%s</strong></div>',
				esc_html( $field['label'] ?: __( 'Subtotal', 'chargeforms' ) ),
				esc_html( $this->format_money( 0 ) )
			);
			return;
		}

		if ( 'tax' === $field['type'] ) {
			printf(
				'<div class="chargeforms-commerce-line chargeforms-commerce-computed" data-fc-tax-rate="%s"><span>%s</span><strong data-fc-display="tax">%s</strong></div>',
				esc_attr( (float) ( $field['rate'] ?? 0 ) ),
				esc_html( $field['label'] ?: __( 'Tax', 'chargeforms' ) ),
				esc_html( $this->format_money( 0 ) )
			);
			return;
		}

		if ( 'discount' === $field['type'] ) {
			printf(
				'<div class="chargeforms-commerce-line chargeforms-commerce-computed" data-fc-discount data-fc-discount-type="%s" data-fc-discount-value="%s"><span>%s</span><strong data-fc-display="discount">-%s</strong></div>',
				esc_attr( $field['discountType'] ?? 'fixed' ),
				esc_attr( (float) ( $field['discountValue'] ?? 0 ) ),
				esc_html( $field['label'] ?: __( 'Discount', 'chargeforms' ) ),
				esc_html( $this->format_money( 0 ) )
			);
			return;
		}

		if ( 'total' === $field['type'] ) {
			printf(
				'<div class="chargeforms-commerce-line chargeforms-commerce-total"><span>%s</span><strong data-fc-display="total">%s</strong></div>',
				esc_html( $field['label'] ?: __( 'Total', 'chargeforms' ) ),
				esc_html( $this->format_money( 0 ) )
			);
			return;
		}

		if ( 'formula' === $field['type'] ) {
			printf( '<div class="chargeforms-commerce-line chargeforms-formula-field"><span>%s</span><strong data-fc-formula data-fc-formula-expression="%s" data-fc-formula-id="%s">0</strong></div><input type="hidden" name="%s" value="0">', esc_html( $field['label'] ?? __( 'Calculated value', 'chargeforms' ) ), esc_attr( $field['expression'] ?? '' ), esc_attr( $field['id'] ), 'chargeforms_data[' . esc_attr( $field['id'] ) . ']' );
			return;
		}

		if ( 'quiz_score' === $field['type'] ) {
			printf( '<div class="chargeforms-quiz-score" data-fc-quiz-score data-fc-quiz-id="%1$s" data-fc-quiz-rules="%2$s" data-fc-quiz-results="%3$s"><span>%4$s</span><strong data-fc-quiz-value>0</strong><em data-fc-quiz-result></em></div>', esc_attr( $field['id'] ), esc_attr( wp_json_encode( is_array( $field['quizRules'] ?? null ) ? $field['quizRules'] : [] ) ), esc_attr( wp_json_encode( is_array( $field['quizResults'] ?? null ) ? $field['quizResults'] : [] ) ), esc_html( $field['label'] ?? __( 'Quiz score', 'chargeforms' ) ) );
			return;
		}

		// Math Field IS a real (if simple) two-operand calculation —
		// live-computed client-side from two other fields' current values,
		// distinct from Formula's honestly-unevaluated expression above.
		if ( 'math_field' === $field['type'] ) {
			printf(
				'<div class="chargeforms-commerce-line chargeforms-math-field"><span>%s</span><strong data-fc-math data-fc-math-a="%s" data-fc-math-b="%s" data-fc-math-op="%s" data-fc-math-id="%s">0</strong></div><input type="hidden" name="%s" value="0">',
				esc_html( $field['label'] ),
				esc_attr( $field['fieldA'] ?? '' ),
				esc_attr( $field['fieldB'] ?? '' ),
				esc_attr( $field['operator'] ?? '+' ),
				esc_attr( $field['id'] ),
				'chargeforms_data[' . esc_attr( $field['id'] ) . ']'
			);
			return;
		}

		if ( 'address' === $field['type'] ) {
			$this->render_address_field( $field );
			return;
		}

		if ( 'social_links' === $field['type'] ) {
			$this->render_social_links_field( $field );
			return;
		}

		$wrapper_classes = [ 'chargeforms-field', 'chargeforms-field-' . $field['type'] ];
		if ( ! empty( $field['labelPlacement'] ) && 'default' !== $field['labelPlacement'] ) {
			$wrapper_classes[] = 'chargeforms-field-label-' . $field['labelPlacement'];
		}
		if ( ! empty( $field['containerClass'] ) ) {
			$wrapper_classes[] = $field['containerClass'];
		}
		?>
		<div class="<?php echo esc_attr( implode( ' ', $wrapper_classes ) ); ?>"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
			<label for="<?php echo esc_attr( $this->field_html_id( $field ) ); ?>">
				<?php echo esc_html( $field['label'] ); ?>
				<?php if ( ! empty( $field['required'] ) ) : ?><span class="req">*</span><?php endif; ?>
				<?php if ( ! empty( $field['tooltip'] ) ) : ?>
					<?php /* aria-label carries the tooltip to screen readers unconditionally — a hover-only "title" attribute alone would repeat the exact pitfall the reference product's own accessibility guide warns against for beside-label help text. */ ?>
					<span class="chargeforms-field-tooltip" tabindex="0" role="img" aria-label="<?php echo esc_attr( $field['tooltip'] ); ?>" title="<?php echo esc_attr( $field['tooltip'] ); ?>">?</span>
				<?php endif; ?>
			</label>
			<?php $this->render_field( $field ); ?>
			<?php if ( ! empty( $field['helpMessage'] ) ) : ?>
				<span id="<?php echo esc_attr( $this->field_help_id( $field ) ); ?>" class="chargeforms-field-help"><?php echo esc_html( $field['helpMessage'] ); ?></span>
			<?php endif; ?>
		</div>
		<?php
	}

	/** Fields rendered as a plain text-type <input> — the set that supports placeholder/default/prefix/suffix/max-length. */
	const TEXT_LIKE_TYPES = [ 'text', 'email', 'number', 'phone', 'url', 'password', 'name', 'post_title', 'tags' ];

	/** Plain data for the Country List field — mirrors assets/src/builder/fields.js COUNTRIES exactly. */
	const COUNTRIES = [
		'United States', 'United Kingdom', 'Canada', 'Australia', 'Germany', 'France', 'Italy', 'Spain',
		'Netherlands', 'Belgium', 'Switzerland', 'Sweden', 'Norway', 'Denmark', 'Finland', 'Ireland',
		'Portugal', 'Austria', 'Poland', 'Greece', 'India', 'Pakistan', 'Bangladesh', 'China', 'Japan',
		'South Korea', 'Singapore', 'Malaysia', 'Indonesia', 'Philippines', 'Vietnam', 'Thailand',
		'United Arab Emirates', 'Saudi Arabia', 'Qatar', 'Turkey', 'Egypt', 'South Africa', 'Nigeria',
		'Kenya', 'Brazil', 'Mexico', 'Argentina', 'Chile', 'Colombia', 'Peru', 'New Zealand',
	];

	/**
	 * The Address field is a composite of five sub-inputs sharing one field
	 * id (chargeforms_data[id][street], [city], [state], [zip], [country]) —
	 * stored and validated as one associative array, not five separate
	 * fields, so it stays a single row in Entries rather than five.
	 */
	private function render_address_field( array $field ) {
		$id       = esc_attr( $field['id'] );
		$name     = 'chargeforms_data[' . esc_attr( $field['id'] ) . ']';
		$provider = $field['autocompleteProvider'] ?? 'default';
		if ( 'default' === $provider ) {
			$provider = Settings::get( 'address_autocomplete_provider', 'none' );
		}
		$autocomplete_on = in_array( $provider, [ 'osm', 'google' ], true );
		?>
		<div
			class="chargeforms-field chargeforms-field-address<?php echo $autocomplete_on ? ' has-autocomplete' : ''; ?>"
			<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>
			<?php if ( $autocomplete_on ) : ?>
				data-fc-address-provider="<?php echo esc_attr( $provider ); ?>"
				data-fc-address-geolocation="<?php echo esc_attr( $field['geolocation'] ?? 'off' ); ?>"
				<?php if ( ! empty( $field['showMap'] ) ) : ?>data-fc-address-map="1"<?php endif; ?>
				<?php if ( ! empty( $field['saveCoordinates'] ) ) : ?>data-fc-address-save-coords="1"<?php endif; ?>
			<?php endif; ?>
		>
			<label>
				<?php echo esc_html( $field['label'] ); ?>
				<?php if ( ! empty( $field['required'] ) ) : ?><span class="req">*</span><?php endif; ?>
			</label>
			<div class="chargeforms-address-fields">
				<?php if ( $autocomplete_on && 'on_click' === ( $field['geolocation'] ?? 'off' ) ) : ?>
					<button type="button" class="chargeforms-address-geolocate-btn"><?php esc_html_e( 'Use my location', 'chargeforms' ); ?></button>
				<?php endif; ?>
				<div class="chargeforms-address-street-wrap">
					<input type="text" id="chargeforms-<?php echo esc_attr( $id ); ?>-street" name="<?php echo esc_attr( $name ); ?>[street]" placeholder="<?php esc_attr_e( 'Street Address', 'chargeforms' ); ?>" <?php echo $autocomplete_on ? 'autocomplete="off"' : ''; ?>>
					<?php if ( $autocomplete_on ) : ?>
						<div class="chargeforms-address-suggestions" role="listbox" hidden></div>
					<?php endif; ?>
				</div>
				<div class="chargeforms-address-row">
					<input type="text" name="<?php echo esc_attr( $name ); ?>[city]" placeholder="<?php esc_attr_e( 'City', 'chargeforms' ); ?>">
					<input type="text" name="<?php echo esc_attr( $name ); ?>[state]" placeholder="<?php esc_attr_e( 'State / Province', 'chargeforms' ); ?>">
				</div>
				<div class="chargeforms-address-row">
					<input type="text" name="<?php echo esc_attr( $name ); ?>[zip]" placeholder="<?php esc_attr_e( 'ZIP / Postal Code', 'chargeforms' ); ?>">
					<select name="<?php echo esc_attr( $name ); ?>[country]">
						<option value=""><?php esc_html_e( 'Country', 'chargeforms' ); ?></option>
						<?php foreach ( self::COUNTRIES as $country ) : ?>
							<option value="<?php echo esc_attr( $country ); ?>"><?php echo esc_html( $country ); ?></option>
						<?php endforeach; ?>
					</select>
				</div>
				<?php if ( $autocomplete_on && ! empty( $field['saveCoordinates'] ) ) : ?>
					<input type="hidden" name="<?php echo esc_attr( $name ); ?>[lat]" class="chargeforms-address-lat">
					<input type="hidden" name="<?php echo esc_attr( $name ); ?>[lng]" class="chargeforms-address-lng">
				<?php endif; ?>
				<?php if ( $autocomplete_on && ! empty( $field['showMap'] ) ) : ?>
					<div class="chargeforms-address-map" hidden></div>
				<?php endif; ?>
			</div>
		</div>
		<?php
	}

	/**
	 * Real UX gap found live: this used to be six fixed platforms
	 * (Facebook/Twitter/Instagram/LinkedIn/YouTube/TikTok), each its own
	 * named sub-field (`chargeforms_data[id][facebook]`, etc). A visitor
	 * whose actual platform wasn't one of those six (Threads, Bluesky,
	 * Discord, WhatsApp, a personal site...) had nowhere to put it, and a
	 * site collecting a niche platform's link couldn't add it without a
	 * code change. Rebuilt as a plain, unlimited add/remove list of URL
	 * inputs instead — one link per row, no platform concept at all — by
	 * reusing the exact same `data-fc-repeater` markup contract
	 * render_repeater() already established for the Repeater field type,
	 * so assets/src/frontend/frontend-entry.js's initRepeaters() wires the
	 * Add/Remove buttons up for free with zero new JS. `minRows`/`maxRows`
	 * mean exactly what they mean there. Submission_Handler already treats
	 * `social_links` as one of its `$expects_array` types (see
	 * has_field_type_gate_free... i.e. class-submission-handler.php) purely
	 * by field type, with no assumption about which keys the array has —
	 * a plain 0-indexed array of URLs needs no change on that side.
	 */
	private function render_social_links_field( array $field ) {
		$id         = esc_attr( $field['id'] );
		$name       = 'chargeforms_data[' . esc_attr( $field['id'] ) . ']';
		$min_rows   = max( 1, (int) ( $field['minRows'] ?? 1 ) );
		$max_rows   = max( $min_rows, (int) ( $field['maxRows'] ?? 10 ) );
		$add_label  = $field['addButtonLabel'] ?? __( 'Add Another Link', 'chargeforms' );
		$row_markup = static function ( $index ) use ( $id, $name ) {
			return sprintf(
				'<input type="url" id="chargeforms-%s-%s" name="%s[%s]" placeholder="%s">',
				$id,
				esc_attr( $index ),
				$name,
				esc_attr( $index ),
				esc_attr__( 'https://…', 'chargeforms' )
			);
		};
		?>
		<div class="chargeforms-field chargeforms-field-social_links"<?php echo wp_kses( $this->conditional_attrs( $field ), [] ); ?>>
			<label>
				<?php echo esc_html( $field['label'] ); ?>
				<?php if ( ! empty( $field['required'] ) ) : ?><span class="req">*</span><?php endif; ?>
			</label>
			<div class="chargeforms-repeater chargeforms-repeater--links" data-fc-repeater="<?php echo esc_attr( $id ); ?>" data-fc-repeater-min="<?php echo (int) $min_rows; ?>" data-fc-repeater-max="<?php echo (int) $max_rows; ?>">
				<div class="chargeforms-repeater-rows">
					<?php for ( $i = 0; $i < $min_rows; $i++ ) : ?>
						<div class="chargeforms-repeater-row">
							<?php echo $row_markup( $i ); // phpcs:ignore ?>
							<button type="button" class="chargeforms-repeater-remove" <?php echo $min_rows >= $max_rows ? 'style="display:none;"' : ''; ?>><?php esc_html_e( 'Remove', 'chargeforms' ); ?></button>
						</div>
					<?php endfor; ?>
				</div>
				<template class="chargeforms-repeater-template">
					<div class="chargeforms-repeater-row">
						<?php echo $row_markup( '__INDEX__' ); // phpcs:ignore ?>
						<button type="button" class="chargeforms-repeater-remove"><?php esc_html_e( 'Remove', 'chargeforms' ); ?></button>
					</div>
				</template>
				<?php if ( $max_rows > $min_rows ) : ?>
					<button type="button" class="chargeforms-repeater-add"><?php echo esc_html( $add_label ); ?></button>
				<?php endif; ?>
			</div>
		</div>
		<?php
	}

	/**
	 * Outputs a data-fc-rule="{...}" attribute (consumed by assets/src/
	 * frontend/conditional.js) carrying the field's `logicRule` VERBATIM —
	 * the engine's own Rule shape, not a translated/compiled copy of it.
	 * field.logicRule IS already the shape the shared evaluator consumes
	 * (Rule_Migrator permanently converts the legacy field.conditional
	 * shape at the data layer — see includes/logic/class-rule-migrator.php
	 * — there is no compile step left here), so this function's only job
	 * is deciding the initial inline display style (so the field doesn't
	 * flash visible/hidden before JS evaluates the rule) and serializing.
	 */
	private function conditional_attrs( array $field ) {
		$rule = $field['logicRule'] ?? null;
		if ( empty( $rule['enabled'] ) || empty( $rule['trigger']['children'] ) ) {
			return '';
		}

		// A field starts hidden only if a matching action for THIS field is
		// 'show' (revealed once the condition passes) and not also 'hide'
		// (if both somehow target the same field, default to visible —
		// never falsely hide real content over an ambiguous rule).
		$shows_this_field = false;
		$hides_this_field = false;
		foreach ( $rule['actions'] ?? [] as $action ) {
			if ( ( $action['target'] ?? null ) !== $field['id'] ) {
				continue;
			}
			if ( 'show' === $action['type'] ) {
				$shows_this_field = true;
			}
			if ( 'hide' === $action['type'] ) {
				$hides_this_field = true;
			}
		}
		$initially_hidden = $shows_this_field && ! $hides_this_field;

		$style = $initially_hidden ? ' style="display:none;"' : '';

		return ' data-fc-rule="' . esc_attr( wp_json_encode( $rule ) ) . '" data-fc-field-id="' . esc_attr( $field['id'] ) . '"' . $style;
	}

	/** Allowed markup for add-on-provided custom fields. */
	public static function allowed_form_html() {
		$allowed = wp_kses_allowed_html( 'post' );
		$common  = [
			'id' => true, 'class' => true, 'title' => true, 'style' => true,
			'aria-label' => true, 'aria-describedby' => true, 'aria-required' => true,
			'data-fc-field-id' => true, 'data-fc-rule' => true,
		];
		foreach ( [
			'data-chains', 'data-digits', 'data-digits-message', 'data-fc-address-geolocation',
			'data-fc-address-map', 'data-fc-address-provider', 'data-fc-address-save-coords',
			'data-fc-commerce-amount', 'data-fc-commerce-qty', 'data-fc-commerce-shipping',
			'data-fc-context', 'data-fc-cost', 'data-fc-custom-amount', 'data-fc-discount',
			'data-fc-discount-type', 'data-fc-discount-value', 'data-fc-display',
			'data-fc-draft-banner', 'data-fc-draft-discard', 'data-fc-draft-email-btn',
			'data-fc-draft-email-input', 'data-fc-draft-resume', 'data-fc-draft-save',
			'data-fc-draft-saved-at', 'data-fc-draft-status', 'data-fc-formula',
			'data-fc-formula-expression', 'data-fc-formula-id', 'data-fc-mask', 'data-fc-math',
			'data-fc-math-a', 'data-fc-math-b', 'data-fc-math-id', 'data-fc-math-op',
			'data-fc-payment-amount', 'data-fc-payment-total', 'data-fc-paypal-config',
			'data-fc-quiz-id', 'data-fc-quiz-result', 'data-fc-quiz-results', 'data-fc-quiz-rules',
			'data-fc-quiz-score', 'data-fc-quiz-value', 'data-fc-ranking', 'data-fc-repeater',
			'data-fc-repeater-max', 'data-fc-repeater-min', 'data-fc-signature',
			'data-fc-stripe-config', 'data-fc-tab-index', 'data-fc-tab-panel', 'data-fc-tabs',
			'data-fc-tax-rate', 'data-fc-unit-price', 'data-format-message', 'data-n',
			'data-required-message', 'data-sitekey', 'data-step', 'data-value',
		] as $data_attribute ) {
			$common[ $data_attribute ] = true;
		}
		$allowed['input'] = array_merge( $common, [
			'type' => true, 'name' => true, 'value' => true, 'placeholder' => true,
			'required' => true, 'readonly' => true, 'disabled' => true, 'checked' => true,
			'min' => true, 'max' => true, 'step' => true, 'multiple' => true, 'accept' => true,
			'minlength' => true, 'maxlength' => true, 'pattern' => true, 'autocomplete' => true,
			'tabindex' => true,
		] );
		$allowed['select'] = array_merge( $common, [ 'name' => true, 'required' => true, 'disabled' => true, 'multiple' => true ] );
		$allowed['option'] = [ 'value' => true, 'selected' => true, 'disabled' => true ];
		$allowed['textarea'] = array_merge( $common, [ 'name' => true, 'placeholder' => true, 'required' => true, 'readonly' => true, 'disabled' => true, 'rows' => true, 'cols' => true ] );
		$allowed['label'] = array_merge( $common, [ 'for' => true ] );
		$allowed['button'] = array_merge( $common, [ 'type' => true, 'name' => true, 'value' => true, 'disabled' => true ] );
		$allowed['form'] = array_merge( $common, [ 'method' => true, 'action' => true, 'enctype' => true, 'novalidate' => true, 'data-chargeforms-track-url' => true, 'data-chargeforms-nonce-url' => true, 'data-chargeforms-rest-nonce' => true, 'data-fc-draft-config' => true, 'data-fc-logic-context' => true ] );
		$allowed['svg'] = array_merge( $common, [ 'width' => true, 'height' => true, 'viewbox' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true, 'stroke-linecap' => true, 'stroke-linejoin' => true, 'aria-hidden' => true, 'focusable' => true ] );
		foreach ( [ 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'ellipse' ] as $svg_tag ) {
			$allowed[ $svg_tag ] = [ 'd' => true, 'cx' => true, 'cy' => true, 'r' => true, 'rx' => true, 'ry' => true, 'x' => true, 'y' => true, 'x1' => true, 'x2' => true, 'y1' => true, 'y2' => true, 'width' => true, 'height' => true, 'points' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true ];
		}
		return apply_filters( 'chargeforms_allowed_form_html', $allowed );
	}

	private function render_field( array $field ) {
		// the reference product parity — its free tier docs this as "populate from
		// URL parameters": a field's static Default Value can instead
		// contain {query.param_name} placeholders, resolved once here
		// against the CURRENT page load's own query string (not the
		// referer's — Context_Builder::current_request_query_params() was
		// already written for exactly this and sanitizes every value, but
		// had no caller anywhere in the codebase until now). Resolved once
		// per field, before any of the per-type render branches below read
		// $field['default'], so every field type gets this for free without
		// each one needing its own substitution call.
		if ( ! empty( $field['default'] ) && is_string( $field['default'] ) && false !== strpos( $field['default'], '{query.' ) ) {
			$field['default'] = self::resolve_query_placeholders( $field['default'] );
		}

		$id       = esc_attr( $this->field_html_id( $field ) );
		$name     = 'chargeforms_data[' . esc_attr( $field['id'] ) . ']';
		$extra    = $this->extra_input_attrs( $field );

		/**
		 * Lets an add-on render a field type this switch doesn't know about.
		 *
		 * Returning a non-null string short-circuits the built-in rendering
		 * entirely, which is what a genuinely new field type needs — the
		 * switch below has no default branch, so without this an unknown
		 * type renders nothing at all and the field silently vanishes from
		 * the form.
		 *
		 * The returned markup is echoed as-is, so a listener owns escaping
		 * its own output. It must also use the $name passed here for its
		 * input, or the submitted value won't reach $values under the
		 * field's id.
		 *
		 * The form id is passed explicitly because a listener has no other
		 * reliable way to get it — the field array doesn't carry it, and
		 * get_the_ID() is the post the form is embedded in, not the form.
		 *
		 * @param string|null $html    Null to fall through to built-in rendering.
		 * @param array       $field   The field definition.
		 * @param string      $name    The input name this field must post under.
		 * @param string      $id      The field's HTML id.
		 * @param int         $form_id The form being rendered.
		 */
		$custom = apply_filters( 'chargeforms_render_custom_field', null, $field, $name, $id, $this->current_form_id );
		if ( null !== $custom ) {
			echo wp_kses( $custom, self::allowed_form_html() );
			return;
		}

		// TEXT_LIKE_TYPES delegates to render_text_like(), which computes
		// its own $required + tabindex independently — must not also
		// increment the tabindex counter here, or those fields double-count.
		if ( in_array( $field['type'], self::TEXT_LIKE_TYPES, true ) ) {
			$html_types = [ 'name' => 'text', 'phone' => 'tel' ];
			$this->render_text_like( $field, $html_types[ $field['type'] ] ?? $field['type'] );
			return;
		}

		$required = $this->required_attr( $field );

		switch ( $field['type'] ) {
			case 'textarea':
			case 'post_content':
			case 'post_excerpt':
				$validation  = is_array( $field['validation'] ?? null ) ? $field['validation'] : [];
				$constraints = '';
				if ( ! empty( $validation['minLength'] ) ) {
					$constraints .= sprintf( ' minlength="%d"', (int) $validation['minLength'] );
				}
				if ( ! empty( $validation['customMessage'] ) ) {
					$constraints .= sprintf( ' title="%s"', esc_attr( $validation['customMessage'] ) );
				}
				printf(
					'<textarea id="%s" name="%s" class="%s" placeholder="%s" maxlength="%s"%s %s%s>%s</textarea>',
					esc_attr( $id ),
					esc_attr( $name ),
					esc_attr( $field['elementClass'] ?? '' ),
					esc_attr( ! empty( $field['placeholder'] ) ? $field['placeholder'] : $this->default_placeholder_for( $field ) ),
					esc_attr( $field['maxLength'] ?? '' ),
					wp_kses( $constraints, [] ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] ),
					esc_textarea( $field['default'] ?? '' )
				);
				break;
			case 'chained_select':
				$chains = is_array( $field['chains'] ?? null ) ? array_values( $field['chains'] ) : [];
				$chains = array_values( array_filter( $chains, static function ( $chain ) { return is_array( $chain ) && ! empty( $chain['options'] ) && is_array( $chain['options'] ); } ) );
				if ( empty( $chains ) ) {
					printf( '<select id="%s" name="%s[0]" %s%s><option value="">%s</option></select>', $id, $name, $required, $extra, esc_html__( 'Choose an option', 'chargeforms' ) );
					break;
				}
				$chain_json = wp_json_encode( $chains );
				echo '<div class="chargeforms-chained-select" data-chains="' . esc_attr( $chain_json ) . '">';
				foreach ( $chains as $index => $chain ) {
					$level_id = $id . '-' . $index;
					printf( '<label for="%1$s">%2$s</label><select id="%1$s" name="%3$s[%4$d]"%5$s%6$s><option value="">%7$s</option>', esc_attr( $level_id ), esc_html( $chain['label'] ?? sprintf( __( 'Level %d', 'chargeforms' ), $index + 1 ) ), $name, (int) $index, 0 === $index ? $required : '', $extra, esc_html__( 'Choose an option', 'chargeforms' ) );
					foreach ( $chain['options'] as $option ) { if ( is_array( $option ) ) { printf( '<option value="%1$s"%3$s>%2$s</option>', esc_attr( $option['value'] ?? '' ), esc_html( $option['label'] ?? $option['value'] ?? '' ), 0 === $index || empty( $option['parent'] ) ? '' : ' hidden' ); } }
					echo '</select>';
				}
				echo '</div>';
				break;
			case 'select':
				printf( '<select id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				foreach ( $field['options'] ?? [] as $option ) {
					printf( '<option value="%1$s">%1$s</option>', esc_attr( $option ) );
				}
				echo '</select>';
				break;
			case 'dynamic_field':
				printf( '<select id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				$options = $field['options'] ?? [];
				if ( empty( $options ) ) { $options = array_map( static function ( $post ) { return [ 'value' => (string) $post->ID, 'label' => $post->post_title ?: __( '(no title)', 'chargeforms' ) ]; }, get_posts( [ 'post_type' => 'post', 'post_status' => 'publish', 'numberposts' => 100, 'orderby' => 'title', 'order' => 'ASC' ] ) ); }
				foreach ( $options as $option ) { $option = is_array( $option ) ? $option : [ 'value' => $option, 'label' => $option ]; printf( '<option value="%1$s">%2$s</option>', esc_attr( $option['value'] ?? '' ), esc_html( $option['label'] ?? '' ) ); }
				echo '</select>';
				break;
			case 'checkable_grid':
				$rows = array_values( array_filter( $field['options'] ?? [] ) );
				$columns = array_values( array_filter( $field['gridColumns'] ?? [ 'Yes', 'No' ] ) );
				echo '<div class="chargeforms-checkable-grid"><table><thead><tr><th></th>';
				foreach ( $columns as $column ) { printf( '<th>%s</th>', esc_html( $column ) ); }
				echo '</tr></thead><tbody>';
				foreach ( $rows as $row_index => $row ) { $row_label = is_array( $row ) ? ( $row['label'] ?? $row['value'] ?? $row_index ) : $row; echo '<tr><th scope="row">' . esc_html( $row_label ) . '</th>'; foreach ( $columns as $column_index => $column ) { printf( '<td><input type="checkbox" name="%1$s[%2$d][%3$d]" value="1"%4$s></td>', esc_attr( $name ), (int) $row_index, (int) $column_index, $extra ); } echo '</tr>'; }
				echo '</tbody></table></div>';
				break;
			case 'post_update':
				printf( '<select id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				$options = $field['options'] ?? [];
				if ( empty( $options ) && is_user_logged_in() ) {
					$options = array_map( static function ( $post ) {
						return [ 'value' => (string) $post->ID, 'label' => $post->post_title ? $post->post_title : __( '(no title)', 'chargeforms' ) ];
					}, get_posts( [ 'post_type' => [ 'post', 'page' ], 'post_status' => [ 'publish', 'draft', 'pending', 'private' ], 'author' => get_current_user_id(), 'numberposts' => 100, 'orderby' => 'modified', 'order' => 'DESC' ] ) );
				}
				foreach ( $options as $option ) {
					$option = is_array( $option ) ? $option : [ 'value' => $option, 'label' => $option ];
					printf( '<option value="%1$s">%2$s</option>', esc_attr( $option['value'] ?? '' ), esc_html( $option['label'] ?? $option['value'] ?? '' ) );
				}
				echo '</select>';
				break;
			case 'categories':
				printf( '<select id="%s" name="%s[]" multiple="multiple" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				$options = $field['options'] ?? [];
				if ( empty( $options ) ) {
					$taxonomy = sanitize_key( $field['taxonomy'] ?? 'category' );
					if ( ! taxonomy_exists( $taxonomy ) ) {
						$taxonomy = 'category';
					}
					$terms = get_terms( [ 'taxonomy' => $taxonomy, 'hide_empty' => false ] );
					$options = is_wp_error( $terms ) ? [] : array_map( static function ( $category ) {
						return [ 'value' => (string) $category->term_id, 'label' => $category->name ];
					}, $terms );
				}
				foreach ( $options as $option ) {
					$option = is_array( $option ) ? $option : [ 'value' => $option, 'label' => $option ];
					printf( '<option value="%1$s">%2$s</option>', esc_attr( $option['value'] ?? '' ), esc_html( $option['label'] ?? $option['value'] ?? '' ) );
				}
				echo '</select>';
				break;
			case 'radio':
				echo '<div class="chargeforms-radio-group">';
				foreach ( $field['options'] ?? [] as $index => $option ) {
					printf(
						'<label class="chargeforms-radio-option"><input type="radio" name="%s" value="%s" %s%s> %s</label>',
						esc_attr( $name ),
						esc_attr( $option ),
						wp_kses( 0 === $index ? $required : '', [] ),
						wp_kses( $extra, [] ),
						esc_html( $option )
					);
				}
				echo '</div>';
				break;
			case 'checkbox':
				printf( '<input type="checkbox" id="%s" name="%s" value="1" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				break;
			case 'date':
				printf( '<input type="date" id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				break;
			case 'time':
				printf( '<input type="time" id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				break;
			case 'datetime':
				printf( '<input type="datetime-local" id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				break;
			case 'quantity':
				printf(
					'<input type="number" id="%s" name="%s" min="%s" max="%s" step="%s" value="%s" data-fc-commerce-qty data-fc-unit-price="%s" %s%s>',
					esc_attr( $id ),
					esc_attr( $name ),
					esc_attr( $field['min'] ?? 1 ),
					esc_attr( $field['max'] ?? 99 ),
					esc_attr( $field['step'] ?? 1 ),
					esc_attr( $field['default'] ?? ( $field['min'] ?? 1 ) ),
					esc_attr( (float) ( $field['unitPrice'] ?? 0 ) ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] )
				);
				break;
			case 'coupon':
				printf(
					'<div class="chargeforms-coupon-field"><input type="text" id="%s" name="%s" placeholder="%s" %s%s><span class="chargeforms-coupon-note">%s</span></div>',
					esc_attr( $id ),
					esc_attr( $name ),
					esc_attr( $field['placeholder'] ?? __( 'Enter coupon code', 'chargeforms' ) ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] ),
					esc_html__( 'Applied at checkout — not validated here yet.', 'chargeforms' )
				);
				break;
			case 'shipping':
				echo '<div class="chargeforms-shipping-options">';
				foreach ( $field['shippingOptions'] ?? [] as $index => $option ) {
					printf(
						'<label class="chargeforms-shipping-option"><input type="radio" name="%s" value="%s" data-fc-commerce-shipping data-fc-cost="%s" %s><span>%s</span><strong>%s</strong></label>',
						esc_attr( $name ),
						esc_attr( $option['label'] ?? '' ),
						esc_attr( (float) ( $option['cost'] ?? 0 ) ),
						wp_kses( 0 === $index ? $this->required_attr( $field ) : '', [] ),
						esc_html( $option['label'] ?? '' ),
						esc_html( $this->format_money( (float) ( $option['cost'] ?? 0 ) ) )
					);
				}
				echo '</div>';
				break;
			case 'toggle':
				printf(
					'<label class="chargeforms-toggle-field"><input type="checkbox" id="%s" name="%s" value="1" %s%s%s><span class="chargeforms-toggle-track"><span class="chargeforms-toggle-thumb"></span></span></label>',
					esc_attr( $id ),
					esc_attr( $name ),
					! empty( $field['default'] ) ? 'checked ' : '',
					wp_kses( $required, [] ),
					wp_kses( $extra, [] )
				);
				break;
			case 'image_choice':
				$input_type = ! empty( $field['multiple'] ) ? 'checkbox' : 'radio';
				echo '<div class="chargeforms-image-choice">';
				foreach ( $field['imageOptions'] ?? [] as $index => $option ) {
					printf(
						'<label class="chargeforms-image-choice-option"><input type="%s" name="%s%s" value="%s" %s><span class="chargeforms-image-choice-thumb">%s</span><span>%s</span></label>',
						esc_attr( $input_type ),
						esc_attr( $name ),
						'checkbox' === $input_type ? '[]' : '',
						esc_attr( $option['label'] ?? '' ),
						wp_kses( 0 === $index ? $required : '', [] ),
						! empty( $option['image'] ) ? '<img src="' . esc_url( $option['image'] ) . '" alt="">' : '',
						esc_html( $option['label'] ?? '' )
					);
				}
				echo '</div>';
				break;
			case 'hidden':
				printf( '<input type="hidden" id="chargeforms-%s" name="%s" value="%s">', esc_attr( $id ), esc_attr( $name ), esc_attr( $field['default'] ?? '' ) );
				break;
			case 'file':
			case 'featured_image':
				$accept = ! empty( $field['allowedExtensions'] )
					? implode( ',', array_map( fn( $ext ) => '.' . ltrim( trim( $ext ), '.' ), explode( ',', $field['allowedExtensions'] ) ) )
					: '';
				printf(
					'<input type="file" id="%s" name="%s" accept="%s" %s%s>',
					esc_attr( $id ),
					esc_attr( $name ),
					esc_attr( $accept ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] )
				);
				if ( ! empty( $field['allowedExtensions'] ) || ! empty( $field['maxSizeMb'] ) ) {
					printf(
						'<p class="chargeforms-file-hint">%s</p>',
						esc_html( sprintf(
							/* translators: 1: allowed extensions, 2: max size in MB */
							__( 'Allowed: %1$s — max %2$sMB', 'chargeforms' ),
							$field['allowedExtensions'] ?? '',
							$field['maxSizeMb'] ?? 5
						) )
					);
				}
				break;
			case 'multi_select':
				printf( '<select id="%s" name="%s[]" multiple %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				foreach ( $field['options'] ?? [] as $option ) {
					printf( '<option value="%1$s">%1$s</option>', esc_attr( $option ) );
				}
				echo '</select>';
				break;
			case 'terms':
			case 'gdpr':
			case 'consent':
				printf(
					'<label class="chargeforms-consent-option"><input type="checkbox" id="%s" name="%s" value="1" %s%s> <span>%s</span></label>',
					esc_attr( $id ),
					esc_attr( $name ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] ),
					wp_kses_post( $field['content'] ?? '' )
				);
				break;
			case 'recaptcha':
				$this->render_recaptcha( $id, $name );
				break;
			case 'custom_amount':
				printf(
					'<input type="number" id="%s" name="%s" data-fc-custom-amount min="%s" step="0.01" placeholder="%s" %s%s>',
					esc_attr( $id ),
					esc_attr( $name ),
					esc_attr( (float) ( $field['minAmount'] ?? 0 ) ),
					esc_attr( $this->format_money( (float) ( $field['minAmount'] ?? 0 ) ) ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] )
				);
				break;
			case 'payment_method':
				$this->render_payment_method( $id, $name, $field );
				break;
			case 'hcaptcha':
				$this->render_hcaptcha( $id, $name );
				break;
			case 'turnstile':
				$this->render_turnstile( $id, $name );
				break;
			case 'range_slider':
				printf(
					'<input type="range" id="%s" name="%s" min="%s" max="%s" step="%s" value="%s" oninput="this.nextElementSibling.textContent=this.value" %s%s>
					<output>%s</output>',
					esc_attr( $id ), esc_attr( $name ),
					esc_attr( $field['min'] ?? 0 ), esc_attr( $field['max'] ?? 100 ), esc_attr( $field['step'] ?? 1 ),
					esc_attr( $field['default'] ?? ( $field['min'] ?? 0 ) ),
					wp_kses( $required, [] ),
					wp_kses( $extra, [] ),
					esc_html( $field['default'] ?? ( $field['min'] ?? 0 ) )
				);
				break;
			case 'ratings':
				$max = (int) ( $field['maxStars'] ?? 5 );
				echo '<div class="chargeforms-star-rating">';
				for ( $i = $max; $i >= 1; $i-- ) {
					printf(
						'<input type="radio" id="chargeforms-%1$s-%2$d" name="%3$s" value="%2$d" %4$s><label for="chargeforms-%1$s-%2$d">&#9733;</label>',
						esc_attr( $id ), (int) $i, esc_attr( $name ), wp_kses( 0 === ( $max - $i ) ? $required : '', [] )
					);
				}
				echo '</div>';
				break;
			case 'nps':
				echo '<div class="chargeforms-nps-scale">';
				for ( $i = 0; $i <= 10; $i++ ) {
					printf(
						'<label class="chargeforms-nps-option"><input type="radio" name="%s" value="%d" %s><span>%d</span></label>',
						esc_attr( $name ), (int) $i, wp_kses( 0 === $i ? $required : '', [] ), (int) $i
					);
				}
				echo '</div>';
				if ( ! empty( $field['lowLabel'] ) || ! empty( $field['highLabel'] ) ) {
					printf(
						'<div class="chargeforms-nps-labels"><span>%s</span><span>%s</span></div>',
						esc_html( $field['lowLabel'] ?? '' ),
						esc_html( $field['highLabel'] ?? '' )
					);
				}
				break;
			case 'multiple_choice':
				echo '<div class="chargeforms-checkbox-group">';
				foreach ( $field['options'] ?? [] as $option ) {
					printf(
						'<label class="chargeforms-checkbox-option"><input type="checkbox" name="%s[]" value="%s"> %s</label>',
						esc_attr( $name ), esc_attr( $option ), esc_html( $option )
					);
				}
				echo '</div>';
				break;
			case 'ranking':
				$options = array_values( array_filter( array_map( 'strval', (array) ( $field['options'] ?? [] ) ) ) );
				echo '<ol class="chargeforms-ranking" data-fc-ranking>';
				foreach ( $options as $index => $option ) {
					printf( '<li draggable="true" data-value="%1$s"><span class="chargeforms-ranking-label">%2$s</span><input type="hidden" name="%3$s[%4$d]" value="%1$s"><button type="button" class="chargeforms-ranking-up" aria-label="%5$s">↑</button><button type="button" class="chargeforms-ranking-down" aria-label="%6$s">↓</button></li>', esc_attr( $option ), esc_html( $option ), $name, (int) $index, esc_attr__( 'Move up', 'chargeforms' ), esc_attr__( 'Move down', 'chargeforms' ) );
				}
				echo '</ol>';
				break;
			case 'country':
				printf( '<select id="%s" name="%s" %s%s>', esc_attr( $id ), esc_attr( $name ), wp_kses( $required, [] ), wp_kses( $extra, [] ) );
				echo '<option value="">' . esc_html__( 'Select a country', 'chargeforms' ) . '</option>';
				foreach ( self::COUNTRIES as $country ) {
					printf( '<option value="%1$s">%1$s</option>', esc_attr( $country ) );
				}
				echo '</select>';
				break;
			case 'image_upload':
			case 'featured_image':
				printf(
					'<input type="file" id="%s" name="%s" accept="image/*" %s%s>',
					$id, $name, $required, wp_kses( $extra, [] )
				);
				break;
			case 'mask_input':
				printf(
					'<input type="text" id="%s" name="%s" data-fc-mask="%s" placeholder="%s" %s%s>',
					$id, $name, esc_attr( $field['mask'] ?? '' ), esc_attr( $this->default_placeholder_for( $field ) ), $required, wp_kses( $extra, [] )
				);
				break;
			case 'color_picker':
				printf(
					'<input type="color" id="%s" name="%s" value="%s" %s%s>',
					$id, $name, esc_attr( $field['default'] ?? '#6c4ef5' ), $required, wp_kses( $extra, [] )
				);
				break;
			case 'signature':
				$this->render_signature( $id, $name, $required );
				break;
		}
	}

	/**
	 * A real HTML5 canvas the visitor draws on (assets/js/frontend.js'
	 * initSignatures() handles mouse/touch drawing), synced into a hidden
	 * input as a base64 PNG data URL on every stroke. Submission_Handler
	 * decodes and saves that as a real uploaded image file (not the raw
	 * data URL) — see its own handle_signature_field(), same reasoning as
	 * any other file-upload field: a data URL embedded straight into the
	 * JSON response blob would be tens of KB of text per submission.
	 */
	private function render_signature( $id, $name, $required ) {
		printf(
			'<div class="chargeforms-signature-pad" data-fc-signature>
				<canvas id="chargeforms-%1$s-canvas" class="chargeforms-signature-canvas" width="500" height="150"></canvas>
				<div class="chargeforms-signature-actions">
					<button type="button" class="chargeforms-signature-clear">%2$s</button>
				</div>
				<input type="hidden" id="chargeforms-%1$s" name="%3$s" %4$s>
			</div>',
			esc_attr( $id ),
			esc_html__( 'Clear', 'chargeforms' ),
			esc_attr( $name ),
			wp_kses( $required, [] )
		);
	}

	private function render_hcaptcha( $id, $name ) {
		$site_key = Settings::get( 'hcaptcha_site_key' );
		if ( ! $site_key ) {
			if ( current_user_can( 'chargeforms_manage_forms' ) ) {
				echo '<p class="chargeforms-notice">' . esc_html__( 'hCaptcha site key not configured — add one in ChargeForms > Global Settings. This message only shows to admins.', 'chargeforms' ) . '</p>';
			}
			return;
		}

		// hCaptcha's widget script must load from hCaptcha's own CDN — it is the CAPTCHA challenge/verification client itself, not an offloadable static asset (same model the official hCaptcha plugin uses).
		wp_enqueue_script( 'chargeforms-hcaptcha', 'https://js.hcaptcha.com/1/api.js', [], null, true ); // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion, PluginCheck.CodeAnalysis.EnqueuedResourceOffloading.OffloadedContent -- vendor-hosted CAPTCHA script, versioned by the vendor itself.
		printf( '<div class="h-captcha" data-sitekey="%s"></div>', esc_attr( $site_key ) );
		printf( '<input type="hidden" id="chargeforms-%s" name="%s">', esc_attr( $id ), esc_attr( $name ) );
	}

	private function render_turnstile( $id, $name ) {
		$site_key = Settings::get( 'turnstile_site_key' );
		if ( ! $site_key ) {
			if ( current_user_can( 'chargeforms_manage_forms' ) ) {
				echo '<p class="chargeforms-notice">' . esc_html__( 'Cloudflare Turnstile site key not configured — add one in ChargeForms > Global Settings. This message only shows to admins.', 'chargeforms' ) . '</p>';
			}
			return;
		}

		// Cloudflare Turnstile's widget script must load from Cloudflare's own CDN for the same reason as hCaptcha above.
		wp_enqueue_script( 'chargeforms-turnstile', 'https://challenges.cloudflare.com/turnstile/v0/api.js', [], null, true ); // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion, PluginCheck.CodeAnalysis.EnqueuedResourceOffloading.OffloadedContent -- vendor-hosted CAPTCHA script, versioned by the vendor itself.
		printf( '<div class="cf-turnstile" data-sitekey="%s"></div>', esc_attr( $site_key ) );
		printf( '<input type="hidden" id="chargeforms-%s" name="%s">', esc_attr( $id ), esc_attr( $name ) );
	}

	/** $1.00 style formatting using the configured Stripe currency's symbol — falls back to the currency code for anything not in the common list. */
	private function format_money( $amount ) {
		$currency = Settings::get( 'stripe_currency', 'usd' );
		$symbols  = [ 'usd' => '$', 'eur' => '€', 'gbp' => '£', 'cad' => 'C$', 'aud' => 'A$', 'inr' => '₹' ];
		$symbol   = $symbols[ $currency ] ?? ( strtoupper( $currency ) . ' ' );
		return $symbol . number_format( $amount, 2 );
	}

	/**
	 * Mounts a Stripe Elements card input. The publishable key and REST URL
	 * are scoped to this one field instance (not a shared global), so a page
	 * with more than one payment form never has one form's config clobber
	 * another's. assets/js/stripe-payment.js reads this data attribute.
	 */
	/**
	 * `$field['gateway']` is unset for every form saved before PayPal existed
	 * — `?? 'stripe'` is what keeps those forms rendering exactly as they
	 * did before this field gained a second gateway option.
	 */
	private function render_payment_method( $id, $name, array $field ) {
		$gateway = $field['gateway'] ?? 'stripe';

		if ( 'paypal' === $gateway ) {
			$this->render_paypal_payment_method( $id, $name );
			return;
		}

		$this->render_stripe_payment_method( $id, $name, $field );
	}

	/**
	 * `billingType`/`billingInterval`/`trialDays` are read straight from
	 * the field config (never re-derived) and handed to stripe-payment.js
	 * as-is — the actual amount and recurrence are always re-verified
	 * server-side (RestApi::create_subscription(),
	 * SubmissionHandler::verify_stripe_subscription()) from the form's OWN
	 * stored config, same anti-tampering discipline as the one-time flow;
	 * this config only tells the client which REST endpoint and which
	 * `stripe.confirm*()` call to use, it never itself authorizes a charge.
	 * `chargeforms_subscription_id` is rendered unconditionally alongside the
	 * existing `chargeforms_payment_intent_id`, even for a one-time field —
	 * one is simply left empty and ignored server-side, simpler than
	 * branching the markup on billingType here too.
	 */
	private function render_stripe_payment_method( $id, $name, array $field = [] ) {
		$publishable_key = Settings::get( 'stripe_publishable_key' );

		if ( ! $publishable_key ) {
			if ( current_user_can( 'chargeforms_manage_forms' ) ) {
				echo '<p class="chargeforms-notice">' . esc_html__( 'Stripe publishable key not configured — add one in ChargeForms > Global Settings > Payments. This message only shows to admins.', 'chargeforms' ) . '</p>';
			}
			return;
		}

		$billing_type = 'recurring' === ( $field['billingType'] ?? 'one_time' ) ? 'recurring' : 'one_time';

		$config = wp_json_encode( [
			'publishableKey' => $publishable_key,
			'restUrl'        => esc_url_raw( rest_url( 'chargeforms/v1' ) ),
			'formId'         => $this->current_form_id,
			'billingType'    => $billing_type,
		] );

		printf(
			'<div class="chargeforms-stripe-mount" id="chargeforms-%s" data-fc-stripe-config="%s"></div><div class="chargeforms-stripe-error" role="alert"></div><input type="hidden" name="chargeforms_payment_intent_id"><input type="hidden" name="chargeforms_subscription_id">',
			esc_attr( $id ),
			esc_attr( $config )
		);
	}

	private function render_paypal_payment_method( $id, $name ) {
		$client_id = Settings::get( 'paypal_client_id' );

		if ( ! $client_id ) {
			if ( current_user_can( 'chargeforms_manage_forms' ) ) {
				echo '<p class="chargeforms-notice">' . esc_html__( 'PayPal client ID not configured — add one in ChargeForms > Global Settings > Payment Methods. This message only shows to admins.', 'chargeforms' ) . '</p>';
			}
			return;
		}

		$config = wp_json_encode( [
			'clientId' => $client_id,
			'currency' => strtoupper( Settings::get( 'paypal_currency', 'usd' ) ),
			'restUrl'  => esc_url_raw( rest_url( 'chargeforms/v1' ) ),
			'formId'   => $this->current_form_id,
		] );

		printf(
			'<div class="chargeforms-paypal-mount" id="chargeforms-%s" data-fc-paypal-config="%s"></div><div class="chargeforms-paypal-error" role="alert"></div><input type="hidden" name="chargeforms_paypal_order_id">',
			esc_attr( $id ),
			esc_attr( $config )
		);
	}

	/**
	 * Renders a single-line <input> with optional prefix/suffix labels,
	 * placeholder, default value, and max length — shared by every
	 * TEXT_LIKE_TYPES field. `field.validation` (minLength/regex/min/max/
	 * customMessage — settings-panel-only until now, see Field_Validator's
	 * doc comment) is mirrored here as native HTML5 constraint attributes,
	 * so the browser enforces the SAME rule PHP now authoritatively
	 * re-checks server-side, not just decorative settings-panel inputs.
	 */
	private function render_text_like( array $field, $html_type ) {
		$id       = esc_attr( $this->field_html_id( $field ) );
		$name     = 'chargeforms_data[' . esc_attr( $field['id'] ) . ']';
		$required = $this->required_attr( $field );
		$autocomplete = 'password' === $html_type ? ' autocomplete="new-password"' : '';
		$extra    = $this->extra_input_attrs( $field );

		$validation  = is_array( $field['validation'] ?? null ) ? $field['validation'] : [];
		$constraints = '';
		if ( ! empty( $validation['minLength'] ) ) {
			$constraints .= sprintf( ' minlength="%d"', (int) $validation['minLength'] );
		}
		if ( ! empty( $validation['regex'] ) ) {
			$constraints .= sprintf( ' pattern="%s"', esc_attr( $validation['regex'] ) );
		}
		if ( 'number' === $field['type'] ) {
			if ( isset( $validation['min'] ) && '' !== $validation['min'] ) {
				$constraints .= sprintf( ' min="%s"', esc_attr( $validation['min'] ) );
			}
			if ( isset( $validation['max'] ) && '' !== $validation['max'] ) {
				$constraints .= sprintf( ' max="%s"', esc_attr( $validation['max'] ) );
			}
			if ( ! empty( $validation['digits'] ) ) {
				$constraints .= sprintf(
					' data-digits="%d" data-digits-message="%s"',
					(int) $validation['digits'],
					esc_attr( ! empty( $validation['customMessage'] ) ? $validation['customMessage'] : Settings::get( 'validation_msg_digits', sprintf(
						/* translators: %d: required digit count */
						__( 'Must be exactly %d digits.', 'chargeforms' ),
						(int) $validation['digits']
					) ) )
				);
			}
		}
		if ( ! empty( $validation['customMessage'] ) ) {
			$constraints .= sprintf( ' title="%s"', esc_attr( $validation['customMessage'] ) );
		}
		$format_rules = [ 'email' => 'validation_msg_email', 'number' => 'validation_msg_numeric', 'url' => 'validation_msg_url' ];
		if ( isset( $format_rules[ $field['type'] ] ) ) {
			$constraints .= sprintf( ' data-format-message="%s"', esc_attr( $this->format_message_attr( $field, $field['type'], $format_rules[ $field['type'] ] ) ) );
		}

		$has_affix = ! empty( $field['prefixLabel'] ) || ! empty( $field['suffixLabel'] );
		if ( $has_affix ) {
			echo '<div class="chargeforms-input-affixed">';
			if ( ! empty( $field['prefixLabel'] ) ) {
				echo '<span class="chargeforms-input-prefix">' . esc_html( $field['prefixLabel'] ) . '</span>';
			}
		}

		printf(
			'<input type="%s" id="%s" name="%s" class="%s" placeholder="%s" value="%s" maxlength="%s"%s%s %s%s%s>',
			esc_attr( $html_type ),
			esc_attr( $id ),
			esc_attr( $name ),
			esc_attr( $field['elementClass'] ?? '' ),
			esc_attr( ! empty( $field['placeholder'] ) ? $field['placeholder'] : $this->default_placeholder_for( $field ) ),
			esc_attr( $field['default'] ?? '' ),
			esc_attr( $field['maxLength'] ?? '' ),
			esc_attr( $autocomplete ),
			wp_kses( $constraints, [] ),
			wp_kses( $required, [] ),
			wp_kses( $extra, [] ),
			'tags' === $field['type'] ? ' list="chargeforms-' . esc_attr( $field['id'] ) . '-tag-suggestions"' : ''
		);
		if ( 'tags' === $field['type'] ) {
			$tag_terms = get_terms( [ 'taxonomy' => 'post_tag', 'hide_empty' => false, 'number' => 100, 'orderby' => 'name', 'order' => 'ASC' ] );
			if ( ! is_wp_error( $tag_terms ) && ! empty( $tag_terms ) ) {
				echo '<datalist id="chargeforms-' . esc_attr( $field['id'] ) . '-tag-suggestions">';
				foreach ( $tag_terms as $tag_term ) {
					printf( '<option value="%s"></option>', esc_attr( $tag_term->name ) );
				}
				echo '</datalist>';
			}
		}

		if ( $has_affix ) {
			if ( ! empty( $field['suffixLabel'] ) ) {
				echo '<span class="chargeforms-input-suffix">' . esc_html( $field['suffixLabel'] ) . '</span>';
			}
			echo '</div>';
		}
	}

	private function render_recaptcha( $id, $name ) {
		$site_key = Settings::get( 'recaptcha_site_key' );

		if ( ! $site_key ) {
			if ( current_user_can( 'chargeforms_manage_forms' ) ) {
				echo '<p class="chargeforms-notice">' . esc_html__( 'reCAPTCHA site key not configured — add one in ChargeForms > Global Settings. This message only shows to admins.', 'chargeforms' ) . '</p>';
			}
			return;
		}

		// Google reCAPTCHA's widget script must load from Google's own CDN for the same reason as hCaptcha above (the official Google reCAPTCHA plugin does the same).
		wp_enqueue_script( 'chargeforms-recaptcha', 'https://www.google.com/recaptcha/api.js', [], null, true ); // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion, PluginCheck.CodeAnalysis.EnqueuedResourceOffloading.OffloadedContent -- vendor-hosted CAPTCHA script, versioned by the vendor itself.
		printf( '<div class="g-recaptcha" data-sitekey="%s"></div>', esc_attr( $site_key ) );
		printf( '<input type="hidden" id="chargeforms-%s" name="%s">', esc_attr( $id ), esc_attr( $name ) );
	}
}