<?php
/**
 * The page board (0.58.0; ui-card-layout-optimization.md §2, the Metronic note's F6, UI-Final-Review FR8 and FR9): the
 * Home's grid on every page. A board is bands; a band is one to three column stacks (a 2:1 or 1:2 pair among them), a
 * band of equal-height rows, or one card across the board. A person moves a card within its band's columns, and a card
 * across the board up and down among the bands that are not fixed: by its grip (a drag, the arrow keys, or the Move
 * menu a click opens; assets/board.js), each move announced and saved per user, product and board (Prefs::BOARDS),
 * cleaned when read as the Home's layout is: unknown cards dropped, new ones placed by default. "Reset layout" puts the
 * board back as the product arranged it.
 *
 * Two ways to build one, the same markup: the bands as data (render(): each band's cards as the HTML strings the card
 * helpers return), or printed (capture( $key, $opts, $render ), $render calling band_open(), echoing the cards,
 * band_close()): the board buffers what a band prints and splits it at its top-level cards, so a module that echoes
 * its cards keeps doing so; the buffer starts and ends in capture() (0.69.0). open() / close() of older products print
 * the cards as they come, without a buffer. A card states its
 * default column (`col`), whether it needs the board's width (`span` all: a band of its own), the width under which it
 * must not go (`min`, rem) and whether it moves (`movable`), as options of rooster_admin_card_open_html(), printed as
 * data attributes on its section the board reads back. Escaped here; the cards are the product's own escaped markup.
 *
 * The person's own rows (0.80.0; the owner, 6 Nov 2026: "to allow each user to set per page the number of columns ...
 * 1:1, 1:1:1, 1:2, 2:1, 1:3, 3:1, 1:1:1:1, 1:2:1, 2:1:1, 1:1:2 and to place there what they want"; rows they build
 * themselves, an "Edit layout" mode, the Home too): a row of columns (a band that is not fixed, not one card across the
 * board, not a band of equal-height rows) takes any of LAYOUTS, the person adds rows (at the top) and removes the ones
 * they added, moves rows up and down, and drags any card of such a row into any column of another. Saved with the
 * arrangement ({o, c, l: band key => layout, r: the added rows' keys}); nothing changes for anyone until they change it,
 * and Reset layout puts the page back as the product arranged it, rows and layouts included.
 *
 * @package RoosterAdmin
 */

namespace Rooster\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * Static.
 */
final class Board {

	/**
	 * The widths (rem) at which a band may go to one column (one container rule each in chrome.css): a band takes the
	 * smallest that its columns and its cards' minimum widths need.
	 */
	public const THRESHOLDS = array( 45, 50, 55, 60, 65, 69, 75, 80, 90, 100, 120 );

	/**
	 * The width a band's columns need by default, by layout (FR9: about 69 rem for two, 90 for three; a 2:1 pair as two),
	 * where the band has the layout the page gave it. A layout the person chose (0.80.0), or one without a default here,
	 * needs its narrowest column LAYOUT_MIN wide (threshold()).
	 */
	public const DEFAULT_AT = array(
		'1:1'   => 69,
		'2:1'   => 69,
		'1:2'   => 69,
		'1:1:1' => 90,
	);

	/**
	 * The layouts a row of columns may take (0.80.0), each column's width in parts: the order the layout menu lists them.
	 */
	public const LAYOUTS = array( '1', '1:1', '1:2', '2:1', '1:3', '3:1', '1:1:1', '1:2:1', '2:1:1', '1:1:2', '1:1:1:1' );

	/**
	 * The narrowest column a layout the person chose keeps before its row goes to one column, in rem, where no card asks
	 * for more (0.80.0): four columns show from 69 rem of board, so a layout chosen on a laptop's screen shows as chosen.
	 */
	public const LAYOUT_MIN = 16;

	/**
	 * The most columns a row takes (0.80.0: four).
	 */
	public const MAX_COLS = 4;

	/**
	 * A row the person added (0.80.0): its key (a dot, which no band's slug has), and the most they may add to a board.
	 */
	public const ROW_PATTERN = '/^u\.row-[1-9][0-9]?$/';
	public const MAX_ROWS    = 20;

	/**
	 * The gap between cards, in rem (--ra-gap-card: 20 px).
	 */
	public const GAP = 1.25;

	/**
	 * The most bytes of JSON one product's saved boards take; the boards saved longest ago go first.
	 */
	public const MAX_BYTES = Prefs::LIMITS[ Prefs::BOARDS ];

	/**
	 * The most bytes of JSON one board's arrangement takes when it is saved (0.80.0: its rows and their layouts with
	 * it; Rest::save()), half the product's boards.
	 */
	public const VALUE_BYTES = 8192;

	/**
	 * The most bands, columns per band and cards per band a saved board names.
	 */
	public const MAX_BANDS = 40;
	public const MAX_CARDS = 80;

	/**
	 * A board's key, a band's and a card's (an HTML id).
	 */
	public const KEY_PATTERN  = '/^[a-z0-9][a-z0-9_.\/-]{0,119}$/';
	public const CARD_PATTERN = '/^[A-Za-z0-9][A-Za-z0-9_:.-]{0,119}$/';

	/**
	 * The boards being printed (open() to close()), the innermost last.
	 *
	 * @var list<array<string, mixed>>
	 */
	private static array $stack = array();

	/**
	 * The boards whose Reset layout the page head carries (Ui::pagehead()'s `board`), by key.
	 *
	 * @var array<string, true>
	 */
	private static array $head_reset = array();

	/**
	 * What went wrong this request (a band printed with content between its cards, a board left open), by board.
	 *
	 * @var array<string, string>
	 */
	private static array $problems = array();

	/**
	 * A counter for the bands' title ids.
	 *
	 * @var int
	 */
	private static int $bands = 0;

	/**
	 * Whether the reset dialog was printed.
	 *
	 * @var bool
	 */
	private static bool $dialog = false;

	/**
	 * The boards whose Edit layout the page head (or the Home's summary) carries, by key (0.80.0).
	 *
	 * @var array<string, true>
	 */
	private static array $head_edit = array();

	/**
	 * Whether the edit mode's template (the row's tools, Add a row, the layout menu) was printed (0.80.0; once a page).
	 *
	 * @var bool
	 */
	private static bool $tools = false;

	/**
	 * The arranged board the buffer's handler (emit()) sends next (0.81.0): set by capture() and end() right before
	 * they flush the board's buffer, sent ahead of what the buffer holds, then emptied.
	 *
	 * @var string
	 */
	private static string $arranged = '';

	/**
	 * The screen page() is printing: the index of its open board in the stack ('board', -1 when none); null outside
	 * page().
	 *
	 * @var array{board: int}|null
	 */
	private static ?array $page = null;

	/**
	 * Prints a board whose cards $render echoes (0.69.0, the wordpress.org review: the board's one buffer starts and ends
	 * here, in this function, at the same level): `ob_start()` with the board's handler (emit()), $render, then
	 * `ob_end_flush()`; when $render throws, the `catch` closes the buffer, forgets the board and throws the error on.
	 * 0.81.0 (the wordpress.org review): nothing the board received is echoed again; PHP sends the buffer through
	 * emit(), which puts the arranged board in its place, the product's cards as their own escaped output printed them. $render states the bands with band_open()
	 * and band_close() and echoes the cards; cards it prints outside a band are one band of one column, in their order
	 * (loose()). A band still open when $render returns ends with the board.
	 *
	 * @param string               $key    The board's key: the screen, unique in the product ("frontend/gallery_layout").
	 * @param array<string, mixed> $opts   See render().
	 * @param callable             $render Echoes the board's bands and cards.
	 *
	 * @throws \Throwable What $render throws.
	 */
	public static function capture( string $key, array $opts, callable $render ): void {
		self::$stack[] = array(
			'key'   => $key,
			'opts'  => $opts,
			'bands' => array(),
			'band'  => null,
		);

		$i = count( self::$stack ) - 1;
		ob_start( array( self::class, 'emit' ) );
		try {
			$render();
			if ( is_array( self::$stack[ $i ]['band'] ) ) {
				self::band_close();
			}
		} catch ( \Throwable $e ) {
			ob_end_clean();
			array_splice( self::$stack, $i );
			throw $e;
		}
		self::loose( $i, self::take() );
		$board = array_pop( self::$stack );
		$opts  = (array) $board['opts'];
		if ( isset( $board['head'] ) ) {
			$opts['head'] = (string) $board['head']; // the module's tab strip, as it printed it (0.58.2)
		}
		self::$arranged = self::render( (string) $board['key'], $board['bands'], $opts );
		ob_end_flush(); // emit(): the arranged board, in place of what the buffer held
	}

	/**
	 * The board of a screen built as a string (0.83.0; the owner, 7 Nov 2026: every page's layout is the person's, Rooster
	 * LMS Pro's screens among them, which build their markup as one string and echo it): what capture() makes of what a
	 * callback prints, without a buffer. A leading tab strip is the board's head; the cards are split at the top level;
	 * anything seen between them keeps the whole as it came (P4, problems()). HTML that is blank comes back as it is.
	 *
	 * @param string               $key  The board's key: the screen, unique in the product.
	 * @param string               $html The screen's cards (escaped: the product's own markup).
	 * @param array<string, mixed> $opts See render().
	 */
	public static function from_html( string $key, string $html, array $opts = array() ): string {
		if ( self::blank( $html ) ) {
			return $html;
		}
		self::$stack[] = array(
			'key'   => $key,
			'opts'  => $opts,
			'bands' => array(),
			'band'  => null,
		);
		self::loose( count( self::$stack ) - 1, $html );
		$board = array_pop( self::$stack );
		if ( isset( $board['head'] ) ) {
			$opts['head'] = (string) $board['head']; // the screen's tab strip, as it built it
		}
		return self::render( $key, $board['bands'], $opts );
	}

	/**
	 * The handler of a board's buffer (0.81.0, capture() and page()): PHP calls it with what the buffer holds when the
	 * buffer is flushed or ended, and sends what it returns. The board arranged last (capture(), end()) goes first, then
	 * what the buffer holds (what the screen printed after its board); a buffer being emptied (take(), a throw) sends
	 * nothing and keeps the board for its flush.
	 *
	 * @param string $buffer What the buffer holds.
	 * @param int    $phase  PHP_OUTPUT_HANDLER_* flags.
	 */
	public static function emit( string $buffer, int $phase ): string {
		if ( $phase & PHP_OUTPUT_HANDLER_CLEAN ) {
			return '';
		}
		$out            = self::$arranged . $buffer;
		self::$arranged = '';
		return $out;
	}

