<?php
/**
 * The admin notices, printed where the scripts would move them (0.86.0, the LMS cleanup's finding, 7 Nov 2026).
 *
 * What a plugin prints on `admin_notices` (or the network's or a user's notices) comes before the page in the HTML.
 * Once the page has loaded, WordPress's common.js moves every `div.notice`, `div.updated` and `div.error` that is not
 * `inline` (nor `below-h2`) after the page's `.wp-header-end`, else after the first `h1` or `h2` in a `.wrap`; the
 * chrome's script moves a kit notice printed there after a `.wp-header-end` in a `.wrap`, before core's ready handler
 * runs, so core's notices end up first. Both moves came after the first paint, so the page jumped: 56 px on the
 * chrome's screens, 142 px on a term's edit screen with two notices. On a chrome screen the library holds what is
 * printed on those hooks and prints each notice where the scripts would put it, so their move changes nothing; the
 * rest of what was printed there (an inline notice, a style, a script) stays where it was, and an inline script right
 * after a notice goes with it (it may look for the notice as it runs).
 *
 * @package RoosterAdmin
 */

namespace Rooster\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * Static.
 */
final class Notices {

	/**
	 * Nothing held yet.
	 */
	private const IDLE = 0;

	/**
	 * Holding what the notices' hooks print.
	 */
	private const HOLDING = 1;

	/**
	 * Holding the page, to print the notices in it.
	 */
	private const PLACING = 2;

	/**
	 * Done for this request.
	 */
	private const DONE = 3;

	/**
	 * Where the request stands.
	 *
	 * @var int
	 */
	private static $state = self::IDLE;

	/**
	 * The output buffer's level this class opened.
	 *
	 * @var int
	 */
	private static $level = 0;

	/**
	 * What the notices' hooks printed.
	 *
	 * @var string
	 */
	private static $notices = '';

	/**
	 * Hook admin_notices, network_admin_notices and user_admin_notices (first), and all_admin_notices (last): on a
	 * chrome screen, the buffer this opens on the first hook holds what the notices' hooks print and closes on the
	 * last; what it held is kept for the page when it holds a notice a script would move (the page's buffer opens
	 * here and closes in finish()), else printed as it was.
	 */
	public static function hold(): void {
		if ( ! doing_action( 'all_admin_notices' ) ) {
			if ( self::IDLE === self::$state && '' !== Library::product() ) {
				self::$state = self::DONE;
				if ( ob_start() ) {
					self::$level = ob_get_level();
					self::$state = self::HOLDING;
				}
			}
			return;
		}
		if ( self::HOLDING !== self::$state ) {
			return;
		}
		self::$state = self::DONE;
		if ( ob_get_level() !== self::$level ) {
			return; // a notice opened a buffer and left it open: everything stays as printed
		}
		$notices = (string) ob_get_clean();
		$cut     = self::cut( $notices, true );
		if ( null === $cut || ( '' === $cut['core'] && '' === $cut['kit'] ) ) {
			echo $notices; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- what WordPress and the plugins printed on the notices' hooks, unchanged.
			return;
		}
		self::$notices = $notices;
		if ( ob_start( array( self::class, 'place' ) ) ) {
			self::$level = ob_get_level();
			self::$state = self::PLACING;
			return;
		}
		self::$notices = '';
		echo $notices; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- as above.
	}

	/**
	 * Hook in_admin_footer (first): the page is complete; the notices go in. A page that exits before its footer is
	 * placed when PHP ends the buffer.
	 */
	public static function finish(): void {
		if ( self::PLACING === self::$state && ob_get_level() === self::$level ) {
			ob_end_flush();
		}
	}

