@relvehq/agent-ready 0.3.0 → 0.4.0

package/dist/wp/relve-agent-ready/includes/class-relve-ar-markdown-builder.php

@@ -1,455 +1,455 @@
-<?php
-/**
- * Markdown builder: a post, page, the posts front page or an archive as one
- * Markdown document, from WordPress's own data (not scraped HTML).
- *
- *   ---
- *   title: "..."
- *   canonical: https://site/post/
- *   author: "..."
- *   published: 2026-10-01T09:00:00Z
- *   modified: 2026-10-02T10:00:00Z
- *   categories: ["News"]
- *   tags: ["AI"]
- *   description: "..."
- *   source: https://site/post/
- *   generator: agent-ready/native
- *   lang: en-US
- *   ---
- *
- *   # Title
- *
- *   ![featured image](...)
- *
- *   Content...
- *
- * The front-matter rules are the package's (core/enrich.ts): empty values
- * dropped, URLs / ISO dates / language tags plain, everything else
- * JSON-quoted. A document that already has front matter (a refined file
- * usually does not, but a hand-made one may) is left exactly as it is.
- *
- * @package Relve_Agent_Ready
- */
-
-if ( ! defined( 'ABSPATH' ) ) {
-	exit;
-}
-
-/**
- * Builds Markdown documents.
- */
-class Relve_AR_Markdown_Builder {
-
-	/** Posts listed on the front page / an archive. */
-	const ARCHIVE_LIMIT = 50;
-
-	// ── pure helpers (unit-tested) ────────────────────────────────────────
-
-	/**
-	 * A YAML front-matter block. Empty values (null, "", empty list) are dropped.
-	 *
-	 * @param array $fields Ordered key => string|int|string[].
-	 * @return string
-	 */
-	public static function front_matter( $fields ) {
-		$lines = array( '---' );
-		foreach ( $fields as $key => $value ) {
-			if ( null === $value || '' === $value || array() === $value ) {
-				continue;
-			}
-			if ( is_array( $value ) ) {
-				$items = array();
-				foreach ( $value as $item ) {
-					$item = self::one_line( (string) $item );
-					if ( '' !== $item ) {
-						$items[] = self::json( $item );
-					}
-				}
-				if ( ! $items ) {
-					continue;
-				}
-				$lines[] = $key . ': [' . implode( ', ', $items ) . ']';
-				continue;
-			}
-			$lines[] = $key . ': ' . self::yaml_scalar( $value );
-		}
-		$lines[] = '---';
-		return implode( "\n", $lines );
-	}
-
-	/**
-	 * Plain scalars for URLs, ISO dates, language tags and the generator;
-	 * JSON-quoted (valid YAML) for everything else. Same rule as the package.
-	 *
-	 * @param string|int $value Value.
-	 * @return string
-	 */
-	public static function yaml_scalar( $value ) {
-		if ( is_int( $value ) || is_float( $value ) ) {
-			return (string) $value;
-		}
-		$one = self::one_line( (string) $value );
-		if ( preg_match( '#^(https?://[^\s\#]+|\d{4}-\d{2}-\d{2}T[\d:.]+Z|[a-z]{2,3}(-[A-Za-z]{2,4})?|agent-ready/[a-z]+)$#', $one ) ) {
-			return $one;
-		}
-		return self::json( $one );
-	}
-
-	/**
-	 * Does the Markdown start with a front-matter block?
-	 *
-	 * @param string $markdown Markdown.
-	 * @return bool
-	 */
-	public static function has_front_matter( $markdown ) {
-		return (bool) preg_match( '/^---\r?\n[\s\S]*?\r?\n---\r?\n/', (string) $markdown );
-	}
-
-	/**
-	 * Final document: front matter, then the body. A body that already has
-	 * front matter is returned as it is (plus a final newline).
-	 *
-	 * @param array  $fields Front-matter fields.
-	 * @param string $body   Markdown body (starting with its H1).
-	 * @return string
-	 */
-	public static function assemble( $fields, $body ) {
-		$body = trim( (string) $body );
-		if ( self::has_front_matter( $body . "\n" ) ) {
-			return $body . "\n";
-		}
-		return self::front_matter( $fields ) . "\n\n" . $body . "\n";
-	}
-
-	/**
-	 * Body of a single post or page: one H1, optional image, content.
-	 *
-	 * @param string      $title         Title.
-	 * @param string      $content_md    Content as Markdown (H1s already demoted).
-	 * @param string|null $image_url     Featured image URL.
-	 * @param string      $image_alt     Featured image alt text.
-	 * @return string
-	 */
-	public static function single_body( $title, $content_md, $image_url = null, $image_alt = '' ) {
-		$parts = array( '# ' . self::heading_text( $title ) );
-		if ( $image_url ) {
-			$alt     = str_replace( array( '[', ']' ), array( '\\[', '\\]' ), self::one_line( $image_alt ) );
-			$parts[] = '![' . $alt . '](' . Relve_AR_Converter::url_for_markdown( $image_url ) . ')';
-		}
-		if ( '' !== trim( (string) $content_md ) ) {
-			$parts[] = trim( $content_md );
-		}
-		return implode( "\n\n", $parts );
-	}
-
-	/**
-	 * Body of a list page: H1, optional intro, a list of posts.
-	 *
-	 * @param string  $title Heading.
-	 * @param string  $intro Intro text (plain).
-	 * @param array[] $items Each { title, url, date (Y-m-d), excerpt }.
-	 * @return string
-	 */
-	public static function list_body( $title, $intro, $items ) {
-		$parts = array( '# ' . self::heading_text( $title ) );
-		$intro = self::one_line( (string) $intro );
-		if ( '' !== $intro ) {
-			$parts[] = $intro;
-		}
-		$lines = array();
-		foreach ( $items as $item ) {
-			$t = self::link_text( $item['title'] );
-			if ( '' === $t ) {
-				continue;
-			}
-			$line = '- [' . $t . '](' . Relve_AR_Converter::url_for_markdown( $item['url'] ) . ')';
-			if ( ! empty( $item['date'] ) ) {
-				$line .= ' (' . $item['date'] . ')';
-			}
-			$excerpt = self::one_line( isset( $item['excerpt'] ) ? (string) $item['excerpt'] : '' );
-			if ( '' !== $excerpt ) {
-				$line .= ': ' . $excerpt;
-			}
-			$lines[] = $line;
-		}
-		$parts[] = $lines ? implode( "\n", $lines ) : '_No posts yet._';
-		return implode( "\n\n", $parts );
-	}
-
-	/**
-	 * Shorten plain text to $max characters on a word boundary.
-	 *
-	 * @param string $text Text.
-	 * @param int    $max  Max characters.
-	 * @return string
-	 */
-	public static function shorten( $text, $max = 300 ) {
-		$text = self::one_line( (string) $text );
-		if ( self::strlen( $text ) <= $max ) {
-			return $text;
-		}
-		$cut   = self::substr( $text, 0, $max - 3 );
-		$space = strrpos( $cut, ' ' );
-		if ( false !== $space && $space > strlen( $cut ) / 2 ) {
-			$cut = substr( $cut, 0, $space );
-		}
-		return rtrim( $cut, " ,.;:" ) . '...';
-	}
-
-	/**
-	 * Collapse whitespace.
-	 *
-	 * @param string $s Text.
-	 * @return string
-	 */
-	public static function one_line( $s ) {
-		$r = preg_replace( '/\s+/u', ' ', str_replace( "\xC2\xA0", ' ', (string) $s ) );
-		return trim( null === $r ? (string) $s : $r );
-	}
-
-	/**
-	 * Text safe inside [link text].
-	 *
-	 * @param string $s Text.
-	 * @return string
-	 */
-	public static function link_text( $s ) {
-		return str_replace( array( '[', ']' ), '', self::one_line( $s ) );
-	}
-
-	/**
-	 * Heading text on one line.
-	 *
-	 * @param string $s Text.
-	 * @return string
-	 */
-	private static function heading_text( $s ) {
-		$t = self::one_line( $s );
-		return '' === $t ? 'Untitled' : $t;
-	}
-
-	/**
-	 * JSON string as the package's JSON.stringify writes it.
-	 *
-	 * @param string $s String.
-	 * @return string
-	 */
-	private static function json( $s ) {
-		$j = json_encode( $s, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );
-		return false === $j ? '""' : $j;
-	}
-
-	/**
-	 * Character length (mbstring when available).
-	 *
-	 * @param string $s Text.
-	 * @return int
-	 */
-	private static function strlen( $s ) {
-		return function_exists( 'mb_strlen' ) ? mb_strlen( $s, 'UTF-8' ) : strlen( $s );
-	}
-
-	/**
-	 * Character substring (mbstring when available).
-	 *
-	 * @param string $s     Text.
-	 * @param int    $start Start.
-	 * @param int    $len   Length.
-	 * @return string
-	 */
-	private static function substr( $s, $start, $len ) {
-		return function_exists( 'mb_substr' ) ? mb_substr( $s, $start, $len, 'UTF-8' ) : substr( $s, $start, $len );
-	}
-
-	// ── WordPress-bound builders ──────────────────────────────────────────
-
-	/**
-	 * Markdown for a post or page.
-	 *
-	 * @param WP_Post $post      The post (published, public, no password).
-	 * @param string  $canonical Canonical permalink.
-	 * @return string
-	 */
-	public static function for_post( $post, $canonical ) {
-		$title   = html_entity_decode( wp_strip_all_tags( get_the_title( $post ) ), ENT_QUOTES, 'UTF-8' );
-		$html    = self::render_content( $post );
-		$content = Relve_AR_Converter::convert( $html, $canonical, array( 'demote_h1' => true ) );
-
-		$image_url = null;
-		$image_alt = '';
-		$thumb_id  = get_post_thumbnail_id( $post );
-		if ( $thumb_id ) {
-			$image_url = wp_get_attachment_image_url( $thumb_id, 'full' );
-			$image_alt = (string) get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );
-			if ( '' === $image_alt ) {
-				$image_alt = $title;
-			}
-		}
-
-		$categories = array();
-		$tags       = array();
-		if ( is_object_in_taxonomy( $post->post_type, 'category' ) ) {
-			foreach ( (array) get_the_category( $post->ID ) as $term ) {
-				$categories[] = html_entity_decode( $term->name, ENT_QUOTES, 'UTF-8' );
-			}
-		}
-		if ( is_object_in_taxonomy( $post->post_type, 'post_tag' ) ) {
-			$post_tags = get_the_tags( $post->ID );
-			if ( is_array( $post_tags ) ) {
-				foreach ( $post_tags as $term ) {
-					$tags[] = html_entity_decode( $term->name, ENT_QUOTES, 'UTF-8' );
-				}
-			}
-		}
-
-		$fields = array(
-			'title'       => $title,
-			'canonical'   => $canonical,
-			'author'      => html_entity_decode( (string) get_the_author_meta( 'display_name', $post->post_author ), ENT_QUOTES, 'UTF-8' ),
-			'published'   => get_post_time( 'Y-m-d\TH:i:s\Z', true, $post ),
-			'modified'    => get_post_modified_time( 'Y-m-d\TH:i:s\Z', true, $post ),
-			'categories'  => $categories,
-			'tags'        => $tags,
-			'description' => self::description_for( $post ),
-			'source'      => $canonical,
-			'generator'   => 'agent-ready/native',
-			'lang'        => get_bloginfo( 'language' ),
-		);
-		$fields = apply_filters( 'relve_agent_ready_front_matter', $fields, $post );
-		$body   = self::single_body( $title, $content, $image_url ? $image_url : null, $image_alt );
-		return self::assemble( $fields, apply_filters( 'relve_agent_ready_markdown_body', $body, $post ) );
-	}
-
-	/**
-	 * The post's content rendered the way the theme would (blocks, shortcodes,
-	 * embeds), with the post set up as the global post.
-	 *
-	 * @param WP_Post $post Post.
-	 * @return string HTML.
-	 */
-	public static function render_content( $post ) {
-		$previous_post   = isset( $GLOBALS['post'] ) ? $GLOBALS['post'] : null;
-		$GLOBALS['post'] = $post; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
-		setup_postdata( $post );
-		$html = apply_filters( 'the_content', $post->post_content ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- core hook.
-		$html = str_replace( ']]>', ']]&gt;', (string) $html );
-		$GLOBALS['post'] = $previous_post; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
-		if ( $previous_post instanceof WP_Post ) {
-			setup_postdata( $previous_post );
-		}
-		return $html;
-	}
-
-	/**
-	 * Front matter for a stored (refined) file that has none of its own.
-	 *
-	 * @param string       $markdown  Stored Markdown.
-	 * @param string       $canonical Canonical URL.
-	 * @param WP_Post|null $post      The post the path resolved to, if any.
-	 * @param string       $title     Title for non-post targets.
-	 * @return string
-	 */
-	public static function for_stored( $markdown, $canonical, $post = null, $title = '' ) {
-		if ( $post ) {
-			$title = html_entity_decode( wp_strip_all_tags( get_the_title( $post ) ), ENT_QUOTES, 'UTF-8' );
-		}
-		return self::assemble(
-			array(
-				'title'     => $title,
-				'canonical' => $canonical,
-				'source'    => $canonical,
-				'generator' => 'agent-ready/stored',
-				'lang'      => get_bloginfo( 'language' ),
-			),
-			$markdown
-		);
-	}
-
-	/**
-	 * Description: Yoast meta description, else the excerpt, else the first
-	 * words of the content.
-	 *
-	 * @param WP_Post $post Post.
-	 * @return string
-	 */
-	public static function description_for( $post ) {
-		$desc = (string) get_post_meta( $post->ID, '_yoast_wpseo_metadesc', true );
-		if ( '' !== $desc && false !== strpos( $desc, '%%' ) ) {
-			$desc = function_exists( 'wpseo_replace_vars' ) ? (string) wpseo_replace_vars( $desc, $post ) : '';
-		}
-		if ( '' === trim( $desc ) && '' !== trim( (string) $post->post_excerpt ) ) {
-			$desc = $post->post_excerpt;
-		}
-		if ( '' === trim( $desc ) ) {
-			$desc = wp_trim_words( wp_strip_all_tags( strip_shortcodes( $post->post_content ) ), 40, '...' );
-		}
-		return self::shorten( html_entity_decode( wp_strip_all_tags( $desc ), ENT_QUOTES, 'UTF-8' ), 300 );
-	}
-
-	/**
-	 * Markdown for the posts front page / posts page or a category, tag or
-	 * author archive: an H1 and its first 50 posts.
-	 *
-	 * @param string $kind      home|category|post_tag|author.
-	 * @param int    $object_id Term or user ID (0 for home).
-	 * @param string $canonical Canonical URL.
-	 * @return string
-	 */
-	public static function for_archive( $kind, $object_id, $canonical ) {
-		$args = array(
-			'post_type'           => 'post',
-			'post_status'         => 'publish',
-			'posts_per_page'      => self::ARCHIVE_LIMIT,
-			'ignore_sticky_posts' => true,
-			'has_password'        => false,
-			'no_found_rows'       => true,
-		);
-		$intro = '';
-		if ( 'category' === $kind ) {
-			$term          = get_term( $object_id, 'category' );
-			$title         = $term && ! is_wp_error( $term ) ? $term->name : '';
-			$intro         = $term && ! is_wp_error( $term ) ? $term->description : '';
-			$args['cat']   = (int) $object_id;
-			$title         = sprintf( 'Category: %s', $title );
-		} elseif ( 'post_tag' === $kind ) {
-			$term           = get_term( $object_id, 'post_tag' );
-			$intro          = $term && ! is_wp_error( $term ) ? $term->description : '';
-			$args['tag_id'] = (int) $object_id;
-			$title          = sprintf( 'Tag: %s', $term && ! is_wp_error( $term ) ? $term->name : '' );
-		} elseif ( 'author' === $kind ) {
-			$args['author'] = (int) $object_id;
-			$title          = sprintf( 'Posts by %s', get_the_author_meta( 'display_name', $object_id ) );
-			$intro          = (string) get_the_author_meta( 'description', $object_id );
-		} else {
-			$title = get_bloginfo( 'name' );
-			$intro = get_bloginfo( 'description' );
-			$page  = (int) get_option( 'page_for_posts' );
-			if ( 'page' === get_option( 'show_on_front' ) && $page ) {
-				$title = get_the_title( $page );
-			}
-		}
-		$title = html_entity_decode( wp_strip_all_tags( (string) $title ), ENT_QUOTES, 'UTF-8' );
-		$intro = html_entity_decode( wp_strip_all_tags( (string) $intro ), ENT_QUOTES, 'UTF-8' );
-
-		$query = new WP_Query( apply_filters( 'relve_agent_ready_archive_query_args', $args, $kind, $object_id ) );
-		$items = array();
-		foreach ( $query->posts as $p ) {
-			$items[] = array(
-				'title'   => html_entity_decode( wp_strip_all_tags( get_the_title( $p ) ), ENT_QUOTES, 'UTF-8' ),
-				'url'     => get_permalink( $p ),
-				'date'    => get_post_time( 'Y-m-d', true, $p ),
-				'excerpt' => self::description_for( $p ),
-			);
-		}
-
-		$fields = array(
-			'title'       => $title,
-			'canonical'   => $canonical,
-			'description' => self::shorten( $intro, 300 ),
-			'source'      => $canonical,
-			'generator'   => 'agent-ready/native',
-			'lang'        => get_bloginfo( 'language' ),
-		);
-		return self::assemble( $fields, self::list_body( $title, $intro, $items ) );
-	}
-}
+<?php
+/**
+ * Markdown builder: a post, page, the posts front page or an archive as one
+ * Markdown document, from WordPress's own data (not scraped HTML).
+ *
+ *   ---
+ *   title: "..."
+ *   canonical: https://site/post/
+ *   author: "..."
+ *   published: 2026-10-01T09:00:00Z
+ *   modified: 2026-10-02T10:00:00Z
+ *   categories: ["News"]
+ *   tags: ["AI"]
+ *   description: "..."
+ *   source: https://site/post/
+ *   generator: agent-ready/native
+ *   lang: en-US
+ *   ---
+ *
+ *   # Title
+ *
+ *   ![featured image](...)
+ *
+ *   Content...
+ *
+ * The front-matter rules are the package's (core/enrich.ts): empty values
+ * dropped, URLs / ISO dates / language tags plain, everything else
+ * JSON-quoted. A document that already has front matter (a refined file
+ * usually does not, but a hand-made one may) is left exactly as it is.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Builds Markdown documents.
+ */
+class Relve_AR_Markdown_Builder {
+
+	/** Posts listed on the front page / an archive. */
+	const ARCHIVE_LIMIT = 50;
+
+	// ── pure helpers (unit-tested) ────────────────────────────────────────
+
+	/**
+	 * A YAML front-matter block. Empty values (null, "", empty list) are dropped.
+	 *
+	 * @param array $fields Ordered key => string|int|string[].
+	 * @return string
+	 */
+	public static function front_matter( $fields ) {
+		$lines = array( '---' );
+		foreach ( $fields as $key => $value ) {
+			if ( null === $value || '' === $value || array() === $value ) {
+				continue;
+			}
+			if ( is_array( $value ) ) {
+				$items = array();
+				foreach ( $value as $item ) {
+					$item = self::one_line( (string) $item );
+					if ( '' !== $item ) {
+						$items[] = self::json( $item );
+					}
+				}
+				if ( ! $items ) {
+					continue;
+				}
+				$lines[] = $key . ': [' . implode( ', ', $items ) . ']';
+				continue;
+			}
+			$lines[] = $key . ': ' . self::yaml_scalar( $value );
+		}
+		$lines[] = '---';
+		return implode( "\n", $lines );
+	}
+
+	/**
+	 * Plain scalars for URLs, ISO dates, language tags and the generator;
+	 * JSON-quoted (valid YAML) for everything else. Same rule as the package.
+	 *
+	 * @param string|int $value Value.
+	 * @return string
+	 */
+	public static function yaml_scalar( $value ) {
+		if ( is_int( $value ) || is_float( $value ) ) {
+			return (string) $value;
+		}
+		$one = self::one_line( (string) $value );
+		if ( preg_match( '#^(https?://[^\s\#]+|\d{4}-\d{2}-\d{2}T[\d:.]+Z|[a-z]{2,3}(-[A-Za-z]{2,4})?|agent-ready/[a-z]+)$#', $one ) ) {
+			return $one;
+		}
+		return self::json( $one );
+	}
+
+	/**
+	 * Does the Markdown start with a front-matter block?
+	 *
+	 * @param string $markdown Markdown.
+	 * @return bool
+	 */
+	public static function has_front_matter( $markdown ) {
+		return (bool) preg_match( '/^---\r?\n[\s\S]*?\r?\n---\r?\n/', (string) $markdown );
+	}
+
+	/**
+	 * Final document: front matter, then the body. A body that already has
+	 * front matter is returned as it is (plus a final newline).
+	 *
+	 * @param array  $fields Front-matter fields.
+	 * @param string $body   Markdown body (starting with its H1).
+	 * @return string
+	 */
+	public static function assemble( $fields, $body ) {
+		$body = trim( (string) $body );
+		if ( self::has_front_matter( $body . "\n" ) ) {
+			return $body . "\n";
+		}
+		return self::front_matter( $fields ) . "\n\n" . $body . "\n";
+	}
+
+	/**
+	 * Body of a single post or page: one H1, optional image, content.
+	 *
+	 * @param string      $title         Title.
+	 * @param string      $content_md    Content as Markdown (H1s already demoted).
+	 * @param string|null $image_url     Featured image URL.
+	 * @param string      $image_alt     Featured image alt text.
+	 * @return string
+	 */
+	public static function single_body( $title, $content_md, $image_url = null, $image_alt = '' ) {
+		$parts = array( '# ' . self::heading_text( $title ) );
+		if ( $image_url ) {
+			$alt     = str_replace( array( '[', ']' ), array( '\\[', '\\]' ), self::one_line( $image_alt ) );
+			$parts[] = '![' . $alt . '](' . Relve_AR_Converter::url_for_markdown( $image_url ) . ')';
+		}
+		if ( '' !== trim( (string) $content_md ) ) {
+			$parts[] = trim( $content_md );
+		}
+		return implode( "\n\n", $parts );
+	}
+
+	/**
+	 * Body of a list page: H1, optional intro, a list of posts.
+	 *
+	 * @param string  $title Heading.
+	 * @param string  $intro Intro text (plain).
+	 * @param array[] $items Each { title, url, date (Y-m-d), excerpt }.
+	 * @return string
+	 */
+	public static function list_body( $title, $intro, $items ) {
+		$parts = array( '# ' . self::heading_text( $title ) );
+		$intro = self::one_line( (string) $intro );
+		if ( '' !== $intro ) {
+			$parts[] = $intro;
+		}
+		$lines = array();
+		foreach ( $items as $item ) {
+			$t = self::link_text( $item['title'] );
+			if ( '' === $t ) {
+				continue;
+			}
+			$line = '- [' . $t . '](' . Relve_AR_Converter::url_for_markdown( $item['url'] ) . ')';
+			if ( ! empty( $item['date'] ) ) {
+				$line .= ' (' . $item['date'] . ')';
+			}
+			$excerpt = self::one_line( isset( $item['excerpt'] ) ? (string) $item['excerpt'] : '' );
+			if ( '' !== $excerpt ) {
+				$line .= ': ' . $excerpt;
+			}
+			$lines[] = $line;
+		}
+		$parts[] = $lines ? implode( "\n", $lines ) : '_No posts yet._';
+		return implode( "\n\n", $parts );
+	}
+
+	/**
+	 * Shorten plain text to $max characters on a word boundary.
+	 *
+	 * @param string $text Text.
+	 * @param int    $max  Max characters.
+	 * @return string
+	 */
+	public static function shorten( $text, $max = 300 ) {
+		$text = self::one_line( (string) $text );
+		if ( self::strlen( $text ) <= $max ) {
+			return $text;
+		}
+		$cut   = self::substr( $text, 0, $max - 3 );
+		$space = strrpos( $cut, ' ' );
+		if ( false !== $space && $space > strlen( $cut ) / 2 ) {
+			$cut = substr( $cut, 0, $space );
+		}
+		return rtrim( $cut, " ,.;:" ) . '...';
+	}
+
+	/**
+	 * Collapse whitespace.
+	 *
+	 * @param string $s Text.
+	 * @return string
+	 */
+	public static function one_line( $s ) {
+		$r = preg_replace( '/\s+/u', ' ', str_replace( "\xC2\xA0", ' ', (string) $s ) );
+		return trim( null === $r ? (string) $s : $r );
+	}
+
+	/**
+	 * Text safe inside [link text].
+	 *
+	 * @param string $s Text.
+	 * @return string
+	 */
+	public static function link_text( $s ) {
+		return str_replace( array( '[', ']' ), '', self::one_line( $s ) );
+	}
+
+	/**
+	 * Heading text on one line.
+	 *
+	 * @param string $s Text.
+	 * @return string
+	 */
+	private static function heading_text( $s ) {
+		$t = self::one_line( $s );
+		return '' === $t ? 'Untitled' : $t;
+	}
+
+	/**
+	 * JSON string as the package's JSON.stringify writes it.
+	 *
+	 * @param string $s String.
+	 * @return string
+	 */
+	private static function json( $s ) {
+		$j = json_encode( $s, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );
+		return false === $j ? '""' : $j;
+	}
+
+	/**
+	 * Character length (mbstring when available).
+	 *
+	 * @param string $s Text.
+	 * @return int
+	 */
+	private static function strlen( $s ) {
+		return function_exists( 'mb_strlen' ) ? mb_strlen( $s, 'UTF-8' ) : strlen( $s );
+	}
+
+	/**
+	 * Character substring (mbstring when available).
+	 *
+	 * @param string $s     Text.
+	 * @param int    $start Start.
+	 * @param int    $len   Length.
+	 * @return string
+	 */
+	private static function substr( $s, $start, $len ) {
+		return function_exists( 'mb_substr' ) ? mb_substr( $s, $start, $len, 'UTF-8' ) : substr( $s, $start, $len );
+	}
+
+	// ── WordPress-bound builders ──────────────────────────────────────────
+
+	/**
+	 * Markdown for a post or page.
+	 *
+	 * @param WP_Post $post      The post (published, public, no password).
+	 * @param string  $canonical Canonical permalink.
+	 * @return string
+	 */
+	public static function for_post( $post, $canonical ) {
+		$title   = html_entity_decode( wp_strip_all_tags( get_the_title( $post ) ), ENT_QUOTES, 'UTF-8' );
+		$html    = self::render_content( $post );
+		$content = Relve_AR_Converter::convert( $html, $canonical, array( 'demote_h1' => true ) );
+
+		$image_url = null;
+		$image_alt = '';
+		$thumb_id  = get_post_thumbnail_id( $post );
+		if ( $thumb_id ) {
+			$image_url = wp_get_attachment_image_url( $thumb_id, 'full' );
+			$image_alt = (string) get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );
+			if ( '' === $image_alt ) {
+				$image_alt = $title;
+			}
+		}
+
+		$categories = array();
+		$tags       = array();
+		if ( is_object_in_taxonomy( $post->post_type, 'category' ) ) {
+			foreach ( (array) get_the_category( $post->ID ) as $term ) {
+				$categories[] = html_entity_decode( $term->name, ENT_QUOTES, 'UTF-8' );
+			}
+		}
+		if ( is_object_in_taxonomy( $post->post_type, 'post_tag' ) ) {
+			$post_tags = get_the_tags( $post->ID );
+			if ( is_array( $post_tags ) ) {
+				foreach ( $post_tags as $term ) {
+					$tags[] = html_entity_decode( $term->name, ENT_QUOTES, 'UTF-8' );
+				}
+			}
+		}
+
+		$fields = array(
+			'title'       => $title,
+			'canonical'   => $canonical,
+			'author'      => html_entity_decode( (string) get_the_author_meta( 'display_name', $post->post_author ), ENT_QUOTES, 'UTF-8' ),
+			'published'   => get_post_time( 'Y-m-d\TH:i:s\Z', true, $post ),
+			'modified'    => get_post_modified_time( 'Y-m-d\TH:i:s\Z', true, $post ),
+			'categories'  => $categories,
+			'tags'        => $tags,
+			'description' => self::description_for( $post ),
+			'source'      => $canonical,
+			'generator'   => 'agent-ready/native',
+			'lang'        => get_bloginfo( 'language' ),
+		);
+		$fields = apply_filters( 'relve_agent_ready_front_matter', $fields, $post );
+		$body   = self::single_body( $title, $content, $image_url ? $image_url : null, $image_alt );
+		return self::assemble( $fields, apply_filters( 'relve_agent_ready_markdown_body', $body, $post ) );
+	}
+
+	/**
+	 * The post's content rendered the way the theme would (blocks, shortcodes,
+	 * embeds), with the post set up as the global post.
+	 *
+	 * @param WP_Post $post Post.
+	 * @return string HTML.
+	 */
+	public static function render_content( $post ) {
+		$previous_post   = isset( $GLOBALS['post'] ) ? $GLOBALS['post'] : null;
+		$GLOBALS['post'] = $post; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
+		setup_postdata( $post );
+		$html = apply_filters( 'the_content', $post->post_content ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- core hook.
+		$html = str_replace( ']]>', ']]&gt;', (string) $html );
+		$GLOBALS['post'] = $previous_post; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
+		if ( $previous_post instanceof WP_Post ) {
+			setup_postdata( $previous_post );
+		}
+		return $html;
+	}
+
+	/**
+	 * Front matter for a stored (refined) file that has none of its own.
+	 *
+	 * @param string       $markdown  Stored Markdown.
+	 * @param string       $canonical Canonical URL.
+	 * @param WP_Post|null $post      The post the path resolved to, if any.
+	 * @param string       $title     Title for non-post targets.
+	 * @return string
+	 */
+	public static function for_stored( $markdown, $canonical, $post = null, $title = '' ) {
+		if ( $post ) {
+			$title = html_entity_decode( wp_strip_all_tags( get_the_title( $post ) ), ENT_QUOTES, 'UTF-8' );
+		}
+		return self::assemble(
+			array(
+				'title'     => $title,
+				'canonical' => $canonical,
+				'source'    => $canonical,
+				'generator' => 'agent-ready/stored',
+				'lang'      => get_bloginfo( 'language' ),
+			),
+			$markdown
+		);
+	}
+
+	/**
+	 * Description: Yoast meta description, else the excerpt, else the first
+	 * words of the content.
+	 *
+	 * @param WP_Post $post Post.
+	 * @return string
+	 */
+	public static function description_for( $post ) {
+		$desc = (string) get_post_meta( $post->ID, '_yoast_wpseo_metadesc', true );
+		if ( '' !== $desc && false !== strpos( $desc, '%%' ) ) {
+			$desc = function_exists( 'wpseo_replace_vars' ) ? (string) wpseo_replace_vars( $desc, $post ) : '';
+		}
+		if ( '' === trim( $desc ) && '' !== trim( (string) $post->post_excerpt ) ) {
+			$desc = $post->post_excerpt;
+		}
+		if ( '' === trim( $desc ) ) {
+			$desc = wp_trim_words( wp_strip_all_tags( strip_shortcodes( $post->post_content ) ), 40, '...' );
+		}
+		return self::shorten( html_entity_decode( wp_strip_all_tags( $desc ), ENT_QUOTES, 'UTF-8' ), 300 );
+	}
+
+	/**
+	 * Markdown for the posts front page / posts page or a category, tag or
+	 * author archive: an H1 and its first 50 posts.
+	 *
+	 * @param string $kind      home|category|post_tag|author.
+	 * @param int    $object_id Term or user ID (0 for home).
+	 * @param string $canonical Canonical URL.
+	 * @return string
+	 */
+	public static function for_archive( $kind, $object_id, $canonical ) {
+		$args = array(
+			'post_type'           => 'post',
+			'post_status'         => 'publish',
+			'posts_per_page'      => self::ARCHIVE_LIMIT,
+			'ignore_sticky_posts' => true,
+			'has_password'        => false,
+			'no_found_rows'       => true,
+		);
+		$intro = '';
+		if ( 'category' === $kind ) {
+			$term          = get_term( $object_id, 'category' );
+			$title         = $term && ! is_wp_error( $term ) ? $term->name : '';
+			$intro         = $term && ! is_wp_error( $term ) ? $term->description : '';
+			$args['cat']   = (int) $object_id;
+			$title         = sprintf( 'Category: %s', $title );
+		} elseif ( 'post_tag' === $kind ) {
+			$term           = get_term( $object_id, 'post_tag' );
+			$intro          = $term && ! is_wp_error( $term ) ? $term->description : '';
+			$args['tag_id'] = (int) $object_id;
+			$title          = sprintf( 'Tag: %s', $term && ! is_wp_error( $term ) ? $term->name : '' );
+		} elseif ( 'author' === $kind ) {
+			$args['author'] = (int) $object_id;
+			$title          = sprintf( 'Posts by %s', get_the_author_meta( 'display_name', $object_id ) );
+			$intro          = (string) get_the_author_meta( 'description', $object_id );
+		} else {
+			$title = get_bloginfo( 'name' );
+			$intro = get_bloginfo( 'description' );
+			$page  = (int) get_option( 'page_for_posts' );
+			if ( 'page' === get_option( 'show_on_front' ) && $page ) {
+				$title = get_the_title( $page );
+			}
+		}
+		$title = html_entity_decode( wp_strip_all_tags( (string) $title ), ENT_QUOTES, 'UTF-8' );
+		$intro = html_entity_decode( wp_strip_all_tags( (string) $intro ), ENT_QUOTES, 'UTF-8' );
+
+		$query = new WP_Query( apply_filters( 'relve_agent_ready_archive_query_args', $args, $kind, $object_id ) );
+		$items = array();
+		foreach ( $query->posts as $p ) {
+			$items[] = array(
+				'title'   => html_entity_decode( wp_strip_all_tags( get_the_title( $p ) ), ENT_QUOTES, 'UTF-8' ),
+				'url'     => get_permalink( $p ),
+				'date'    => get_post_time( 'Y-m-d', true, $p ),
+				'excerpt' => self::description_for( $p ),
+			);
+		}
+
+		$fields = array(
+			'title'       => $title,
+			'canonical'   => $canonical,
+			'description' => self::shorten( $intro, 300 ),
+			'source'      => $canonical,
+			'generator'   => 'agent-ready/native',
+			'lang'        => get_bloginfo( 'language' ),
+		);
+		return self::assemble( $fields, self::list_body( $title, $intro, $items ) );
+	}
+}