	/**
	 * Prints a whole screen whose board starts and ends somewhere in it (0.69.0): the screen's render callback runs in
	 * one buffer, started and ended here at the same level (`ob_start()` with the board's handler, emit(), $render,
	 * `ob_end_flush()`; when $render throws, the `catch` closes the buffer, forgets the board and throws the error on);
	 * inside it start() marks where the board begins (what was printed before goes out as it came: the page head) and
	 * end() where it ends (the board arranged from what was printed between, bands included, sent in its place by
	 * emit()). A product wraps its screens' callbacks once (the LMS's
	 * UI\Admin\Page::screen()) and its page helper calls start() and end(), so a screen with several ways out (an early
	 * return) needs no closure of its own. A board still open when $render returns ends there.
	 *
	 * @param callable $render Prints the screen.
	 *
	 * @throws \Throwable What $render throws.
	 */
	public static function page( callable $render ): void {
		$outer      = self::$page;
		self::$page = array( 'board' => -1 );

		$level = count( self::$stack );
		ob_start( array( self::class, 'emit' ) );
		try {
			$render();
			self::end();
		} catch ( \Throwable $e ) {
			ob_end_clean();
			self::$page = $outer;
			array_splice( self::$stack, $level );
			throw $e;
		}
		ob_end_flush(); // what the screen printed after its board (the board itself went out from end())
		self::$page = $outer;
	}

	/**
	 * Starts the board of the screen page() prints, here: what the screen printed so far goes out as it came. False
	 * (and nothing starts) outside page() or when its board is open already.
	 *
	 * @param string               $key  The board's key.
	 * @param array<string, mixed> $opts See render().
	 */
	public static function start( string $key, array $opts = array() ): bool {
		if ( null === self::$page || self::$page['board'] >= 0 ) {
			return false;
		}
		if ( ob_get_level() > 0 ) {
			ob_flush(); // the page head, as the screen printed it, to the level page() found; the buffer stays open
		}
		self::$stack[] = array(
			'key'   => $key,
			'opts'  => $opts,
			'bands' => array(),
			'band'  => null,
		);

		self::$page['board'] = count( self::$stack ) - 1;
		return true;
	}

	/**
	 * Ends the board start() began: what the screen printed since is arranged (bands, loose cards) and sent in its place
	 * (the buffer flushed through emit(), 0.81.0); what follows is the screen's again. Nothing when no board of page()
	 * is open.
	 */
	public static function end(): void {
		if ( null === self::$page || self::$page['board'] < 0 ) {
			return;
		}
		$i = self::$page['board'];
		if ( is_array( self::$stack[ $i ]['band'] ) ) {
			self::band_close();
		}
		self::loose( $i, self::take() );
		$board               = array_pop( self::$stack );
		self::$page['board'] = -1;
		$opts                = (array) $board['opts'];
		if ( isset( $board['head'] ) ) {
			$opts['head'] = (string) $board['head']; // the module's tab strip, as it printed it (0.58.2)
		}
		self::$arranged = self::render( (string) $board['key'], $board['bands'], $opts );
		if ( ob_get_level() > 0 ) {
			ob_flush(); // page()'s buffer, through emit(): the arranged board; the buffer stays open for the rest of the screen
		}
	}

	/**
	 * Starts a printed board the old way (before 0.69.0): it no longer buffers (the wordpress.org review: a buffer must
	 * end in the function that starts it), so what follows until close() is printed where it comes, one card under the
	 * other, nothing moves, and band_open() / band_close() inside it do nothing. A product moves to capture(); this
	 * stays so a product built for an older library keeps working when a newer copy is loaded.
	 *
	 * @param string               $key  The board's key.
	 * @param array<string, mixed> $opts See render().
	 */
	public static function open( string $key, array $opts = array() ): void {
		unset( $opts );
		self::$stack[] = array(
			'key'   => $key,
			'flat'  => true,
			'bands' => array(),
			'band'  => null,
		);
	}

	/**
	 * Starts a band of the board being printed; its cards are echoed until band_close().
	 *
	 * @param array<string, mixed> $opts See render()'s bands (title, description, key, id, cols, rows, fixed, min).
	 */
	public static function band_open( array $opts = array() ): void {
		$i = count( self::$stack ) - 1;
		if ( $i < 0 || ! empty( self::$stack[ $i ]['flat'] ) ) {
			return;
		}
		self::loose( $i, self::take() );
		self::$stack[ $i ]['band'] = $opts;
	}

	/**
	 * Ends the band being printed.
	 */
	public static function band_close(): void {
		$i = count( self::$stack ) - 1;
		if ( $i < 0 || ! empty( self::$stack[ $i ]['flat'] ) || ! is_array( self::$stack[ $i ]['band'] ) ) {
			return;
		}
		$html = self::take();
		$band = self::$stack[ $i ]['band'];
		$units = self::split( $html );
		if ( null === $units || self::unseen_only( $units ) ) {
			// Something stands between the cards (P4): the band is printed as it came, one column, nothing moves. A band
			// that holds only what is never seen (a script) is printed as it came too, without a problem.
			if ( null === $units ) {
				self::$problems[ (string) self::$stack[ $i ]['key'] ] = 'content between the cards of a band (P4): printed as it came';
			}
			$band = array( 'raw' => $html );
		} else {
			$band['cards'] = $units;
		}
		self::$stack[ $i ]['bands'][] = $band;
		self::$stack[ $i ]['band']    = null;
	}

	/**
	 * What the board's buffer (capture()'s or page()'s) holds so far, the buffer emptied and kept open (band_open(),
	 * band_close() and end() cut the board's one buffer instead of closing it and starting their own). Only called
	 * inside capture() or page(), for a board that is not flat, so the buffer is always the board's.
	 */
	private static function take(): string {
		if ( ob_get_level() < 1 ) {
			return '';
		}
		$html = (string) ob_get_contents();
		ob_clean();
		return $html;
	}

	/**
	 * Ends a board open() started (before 0.69.0): it printed as it came, so nothing is left to echo.
	 */
	public static function close(): void {
		$i = count( self::$stack ) - 1;
		if ( $i >= 0 && ! empty( self::$stack[ $i ]['flat'] ) ) {
			array_pop( self::$stack );
		}
	}

	/**
	 * What a printed board holds outside its bands: cards alone are one band of one column, in their order (a page
	 * that turns its board on before its modules state bands: Rooster One's page.php around every module); anything
	 * else stays in place as it came, never moving (P4).
	 *
	 * @param int    $i    The board's index in the stack.
	 * @param string $html What was printed.
	 */
	private static function loose( int $i, string $html ): void {
		if ( self::blank( $html ) ) {
			return;
		}
		if ( array() === self::$stack[ $i ]['bands'] && ! isset( self::$stack[ $i ]['head'] ) ) {
			$head = self::tab_head( $html );
			if ( null !== $head ) {
				self::$stack[ $i ]['head'] = $head[0];
				$html                      = $head[1];
				if ( self::blank( $html ) ) {
					return;
				}
			}
		}
		$units = self::split( $html );
		if ( null === $units || self::unseen_only( $units ) ) {
			if ( null === $units ) {
				self::$problems[ (string) self::$stack[ $i ]['key'] ] = 'content between the cards of a board (P4): printed as it came';
			}
			self::$stack[ $i ]['bands'][] = array( 'raw' => $html );
			return;
		}
		self::$stack[ $i ]['bands'][] = array( 'cards' => $units );
	}

	/**
	 * A module's leading tab strip, set apart as the board's head (0.58.2, Rooster One's wave 1: about 24 of its modules
	 * print their in-page tabs at the top of their render, after page.php has opened the board, and the strip stopped
	 * the split, P4): when the first visible node a board receives is a `.rooster-admin-tabs` nav, or an element whose
	 * only child is one (a plain wrapper), it is printed above the bands, out of the move set, and the cards after it
	 * form the board as usual. Anything else seen still stops the split. [head HTML, the rest], or null.
	 *
	 * @param string $html What the board received before its first band.
	 * @return array{0: string, 1: string}|null
	 */
	private static function tab_head( string $html ): ?array {
		$at = 1 === preg_match( '/^(?:\s+|<!--.*?-->)*/s', $html, $space ) ? strlen( $space[0] ) : 0;
		if ( 1 !== preg_match( '/\G<([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*>/', $html, $open, 0, $at ) ) {
			return null;
		}
		$tag = strtolower( $open[1] );
		$end = self::end_of( $html, $tag, $at );
		if ( null === $end ) {
			return null;
		}
		$node = substr( $html, $at, $end - $at );
		if ( ! self::is_tabs( $node ) ) {
			if ( 'nav' === $tag || 1 !== preg_match( '#^<' . preg_quote( $open[1], '#' ) . '\b[^>]*>(.*)</' . preg_quote( $open[1], '#' ) . '\s*>$#is', $node, $inner ) ) {
				return null;
			}
			$only = trim( (string) preg_replace( '/<!--.*?-->/s', '', $inner[1] ) );
			$nav  = '' !== $only ? self::end_of( $only, 'nav', 0 ) : null;
			if ( null === $nav || strlen( $only ) !== $nav || ! self::is_tabs( $only ) ) {
				return null;
			}
		}
		return array( substr( $html, $at, $end - $at ), substr( $html, $end ) );
	}

	/**
	 * Whether HTML starts with the library's tab strip (`<nav class="rooster-admin-tabs …">`, Ui::tabs()).
	 *
	 * @param string $html HTML.
	 */
	private static function is_tabs( string $html ): bool {
		return 1 === preg_match( '/^<nav\b[^>]*\sclass="(?:[^"]*\s)?rooster-admin-tabs(?:\s[^"]*)?"/i', $html );
	}