	/**
	 * The page buffer's handler: the page with the notices in it.
	 *
	 * @param string $buffer The page so far.
	 * @param int    $phase  PHP_OUTPUT_HANDLER_* flags.
	 */
	public static function place( string $buffer, int $phase ): string {
		if ( self::PLACING !== self::$state ) {
			return $buffer;
		}
		if ( 0 !== ( $phase & PHP_OUTPUT_HANDLER_CLEAN ) ) {
			if ( 0 !== ( $phase & PHP_OUTPUT_HANDLER_FINAL ) ) {
				self::$state = self::DONE; // the page was thrown away (a download, say): so are the notices
			}
			return ''; // emptied: the notices still to print
		}
		self::$state   = self::DONE;
		$notices       = self::$notices;
		self::$notices = '';
		return self::arrange( $notices, $buffer );
	}

	/**
	 * The notices and the page as the scripts would leave them: each notice a script moves after the page's mark (core's
	 * first, then the kit's), the rest of the notices before the page. Unchanged when the page has no mark or a
	 * notice is not closed.
	 *
	 * @param string $notices What the notices' hooks printed.
	 * @param string $page    The page that follows them.
	 */
	public static function arrange( string $notices, string $page ): string {
		$mark = self::mark( $page );
		$cut  = null !== $mark ? self::cut( $notices, $mark['kit'] ) : null;
		if ( null === $cut ) {
			return $notices . $page;
		}
		return $cut['stay'] . substr( $page, 0, $mark['at'] ) . $cut['core'] . $cut['kit'] . substr( $page, $mark['at'] );
	}

	/**
	 * Where common.js puts the notices: after the first `.wp-header-end`, else after the first `h1` or `h2` in a
	 * `.wrap`; and whether the chrome's script puts the kit's there too (a `.wp-header-end` in a `.wrap`).
	 *
	 * @param string $page The page.
	 * @return array{at: int, kit: bool}|null The byte offset after the mark; null when there is none.
	 */
	private static function mark( string $page ): ?array {
		$ends = false !== strpos( $page, 'wp-header-end' ); // none: the wrap's first heading is the mark, the scan stops there
		if ( ! $ends && ( 1 !== preg_match( '/<h[12][\s>]/i', $page ) || 1 !== preg_match( '/\sclass\s*=\s*["\']?(?:[^"\'>]*\s)?wrap[\s"\'>]/i', $page ) ) ) {
			return null; // no mark, and no heading or no .wrap: nothing to scan for
		}
		$scan    = self::scanner( $page );
		$divs    = 0;
		$wrap    = 0; // the depth of the .wrap the scan is in, 0 outside
		$heading = null;
		while ( $scan->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
			$tag = (string) $scan->get_tag();
			if ( 'DIV' === $tag ) {
				if ( $scan->is_tag_closer() ) {
					$wrap = $wrap === $divs ? 0 : $wrap;
					--$divs;
					continue;
				}
				++$divs;
				$wrap = 0 === $wrap && true === $scan->has_class( 'wrap' ) ? $divs : $wrap;
			}
			if ( $scan->is_tag_closer() ) {
				continue;
			}
			if ( true === $scan->has_class( 'wp-header-end' ) ) {
				$at = self::after( $scan, $tag );
				return null !== $at ? array( 'at' => $at, 'kit' => 0 !== $wrap ) : null;
			}
			if ( null === $heading && 0 !== $wrap && ( 'H1' === $tag || 'H2' === $tag ) ) {
				$heading = self::after( $scan, $tag ); // kept: a .wp-header-end further down wins
				if ( ! $ends ) {
					break;
				}
			}
		}
		return null !== $heading ? array( 'at' => $heading, 'kit' => false ) : null;
	}

	/**
	 * The offset after the element the scan stands on: its tag when void, else its closer (the scan moves to it).
	 *
	 * @param object $scan The scan (scanner()).
	 * @param string $tag  The element's tag name.
	 */
	private static function after( $scan, string $tag ): ?int {
		$span = $scan->span();
		if ( \WP_HTML_Processor::is_void( $tag ) ) {
			return $span[1];
		}
		$depth = 1;
		while ( $scan->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
			if ( $tag !== $scan->get_tag() ) {
				continue;
			}
			$depth += $scan->is_tag_closer() ? -1 : 1;
			if ( 0 === $depth ) {
				return $scan->span()[1];
			}
		}
		return null;
	}

