<?php
/**
 * Core's extension registration boundary for the Pro add-on.
 *
 * Core-owned: this file ships only in the WordPress.org core package, never
 * in the Pro add-on delta. See ARCHITECTURE-CORE-PRO-ADDON.md's "Registration
 * rather than replacement" section for the contract this implements.
 *
 * The problem this solves: core's admin shell registers the compatible URL
 * for a Pro-exclusive workspace (Metadata, Schema, Business details)
 * unconditionally, so bookmarks and links never break. What that URL renders
 * depends on a fact only available at runtime -- is the Pro add-on installed
 * and active on this site -- and core cannot decide it by reading a class
 * name off disk, because Metadata's classes are deliberately NOT loaded
 * until Pro's own entitlement check passes (a liteness decision: an admin
 * request on a site with Pro installed but not currently entitled should not
 * pay to load ~600KB of Metadata classes it is not going to use). So "the
 * Metadata class exists" and "the Pro add-on is present" are different
 * facts, and core needs the second one, not the first.
 *
 * This registry supplies that fact, and the renderer that goes with it. The
 * add-on's module bootstraps call register_workspace() at require time --
 * before any decision about entitlement -- handing core the callable that
 * renders the real workspace. Core's entry point then does one thing: ask
 * the registry to render, and show its own absent-state presentation if
 * nothing answered. Whether the registered renderer shows the workspace or
 * the add-on's own workspace-locked state is the renderer's decision; core
 * never reads entitlement state itself.
 *
 * tests/extensions-registry.php pins this contract.
 */

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

class AI_O_Optimiser_Extensions {

	/**
	 * The registration contract this core version understands. A Pro add-on
	 * built against an incompatible contract version is refused rather than
	 * trusted to behave -- "fail closed when the add-on contract version is
	 * unknown" per CLAUDE-HANDOFF-CORE-PRO-ADDON.md.
	 */
	const CONTRACT_VERSION = 1;

	/**
	 * Workspace key => renderer (callable), or true when only presence was
	 * declared, for every workspace the Pro add-on registered at a compatible
	 * contract version.
	 *
	 * @var array<string,callable|bool>
	 */
	private static $workspaces = array();

	/** @var array<string,string> Workspace key => tab label the add-on offers. */
	private static $labels = array();

	/**
	 * Register the add-on's renderer for a workspace. Also marks it present.
	 *
	 * Call this at require time in the module that owns the workspace, not
	 * gated on entitlement state: presence and entitlement are different
	 * questions, and the renderer handed over here is where the second one is
	 * answered.
	 *
	 * @param string   $key              Workspace key: metadata, schema or local.
	 * @param callable $render           Renders the workspace (or its locked state). Takes no arguments.
	 * @param int      $contract_version The CONTRACT_VERSION the caller was built against.
	 * @return bool True if the registration was accepted.
	 */
	public static function register_workspace( $key, $render, $contract_version = self::CONTRACT_VERSION ) {
		$key = (string) $key;
		if ( '' === $key || (int) $contract_version !== self::CONTRACT_VERSION || ! is_callable( $render ) ) {
			return false;
		}
		self::$workspaces[ $key ] = $render;
		return true;
	}

	/**
	 * Declare that the Pro add-on provides a workspace, without a renderer.
	 * Kept for callers that only need presence; register_workspace() is the
	 * normal path.
	 *
	 * @param string $key              Workspace key.
	 * @param int    $contract_version The CONTRACT_VERSION the caller was built against.
	 * @return bool True if the registration was accepted.
	 */
	public static function mark_present( $key, $contract_version = self::CONTRACT_VERSION ) {
		$key = (string) $key;
		if ( '' === $key || (int) $contract_version !== self::CONTRACT_VERSION ) {
			return false;
		}
		if ( ! isset( self::$workspaces[ $key ] ) ) {
			self::$workspaces[ $key ] = true;
		}
		return true;
	}

	/**
	 * Whether the Pro add-on has registered $key at a compatible contract
	 * version. This says nothing about entitlement state.
	 *
	 * @param string $key Workspace key.
	 * @return bool
	 */
	public static function is_available( $key ) {
		return ! empty( self::$workspaces[ (string) $key ] );
	}

	/**
	 * Register the tab label to show for $key once the add-on is present, so
	 * a tab never shows real add-on content under core's own absent-state name.
	 *
	 * @param string $key              Workspace key.
	 * @param string $label            Label to show once the add-on is present.
	 * @param int    $contract_version The CONTRACT_VERSION the caller was built against.
	 * @return bool True if accepted.
	 */
	public static function register_label( $key, $label, $contract_version = self::CONTRACT_VERSION ) {
		$key = (string) $key;
		if ( '' === $key || (int) $contract_version !== self::CONTRACT_VERSION || '' === (string) $label ) {
			return false;
		}
		self::$labels[ $key ] = (string) $label;
		return true;
	}

	/** @param string $key Workspace key. @param string $default Fallback. @return string */
	public static function label( $key, $default ) {
		$key = (string) $key;
		return isset( self::$labels[ $key ] ) && '' !== self::$labels[ $key ] ? self::$labels[ $key ] : (string) $default;
	}

	/**
	 * Render the add-on's workspace for $key, if one is registered.
	 *
	 * @param string $key Workspace key.
	 * @return bool True if a registered renderer ran; false if the caller
	 *              should show its own absent-state presentation instead.
	 */
	public static function render( $key ) {
		$key = (string) $key;
		if ( empty( self::$workspaces[ $key ] ) || ! is_callable( self::$workspaces[ $key ] ) ) {
			return false;
		}
		call_user_func( self::$workspaces[ $key ] );
		return true;
	}

	/**
	 * Test-only: clear registrations between fixtures in the same process.
	 *
	 * @return void
	 */
	public static function reset_for_tests() {
		self::$workspaces = array();
		self::$labels     = array();
	}
}