	/**
	 * A board from its bands (escaped).
	 *
	 * @param string                           $key   The board's key (see open()).
	 * @param array<int, array<string, mixed>> $bands Each: title (raw: an overline label of the cards under it),
	 *                                                description (raw), key (stable: the saved layout's name for the
	 *                                                band; by default its title's slug, or its card's id for a band of
	 *                                                one card, else its place), id (0.61.1: the band's anchor, on its element: a deep link, a palette entry; no pin), cols (1 to 4, or one of LAYOUTS: '2:1', '1:2:1'…; the person may choose another, 0.80.0), rows (a
	 *                                                band of equal-height rows: the cards side by side, reordered
	 *                                                only), fixed (nothing in it moves and it keeps its place: a guided
	 *                                                set-up, a wizard), min (rem: the band's own minimum column width),
	 *                                                and its cards as one of: `cards` (HTML strings; each placed in its
	 *                                                `col`, else the column holding the fewest so far), `columns` (lists
	 *                                                of HTML strings: the default columns), `full` (one card across the
	 *                                                board). A card with `span` all in a band of columns stands as a band
	 *                                                of its own where it comes.
	 * @param array<string, mixed>             $opts  movable (false: nothing on the board moves), saved (the
	 *                                                arrangement to apply instead of the user's; tests), reset (false:
	 *                                                the page prints its own Reset
	 *                                                layout, the Home's in its summary), class, head (0.58.2: escaped
	 *                                                HTML above the bands, out of the move set: a module's tab strip,
	 *                                                which a printed board takes by itself from what it receives first).
	 */
	public static function render( string $key, array $bands, array $opts = array() ): string {
		$bands = self::normalise( $bands );
		$saved = array_key_exists( 'saved', $opts ) ? $opts['saved'] : self::saved( $key );
		return self::html( $key, self::arrange( $bands, is_array( $saved ) ? $saved : null ), $opts );
	}

	/**
	 * The bands as the board arranges them: each with its key, its cards as units, a band of one card across the board
	 * for every card that spans it, the keys unique.
	 *
	 * @param array<int, array<string, mixed>> $bands See render().
	 * @return list<array<string, mixed>>
	 */
	public static function normalise( array $bands ): array {
		$out  = array();
		$seen = array();
		foreach ( array_values( $bands ) as $n => $band ) {
			if ( ! is_array( $band ) ) {
				continue;
			}
			if ( isset( $band['raw'] ) ) {
				$out[] = array(
					'raw'   => (string) $band['raw'],
					'fixed' => true,
					'key'   => '',
				);
				continue;
			}
			[ $cols, $ratio ] = self::cols( $band['cols'] ?? 1 );
			$layout           = self::layout_of( $cols, $ratio );
			$rows             = ! empty( $band['rows'] );
			$units            = array();
			if ( isset( $band['full'] ) ) {
				foreach ( self::units( (string) $band['full'] ) as $unit ) {
					$unit['span'] = true;
					$units[]      = $unit;
				}
			} elseif ( isset( $band['columns'] ) && is_array( $band['columns'] ) ) {
				foreach ( array_values( $band['columns'] ) as $c => $column ) {
					foreach ( (array) $column as $html ) {
						foreach ( self::units( (string) $html ) as $unit ) {
							$unit['col'] = $c + 1; // the band's columns are the defaults
							$units[]     = $unit;
						}
					}
				}
			} else {
				foreach ( (array) ( $band['cards'] ?? array() ) as $card ) {
					foreach ( is_array( $card ) ? array( $card ) : self::units( (string) $card ) as $unit ) {
						$units[] = $unit;
					}
				}
			}
			$title = (string) ( $band['title'] ?? '' );
			$base  = array(
				'title'       => $title,
				'description' => (string) ( $band['description'] ?? '' ),
				'cols'        => $cols,
				'ratio'       => $ratio,
				'layout'      => $layout, // 0.80.0: as the person sees it (theirs, once arrange() applies it)
				'default'     => $layout, // and as the product made it
				'rows'        => $rows,
				'fixed'       => ! empty( $band['fixed'] ),
				'min'         => (float) ( $band['min'] ?? 0 ),
				// 0.61.1, Rooster One's waves: the band's own anchor (a titled band that was an outer box with a catalogue
				// row, a deep link and a palette entry: the surveys' group banners); no pin, the band does not move for it.
				'id'          => 1 === preg_match( '/^[A-Za-z][A-Za-z0-9_-]*$/', (string) ( $band['id'] ?? '' ) ) ? (string) $band['id'] : '',
			);
			$key   = (string) ( $band['key'] ?? ( '' !== $title ? sanitize_title( $title ) : '' ) );
			$full  = isset( $band['full'] ) || ( 1 === $cols && ! $rows && 1 === count( $units ) && ! empty( $units[0]['span'] ) );
			// A card that spans the board stands as a band of its own (layout §2.2): the band is cut around it.
			$part = array();
			$cut  = 0;
			$push = static function ( array $cards, bool $alone ) use ( &$out, &$seen, &$cut, $base, $key, $n ): void {
				if ( array() === $cards ) {
					return;
				}
				$band = $base;
				if ( $cut > 0 ) {
					$band['title']       = ''; // the title heads the band's first part only, and its anchor
					$band['description'] = '';
					$band['id']          = '';
				}
				$band['cards'] = $cards;
				$band['had']   = true; // 0.80.0: emptied by the person, it hides outside the edit mode
				$band['full']  = $alone;
				if ( $alone && ! empty( $cards[0]['alone'] ) ) {
					$band['fixed'] = true; // a side panel's layout (0.68.10): where the product put it
				}
				$name          = $alone && '' !== (string) $cards[0]['key'] && ( $cut > 0 || '' === $key ) ? (string) $cards[0]['key'] : ( '' !== $key ? $key : 'band-' . ( $n + 1 ) );
				$name          = $cut > 0 && ! $alone ? $name . '-' . ( $cut + 1 ) : $name;
				while ( isset( $seen[ $name ] ) ) {
					$name .= '-x';
				}
				$seen[ $name ] = true;
				$band['key']   = $name;
				$out[]         = $band;
				++$cut;
			};
			if ( $full ) {
				$push( $units, true );
				continue;
			}
			foreach ( $units as $unit ) {
				if ( ! empty( $unit['span'] ) && ( $cols > 1 || $rows || ! empty( $unit['alone'] ) ) ) {
					$push( $part, false );
					$part = array();
					$push( array( $unit ), true );
					continue;
				}
				$part[] = $unit;
			}
			$push( $part, false );
			if ( 0 === $cut ) { // an empty band keeps its head
				$band          = $base;
				$band['cards'] = array();
				$band['full']  = false;
				$band['key']   = '' !== $key ? $key : 'band-' . ( $n + 1 );
				$out[]         = $band;
			}
		}
		return $out;
	}

	/**
	 * A band's column count and ratio from its `cols`.
	 *
	 * @param mixed $cols 1 to 4, or one of LAYOUTS ('2:1', '1:2:1'; 0.80.0: any of them).
	 * @return array{0: int, 1: string}
	 */
	private static function cols( $cols ): array {
		if ( is_string( $cols ) && in_array( $cols, self::LAYOUTS, true ) ) {
			return self::shape( $cols );
		}
		return array( max( 1, min( self::MAX_COLS, (int) $cols ) ), '' );
	}

	/**
	 * A layout's column count and its ratio as the band's class names it ('1-2'; '' when its columns are equal).
	 *
	 * @param string $layout One of LAYOUTS.
	 * @return array{0: int, 1: string}
	 */
	public static function shape( string $layout ): array {
		$parts = self::parts( $layout );
		return array( count( $parts ), count( array_unique( $parts ) ) > 1 ? implode( '-', $parts ) : '' );
	}

	/**
	 * A layout's columns, each its width in parts ('1:2' => [1, 2]).
	 *
	 * @param string $layout A layout.
	 * @return list<int>
	 */
	public static function parts( string $layout ): array {
		return array_map( 'intval', explode( ':', $layout ) );
	}

	/**
	 * The layout of a column count and a ratio (2 and '' => '1:1', 2 and '2-1' => '2:1').
	 *
	 * @param int    $cols  Columns.
	 * @param string $ratio The ratio's class part, or ''.
	 */
	public static function layout_of( int $cols, string $ratio ): string {
		return '' !== $ratio ? str_replace( '-', ':', $ratio ) : implode( ':', array_fill( 0, max( 1, $cols ), '1' ) );
	}

	/**
	 * Whether a band is a row of columns that takes the person's layout and swaps cards with the others (0.80.0): not
	 * fixed, not one card across the board, not a band of equal-height rows, not raw markup.
	 *
	 * @param array<string, mixed> $band A normalised band.
	 */
	public static function flex( array $band ): bool {
		return ! isset( $band['raw'] ) && empty( $band['fixed'] ) && empty( $band['full'] ) && empty( $band['rows'] );
	}