	/**
	 * The notices cut into what the scripts move and what stays: every `div.notice`, `.updated` or `.error` that is not
	 * `inline` (nor `below-h2`), wherever it sits, is core's; a `div.rooster-admin-notice` outside any div is the
	 * kit's when the chrome's script moves it ($kit). An inline script right after a moved notice goes with it.
	 *
	 * @param string $notices What the notices' hooks printed.
	 * @param bool   $kit     Whether the kit's notices move.
	 * @return array{stay: string, core: string, kit: string}|null Null when a notice is not closed.
	 */
	private static function cut( string $notices, bool $kit ): ?array {
		$scan  = self::scanner( $notices );
		$cuts  = array(); // each: its start, its end, whose (core or kit)
		$divs  = 0;
		$open  = null;
		$after = null; // the cut a script right after it would join
		while ( $scan->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
			$tag  = (string) $scan->get_tag();
			$span = $scan->span();
			if ( null !== $after ) {
				$joins = 'SCRIPT' === $tag && ! $scan->is_tag_closer() && '' === trim( substr( $notices, $cuts[ $after ][1], $span[0] - $cuts[ $after ][1] ) ) && null === $scan->get_attribute( 'src' );
				$after = null;
				if ( $joins ) {
					$cuts[ count( $cuts ) - 1 ][1] = self::close_of( $scan, $notices );
					continue;
				}
			}
			if ( 'DIV' !== $tag ) {
				continue;
			}
			if ( $scan->is_tag_closer() ) {
				if ( null !== $open && $divs === $open[1] ) {
					$cuts[] = array( $open[0], $span[1], $open[2] );
					$after  = count( $cuts ) - 1;
					$open   = null;
				}
				--$divs;
				continue;
			}
			++$divs;
			if ( null !== $open ) {
				continue;
			}
			if ( ( $scan->has_class( 'notice' ) || $scan->has_class( 'updated' ) || $scan->has_class( 'error' ) ) && ! $scan->has_class( 'inline' ) && ! $scan->has_class( 'below-h2' ) ) {
				$open = array( $span[0], $divs, 'core' );
			} elseif ( $kit && 1 === $divs && $scan->has_class( 'rooster-admin-notice' ) ) {
				$open = array( $span[0], $divs, 'kit' );
			}
		}
		if ( null !== $open ) {
			return null;
		}
		$out  = array(
			'stay' => '',
			'core' => '',
			'kit'  => '',
		);
		$from = 0;
		foreach ( $cuts as $cut ) {
			$out['stay']    .= substr( $notices, $from, $cut[0] - $from );
			$out[ $cut[2] ] .= substr( $notices, $cut[0], $cut[1] - $cut[0] );
			$from            = $cut[1];
		}
		$out['stay'] .= substr( $notices, $from );
		return $out;
	}

	/**
	 * The offset after the closer of the script the scan stands on: the first `</script` after its opener (a script's
	 * text cannot hold one; the scanner's token may or may not take the text in).
	 *
	 * @param object $scan    The scan, on a SCRIPT opener.
	 * @param string $notices The scanned HTML.
	 */
	private static function close_of( $scan, string $notices ): int {
		$span  = $scan->span();
		$close = stripos( $notices, '</script', $span[0] + 7 );
		$end   = false !== $close ? strpos( $notices, '>', $close ) : false;
		return false !== $end ? $end + 1 : strlen( $notices );
	}

	/**
	 * Core's tag processor, telling where the tag it stands on starts and ends.
	 *
	 * @param string $html The HTML to scan.
	 */
	private static function scanner( string $html ): object {
		return new class( $html ) extends \WP_HTML_Tag_Processor {
			/**
			 * The tag's byte offsets: [start, end].
			 *
			 * @return int[]
			 */
			public function span(): array {
				$this->set_bookmark( 'here' );
				$span = $this->bookmarks['here'];
				return array( $span->start, $span->start + $span->length );
			}
		};
	}
}