Long-form teaser-thread strategy + atmosphere_long_form_composition filter

.github/changelog/add-long-form-composition-setting

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Choose how long-form posts publish to Bluesky from the ATmosphere settings page — link card (default), a single post combining body text with the permalink, or a two-post teaser thread.

.github/changelog/long-form-teaser-thread

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Long-form posts can now be published to Bluesky as a short thread that points readers back to the full article. Sites can keep the existing single-post behavior, publish a shortened text version with a link, or use a two-post teaser thread. When a threaded post is edited, ATmosphere updates the existing Bluesky posts when possible so links and replies stay connected. If the publishing format changes, ATmosphere replaces the old Bluesky posts with new ones.

includes/class-api.php

@@ -167,6 +167,45 @@ public static function upload_blob( string $file_path, string $mime_type ): arra
 	 * @return array|\WP_Error
 	 */
 	public static function apply_writes( array $writes ): array|\WP_Error {
+		/**
+		 * Short-circuits the applyWrites call before it reaches the PDS.
+		 *
+		 * Return a non-null array (success shape: `[ 'results' => [...] ]`,
+		 * with one array result per write) or a `WP_Error` to bypass the
+		 * real HTTP round-trip. Used by
+		 * the PHPUnit suite, the FOSSE end-to-end harness, and anything
+		 * else that needs to observe or mock a write batch without
+		 * actually hitting the PDS.
+		 *
+		 * A common use is `pre_http_request`, but that filter fires
+		 * inside `wp_remote_request`, which is only reached after the
+		 * DPoP proof has been built — so in test environments without
+		 * a real DPoP JWK, the call errors out first. This filter runs
+		 * before any of that.
+		 *
+		 * @param null|array|\WP_Error $short_circuit Short-circuit value. Return null to skip.
+		 * @param array                $writes        The write batch about to be sent.
+		 */
+		$short_circuit = \apply_filters( 'atmosphere_pre_apply_writes', null, $writes );
+
+		if ( \is_wp_error( $short_circuit ) ) {
+			return $short_circuit;
+		}
+
+		if ( \is_array( $short_circuit ) ) {
+			return self::validate_apply_writes_response( $short_circuit, $writes );
+		}
+
+		if ( null !== $short_circuit ) {
+			// Malformed filter return (scalar / object / etc). Surface as a
+			// WP_Error instead of letting PHP fatal on the `array|\WP_Error`
+			// return type.
+			return new \WP_Error(
+				'atmosphere_invalid_pre_apply_writes_return',
+				\__( 'atmosphere_pre_apply_writes must return null, an array, or a WP_Error.', 'atmosphere' )
+			);
+		}
+
 		return self::post(
 			'/xrpc/com.atproto.repo.applyWrites',
 			array(
@@ -176,6 +215,56 @@ public static function apply_writes( array $writes ): array|\WP_Error {
 		);
 	}
 
+	/**
+	 * Validate a short-circuited applyWrites success response.
+	 *
+	 * @param array $response Short-circuited applyWrites response.
+	 * @param array $writes   Write batch the response represents.
+	 * @return array|\WP_Error
+	 */
+	private static function validate_apply_writes_response( array $response, array $writes ): array|\WP_Error {
+		if ( ! isset( $response['results'] )
+			|| ! \is_array( $response['results'] )
+			|| ! \array_is_list( $response['results'] )
+			|| \count( $response['results'] ) !== \count( $writes )
+		) {
+			return self::invalid_apply_writes_response();
+		}
+
+		foreach ( $response['results'] as $i => $result ) {
+			if ( ! \is_array( $result ) ) {
+				return self::invalid_apply_writes_response();
+			}
+
+			$type = $writes[ $i ]['$type'] ?? '';
+			if ( \in_array(
+				$type,
+				array(
+					'com.atproto.repo.applyWrites#create',
+					'com.atproto.repo.applyWrites#update',
+				),
+				true
+			) && ( empty( $result['uri'] ) || empty( $result['cid'] ) )
+			) {
+				return self::invalid_apply_writes_response();
+			}
+		}
+
+		return $response;
+	}
+
+	/**
+	 * Build a consistent malformed applyWrites response error.
+	 *
+	 * @return \WP_Error
+	 */
+	private static function invalid_apply_writes_response(): \WP_Error {
+		return new \WP_Error(
+			'atmosphere_invalid_pre_apply_writes_response',
+			\__( 'atmosphere_pre_apply_writes success responses must include one results array entry for each write.', 'atmosphere' )
+		);
+	}
+
 	/**
 	 * Get a single record from the PDS.
 	 *

includes/class-atmosphere.php

@@ -21,6 +21,12 @@
  */
 class Atmosphere {
 
+	/**
+	 * Allowed values for the long-form composition strategy filter and
+	 * the matching `atmosphere_long_form_composition` option.
+	 */
+	public const LONG_FORM_STRATEGIES = array( 'link-card', 'truncate-link', 'teaser-thread' );
+
 	/**
 	 * Wire up all hooks.
 	 */
@@ -34,6 +40,13 @@ public function init(): void {
 		\add_action( 'init', array( Admin::class, 'register' ), 5 );
 		\add_action( 'init', array( Backfill::class, 'register' ), 5 );
 
+		/*
+		 * Seed the long-form composition strategy from the user's
+		 * setting. Priority 1 so any downstream filter at the default
+		 * priority can still override it per post.
+		 */
+		\add_filter( 'atmosphere_long_form_composition', array( self::class, 'seed_long_form_composition' ), 1 );
+
 		// REST route (always active for client-metadata).
 		\add_action( 'rest_api_init', array( Admin::class, 'register_rest_routes' ) );
 
@@ -306,8 +319,11 @@ public function on_status_change( string $new_status, string $old_status, \WP_Po
 	/**
 	 * Schedule AT Protocol record deletion before a post is permanently deleted.
 	 *
-	 * Captures TIDs from post meta before they're lost, then schedules
-	 * an async delete via cron.
+	 * Captures every Bluesky TID (including thread replies) and the
+	 * document TID from post meta before they're lost, then schedules
+	 * an async delete via cron. Thread-strategy posts: reads
+	 * `Post::META_THREAD_RECORDS` and batches every bsky tid into the
+	 * cron event so a single delete covers root + replies.
 	 *
 	 * @param int $post_id Post ID being deleted.
 	 */
@@ -330,11 +346,28 @@ public function on_before_delete( int $post_id ): void {
 		 * Gating this on current support would orphan already-published
 		 * records whenever a site narrows its configuration.
 		 */
-		$bsky_tid = \get_post_meta( $post_id, Transformer\Post::META_TID, true );
-		$doc_tid  = \get_post_meta( $post_id, Transformer\Document::META_TID, true );
+		$bsky_tids = array();
 
-		if ( $bsky_tid || $doc_tid ) {
-			\wp_schedule_single_event( \time(), 'atmosphere_delete_records', array( $bsky_tid, $doc_tid ) );
+		$thread_records = \get_post_meta( $post_id, Transformer\Post::META_THREAD_RECORDS, true );
+		if ( \is_array( $thread_records ) && ! empty( $thread_records ) ) {
+			foreach ( $thread_records as $record ) {
+				if ( ! empty( $record['tid'] ) ) {
+					$bsky_tids[] = (string) $record['tid'];
+				}
+			}
+		}
+
+		if ( empty( $bsky_tids ) ) {
+			$legacy_tid = \get_post_meta( $post_id, Transformer\Post::META_TID, true );
+			if ( $legacy_tid ) {
+				$bsky_tids[] = (string) $legacy_tid;
+			}
+		}
+
+		$doc_tid = (string) \get_post_meta( $post_id, Transformer\Document::META_TID, true );
+
+		if ( ! empty( $bsky_tids ) || '' !== $doc_tid ) {
+			\wp_schedule_single_event( \time(), 'atmosphere_delete_records', array( $bsky_tids, $doc_tid ) );
 		}
 	}
 
@@ -362,6 +395,38 @@ public function cron_refresh_token(): void {
 		Client::refresh();
 	}
 
+	/**
+	 * Seed the `atmosphere_long_form_composition` filter from the option.
+	 *
+	 * Returns the configured strategy when valid; otherwise returns the
+	 * incoming `$strategy` (so downstream filters and the `link-card`
+	 * default still apply). An invalid stored value is logged at most
+	 * once per hour so operators can spot config drift.
+	 *
+	 * @param string $strategy Strategy passed in by `apply_filters()`.
+	 * @return string
+	 */
+	public static function seed_long_form_composition( string $strategy ): string {
+		$option = (string) \get_option( 'atmosphere_long_form_composition', 'link-card' );
+
+		if ( \in_array( $option, self::LONG_FORM_STRATEGIES, true ) ) {
+			return $option;
+		}
+
+		if ( ! \get_transient( 'atmosphere_invalid_long_form_composition_logged' ) ) {
+			// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
+			\error_log(
+				\sprintf(
+					'[atmosphere] invalid `atmosphere_long_form_composition` option value %s; falling through to default',
+					\wp_json_encode( $option )
+				)
+			);
+			\set_transient( 'atmosphere_invalid_long_form_composition_logged', 1, \HOUR_IN_SECONDS );
+		}
+
+		return $strategy;
+	}
+
 	/**
 	 * Register async action hooks (called by WP-Cron).
 	 */
@@ -413,8 +478,8 @@ static function (): void {
 
 		\add_action(
 			'atmosphere_delete_records',
-			static function ( string $bsky_tid, string $doc_tid ): void {
-				Publisher::delete_by_tids( $bsky_tid, $doc_tid );
+			static function ( $bsky_tids, string $doc_tid ): void {
+				Publisher::delete_by_tids( $bsky_tids, $doc_tid );
 			},
 			10,
 			2