	/**
	 * Whether a band holds a card that needs the board's width (`span` all, in a band of one column, where it is not cut
	 * out): such a row keeps its one column, and the card stays in it (0.80.0).
	 *
	 * @param array<string, mixed> $band A normalised band.
	 */
	private static function holds_wide( array $band ): bool {
		foreach ( (array) ( $band['cards'] ?? array() ) as $unit ) {
			if ( ! empty( $unit['span'] ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * The cards of an HTML string: its top-level card sections, or the whole string as one card without a key when
	 * anything else stands between them (a card wrapped in a form, a script after it: kept whole, never split).
	 *
	 * @param string $html Escaped HTML.
	 * @return list<array<string, mixed>>
	 */
	public static function units( string $html ): array {
		if ( self::blank( $html ) ) {
			return array();
		}
		$parts = self::split( $html );
		if ( null === $parts ) {
			return array(
				array(
					'html'    => $html,
					'key'     => '',
					'col'     => 0,
					'span'    => false,
					'min'     => 0.0,
					'movable' => false,
					'title'   => '',
				),
			);
		}
		return $parts;
	}

	/**
	 * Splits HTML at its top-level card sections (`<section class="rooster-admin-card …">`); null when anything seen
	 * stands outside them (a paragraph, a notice, a form around cards: never split), or an element does not close.
	 *
	 * What is never seen stands aside (0.58.1, Rooster One's pilot: 143 of its modules print an inline script, 44 an
	 * inline style, between or after their cards): white space and comments, a script, a style, a link, a hidden
	 * input, a template, a noscript, an element with the `hidden` attribute (a modal waiting to open), a dialog that is
	 * not open. Each travels with the card that follows it (`before`), those after the last card with that card
	 * (`after`), so the scripts keep their order as printed; HTML of such nodes alone is one unit without a key.
	 *
	 * A side panel's layout (0.68.10, Rooster One's request 51: Ui::panel_open() … panel_close(), its cards in its main
	 * column and its panel) is a unit of its own, kept whole: across the board, never moving, no key; a board prints
	 * it in a band of its own (`alone`), fixed in its place, whether it stands in a band or outside any. So is a page's
	 * windows (0.68.13, Ui::windows(): Rooster One's chat, on a board).
	 *
	 * @param string $html Escaped HTML.
	 * @return list<array<string, mixed>>|null
	 */
	public static function split( string $html ): ?array {
		$units   = array();
		$pending = '';
		$at      = 0;
		$length  = strlen( $html );
		while ( true ) {
			if ( 1 === preg_match( '/\G(?:\s+|<!--.*?-->)+/s', $html, $space, 0, $at ) ) {
				$at += strlen( $space[0] );
			}
			if ( $at >= $length ) {
				break;
			}
			if ( 1 !== preg_match( '/\G<([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*>/', $html, $open, 0, $at ) ) {
				return null; // text, or a tag that closes what this HTML did not open
			}
			$tag = strtolower( $open[1] );
			if ( 'div' === $tag && 1 === preg_match( '/\sclass="(?:[^"]*\s)?rooster-admin-(?:split|windows)(?:\s[^"]*)?"/', $open[0] ) ) {
				$end = self::end_of( $html, 'div', $at );
				if ( null === $end ) {
					return null;
				}
				$units[] = array(
					'html'    => substr( $html, $at, $end - $at ),
					'key'     => '',
					'col'     => 0,
					'span'    => true,
					'min'     => 0.0,
					'movable' => false,
					'title'   => '',
					'alone'   => true,
					'before'  => $pending,
				);
				$pending = '';
				$at      = $end;
				continue;
			}
			if ( 'section' === $tag && 1 === preg_match( '/\sclass="(?:[^"]*\s)?rooster-admin-card(?:\s[^"]*)?"/', $open[0] ) ) {
				$end = self::end_of( $html, 'section', $at );
				if ( null === $end ) {
					return null;
				}
				$unit           = self::unit( substr( $html, $at, $end - $at ) );
				$unit['before'] = $pending;
				$units[]        = $unit;
				$pending        = '';
				$at             = $end;
				continue;
			}
			// 0.83.0: a form that holds one card and nothing else seen is that card's own form (FR1: a card saves with its
			// own form): the two are one unit, the card's place, key and grip on the form, and move together.
			$end  = 'form' === $tag ? self::end_of( $html, 'form', $at ) : null;
			$card = null !== $end ? self::form_card( substr( $html, $at, $end - $at ) ) : null;
			if ( null !== $card ) {
				$unit           = self::unit( $card );
				$unit['html']   = substr( $html, $at, $end - $at );
				$unit['before'] = $pending;
				$units[]        = $unit;
				$pending        = '';
				$at             = $end;
				continue;
			}
			$end = self::unseen( $html, $tag, $open[0], $at );
			if ( null === $end ) {
				return null;
			}
			$pending .= substr( $html, $at, $end - $at );
			$at       = $end;
		}
		if ( '' === $pending ) {
			return $units;
		}
		if ( array() === $units ) {
			return array( self::unseen_unit( $pending ) );
		}
		$units[ count( $units ) - 1 ]['after'] = $pending;
		return $units;
	}

	/**
	 * The one card a form holds (0.83.0, split()): its section's HTML when the form's content is one card and what is never
	 * seen (hidden inputs, scripts), else null.
	 *
	 * @param string $form The form's HTML, from its opening tag to its closing one.
	 */
	private static function form_card( string $form ): ?string {
		$start = strpos( $form, '>' );
		$close = strripos( $form, '</form' );
		if ( false === $start || false === $close || $close <= $start ) {
			return null;
		}
		$units = self::split( substr( $form, $start + 1, $close - $start - 1 ) );
		$cards = null === $units ? array() : array_values( array_filter( $units, static fn( array $unit ): bool => empty( $unit['unseen'] ) ) );
		if ( 1 !== count( $cards ) || ! empty( $cards[0]['alone'] ) || '' === (string) $cards[0]['key'] || 1 !== preg_match( '#^\s*<section\b#i', (string) $cards[0]['html'] ) ) {
			return null;
		}
		return (string) $cards[0]['html'];
	}

	/**
	 * The end of an element that is never seen and starts at `$at`, or null when it is seen (or never closes).
	 *
	 * @param string $html The HTML.
	 * @param string $tag  Its tag name, lower case.
	 * @param string $open Its opening tag.
	 * @param int    $at   Where it starts.
	 */
	private static function unseen( string $html, string $tag, string $open, int $at ): ?int {
		if ( 'script' === $tag || 'style' === $tag ) { // raw text: to its own closing tag, whatever it holds
			$close = stripos( $html, '</' . $tag, $at + strlen( $open ) );
			$gt    = false === $close ? false : strpos( $html, '>', $close );
			return false === $gt ? null : $gt + 1;
		}
		if ( 'link' === $tag || ( 'input' === $tag && 1 === preg_match( '/\stype\s*=\s*["\']?hidden\b/i', $open ) ) ) {
			return $at + strlen( $open ); // void
		}
		$attrs = (string) preg_replace( '/"[^"]*"|\'[^\']*\'/', '""', $open ); // the attributes' names, their values emptied
		$flag  = static fn( string $name ): bool => 1 === preg_match( '/\s' . $name . '(?=[\s>\/=])/i', $attrs );
		if ( 'template' === $tag || 'noscript' === $tag || $flag( 'hidden' ) || ( 'dialog' === $tag && ! $flag( 'open' ) ) ) {
			return self::end_of( $html, $tag, $at );
		}
		return null;
	}

	/**
	 * The end of the element whose opening tag starts at `$at`: past its closing tag, its own nested elements of the
	 * same name counted, comments, scripts and styles skipped whole (a script may hold "<section" in a string); null
	 * when it never closes.
	 *
	 * @param string $html The HTML.
	 * @param string $tag  Its tag name, lower case.
	 * @param int    $at   Where it starts.
	 */
	private static function end_of( string $html, string $tag, int $at ): ?int {
		$pattern = '#<!--.*?-->|<(script|style)\b[^>]*>.*?</\1\s*>|<(/?)' . preg_quote( $tag, '#' ) . '\b[^>]*>#is';
		if ( ! preg_match_all( $pattern, $html, $hits, PREG_SET_ORDER | PREG_OFFSET_CAPTURE, $at ) ) {
			return null;
		}
		$depth = 0;
		foreach ( $hits as $hit ) {
			if ( ! isset( $hit[2] ) || -1 === $hit[2][1] ) {
				continue; // a comment, a script, a style
			}
			$depth += '/' === $hit[2][0] ? -1 : 1;
			if ( 0 === $depth ) {
				return $hit[0][1] + strlen( $hit[0][0] );
			}
		}
		return null;
	}

	/**
	 * Whether units are only what is never seen (split() of a script, a style, a hidden modal).
	 *
	 * @param list<array<string, mixed>> $units split()'s units.
	 */
	private static function unseen_only( array $units ): bool {
		return 1 === count( $units ) && ! empty( $units[0]['unseen'] );
	}

	/**
	 * HTML that is never seen, alone: a unit without a key, printed where it stands.
	 *
	 * @param string $html The HTML.
	 * @return array<string, mixed>
	 */
	private static function unseen_unit( string $html ): array {
		return array(
			'html'    => $html,
			'key'     => '',
			'col'     => 0,
			'span'    => false,
			'min'     => 0.0,
			'movable' => false,
			'title'   => '',
			'unseen'  => true,
		);
	}

	/**
	 * One card's place on the board, read back from its section (the card helper's data attributes): its key (the id,
	 * the frozen anchor its pin and deep links use), its default column, whether it spans the board, its minimum
	 * width, whether it moves, its title (the grip's name).
	 *
	 * @param string $html The card's escaped HTML.
	 * @return array<string, mixed>
	 */
	public static function unit( string $html ): array {
		$open = 1 === preg_match( '#^\s*<section\b([^>]*)>#i', $html, $m ) ? $m[1] : '';
		$attr = static function ( string $name ) use ( $open ): ?string {
			return 1 === preg_match( '/\s' . preg_quote( $name, '/' ) . '="([^"]*)"/', $open, $a ) ? html_entity_decode( $a[1], ENT_QUOTES, 'UTF-8' ) : null;
		};
		$key   = (string) ( $attr( 'data-ra-key' ) ?? $attr( 'id' ) ?? '' );
		$title = 1 === preg_match( '#<h[23]\b[^>]*\bclass="rooster-admin-card__title"[^>]*>(.*?)</h[23]>#s', $html, $t ) ? trim( html_entity_decode( wp_strip_all_tags( $t[1] ), ENT_QUOTES, 'UTF-8' ) ) : '';
		return array(
			'html'    => $html,
			'key'     => 1 === preg_match( self::CARD_PATTERN, $key ) ? $key : '',
			'col'     => max( 0, (int) $attr( 'data-ra-col' ) ),
			'span'    => 'all' === $attr( 'data-ra-span' ),
			'min'     => max( 0.0, (float) $attr( 'data-ra-min' ) ),
			'movable' => 'false' !== $attr( 'data-ra-movable' ),
			'title'   => $title,
		);
	}

	/**
	 * Whether HTML is only white space and comments.
	 *
	 * @param string $html HTML.
	 */
	private static function blank( string $html ): bool {
		return '' === trim( (string) preg_replace( '/<!--.*?-->/s', '', $html ) );
	}

	/**
	 * The bands in the person's arrangement: the bands that move (those not fixed) in the saved order, new ones at
	 * their own place; each band's cards in the saved columns, unknown ones dropped, new ones placed by default (their
	 * `col`, else the column with the fewest cards so far: the Home's rule), a column the band no longer has folded
	 * into its last.
	 *
	 * @param list<array<string, mixed>> $bands normalise()'s bands.
	 * @param array<string, mixed>|null  $saved {o: [band keys], c: {band key: [[card keys], …]}}.
	 * @return list<array<string, mixed>> The bands, each with `columns` (lists of units).
	 */
	public static function arrange( array $bands, ?array $saved ): array {
		$order   = is_array( $saved['o'] ?? null ) ? $saved['o'] : array();
		$columns = is_array( $saved['c'] ?? null ) ? $saved['c'] : array();
		$layouts = is_array( $saved['l'] ?? null ) ? $saved['l'] : array();
		// The rows the person added (0.80.0): empty rows of columns of their own, which the order places as it places the
		// product's bands.
		$keys = array();
		foreach ( $bands as $band ) {
			$keys[ (string) ( $band['key'] ?? '' ) ] = true;
		}
		// They stand before the first band that moves, as the script adds them, so the order's slots are the page's.
		$added = array();
		foreach ( is_array( $saved['r'] ?? null ) ? array_slice( $saved['r'], 0, self::MAX_ROWS ) : array() as $row ) {
			if ( is_string( $row ) && 1 === preg_match( self::ROW_PATTERN, $row ) && ! isset( $keys[ $row ] ) ) {
				$keys[ $row ] = true;
				$added[]      = array(
					'title'       => '',
					'description' => '',
					'cols'        => 2,
					'ratio'       => '',
					'layout'      => '1:1',
					'default'     => '',
					'rows'        => false,
					'fixed'       => false,
					'min'         => 0.0,
					'id'          => '',
					'key'         => $row,
					'cards'       => array(),
					'full'        => false,
					'person'      => true,
				);
			}
		}
		if ( $added ) {
			$first = count( $bands );
			foreach ( $bands as $i => $band ) {
				if ( empty( $band['fixed'] ) ) {
					$first = $i;
					break;
				}
			}
			array_splice( $bands, $first, 0, $added );
		}
		// The slots of the bands that move, in the person's order.
		$moving = array();
		foreach ( $bands as $i => $band ) {
			if ( empty( $band['fixed'] ) ) {
				$moving[ (string) $band['key'] ] = $i;
			}
		}
		$keys = array();
		foreach ( $order as $k ) {
			if ( is_string( $k ) && isset( $moving[ $k ] ) && ! in_array( $k, $keys, true ) ) {
				$keys[] = $k;
			}
		}
		$at = 0;
		foreach ( array_keys( $moving ) as $k ) {
			$k = (string) $k;
			if ( ! in_array( $k, $keys, true ) ) {
				array_splice( $keys, min( $at, count( $keys ) ), 0, array( $k ) );
			}
			++$at;
		}
		$out  = array();
		$next = 0;
		foreach ( $bands as $band ) {
			if ( empty( $band['fixed'] ) ) {
				$band = $bands[ $moving[ $keys[ $next ] ] ];
				++$next;
			}
			// A row of columns takes the person's layout (0.80.0), but for one that holds a card needing the board's
			// width: it keeps its one column.
			$wide = self::flex( $band ) && self::holds_wide( $band );
			if ( $wide ) {
				$band['wide'] = true;
			}
			$layout = self::flex( $band ) && ! $wide ? ( $layouts[ (string) $band['key'] ] ?? '' ) : '';
			if ( is_string( $layout ) && in_array( $layout, self::LAYOUTS, true ) ) {
				[ $band['cols'], $band['ratio'] ] = self::shape( $layout );
				$band['layout']                   = $layout;
			}
			$out[] = $band;
		}
		// The cards of the rows of columns move between them (0.80.0): each where the person left it, in whichever row;
		// the rest in their own row by default. A card moves between rows when it moves at all and does not need the
		// board's width; a key printed twice moves once (its first copy). Each card is numbered (`n`) so that every
		// copy is placed once, and takes its band's minimum width with it. Any other band keeps its own cards, as before.
		$pool = array();
		$n    = 0;
		foreach ( $out as $i => $band ) {
			if ( ! self::flex( $band ) ) {
				continue;
			}
			foreach ( $band['cards'] as $j => $unit ) {
				$unit['n']                = ++$n;
				$unit['min']              = max( (float) $unit['min'], (float) $band['min'] );
				$out[ $i ]['cards'][ $j ] = $unit;
				$key                      = (string) $unit['key'];
				if ( '' !== $key && ! empty( $unit['movable'] ) && empty( $unit['span'] ) && ! isset( $pool[ $key ] ) ) {
					$pool[ $key ] = $unit;
				}
			}
		}
		$placed = array();
		$filled = array();
		foreach ( $out as $i => $band ) {
			if ( ! self::flex( $band ) ) {
				continue;
			}
			// The row's own cards that stay in it (one that does not move, one that needs the board's width, a key's
			// second copy) keep their saved places there too.
			$own = array();
			foreach ( $band['cards'] as $unit ) {
				$key = (string) $unit['key'];
				if ( '' !== $key && ! isset( $own[ $key ] ) && ( ! isset( $pool[ $key ] ) || $pool[ $key ]['n'] !== $unit['n'] ) ) {
					$own[ $key ] = $unit;
				}
			}
			$cols         = max( 1, (int) $band['cols'] );
			$filled[ $i ] = array_fill( 0, $cols, array() );
			$saved_cols   = $columns[ (string) $band['key'] ] ?? array();
			foreach ( array_values( is_array( $saved_cols ) ? $saved_cols : array() ) as $c => $column ) {
				foreach ( is_array( $column ) ? $column : array() as $key ) {
					if ( ! is_string( $key ) ) {
						continue;
					}
					$unit = isset( $pool[ $key ] ) && ! isset( $placed[ $pool[ $key ]['n'] ] ) ? $pool[ $key ] : null;
					$unit = null === $unit && isset( $own[ $key ] ) && ! isset( $placed[ $own[ $key ]['n'] ] ) ? $own[ $key ] : $unit;
					if ( null !== $unit ) {
						$filled[ $i ][ min( $c, $cols - 1 ) ][] = $unit;
						$placed[ $unit['n'] ]                   = true;
					}
				}
			}
		}
		foreach ( $out as $i => $band ) {
			if ( isset( $band['raw'] ) ) {
				continue;
			}
			if ( ! self::flex( $band ) ) {
				$saved_cols            = ! empty( $band['fixed'] ) ? null : ( $columns[ (string) $band['key'] ] ?? null );
				$out[ $i ]['columns'] = self::place( $band['cards'], ! empty( $band['full'] ) || ! empty( $band['rows'] ) ? 1 : (int) $band['cols'], is_array( $saved_cols ) ? $saved_cols : null );
				continue;
			}
			$rest = array();
			foreach ( $band['cards'] as $unit ) {
				if ( ! isset( $placed[ $unit['n'] ] ) ) {
					$rest[] = $unit;
				}
			}
			$out[ $i ]['columns'] = self::spread( $filled[ $i ], $rest );
		}
		return $out;
	}

	/**
	 * A band's cards in its columns: the saved ones first, where the person left them; the rest by default.
	 *
	 * @param list<array<string, mixed>> $units The band's cards.
	 * @param int                        $cols  Its columns.
	 * @param array<int, mixed>|null     $saved Lists of card keys.
	 * @return list<list<array<string, mixed>>>
	 */
	public static function place( array $units, int $cols, ?array $saved ): array {
		$cols   = max( 1, $cols );
		$out    = array_fill( 0, $cols, array() );
		$byKey  = array(); // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
		$placed = array();
		foreach ( $units as $i => $unit ) {
			if ( '' !== (string) $unit['key'] ) {
				$byKey[ (string) $unit['key'] ] = $i; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
			}
		}
		foreach ( array_values( (array) $saved ) as $c => $column ) {
			foreach ( is_array( $column ) ? $column : array() as $key ) {
				if ( is_string( $key ) && isset( $byKey[ $key ] ) && ! isset( $placed[ $byKey[ $key ] ] ) ) { // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
					$out[ min( $c, $cols - 1 ) ][]  = $units[ $byKey[ $key ] ]; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
					$placed[ $byKey[ $key ] ] = true; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
				}
			}
		}
		$rest = array();
		foreach ( $units as $i => $unit ) {
			if ( ! isset( $placed[ $i ] ) ) {
				$rest[] = $unit;
			}
		}
		return self::spread( $out, $rest );
	}

	/**
	 * Cards added to columns by default: each in its `col` (the last column when the row has fewer), else the column
	 * holding the fewest cards so far (the Home's rule).
	 *
	 * @param list<list<array<string, mixed>>> $columns The columns so far.
	 * @param list<array<string, mixed>>       $units   The cards to add, in order.
	 * @return list<list<array<string, mixed>>>
	 */
	private static function spread( array $columns, array $units ): array {
		$cols = max( 1, count( $columns ) );
		foreach ( $units as $unit ) {
			$col = (int) $unit['col'];
			if ( $col < 1 ) {
				$load = array_map( 'count', $columns );
				$col  = (int) array_search( min( $load ), $load, true ) + 1;
			}
			$columns[ min( $col, $cols ) - 1 ][] = $unit;
		}
		return $columns;
	}

	/**
	 * The width (rem) under which a band goes to one column: what its columns need at their minimum width (the
	 * band's own `min` or its widest card's), snapped up to a threshold; the default for its columns without one.
	 *
	 * @param array<string, mixed> $band An arranged band.
	 */
	public static function threshold( array $band ): int {
		$cols = (int) $band['cols'];
		if ( $cols < 2 || ! empty( $band['full'] ) ) {
			return 0;
		}
		$layout = (string) ( $band['layout'] ?? self::layout_of( $cols, (string) $band['ratio'] ) );
		$parts  = self::parts( $layout );
		$min    = (float) $band['min'];
		// The cards it holds (0.80.0: a row's columns may hold another row's cards), else the ones it was given.
		$units = isset( $band['columns'] ) && is_array( $band['columns'] ) ? array_merge( array(), ...array_values( $band['columns'] ) ) : (array) $band['cards'];
		foreach ( $units as $unit ) {
			$min = max( $min, (float) $unit['min'] );
		}
		if ( $min <= 0 ) {
			// The page's own layout keeps the width it always had; the person's needs its narrowest column LAYOUT_MIN wide.
			if ( isset( self::DEFAULT_AT[ $layout ] ) && (string) ( $band['default'] ?? $layout ) === $layout ) {
				return self::DEFAULT_AT[ $layout ];
			}
			$min = self::LAYOUT_MIN;
		}
		// The narrowest column at the minimum width: a 2:1 pair's is a third of the parts, a 1:2:1 row's a quarter.
		$need = array_sum( $parts ) / max( 1, min( $parts ) ) * $min + ( $cols - 1 ) * self::GAP;
		foreach ( self::THRESHOLDS as $at ) {
			if ( $at >= $need ) {
				return $at;
			}
		}
		return self::THRESHOLDS[ count( self::THRESHOLDS ) - 1 ];
	}

	/**
	 * The board's markup from its arranged bands: each movable card with its grip, the bands with their heads, the
	 * Reset layout where the page head does not carry it. The Home calls it with its own arrangement.
	 *
	 * @param string                     $key   The board's key.
	 * @param list<array<string, mixed>> $bands arrange()'s bands.
	 * @param array<string, mixed>       $opts  See render().
	 */
	public static function html( string $key, array $bands, array $opts = array() ): string {
		$movable = false !== ( $opts['movable'] ?? true );
		$slots   = 0; // the bands that are not fixed: a card across the board moves its band among them
		foreach ( $bands as $band ) {
			if ( empty( $band['fixed'] ) && ! isset( $band['raw'] ) ) {
				++$slots;
			}
		}
		// The cards that may change row (0.80.0): those of the rows of columns, which swap cards and take layouts.
		$flex_cards = 0;
		$flex_rows  = 0;
		foreach ( $bands as $band ) {
			if ( $movable && self::flex( $band ) ) {
				++$flex_rows;
				foreach ( (array) ( $band['columns'] ?? array() ) as $column ) {
					foreach ( $column as $unit ) {
						$flex_cards += ( '' !== (string) $unit['key'] && $unit['movable'] && empty( $unit['span'] ) ) ? 1 : 0;
					}
				}
			}
		}
		$any   = false;
		$shown = false; // a grip printed visible: Reset layout shows
		$body  = '';
		foreach ( $bands as $band ) {
			if ( isset( $band['raw'] ) ) {
				$body .= (string) $band['raw'];
				continue;
			}
			$free  = $movable && empty( $band['fixed'] );
			$flex  = $free && self::flex( $band );
			$cards = 0;
			foreach ( $band['columns'] as $column ) {
				foreach ( $column as $unit ) {
					$cards += ( '' !== (string) $unit['key'] && $unit['movable'] ) ? 1 : 0;
				}
			}
			$cols = '';
			foreach ( $band['columns'] as $c => $column ) {
				$inner = '';
				foreach ( $column as $unit ) {
					// A card moves within its band when another moves there too; a card across the board moves its band
					// among the others that are not fixed (FR8: the grip only where something can move).
					// 0.80.0: a card of a row of columns moves while another such card does, into any of those rows; one that
					// needs the board's width moves within its own row only.
					// 0.82.0: the one card of the rows of columns has its grip too (the person may lay its row out, add a
					// row and move it there), printed hidden while it has nowhere to go: its row of one column. The
					// board's script shows it once it can go somewhere (FR8: the grip only where something can move).
					$can    = $free && '' !== (string) $unit['key'] && $unit['movable'] && ( ! empty( $band['full'] ) ? $slots > 1 : ( $flex && empty( $unit['span'] ) ? $flex_cards > 0 : $cards > 1 ) );
					$hide   = $can && $flex && empty( $band['full'] ) && empty( $unit['span'] ) && 1 === $flex_cards && count( $band['columns'] ) < 2;
					$any    = $any || $can;
					$shown  = $shown || ( $can && ! $hide );
					$inner .= self::card( $unit, $can, $hide );
				}
				$cols .= ! empty( $band['full'] ) || ! empty( $band['rows'] ) ? $inner : '<div class="rooster-admin-band__col" data-ra-col="' . ( $c + 1 ) . '">' . $inner . '</div>';
			}
			$at    = self::threshold( $band );
			$title = (string) $band['title'];
			$id    = '' !== $title ? 'rooster-admin-band-' . ( ++self::$bands ) : '';
			$tag   = '' !== $title ? 'section' : 'div';
			// A row of columns (0.80.0): its layout and the product's, whether the person added it, whether it is a row they
			// emptied (or added and left empty): hidden outside the edit mode, so nothing shows where nothing is.
			$person = ! empty( $band['person'] );
			$empty  = $flex && 0 === array_sum( array_map( 'count', $band['columns'] ) ) && ( $person || ! empty( $band['had'] ) );
			$class  = 'rooster-admin-band' . ( (int) $band['cols'] > 1 && empty( $band['full'] ) ? ' is-cols-' . (int) $band['cols'] : '' ) . ( '' !== (string) $band['ratio'] ? ' is-ratio-' . $band['ratio'] : '' )
				. ( ! empty( $band['rows'] ) ? ' is-rows' : '' ) . ( ! empty( $band['full'] ) ? ' is-full' : '' ) . ( $at > 0 ? ' is-at-' . $at : '' )
				. ( $person ? ' is-person' : '' ) . ( $empty ? ' is-empty' : '' );
			$flex_attrs = $flex && $flex_cards > 0
				? ' data-ra-flex="" data-ra-layout="' . esc_attr( (string) ( $band['layout'] ?? self::layout_of( (int) $band['cols'], (string) $band['ratio'] ) ) ) . '" data-ra-default-layout="' . esc_attr( (string) ( $band['default'] ?? '' ) ) . '"'
					. ( $person ? ' data-ra-person=""' : '' ) . ( ! empty( $band['had'] ) ? ' data-ra-had=""' : '' ) . ( (float) $band['min'] > 0 ? ' data-ra-min="' . esc_attr( (string) (float) $band['min'] ) . '"' : '' )
					. ( ! empty( $band['wide'] ) ? ' data-ra-layout-fixed=""' : '' )
				: '';
			$body .= '<' . $tag . ( '' !== (string) ( $band['id'] ?? '' ) ? ' id="' . esc_attr( (string) $band['id'] ) . '"' : '' ) . ' class="' . esc_attr( $class ) . '" data-ra-band="' . esc_attr( (string) $band['key'] ) . '"' . ( ! $free ? ' data-ra-fixed=""' : '' ) . $flex_attrs . ( '' !== $id ? ' aria-labelledby="' . esc_attr( $id ) . '"' : '' ) . '>'
				. ( '' !== $title ? '<div class="rooster-admin-band__head"><p class="rooster-admin-band__title" id="' . esc_attr( $id ) . '">' . esc_html( $title ) . '</p>' . ( '' !== (string) $band['description'] ? '<p class="rooster-admin-band__desc">' . esc_html( (string) $band['description'] ) . '</p>' : '' ) . '</div>' : '' )
				. '<div class="' . ( ! empty( $band['full'] ) ? 'rooster-admin-band__full' : 'rooster-admin-band__grid' ) . '">' . $cols . '</div></' . $tag . '>';
		}
		// Edit layout (0.80.0) where the rows of columns hold a card (0.82.0: one is enough, the owner, 7 Nov 2026: every
		// page's layout is the person's): in the page head (or the Home's summary) when the page put it there, else on
		// the board's bar with Reset layout, which is hidden while no grip shows (the script shows it with the grip).
		$edit = $movable && $flex_rows > 0 && $flex_cards > 0;
		$bar  = ( $edit && ! isset( self::$head_edit[ $key ] ) ? self::edit_button( $key ) : '' )
			. ( $any && ! isset( self::$head_reset[ $key ] ) && false !== ( $opts['reset'] ?? true ) ? self::reset_button( $key, false, ! $shown ) : '' );
		$bar  = '' !== $bar ? '<div class="rooster-admin-board__bar">' . $bar . '</div>' : '';
		if ( $any ) {
			wp_enqueue_script( 'rooster-admin-board' ); // the moves, on a screen whose board has something to move
		}
		$head = '' !== (string) ( $opts['head'] ?? '' ) ? '<div class="rooster-admin-board__head">' . $opts['head'] . '</div>' : ''; // escaped by the product: its tab strip as printed (0.58.2)
		// 0.86.2: what the page head's buttons, printed before the board, will show, so the stylesheet shows them from the
		// first paint (on a phone they took a line of the head when the script showed them, and the page moved 26 px).
		$shows = trim( ( $edit && isset( self::$head_edit[ $key ] ) ? 'edit ' : '' ) . ( $shown && isset( self::$head_reset[ $key ] ) && false !== ( $opts['reset'] ?? true ) ? 'reset' : '' ) );
		return '<div class="rooster-admin-board' . ( '' !== (string) ( $opts['class'] ?? '' ) ? ' ' . esc_attr( (string) $opts['class'] ) : '' ) . '" id="' . esc_attr( 'rooster-admin-board-' . sanitize_html_class( str_replace( '/', '-', $key ) ) ) . '" data-ra-board="' . esc_attr( $key ) . '"' . ( '' !== $shows ? ' data-ra-shows="' . $shows . '"' : '' ) . '>'
			. $head . $bar . $body . '</div>' . ( $any ? self::reset_dialog() : '' ) . ( $edit ? self::tools() : '' );
	}

	/**
	 * One card on the board: its key on its section, and the grip first in its head when it can move.
	 *
	 * @param array<string, mixed> $unit The card.
	 * @param bool                 $can  Whether it can move.
	 * @param bool                 $hide Whether its grip is printed hidden (0.82.0: the one card of the rows of columns,
	 *                                   with nowhere to go yet).
	 */
	private static function card( array $unit, bool $can, bool $hide = false ): string {
		$html = (string) $unit['html'];
		$key  = (string) $unit['key'];
		$near = array( (string) ( $unit['before'] ?? '' ), (string) ( $unit['after'] ?? '' ) ); // what is never seen, around it as printed (0.58.1)
		if ( '' === $key ) {
			return $near[0] . $html . $near[1];
		}
		// On the unit's own element: the card's section, or the form that holds it (0.83.0, split()).
		if ( false === strpos( (string) strstr( $html, '>', true ), 'data-ra-key=' ) ) {
			$html = (string) preg_replace( '#^(\s*<(?:section|form)\b)#i', '$1 data-ra-key="' . esc_attr( $key ) . '"', $html, 1 );
		}
		// The minimum width it takes from its band (0.80.0), on the card, so it holds in another row and for the script.
		$min = (float) ( $unit['min'] ?? 0 );
		if ( $min > 0 && false === strpos( (string) strstr( $html, '>', true ), 'data-ra-min=' ) ) {
			$html = (string) preg_replace( '#^(\s*<(?:section|form)\b[^>]*)>#i', '$1 data-ra-min="' . esc_attr( (string) $min ) . '">', $html, 1 );
		}
		if ( ! empty( $unit['span'] ) && 1 === preg_match( '#^\s*<form\b#i', $html ) && false === strpos( (string) strstr( $html, '>', true ), 'data-ra-span=' ) ) {
			$html = (string) preg_replace( '#^(\s*<form\b)#i', '$1 data-ra-span="all"', $html, 1 ); // the script reads it on the unit
		}
		if ( $can ) {
			$html = (string) preg_replace( '#(<header class="rooster-admin-card__head"[^>]*>)#', '$1' . self::grip( (string) $unit['title'], $hide ), $html, 1 );
		}
		return $near[0] . $html . $near[1];
	}

	/**
	 * The grip of a card that can move (escaped): a button, so a click opens the Move menu; a drag or the arrow keys
	 * move the card at once.
	 *
	 * @param string $title  The card's title (raw).
	 * @param bool   $hidden Printed hidden (0.82.0: a card with nowhere to go yet; the board's script shows it).
	 */
	public static function grip( string $title, bool $hidden = false ): string {
		/* translators: %s: the card's title. */
		$label = sprintf( __( 'Move the card "%s": drag it, use the arrow keys, or press Enter for the Move menu', 'ai-eshop-optimizer' ), $title );
		return '<button type="button" class="rooster-admin-grip" data-ra-grip="" aria-haspopup="menu" aria-expanded="false" aria-label="' . esc_attr( $label ) . '" data-ra-tip="' . esc_attr__( 'Drag to move, or click for the Move menu', 'ai-eshop-optimizer' ) . '"' . ( $hidden ? ' hidden' : '' ) . '>' . Icons::ui( 'grip', 16 ) . '</button>';
	}

	/**
	 * The Reset layout button of a board (escaped): in the page head's actions (Ui::pagehead()'s `board`), else on
	 * the board. Hidden until the board's script finds something that can move (FR8: shown only then).
	 *
	 * @param string $key    The board's key.
	 * @param bool   $head   Whether it goes in the page head (printed before the board: the script shows it).
	 * @param bool   $hidden Printed hidden on the board too (0.82.0: no grip shows yet; the script shows it with one).
	 */
	public static function reset_button( string $key, bool $head = false, bool $hidden = false ): string {
		if ( $head ) {
			self::$head_reset[ $key ] = true;
		}
		return Ui::button(
			__( 'Reset layout', 'ai-eshop-optimizer' ),
			array(
				'variant' => 'ghost',
				'size'    => 'sm',
				'icon'    => 'rotate-ccw',
				'class'   => 'is-tip-end',
				'attrs'   => array(
					'data-ra-board-reset' => $key,
					'data-ra-tip'         => __( 'Every card back to where the page puts it; your pins are kept', 'ai-eshop-optimizer' ),
					'hidden'              => $head || $hidden,
					'data-ra-pending'     => $head, // 0.86.2: shown from the first paint where its board says so (CSS), until the script decides
				),
			)
		);
	}

	/**
	 * The reset confirmation (the Home's since 0.10; once per page): a modal dialog, the pins kept.
	 */
	public static function reset_dialog(): string {
		if ( self::$dialog ) {
			return '';
		}
		self::$dialog = true;
		return '<dialog class="rooster-admin-dialog rooster-admin-home__reset" id="rooster-admin-reset-dialog" aria-labelledby="rooster-admin-reset-title"><form method="dialog">'
			. '<div class="rooster-admin-dialog__header"><h2 id="rooster-admin-reset-title">' . esc_html__( 'Reset this page\'s layout?', 'ai-eshop-optimizer' ) . '</h2></div>'
			. '<div class="rooster-admin-dialog__body"><p>' . esc_html__( 'Every card goes back to where the page puts it, in its own column and order; the rows you added go and every row takes the page\'s own layout again. Your pinned items are kept.', 'ai-eshop-optimizer' ) . '</p>'
			. '<p data-ra-reset-cards="" hidden>' . esc_html__( 'The cards you hid on this page come back too.', 'ai-eshop-optimizer' ) . '</p></div>' // 0.64.3: chrome.js shows it while the page has one
			. '<div class="rooster-admin-dialog__footer"><button type="submit" value="cancel" class="rooster-admin-button rooster-admin-button--secondary">' . esc_html__( 'Cancel', 'ai-eshop-optimizer' ) . '</button>'
			. '<button type="submit" value="reset" class="rooster-admin-button rooster-admin-button--primary">' . esc_html__( 'Reset layout', 'ai-eshop-optimizer' ) . '</button></div></form></dialog>';
	}

	/**
	 * The Edit layout button of a board (0.80.0, escaped): a toggle, pressed while the page is in its edit mode (the rows'
	 * layouts, Add a row, moving and removing rows); its words become Done there. In the page head's actions
	 * (Ui::pagehead()'s `board`), the Home's summary, else the board's bar; hidden until the board's script finds rows of
	 * columns with two cards or more.
	 *
	 * @param string $key  The board's key.
	 * @param bool   $head Whether the page head (or another place printed before the board) carries it.
	 */
	public static function edit_button( string $key, bool $head = false ): string {
		if ( $head ) {
			self::$head_edit[ $key ] = true;
		}
		return Ui::button(
			__( 'Edit layout', 'ai-eshop-optimizer' ),
			array(
				'variant' => 'ghost',
				'size'    => 'sm',
				'icon'    => 'layout-grid',
				'class'   => 'is-tip-end',
				'attrs'   => array(
					'data-ra-board-edit' => $key,
					'aria-pressed'       => 'false',
					'data-ra-tip'        => __( 'Choose the columns of each row, add rows, move cards between them', 'ai-eshop-optimizer' ),
					'hidden'             => true,
					'data-ra-pending'    => $head, // 0.86.2: as Reset layout's
				),
			)
		);
	}

	/**
	 * Each layout's name, as the layout menu and the live region say it (0.80.0).
	 *
	 * @return array<string, string>
	 */
	public static function layout_names(): array {
		return array(
			'1'       => __( 'One column', 'ai-eshop-optimizer' ),
			'1:1'     => __( 'Two equal columns', 'ai-eshop-optimizer' ),
			'1:2'     => __( 'Two columns, the second twice as wide', 'ai-eshop-optimizer' ),
			'2:1'     => __( 'Two columns, the first twice as wide', 'ai-eshop-optimizer' ),
			'1:3'     => __( 'Two columns, the second three times as wide', 'ai-eshop-optimizer' ),
			'3:1'     => __( 'Two columns, the first three times as wide', 'ai-eshop-optimizer' ),
			'1:1:1'   => __( 'Three equal columns', 'ai-eshop-optimizer' ),
			'1:2:1'   => __( 'Three columns, the middle one twice as wide', 'ai-eshop-optimizer' ),
			'2:1:1'   => __( 'Three columns, the first twice as wide', 'ai-eshop-optimizer' ),
			'1:1:2'   => __( 'Three columns, the last twice as wide', 'ai-eshop-optimizer' ),
			'1:1:1:1' => __( 'Four equal columns', 'ai-eshop-optimizer' ),
		);
	}

	/**
	 * A layout's picture (escaped, decorative): its columns as bars in their widths.
	 *
	 * @param string $layout One of LAYOUTS.
	 */
	public static function layout_picture( string $layout ): string {
		$bars = '';
		foreach ( self::parts( $layout ) as $part ) {
			$bars .= '<span class="is-w' . (int) $part . '"></span>';
		}
		return '<span class="rooster-admin-layoutpic" aria-hidden="true">' . $bars . '</span>';
	}

	/**
	 * The edit mode's parts (0.80.0; once a page, escaped), inert in a template the board's script clones: Add a row (at
	 * the top of the board), a row's tools (its layout, up, down, remove) and the layout menu's items, each with its
	 * picture, its ratio and its name; the widths the script needs to send a row to one column (THRESHOLDS,
	 * DEFAULT_AT, LAYOUT_MIN, GAP) and the most rows a person adds (MAX_ROWS) as data.
	 */
	public static function tools(): string {
		if ( self::$tools ) {
			return '';
		}
		self::$tools = true;
		$items       = '';
		foreach ( self::layout_names() as $layout => $name ) {
			$items .= '<button type="button" class="rooster-admin-layoutmenu__item" role="menuitemradio" aria-checked="false" data-ra-layout-choice="' . esc_attr( $layout ) . '" data-ra-layout-name="' . esc_attr( $name ) . '">'
				. self::layout_picture( (string) $layout ) . '<span class="rooster-admin-layoutmenu__ratio">' . esc_html( (string) $layout ) . '</span><span class="rooster-admin-layoutmenu__name">' . esc_html( $name ) . '</span></button>';
		}
		$grid = array(
			't' => self::THRESHOLDS,
			'd' => self::DEFAULT_AT,
			'm' => self::LAYOUT_MIN,
			'g' => self::GAP,
			'x' => self::MAX_ROWS,
		);
		$small = static fn( string $label, string $icon, array $attrs ): string => Ui::button(
			$label,
			array(
				'variant'   => 'ghost',
				'size'      => 'sm',
				'icon'      => $icon,
				'icon_only' => true,
				'attrs'     => $attrs,
			)
		);
		return '<template id="rooster-admin-boardgrid" data-ra-grid="' . esc_attr( (string) wp_json_encode( $grid ) ) . '">'
			. '<div class="rooster-admin-board__add" data-ra-add-bar=""><button type="button" class="rooster-admin-button rooster-admin-button--sm" data-ra-row-add="">' . Icons::svg( 'plus', 15 ) . esc_html__( 'Add a row', 'ai-eshop-optimizer' ) . '</button>'
			. '<p class="rooster-admin-board__hint">' . esc_html__( 'A new row starts at the top: choose its layout, drag cards into its columns, move it where you like. Done keeps your layout; Reset layout brings back the page\'s own.', 'ai-eshop-optimizer' ) . '</p></div>'
			. '<div class="rooster-admin-band__tools" data-ra-row-tools=""><span class="rooster-admin-band__label" data-ra-row-label=""></span>'
			. '<button type="button" class="rooster-admin-button rooster-admin-button--sm rooster-admin-layoutbtn" data-ra-layout-open="" aria-haspopup="menu" aria-expanded="false" aria-label="' . esc_attr__( 'Layout of this row', 'ai-eshop-optimizer' ) . '"><span data-ra-layout-pic=""></span><span data-ra-layout-text=""></span></button>'
			. $small( __( 'Move this row up', 'ai-eshop-optimizer' ), 'arrow-up', array( 'data-ra-row-move' => 'up' ) )
			. $small( __( 'Move this row down', 'ai-eshop-optimizer' ), 'arrow-down', array( 'data-ra-row-move' => 'down' ) )
			. $small( __( 'Remove this row (its cards go to the row above)', 'ai-eshop-optimizer' ), 'trash-2', array( 'data-ra-row-remove' => '' ) )
			. '</div><div data-ra-layout-items="">' . $items . '</div></template>';
	}

	/**
	 * The current user's saved arrangement of a board of the current product (null when none).
	 *
	 * @param string $key The board's key.
	 * @return array<string, mixed>|null
	 */
	public static function saved( string $key ): ?array {
		$product = Library::product(); // 0.75.0: the registry's, or the storefront screen's
		if ( '' === $product || get_current_user_id() <= 0 ) {
			return null;
		}
		$all = Prefs::get( get_current_user_id(), Prefs::BOARDS, $product, array() );
		return is_array( $all ) && is_array( $all[ $key ] ?? null ) ? $all[ $key ] : null;
	}

	/**
	 * A board's arrangement from a client, its shape checked (the cards are checked when the board is drawn, as the
	 * Home's layout is): {o: [band keys], c: {band key: [[card keys] × 1 to 4]}, l: {band key: one of LAYOUTS}, r: [the added
	 * rows' keys]} (0.80.0: l and r); null when malformed.
	 *
	 * @param mixed $value Value.
	 * @return array<string, mixed>|null
	 */
	public static function clean( $value ): ?array {
		if ( ! is_array( $value ) || array() !== array_diff( array_keys( $value ), array( 'o', 'c', 'l', 'r' ) ) ) {
			return null;
		}
		// 0.80.0: the rows' layouts (band key => one of LAYOUTS) and the rows the person added (their keys, in order).
		$layouts = $value['l'] ?? array();
		$rows    = $value['r'] ?? array();
		if ( ! is_array( $layouts ) || count( $layouts ) > self::MAX_BANDS + self::MAX_ROWS || ! is_array( $rows ) || count( $rows ) > self::MAX_ROWS ) {
			return null;
		}
		$extra = array();
		foreach ( $layouts as $band => $layout ) {
			if ( ! is_string( $band ) || 1 !== preg_match( self::KEY_PATTERN, $band ) || ! is_string( $layout ) || ! in_array( $layout, self::LAYOUTS, true ) ) {
				return null;
			}
			$extra['l'][ $band ] = $layout;
		}
		foreach ( array_values( $rows ) as $row ) {
			if ( ! is_string( $row ) || 1 !== preg_match( self::ROW_PATTERN, $row ) || in_array( $row, $extra['r'] ?? array(), true ) ) {
				return null;
			}
			$extra['r'][] = $row;
		}
		$order = $value['o'] ?? array();
		$cols  = $value['c'] ?? array();
		if ( ! is_array( $order ) || count( $order ) > self::MAX_BANDS + self::MAX_ROWS || ! is_array( $cols ) || count( $cols ) > self::MAX_BANDS + self::MAX_ROWS ) {
			return null;
		}
		$out = array(
			'o' => array(),
			'c' => array(),
		);
		foreach ( $order as $band ) {
			if ( ! is_string( $band ) || 1 !== preg_match( self::KEY_PATTERN, $band ) || in_array( $band, $out['o'], true ) ) {
				return null;
			}
			$out['o'][] = $band;
		}
		foreach ( $cols as $band => $columns ) {
			if ( ! is_string( $band ) || 1 !== preg_match( self::KEY_PATTERN, $band ) || ! is_array( $columns ) || count( $columns ) < 1 || count( $columns ) > self::MAX_COLS ) {
				return null;
			}
			$seen = array();
			$list = array();
			foreach ( array_values( $columns ) as $column ) {
				if ( ! is_array( $column ) ) {
					return null;
				}
				$keys = array();
				foreach ( $column as $card ) {
					if ( ! is_string( $card ) || 1 !== preg_match( self::CARD_PATTERN, $card ) || isset( $seen[ $card ] ) || count( $seen ) >= self::MAX_CARDS ) {
						return null;
					}
					$seen[ $card ] = true;
					$keys[]        = $card;
				}
				$list[] = $keys;
			}
			$out['c'][ $band ] = $list;
		}
		return $out + $extra;
	}

	/**
	 * A product's saved boards with one board stored (or removed with null), the boards saved longest ago dropped
	 * until the whole fits MAX_BYTES; the board just saved last.
	 *
	 * @param mixed                     $boards The saved boards (board key => arrangement).
	 * @param string                    $key    The board's key.
	 * @param array<string, mixed>|null $layout clean()'s arrangement, or null.
	 * @return array<string, mixed>
	 */
	public static function store( $boards, string $key, ?array $layout ): array {
		$boards = is_array( $boards ) ? $boards : array();
		unset( $boards[ $key ] );
		if ( null !== $layout ) {
			$boards[ $key ] = $layout;
		}
		while ( count( $boards ) > 1 && strlen( (string) wp_json_encode( $boards ) ) > self::MAX_BYTES ) {
			array_shift( $boards );
		}
		return $boards;
	}

	/**
	 * The words of the board's moves (assets/board.js; 0.58.0 in the chrome's script data, 0.65.1 a table's own off the
	 * chrome, 0.75.0 here, printed before the script on the storefront too): where a moved card or row went, the Move menu.
	 *
	 * @return array<string, string>
	 */
	public static function words(): array {
		return array(
			/* translators: 1: the column, 2: the columns, 3: the card's place in its column, 4: the cards in it. */
			'column'     => __( 'Moved to column %1$s of %2$s, position %3$s of %4$s', 'ai-eshop-optimizer' ),
			/* translators: 1: the card's place, 2: the cards. */
			'position'   => __( 'Moved to position %1$s of %2$s', 'ai-eshop-optimizer' ),
			/* translators: 1: the band's place on the page, 2: the bands that move. */
			'band'       => __( 'Moved to place %1$s of %2$s on the page', 'ai-eshop-optimizer' ),
			'already'    => __( 'Already there', 'ai-eshop-optimizer' ),
			/* translators: %s: the card's title. */
			'menu'       => __( 'Move "%s"', 'ai-eshop-optimizer' ),
			'up'         => __( 'Move up', 'ai-eshop-optimizer' ),
			'down'       => __( 'Move down', 'ai-eshop-optimizer' ),
			'left'       => __( 'Move left', 'ai-eshop-optimizer' ),
			'right'      => __( 'Move right', 'ai-eshop-optimizer' ),
			/* translators: %s: a column's number. */
			'toColumn'   => __( 'Move to column %s', 'ai-eshop-optimizer' ),
			'top'        => __( 'Move to the top', 'ai-eshop-optimizer' ),
			'first'      => __( 'Move to the top of the page', 'ai-eshop-optimizer' ),
			// 0.80.0: the rows of columns, the edit mode.
			/* translators: 1: the row, 2: the rows, 3: the column, 4: the columns, 5: the card's place in its column, 6: the cards in it. */
			'rowColumn'  => __( 'Moved to row %1$s of %2$s, column %3$s of %4$s, position %5$s of %6$s', 'ai-eshop-optimizer' ),
			'rowAbove'   => __( 'Move to the row above', 'ai-eshop-optimizer' ),
			'rowBelow'   => __( 'Move to the row below', 'ai-eshop-optimizer' ),
			'edit'       => __( 'Edit layout', 'ai-eshop-optimizer' ),
			'done'       => __( 'Done', 'ai-eshop-optimizer' ),
			'editing'    => __( 'Editing the layout: each row has its layout and its tools; drag cards between rows. Done to finish.', 'ai-eshop-optimizer' ),
			'edited'     => __( 'Layout saved.', 'ai-eshop-optimizer' ),
			/* translators: 1: the row's place, 2: the rows. */
			'row'        => __( 'Row %1$s of %2$s', 'ai-eshop-optimizer' ),
			/* translators: 1: the row's place, 2: the rows, 3: its layout's name. */
			'layoutOf'   => __( 'Layout of row %1$s of %2$s: %3$s. Change it', 'ai-eshop-optimizer' ),
			/* translators: %s: the row's place. */
			'layoutMenu' => __( 'Layouts for row %s', 'ai-eshop-optimizer' ),
			/* translators: 1: the row's place, 2: its layout's name. */
			'layoutSet'  => __( 'Row %1$s: %2$s', 'ai-eshop-optimizer' ),
			'rowAdded'   => __( 'A row was added at the top. Choose its layout, then drag cards into it.', 'ai-eshop-optimizer' ),
			/* translators: 1: the row's new place, 2: the rows. */
			'rowMoved'   => __( 'The row moved to place %1$s of %2$s', 'ai-eshop-optimizer' ),
			'rowRemoved' => __( 'The row was removed; its cards went to the row above.', 'ai-eshop-optimizer' ),
			'rowFirst'   => __( 'The row was removed; its cards went to the row below.', 'ai-eshop-optimizer' ),
			'dropHere'   => __( 'Drop a card here', 'ai-eshop-optimizer' ),
			'maxRows'    => __( 'This page has as many added rows as it can take.', 'ai-eshop-optimizer' ),
			'wideRow'    => __( 'This row keeps one column: a card in it needs the page\'s width.', 'ai-eshop-optimizer' ),
		);
	}

	/**
	 * What went wrong this request, by board (tests and the rules: a band with content between its cards).
	 *
	 * @return array<string, string>
	 */
	public static function problems(): array {
		return self::$problems;
	}

	/**
	 * Forgets the request's state (tests: many pages in one process).
	 *
	 * @internal
	 */
	public static function forget(): void {
		self::$stack      = array();
		self::$head_reset = array();
		self::$head_edit  = array();
		self::$problems   = array();
		self::$bands      = 0;
		self::$dialog     = false;
		self::$tools      = false;
		self::$page       = null;
		self::$arranged   = '';
	}
}