From 985a15db343b9f059beec588e63747853e42e0cd Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:54:52 -0400
Subject: [PATCH 01/25] refactor: return typed link preview metadata

---
 app/Actions/UpdateLinkPreview.php  | 87 ++++-------------------------
 app/Dto/LinkPreviewMetadata.php    | 35 ++++++++++++
 app/Services/LinkPreviewParser.php | 88 ++++++++++++++++++++++++++++++
 3 files changed, 134 insertions(+), 76 deletions(-)
 create mode 100644 app/Dto/LinkPreviewMetadata.php
 create mode 100644 app/Services/LinkPreviewParser.php

diff --git a/app/Actions/UpdateLinkPreview.php b/app/Actions/UpdateLinkPreview.php
index 941badb57..583f32f85 100644
--- a/app/Actions/UpdateLinkPreview.php
+++ b/app/Actions/UpdateLinkPreview.php
@@ -5,8 +5,9 @@
 namespace App\Actions;
 
 use App\Contracts\Services\DnsResolver;
+use App\Dto\LinkPreviewMetadata;
 use App\Models\LinkPreview;
-use Dom\HTMLDocument;
+use App\Services\LinkPreviewParser;
 use GuzzleHttp\Exception\ResponseException;
 use GuzzleHttp\Psr7\Utils;
 use Illuminate\Http\Client\ConnectionException;
@@ -22,8 +23,6 @@
 
     private const int MAX_BODY_BYTES = 1_048_576;
 
-    private const int MAX_IMAGE_URL_LENGTH = 2048;
-
     /**
      * Non-public ranges that filter_var's private and reserved range flags let through: carrier-grade NAT, IETF protocol
      * assignments, 6to4 relays, benchmarking, documentation and multicast for IPv4; NAT64, discard, Teredo,
@@ -51,14 +50,7 @@
         '::ffff:0:0:0/96',
     ];
 
-    private const array NO_METADATA = [
-        'title' => null,
-        'description' => null,
-        'image_url' => null,
-        'site_name' => null,
-    ];
-
-    public function __construct(private DnsResolver $dns)
+    public function __construct(private DnsResolver $dns, private LinkPreviewParser $parser)
     {
         //
     }
@@ -70,15 +62,15 @@ public function __construct(private DnsResolver $dns)
      */
     public function handle(LinkPreview $linkPreview): void
     {
-        $linkPreview->update([...$this->fetchMetadata($linkPreview->url), 'fetched_at' => now()]);
+        $metadata = $this->fetchMetadata($linkPreview->url);
+
+        $linkPreview->update([...$metadata->toArray(), 'fetched_at' => now()]);
     }
 
     /**
      * Follows up to three redirects by hand, so that every hop goes through the same checks as the original URL.
-     *
-     * @return array{title: string|null, description: string|null, image_url: string|null, site_name: string|null}
      */
-    private function fetchMetadata(string $url): array
+    private function fetchMetadata(string $url): LinkPreviewMetadata
     {
         $page = Url::parse($url);
 
@@ -86,7 +78,7 @@ private function fetchMetadata(string $url): array
             $address = $this->publicAddress($page);
 
             if ($address === null) {
-                return self::NO_METADATA;
+                return new LinkPreviewMetadata;
             }
 
             $response = $this->get($page, $address);
@@ -97,14 +89,14 @@ private function fetchMetadata(string $url): array
 
             if (! $response->redirect()) {
                 return $response->successful() && $this->isHtml($response)
-                    ? $this->parse($this->body($response), $page)
-                    : self::NO_METADATA;
+                    ? $this->parser->parse($this->body($response), $page)
+                    : new LinkPreviewMetadata;
             }
 
             $page = Url::parse($response->header('Location'), $page);
         }
 
-        return self::NO_METADATA;
+        return new LinkPreviewMetadata;
     }
 
     /**
@@ -184,61 +176,4 @@ private function body(Response $response): string
         return Utils::copyToString($body, self::MAX_BODY_BYTES);
     }
 
-    /**
-     * @return array{title: string|null, description: string|null, image_url: string|null, site_name: string|null}
-     */
-    private function parse(string $html, Url $page): array
-    {
-        $document = HTMLDocument::createFromString($html, LIBXML_NOERROR);
-        $meta = [];
-
-        foreach ($document->querySelectorAll('meta[content]') as $element) {
-            $key = mb_strtolower(mb_trim($element->getAttribute('property') ?? $element->getAttribute('name') ?? ''));
-            $meta[$key] ??= (string) $element->getAttribute('content');
-        }
-
-        return [
-            'title' => $this->text([$meta['og:title'] ?? '', $meta['twitter:title'] ?? '', $document->title], 300),
-            'description' => $this->text([$meta['og:description'] ?? '', $meta['twitter:description'] ?? '', $meta['description'] ?? ''], 500),
-            'image_url' => $this->imageUrl([$meta['og:image:secure_url'] ?? '', $meta['og:image'] ?? '', $meta['twitter:image'] ?? ''], $page),
-            'site_name' => $this->text([$meta['og:site_name'] ?? ''], 100),
-        ];
-    }
-
-    /**
-     * Returns the first candidate that still has text once entities are decoded and whitespace is collapsed,
-     * truncated to the column's length.
-     *
-     * @param  list<string>  $candidates
-     */
-    private function text(array $candidates, int $limit): ?string
-    {
-        foreach ($candidates as $candidate) {
-            $text = Str::squish(html_entity_decode($candidate, ENT_QUOTES | ENT_HTML5, 'UTF-8'));
-
-            if ($text !== '') {
-                return mb_strlen($text) > $limit ? mb_rtrim(mb_substr($text, 0, $limit - 1)).'…' : $text;
-            }
-        }
-
-        return null;
-    }
-
-    /**
-     * Returns the first candidate that, resolved against the page URL, is an https URL.
-     *
-     * @param  list<string>  $candidates
-     */
-    private function imageUrl(array $candidates, Url $page): ?string
-    {
-        foreach ($candidates as $candidate) {
-            $image = mb_trim($candidate) === '' ? null : Url::parse($candidate, $page);
-
-            if ($image?->getScheme() === 'https' && mb_strlen($image->toAsciiString()) <= self::MAX_IMAGE_URL_LENGTH) {
-                return $image->toAsciiString();
-            }
-        }
-
-        return null;
-    }
 }
diff --git a/app/Dto/LinkPreviewMetadata.php b/app/Dto/LinkPreviewMetadata.php
new file mode 100644
index 000000000..7e0168326
--- /dev/null
+++ b/app/Dto/LinkPreviewMetadata.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Dto;
+
+use Illuminate\Contracts\Support\Arrayable;
+
+/**
+ * @implements Arrayable<string, string|null>
+ */
+final readonly class LinkPreviewMetadata implements Arrayable
+{
+    public function __construct(
+        public ?string $title = null,
+        public ?string $description = null,
+        public ?string $imageUrl = null,
+        public ?string $siteName = null,
+    ) {
+        //
+    }
+
+    /**
+     * @return array{title: string|null, description: string|null, image_url: string|null, site_name: string|null}
+     */
+    public function toArray(): array
+    {
+        return [
+            'title' => $this->title,
+            'description' => $this->description,
+            'image_url' => $this->imageUrl,
+            'site_name' => $this->siteName,
+        ];
+    }
+}
diff --git a/app/Services/LinkPreviewParser.php b/app/Services/LinkPreviewParser.php
new file mode 100644
index 000000000..79ca52577
--- /dev/null
+++ b/app/Services/LinkPreviewParser.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Dto\LinkPreviewMetadata;
+use Dom\HTMLDocument;
+use Illuminate\Support\Str;
+use Uri\WhatWg\Url;
+
+final readonly class LinkPreviewParser
+{
+    private const int MAX_IMAGE_URL_LENGTH = 2048;
+
+    private const int MAX_TITLE_LENGTH = 300;
+
+    private const int MAX_DESCRIPTION_LENGTH = 500;
+
+    private const int MAX_SITE_NAME_LENGTH = 100;
+
+    public function parse(string $html, Url $page): LinkPreviewMetadata
+    {
+        $document = HTMLDocument::createFromString($html, LIBXML_NOERROR);
+        $meta = [];
+
+        foreach ($document->querySelectorAll('meta[content]') as $element) {
+            $key = mb_strtolower(mb_trim($element->getAttribute('property') ?? $element->getAttribute('name') ?? ''));
+            $meta[$key] ??= (string) $element->getAttribute('content');
+        }
+
+        return new LinkPreviewMetadata(
+            title: $this->text([$meta['og:title'] ?? '', $meta['twitter:title'] ?? '', $document->title], self::MAX_TITLE_LENGTH),
+            description: $this->text([$meta['og:description'] ?? '', $meta['twitter:description'] ?? '', $meta['description'] ?? ''], self::MAX_DESCRIPTION_LENGTH),
+            imageUrl: $this->imageUrl([$meta['og:image:secure_url'] ?? '', $meta['og:image'] ?? '', $meta['twitter:image'] ?? ''], $page),
+            siteName: $this->text([$meta['og:site_name'] ?? ''], self::MAX_SITE_NAME_LENGTH),
+        );
+    }
+
+    /**
+     * Returns the first candidate that still has text once entities are decoded and whitespace is collapsed,
+     * truncated to the column's length.
+     *
+     * @param  list<string>  $candidates
+     */
+    private function text(array $candidates, int $limit): ?string
+    {
+        foreach ($candidates as $candidate) {
+            $text = Str::squish(html_entity_decode($candidate, ENT_QUOTES | ENT_HTML5, 'UTF-8'));
+
+            if ($text === '') {
+                continue;
+            }
+
+            if (mb_strlen($text) <= $limit) {
+                return $text;
+            }
+
+            return mb_rtrim(mb_substr($text, 0, $limit - 1)).'…';
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns the first candidate that, resolved against the page URL, is an https URL.
+     *
+     * @param  list<string>  $candidates
+     */
+    private function imageUrl(array $candidates, Url $page): ?string
+    {
+        foreach ($candidates as $candidate) {
+            $image = mb_trim($candidate) === '' ? null : Url::parse($candidate, $page);
+
+            if ($image?->getScheme() !== 'https') {
+                continue;
+            }
+
+            if (mb_strlen($image->toAsciiString()) > self::MAX_IMAGE_URL_LENGTH) {
+                continue;
+            }
+
+            return $image->toAsciiString();
+        }
+
+        return null;
+    }
+}

From a66fa5e2857bc7f604a15d1be13a728b57250943 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:26 -0400
Subject: [PATCH 02/25] refactor: reuse Symfony ranges for preview address
 checks

---
 app/Actions/UpdateLinkPreview.php            | 58 +----------------
 app/Services/LinkPreviewAddress.php          | 65 ++++++++++++++++++++
 tests/Unit/Actions/UpdateLinkPreviewTest.php |  9 +++
 3 files changed, 77 insertions(+), 55 deletions(-)
 create mode 100644 app/Services/LinkPreviewAddress.php

diff --git a/app/Actions/UpdateLinkPreview.php b/app/Actions/UpdateLinkPreview.php
index 583f32f85..5fbd072cb 100644
--- a/app/Actions/UpdateLinkPreview.php
+++ b/app/Actions/UpdateLinkPreview.php
@@ -4,7 +4,7 @@
 
 namespace App\Actions;
 
-use App\Contracts\Services\DnsResolver;
+use App\Services\LinkPreviewAddress;
 use App\Dto\LinkPreviewMetadata;
 use App\Models\LinkPreview;
 use App\Services\LinkPreviewParser;
@@ -14,7 +14,6 @@
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Str;
-use Symfony\Component\HttpFoundation\IpUtils;
 use Uri\WhatWg\Url;
 
 final readonly class UpdateLinkPreview
@@ -23,34 +22,7 @@
 
     private const int MAX_BODY_BYTES = 1_048_576;
 
-    /**
-     * Non-public ranges that filter_var's private and reserved range flags let through: carrier-grade NAT, IETF protocol
-     * assignments, 6to4 relays, benchmarking, documentation and multicast for IPv4; NAT64, discard, Teredo,
-     * documentation, 6to4, site-local, multicast and IPv4-translated addresses for IPv6.
-     *
-     * @var list<string>
-     */
-    private const array BLOCKED_RANGES = [
-        '100.64.0.0/10',
-        '192.0.0.0/24',
-        '192.0.2.0/24',
-        '192.88.99.0/24',
-        '198.18.0.0/15',
-        '198.51.100.0/24',
-        '203.0.113.0/24',
-        '224.0.0.0/4',
-        '64:ff9b::/96',
-        '64:ff9b:1::/48',
-        '100::/64',
-        '2001::/32',
-        '2001:db8::/32',
-        '2002::/16',
-        'fec0::/10',
-        'ff00::/8',
-        '::ffff:0:0:0/96',
-    ];
-
-    public function __construct(private DnsResolver $dns, private LinkPreviewParser $parser)
+    public function __construct(private LinkPreviewAddress $addresses, private LinkPreviewParser $parser)
     {
         //
     }
@@ -75,7 +47,7 @@ private function fetchMetadata(string $url): LinkPreviewMetadata
         $page = Url::parse($url);
 
         for ($hop = 0; $hop <= self::MAX_REDIRECTS && $page instanceof Url; $hop++) {
-            $address = $this->publicAddress($page);
+            $address = $this->addresses->get($page);
 
             if ($address === null) {
                 return new LinkPreviewMetadata;
@@ -99,30 +71,6 @@ private function fetchMetadata(string $url): LinkPreviewMetadata
         return new LinkPreviewMetadata;
     }
 
-    /**
-     * Returns the address to connect to, or null when the URL must not be fetched: anything but plain http(s) on a
-     * default port without credentials, or a host that resolves to nothing or to any non-public address.
-     */
-    private function publicAddress(Url $url): ?string
-    {
-        if (! in_array($url->getScheme(), ['http', 'https'], true)
-            || ($url->getUsername() ?? '') !== ''
-            || ($url->getPassword() ?? '') !== ''
-            || ! in_array($url->getPort(), [null, 80, 443], true)) {
-            return null;
-        }
-
-        $addresses = $this->dns->resolve(mb_trim((string) $url->getAsciiHost(), '[]'));
-
-        return $addresses !== [] && array_all($addresses, $this->isPublic(...)) ? $addresses[0] : null;
-    }
-
-    private function isPublic(string $address): bool
-    {
-        return filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) !== false
-            && ! IpUtils::checkIp($address, self::BLOCKED_RANGES);
-    }
-
     /**
      * Connects to the address that was checked rather than resolving the host again, so DNS rebinding can't swap in a
      * private address. The empty host and port in CURLOPT_CONNECT_TO match every request, so the pin holds even if
diff --git a/app/Services/LinkPreviewAddress.php b/app/Services/LinkPreviewAddress.php
new file mode 100644
index 000000000..b4a6a7d04
--- /dev/null
+++ b/app/Services/LinkPreviewAddress.php
@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Contracts\Services\DnsResolver;
+use Symfony\Component\HttpFoundation\IpUtils;
+use Uri\WhatWg\Url;
+
+final readonly class LinkPreviewAddress
+{
+    /**
+     * Extend Symfony's private subnets with relay, multicast, site-local and translated ranges
+     * that PHP's global-range filter also permits.
+     *
+     * @var list<string>
+     */
+    private const array BLOCKED_RANGES = [
+        ...IpUtils::PRIVATE_SUBNETS,
+        '192.88.99.0/24',
+        '224.0.0.0/4',
+        'fec0::/10',
+        'ff00::/8',
+        '::ffff:0:0:0/96',
+    ];
+
+    public function __construct(private DnsResolver $dns)
+    {
+        //
+    }
+
+    /**
+     * Returns the address to connect to, or null when the URL must not be fetched: anything but plain http(s) on a
+     * default port without credentials, or a host that resolves to nothing or to any non-public address.
+     */
+    public function get(Url $url): ?string
+    {
+        if (! in_array($url->getScheme(), ['http', 'https'], true)) {
+            return null;
+        }
+
+        if (($url->getUsername() ?? '') !== '') {
+            return null;
+        }
+
+        if (($url->getPassword() ?? '') !== '') {
+            return null;
+        }
+
+        if ($url->getPort() !== null) {
+            return null;
+        }
+
+        $addresses = $this->dns->resolve(mb_trim((string) $url->getAsciiHost(), '[]'));
+
+        return $addresses !== [] && array_all($addresses, $this->isPublic(...)) ? $addresses[0] : null;
+    }
+
+    private function isPublic(string $address): bool
+    {
+        return filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE) !== false
+            && ! IpUtils::checkIp($address, self::BLOCKED_RANGES);
+    }
+}
diff --git a/tests/Unit/Actions/UpdateLinkPreviewTest.php b/tests/Unit/Actions/UpdateLinkPreviewTest.php
index bd4d7f77a..58d70f171 100644
--- a/tests/Unit/Actions/UpdateLinkPreviewTest.php
+++ b/tests/Unit/Actions/UpdateLinkPreviewTest.php
@@ -301,6 +301,9 @@ function expectNoMetadata(LinkPreview $linkPreview): void
     'home network' => 'http://192.168.1.1/',
     'cloud metadata' => 'http://169.254.169.254/latest/meta-data/',
     'carrier-grade nat' => 'http://100.64.0.1/',
+    'protocol assignment' => 'http://192.0.0.1/',
+    'deprecated relay' => 'http://192.88.99.1/',
+    'documentation' => 'http://192.0.2.1/',
     'benchmarking' => 'http://198.18.0.1/',
     'unspecified' => 'http://0.0.0.0/',
     'multicast' => 'http://224.0.0.1/',
@@ -309,12 +312,18 @@ function expectNoMetadata(LinkPreview $linkPreview): void
     'ipv6 link-local' => 'http://[fe80::1]/',
     'ipv4-mapped ipv6' => 'http://[::ffff:127.0.0.1]/',
     'nat64' => 'http://[64:ff9b::a00:1]/',
+    'nat64 local use' => 'http://[64:ff9b:1::a00:1]/',
+    'ipv6 discard' => 'http://[100::1]/',
+    'ipv6 site-local' => 'http://[fec0::1]/',
+    'ipv4-translated ipv6' => 'http://[::ffff:0:a00:1]/',
     'ipv6 multicast' => 'http://[ff02::1]/',
     'localhost' => 'http://localhost/',
     'host resolving to a private address' => 'https://internal.example.com/',
     'host resolving partly to a private address' => 'https://mixed.example.com/',
     'host resolving to nothing' => 'https://nowhere.example.com/',
     'non-default port' => 'https://example.com:8080/',
+    'https on http port' => 'https://example.com:80/',
+    'http on https port' => 'http://example.com:443/',
     'credentials' => 'https://user:secret@example.com/',
     'username only' => 'https://user@example.com/',
     'password only' => 'https://:secret@example.com/',

From aabddceb69dd99342f1f00e43faac4f2ff6cddc4 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:29 -0400
Subject: [PATCH 03/25] fix: bound preview bodies and redirect request budgets

---
 app/Actions/UpdateLinkPreview.php             | 115 ++++++++++--------
 app/Dto/LinkPreviewRequest.php                |  23 ++++
 app/Services/LimitedResponseBody.php          |  25 ++++
 app/Services/LinkPreviewBudget.php            |  42 +++++++
 app/Services/LinkPreviewHttpClient.php        |  51 ++++++++
 tests/Unit/Actions/UpdateLinkPreviewTest.php  | 107 +++++++++++++++-
 .../Unit/Services/LimitedResponseBodyTest.php |  39 ++++++
 tests/Unit/Services/LinkPreviewBudgetTest.php |  28 +++++
 8 files changed, 377 insertions(+), 53 deletions(-)
 create mode 100644 app/Dto/LinkPreviewRequest.php
 create mode 100644 app/Services/LimitedResponseBody.php
 create mode 100644 app/Services/LinkPreviewBudget.php
 create mode 100644 app/Services/LinkPreviewHttpClient.php
 create mode 100644 tests/Unit/Services/LimitedResponseBodyTest.php
 create mode 100644 tests/Unit/Services/LinkPreviewBudgetTest.php

diff --git a/app/Actions/UpdateLinkPreview.php b/app/Actions/UpdateLinkPreview.php
index 5fbd072cb..b1ebadbd8 100644
--- a/app/Actions/UpdateLinkPreview.php
+++ b/app/Actions/UpdateLinkPreview.php
@@ -4,15 +4,15 @@
 
 namespace App\Actions;
 
-use App\Services\LinkPreviewAddress;
 use App\Dto\LinkPreviewMetadata;
+use App\Dto\LinkPreviewRequest;
 use App\Models\LinkPreview;
+use App\Services\LinkPreviewAddress;
+use App\Services\LinkPreviewBudget;
+use App\Services\LinkPreviewHttpClient;
 use App\Services\LinkPreviewParser;
-use GuzzleHttp\Exception\ResponseException;
 use GuzzleHttp\Psr7\Utils;
-use Illuminate\Http\Client\ConnectionException;
 use Illuminate\Http\Client\Response;
-use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Str;
 use Uri\WhatWg\Url;
 
@@ -22,8 +22,16 @@
 
     private const int MAX_BODY_BYTES = 1_048_576;
 
-    public function __construct(private LinkPreviewAddress $addresses, private LinkPreviewParser $parser)
-    {
+    private const string HEADER_ACCEPT = 'Accept';
+
+    private const string HTML_CONTENT_TYPE = 'text/html';
+
+    public function __construct(
+        private LinkPreviewAddress $addresses,
+        private LinkPreviewBudget $budget,
+        private LinkPreviewHttpClient $http,
+        private LinkPreviewParser $parser,
+    ) {
         //
     }
 
@@ -45,75 +53,83 @@ public function handle(LinkPreview $linkPreview): void
     private function fetchMetadata(string $url): LinkPreviewMetadata
     {
         $page = Url::parse($url);
+        $deadline = $this->budget->start();
+        $visited = [];
 
         for ($hop = 0; $hop <= self::MAX_REDIRECTS && $page instanceof Url; $hop++) {
-            $address = $this->addresses->get($page);
+            $source = $page->withFragment(null)->toAsciiString();
 
-            if ($address === null) {
+            if (isset($visited[$source])) {
                 return new LinkPreviewMetadata;
             }
 
-            $response = $this->get($page, $address);
+            $visited[$source] = true;
+            $request = $this->prepareRequest($page, $deadline);
 
-            if ($response->serverError() || $response->tooManyRequests()) {
-                $response->throw();
+            if (! $request instanceof LinkPreviewRequest) {
+                return new LinkPreviewMetadata;
             }
 
+            $response = $this->http->get($request);
+            $response->throwIf($response->serverError() || $response->tooManyRequests());
+
             if (! $response->redirect()) {
-                return $response->successful() && $this->isHtml($response)
-                    ? $this->parser->parse($this->body($response), $page)
-                    : new LinkPreviewMetadata;
+                return $this->responseMetadata($response, $page);
             }
 
-            $page = Url::parse($response->header('Location'), $page);
+            $page = $this->redirectPage($response, $page);
         }
 
         return new LinkPreviewMetadata;
     }
 
-    /**
-     * Connects to the address that was checked rather than resolving the host again, so DNS rebinding can't swap in a
-     * private address. The empty host and port in CURLOPT_CONNECT_TO match every request, so the pin holds even if
-     * cURL were to read the URL differently than we do. Bodies are cut off after 1 MB, and a body that was cut off
-     * (by that limit or by the timeout) is still used, as metadata lives at the top of the page. English is asked for
-     * explicitly, as sites such as YouTube otherwise pick the language from the server's location.
-     */
-    private function get(Url $url, string $address): Response
+    private function prepareRequest(Url $page, float $deadline): ?LinkPreviewRequest
     {
-        $port = $url->getPort() ?? ($url->getScheme() === 'https' ? 443 : 80);
-
-        $request = Http::withUserAgent(sprintf('Mozilla/5.0 (compatible; devnull-linkpreview/1.0; +%s)', config()->string('app.url')))
-            ->accept('text/html')
-            ->withHeaders(['Accept-Language' => 'en-US,en;q=0.9'])
-            ->connectTimeout(3)
-            ->timeout(5)
-            ->withoutRedirecting()
-            ->withOptions([
-                'decode_content' => false,
-                'progress' => fn (int $expected, int $downloaded): bool => $downloaded > self::MAX_BODY_BYTES,
-                'curl' => [
-                    CURLOPT_CONNECT_TO => [sprintf('::%s:%d', str_contains($address, ':') ? "[{$address}]" : $address, $port)],
-                ],
-            ]);
-
-        try {
-            return $request->get($url->toAsciiString());
-        } catch (ConnectionException $connectionException) {
-            $cutOff = $connectionException->getPrevious();
-
-            if ($cutOff instanceof ResponseException) {
-                return new Response($cutOff->getResponse());
-            }
+        $address = $this->addresses->get($page);
+        $remaining = $this->budget->remaining($deadline);
 
-            throw $connectionException;
+        if ($address === null || $remaining <= 0) {
+            return null;
         }
+
+        return new LinkPreviewRequest(
+            url: $page,
+            address: $address,
+            headers: [self::HEADER_ACCEPT => self::HTML_CONTENT_TYPE],
+            maxBodyBytes: self::MAX_BODY_BYTES,
+            timeoutSeconds: $remaining,
+        );
+    }
+
+    private function redirectPage(Response $response, Url $page): ?Url
+    {
+        $location = mb_trim($response->header('Location'));
+
+        if ($location === '') {
+            return null;
+        }
+
+        return Url::parse($location, $page);
+    }
+
+    private function responseMetadata(Response $response, Url $page): LinkPreviewMetadata
+    {
+        if (! $response->successful()) {
+            return new LinkPreviewMetadata;
+        }
+
+        if (! $this->isHtml($response)) {
+            return new LinkPreviewMetadata;
+        }
+
+        return $this->parser->parse($this->body($response), $page);
     }
 
     private function isHtml(Response $response): bool
     {
         $mediaType = mb_strtolower(mb_trim(Str::before($response->header('Content-Type'), ';')));
 
-        return in_array($mediaType, ['text/html', 'application/xhtml+xml'], true);
+        return in_array($mediaType, [self::HTML_CONTENT_TYPE, 'application/xhtml+xml'], true);
     }
 
     private function body(Response $response): string
@@ -123,5 +139,4 @@ private function body(Response $response): string
 
         return Utils::copyToString($body, self::MAX_BODY_BYTES);
     }
-
 }
diff --git a/app/Dto/LinkPreviewRequest.php b/app/Dto/LinkPreviewRequest.php
new file mode 100644
index 000000000..23f9f6f86
--- /dev/null
+++ b/app/Dto/LinkPreviewRequest.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Dto;
+
+use Uri\WhatWg\Url;
+
+final readonly class LinkPreviewRequest
+{
+    /**
+     * @param  array<string, string>  $headers
+     */
+    public function __construct(
+        public Url $url,
+        public string $address,
+        public array $headers,
+        public int $maxBodyBytes,
+        public float $timeoutSeconds,
+    ) {
+        //
+    }
+}
diff --git a/app/Services/LimitedResponseBody.php b/app/Services/LimitedResponseBody.php
new file mode 100644
index 000000000..85453c0be
--- /dev/null
+++ b/app/Services/LimitedResponseBody.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use GuzzleHttp\Psr7\Stream;
+use GuzzleHttp\Psr7\Utils;
+
+final class LimitedResponseBody extends Stream
+{
+    private const string BINARY_ENCODING = '8bit';
+
+    public function __construct(private readonly int $maxBytes)
+    {
+        parent::__construct(Utils::tryFopen('php://temp', 'w+'));
+    }
+
+    public function write(string $string): int
+    {
+        $remaining = max(0, $this->maxBytes - $this->tell());
+
+        return parent::write(mb_substr($string, 0, $remaining, self::BINARY_ENCODING));
+    }
+}
diff --git a/app/Services/LinkPreviewBudget.php b/app/Services/LinkPreviewBudget.php
new file mode 100644
index 000000000..dc05fcbe6
--- /dev/null
+++ b/app/Services/LinkPreviewBudget.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use Carbon\CarbonInterface;
+use Closure;
+
+final readonly class LinkPreviewBudget
+{
+    private const int TIMEOUT_SECONDS = 5;
+
+    private const int NANOSECONDS_PER_SECOND = 1_000_000_000;
+
+    /**
+     * @param  (Closure(): int)|null  $clock
+     */
+    public function __construct(private ?Closure $clock = null)
+    {
+        //
+    }
+
+    public function start(): float
+    {
+        return $this->seconds() + self::TIMEOUT_SECONDS;
+    }
+
+    public function remaining(float $deadline): float
+    {
+        $milliseconds = floor(($deadline - $this->seconds()) * CarbonInterface::MILLISECONDS_PER_SECOND);
+
+        return max(0, $milliseconds) / CarbonInterface::MILLISECONDS_PER_SECOND;
+    }
+
+    private function seconds(): float
+    {
+        $nanoseconds = $this->clock instanceof Closure ? ($this->clock)() : hrtime(true);
+
+        return $nanoseconds / self::NANOSECONDS_PER_SECOND;
+    }
+}
diff --git a/app/Services/LinkPreviewHttpClient.php b/app/Services/LinkPreviewHttpClient.php
new file mode 100644
index 000000000..fdac09890
--- /dev/null
+++ b/app/Services/LinkPreviewHttpClient.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Dto\LinkPreviewRequest;
+use GuzzleHttp\Exception\ResponseException;
+use GuzzleHttp\RequestOptions;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Facades\Http;
+
+final readonly class LinkPreviewHttpClient
+{
+    public const int HTTP_PORT = 80;
+
+    public const int HTTPS_PORT = 443;
+
+    private const int CONNECT_TIMEOUT_SECONDS = 3;
+
+    private const string USER_AGENT_FORMAT = 'Mozilla/5.0 (compatible; devnull-linkpreview/1.0; +%s)';
+
+    private const array DEFAULT_HEADERS = ['Accept-Language' => 'en-US,en;q=0.9'];
+
+    public function get(LinkPreviewRequest $request): Response
+    {
+        $port = $request->url->getPort() ?? ($request->url->getScheme() === 'https' ? self::HTTPS_PORT : self::HTTP_PORT);
+        $connection = sprintf('::%s:%d', str_contains($request->address, ':') ? "[{$request->address}]" : $request->address, $port);
+
+        try {
+            return Http::withUserAgent(sprintf(self::USER_AGENT_FORMAT, config()->string('app.url')))
+                ->withHeaders([...self::DEFAULT_HEADERS, ...$request->headers])
+                ->connectTimeout(min(self::CONNECT_TIMEOUT_SECONDS, $request->timeoutSeconds))
+                ->timeout($request->timeoutSeconds)
+                ->withoutRedirecting()
+                ->withOptions([
+                    RequestOptions::DECODE_CONTENT => false,
+                    RequestOptions::SINK => new LimitedResponseBody($request->maxBodyBytes),
+                    RequestOptions::CURL => [CURLOPT_CONNECT_TO => [$connection]],
+                ])
+                ->get($request->url->toAsciiString());
+        } catch (ConnectionException $connectionException) {
+            $previous = $connectionException->getPrevious();
+
+            throw_unless($previous instanceof ResponseException, $connectionException);
+
+            return new Response($previous->getResponse());
+        }
+    }
+}
diff --git a/tests/Unit/Actions/UpdateLinkPreviewTest.php b/tests/Unit/Actions/UpdateLinkPreviewTest.php
index 58d70f171..21b9f2a90 100644
--- a/tests/Unit/Actions/UpdateLinkPreviewTest.php
+++ b/tests/Unit/Actions/UpdateLinkPreviewTest.php
@@ -4,15 +4,21 @@
 
 use App\Actions\UpdateLinkPreview;
 use App\Contracts\Services\DnsResolver;
+use App\Dto\LinkPreviewRequest;
 use App\Models\LinkPreview;
 use App\Services\DnsResolvers\SystemDnsResolver;
+use App\Services\LimitedResponseBody;
+use App\Services\LinkPreviewBudget;
+use App\Services\LinkPreviewHttpClient;
 use GuzzleHttp\Exception\ResponseException;
 use GuzzleHttp\Promise\Create;
 use GuzzleHttp\Promise\PromiseInterface;
 use GuzzleHttp\Psr7\Response as PsrResponse;
+use GuzzleHttp\RequestOptions;
 use Illuminate\Http\Client\HttpClientException;
 use Illuminate\Http\Client\Request;
 use Illuminate\Support\Facades\Http;
+use Uri\WhatWg\Url;
 
 beforeEach(function (): void {
     $this->app->instance(DnsResolver::class, new readonly class implements DnsResolver
@@ -103,11 +109,12 @@ function expectNoMetadata(LinkPreview $linkPreview): void
     expect($options)
         ->allow_redirects->toBeFalse()
         ->connect_timeout->toBe(3)
-        ->timeout->toBe(5)
+        ->timeout->toBeGreaterThan(0)->toBeLessThanOrEqual(5)
         ->decode_content->toBeFalse()
         ->and($options['curl'][CURLOPT_CONNECT_TO])->toBe(['::93.184.216.34:443'])
-        ->and($options['progress'](0, 1_048_576, 0, 0))->toBeFalse()
-        ->and($options['progress'](2_000_000, 1_048_577, 0, 0))->toBeTrue();
+        ->and($options['sink'])->toBeInstanceOf(LimitedResponseBody::class)
+        ->and($options['sink']->write(str_repeat('x', 1_048_577)))->toBe(1_048_576)
+        ->and($options['sink']->getSize())->toBe(1_048_576);
 });
 
 it('pins the connection to the port and address that were checked', function (string $url, string $connectTo): void {
@@ -439,3 +446,97 @@ public function resolve(string $host): array
     expect(fn () => resolve(UpdateLinkPreview::class)->handle($linkPreview))->toThrow(RuntimeException::class, 'The resolver broke.')
         ->and($linkPreview->refresh()->fetched_at)->toBeNull();
 });
+
+it('stops repeated redirect destinations before fetching them again', function (array $responses, int $requests): void {
+    Http::fake($responses);
+
+    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    Http::assertSentCount($requests);
+})->with([
+    'self loop' => [fn (): array => [
+        'https://example.com/start.gif' => Http::response(status: 302, headers: ['Location' => '/start.gif']),
+    ], 1],
+    'fragment-only loop' => [fn (): array => [
+        'https://example.com/start.gif' => Http::response(status: 302, headers: ['Location' => '#other']),
+    ], 1],
+    'two host loop' => [fn (): array => [
+        'https://example.com/start.gif' => Http::response(status: 302, headers: ['Location' => 'https://www.example.com/next.gif']),
+        'https://www.example.com/next.gif' => Http::response(status: 302, headers: ['Location' => 'https://example.com/start.gif']),
+    ], 2],
+]);
+
+it('does not refetch redirects with a missing or invalid location', function (?string $location): void {
+    Http::fake(['https://example.com/*' => Http::response(status: 302, headers: $location === null ? [] : ['Location' => $location])]);
+
+    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    Http::assertSentCount(1);
+})->with([null, '', '   ', 'https://invalid host/cat.gif']);
+
+it('reduces each hop timeout to the remaining overall budget', function (): void {
+    $nanoseconds = 0;
+    $clock = function () use (&$nanoseconds): int {
+        return $nanoseconds;
+    };
+    $this->app->instance(LinkPreviewBudget::class, new LinkPreviewBudget($clock));
+    $timeouts = [];
+    $connectTimeouts = [];
+    Http::fake(function (Request $request, array $options) use (&$nanoseconds, &$timeouts, &$connectTimeouts): PromiseInterface {
+        $timeouts[] = $options['timeout'];
+        $connectTimeouts[] = $options['connect_timeout'];
+        $nanoseconds += 2_000_000_000;
+
+        return Http::response(status: 302, headers: ['Location' => '/hop-'.count($timeouts).'.gif']);
+    });
+
+    expect(unfurl('https://example.com/start.gif')->title)->toBeNull()
+        ->and($timeouts)->toBe([5.0, 3.0, 1.0])
+        ->and($connectTimeouts)->toBe([3, 3.0, 1.0]);
+    Http::assertSentCount(3);
+});
+
+it('does not connect if resolving an address exhausted the budget', function (): void {
+    $this->app->instance(LinkPreviewBudget::class, new LinkPreviewBudget(function (): int {
+        static $calls = 0;
+
+        return $calls++ === 0 ? 0 : 6_000_000_000;
+    }));
+    Http::fake();
+
+    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    Http::assertNothingSent();
+});
+
+it('rechecks changed DNS answers before following a redirect', function (): void {
+    $this->app->instance(DnsResolver::class, new class implements DnsResolver
+    {
+        private int $calls = 0;
+
+        public function resolve(string $host): array
+        {
+            return $this->calls++ === 0 ? ['93.184.216.34'] : ['10.0.0.1'];
+        }
+    });
+    Http::fake(['https://example.com/start.gif' => Http::response(status: 302, headers: ['Location' => '/next.gif'])]);
+
+    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    Http::assertSentCount(1);
+});
+
+it('pins the explicit port carried by a prepared request', function (): void {
+    $options = [];
+    Http::fake(function (Request $request, array $sent) use (&$options): PromiseInterface {
+        $options = $sent;
+
+        return htmlResponse('<title>Prepared request</title>');
+    });
+    $request = new LinkPreviewRequest(
+        url: Url::parse('https://example.com:8443/'),
+        address: '93.184.216.34',
+        headers: ['Accept' => 'text/html'],
+        maxBodyBytes: 32,
+        timeoutSeconds: 5,
+    );
+
+    expect(resolve(LinkPreviewHttpClient::class)->get($request)->successful())->toBeTrue()
+        ->and($options[RequestOptions::CURL][CURLOPT_CONNECT_TO])->toBe(['::93.184.216.34:8443']);
+});
diff --git a/tests/Unit/Services/LimitedResponseBodyTest.php b/tests/Unit/Services/LimitedResponseBodyTest.php
new file mode 100644
index 000000000..d040fd93b
--- /dev/null
+++ b/tests/Unit/Services/LimitedResponseBodyTest.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Services\LimitedResponseBody;
+
+it('retains short responses without changing their bytes', function (): void {
+    $body = new LimitedResponseBody(32);
+    $header = "GIF89a\xc2\x80\x01\x00\x80\x00\x00";
+
+    expect($body->write($header))->toBe(13)
+        ->and((string) $body)->toBe($header);
+});
+
+it('returns a short write so the transport aborts an oversized response', function (): void {
+    $body = new LimitedResponseBody(32);
+
+    expect($body->write('GIF89a'.str_repeat('x', 1_048_576)))->toBe(32)
+        ->and($body->getSize())->toBe(32)
+        ->and((string) $body)->toBe('GIF89a'.str_repeat('x', 26));
+});
+
+it('enforces the same cap across multiple writes', function (): void {
+    $body = new LimitedResponseBody(32);
+
+    expect($body->write(str_repeat('a', 20)))->toBe(20)
+        ->and($body->write(str_repeat('b', 20)))->toBe(12)
+        ->and($body->write('c'))->toBe(0)
+        ->and($body->getSize())->toBe(32)
+        ->and((string) $body)->toBe(str_repeat('a', 20).str_repeat('b', 12));
+});
+
+it('does not let a seek move writes past the byte cap', function (): void {
+    $body = new LimitedResponseBody(32);
+    $body->seek(64);
+
+    expect($body->write('overflow'))->toBe(0)
+        ->and($body->getSize())->toBe(0);
+});
diff --git a/tests/Unit/Services/LinkPreviewBudgetTest.php b/tests/Unit/Services/LinkPreviewBudgetTest.php
new file mode 100644
index 000000000..765cf81f6
--- /dev/null
+++ b/tests/Unit/Services/LinkPreviewBudgetTest.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Services\LinkPreviewBudget;
+
+it('shares one monotonic deadline across the fetch', function (): void {
+    $nanoseconds = 0;
+    $clock = function () use (&$nanoseconds): int {
+        return $nanoseconds;
+    };
+    $budget = new LinkPreviewBudget($clock);
+    $deadline = $budget->start();
+    $nanoseconds = 2_000_000_000;
+
+    expect($deadline)->toBe(5.0)
+        ->and($budget->remaining($deadline))->toBe(3.0);
+
+    $nanoseconds = 6_000_000_000;
+
+    expect($budget->remaining($deadline))->toBe(0.0);
+});
+
+it('does not pass a sub-millisecond timeout to the HTTP client', function (int $nanoseconds): void {
+    $budget = new LinkPreviewBudget(fn (): int => $nanoseconds);
+
+    expect($budget->remaining(5.0))->toBe(0.0);
+})->with([4_999_999_999, 4_999_100_000]);

From 426d98f08b17a7c581822a3c7e981280c9f897dd Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:31 -0400
Subject: [PATCH 04/25] feat: resolve Giphy share links without API keys

---
 app/Dto/Embed.php                             |  5 ++
 app/Enums/EmbedKind.php                       |  1 +
 app/Services/EmbedProviders/Giphy.php         | 75 +++++++++++++++++++
 config/embeds.php                             |  2 +
 .../Services/EmbedProviders/GiphyTest.php     | 43 +++++++++++
 5 files changed, 126 insertions(+)
 create mode 100644 app/Services/EmbedProviders/Giphy.php
 create mode 100644 tests/Unit/Services/EmbedProviders/GiphyTest.php

diff --git a/app/Dto/Embed.php b/app/Dto/Embed.php
index a5c6ef6a6..7d1f161eb 100644
--- a/app/Dto/Embed.php
+++ b/app/Dto/Embed.php
@@ -41,6 +41,11 @@ public static function fixed(string $provider, EmbedKind $kind, string $src, int
         return new self($provider, $kind, self::withQuery($src, $query), null, $height);
     }
 
+    public static function gif(string $provider, string $src, ?string $poster = null): self
+    {
+        return new self($provider, EmbedKind::Gif, $src, '1 / 1', null, $poster);
+    }
+
     /**
      * @return array{provider: string, kind: string, src: string, aspect_ratio: string|null, height: int|null, poster: string|null}
      */
diff --git a/app/Enums/EmbedKind.php b/app/Enums/EmbedKind.php
index 09d39fa51..ca66dd258 100644
--- a/app/Enums/EmbedKind.php
+++ b/app/Enums/EmbedKind.php
@@ -9,4 +9,5 @@ enum EmbedKind: string
     case Video = 'video';
     case Audio = 'audio';
     case Code = 'code';
+    case Gif = 'gif';
 }
diff --git a/app/Services/EmbedProviders/Giphy.php b/app/Services/EmbedProviders/Giphy.php
new file mode 100644
index 000000000..2856adffa
--- /dev/null
+++ b/app/Services/EmbedProviders/Giphy.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\EmbedProviders;
+
+use App\Contracts\Services\EmbedProvider;
+use App\Dto\Embed;
+use Illuminate\Support\Str;
+use Uri\WhatWg\Url;
+
+final readonly class Giphy implements EmbedProvider
+{
+    private const array SUPPORTED_SCHEMES = ['http', 'https'];
+
+    private const array SUPPORTED_HOSTS = ['giphy.com', 'www.giphy.com'];
+
+    private const int PATH_SEGMENT_COUNT = 2;
+
+    public function embed(Url $url): ?Embed
+    {
+        if (! $this->supportsUrl($url)) {
+            return null;
+        }
+
+        $identifier = $this->getGifId($url->getPath());
+
+        if ($identifier === null) {
+            return null;
+        }
+
+        $mediaUrl = "https://media.giphy.com/media/{$identifier}";
+
+        return Embed::gif('GIPHY', "{$mediaUrl}/giphy.gif", "{$mediaUrl}/giphy_s.gif");
+    }
+
+    private function supportsUrl(Url $url): bool
+    {
+        if (! in_array($url->getScheme(), self::SUPPORTED_SCHEMES, true)) {
+            return false;
+        }
+
+        if (! in_array($url->getAsciiHost(), self::SUPPORTED_HOSTS, true)) {
+            return false;
+        }
+
+        if (($url->getUsername() ?? '') !== '') {
+            return false;
+        }
+
+        if (($url->getPassword() ?? '') !== '') {
+            return false;
+        }
+
+        return $url->getPort() === null;
+    }
+
+    private function getGifId(string $path): ?string
+    {
+        $segments = explode('/', mb_trim($path, '/'));
+
+        if (count($segments) !== self::PATH_SEGMENT_COUNT) {
+            return null;
+        }
+
+        [$section, $slug] = $segments;
+        $identifier = match (Str::lower($section)) {
+            'gifs' => Str::afterLast($slug, '-'),
+            'embed' => $slug,
+            default => '',
+        };
+
+        return ctype_alnum($identifier) ? $identifier : null;
+    }
+}
diff --git a/config/embeds.php b/config/embeds.php
index c9349bc0c..ee6564a40 100644
--- a/config/embeds.php
+++ b/config/embeds.php
@@ -5,6 +5,7 @@
 use App\Services\EmbedProviders\AppleMusic;
 use App\Services\EmbedProviders\Asciinema;
 use App\Services\EmbedProviders\CodePen;
+use App\Services\EmbedProviders\Giphy;
 use App\Services\EmbedProviders\Loom;
 use App\Services\EmbedProviders\SoundCloud;
 use App\Services\EmbedProviders\Spotify;
@@ -20,6 +21,7 @@
     'only' => array_values(array_filter(array_map(trim(...), explode(',', (string) env('EMBEDS_PROVIDERS', ''))))),
 
     'providers' => [
+        'giphy' => Giphy::class,
         'youtube' => YouTube::class,
         'vimeo' => Vimeo::class,
         'loom' => Loom::class,
diff --git a/tests/Unit/Services/EmbedProviders/GiphyTest.php b/tests/Unit/Services/EmbedProviders/GiphyTest.php
new file mode 100644
index 000000000..c098e9ba8
--- /dev/null
+++ b/tests/Unit/Services/EmbedProviders/GiphyTest.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Services\EmbedProviders\Giphy;
+use Uri\WhatWg\Url;
+
+it('builds external GIF and static poster URLs without an API', function (string $url): void {
+    expect(resolve(Giphy::class)->embed(Url::parse($url))?->toArray())->toBe([
+        'provider' => 'GIPHY',
+        'kind' => 'gif',
+        'src' => 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif',
+        'aspect_ratio' => '1 / 1',
+        'height' => null,
+        'poster' => 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy_s.gif',
+    ]);
+})->with([
+    'share' => 'https://giphy.com/gifs/cat-typing-JIX9t2j0ZTN9S',
+    'id' => 'https://www.giphy.com/gifs/JIX9t2j0ZTN9S/',
+    'embed' => 'https://giphy.com/embed/JIX9t2j0ZTN9S',
+    'uppercase section' => 'https://giphy.com/GIFS/cat-JIX9t2j0ZTN9S',
+    'query and fragment' => 'https://giphy.com/gifs/cat-JIX9t2j0ZTN9S?tracking=ignored#ignored',
+    'http link' => 'http://giphy.com/gifs/JIX9t2j0ZTN9S',
+]);
+
+it('does not embed malformed links or untrusted hosts', function (string $url): void {
+    expect(resolve(Giphy::class)->embed(Url::parse($url)))->toBeNull();
+})->with([
+    'home' => 'https://giphy.com/',
+    'search' => 'https://giphy.com/search/cats',
+    'missing id' => 'https://giphy.com/gifs/',
+    'empty slug identifier' => 'https://giphy.com/gifs/cat-',
+    'embed with slug' => 'https://giphy.com/embed/cat-JIX9t2j0ZTN9S',
+    'escaped id' => 'https://giphy.com/gifs/cat-%3Cscript%3E',
+    'extra segment' => 'https://giphy.com/embed/JIX9t2j0ZTN9S/other',
+    'lookalike' => 'https://giphy.com.example.com/gifs/JIX9t2j0ZTN9S',
+    'other host' => 'https://example.com/gifs/JIX9t2j0ZTN9S',
+    'credentials' => 'https://user:secret@giphy.com/gifs/JIX9t2j0ZTN9S',
+    'username' => 'https://user@giphy.com/gifs/JIX9t2j0ZTN9S',
+    'password' => 'https://:secret@giphy.com/gifs/JIX9t2j0ZTN9S',
+    'port' => 'https://giphy.com:8443/gifs/JIX9t2j0ZTN9S',
+    'scheme' => 'ftp://giphy.com/gifs/JIX9t2j0ZTN9S',
+]);

From 40fb0fae4870abeb574f93ae9fc61937fce1c946 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:34 -0400
Subject: [PATCH 05/25] feat: verify and persist external GIF preview URLs

---
 app/Actions/UpdateLinkPreview.php             |  44 ++++++-
 app/Dto/LinkPreviewMetadata.php               |   4 +-
 app/Models/LinkPreview.php                    |   4 +-
 app/Services/Embeds.php                       |  13 +-
 app/Services/GifLinks.php                     |  87 +++++++++++++
 config/embeds.php                             |   1 +
 ...000_add_gif_url_to_link_previews_table.php |  17 +++
 .../Controllers/Api/CommitControllerTest.php  |  20 +++
 tests/Unit/Actions/UpdateLinkPreviewTest.php  | 122 +++++++++++++++++-
 tests/Unit/Models/LinkPreviewTest.php         |  14 ++
 tests/Unit/Services/EmbedsTest.php            |  30 +++++
 11 files changed, 341 insertions(+), 15 deletions(-)
 create mode 100644 app/Services/GifLinks.php
 create mode 100644 database/migrations/2026_10_20_120000_add_gif_url_to_link_previews_table.php

diff --git a/app/Actions/UpdateLinkPreview.php b/app/Actions/UpdateLinkPreview.php
index b1ebadbd8..f520103fb 100644
--- a/app/Actions/UpdateLinkPreview.php
+++ b/app/Actions/UpdateLinkPreview.php
@@ -7,6 +7,7 @@
 use App\Dto\LinkPreviewMetadata;
 use App\Dto\LinkPreviewRequest;
 use App\Models\LinkPreview;
+use App\Services\GifLinks;
 use App\Services\LinkPreviewAddress;
 use App\Services\LinkPreviewBudget;
 use App\Services\LinkPreviewHttpClient;
@@ -24,11 +25,14 @@
 
     private const string HEADER_ACCEPT = 'Accept';
 
+    private const string HEADER_RANGE = 'Range';
+
     private const string HTML_CONTENT_TYPE = 'text/html';
 
     public function __construct(
         private LinkPreviewAddress $addresses,
         private LinkPreviewBudget $budget,
+        private GifLinks $gifLinks,
         private LinkPreviewHttpClient $http,
         private LinkPreviewParser $parser,
     ) {
@@ -53,6 +57,7 @@ public function handle(LinkPreview $linkPreview): void
     private function fetchMetadata(string $url): LinkPreviewMetadata
     {
         $page = Url::parse($url);
+        $isGif = $this->gifLinks->isGifUrl($page);
         $deadline = $this->budget->start();
         $visited = [];
 
@@ -64,7 +69,7 @@ private function fetchMetadata(string $url): LinkPreviewMetadata
             }
 
             $visited[$source] = true;
-            $request = $this->prepareRequest($page, $deadline);
+            $request = $this->prepareRequest($page, $isGif, $deadline);
 
             if (! $request instanceof LinkPreviewRequest) {
                 return new LinkPreviewMetadata;
@@ -74,7 +79,7 @@ private function fetchMetadata(string $url): LinkPreviewMetadata
             $response->throwIf($response->serverError() || $response->tooManyRequests());
 
             if (! $response->redirect()) {
-                return $this->responseMetadata($response, $page);
+                return $this->responseMetadata($response, $page, $isGif);
             }
 
             $page = $this->redirectPage($response, $page);
@@ -83,8 +88,12 @@ private function fetchMetadata(string $url): LinkPreviewMetadata
         return new LinkPreviewMetadata;
     }
 
-    private function prepareRequest(Url $page, float $deadline): ?LinkPreviewRequest
+    private function prepareRequest(Url $page, bool $isGif, float $deadline): ?LinkPreviewRequest
     {
+        if ($isGif && $page->getScheme() !== 'https') {
+            return null;
+        }
+
         $address = $this->addresses->get($page);
         $remaining = $this->budget->remaining($deadline);
 
@@ -95,8 +104,8 @@ private function prepareRequest(Url $page, float $deadline): ?LinkPreviewRequest
         return new LinkPreviewRequest(
             url: $page,
             address: $address,
-            headers: [self::HEADER_ACCEPT => self::HTML_CONTENT_TYPE],
-            maxBodyBytes: self::MAX_BODY_BYTES,
+            headers: $this->requestHeaders($isGif),
+            maxBodyBytes: $isGif ? GifLinks::HEADER_BYTES : self::MAX_BODY_BYTES,
             timeoutSeconds: $remaining,
         );
     }
@@ -112,12 +121,28 @@ private function redirectPage(Response $response, Url $page): ?Url
         return Url::parse($location, $page);
     }
 
-    private function responseMetadata(Response $response, Url $page): LinkPreviewMetadata
+    /**
+     * @return array<string, string>
+     */
+    private function requestHeaders(bool $isGif): array
+    {
+        if (! $isGif) {
+            return [self::HEADER_ACCEPT => self::HTML_CONTENT_TYPE];
+        }
+
+        return [self::HEADER_ACCEPT => GifLinks::CONTENT_TYPE, self::HEADER_RANGE => sprintf('bytes=0-%d', GifLinks::HEADER_BYTES - 1)];
+    }
+
+    private function responseMetadata(Response $response, Url $page, bool $isGif): LinkPreviewMetadata
     {
         if (! $response->successful()) {
             return new LinkPreviewMetadata;
         }
 
+        if ($isGif) {
+            return $this->getGifMetadata($response, $page);
+        }
+
         if (! $this->isHtml($response)) {
             return new LinkPreviewMetadata;
         }
@@ -125,6 +150,13 @@ private function responseMetadata(Response $response, Url $page): LinkPreviewMet
         return $this->parser->parse($this->body($response), $page);
     }
 
+    private function getGifMetadata(Response $response, Url $page): LinkPreviewMetadata
+    {
+        $url = $this->gifLinks->getVerifiedUrl($page, $response->header('Content-Type'), $this->body($response));
+
+        return new LinkPreviewMetadata(gifUrl: $url);
+    }
+
     private function isHtml(Response $response): bool
     {
         $mediaType = mb_strtolower(mb_trim(Str::before($response->header('Content-Type'), ';')));
diff --git a/app/Dto/LinkPreviewMetadata.php b/app/Dto/LinkPreviewMetadata.php
index 7e0168326..1faa88191 100644
--- a/app/Dto/LinkPreviewMetadata.php
+++ b/app/Dto/LinkPreviewMetadata.php
@@ -16,12 +16,13 @@ public function __construct(
         public ?string $description = null,
         public ?string $imageUrl = null,
         public ?string $siteName = null,
+        public ?string $gifUrl = null,
     ) {
         //
     }
 
     /**
-     * @return array{title: string|null, description: string|null, image_url: string|null, site_name: string|null}
+     * @return array{title: string|null, description: string|null, image_url: string|null, site_name: string|null, gif_url: string|null}
      */
     public function toArray(): array
     {
@@ -30,6 +31,7 @@ public function toArray(): array
             'description' => $this->description,
             'image_url' => $this->imageUrl,
             'site_name' => $this->siteName,
+            'gif_url' => $this->gifUrl,
         ];
     }
 }
diff --git a/app/Models/LinkPreview.php b/app/Models/LinkPreview.php
index cda016627..3a5b564d0 100644
--- a/app/Models/LinkPreview.php
+++ b/app/Models/LinkPreview.php
@@ -20,6 +20,7 @@
  * @property-read string|null $description
  * @property-read string|null $image_url
  * @property-read string|null $site_name
+ * @property-read string|null $gif_url
  * @property-read CarbonInterface|null $fetched_at
  * @property-read CarbonInterface $created_at
  * @property-read CarbonInterface $updated_at
@@ -51,6 +52,7 @@ public function casts(): array
             'description' => 'string',
             'image_url' => 'string',
             'site_name' => 'string',
+            'gif_url' => 'string',
             'fetched_at' => 'datetime',
             'created_at' => 'datetime',
             'updated_at' => 'datetime',
@@ -62,6 +64,6 @@ public function casts(): array
      */
     public function toArray(): array
     {
-        return [...parent::toArray(), 'is_pending' => $this->fetched_at === null, 'embed' => resolve(Embeds::class)->for($this->url)?->toArray()];
+        return [...parent::toArray(), 'is_pending' => $this->fetched_at === null, 'embed' => resolve(Embeds::class)->for($this->url, $this->gif_url)?->toArray()];
     }
 }
diff --git a/app/Services/Embeds.php b/app/Services/Embeds.php
index 9b2847713..5946695cf 100644
--- a/app/Services/Embeds.php
+++ b/app/Services/Embeds.php
@@ -16,7 +16,10 @@ public function __construct(private Container $container)
         //
     }
 
-    public function for(string $url): ?Embed
+    /**
+     * The GIF URL is metadata verified by the link unfurler, never a client-supplied attachment.
+     */
+    public function for(string $url, ?string $gifUrl = null): ?Embed
     {
         $parsed = Url::parse($url);
 
@@ -32,7 +35,13 @@ public function for(string $url): ?Embed
             }
         }
 
-        return null;
+        $only = config()->array('embeds.only');
+
+        if ($gifUrl === null || ($only !== [] && ! in_array('gif', $only, true))) {
+            return null;
+        }
+
+        return Embed::gif('GIF', $gifUrl);
     }
 
     /**
diff --git a/app/Services/GifLinks.php b/app/Services/GifLinks.php
new file mode 100644
index 000000000..c4e8bca86
--- /dev/null
+++ b/app/Services/GifLinks.php
@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use Illuminate\Support\Str;
+use Uri\WhatWg\Url;
+
+final readonly class GifLinks
+{
+    public const string CONTENT_TYPE = 'image/gif';
+
+    public const int HEADER_BYTES = 32;
+
+    private const int MIN_HEADER_BYTES = 13;
+
+    private const int MAX_URL_LENGTH = 2048;
+
+    private const int SIGNATURE_BYTES = 6;
+
+    private const int WIDTH_OFFSET = 6;
+
+    private const int HEIGHT_OFFSET = 8;
+
+    private const int DIMENSION_BYTES = 2;
+
+    private const array SIGNATURES = ['GIF87a', 'GIF89a'];
+
+    private const string ZERO_DIMENSION = "\0\0";
+
+    private const string BINARY_ENCODING = '8bit';
+
+    public function isGifUrl(?Url $url): bool
+    {
+        if ($url?->getScheme() !== 'https') {
+            return false;
+        }
+
+        return str_ends_with(mb_strtolower($url->getPath()), '.gif');
+    }
+
+    public function getVerifiedUrl(Url $url, string $contentType, string $header): ?string
+    {
+        $mediaType = mb_strtolower(mb_trim(Str::before($contentType, ';')));
+
+        if ($mediaType !== self::CONTENT_TYPE) {
+            return null;
+        }
+
+        $sourceUrl = $url->toAsciiString();
+
+        if (mb_strlen($sourceUrl) > self::MAX_URL_LENGTH) {
+            return null;
+        }
+
+        if (! $this->isValidHeader($header)) {
+            return null;
+        }
+
+        return $sourceUrl;
+    }
+
+    private function isValidHeader(string $header): bool
+    {
+        if (mb_strlen($header, self::BINARY_ENCODING) < self::MIN_HEADER_BYTES) {
+            return false;
+        }
+
+        return $this->hasValidSignature($header) && $this->hasValidDimensions($header);
+    }
+
+    private function hasValidSignature(string $header): bool
+    {
+        $signature = mb_substr($header, 0, self::SIGNATURE_BYTES, self::BINARY_ENCODING);
+
+        return in_array($signature, self::SIGNATURES, true);
+    }
+
+    private function hasValidDimensions(string $header): bool
+    {
+        $width = mb_substr($header, self::WIDTH_OFFSET, self::DIMENSION_BYTES, self::BINARY_ENCODING);
+        $height = mb_substr($header, self::HEIGHT_OFFSET, self::DIMENSION_BYTES, self::BINARY_ENCODING);
+
+        return $width !== self::ZERO_DIMENSION && $height !== self::ZERO_DIMENSION;
+    }
+}
diff --git a/config/embeds.php b/config/embeds.php
index ee6564a40..bbc3b3d9d 100644
--- a/config/embeds.php
+++ b/config/embeds.php
@@ -18,6 +18,7 @@
 
     'enabled' => (bool) env('EMBEDS_ENABLED', true),
 
+    // "gif" selects verified external GIFs; the other keys select providers below.
     'only' => array_values(array_filter(array_map(trim(...), explode(',', (string) env('EMBEDS_PROVIDERS', ''))))),
 
     'providers' => [
diff --git a/database/migrations/2026_10_20_120000_add_gif_url_to_link_previews_table.php b/database/migrations/2026_10_20_120000_add_gif_url_to_link_previews_table.php
new file mode 100644
index 000000000..d730d21d9
--- /dev/null
+++ b/database/migrations/2026_10_20_120000_add_gif_url_to_link_previews_table.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('link_previews', function (Blueprint $table): void {
+            $table->string('gif_url', 2048)->nullable();
+        });
+    }
+};
diff --git a/tests/Feature/Controllers/Api/CommitControllerTest.php b/tests/Feature/Controllers/Api/CommitControllerTest.php
index 406f88ccb..125ba48b9 100644
--- a/tests/Feature/Controllers/Api/CommitControllerTest.php
+++ b/tests/Feature/Controllers/Api/CommitControllerTest.php
@@ -125,6 +125,26 @@
         ]);
 });
 
+it('includes verified external GIF metadata in the public API', function (): void {
+    $preview = LinkPreview::factory()->fetched()->create([
+        'url' => 'https://example.com/cat.gif',
+        'gif_url' => 'https://cdn.example.com/cat.gif',
+    ]);
+    $commit = Commit::factory()->create(['link_preview_id' => $preview->id]);
+
+    $this->getJson(route('api-commit.show', $commit))
+        ->assertOk()
+        ->assertJsonMissingPath('data.link_preview.gif_url')
+        ->assertJsonPath('data.link_preview.embed', [
+            'provider' => 'GIF',
+            'kind' => 'gif',
+            'src' => 'https://cdn.example.com/cat.gif',
+            'aspect_ratio' => '1 / 1',
+            'height' => null,
+            'poster' => null,
+        ]);
+});
+
 it('includes the images of the commit in order', function (): void {
     $commit = Commit::factory()->create();
     $second = CommitImage::factory()->for($commit)->create(['position' => 1, 'width' => 640, 'height' => 480]);
diff --git a/tests/Unit/Actions/UpdateLinkPreviewTest.php b/tests/Unit/Actions/UpdateLinkPreviewTest.php
index 21b9f2a90..00fb4efba 100644
--- a/tests/Unit/Actions/UpdateLinkPreviewTest.php
+++ b/tests/Unit/Actions/UpdateLinkPreviewTest.php
@@ -38,6 +38,107 @@ public function resolve(string $host): array
     });
 });
 
+it('verifies external GIFs from a small header without storing their bytes', function (string $signature): void {
+    $options = [];
+    Http::fake(function (Request $request, array $sent) use (&$options, $signature): PromiseInterface {
+        $options = $sent;
+
+        return Http::response($signature."\x01\x00\x01\x00\x80\x00\x00", 206, ['Content-Type' => 'IMAGE/GIF; charset=binary']);
+    });
+
+    $preview = unfurl('https://example.com/cat.GIF?token=keep');
+
+    expect($preview->gif_url)->toBe('https://example.com/cat.GIF?token=keep')
+        ->and($preview->image_url)->toBeNull()
+        ->and($preview->fetched_at)->not->toBeNull()
+        ->and($options['sink'])->toBeInstanceOf(LimitedResponseBody::class)
+        ->and($options['sink']->write(str_repeat('x', 33)))->toBe(32)
+        ->and($options['sink']->getSize())->toBe(32);
+
+    Http::assertSent(fn (Request $request): bool => $request->header('Range') === ['bytes=0-31']
+        && $request->header('Accept') === ['image/gif']);
+})->with(['GIF87a', 'GIF89a']);
+
+it('reads GIF dimensions as bytes rather than UTF-8 text', function (): void {
+    Http::fake(['https://example.com/cat.gif' => Http::response("GIF89a\xc2\x80\x01\x00\x80\x00\x00", 206, ['Content-Type' => 'image/gif'])]);
+
+    expect(unfurl('https://example.com/cat.gif')->gif_url)->toBe('https://example.com/cat.gif');
+});
+
+it('does not trust a GIF extension or a content type without a valid header', function (string $body, string $contentType): void {
+    Http::fake(['https://example.com/*' => Http::response($body, 200, ['Content-Type' => $contentType])]);
+
+    expect(unfurl('https://example.com/cat.gif')->gif_url)->toBeNull();
+})->with([
+    'html' => ['<title>A page</title>', 'text/html'],
+    'spoofed type' => ['<script>alert(1)</script>', 'image/gif'],
+    'wrong type' => ["GIF89a\x01\x00\x01\x00\x80\x00\x00", 'image/png'],
+    'truncated' => ['GIF89a', 'image/gif'],
+    'wrong signature' => ["GIF90a\x01\x00\x01\x00\x80\x00\x00", 'image/gif'],
+    'zero width' => ["GIF89a\x00\x00\x01\x00\x80\x00\x00", 'image/gif'],
+    'zero height' => ["GIF89a\x01\x00\x00\x00\x80\x00\x00", 'image/gif'],
+    'zero height with wide canvas' => ["GIF89a\x00\x01\x00\x00\x80\x00\x00", 'image/gif'],
+    'incomplete screen descriptor' => ["GIF89a\x01\x00\x01\x00\x80\x00", 'image/gif'],
+]);
+
+it('keeps only the final public HTTPS GIF URL after redirects', function (): void {
+    Http::fake([
+        'https://example.com/cat.gif' => Http::response(status: 302, headers: ['Location' => 'https://www.example.com/media?id=cat']),
+        'https://www.example.com/media?id=cat' => Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 200, ['Content-Type' => 'image/gif']),
+    ]);
+
+    $preview = unfurl('https://example.com/cat.gif');
+
+    expect($preview->url)->toBe('https://example.com/cat.gif')
+        ->and($preview->gif_url)->toBe('https://www.example.com/media?id=cat');
+    Http::assertSentCount(2);
+});
+
+it('does not follow GIF redirects to unsafe destinations', function (string $destination): void {
+    Http::fake(['https://example.com/cat.gif' => Http::response(status: 302, headers: ['Location' => $destination])]);
+
+    expect(unfurl('https://example.com/cat.gif')->gif_url)->toBeNull();
+    Http::assertSentCount(1);
+})->with([
+    'downgrade' => 'http://www.example.com/cat.gif',
+    'private address' => 'https://10.0.0.1/cat.gif',
+    'private DNS' => 'https://internal.example.com/cat.gif',
+    'mixed DNS' => 'https://mixed.example.com/cat.gif',
+    'credentials' => 'https://user:secret@www.example.com/cat.gif',
+    'port' => 'https://www.example.com:8443/cat.gif',
+]);
+
+it('does not embed HTTP GIFs or treat a query string as a GIF path', function (string $url): void {
+    Http::fake(['*' => Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 200, ['Content-Type' => 'image/gif'])]);
+
+    expect(unfurl($url)->gif_url)->toBeNull();
+})->with([
+    'HTTP' => 'http://example.com/cat.gif',
+    'query' => 'https://example.com/page?image=cat.gif',
+]);
+
+it('does not keep oversized redirected GIF URLs', function (): void {
+    $destination = 'https://www.example.com/'.str_repeat('x', 2048);
+    Http::fake([
+        'https://example.com/cat.gif' => Http::response(status: 302, headers: ['Location' => $destination]),
+        $destination => Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 200, ['Content-Type' => 'image/gif']),
+    ]);
+
+    expect(unfurl('https://example.com/cat.gif')->gif_url)->toBeNull();
+});
+
+it('clears a previously verified GIF when refetching fails permanently', function (): void {
+    Http::fake(['https://example.com/cat.gif' => Http::response(status: 404)]);
+    $preview = LinkPreview::factory()->create([
+        'url' => 'https://example.com/cat.gif',
+        'gif_url' => 'https://example.com/old.gif',
+    ]);
+
+    resolve(UpdateLinkPreview::class)->handle($preview);
+
+    expect($preview->refresh()->gif_url)->toBeNull();
+});
+
 function unfurl(string $url): LinkPreview
 {
     $linkPreview = LinkPreview::factory()->create(['url' => $url]);
@@ -450,7 +551,7 @@ public function resolve(string $host): array
 it('stops repeated redirect destinations before fetching them again', function (array $responses, int $requests): void {
     Http::fake($responses);
 
-    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    expect(unfurl('https://example.com/start.gif')->gif_url)->toBeNull();
     Http::assertSentCount($requests);
 })->with([
     'self loop' => [fn (): array => [
@@ -468,7 +569,7 @@ public function resolve(string $host): array
 it('does not refetch redirects with a missing or invalid location', function (?string $location): void {
     Http::fake(['https://example.com/*' => Http::response(status: 302, headers: $location === null ? [] : ['Location' => $location])]);
 
-    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    expect(unfurl('https://example.com/start.gif')->gif_url)->toBeNull();
     Http::assertSentCount(1);
 })->with([null, '', '   ', 'https://invalid host/cat.gif']);
 
@@ -488,7 +589,7 @@ public function resolve(string $host): array
         return Http::response(status: 302, headers: ['Location' => '/hop-'.count($timeouts).'.gif']);
     });
 
-    expect(unfurl('https://example.com/start.gif')->title)->toBeNull()
+    expect(unfurl('https://example.com/start.gif')->gif_url)->toBeNull()
         ->and($timeouts)->toBe([5.0, 3.0, 1.0])
         ->and($connectTimeouts)->toBe([3, 3.0, 1.0]);
     Http::assertSentCount(3);
@@ -502,7 +603,7 @@ public function resolve(string $host): array
     }));
     Http::fake();
 
-    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    expect(unfurl('https://example.com/start.gif')->gif_url)->toBeNull();
     Http::assertNothingSent();
 });
 
@@ -518,10 +619,21 @@ public function resolve(string $host): array
     });
     Http::fake(['https://example.com/start.gif' => Http::response(status: 302, headers: ['Location' => '/next.gif'])]);
 
-    expect(unfurl('https://example.com/start.gif')->title)->toBeNull();
+    expect(unfurl('https://example.com/start.gif')->gif_url)->toBeNull();
     Http::assertSentCount(1);
 });
 
+it('accepts only final GIF URLs within the storage length limit', function (int $length, bool $valid): void {
+    $base = 'https://www.example.com/';
+    $destination = $base.str_repeat('x', $length - mb_strlen($base));
+    Http::fake([
+        'https://example.com/cat.gif' => Http::response(status: 302, headers: ['Location' => $destination]),
+        $destination => Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 200, ['Content-Type' => 'image/gif']),
+    ]);
+
+    expect(unfurl('https://example.com/cat.gif')->gif_url)->toBe($valid ? $destination : null);
+})->with([[2048, true], [2049, false]]);
+
 it('pins the explicit port carried by a prepared request', function (): void {
     $options = [];
     Http::fake(function (Request $request, array $sent) use (&$options): PromiseInterface {
diff --git a/tests/Unit/Models/LinkPreviewTest.php b/tests/Unit/Models/LinkPreviewTest.php
index 83447671b..fc5b061e2 100644
--- a/tests/Unit/Models/LinkPreviewTest.php
+++ b/tests/Unit/Models/LinkPreviewTest.php
@@ -41,6 +41,20 @@
     expect($linkPreview->url_hash)->toBe(hash('sha256', 'https://example.com'));
 });
 
+it('serializes a verified external GIF without exposing its storage field', function (): void {
+    $preview = LinkPreview::factory()->fetched()->create([
+        'url' => 'https://example.com/cat.gif',
+        'gif_url' => 'https://cdn.example.com/cat.gif',
+    ])->refresh();
+
+    expect($preview->gif_url)->toBe('https://cdn.example.com/cat.gif')
+        ->and($preview->toArray())->not->toHaveKey('gif_url')
+        ->and($preview->toArray()['embed'])->toMatchArray([
+            'kind' => 'gif',
+            'src' => 'https://cdn.example.com/cat.gif',
+        ]);
+});
+
 it('casts the fetched at timestamp', function (): void {
     $linkPreview = LinkPreview::factory()->fetched()->create()->refresh();
 
diff --git a/tests/Unit/Services/EmbedsTest.php b/tests/Unit/Services/EmbedsTest.php
index 02386da8c..c428faa66 100644
--- a/tests/Unit/Services/EmbedsTest.php
+++ b/tests/Unit/Services/EmbedsTest.php
@@ -9,6 +9,36 @@
 use App\Services\Embeds;
 use Uri\WhatWg\Url;
 
+it('only embeds direct GIF URLs after the unfurler has verified them', function (): void {
+    expect(resolve(Embeds::class)->for('https://example.com/cat.gif'))->toBeNull()
+        ->and(resolve(Embeds::class)->for('https://example.com/cat.gif', 'https://cdn.example.com/cat.gif')?->toArray())->toBe([
+            'provider' => 'GIF',
+            'kind' => 'gif',
+            'src' => 'https://cdn.example.com/cat.gif',
+            'aspect_ratio' => '1 / 1',
+            'height' => null,
+            'poster' => null,
+        ]);
+});
+
+it('honors the GIF selectors independently', function (): void {
+    $embeds = resolve(Embeds::class);
+    config(['embeds.only' => ['gif']]);
+
+    expect($embeds->for('https://giphy.com/gifs/cat-JIX9t2j0ZTN9S'))->toBeNull()
+        ->and($embeds->for('https://example.com/cat.gif', 'https://example.com/cat.gif')?->provider)->toBe('GIF');
+
+    config(['embeds.only' => ['giphy']]);
+
+    expect($embeds->for('https://giphy.com/gifs/cat-JIX9t2j0ZTN9S')?->provider)->toBe('GIPHY')
+        ->and($embeds->for('https://example.com/cat.gif', 'https://example.com/cat.gif'))->toBeNull();
+
+    config(['embeds.enabled' => false]);
+
+    expect($embeds->for('https://giphy.com/gifs/cat-JIX9t2j0ZTN9S'))->toBeNull()
+        ->and($embeds->for('https://example.com/cat.gif', 'https://example.com/cat.gif'))->toBeNull();
+});
+
 it('embeds links to a provider', function (): void {
     expect(resolve(Embeds::class)->for('https://www.youtube.com/watch?v=dQw4w9WgXcQ')?->toArray())->toBe([
         'provider' => 'YouTube',

From 5e4b2f8d13709a75bf1bba903604b54abd5e0eaa Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:36 -0400
Subject: [PATCH 06/25] feat: define safe GIF playback and autoplay policy

---
 resources/js/lib/gifs.ts       |  72 ++++++++++++++++++++++
 tests/Unit/GifPlayback.test.ts | 107 +++++++++++++++++++++++++++++++++
 2 files changed, 179 insertions(+)
 create mode 100644 resources/js/lib/gifs.ts
 create mode 100644 tests/Unit/GifPlayback.test.ts

diff --git a/resources/js/lib/gifs.ts b/resources/js/lib/gifs.ts
new file mode 100644
index 000000000..bb4fca371
--- /dev/null
+++ b/resources/js/lib/gifs.ts
@@ -0,0 +1,72 @@
+const GIF_AUTOPLAY_HOSTS = new Set(['media.giphy.com']);
+
+function parseHttpsUrl(value: string): URL | null {
+    try {
+        const url = new URL(value);
+
+        if (
+            url.protocol !== 'https:' ||
+            url.username !== '' ||
+            url.password !== '' ||
+            url.port !== ''
+        ) {
+            return null;
+        }
+
+        return url;
+    } catch {
+        return null;
+    }
+}
+
+export function isGifUrl(value: string): boolean {
+    return (
+        parseHttpsUrl(value)?.pathname.toLowerCase().endsWith('.gif') ?? false
+    );
+}
+
+export function canAutoplayGif(value: string): boolean {
+    const url = parseHttpsUrl(value);
+
+    return url !== null && GIF_AUTOPLAY_HOSTS.has(url.hostname);
+}
+
+export const GIF_PLAYBACK_MODE = {
+    AUTOMATIC: 'auto',
+    PLAYING: 'play',
+    STOPPED: 'stop',
+} as const;
+
+export type GifPlayback =
+    (typeof GIF_PLAYBACK_MODE)[keyof typeof GIF_PLAYBACK_MODE];
+
+export function isGifPlaying({
+    source,
+    playback,
+    isVisible,
+    reducedMotion,
+    isStatic,
+    hasFailed,
+}: {
+    source: string;
+    playback: GifPlayback;
+    isVisible: boolean;
+    reducedMotion: boolean;
+    isStatic: boolean;
+    hasFailed: boolean;
+}): boolean {
+    if (
+        isStatic ||
+        hasFailed ||
+        !isVisible ||
+        playback === GIF_PLAYBACK_MODE.STOPPED
+    ) {
+        return false;
+    }
+
+    if (playback === GIF_PLAYBACK_MODE.PLAYING) {
+        return true;
+    }
+
+    return !reducedMotion && canAutoplayGif(source);
+}
diff --git a/tests/Unit/GifPlayback.test.ts b/tests/Unit/GifPlayback.test.ts
new file mode 100644
index 000000000..f29f1d439
--- /dev/null
+++ b/tests/Unit/GifPlayback.test.ts
@@ -0,0 +1,107 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { canAutoplayGif, isGifPlaying, isGifUrl } from '../../resources/js/lib/gifs.ts';
+
+const validGifUrls = [
+    'https://example.com/animation.gif',
+    'https://example.com/animation.GIF?token=abc#frame',
+    'https://media2.giphy.com/media/cat/giphy.gif',
+    'https://example.com:443/cat.gif',
+];
+
+for (const url of validGifUrls) {
+    void test(`recognizes a direct HTTPS GIF link: ${url}`, () => {
+        assert.equal(isGifUrl(url), true);
+    });
+}
+
+const invalidGifUrls = [
+    'not a URL',
+    'http://example.com/cat.gif',
+    'data:image/gif;base64,R0lGODlh',
+    'javascript:alert(1)',
+    'https://example.com/page?image=cat.gif',
+    'https://example.com/cat.gif/page',
+    'https://example.com/cat.gif.html',
+    'https://user:secret@example.com/cat.gif',
+    'https://user@example.com/cat.gif',
+    'https://:secret@example.com/cat.gif',
+    'https://example.com:8443/cat.gif',
+];
+
+for (const url of invalidGifUrls) {
+    void test(`does not treat an unsupported link as a GIF: ${url}`, () => {
+        assert.equal(isGifUrl(url), false);
+    });
+}
+
+const playback = {
+    source: 'https://media.giphy.com/media/cat/giphy.gif',
+    playback: 'auto' as const,
+    isVisible: true,
+    reducedMotion: false,
+    isStatic: false,
+    hasFailed: false,
+};
+
+void test('autoplays visible GIFs and suspends them outside the viewport', () => {
+    assert.equal(isGifPlaying(playback), true);
+    assert.equal(isGifPlaying({ ...playback, isVisible: false }), false);
+});
+
+void test('reduced motion requires an explicit Play action', () => {
+    assert.equal(isGifPlaying({ ...playback, reducedMotion: true }), false);
+    assert.equal(
+        isGifPlaying({ ...playback, reducedMotion: true, playback: 'play' }),
+        true,
+    );
+});
+
+void test('Stop survives leaving and reentering the viewport', () => {
+    assert.equal(isGifPlaying({ ...playback, playback: 'stop' }), false);
+    assert.equal(
+        isGifPlaying({ ...playback, playback: 'stop', isVisible: false }),
+        false,
+    );
+    assert.equal(isGifPlaying({ ...playback, playback: 'stop' }), false);
+    assert.equal(isGifPlaying({ ...playback, playback: 'play' }), true);
+});
+
+void test('static cards and failed GIFs never animate, even after Play', () => {
+    assert.equal(isGifPlaying({ ...playback, isStatic: true }), false);
+    assert.equal(
+        isGifPlaying({ ...playback, playback: 'play', isStatic: true }),
+        false,
+    );
+    assert.equal(isGifPlaying({ ...playback, hasFailed: true }), false);
+    assert.equal(
+        isGifPlaying({ ...playback, playback: 'play', hasFailed: true }),
+        false,
+    );
+});
+
+void test('only canonical Giphy media can autoplay', () => {
+    assert.equal(canAutoplayGif('https://media.giphy.com/media/cat/giphy.gif'), true);
+    for (const source of [
+        'https://example.com/cat.gif',
+        'https://media.giphy.com.attacker.example/cat.gif',
+        'https://attacker.giphy.com/cat.gif',
+        'http://media.giphy.com/media/cat/giphy.gif',
+        'https://user:secret@media.giphy.com/media/cat/giphy.gif',
+        'https://user@media.giphy.com/media/cat/giphy.gif',
+        'https://:secret@media.giphy.com/media/cat/giphy.gif',
+        'https://media.giphy.com:8443/media/cat/giphy.gif',
+        'not a URL',
+    ]) {
+        assert.equal(canAutoplayGif(source), false);
+    }
+});
+
+void test('arbitrary GIF hosts require Play and Stop still takes precedence', () => {
+    const external = { ...playback, source: 'https://example.com/cat.gif' };
+    assert.equal(isGifPlaying(external), false);
+    assert.equal(isGifPlaying({ ...external, playback: 'play' }), true);
+    assert.equal(isGifPlaying({ ...external, playback: 'stop' }), false);
+    assert.equal(isGifPlaying({ ...external, playback: 'play', isVisible: false }), false);
+});

From 2ba852c3108888e6831d374dbd5a4053b0a9f1ec Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:39 -0400
Subject: [PATCH 07/25] feat: render external GIFs with accessible playback
 controls

---
 resources/js/components/gif-embed.tsx    | 176 +++++++++++++++++++++++
 resources/js/components/link-embed.tsx   |  13 ++
 resources/js/components/link-preview.tsx |   8 ++
 resources/js/hooks/use-gif-playback.ts   |  80 +++++++++++
 resources/js/types/commit.ts             |   2 +-
 tests/Unit/GifEmbed.test.tsx             | 102 +++++++++++++
 tests/draft-images.config.ts             |   1 +
 tests/tsconfig.json                      |   5 +-
 8 files changed, 385 insertions(+), 2 deletions(-)
 create mode 100644 resources/js/components/gif-embed.tsx
 create mode 100644 resources/js/hooks/use-gif-playback.ts
 create mode 100644 tests/Unit/GifEmbed.test.tsx

diff --git a/resources/js/components/gif-embed.tsx b/resources/js/components/gif-embed.tsx
new file mode 100644
index 000000000..41184bba2
--- /dev/null
+++ b/resources/js/components/gif-embed.tsx
@@ -0,0 +1,176 @@
+import { Play, Square } from 'lucide-react';
+import { useRef, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { useGifPlayback } from '@/hooks/use-gif-playback';
+import { canAutoplayGif } from '@/lib/gifs';
+import { hostname } from '@/lib/urls';
+import type { Embed, LinkPreview } from '@/types';
+
+type GifEmbedProps = {
+    preview: LinkPreview;
+    embed?: Embed | null;
+    isStatic?: boolean;
+};
+
+type GifPlaybackState = ReturnType<typeof useGifPlayback>;
+
+type GifMediaProps = {
+    preview: LinkPreview;
+    embed: Embed | null;
+    playback: GifPlaybackState;
+};
+
+export function GifEmbed({
+    preview,
+    embed = null,
+    isStatic = false,
+}: GifEmbedProps) {
+    const container = useRef<HTMLDivElement>(null);
+    const playback = useGifPlayback({ embed, isStatic, container });
+
+    return (
+        <div
+            ref={container}
+            onClick={isStatic ? undefined : (event) => event.stopPropagation()}
+            className="mt-3 overflow-hidden rounded-lg border"
+            data-test="gif-embed"
+            data-provider={embed?.provider ?? 'GIF'}
+        >
+            <div className="relative mx-auto aspect-square w-full max-w-80 overflow-hidden bg-muted">
+                <GifMedia preview={preview} embed={embed} playback={playback} />
+                <GifPlaybackButton
+                    embed={embed}
+                    playback={playback}
+                    isStatic={isStatic}
+                />
+            </div>
+            <GifSource preview={preview} embed={embed} isStatic={isStatic} />
+        </div>
+    );
+}
+
+function GifMedia({ preview, embed, playback }: GifMediaProps) {
+    const [posterFailed, setPosterFailed] = useState(false);
+
+    if (playback.isPlaying && embed) {
+        return (
+            <img
+                src={embed.src}
+                alt={preview.title ?? 'Animated GIF'}
+                referrerPolicy="no-referrer"
+                onError={playback.onError}
+                className="absolute inset-0 size-full object-contain"
+                data-test="gif-animation"
+            />
+        );
+    }
+
+    if (
+        embed?.poster &&
+        canAutoplayGif(embed.poster) &&
+        !posterFailed &&
+        !playback.hasFailed
+    ) {
+        return (
+            <img
+                src={embed.poster}
+                alt=""
+                loading="lazy"
+                referrerPolicy="no-referrer"
+                onError={() => setPosterFailed(true)}
+                className="absolute inset-0 size-full object-contain"
+                data-test="gif-poster"
+            />
+        );
+    }
+
+    return <GifStatus preview={preview} embed={embed} playback={playback} />;
+}
+
+function GifStatus({ preview, embed, playback }: GifMediaProps) {
+    return (
+        <span
+            className="absolute inset-0 flex items-center justify-center px-4 text-center text-sm text-muted-foreground"
+            role={playback.hasFailed ? 'status' : undefined}
+        >
+            {playback.hasFailed && 'GIF could not load'}
+            {!playback.hasFailed &&
+                embed &&
+                (canAutoplayGif(embed.src)
+                    ? 'GIF'
+                    : 'External GIF — press Play to load')}
+            {!playback.hasFailed &&
+                !embed &&
+                preview.is_pending &&
+                'Loading GIF…'}
+            {!playback.hasFailed &&
+                !embed &&
+                !preview.is_pending &&
+                'GIF preview unavailable'}
+        </span>
+    );
+}
+
+function GifPlaybackButton({
+    embed,
+    playback,
+    isStatic,
+}: {
+    embed: Embed | null;
+    playback: GifPlaybackState;
+    isStatic: boolean;
+}) {
+    if (isStatic || !embed || playback.hasFailed) {
+        return null;
+    }
+
+    const Icon = playback.isPlaying ? Square : Play;
+    const label = playback.isPlaying ? 'Stop' : 'Play';
+
+    return (
+        <Button
+            type="button"
+            variant="secondary"
+            size="sm"
+            onClick={playback.onToggle}
+            aria-label={`${label} GIF`}
+            className="absolute right-3 bottom-3 min-w-20 cursor-pointer bg-black/75 text-white hover:bg-black/85"
+            data-test="gif-playback"
+        >
+            <Icon className="size-4 fill-current" />
+            {label}
+        </Button>
+    );
+}
+
+function GifSource({ preview, embed, isStatic }: GifEmbedProps) {
+    const details = <GifDetails preview={preview} embed={embed} />;
+
+    if (isStatic) {
+        return <div className="border-t px-3 py-2">{details}</div>;
+    }
+
+    return (
+        <a
+            href={preview.url}
+            target="_blank"
+            rel="noopener noreferrer nofollow ugc"
+            className="block border-t px-3 py-2 transition-colors hover:bg-accent focus-visible:bg-accent"
+        >
+            {details}
+        </a>
+    );
+}
+
+function GifDetails({ preview, embed }: GifEmbedProps) {
+    return (
+        <>
+            <span className="block truncate font-mono text-xs text-muted-foreground">
+                {embed?.provider ?? hostname(preview.url)}
+            </span>
+            <span className="block truncate text-sm leading-snug font-medium">
+                {preview.title ?? 'GIF'}
+            </span>
+        </>
+    );
+}
diff --git a/resources/js/components/link-embed.tsx b/resources/js/components/link-embed.tsx
index 38b34eba3..942e34bfb 100644
--- a/resources/js/components/link-embed.tsx
+++ b/resources/js/components/link-embed.tsx
@@ -1,6 +1,7 @@
 import { AudioLines, Code2, Play } from 'lucide-react';
 import type { CSSProperties, ReactNode } from 'react';
 import { useState } from 'react';
+import { GifEmbed } from '@/components/gif-embed';
 import { cn } from '@/lib/utils';
 import type { Embed, LinkPreview } from '@/types';
 
@@ -110,6 +111,18 @@ export function LinkEmbed({
     isStatic?: boolean;
 }) {
     const [isPlaying, setIsPlaying] = useState(false);
+
+    if (embed.kind === 'gif') {
+        return (
+            <GifEmbed
+                key={preview.url}
+                preview={preview}
+                embed={embed}
+                isStatic={isStatic}
+            />
+        );
+    }
+
     const Icon = icons[embed.kind];
     const label = `Play ${preview.title ?? preview.url} from ${embed.provider}`;
     const isVideo = embed.aspect_ratio !== null;
diff --git a/resources/js/components/link-preview.tsx b/resources/js/components/link-preview.tsx
index 513987a24..700848f6d 100644
--- a/resources/js/components/link-preview.tsx
+++ b/resources/js/components/link-preview.tsx
@@ -1,6 +1,8 @@
 import { useEffect, useState } from 'react';
+import { GifEmbed } from '@/components/gif-embed';
 import { LinkEmbed } from '@/components/link-embed';
 import { Skeleton } from '@/components/ui/skeleton';
+import { isGifUrl } from '@/lib/gifs';
 import { hostname } from '@/lib/urls';
 import type { LinkPreview as LinkPreviewData } from '@/types';
 
@@ -129,6 +131,12 @@ export function LinkPreview({
         );
     }
 
+    if (isGifUrl(preview.url)) {
+        return (
+            <GifEmbed key={preview.url} preview={preview} isStatic={isStatic} />
+        );
+    }
+
     if (isWaiting) {
         return <LinkPreviewSkeleton />;
     }
diff --git a/resources/js/hooks/use-gif-playback.ts b/resources/js/hooks/use-gif-playback.ts
new file mode 100644
index 000000000..4be38359f
--- /dev/null
+++ b/resources/js/hooks/use-gif-playback.ts
@@ -0,0 +1,80 @@
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+import { useMediaQuery } from '@/hooks/use-media-query';
+import { GIF_PLAYBACK_MODE, isGifPlaying, type GifPlayback } from '@/lib/gifs';
+import type { Embed } from '@/types';
+
+const MIN_VISIBLE_RATIO = 0.1;
+
+function useGifVisibility(
+    container: RefObject<HTMLDivElement | null>,
+): boolean {
+    const [isVisible, setIsVisible] = useState(false);
+
+    useEffect(() => {
+        const element = container.current;
+
+        if (!element) {
+            return;
+        }
+
+        if (typeof IntersectionObserver === 'undefined') {
+            const frame = requestAnimationFrame(() => setIsVisible(true));
+
+            return () => cancelAnimationFrame(frame);
+        }
+
+        const observer = new IntersectionObserver(
+            ([entry]) =>
+                setIsVisible(
+                    entry.isIntersecting &&
+                        entry.intersectionRatio >= MIN_VISIBLE_RATIO,
+                ),
+            { threshold: MIN_VISIBLE_RATIO },
+        );
+        observer.observe(element);
+
+        return () => observer.disconnect();
+    }, [container]);
+
+    return isVisible;
+}
+
+export function useGifPlayback({
+    embed,
+    isStatic,
+    container,
+}: {
+    embed: Embed | null;
+    isStatic: boolean;
+    container: RefObject<HTMLDivElement | null>;
+}) {
+    const isVisible = useGifVisibility(container);
+    const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+    const [playback, setPlayback] = useState<GifPlayback>(
+        GIF_PLAYBACK_MODE.AUTOMATIC,
+    );
+    const [hasFailed, setHasFailed] = useState(false);
+    const isPlaying =
+        embed !== null &&
+        isGifPlaying({
+            source: embed.src,
+            playback,
+            isVisible,
+            reducedMotion,
+            isStatic,
+            hasFailed,
+        });
+
+    return {
+        isPlaying,
+        hasFailed,
+        onError: () => setHasFailed(true),
+        onToggle: () =>
+            setPlayback(
+                isPlaying
+                    ? GIF_PLAYBACK_MODE.STOPPED
+                    : GIF_PLAYBACK_MODE.PLAYING,
+            ),
+    };
+}
diff --git a/resources/js/types/commit.ts b/resources/js/types/commit.ts
index 82d06dae1..e83515c41 100644
--- a/resources/js/types/commit.ts
+++ b/resources/js/types/commit.ts
@@ -2,7 +2,7 @@ import type { User } from '@/types/auth';
 
 export type CommitStatus = 'pending' | 'approved' | 'rejected';
 
-export type EmbedKind = 'video' | 'audio' | 'code';
+export type EmbedKind = 'video' | 'audio' | 'code' | 'gif';
 
 export type Embed = {
     provider: string;
diff --git a/tests/Unit/GifEmbed.test.tsx b/tests/Unit/GifEmbed.test.tsx
new file mode 100644
index 000000000..a5c900d5d
--- /dev/null
+++ b/tests/Unit/GifEmbed.test.tsx
@@ -0,0 +1,102 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { test } from 'vite-plus/test';
+import { GifEmbed } from '../../resources/js/components/gif-embed';
+import { LinkEmbed } from '../../resources/js/components/link-embed';
+import type { Embed, LinkPreview } from '../../resources/js/types/commit';
+
+const preview: LinkPreview = {
+    url: 'https://example.com/cat.gif',
+    title: null,
+    description: null,
+    image_url: 'https://example.com/untrusted-thumbnail.gif',
+    site_name: null,
+    is_pending: false,
+};
+
+const embed: Embed = {
+    provider: 'GIF',
+    kind: 'gif',
+    src: 'https://example.com/cat.gif',
+    aspect_ratio: '1 / 1',
+    height: null,
+    poster: null,
+};
+
+test('waits until hydration and visibility before requesting animated content', () => {
+    const html = renderToStaticMarkup(
+        <LinkEmbed preview={preview} embed={embed} />,
+    );
+
+    assert.ok(html.includes('data-test="gif-embed"'));
+    assert.ok(html.includes('aspect-square'));
+    assert.ok(html.includes('aria-label="Play GIF"'));
+    assert.ok(html.includes('href="https://example.com/cat.gif"'));
+    assert.ok(!html.includes('<iframe'));
+    assert.ok(!html.includes('<img'));
+    assert.ok(!html.includes('untrusted-thumbnail'));
+});
+
+test('pending and verified cards reserve the same image box', () => {
+    const pending = renderToStaticMarkup(
+        <GifEmbed preview={{ ...preview, is_pending: true }} />,
+    );
+    const verified = renderToStaticMarkup(
+        <GifEmbed preview={preview} embed={embed} />,
+    );
+    const box = /class="[^"]*aspect-square[^"]*"/;
+
+    assert.equal(pending.match(box)?.[0], verified.match(box)?.[0]);
+    assert.ok(pending.includes('Loading GIF'));
+    assert.ok(!pending.includes('<img'));
+    assert.ok(!pending.includes('<button'));
+});
+
+test('an unverified GIF remains a source link without fetching the image', () => {
+    const html = renderToStaticMarkup(<GifEmbed preview={preview} />);
+
+    assert.ok(html.includes('GIF preview unavailable'));
+    assert.ok(html.includes('href="https://example.com/cat.gif"'));
+    assert.ok(!html.includes('<img'));
+    assert.ok(!html.includes('<button'));
+});
+
+test('static cards have no playback or navigation controls', () => {
+    const html = renderToStaticMarkup(
+        <GifEmbed preview={preview} embed={embed} isStatic />,
+    );
+
+    assert.ok(html.includes('aspect-square'));
+    assert.ok(!html.includes('<img'));
+    assert.ok(!html.includes('<button'));
+    assert.ok(!html.includes('<a '));
+});
+
+test('only the explicit static poster can load before playback', () => {
+    const html = renderToStaticMarkup(
+        <GifEmbed
+            preview={preview}
+            embed={{
+                ...embed,
+                poster: 'https://media.giphy.com/media/cat/giphy_s.gif',
+            }}
+        />,
+    );
+
+    assert.ok(html.includes('data-test="gif-poster"'));
+    assert.ok(html.includes('referrerPolicy="no-referrer"'));
+    assert.ok(!html.includes('data-test="gif-animation"'));
+    assert.ok(!html.includes('untrusted-thumbnail'));
+});
+
+test('arbitrary GIF hosts have no automatic thumbnail or image request', () => {
+    const html = renderToStaticMarkup(
+        <GifEmbed preview={preview} embed={{ ...embed, poster: 'https://example.com/poster.gif' }} />,
+    );
+
+    assert.ok(html.includes('aria-label="Play GIF"'));
+    assert.ok(html.includes('External GIF'));
+    assert.ok(!html.includes('<img'));
+    assert.ok(!html.includes('poster.gif'));
+});
diff --git a/tests/draft-images.config.ts b/tests/draft-images.config.ts
index 7bf447fa4..cc9995fd7 100644
--- a/tests/draft-images.config.ts
+++ b/tests/draft-images.config.ts
@@ -9,6 +9,7 @@ export default defineConfig({
     },
     test: {
         include: [
+            'tests/Unit/GifEmbed.test.tsx',
             'tests/Unit/CommitPhoto.test.tsx',
             'tests/Unit/CommitSize.test.tsx',
             'tests/Unit/ThreadHistory.test.tsx',
diff --git a/tests/tsconfig.json b/tests/tsconfig.json
index aecdaaa64..ab7c8f13b 100644
--- a/tests/tsconfig.json
+++ b/tests/tsconfig.json
@@ -1,7 +1,9 @@
 {
     "extends": "../tsconfig.json",
     "compilerOptions": {
-        "types": ["node"],
+        "types": [
+            "node"
+        ],
         "allowImportingTsExtensions": true
     },
     "include": [
@@ -14,6 +16,7 @@
         "Unit/ImageAttachments.test.tsx",
         "Unit/StagedRail.test.tsx",
         "Unit/UseNow.test.tsx",
+        "Unit/GifEmbed.test.tsx",
         "../resources/js/types/*.d.ts",
         "draft-images.config.ts"
     ]

From 24faa49a7a711d22b98e7851539508db4ea37751 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:41 -0400
Subject: [PATCH 08/25] test: automate GIF security mutation checks in CI

---
 .github/workflows/tests.yml          |   3 +
 composer.json                        |   6 +-
 package.json                         |   3 +-
 tests/Mutation/GifSecurity.test.ts   | 145 +++++++++++++++++++++++
 tests/Mutation/php-gif-mutations.ts  | 164 +++++++++++++++++++++++++++
 tests/Mutation/playback-mutations.ts |  81 +++++++++++++
 tests/tsconfig.json                  |   3 +-
 7 files changed, 401 insertions(+), 4 deletions(-)
 create mode 100644 tests/Mutation/GifSecurity.test.ts
 create mode 100644 tests/Mutation/php-gif-mutations.ts
 create mode 100644 tests/Mutation/playback-mutations.ts

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 4d2a1d9c1..4fe0759e4 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -146,5 +146,8 @@ jobs:
         if: steps.build-cache.outputs.cache-hit != 'true'
         run: bun run build
 
+      - name: GIF Security Mutations
+        run: composer test:mutations
+
       - name: Tests
         run: composer test:unit
diff --git a/composer.json b/composer.json
index c53117727..313cbce01 100644
--- a/composer.json
+++ b/composer.json
@@ -113,8 +113,10 @@
             "@test:lint",
             "@test:types",
             "@test:type-coverage",
-            "@test:unit"
-        ]
+            "@test:unit",
+            "@test:mutations"
+        ],
+        "test:mutations": "bun run test:mutations"
     },
     "extra": {
         "laravel": {
diff --git a/package.json b/package.json
index f45b0f962..93b8581de 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,8 @@
         "lint": "NODE_OPTIONS='--experimental-strip-types' vp fmt resources/ && NODE_OPTIONS='--experimental-strip-types' vp lint --fix",
         "test:lint": "NODE_OPTIONS='--experimental-strip-types' vp fmt --check resources/ && NODE_OPTIONS='--experimental-strip-types' vp lint",
         "test:types": "tsc --noEmit && tsc --noEmit --project tests/tsconfig.json",
-        "test:unit": "node --experimental-strip-types --test tests/Unit/*.test.ts"
+        "test:unit": "node --experimental-strip-types --test tests/Unit/*.test.ts",
+        "test:mutations": "node --experimental-strip-types --test tests/Mutation/*.test.ts"
     },
     "dependencies": {
         "@daypicker/react": "^10.0.2",
diff --git a/tests/Mutation/GifSecurity.test.ts b/tests/Mutation/GifSecurity.test.ts
new file mode 100644
index 000000000..464bae595
--- /dev/null
+++ b/tests/Mutation/GifSecurity.test.ts
@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import type { SpawnSyncReturns } from 'node:child_process';
+import {
+    mkdtempSync,
+    mkdirSync,
+    readFileSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { phpGifMutations } from './php-gif-mutations.ts';
+import type { GifMutation } from './php-gif-mutations.ts';
+import { playbackMutations } from './playback-mutations.ts';
+
+const root = fileURLToPath(new URL('../..', import.meta.url));
+const temporary = mkdtempSync(join(tmpdir(), 'devnull-gif-mutations-'));
+const mutationTarget = 'PEST_MUTATION_TESTING';
+const mutationSource = 'PEST_MUTATION_FILE';
+const timeoutMilliseconds = 60_000;
+const controls = new Set<string>();
+
+function runPhp(
+    mutation: GifMutation,
+    source: string,
+): SpawnSyncReturns<string> {
+    const modifiedFile = join(temporary, 'mutated.php');
+    writeFileSync(modifiedFile, source);
+
+    return spawnSync(
+        'php',
+        [
+            'vendor/bin/pest',
+            '--ci',
+            '--compact',
+            '--colors=never',
+            mutation.test,
+        ],
+        {
+            cwd: root,
+            encoding: 'utf8',
+            timeout: timeoutMilliseconds,
+            env: {
+                ...process.env,
+                [mutationTarget]: join(root, mutation.source),
+                [mutationSource]: modifiedFile,
+            },
+        },
+    );
+}
+
+function runPlayback(
+    mutation: GifMutation,
+    source: string,
+): SpawnSyncReturns<string> {
+    const modifiedFile = join(temporary, mutation.source);
+    const testFile = join(temporary, mutation.test);
+    mkdirSync(dirname(modifiedFile), { recursive: true });
+    mkdirSync(dirname(testFile), { recursive: true });
+    writeFileSync(join(temporary, 'package.json'), '{"type":"module"}');
+    writeFileSync(modifiedFile, source);
+    writeFileSync(testFile, readFileSync(join(root, mutation.test)));
+    const environment = { ...process.env };
+    delete environment.NODE_TEST_CONTEXT;
+
+    return spawnSync(
+        process.execPath,
+        ['--experimental-strip-types', '--test', testFile],
+        {
+            encoding: 'utf8',
+            timeout: timeoutMilliseconds,
+            env: environment,
+        },
+    );
+}
+
+function output(result: SpawnSyncReturns<string>): string {
+    assert.ifError(result.error);
+    assert.notEqual(result.status, null, 'Mutation process did not finish');
+
+    return result.stdout + result.stderr;
+}
+
+type Runner = (
+    mutation: GifMutation,
+    source: string,
+) => SpawnSyncReturns<string>;
+
+function verifyControl(
+    mutation: GifMutation,
+    source: string,
+    run: Runner,
+): void {
+    if (controls.has(mutation.source)) {
+        return;
+    }
+
+    const control = run(mutation, source);
+    const report = output(control);
+    assert.equal(control.status, 0, report);
+    assert.match(
+        report,
+        run === runPhp ? /Tests:\s+.*\bpassed\b/ : /\bpass [1-9]\d*/,
+        report,
+    );
+    controls.add(mutation.source);
+}
+
+function checkMutation(mutation: GifMutation): void {
+    const original = readFileSync(join(root, mutation.source), 'utf8');
+    const run = mutation.source.endsWith('.php') ? runPhp : runPlayback;
+    verifyControl(mutation, original, run);
+    assert.ok(
+        original.includes(mutation.before),
+        `Mutation no longer matches ${mutation.source}`,
+    );
+    const result = run(
+        mutation,
+        original.replace(mutation.before, mutation.after),
+    );
+    const report = output(result);
+    assert.notEqual(
+        result.status,
+        0,
+        `Mutation survived: ${mutation.name}\n${report}`,
+    );
+    assert.match(
+        report,
+        run === runPhp ? /Tests:\s+.*\bfailed\b/ : /ERR_ASSERTION/,
+        report,
+    );
+}
+
+await test('GIF security mutation gate', async (context) => {
+    context.after(() => rmSync(temporary, { recursive: true, force: true }));
+
+    for (const mutation of [...phpGifMutations, ...playbackMutations]) {
+        await context.test(`detects mutation: ${mutation.name}`, () =>
+            checkMutation(mutation),
+        );
+    }
+});
diff --git a/tests/Mutation/php-gif-mutations.ts b/tests/Mutation/php-gif-mutations.ts
new file mode 100644
index 000000000..b962485cb
--- /dev/null
+++ b/tests/Mutation/php-gif-mutations.ts
@@ -0,0 +1,164 @@
+export type GifMutation = {
+    name: string;
+    source: string;
+    test: string;
+    before: string;
+    after: string;
+};
+
+export const phpGifMutations: GifMutation[] = [
+    {
+        name: 'redirect limit cannot increase',
+        source: 'app/Actions/UpdateLinkPreview.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'MAX_REDIRECTS = 3',
+        after: 'MAX_REDIRECTS = 4',
+    },
+    {
+        name: 'redirect limit cannot decrease',
+        source: 'app/Actions/UpdateLinkPreview.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'MAX_REDIRECTS = 3',
+        after: 'MAX_REDIRECTS = 2',
+    },
+    {
+        name: 'redirect cycles stop before refetching',
+        source: 'app/Actions/UpdateLinkPreview.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'if (isset($visited[$source]))',
+        after: 'if (false)',
+    },
+    {
+        name: 'non-default ports are rejected',
+        source: 'app/Services/LinkPreviewAddress.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'if ($url->getPort() !== null)',
+        after: 'if (false)',
+    },
+    {
+        name: 'non-global addresses are rejected',
+        source: 'app/Services/LinkPreviewAddress.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'return filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE) !== false',
+        after: 'return true',
+    },
+    {
+        name: 'Symfony special-use subnets stay blocked',
+        source: 'app/Services/LinkPreviewAddress.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: '...IpUtils::PRIVATE_SUBNETS,',
+        after: '',
+    },
+    {
+        name: 'additional relay ranges stay blocked',
+        source: 'app/Services/LinkPreviewAddress.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: "'192.88.99.0/24',",
+        after: '',
+    },
+    {
+        name: 'all DNS answers must be public',
+        source: 'app/Services/LinkPreviewAddress.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'array_all($addresses, $this->isPublic(...))',
+        after: 'true',
+    },
+    {
+        name: 'response body is capped',
+        source: 'app/Services/LimitedResponseBody.php',
+        test: 'tests/Unit/Services/LimitedResponseBodyTest.php',
+        before: '$remaining = max(0, $this->maxBytes - $this->tell());',
+        after: '$remaining = PHP_INT_MAX;',
+    },
+    {
+        name: 'seeking cannot bypass the byte cap',
+        source: 'app/Services/LimitedResponseBody.php',
+        test: 'tests/Unit/Services/LimitedResponseBodyTest.php',
+        before: 'max(0, $this->maxBytes - $this->tell())',
+        after: 'max(-1, $this->maxBytes - $this->tell())',
+    },
+    {
+        name: 'overall deadline stays at five seconds',
+        source: 'app/Services/LinkPreviewBudget.php',
+        test: 'tests/Unit/Services/LinkPreviewBudgetTest.php',
+        before: 'TIMEOUT_SECONDS = 5',
+        after: 'TIMEOUT_SECONDS = 6',
+    },
+    {
+        name: 'remaining timeout never rounds upward',
+        source: 'app/Services/LinkPreviewBudget.php',
+        test: 'tests/Unit/Services/LinkPreviewBudgetTest.php',
+        before: 'floor(($deadline - $this->seconds())',
+        after: 'round(($deadline - $this->seconds())',
+    },
+    {
+        name: 'automatic HTTP redirects stay disabled',
+        source: 'app/Services/LinkPreviewHttpClient.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: '->withoutRedirecting()',
+        after: '->withOptions([RequestOptions::ALLOW_REDIRECTS => true])',
+    },
+    {
+        name: 'automatic decompression stays disabled',
+        source: 'app/Services/LinkPreviewHttpClient.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'RequestOptions::DECODE_CONTENT => false',
+        after: 'RequestOptions::DECODE_CONTENT => true',
+    },
+    {
+        name: 'requests pin the checked address',
+        source: 'app/Services/LinkPreviewHttpClient.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'CURLOPT_CONNECT_TO => [$connection]',
+        after: 'CURLOPT_CONNECT_TO => []',
+    },
+    {
+        name: 'content type is checked',
+        source: 'app/Services/GifLinks.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'if ($mediaType !== self::CONTENT_TYPE)',
+        after: 'if (false)',
+    },
+    {
+        name: 'both supported GIF signatures remain valid',
+        source: 'app/Services/GifLinks.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: "SIGNATURES = ['GIF87a', 'GIF89a']",
+        after: "SIGNATURES = ['GIF89a']",
+    },
+    {
+        name: 'truncated GIF descriptors are rejected',
+        source: 'app/Services/GifLinks.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'MIN_HEADER_BYTES = 13',
+        after: 'MIN_HEADER_BYTES = 12',
+    },
+    {
+        name: 'GIF dimensions must be nonzero',
+        source: 'app/Services/GifLinks.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'return $width !== self::ZERO_DIMENSION && $height !== self::ZERO_DIMENSION;',
+        after: 'return true;',
+    },
+    {
+        name: 'oversized URLs stay rejected',
+        source: 'app/Services/GifLinks.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'MAX_URL_LENGTH = 2048',
+        after: 'MAX_URL_LENGTH = 2049',
+    },
+    {
+        name: 'maximum-length URLs remain supported',
+        source: 'app/Services/GifLinks.php',
+        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        before: 'MAX_URL_LENGTH = 2048',
+        after: 'MAX_URL_LENGTH = 2047',
+    },
+    {
+        name: 'Giphy hosts cannot be spoofed',
+        source: 'app/Services/EmbedProviders/Giphy.php',
+        test: 'tests/Unit/Services/EmbedProviders/GiphyTest.php',
+        before: 'if (! in_array($url->getAsciiHost(), self::SUPPORTED_HOSTS, true))',
+        after: 'if (false)',
+    },
+];
diff --git a/tests/Mutation/playback-mutations.ts b/tests/Mutation/playback-mutations.ts
new file mode 100644
index 000000000..48ed82a62
--- /dev/null
+++ b/tests/Mutation/playback-mutations.ts
@@ -0,0 +1,81 @@
+import type { GifMutation } from './php-gif-mutations.ts';
+
+export const playbackMutations: GifMutation[] = [
+    {
+        name: 'autoplay arbitrary hosts',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: 'GIF_AUTOPLAY_HOSTS.has(url.hostname)',
+        after: 'true',
+    },
+    {
+        name: 'ignore reduced motion',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: '!reducedMotion && canAutoplayGif(source)',
+        after: 'canAutoplayGif(source)',
+    },
+    {
+        name: 'ignore visibility',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: '        !isVisible ||\n',
+        after: '',
+    },
+    {
+        name: 'ignore static cards',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: '        isStatic ||\n',
+        after: '',
+    },
+    {
+        name: 'ignore failed loads',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: '        hasFailed ||\n',
+        after: '',
+    },
+    {
+        name: 'ignore Stop',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: '        playback === GIF_PLAYBACK_MODE.STOPPED',
+        after: '        false',
+    },
+    {
+        name: 'deny explicit Play',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: 'playback === GIF_PLAYBACK_MODE.PLAYING',
+        after: 'false',
+    },
+    {
+        name: 'allow HTTP',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: "            url.protocol !== 'https:' ||\n",
+        after: '',
+    },
+    {
+        name: 'allow username',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: "            url.username !== '' ||\n",
+        after: '',
+    },
+    {
+        name: 'allow password',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: "            url.password !== '' ||\n",
+        after: '',
+    },
+    {
+        name: 'allow non-default port',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: "            url.password !== '' ||\n            url.port !== ''",
+        after: "            url.password !== ''",
+    },
+];
diff --git a/tests/tsconfig.json b/tests/tsconfig.json
index ab7c8f13b..d4fa9eb6e 100644
--- a/tests/tsconfig.json
+++ b/tests/tsconfig.json
@@ -18,6 +18,7 @@
         "Unit/UseNow.test.tsx",
         "Unit/GifEmbed.test.tsx",
         "../resources/js/types/*.d.ts",
-        "draft-images.config.ts"
+        "draft-images.config.ts",
+        "Mutation/**/*.ts"
     ]
 }

From 162ef7c96b9f40b4b4f88012975cfac48be16f68 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 13:55:44 -0400
Subject: [PATCH 09/25] docs: explain external GIF support and security limits

---
 KNOWLEDGE_BASE.md | 2 ++
 README.md         | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md
index af8ddb6a3..302f3047c 100644
--- a/KNOWLEDGE_BASE.md
+++ b/KNOWLEDGE_BASE.md
@@ -225,6 +225,8 @@ URLs and bare domains in commits and replies become clickable links. Long URLs a
 
 Supported links can also show click-to-play embedded players: YouTube, Vimeo, Loom, Twitch, Spotify, SoundCloud, Apple Music, Suno, CodePen, and asciinema. Only the link that gets the card can show a player, so choosing no card means no player. Embeds depend on server configuration and the linked URL being supported. Third-party player content loads only after you press play; those providers have their own privacy policies. This is embedding a link, not uploading a video or audio file to /dev/null.
 
+Giphy GIF share links and public HTTPS links ending in `.gif` can show animated GIFs in the selected link card, including in replies and remotes. They load from the external host and have **Play** and **Stop** controls. Only the canonical Giphy media host autoplays while visible; other hosts wait for **Play** before the browser requests the image. With reduced motion enabled they wait for **Play**; static preview cards do not animate. Direct GIFs must pass the link unfurler's public-address, redirect, content-type, and GIF-header checks first. It retains at most 32 response-body bytes for this check, stops redirect cycles and missing locations immediately, and shares one five-second HTTP budget across redirects. Synchronous DNS lookups cannot be interrupted by that budget. The original host still controls the browser's later response and file size. Failed previews keep a link to the source. There is no GIF search, API key, file upload, conversion, or hosted GIF storage. Administrators can enable only these embeds with `EMBEDS_PROVIDERS=giphy,gif`, or disable them with the existing embed controls. Previously fetched direct GIF links need refetching before they can animate; Giphy share links work without a backfill.
+
 Sources: [link rendering](resources/js/components/linkified-text.tsx), [link-card selection](app/Http/Requests/CreateCommitRequest.php), [embed configuration](config/embeds.php), [embedded player](resources/js/components/link-embed.tsx).
 
 ### Replies and threads
diff --git a/README.md b/README.md
index fcc948e5b..88315d9c6 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,14 @@ A link card for a video, song or pen becomes a player that loads when clicked. T
 | `apple_music` | albums, playlists and songs |
 | `codepen` | pens |
 | `asciinema` | recordings |
+| `giphy` | `giphy.com/gifs/{id-or-slug-id}` and `giphy.com/embed/{id}` |
+| `gif` | Public HTTPS links whose path ends in `.gif` (case-insensitive) |
+
+GIFs load from their external host, with **Play** and **Stop** controls. Only the canonical Giphy media host autoplays while visible; other hosts require **Play** before the browser requests the image. Reduced-motion users press **Play** to start them. There is no GIF search, provider API key, upload, conversion, or hosted copy. Giphy share links use its public media URLs; direct GIF links are verified by the existing protected link unfurler before playback. It requests the first 32 bytes, caps the response body retained for verification at 32 bytes even if the host ignores the range, and stores only the final URL. Network chunks and response headers can exceed that body cap. Redirect cycles and missing locations stop immediately; the redirect chain shares a five-second HTTP budget, including time spent resolving addresses, although the synchronous DNS lookup itself cannot be interrupted by that budget. External hosts can change their content or redirect later browser requests; this verification does not impose a browser download-size limit. Previously fetched direct GIF links need refetching to gain this metadata; this change does not backfill them.
+
+GIF embeds use the existing embed JSON fields with `kind: "gif"`; their `src` is an image URL, not an iframe URL. Clients that do not support this kind can keep showing the source link.
+
+Run `composer test:mutations` to check selected GIF security mutations across the PHP unfurler and browser playback policy. The suite first verifies unchanged-source controls, then requires each weakened protection to cause assertion failures. It runs automatically in the tests workflow; it is a focused regression gate, not an exhaustive mutation score.
 
 | Variable | Default | |
 |---|---|---|

From a7f1fa65eeffd201caca9c3c198024f569abd1cc Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 14:32:20 -0400
Subject: [PATCH 10/25] chore: separate GIF tests from upstream test additions

---
 tests/tsconfig.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/tsconfig.json b/tests/tsconfig.json
index d4fa9eb6e..a0de95d84 100644
--- a/tests/tsconfig.json
+++ b/tests/tsconfig.json
@@ -8,6 +8,7 @@
     },
     "include": [
         "Unit/**/*.test.ts",
+        "Unit/GifEmbed.test.tsx",
         "Unit/CommitPhoto.test.tsx",
         "Unit/DraftStash.test.tsx",
         "Unit/ComposerDraft.test.tsx",
@@ -16,7 +17,6 @@
         "Unit/ImageAttachments.test.tsx",
         "Unit/StagedRail.test.tsx",
         "Unit/UseNow.test.tsx",
-        "Unit/GifEmbed.test.tsx",
         "../resources/js/types/*.d.ts",
         "draft-images.config.ts",
         "Mutation/**/*.ts"

From 37cb6d3b581b011037c1f25e8ef0e130c6b54634 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:01:30 -0400
Subject: [PATCH 11/25] docs: keep GIF embed instructions concise

---
 README.md | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 88315d9c6..ef88cc757 100644
--- a/README.md
+++ b/README.md
@@ -45,13 +45,9 @@ A link card for a video, song or pen becomes a player that loads when clicked. T
 | `codepen` | pens |
 | `asciinema` | recordings |
 | `giphy` | `giphy.com/gifs/{id-or-slug-id}` and `giphy.com/embed/{id}` |
-| `gif` | Public HTTPS links whose path ends in `.gif` (case-insensitive) |
+| `gif` | Public HTTPS `.gif` links |
 
-GIFs load from their external host, with **Play** and **Stop** controls. Only the canonical Giphy media host autoplays while visible; other hosts require **Play** before the browser requests the image. Reduced-motion users press **Play** to start them. There is no GIF search, provider API key, upload, conversion, or hosted copy. Giphy share links use its public media URLs; direct GIF links are verified by the existing protected link unfurler before playback. It requests the first 32 bytes, caps the response body retained for verification at 32 bytes even if the host ignores the range, and stores only the final URL. Network chunks and response headers can exceed that body cap. Redirect cycles and missing locations stop immediately; the redirect chain shares a five-second HTTP budget, including time spent resolving addresses, although the synchronous DNS lookup itself cannot be interrupted by that budget. External hosts can change their content or redirect later browser requests; this verification does not impose a browser download-size limit. Previously fetched direct GIF links need refetching to gain this metadata; this change does not backfill them.
-
-GIF embeds use the existing embed JSON fields with `kind: "gif"`; their `src` is an image URL, not an iframe URL. Clients that do not support this kind can keep showing the source link.
-
-Run `composer test:mutations` to check selected GIF security mutations across the PHP unfurler and browser playback policy. The suite first verifies unchanged-source controls, then requires each weakened protection to cause assertion failures. It runs automatically in the tests workflow; it is a focused regression gate, not an exhaustive mutation score.
+GIFs load from their external host with Play and Stop controls. Giphy autoplays while visible; other hosts and reduced-motion users press Play to start playback.
 
 | Variable | Default | |
 |---|---|---|

From 1c8925497ca0c850afb97ef003d8d4dcf23e5a28 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:06:33 -0400
Subject: [PATCH 12/25] style: keep GIF playback controls small and unobtrusive

---
 resources/js/components/gif-embed.tsx | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/resources/js/components/gif-embed.tsx b/resources/js/components/gif-embed.tsx
index 41184bba2..0bcf29254 100644
--- a/resources/js/components/gif-embed.tsx
+++ b/resources/js/components/gif-embed.tsx
@@ -4,6 +4,7 @@ import { Button } from '@/components/ui/button';
 import { useGifPlayback } from '@/hooks/use-gif-playback';
 import { canAutoplayGif } from '@/lib/gifs';
 import { hostname } from '@/lib/urls';
+import { cn } from '@/lib/utils';
 import type { Embed, LinkPreview } from '@/types';
 
 type GifEmbedProps = {
@@ -36,7 +37,7 @@ export function GifEmbed({
             data-test="gif-embed"
             data-provider={embed?.provider ?? 'GIF'}
         >
-            <div className="relative mx-auto aspect-square w-full max-w-80 overflow-hidden bg-muted">
+            <div className="group/gif relative mx-auto aspect-square w-full max-w-80 overflow-hidden bg-muted">
                 <GifMedia preview={preview} embed={embed} playback={playback} />
                 <GifPlaybackButton
                     embed={embed}
@@ -131,14 +132,18 @@ function GifPlaybackButton({
         <Button
             type="button"
             variant="secondary"
-            size="sm"
+            size="icon"
             onClick={playback.onToggle}
             aria-label={`${label} GIF`}
-            className="absolute right-3 bottom-3 min-w-20 cursor-pointer bg-black/75 text-white hover:bg-black/85"
+            title={`${label} GIF`}
+            className={cn(
+                'absolute right-2 bottom-2 size-7 cursor-pointer bg-black/60 text-white transition-opacity hover:bg-black/80',
+                playback.isPlaying &&
+                    'opacity-0 group-hover/gif:opacity-100 focus-visible:opacity-100 [@media(hover:none)]:opacity-100',
+            )}
             data-test="gif-playback"
         >
-            <Icon className="size-4 fill-current" />
-            {label}
+            <Icon className="size-3 fill-current" />
         </Button>
     );
 }

From 40e510e63e5253a807503e1a727f10fd7c5a85e6 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:19:52 -0400
Subject: [PATCH 13/25] fix: autoplay verified external GIFs while visible

---
 KNOWLEDGE_BASE.md                     |  2 +-
 README.md                             |  2 +-
 resources/js/components/gif-embed.tsx | 10 +++-------
 resources/js/lib/gifs.ts              |  8 ++++----
 tests/Mutation/playback-mutations.ts  | 10 +++++-----
 tests/Unit/GifEmbed.test.tsx          |  4 ++--
 tests/Unit/GifPlayback.test.ts        | 17 +++++++++++------
 7 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md
index 9f257e9eb..d7a0fefd8 100644
--- a/KNOWLEDGE_BASE.md
+++ b/KNOWLEDGE_BASE.md
@@ -231,7 +231,7 @@ URLs and bare domains in commits and replies become clickable links. Long URLs a
 
 Supported links can also show click-to-play embedded players: YouTube, Vimeo, Loom, Twitch, Spotify, SoundCloud, Apple Music, Suno, CodePen, and asciinema. Only the link that gets the card can show a player, so choosing no card means no player. Embeds depend on server configuration and the linked URL being supported. Third-party player content loads only after you press play; those providers have their own privacy policies. This is embedding a link, not uploading a video or audio file to /dev/null.
 
-Giphy GIF share links and public HTTPS links ending in `.gif` can show animated GIFs in the selected link card, including in replies and remotes. They load from the external host and have **Play** and **Stop** controls. Only the canonical Giphy media host autoplays while visible; other hosts wait for **Play** before the browser requests the image. With reduced motion enabled they wait for **Play**; static preview cards do not animate. Direct GIFs must pass the link unfurler's public-address, redirect, content-type, and GIF-header checks first. It retains at most 32 response-body bytes for this check, stops redirect cycles and missing locations immediately, and shares one five-second HTTP budget across redirects. Synchronous DNS lookups cannot be interrupted by that budget. The original host still controls the browser's later response and file size. Failed previews keep a link to the source. There is no GIF search, API key, file upload, conversion, or hosted GIF storage. Administrators can enable only these embeds with `EMBEDS_PROVIDERS=giphy,gif`, or disable them with the existing embed controls. Previously fetched direct GIF links need refetching before they can animate; Giphy share links work without a backfill.
+Giphy GIF share links and public HTTPS links ending in `.gif` can show animated GIFs in the selected link card, including in replies and remotes. They load from the external host and have **Play** and **Stop** controls. Verified GIFs autoplay while visible and unload outside the viewport. Only the canonical Giphy media host can supply a static poster before playback. With reduced motion enabled they wait for **Play**; static preview cards do not animate. Direct GIFs must pass the link unfurler's public-address, redirect, content-type, and GIF-header checks first. It retains at most 32 response-body bytes for this check, stops redirect cycles and missing locations immediately, and shares one five-second HTTP budget across redirects. Synchronous DNS lookups cannot be interrupted by that budget. The original host still controls the browser's later response and file size. Failed previews keep a link to the source. There is no GIF search, API key, file upload, conversion, or hosted GIF storage. Administrators can enable only these embeds with `EMBEDS_PROVIDERS=giphy,gif`, or disable them with the existing embed controls. Previously fetched direct GIF links need refetching before they can animate; Giphy share links work without a backfill.
 
 Sources: [link rendering](resources/js/components/linkified-text.tsx), [link-card selection](app/Http/Requests/CreateCommitRequest.php), [embed configuration](config/embeds.php), [embedded player](resources/js/components/link-embed.tsx).
 
diff --git a/README.md b/README.md
index ef88cc757..e2edb6e57 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ A link card for a video, song or pen becomes a player that loads when clicked. T
 | `giphy` | `giphy.com/gifs/{id-or-slug-id}` and `giphy.com/embed/{id}` |
 | `gif` | Public HTTPS `.gif` links |
 
-GIFs load from their external host with Play and Stop controls. Giphy autoplays while visible; other hosts and reduced-motion users press Play to start playback.
+GIFs load from their external host with Play and Stop controls. Verified GIFs autoplay while visible; reduced-motion users press Play to start playback.
 
 | Variable | Default | |
 |---|---|---|
diff --git a/resources/js/components/gif-embed.tsx b/resources/js/components/gif-embed.tsx
index 0bcf29254..de79ab3a2 100644
--- a/resources/js/components/gif-embed.tsx
+++ b/resources/js/components/gif-embed.tsx
@@ -2,7 +2,7 @@ import { Play, Square } from 'lucide-react';
 import { useRef, useState } from 'react';
 import { Button } from '@/components/ui/button';
 import { useGifPlayback } from '@/hooks/use-gif-playback';
-import { canAutoplayGif } from '@/lib/gifs';
+import { canLoadGifPoster } from '@/lib/gifs';
 import { hostname } from '@/lib/urls';
 import { cn } from '@/lib/utils';
 import type { Embed, LinkPreview } from '@/types';
@@ -68,7 +68,7 @@ function GifMedia({ preview, embed, playback }: GifMediaProps) {
 
     if (
         embed?.poster &&
-        canAutoplayGif(embed.poster) &&
+        canLoadGifPoster(embed.poster) &&
         !posterFailed &&
         !playback.hasFailed
     ) {
@@ -95,11 +95,7 @@ function GifStatus({ preview, embed, playback }: GifMediaProps) {
             role={playback.hasFailed ? 'status' : undefined}
         >
             {playback.hasFailed && 'GIF could not load'}
-            {!playback.hasFailed &&
-                embed &&
-                (canAutoplayGif(embed.src)
-                    ? 'GIF'
-                    : 'External GIF — press Play to load')}
+            {!playback.hasFailed && embed && 'GIF'}
             {!playback.hasFailed &&
                 !embed &&
                 preview.is_pending &&
diff --git a/resources/js/lib/gifs.ts b/resources/js/lib/gifs.ts
index bb4fca371..46611fe8e 100644
--- a/resources/js/lib/gifs.ts
+++ b/resources/js/lib/gifs.ts
@@ -1,4 +1,4 @@
-const GIF_AUTOPLAY_HOSTS = new Set(['media.giphy.com']);
+const GIF_POSTER_HOSTS = new Set(['media.giphy.com']);
 
 function parseHttpsUrl(value: string): URL | null {
     try {
@@ -25,10 +25,10 @@ export function isGifUrl(value: string): boolean {
     );
 }
 
-export function canAutoplayGif(value: string): boolean {
+export function canLoadGifPoster(value: string): boolean {
     const url = parseHttpsUrl(value);
 
-    return url !== null && GIF_AUTOPLAY_HOSTS.has(url.hostname);
+    return url !== null && GIF_POSTER_HOSTS.has(url.hostname);
 }
 
 export const GIF_PLAYBACK_MODE = {
@@ -68,5 +68,5 @@ export function isGifPlaying({
         return true;
     }
 
-    return !reducedMotion && canAutoplayGif(source);
+    return !reducedMotion && isGifUrl(source);
 }
diff --git a/tests/Mutation/playback-mutations.ts b/tests/Mutation/playback-mutations.ts
index 48ed82a62..92cea825c 100644
--- a/tests/Mutation/playback-mutations.ts
+++ b/tests/Mutation/playback-mutations.ts
@@ -2,18 +2,18 @@ import type { GifMutation } from './php-gif-mutations.ts';
 
 export const playbackMutations: GifMutation[] = [
     {
-        name: 'autoplay arbitrary hosts',
+        name: 'autoplay unsupported URLs',
         source: 'resources/js/lib/gifs.ts',
         test: 'tests/Unit/GifPlayback.test.ts',
-        before: 'GIF_AUTOPLAY_HOSTS.has(url.hostname)',
-        after: 'true',
+        before: '!reducedMotion && isGifUrl(source)',
+        after: '!reducedMotion',
     },
     {
         name: 'ignore reduced motion',
         source: 'resources/js/lib/gifs.ts',
         test: 'tests/Unit/GifPlayback.test.ts',
-        before: '!reducedMotion && canAutoplayGif(source)',
-        after: 'canAutoplayGif(source)',
+        before: '!reducedMotion && isGifUrl(source)',
+        after: 'isGifUrl(source)',
     },
     {
         name: 'ignore visibility',
diff --git a/tests/Unit/GifEmbed.test.tsx b/tests/Unit/GifEmbed.test.tsx
index a5c900d5d..ed7e9e36e 100644
--- a/tests/Unit/GifEmbed.test.tsx
+++ b/tests/Unit/GifEmbed.test.tsx
@@ -90,13 +90,13 @@ test('only the explicit static poster can load before playback', () => {
     assert.ok(!html.includes('untrusted-thumbnail'));
 });
 
-test('arbitrary GIF hosts have no automatic thumbnail or image request', () => {
+test('external GIFs do not load unverified posters before visibility', () => {
     const html = renderToStaticMarkup(
         <GifEmbed preview={preview} embed={{ ...embed, poster: 'https://example.com/poster.gif' }} />,
     );
 
     assert.ok(html.includes('aria-label="Play GIF"'));
-    assert.ok(html.includes('External GIF'));
+    assert.ok(!html.includes('press Play to load'));
     assert.ok(!html.includes('<img'));
     assert.ok(!html.includes('poster.gif'));
 });
diff --git a/tests/Unit/GifPlayback.test.ts b/tests/Unit/GifPlayback.test.ts
index f29f1d439..d435b6b05 100644
--- a/tests/Unit/GifPlayback.test.ts
+++ b/tests/Unit/GifPlayback.test.ts
@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
-import { canAutoplayGif, isGifPlaying, isGifUrl } from '../../resources/js/lib/gifs.ts';
+import { canLoadGifPoster, isGifPlaying, isGifUrl } from '../../resources/js/lib/gifs.ts';
 
 const validGifUrls = [
     'https://example.com/animation.gif',
@@ -13,6 +13,7 @@ const validGifUrls = [
 for (const url of validGifUrls) {
     void test(`recognizes a direct HTTPS GIF link: ${url}`, () => {
         assert.equal(isGifUrl(url), true);
+        assert.equal(isGifPlaying({ ...playback, source: url }), true);
     });
 }
 
@@ -33,6 +34,7 @@ const invalidGifUrls = [
 for (const url of invalidGifUrls) {
     void test(`does not treat an unsupported link as a GIF: ${url}`, () => {
         assert.equal(isGifUrl(url), false);
+        assert.equal(isGifPlaying({ ...playback, source: url }), false);
     });
 }
 
@@ -81,8 +83,8 @@ void test('static cards and failed GIFs never animate, even after Play', () => {
     );
 });
 
-void test('only canonical Giphy media can autoplay', () => {
-    assert.equal(canAutoplayGif('https://media.giphy.com/media/cat/giphy.gif'), true);
+void test('only canonical Giphy media can supply a static poster', () => {
+    assert.equal(canLoadGifPoster('https://media.giphy.com/media/cat/giphy.gif'), true);
     for (const source of [
         'https://example.com/cat.gif',
         'https://media.giphy.com.attacker.example/cat.gif',
@@ -94,13 +96,16 @@ void test('only canonical Giphy media can autoplay', () => {
         'https://media.giphy.com:8443/media/cat/giphy.gif',
         'not a URL',
     ]) {
-        assert.equal(canAutoplayGif(source), false);
+        assert.equal(canLoadGifPoster(source), false);
     }
 });
 
-void test('arbitrary GIF hosts require Play and Stop still takes precedence', () => {
+void test('external GIFs autoplay while visible and respect playback preferences', () => {
     const external = { ...playback, source: 'https://example.com/cat.gif' };
-    assert.equal(isGifPlaying(external), false);
+    assert.equal(isGifPlaying(external), true);
+    assert.equal(isGifPlaying({ ...external, isVisible: false }), false);
+    assert.equal(isGifPlaying({ ...external, reducedMotion: true }), false);
+    assert.equal(isGifPlaying({ ...external, reducedMotion: true, playback: 'play' }), true);
     assert.equal(isGifPlaying({ ...external, playback: 'play' }), true);
     assert.equal(isGifPlaying({ ...external, playback: 'stop' }), false);
     assert.equal(isGifPlaying({ ...external, playback: 'play', isVisible: false }), false);

From a2f9d82377b44388014f1540370c1bd152907033 Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:24:02 -0400
Subject: [PATCH 14/25] fix: retain GIF rendering alongside upstream embed
 resizing

---
 resources/js/components/link-embed.tsx | 85 ++++++++++++++++++++++----
 1 file changed, 74 insertions(+), 11 deletions(-)

diff --git a/resources/js/components/link-embed.tsx b/resources/js/components/link-embed.tsx
index 942e34bfb..9c62d44f5 100644
--- a/resources/js/components/link-embed.tsx
+++ b/resources/js/components/link-embed.tsx
@@ -1,9 +1,9 @@
 import { AudioLines, Code2, Play } from 'lucide-react';
 import type { CSSProperties, ReactNode } from 'react';
-import { useState } from 'react';
-import { GifEmbed } from '@/components/gif-embed';
+import { useEffect, useRef, useState } from 'react';
 import { cn } from '@/lib/utils';
 import type { Embed, LinkPreview } from '@/types';
+import { GifEmbed } from './gif-embed';
 
 const icons = { video: Play, audio: AudioLines, code: Code2 };
 
@@ -21,6 +21,75 @@ function frameStyle(embed: Embed): CSSProperties {
         : { aspectRatio: embed.aspect_ratio };
 }
 
+function isAsciinemaRecording(embed: Embed): boolean {
+    return (
+        embed.provider === 'asciinema' &&
+        /^https:\/\/asciinema\.org\/a\/\w+\/iframe(?:[?#].*)?$/.test(embed.src)
+    );
+}
+
+function isAsciinemaBodySize(
+    data: unknown,
+): data is { type: 'bodySize'; payload: { height: number } } {
+    return (
+        typeof data === 'object' &&
+        data !== null &&
+        'type' in data &&
+        data.type === 'bodySize' &&
+        'payload' in data &&
+        typeof data.payload === 'object' &&
+        data.payload !== null &&
+        'height' in data.payload &&
+        typeof data.payload.height === 'number' &&
+        Number.isFinite(data.payload.height) &&
+        data.payload.height > 0
+    );
+}
+
+export function EmbedFrame({ embed, title }: { embed: Embed; title: string }) {
+    const iframeRef = useRef<HTMLIFrameElement>(null);
+    const recording = isAsciinemaRecording(embed);
+    const [height, setHeight] = useState(embed.height ?? 420);
+
+    useEffect(() => {
+        if (!recording) {
+            return;
+        }
+
+        const iframe = iframeRef.current;
+        const resize = (event: MessageEvent<unknown>) => {
+            if (
+                event.origin !== 'https://asciinema.org' ||
+                event.source !== iframe?.contentWindow ||
+                !isAsciinemaBodySize(event.data)
+            ) {
+                return;
+            }
+
+            setHeight(event.data.payload.height);
+        };
+
+        window.addEventListener('message', resize);
+
+        return () => window.removeEventListener('message', resize);
+    }, [recording]);
+
+    return (
+        <iframe
+            ref={iframeRef}
+            src={embed.src}
+            title={title}
+            allow="autoplay; encrypted-media; fullscreen; picture-in-picture; clipboard-write"
+            sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-presentation allow-forms"
+            referrerPolicy="strict-origin-when-cross-origin"
+            allowFullScreen
+            style={recording ? { height } : frameStyle(embed)}
+            className="block w-full border-0 bg-muted"
+            data-test="link-embed-frame"
+        />
+    );
+}
+
 function Thumbnail({
     src,
     className,
@@ -129,16 +198,10 @@ export function LinkEmbed({
     const poster = preview.image_url ?? embed.poster ?? null;
 
     const frame = (
-        <iframe
-            src={embed.src}
+        <EmbedFrame
+            key={embed.src}
+            embed={embed}
             title={preview.title ?? `${embed.provider} player`}
-            allow="autoplay; encrypted-media; fullscreen; picture-in-picture; clipboard-write"
-            sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-presentation allow-forms"
-            referrerPolicy="strict-origin-when-cross-origin"
-            allowFullScreen
-            style={frameStyle(embed)}
-            className="block w-full border-0 bg-muted"
-            data-test="link-embed-frame"
         />
     );
 

From 789e512c79cc899df2e8782717b41c64a1a6d90a Mon Sep 17 00:00:00 2001
From: Jerry <99199491+devjerry0@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:24:07 -0400
Subject: [PATCH 15/25] style: normalize embed imports after upstream merge

---
 resources/js/components/link-embed.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/components/link-embed.tsx b/resources/js/components/link-embed.tsx
index 9c62d44f5..a8af6c897 100644
--- a/resources/js/components/link-embed.tsx
+++ b/resources/js/components/link-embed.tsx
@@ -1,9 +1,9 @@
 import { AudioLines, Code2, Play } from 'lucide-react';
 import type { CSSProperties, ReactNode } from 'react';
 import { useEffect, useRef, useState } from 'react';
+import { GifEmbed } from '@/components/gif-embed';
 import { cn } from '@/lib/utils';
 import type { Embed, LinkPreview } from '@/types';
-import { GifEmbed } from './gif-embed';
 
 const icons = { video: Play, audio: AudioLines, code: Code2 };
 

From e7902b11d07b7305021dd0725392c72aa282c551 Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:17:38 -0400
Subject: [PATCH 16/25] fix(security): pin non-public link preview address
 ranges

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 app/Services/LinkPreviewAddress.php           |  8 +-
 tests/Mutation/php-gif-mutations.ts           |  9 +-
 .../Unit/Services/LinkPreviewAddressTest.php  | 94 +++++++++++++++++++
 3 files changed, 103 insertions(+), 8 deletions(-)
 create mode 100644 tests/Unit/Services/LinkPreviewAddressTest.php

diff --git a/app/Services/LinkPreviewAddress.php b/app/Services/LinkPreviewAddress.php
index b4a6a7d04..bf9db2e93 100644
--- a/app/Services/LinkPreviewAddress.php
+++ b/app/Services/LinkPreviewAddress.php
@@ -11,13 +11,11 @@
 final readonly class LinkPreviewAddress
 {
     /**
-     * Extend Symfony's private subnets with relay, multicast, site-local and translated ranges
-     * that PHP's global-range filter also permits.
-     *
      * @var list<string>
      */
     private const array BLOCKED_RANGES = [
         ...IpUtils::PRIVATE_SUBNETS,
+        '64:ff9b::/32', // NAT64; FILTER_FLAG_GLOBAL_RANGE permits RFC 6052.
         '192.88.99.0/24',
         '224.0.0.0/4',
         'fec0::/10',
@@ -30,10 +28,6 @@ public function __construct(private DnsResolver $dns)
         //
     }
 
-    /**
-     * Returns the address to connect to, or null when the URL must not be fetched: anything but plain http(s) on a
-     * default port without credentials, or a host that resolves to nothing or to any non-public address.
-     */
     public function get(Url $url): ?string
     {
         if (! in_array($url->getScheme(), ['http', 'https'], true)) {
diff --git a/tests/Mutation/php-gif-mutations.ts b/tests/Mutation/php-gif-mutations.ts
index b962485cb..e75f3df7a 100644
--- a/tests/Mutation/php-gif-mutations.ts
+++ b/tests/Mutation/php-gif-mutations.ts
@@ -45,7 +45,7 @@ export const phpGifMutations: GifMutation[] = [
     {
         name: 'Symfony special-use subnets stay blocked',
         source: 'app/Services/LinkPreviewAddress.php',
-        test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
+        test: 'tests/Unit/Services/LinkPreviewAddressTest.php',
         before: '...IpUtils::PRIVATE_SUBNETS,',
         after: '',
     },
@@ -63,6 +63,13 @@ export const phpGifMutations: GifMutation[] = [
         before: 'array_all($addresses, $this->isPublic(...))',
         after: 'true',
     },
+    {
+        name: 'NAT64 translations stay blocked',
+        source: 'app/Services/LinkPreviewAddress.php',
+        test: 'tests/Unit/Services/LinkPreviewAddressTest.php',
+        before: "'64:ff9b::/32',",
+        after: '',
+    },
     {
         name: 'response body is capped',
         source: 'app/Services/LimitedResponseBody.php',
diff --git a/tests/Unit/Services/LinkPreviewAddressTest.php b/tests/Unit/Services/LinkPreviewAddressTest.php
new file mode 100644
index 000000000..95e4ffc48
--- /dev/null
+++ b/tests/Unit/Services/LinkPreviewAddressTest.php
@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Contracts\Services\DnsResolver;
+use App\Services\LinkPreviewAddress;
+use Uri\WhatWg\Url;
+
+it('rejects non-public and NAT64 addresses', function (string $address): void {
+    $validator = new LinkPreviewAddress(new readonly class($address) implements DnsResolver
+    {
+        public function __construct(private string $address)
+        {
+            //
+        }
+
+        public function resolve(string $host): array
+        {
+            return [$this->address];
+        }
+    });
+
+    expect($validator->get(Url::parse('https://example.com/cat.gif')))->toBeNull();
+})->with([
+    'carrier-grade NAT' => '100.64.0.1',
+    'IETF protocol assignment' => '192.0.0.1',
+    'IPv4 documentation one' => '192.0.2.1',
+    '6to4 relay' => '192.88.99.1',
+    'benchmarking' => '198.18.0.1',
+    'IPv4 documentation two' => '198.51.100.1',
+    'IPv4 documentation three' => '203.0.113.1',
+    'IPv4 multicast' => '224.0.0.1',
+    'RFC 6052 loopback' => '64:ff9b::7f00:1',
+    'local-use NAT64 loopback' => '64:ff9b:1::7f00:1',
+    'broader NAT64 prefix one' => '64:ff9b:7f00:1::',
+    'broader NAT64 prefix two' => '64:ff9b::1:7f00:1',
+    'RFC 6052 private address' => '64:ff9b::a00:1',
+    'discard-only' => '100::1',
+    'Teredo' => '2001::1',
+    'IPv6 documentation' => '2001:db8::1',
+    'IPv6 6to4' => '2002::1',
+    'site-local' => 'fec0::1',
+    'IPv6 multicast' => 'ff00::1',
+    'IPv4-compatible address' => '::2',
+    'IPv4-mapped address' => '::ffff:127.0.0.1',
+    'IPv4-translated address' => '::ffff:0:7f00:1',
+    'IPv4 loopback' => '127.0.0.1',
+    'IPv6 loopback' => '::1',
+]);
+
+it('rejects a host when any resolved address is not public', function (): void {
+    $validator = new LinkPreviewAddress(new readonly class implements DnsResolver
+    {
+        public function resolve(string $host): array
+        {
+            return ['93.184.216.34', '64:ff9b::7f00:1'];
+        }
+    });
+
+    expect($validator->get(Url::parse('https://example.com/cat.gif')))->toBeNull();
+});
+
+it('accepts public addresses on default HTTP ports', function (string $url, string $address): void {
+    $validator = new LinkPreviewAddress(new readonly class($address) implements DnsResolver
+    {
+        public function __construct(private string $address)
+        {
+            //
+        }
+
+        public function resolve(string $host): array
+        {
+            return [$this->address];
+        }
+    });
+
+    expect($validator->get(Url::parse($url)))->toBe($address);
+})->with([
+    'IPv4 HTTPS default port' => ['https://example.com:443/cat.gif', '93.184.216.34'],
+    'IPv6 HTTPS default port' => ['https://example.com:443/cat.gif', '2606:2800:220:1:248:1893:25c8:1946'],
+    'IPv4 HTTP default port' => ['http://example.com:80/cat.gif', '93.184.216.34'],
+]);
+
+it('rejects non-default ports', function (): void {
+    $validator = new LinkPreviewAddress(new readonly class implements DnsResolver
+    {
+        public function resolve(string $host): array
+        {
+            return ['93.184.216.34'];
+        }
+    });
+
+    expect($validator->get(Url::parse('https://example.com:8443/cat.gif')))->toBeNull();
+});

From 20bbd021480ae8880da965010eda66bd8a92feab Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:17:45 -0400
Subject: [PATCH 17/25] test: cover servers that ignore GIF range requests

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 tests/Fixtures/link-preview-http.php          | 42 ++++++++++++++++
 .../Services/LinkPreviewHttpClientTest.php    | 48 +++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 tests/Fixtures/link-preview-http.php
 create mode 100644 tests/Unit/Services/LinkPreviewHttpClientTest.php

diff --git a/tests/Fixtures/link-preview-http.php b/tests/Fixtures/link-preview-http.php
new file mode 100644
index 000000000..641748cfd
--- /dev/null
+++ b/tests/Fixtures/link-preview-http.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+$server = stream_socket_server('tcp://127.0.0.1:0', $errorCode, $errorMessage);
+
+if ($server === false) {
+    fwrite(STDERR, "{$errorMessage} ({$errorCode})\n");
+
+    exit(1);
+}
+
+$address = stream_socket_get_name($server, false);
+$port = (int) mb_substr(mb_strrchr($address, ':'), 1);
+
+fwrite(STDOUT, "{$port}\n");
+
+$connection = stream_socket_accept($server, 5);
+
+if ($connection === false) {
+    exit(1);
+}
+
+$request = '';
+
+while (($line = fgets($connection)) !== false) {
+    $request .= $line;
+
+    if ($line === "\r\n") {
+        break;
+    }
+}
+
+file_put_contents($argv[1], $request);
+
+$body = "GIF89a\x01\x00\x01\x00\x80\x00\x00".str_repeat('x', 243);
+$response = "HTTP/1.1 200 OK\r\nContent-Type: image/gif\r\nContent-Length: ".mb_strlen($body)."\r\nConnection: close\r\n\r\n".$body;
+
+fwrite($connection, $response);
+
+fclose($connection);
+fclose($server);
diff --git a/tests/Unit/Services/LinkPreviewHttpClientTest.php b/tests/Unit/Services/LinkPreviewHttpClientTest.php
new file mode 100644
index 000000000..a4ae7d71b
--- /dev/null
+++ b/tests/Unit/Services/LinkPreviewHttpClientTest.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Dto\LinkPreviewRequest;
+use App\Services\LinkPreviewHttpClient;
+use Illuminate\Support\Facades\Http;
+use Symfony\Component\Process\Process;
+use Uri\WhatWg\Url;
+
+it('recovers a bounded response when a server ignores the requested GIF range', function (): void {
+    $requestLog = tempnam(sys_get_temp_dir(), 'link-preview-http-');
+    throw_if(
+        $requestLog === false,
+        RuntimeException::class,
+        'Unable to create link preview request log.',
+    );
+
+    $server = new Process([PHP_BINARY, base_path('tests/Fixtures/link-preview-http.php'), $requestLog]);
+    $server->setTimeout(5)->start();
+
+    try {
+        $server->waitUntil(
+            static fn (string $type, string $output): bool => $type === Process::OUT && mb_trim($output) !== '',
+        );
+        $port = (int) mb_trim($server->getOutput());
+
+        throw_if($port === 0, RuntimeException::class, 'Link preview fixture did not report a port.');
+        Http::allowStrayRequests(["http://example.test:{$port}/*"]);
+
+        $response = resolve(LinkPreviewHttpClient::class)->get(new LinkPreviewRequest(
+            url: Url::parse("http://example.test:{$port}/cat.gif"),
+            address: '127.0.0.1',
+            headers: ['Accept' => 'image/gif', 'Range' => 'bytes=0-31'],
+            maxBodyBytes: 32,
+            timeoutSeconds: 5,
+        ));
+
+        expect($response->status())->toBe(200)
+            ->and($response->header('Content-Type'))->toBe('image/gif')
+            ->and($response->body())->toHaveLength(32)
+            ->and($response->body())->toBe("GIF89a\x01\x00\x01\x00\x80\x00\x00".str_repeat('x', 19))
+            ->and(file_get_contents($requestLog))->toContain("Range: bytes=0-31\r\n");
+    } finally {
+        $server->stop();
+        unlink($requestLog);
+    }
+});

From 070eb47528ca2402344cddc209e8a62bdacdeba0 Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:17:48 -0400
Subject: [PATCH 18/25] fix: stabilize GIF loading, playback, and manual
 retries

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 KNOWLEDGE_BASE.md                             |   2 +-
 app/Dto/Embed.php                             |   4 +-
 app/Services/Embeds.php                       |   7 +-
 app/Services/GifLinks.php                     |   4 +-
 app/Services/LinkPreviewParser.php            |   5 -
 resources/js/components/gif-embed.tsx         |  79 +++--
 resources/js/hooks/use-gif-playback.ts        |  44 ++-
 resources/js/lib/gifs.ts                      |  87 +++++-
 .../Controllers/Api/CommitControllerTest.php  |   2 +-
 tests/Mutation/php-gif-mutations.ts           |   8 +-
 tests/Mutation/playback-mutations.ts          |  22 +-
 tests/Unit/GifEmbed.test.tsx                  |   2 +-
 tests/Unit/GifEmbedPlayback.test.tsx          | 270 ++++++++++++++++++
 tests/Unit/GifPlayback.test.ts                | 118 +++++++-
 tests/Unit/GifPlaybackHook.test.tsx           | 181 ++++++++++++
 .../Services/EmbedProviders/GiphyTest.php     |   3 +-
 tests/Unit/Services/EmbedsTest.php            |   2 +-
 tests/draft-images.config.ts                  |   2 +
 tests/tsconfig.json                           |   2 +
 19 files changed, 781 insertions(+), 63 deletions(-)
 create mode 100644 tests/Unit/GifEmbedPlayback.test.tsx
 create mode 100644 tests/Unit/GifPlaybackHook.test.tsx

diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md
index b246ce4f7..0e66a1846 100644
--- a/KNOWLEDGE_BASE.md
+++ b/KNOWLEDGE_BASE.md
@@ -229,7 +229,7 @@ URLs and bare domains in commits and replies become clickable links. Long URLs a
 
 Supported links can also show click-to-play embedded players: YouTube, Vimeo, Loom, Twitch, Spotify, SoundCloud, Apple Music, Suno, CodePen, and asciinema. Only the link that gets the card can show a player, so choosing no card means no player. Embeds depend on server configuration and the linked URL being supported. Third-party player content loads only after you press play; those providers have their own privacy policies. This is embedding a link, not uploading a video or audio file to /dev/null.
 
-Giphy GIF share links and public HTTPS links ending in `.gif` can show animated GIFs in the selected link card, including in replies and remotes. They load from the external host and have **Play** and **Stop** controls. Verified GIFs autoplay while visible and unload outside the viewport. Only the canonical Giphy media host can supply a static poster before playback. With reduced motion enabled they wait for **Play**; static preview cards do not animate. Direct GIFs must pass the link unfurler's public-address, redirect, content-type, and GIF-header checks first. It retains at most 32 response-body bytes for this check, stops redirect cycles and missing locations immediately, and shares one five-second HTTP budget across redirects. Synchronous DNS lookups cannot be interrupted by that budget. The original host still controls the browser's later response and file size. Failed previews keep a link to the source. There is no GIF search, API key, file upload, conversion, or hosted GIF storage. Administrators can enable only these embeds with `EMBEDS_PROVIDERS=giphy,gif`, or disable them with the existing embed controls. Previously fetched direct GIF links need refetching before they can animate; Giphy share links work without a backfill.
+Giphy share links and verified public HTTPS `.gif` links play inline from their external host. Verified GIFs autoplay while visible and unload offscreen; reduced-motion users press **Play**. **Stop** unloads the animation, and failed GIFs offer two manual retries. No uploads or provider keys are required. Enable with `EMBEDS_PROVIDERS=giphy,gif`. Previously cached direct GIF links require refetching.
 
 Sources: [link rendering](resources/js/components/linkified-text.tsx), [link-card selection](app/Http/Requests/CreateCommitRequest.php), [embed configuration](config/embeds.php), [embedded player](resources/js/components/link-embed.tsx).
 
diff --git a/app/Dto/Embed.php b/app/Dto/Embed.php
index 7d1f161eb..b221a40f6 100644
--- a/app/Dto/Embed.php
+++ b/app/Dto/Embed.php
@@ -24,8 +24,6 @@ private function __construct(
     }
 
     /**
-     * The poster stands in for the player until it is played, for when the link's own preview has no image.
-     *
      * @param  array<string, string|int>  $query
      */
     public static function video(string $provider, string $src, array $query = [], string $aspectRatio = '16 / 9', ?string $poster = null): self
@@ -43,7 +41,7 @@ public static function fixed(string $provider, EmbedKind $kind, string $src, int
 
     public static function gif(string $provider, string $src, ?string $poster = null): self
     {
-        return new self($provider, EmbedKind::Gif, $src, '1 / 1', null, $poster);
+        return new self($provider, EmbedKind::Gif, $src, null, null, $poster);
     }
 
     /**
diff --git a/app/Services/Embeds.php b/app/Services/Embeds.php
index 5946695cf..bb805b5d5 100644
--- a/app/Services/Embeds.php
+++ b/app/Services/Embeds.php
@@ -11,14 +11,13 @@
 
 final readonly class Embeds
 {
+    private const string GIF_PROVIDER = 'GIF';
+
     public function __construct(private Container $container)
     {
         //
     }
 
-    /**
-     * The GIF URL is metadata verified by the link unfurler, never a client-supplied attachment.
-     */
     public function for(string $url, ?string $gifUrl = null): ?Embed
     {
         $parsed = Url::parse($url);
@@ -41,7 +40,7 @@ public function for(string $url, ?string $gifUrl = null): ?Embed
             return null;
         }
 
-        return Embed::gif('GIF', $gifUrl);
+        return Embed::gif(self::GIF_PROVIDER, $gifUrl);
     }
 
     /**
diff --git a/app/Services/GifLinks.php b/app/Services/GifLinks.php
index c4e8bca86..caff45d9c 100644
--- a/app/Services/GifLinks.php
+++ b/app/Services/GifLinks.php
@@ -15,8 +15,6 @@
 
     private const int MIN_HEADER_BYTES = 13;
 
-    private const int MAX_URL_LENGTH = 2048;
-
     private const int SIGNATURE_BYTES = 6;
 
     private const int WIDTH_OFFSET = 6;
@@ -50,7 +48,7 @@ public function getVerifiedUrl(Url $url, string $contentType, string $header): ?
 
         $sourceUrl = $url->toAsciiString();
 
-        if (mb_strlen($sourceUrl) > self::MAX_URL_LENGTH) {
+        if (mb_strlen($sourceUrl) > Urls::MAX_LENGTH) {
             return null;
         }
 
diff --git a/app/Services/LinkPreviewParser.php b/app/Services/LinkPreviewParser.php
index 79ca52577..c67033983 100644
--- a/app/Services/LinkPreviewParser.php
+++ b/app/Services/LinkPreviewParser.php
@@ -38,9 +38,6 @@ public function parse(string $html, Url $page): LinkPreviewMetadata
     }
 
     /**
-     * Returns the first candidate that still has text once entities are decoded and whitespace is collapsed,
-     * truncated to the column's length.
-     *
      * @param  list<string>  $candidates
      */
     private function text(array $candidates, int $limit): ?string
@@ -63,8 +60,6 @@ private function text(array $candidates, int $limit): ?string
     }
 
     /**
-     * Returns the first candidate that, resolved against the page URL, is an https URL.
-     *
      * @param  list<string>  $candidates
      */
     private function imageUrl(array $candidates, Url $page): ?string
diff --git a/resources/js/components/gif-embed.tsx b/resources/js/components/gif-embed.tsx
index de79ab3a2..56f84d429 100644
--- a/resources/js/components/gif-embed.tsx
+++ b/resources/js/components/gif-embed.tsx
@@ -1,4 +1,4 @@
-import { Play, Square } from 'lucide-react';
+import { Play, RotateCcw, Square } from 'lucide-react';
 import { useRef, useState } from 'react';
 import { Button } from '@/components/ui/button';
 import { useGifPlayback } from '@/hooks/use-gif-playback';
@@ -51,20 +51,52 @@ export function GifEmbed({
 }
 
 function GifMedia({ preview, embed, playback }: GifMediaProps) {
-    const [posterFailed, setPosterFailed] = useState(false);
-
-    if (playback.isPlaying && embed) {
-        return (
-            <img
-                src={embed.src}
-                alt={preview.title ?? 'Animated GIF'}
-                referrerPolicy="no-referrer"
-                onError={playback.onError}
-                className="absolute inset-0 size-full object-contain"
-                data-test="gif-animation"
+    return (
+        <>
+            {/* Retry posters only for new media or a manual retry. */}
+            <GifFallback
+                key={`${embed?.src}:${embed?.poster}:${playback.retryCount}`}
+                preview={preview}
+                embed={embed}
+                playback={playback}
             />
-        );
-    }
+            {playback.isPlaying && embed && (
+                <GifAnimation
+                    key={embed.src}
+                    preview={preview}
+                    embed={embed}
+                    playback={playback}
+                />
+            )}
+        </>
+    );
+}
+
+function GifAnimation({
+    preview,
+    embed,
+    playback,
+}: GifMediaProps & { embed: Embed }) {
+    const [isLoaded, setIsLoaded] = useState(false);
+
+    return (
+        <img
+            src={embed.src}
+            alt={preview.title ?? 'Animated GIF'}
+            referrerPolicy="no-referrer"
+            onLoad={() => setIsLoaded(true)}
+            onError={playback.onError}
+            className={cn(
+                'absolute inset-0 size-full bg-muted object-contain',
+                !isLoaded && 'invisible',
+            )}
+            data-test="gif-animation"
+        />
+    );
+}
+
+function GifFallback({ preview, embed, playback }: GifMediaProps) {
+    const [posterFailed, setPosterFailed] = useState(false);
 
     if (
         embed?.poster &&
@@ -117,19 +149,18 @@ function GifPlaybackButton({
     playback: GifPlaybackState;
     isStatic: boolean;
 }) {
-    if (isStatic || !embed || playback.hasFailed) {
+    if (isStatic || !embed || (playback.hasFailed && !playback.canRetry)) {
         return null;
     }
 
-    const Icon = playback.isPlaying ? Square : Play;
-    const label = playback.isPlaying ? 'Stop' : 'Play';
+    const { Icon, label, onClick } = gifPlaybackControl(playback);
 
     return (
         <Button
             type="button"
             variant="secondary"
             size="icon"
-            onClick={playback.onToggle}
+            onClick={onClick}
             aria-label={`${label} GIF`}
             title={`${label} GIF`}
             className={cn(
@@ -144,6 +175,18 @@ function GifPlaybackButton({
     );
 }
 
+function gifPlaybackControl(playback: GifPlaybackState) {
+    if (playback.hasFailed) {
+        return { Icon: RotateCcw, label: 'Retry', onClick: playback.onRetry };
+    }
+
+    return {
+        Icon: playback.isPlaying ? Square : Play,
+        label: playback.isPlaying ? 'Stop' : 'Play',
+        onClick: playback.onToggle,
+    };
+}
+
 function GifSource({ preview, embed, isStatic }: GifEmbedProps) {
     const details = <GifDetails preview={preview} embed={embed} />;
 
diff --git a/resources/js/hooks/use-gif-playback.ts b/resources/js/hooks/use-gif-playback.ts
index 4be38359f..d5d66c2b4 100644
--- a/resources/js/hooks/use-gif-playback.ts
+++ b/resources/js/hooks/use-gif-playback.ts
@@ -1,7 +1,17 @@
 import type { RefObject } from 'react';
 import { useEffect, useState } from 'react';
 import { useMediaQuery } from '@/hooks/use-media-query';
-import { GIF_PLAYBACK_MODE, isGifPlaying, type GifPlayback } from '@/lib/gifs';
+import {
+    canRetryGifLoad,
+    failGifLoad,
+    GIF_PLAYBACK_MODE,
+    hasGifLoadFailed,
+    isGifPlaying,
+    retryGifLoad,
+    syncGifLoadRetryState,
+    toggleGifPlayback,
+    type GifLoadRetryState,
+} from '@/lib/gifs';
 import type { Embed } from '@/types';
 
 const MIN_VISIBLE_RATIO = 0.1;
@@ -51,15 +61,26 @@ export function useGifPlayback({
 }) {
     const isVisible = useGifVisibility(container);
     const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
-    const [playback, setPlayback] = useState<GifPlayback>(
-        GIF_PLAYBACK_MODE.AUTOMATIC,
-    );
-    const [hasFailed, setHasFailed] = useState(false);
+    const source = embed?.src ?? null;
+    const [retryState, setRetryState] = useState<GifLoadRetryState>({
+        source,
+        failedSource: null,
+        retryCount: 0,
+        playback: GIF_PLAYBACK_MODE.AUTOMATIC,
+    });
+    const currentRetryState = syncGifLoadRetryState(retryState, source);
+
+    if (currentRetryState !== retryState) {
+        setRetryState(currentRetryState);
+    }
+
+    const hasFailed = hasGifLoadFailed(currentRetryState, source);
+    const canRetry = canRetryGifLoad(currentRetryState, source);
     const isPlaying =
         embed !== null &&
         isGifPlaying({
             source: embed.src,
-            playback,
+            playback: currentRetryState.playback,
             isVisible,
             reducedMotion,
             isStatic,
@@ -69,12 +90,13 @@ export function useGifPlayback({
     return {
         isPlaying,
         hasFailed,
-        onError: () => setHasFailed(true),
+        canRetry,
+        retryCount: currentRetryState.retryCount,
+        onError: () => setRetryState((state) => failGifLoad(state, source)),
+        onRetry: () => setRetryState((state) => retryGifLoad(state, source)),
         onToggle: () =>
-            setPlayback(
-                isPlaying
-                    ? GIF_PLAYBACK_MODE.STOPPED
-                    : GIF_PLAYBACK_MODE.PLAYING,
+            setRetryState((state) =>
+                toggleGifPlayback(state, source, isPlaying),
             ),
     };
 }
diff --git a/resources/js/lib/gifs.ts b/resources/js/lib/gifs.ts
index 46611fe8e..bb5a50ce0 100644
--- a/resources/js/lib/gifs.ts
+++ b/resources/js/lib/gifs.ts
@@ -40,6 +40,91 @@ export const GIF_PLAYBACK_MODE = {
 export type GifPlayback =
     (typeof GIF_PLAYBACK_MODE)[keyof typeof GIF_PLAYBACK_MODE];
 
+export const MAX_GIF_RETRIES = 2;
+
+export type GifLoadRetryState = {
+    source: string | null;
+    failedSource: string | null;
+    retryCount: number;
+    playback: GifPlayback;
+};
+
+export function syncGifLoadRetryState(
+    state: GifLoadRetryState,
+    source: string | null,
+): GifLoadRetryState {
+    if (state.source === source) {
+        return state;
+    }
+
+    return {
+        source,
+        failedSource: null,
+        retryCount: 0,
+        playback: state.playback,
+    };
+}
+
+export function hasGifLoadFailed(
+    state: GifLoadRetryState,
+    source: string | null,
+): boolean {
+    return source !== null && state.failedSource === source;
+}
+
+export function canRetryGifLoad(
+    state: GifLoadRetryState,
+    source: string | null,
+): boolean {
+    return (
+        hasGifLoadFailed(state, source) && state.retryCount < MAX_GIF_RETRIES
+    );
+}
+
+export function failGifLoad(
+    state: GifLoadRetryState,
+    source: string | null,
+): GifLoadRetryState {
+    if (state.source !== source || source === null) {
+        return state;
+    }
+
+    return { ...state, failedSource: source };
+}
+
+export function retryGifLoad(
+    state: GifLoadRetryState,
+    source: string | null,
+): GifLoadRetryState {
+    if (!canRetryGifLoad(state, source)) {
+        return state;
+    }
+
+    return {
+        ...state,
+        failedSource: null,
+        retryCount: state.retryCount + 1,
+        playback: GIF_PLAYBACK_MODE.PLAYING,
+    };
+}
+
+export function toggleGifPlayback(
+    state: GifLoadRetryState,
+    source: string | null,
+    isPlaying: boolean,
+): GifLoadRetryState {
+    if (state.source !== source) {
+        return state;
+    }
+
+    return {
+        ...state,
+        playback: isPlaying
+            ? GIF_PLAYBACK_MODE.STOPPED
+            : GIF_PLAYBACK_MODE.PLAYING,
+    };
+}
+
 export function isGifPlaying({
     source,
     playback,
@@ -68,5 +153,5 @@ export function isGifPlaying({
         return true;
     }
 
-    return !reducedMotion && isGifUrl(source);
+    return !reducedMotion && parseHttpsUrl(source) !== null;
 }
diff --git a/tests/Feature/Controllers/Api/CommitControllerTest.php b/tests/Feature/Controllers/Api/CommitControllerTest.php
index 0c2e7763e..9d965afac 100644
--- a/tests/Feature/Controllers/Api/CommitControllerTest.php
+++ b/tests/Feature/Controllers/Api/CommitControllerTest.php
@@ -138,7 +138,7 @@
             'provider' => 'GIF',
             'kind' => 'gif',
             'src' => 'https://cdn.example.com/cat.gif',
-            'aspect_ratio' => '1 / 1',
+            'aspect_ratio' => null,
             'height' => null,
             'poster' => null,
         ]);
diff --git a/tests/Mutation/php-gif-mutations.ts b/tests/Mutation/php-gif-mutations.ts
index e75f3df7a..ae8c05f80 100644
--- a/tests/Mutation/php-gif-mutations.ts
+++ b/tests/Mutation/php-gif-mutations.ts
@@ -151,15 +151,15 @@ export const phpGifMutations: GifMutation[] = [
         name: 'oversized URLs stay rejected',
         source: 'app/Services/GifLinks.php',
         test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
-        before: 'MAX_URL_LENGTH = 2048',
-        after: 'MAX_URL_LENGTH = 2049',
+        before: 'mb_strlen($sourceUrl) > Urls::MAX_LENGTH',
+        after: 'mb_strlen($sourceUrl) > Urls::MAX_LENGTH + 1',
     },
     {
         name: 'maximum-length URLs remain supported',
         source: 'app/Services/GifLinks.php',
         test: 'tests/Unit/Actions/UpdateLinkPreviewTest.php',
-        before: 'MAX_URL_LENGTH = 2048',
-        after: 'MAX_URL_LENGTH = 2047',
+        before: 'mb_strlen($sourceUrl) > Urls::MAX_LENGTH',
+        after: 'mb_strlen($sourceUrl) > Urls::MAX_LENGTH - 1',
     },
     {
         name: 'Giphy hosts cannot be spoofed',
diff --git a/tests/Mutation/playback-mutations.ts b/tests/Mutation/playback-mutations.ts
index 92cea825c..567f98db9 100644
--- a/tests/Mutation/playback-mutations.ts
+++ b/tests/Mutation/playback-mutations.ts
@@ -2,18 +2,18 @@ import type { GifMutation } from './php-gif-mutations.ts';
 
 export const playbackMutations: GifMutation[] = [
     {
-        name: 'autoplay unsupported URLs',
+        name: 'autoplay invalid verified GIF sources',
         source: 'resources/js/lib/gifs.ts',
         test: 'tests/Unit/GifPlayback.test.ts',
-        before: '!reducedMotion && isGifUrl(source)',
+        before: '!reducedMotion && parseHttpsUrl(source) !== null',
         after: '!reducedMotion',
     },
     {
         name: 'ignore reduced motion',
         source: 'resources/js/lib/gifs.ts',
         test: 'tests/Unit/GifPlayback.test.ts',
-        before: '!reducedMotion && isGifUrl(source)',
-        after: 'isGifUrl(source)',
+        before: '!reducedMotion && parseHttpsUrl(source) !== null',
+        after: 'parseHttpsUrl(source) !== null',
     },
     {
         name: 'ignore visibility',
@@ -50,6 +50,20 @@ export const playbackMutations: GifMutation[] = [
         before: 'playback === GIF_PLAYBACK_MODE.PLAYING',
         after: 'false',
     },
+    {
+        name: 'keep GIF failures after a manual retry',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: 'failedSource: null,\n        retryCount: state.retryCount + 1',
+        after: 'failedSource: state.failedSource,\n        retryCount: state.retryCount + 1',
+    },
+    {
+        name: 'allow unlimited GIF retries',
+        source: 'resources/js/lib/gifs.ts',
+        test: 'tests/Unit/GifPlayback.test.ts',
+        before: 'state.retryCount < MAX_GIF_RETRIES',
+        after: 'true',
+    },
     {
         name: 'allow HTTP',
         source: 'resources/js/lib/gifs.ts',
diff --git a/tests/Unit/GifEmbed.test.tsx b/tests/Unit/GifEmbed.test.tsx
index ed7e9e36e..19d98aeab 100644
--- a/tests/Unit/GifEmbed.test.tsx
+++ b/tests/Unit/GifEmbed.test.tsx
@@ -19,7 +19,7 @@ const embed: Embed = {
     provider: 'GIF',
     kind: 'gif',
     src: 'https://example.com/cat.gif',
-    aspect_ratio: '1 / 1',
+    aspect_ratio: null,
     height: null,
     poster: null,
 };
diff --git a/tests/Unit/GifEmbedPlayback.test.tsx b/tests/Unit/GifEmbedPlayback.test.tsx
new file mode 100644
index 000000000..59bffe951
--- /dev/null
+++ b/tests/Unit/GifEmbedPlayback.test.tsx
@@ -0,0 +1,270 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import * as React from 'react';
+import type { ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterAll, afterEach, test, vi } from 'vite-plus/test';
+import type { Embed, LinkPreview } from '../../resources/js/types/commit';
+
+const playback = {
+    isPlaying: true,
+    hasFailed: false,
+    canRetry: false,
+    retryCount: 0,
+    onError: () => {},
+    onToggle: () => {},
+    onRetry: vi.fn(),
+};
+
+let states: unknown[] = [];
+let stateIndex = 0;
+
+vi.doMock('react', () => ({
+    ...React,
+    useRef: (initial: unknown) => ({ current: initial }),
+    useState: (initial: unknown) => {
+        const index = stateIndex++;
+        states[index] ??= typeof initial === 'function' ? initial() : initial;
+
+        return [
+            states[index],
+            (value: unknown) => {
+                states[index] =
+                    typeof value === 'function' ? value(states[index]) : value;
+            },
+        ];
+    },
+}));
+
+vi.doMock('../../resources/js/hooks/use-gif-playback', () => ({
+    useGifPlayback: () => playback,
+}));
+
+const { GifEmbed } = await import('../../resources/js/components/gif-embed');
+
+afterAll(() => vi.doUnmock('../../resources/js/hooks/use-gif-playback'));
+afterEach(() => {
+    playback.isPlaying = true;
+    playback.hasFailed = false;
+    playback.canRetry = false;
+    playback.retryCount = 0;
+    playback.onRetry.mockClear();
+    states = [];
+    stateIndex = 0;
+});
+
+const preview: LinkPreview = {
+    url: 'https://giphy.com/gifs/cat',
+    title: null,
+    description: null,
+    image_url: null,
+    site_name: null,
+    is_pending: false,
+};
+
+const embed: Embed = {
+    provider: 'GIPHY',
+    kind: 'gif',
+    src: 'https://media.giphy.com/media/cat/giphy.gif',
+    poster: 'https://media.giphy.com/media/cat/giphy_s.gif',
+    aspect_ratio: null,
+    height: null,
+};
+
+function render(current: Embed = embed): string {
+    startRender();
+
+    return renderToStaticMarkup(<GifEmbed preview={preview} embed={current} />);
+}
+
+function startRender() {
+    stateIndex = 0;
+}
+
+function startPlaybackSession() {
+    states = [];
+    startRender();
+}
+
+function animation(
+    current: Embed = embed,
+): ReactElement<ImgHTMLAttributes<HTMLImageElement>> {
+    const content = mediaContent(current);
+    const image = React.Children.toArray(
+        content.props.children,
+    )[1] as ReactElement<{
+        preview: LinkPreview;
+        embed: Embed;
+        playback: typeof playback;
+    }>;
+
+    return (
+        image.type as (
+            props: typeof image.props,
+        ) => ReactElement<ImgHTMLAttributes<HTMLImageElement>>
+    )(image.props);
+}
+
+function frame(current: Embed = embed): ReactElement<{ children: ReactNode }> {
+    startRender();
+    const card = GifEmbed({ preview, embed: current }) as ReactElement<{
+        children: ReactNode;
+    }>;
+    return React.Children.toArray(card.props.children)[0] as ReactElement<{
+        children: ReactNode;
+    }>;
+}
+
+function mediaContent(
+    current: Embed = embed,
+): ReactElement<{ children: ReactNode }> {
+    const media = React.Children.toArray(
+        frame(current).props.children,
+    )[0] as ReactElement<{
+        preview: LinkPreview;
+        embed: Embed;
+        playback: typeof playback;
+    }>;
+
+    return (
+        media.type as (props: typeof media.props) => ReactElement<{
+            children: ReactNode;
+        }>
+    )(media.props);
+}
+
+test('keeps the static poster underneath an animation that has not loaded', () => {
+    const html = render();
+
+    assert.ok(html.includes('data-test="gif-poster"'));
+    assert.match(
+        html,
+        /<img[^>]*class="[^"]*invisible[^>]*data-test="gif-animation"/,
+    );
+});
+
+test('keeps the direct GIF placeholder while its animation loads', () => {
+    const html = render({ ...embed, poster: null });
+
+    assert.match(html, /<span class="absolute[^>]*>GIF<\/span>/);
+    assert.match(
+        html,
+        /<img[^>]*class="[^"]*invisible[^>]*data-test="gif-animation"/,
+    );
+});
+
+test('shows a loaded animation and starts a fresh playback session hidden', () => {
+    const loading = animation();
+
+    assert.match(String(loading.props.className), /invisible/);
+    loading.props.onLoad?.({} as React.SyntheticEvent<HTMLImageElement>);
+
+    const loaded = animation();
+
+    assert.doesNotMatch(String(loaded.props.className), /invisible/);
+
+    startPlaybackSession();
+
+    const restarted = animation({ ...embed, src: `${embed.src}?restart=1` });
+
+    assert.match(String(restarted.props.className), /invisible/);
+});
+
+test('Stop and offscreen states unload the animation and retain the poster', () => {
+    playback.isPlaying = false;
+    const html = render();
+
+    assert.ok(html.includes('data-test="gif-poster"'));
+    assert.ok(!html.includes('data-test="gif-animation"'));
+    assert.ok(html.includes('aria-label="Play GIF"'));
+});
+
+test('a failed animation retains the card and reports its failure', () => {
+    playback.isPlaying = false;
+    playback.hasFailed = true;
+    const html = render();
+
+    assert.ok(html.includes('aspect-square'));
+    assert.ok(html.includes('GIF could not load'));
+    assert.ok(!html.includes('<img'));
+    assert.ok(!html.includes('<button'));
+});
+
+test('a failed GIF offers a visible retry control while attempts remain', () => {
+    playback.isPlaying = false;
+    playback.hasFailed = true;
+    playback.canRetry = true;
+    const html = render();
+
+    assert.ok(html.includes('GIF could not load'));
+    assert.ok(html.includes('aria-label="Retry GIF"'));
+    assert.ok(!html.includes('opacity-0'));
+    assert.ok(!html.includes('data-test="gif-animation"'));
+});
+
+test('the retry control invokes retry rather than toggling playback', () => {
+    playback.isPlaying = false;
+    playback.hasFailed = true;
+    playback.canRetry = true;
+    const control = React.Children.toArray(
+        frame().props.children,
+    )[1] as ReactElement<{
+        embed: Embed;
+        playback: typeof playback;
+        isStatic: boolean;
+    }>;
+    const button = (
+        control.type as (props: typeof control.props) => ReactElement<{
+            onClick: () => void;
+        }>
+    )(control.props);
+    button.props.onClick();
+
+    assert.equal(playback.onRetry.mock.calls.length, 1);
+});
+
+test('retry keeps the verified animation and poster URLs unchanged', () => {
+    playback.retryCount = 1;
+    const html = render();
+
+    assert.ok(html.includes(`src="${embed.src}"`));
+    assert.ok(html.includes(`src="${embed.poster}"`));
+});
+
+test('poster failures survive Stop and visibility changes but reset on manual retry or new media', () => {
+    playback.isPlaying = false;
+    const fallback = React.Children.toArray(
+        mediaContent().props.children,
+    )[0] as ReactElement<{
+        preview: LinkPreview;
+        embed: Embed;
+        playback: typeof playback;
+    }>;
+    const poster = (
+        fallback.type as (
+            props: typeof fallback.props,
+        ) => ReactElement<ImgHTMLAttributes<HTMLImageElement>>
+    )(fallback.props);
+    poster.props.onError?.({} as React.SyntheticEvent<HTMLImageElement>);
+
+    assert.ok(!render().includes('data-test="gif-poster"'));
+    playback.isPlaying = true;
+    assert.ok(!render().includes('data-test="gif-poster"'));
+    const unchanged = React.Children.toArray(
+        mediaContent().props.children,
+    )[0] as ReactElement;
+    assert.equal(unchanged.key, fallback.key);
+
+    playback.retryCount = 1;
+    const retried = React.Children.toArray(
+        mediaContent().props.children,
+    )[0] as ReactElement;
+    assert.notEqual(retried.key, fallback.key);
+    const changed = React.Children.toArray(
+        mediaContent({
+            ...embed,
+            poster: 'https://media.giphy.com/media/dog/giphy_s.gif',
+        }).props.children,
+    )[0] as ReactElement;
+    assert.notEqual(changed.key, retried.key);
+});
diff --git a/tests/Unit/GifPlayback.test.ts b/tests/Unit/GifPlayback.test.ts
index d435b6b05..5a76b1986 100644
--- a/tests/Unit/GifPlayback.test.ts
+++ b/tests/Unit/GifPlayback.test.ts
@@ -1,7 +1,18 @@
 /// <reference types="node" />
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
-import { canLoadGifPoster, isGifPlaying, isGifUrl } from '../../resources/js/lib/gifs.ts';
+import {
+    canLoadGifPoster,
+    canRetryGifLoad,
+    failGifLoad,
+    hasGifLoadFailed,
+    isGifPlaying,
+    isGifUrl,
+    MAX_GIF_RETRIES,
+    retryGifLoad,
+    syncGifLoadRetryState,
+    type GifLoadRetryState,
+} from '../../resources/js/lib/gifs.ts';
 
 const validGifUrls = [
     'https://example.com/animation.gif',
@@ -34,7 +45,6 @@ const invalidGifUrls = [
 for (const url of invalidGifUrls) {
     void test(`does not treat an unsupported link as a GIF: ${url}`, () => {
         assert.equal(isGifUrl(url), false);
-        assert.equal(isGifPlaying({ ...playback, source: url }), false);
     });
 }
 
@@ -52,6 +62,24 @@ void test('autoplays visible GIFs and suspends them outside the viewport', () =>
     assert.equal(isGifPlaying({ ...playback, isVisible: false }), false);
 });
 
+void test('autoplays a server-verified GIF after an extensionless redirect', () => {
+    const source = 'https://www.example.com/media?id=cat';
+
+    assert.equal(isGifUrl(source), false);
+    assert.equal(isGifPlaying({ ...playback, source }), true);
+});
+
+for (const source of [
+    'not a URL',
+    'http://example.com/media?id=cat',
+    'https://user:secret@example.com/media?id=cat',
+    'https://example.com:8443/media?id=cat',
+]) {
+    void test(`does not autoplay an unsafe verified GIF source: ${source}`, () => {
+        assert.equal(isGifPlaying({ ...playback, source }), false);
+    });
+}
+
 void test('reduced motion requires an explicit Play action', () => {
     assert.equal(isGifPlaying({ ...playback, reducedMotion: true }), false);
     assert.equal(
@@ -84,7 +112,10 @@ void test('static cards and failed GIFs never animate, even after Play', () => {
 });
 
 void test('only canonical Giphy media can supply a static poster', () => {
-    assert.equal(canLoadGifPoster('https://media.giphy.com/media/cat/giphy.gif'), true);
+    assert.equal(
+        canLoadGifPoster('https://media.giphy.com/media/cat/giphy.gif'),
+        true,
+    );
     for (const source of [
         'https://example.com/cat.gif',
         'https://media.giphy.com.attacker.example/cat.gif',
@@ -105,8 +136,85 @@ void test('external GIFs autoplay while visible and respect playback preferences
     assert.equal(isGifPlaying(external), true);
     assert.equal(isGifPlaying({ ...external, isVisible: false }), false);
     assert.equal(isGifPlaying({ ...external, reducedMotion: true }), false);
-    assert.equal(isGifPlaying({ ...external, reducedMotion: true, playback: 'play' }), true);
+    assert.equal(
+        isGifPlaying({ ...external, reducedMotion: true, playback: 'play' }),
+        true,
+    );
     assert.equal(isGifPlaying({ ...external, playback: 'play' }), true);
     assert.equal(isGifPlaying({ ...external, playback: 'stop' }), false);
-    assert.equal(isGifPlaying({ ...external, playback: 'play', isVisible: false }), false);
+    assert.equal(
+        isGifPlaying({ ...external, playback: 'play', isVisible: false }),
+        false,
+    );
+});
+
+void test('a failed GIF stays stopped until the user retries it', () => {
+    const source = 'https://example.com/cat.gif';
+    const failed = failGifLoad(
+        { source, failedSource: null, retryCount: 0, playback: 'auto' },
+        source,
+    );
+
+    assert.equal(hasGifLoadFailed(failed, source), true);
+    assert.equal(isGifPlaying({ ...playback, source, hasFailed: true }), false);
+    assert.equal(canRetryGifLoad(failed, source), true);
+
+    const retried = retryGifLoad(failed, source);
+    assert.equal(hasGifLoadFailed(retried, source), false);
+    assert.equal(retried.retryCount, 1);
+    assert.equal(retried.playback, 'play');
+});
+
+void test('a new GIF source gets a fresh retry budget without changing playback preference', () => {
+    const source = 'https://example.com/cat.gif';
+    const replacement = 'https://example.com/dog.gif';
+    const failed = failGifLoad(
+        {
+            source,
+            failedSource: null,
+            retryCount: MAX_GIF_RETRIES,
+            playback: 'stop',
+        },
+        source,
+    );
+
+    const replacementState = syncGifLoadRetryState(failed, replacement);
+    assert.equal(hasGifLoadFailed(replacementState, replacement), false);
+    assert.equal(replacementState.retryCount, 0);
+    assert.equal(replacementState.playback, 'stop');
+    assert.equal(canRetryGifLoad(replacementState, replacement), false);
+
+    const failedReplacement = failGifLoad(replacementState, replacement);
+    assert.equal(canRetryGifLoad(failedReplacement, replacement), true);
+
+    const originalState = syncGifLoadRetryState(failedReplacement, source);
+    assert.equal(hasGifLoadFailed(originalState, source), false);
+    assert.equal(originalState.retryCount, 0);
+    assert.equal(canRetryGifLoad(originalState, source), false);
+});
+
+void test('GIF retries are bounded and stale failures cannot affect a replacement source', () => {
+    const source = 'https://example.com/cat.gif';
+    const replacement = 'https://example.com/dog.gif';
+    let state: GifLoadRetryState = {
+        source,
+        failedSource: null,
+        retryCount: 0,
+        playback: 'auto' as const,
+    };
+
+    for (let retry = 0; retry < MAX_GIF_RETRIES; retry++) {
+        state = failGifLoad(state, source);
+        assert.equal(canRetryGifLoad(state, source), true);
+        state = retryGifLoad(state, source);
+    }
+
+    state = failGifLoad(state, source);
+    assert.equal(hasGifLoadFailed(state, source), true);
+    assert.equal(canRetryGifLoad(state, source), false);
+    assert.equal(retryGifLoad(state, source), state);
+
+    const active = syncGifLoadRetryState(state, replacement);
+    assert.equal(failGifLoad(active, source), active);
+    assert.equal(hasGifLoadFailed(active, replacement), false);
 });
diff --git a/tests/Unit/GifPlaybackHook.test.tsx b/tests/Unit/GifPlaybackHook.test.tsx
new file mode 100644
index 000000000..1b197cf19
--- /dev/null
+++ b/tests/Unit/GifPlaybackHook.test.tsx
@@ -0,0 +1,181 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import * as React from 'react';
+import { afterAll, afterEach, test, vi } from 'vite-plus/test';
+import type { Embed } from '../../resources/js/types/commit';
+
+let states: unknown[] = [];
+let stateIndex = 0;
+let didUpdate = false;
+let effects: (() => void | (() => void))[] = [];
+let reducedMotion = false;
+let setVisible: (visible: boolean) => void;
+
+vi.doMock('react', () => ({
+    ...React,
+    useEffect: (effect: () => void | (() => void)) => effects.push(effect),
+    useState: (initial: unknown) => {
+        const index = stateIndex++;
+        states[index] ??= typeof initial === 'function' ? initial() : initial;
+
+        return [
+            states[index],
+            (update: unknown) => {
+                const next =
+                    typeof update === 'function'
+                        ? update(states[index])
+                        : update;
+                didUpdate ||= next !== states[index];
+                states[index] = next;
+            },
+        ];
+    },
+}));
+
+vi.doMock('../../resources/js/hooks/use-media-query', () => ({
+    useMediaQuery: () => reducedMotion,
+}));
+
+vi.stubGlobal(
+    'IntersectionObserver',
+    class {
+        constructor(callback: IntersectionObserverCallback) {
+            setVisible = (visible) =>
+                callback(
+                    [
+                        {
+                            isIntersecting: visible,
+                            intersectionRatio: visible ? 1 : 0,
+                        } as IntersectionObserverEntry,
+                    ],
+                    this as unknown as IntersectionObserver,
+                );
+        }
+
+        observe() {}
+        disconnect() {}
+    },
+);
+
+const { useGifPlayback } =
+    await import('../../resources/js/hooks/use-gif-playback');
+
+afterAll(() => vi.unstubAllGlobals());
+afterEach(() => {
+    states = [];
+    stateIndex = 0;
+    effects = [];
+    reducedMotion = false;
+});
+
+const embed: Embed = {
+    provider: 'GIF',
+    kind: 'gif',
+    src: 'https://example.com/cat.gif',
+    poster: null,
+    aspect_ratio: null,
+    height: null,
+};
+const container = { current: {} as HTMLDivElement };
+
+function render(current: Embed = embed) {
+    let result: ReturnType<typeof useGifPlayback>;
+    let renders = 0;
+
+    do {
+        assert.ok(
+            renders++ < 10,
+            'source state must settle without a render loop',
+        );
+        didUpdate = false;
+        stateIndex = 0;
+        result = useGifPlayback({ embed: current, isStatic: false, container });
+    } while (didUpdate);
+
+    return result;
+}
+
+function mount() {
+    render();
+    effects.shift()?.();
+    setVisible(true);
+
+    return render();
+}
+
+test('only manual retry clears a failure and the hook enforces two extra attempts', () => {
+    mount().onError();
+    let playback = render();
+
+    assert.equal(playback.hasFailed, true);
+    assert.equal(playback.isPlaying, false);
+    assert.equal(playback.canRetry, true);
+
+    setVisible(false);
+    render();
+    setVisible(true);
+    playback = render();
+    assert.equal(playback.hasFailed, true);
+    assert.equal(playback.isPlaying, false);
+
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        playback.onRetry();
+        playback = render();
+        assert.equal(playback.hasFailed, false);
+        assert.equal(playback.isPlaying, true);
+        assert.equal(playback.retryCount, attempt);
+        playback.onError();
+        playback = render();
+    }
+
+    assert.equal(playback.canRetry, false);
+    playback.onRetry();
+    playback = render();
+    assert.equal(playback.hasFailed, true);
+    assert.equal(playback.isPlaying, false);
+    assert.equal(playback.retryCount, 2);
+});
+
+test('changing sources clears failure and the retry budget without stale error leakage', () => {
+    const first = mount();
+    first.onError();
+    render().onRetry();
+    render().onError();
+    const failedFirst = render();
+    const next = { ...embed, src: 'https://example.com/dog.gif' };
+    let playback = render(next);
+
+    assert.equal(playback.hasFailed, false);
+    assert.equal(playback.isPlaying, true);
+    assert.equal(playback.retryCount, 0);
+
+    first.onError();
+    playback = render(next);
+    assert.equal(playback.hasFailed, false);
+    playback.onToggle();
+    failedFirst.onRetry();
+    playback = render(next);
+    assert.equal(playback.isPlaying, false);
+    assert.equal(playback.retryCount, 0);
+    playback.onError();
+    assert.equal(render(next).hasFailed, true);
+    playback = render();
+    assert.equal(playback.hasFailed, false);
+    assert.equal(playback.retryCount, 0);
+});
+
+test('retry is explicit playback for reduced motion and source changes retain Stop', () => {
+    reducedMotion = true;
+    let playback = mount();
+    assert.equal(playback.isPlaying, false);
+    playback.onToggle();
+    playback = render();
+    assert.equal(playback.isPlaying, true);
+    playback.onError();
+    render().onRetry();
+    playback = render();
+    assert.equal(playback.isPlaying, true);
+    playback.onToggle();
+    playback = render({ ...embed, src: 'https://example.com/dog.gif' });
+    assert.equal(playback.isPlaying, false);
+});
diff --git a/tests/Unit/Services/EmbedProviders/GiphyTest.php b/tests/Unit/Services/EmbedProviders/GiphyTest.php
index c098e9ba8..264b5c3b1 100644
--- a/tests/Unit/Services/EmbedProviders/GiphyTest.php
+++ b/tests/Unit/Services/EmbedProviders/GiphyTest.php
@@ -10,7 +10,7 @@
         'provider' => 'GIPHY',
         'kind' => 'gif',
         'src' => 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif',
-        'aspect_ratio' => '1 / 1',
+        'aspect_ratio' => null,
         'height' => null,
         'poster' => 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy_s.gif',
     ]);
@@ -21,6 +21,7 @@
     'uppercase section' => 'https://giphy.com/GIFS/cat-JIX9t2j0ZTN9S',
     'query and fragment' => 'https://giphy.com/gifs/cat-JIX9t2j0ZTN9S?tracking=ignored#ignored',
     'http link' => 'http://giphy.com/gifs/JIX9t2j0ZTN9S',
+    'explicit default HTTPS port' => 'https://giphy.com:443/gifs/JIX9t2j0ZTN9S',
 ]);
 
 it('does not embed malformed links or untrusted hosts', function (string $url): void {
diff --git a/tests/Unit/Services/EmbedsTest.php b/tests/Unit/Services/EmbedsTest.php
index c428faa66..ebaf34f88 100644
--- a/tests/Unit/Services/EmbedsTest.php
+++ b/tests/Unit/Services/EmbedsTest.php
@@ -15,7 +15,7 @@
             'provider' => 'GIF',
             'kind' => 'gif',
             'src' => 'https://cdn.example.com/cat.gif',
-            'aspect_ratio' => '1 / 1',
+            'aspect_ratio' => null,
             'height' => null,
             'poster' => null,
         ]);
diff --git a/tests/draft-images.config.ts b/tests/draft-images.config.ts
index 7f30e0d45..41cdb5729 100644
--- a/tests/draft-images.config.ts
+++ b/tests/draft-images.config.ts
@@ -10,6 +10,8 @@ export default defineConfig({
     test: {
         include: [
             'tests/Unit/GifEmbed.test.tsx',
+            'tests/Unit/GifEmbedPlayback.test.tsx',
+            'tests/Unit/GifPlaybackHook.test.tsx',
             'tests/Unit/CommitPhoto.test.tsx',
             'tests/Unit/CommitSize.test.tsx',
             'tests/Unit/ThreadHistory.test.tsx',
diff --git a/tests/tsconfig.json b/tests/tsconfig.json
index 7e3a1fcbc..21be43335 100644
--- a/tests/tsconfig.json
+++ b/tests/tsconfig.json
@@ -9,6 +9,8 @@
     "include": [
         "Unit/**/*.test.ts",
         "Unit/GifEmbed.test.tsx",
+        "Unit/GifEmbedPlayback.test.tsx",
+        "Unit/GifPlaybackHook.test.tsx",
         "Unit/CommitPhoto.test.tsx",
         "Unit/DraftStash.test.tsx",
         "Unit/ComposerDraft.test.tsx",

From 61056e3f5746ca6576ff3f3f9eb882f2f60300d2 Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:17:54 -0400
Subject: [PATCH 19/25] fix: bound publication retries and serialize unfurl
 workers

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 app/Actions/CreateCommit.php                  | 16 ++--
 app/Actions/CreateLinkPreviewJob.php          | 31 +++++++
 app/Actions/CreateMessage.php                 | 15 ++--
 app/Actions/UpdateLinkPreview.php             | 10 +--
 app/Jobs/UnfurlLink.php                       | 44 ++++++---
 app/Models/LinkPreview.php                    | 55 ++++++++++++
 database/factories/LinkPreviewFactory.php     |  1 +
 ...dd_unfurl_state_to_link_previews_table.php | 18 ++++
 .../ConversationMessageControllerTest.php     | 47 ++++++++++
 tests/Fixtures/unfurl-link.php                | 50 +++++++++++
 tests/Mutation/php-gif-mutations.ts           | 28 ++++++
 tests/Unit/Actions/CreateCommitTest.php       | 85 ++++++++++++++++++
 .../Unit/Actions/CreateLinkPreviewJobTest.php | 44 +++++++++
 tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php | 89 +++++++++++++++++++
 tests/Unit/Jobs/UnfurlLinkTest.php            | 62 +++++++++++++
 tests/Unit/Models/LinkPreviewTest.php         | 35 ++++++++
 16 files changed, 587 insertions(+), 43 deletions(-)
 create mode 100644 app/Actions/CreateLinkPreviewJob.php
 create mode 100644 database/migrations/2026_10_20_130000_add_unfurl_state_to_link_previews_table.php
 create mode 100644 tests/Fixtures/unfurl-link.php
 create mode 100644 tests/Unit/Actions/CreateLinkPreviewJobTest.php
 create mode 100644 tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php

diff --git a/app/Actions/CreateCommit.php b/app/Actions/CreateCommit.php
index 6dfb586a4..e7dcbb56d 100644
--- a/app/Actions/CreateCommit.php
+++ b/app/Actions/CreateCommit.php
@@ -10,7 +10,6 @@
 use App\Jobs\EmbedCommit;
 use App\Jobs\ModerateCommit;
 use App\Jobs\ReplyAsTom;
-use App\Jobs\UnfurlLink;
 use App\Models\Commit;
 use App\Models\LinkPreview;
 use App\Models\User;
@@ -30,6 +29,7 @@ public function __construct(
         private CreateMentionNotifications $createMentionNotifications,
         private CreateCommitImages $createCommitImages,
         private CreateWorldReply $createWorldReply,
+        private CreateLinkPreviewJob $createLinkPreviewJob,
         private UpdateCommitHotScores $updateCommitHotScores,
         private TheAlgorithm $theAlgorithm,
         private EmojiShortcodes $emojiShortcodes,
@@ -41,8 +41,6 @@ public function __construct(
     }
 
     /**
-     * The link preview is of the first URL in the body when true, of the given URL when a string, or none when false.
-     *
      * @param  list<UploadedFile>  $images
      * @param  array<int, string|null>  $imageDescriptions
      */
@@ -85,8 +83,10 @@ public function handle(User $user, string $body, ?Commit $parent = null, ?Commit
             $this->createQuoteNotifications->handle($commit);
             $this->createMentionNotifications->handle($commit);
 
-            if ($linkPreview instanceof LinkPreview && $linkPreview->fetched_at === null) {
-                dispatch(new UnfurlLink($linkPreview));
+            if ($linkPreview instanceof LinkPreview && $linkPreview->prepareUnfurlForPublication()) {
+                DB::afterCommit(function () use ($linkPreview): void {
+                    $this->createLinkPreviewJob->handle($linkPreview);
+                });
             }
 
             $this->createWorldReply->handle($commit);
@@ -118,9 +118,6 @@ public function handle(User $user, string $body, ?Commit $parent = null, ?Commit
         });
     }
 
-    /**
-     * A poll opens with its commit's approval, so polls of pending commits wait for moderation.
-     */
     private function createPoll(Commit $commit, NewPoll $newPoll): void
     {
         $poll = $commit->poll()->create([
@@ -135,9 +132,6 @@ private function createPoll(Commit $commit, NewPoll $newPoll): void
         ));
     }
 
-    /**
-     * Commits that link to the same URL share one preview, so a page is fetched once however often it is linked.
-     */
     private function linkPreviewFor(?string $url): ?LinkPreview
     {
         if ($url === null) {
diff --git a/app/Actions/CreateLinkPreviewJob.php b/app/Actions/CreateLinkPreviewJob.php
new file mode 100644
index 000000000..11f8e0803
--- /dev/null
+++ b/app/Actions/CreateLinkPreviewJob.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions;
+
+use App\Jobs\UnfurlLink;
+use App\Models\LinkPreview;
+use Throwable;
+
+final readonly class CreateLinkPreviewJob
+{
+    public function handle(LinkPreview $linkPreview): void
+    {
+        $preview = $linkPreview->fresh();
+
+        if (! $preview instanceof LinkPreview || $preview->fetched_at !== null) {
+            return;
+        }
+
+        $job = new UnfurlLink($preview);
+
+        try {
+            dispatch($job)->afterCommit();
+        } catch (Throwable $throwable) {
+            $job->failed();
+
+            throw $throwable;
+        }
+    }
+}
diff --git a/app/Actions/CreateMessage.php b/app/Actions/CreateMessage.php
index d8662c8c2..b7e0c208f 100644
--- a/app/Actions/CreateMessage.php
+++ b/app/Actions/CreateMessage.php
@@ -5,7 +5,6 @@
 namespace App\Actions;
 
 use App\Enums\RemoteStatus;
-use App\Jobs\UnfurlLink;
 use App\Models\Conversation;
 use App\Models\ConversationParticipant;
 use App\Models\LinkPreview;
@@ -26,13 +25,11 @@ public function __construct(
         private CreateCommitImageFiles $createCommitImageFiles,
         private MentionedUsersQuery $mentionedUsers,
         private Urls $urls,
+        private CreateLinkPreviewJob $createLinkPreviewJob,
     ) {
         //
     }
 
-    /**
-     * Makes the message the conversation's latest, for every member's inbox.
-     */
     public static function advance(Conversation $conversation, Message $message, bool $unstash): void
     {
         Conversation::query()
@@ -46,10 +43,6 @@ public static function advance(Conversation $conversation, Message $message, boo
     }
 
     /**
-     * Sending the same client id again, as a retry does, returns the message it already created, without storing its
-     * images twice. A new message brings the conversation back out of the stash for everyone in it. The link card is
-     * of the first link in the body when true, of the given link when a string, or none when false.
-     *
      * @param  list<UploadedFile>  $images
      * @param  array<int, string|null>  $imageDescriptions
      */
@@ -94,8 +87,10 @@ public function handle(User $sender, Conversation $conversation, string $body, s
                 ->where('read_through_id', '<', $message->id)
                 ->update(['read_through_id' => $message->id, 'read_at' => now()]);
 
-            if ($linkPreview instanceof LinkPreview && $linkPreview->fetched_at === null) {
-                dispatch(new UnfurlLink($linkPreview))->afterCommit();
+            if ($linkPreview instanceof LinkPreview && $linkPreview->prepareUnfurlForPublication()) {
+                DB::afterCommit(function () use ($linkPreview): void {
+                    $this->createLinkPreviewJob->handle($linkPreview);
+                });
             }
 
             return $message;
diff --git a/app/Actions/UpdateLinkPreview.php b/app/Actions/UpdateLinkPreview.php
index f520103fb..532c1e6fa 100644
--- a/app/Actions/UpdateLinkPreview.php
+++ b/app/Actions/UpdateLinkPreview.php
@@ -39,21 +39,13 @@ public function __construct(
         //
     }
 
-    /**
-     * Fetches the page behind the link and stores its Open Graph metadata. A page that can't or mustn't be fetched is
-     * marked as fetched without metadata, so it is not tried again. Failures that may pass, such as connection errors,
-     * timeouts, rate limits and server errors, are thrown instead, so the caller can try again later.
-     */
     public function handle(LinkPreview $linkPreview): void
     {
         $metadata = $this->fetchMetadata($linkPreview->url);
 
-        $linkPreview->update([...$metadata->toArray(), 'fetched_at' => now()]);
+        $linkPreview->completeUnfurl($metadata->toArray());
     }
 
-    /**
-     * Follows up to three redirects by hand, so that every hop goes through the same checks as the original URL.
-     */
     private function fetchMetadata(string $url): LinkPreviewMetadata
     {
         $page = Url::parse($url);
diff --git a/app/Jobs/UnfurlLink.php b/app/Jobs/UnfurlLink.php
index 7ce7f47b2..3bddaa1f5 100644
--- a/app/Jobs/UnfurlLink.php
+++ b/app/Jobs/UnfurlLink.php
@@ -6,41 +6,59 @@
 
 use App\Actions\UpdateLinkPreview;
 use App\Models\LinkPreview;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
 use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Foundation\Queue\Queueable;
 use Illuminate\Queue\Attributes\Backoff;
 use Illuminate\Queue\Attributes\DeleteWhenMissingModels;
 use Illuminate\Queue\Attributes\Tries;
+use Illuminate\Support\Facades\DB;
 
 #[Backoff([60, 600])]
 #[Tries(3)]
 #[DeleteWhenMissingModels]
-final class UnfurlLink implements ShouldQueue
+final class UnfurlLink implements ShouldBeUnique, ShouldQueue
 {
     use Queueable;
 
+    // Allow foreign-key references while serializing workers.
+    private const string METADATA_LOCK = 'for no key update';
+
+    // Default supports older queued payloads.
+    public int $publicationUnfurlRetries = 0;
+
     public function __construct(public readonly LinkPreview $linkPreview)
     {
-        //
+        if ($linkPreview->publication_unfurl_retries === 0) {
+            return;
+        }
+
+        $this->publicationUnfurlRetries = $linkPreview->publication_unfurl_retries;
+    }
+
+    public function uniqueId(): string
+    {
+        return $this->linkPreview->id;
     }
 
-    /**
-     * Commits that share a link may each queue this job before the first one runs, so only the first one fetches.
-     */
     public function handle(UpdateLinkPreview $action): void
     {
-        if ($this->linkPreview->fetched_at !== null) {
-            return;
-        }
+        DB::transaction(function () use ($action): void {
+            $linkPreview = LinkPreview::query()->lock(self::METADATA_LOCK)->find($this->linkPreview->id);
+
+            if (! $linkPreview instanceof LinkPreview
+                || $linkPreview->fetched_at !== null
+                || $linkPreview->publication_unfurl_retries !== $this->publicationUnfurlRetries
+            ) {
+                return;
+            }
 
-        $action->handle($this->linkPreview);
+            $action->handle($linkPreview);
+        });
     }
 
-    /**
-     * Once every attempt has failed, the link preview is marked as fetched without metadata, so it is not tried again.
-     */
     public function failed(): void
     {
-        $this->linkPreview->update(['fetched_at' => now()]);
+        $this->linkPreview->markUnfurlAsTransientFailure($this->publicationUnfurlRetries);
     }
 }
diff --git a/app/Models/LinkPreview.php b/app/Models/LinkPreview.php
index 3a5b564d0..cdb2e9a7b 100644
--- a/app/Models/LinkPreview.php
+++ b/app/Models/LinkPreview.php
@@ -11,6 +11,7 @@
 use Illuminate\Database\Eloquent\Concerns\HasUuids;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\DB;
 
 /**
  * @property-read string $id
@@ -22,6 +23,8 @@
  * @property-read string|null $site_name
  * @property-read string|null $gif_url
  * @property-read CarbonInterface|null $fetched_at
+ * @property-read CarbonInterface|null $unfurl_failed_at
+ * @property-read int $publication_unfurl_retries
  * @property-read CarbonInterface $created_at
  * @property-read CarbonInterface $updated_at
  */
@@ -39,6 +42,13 @@ final class LinkPreview extends Model
 
     use HasUuids;
 
+    public const int MAX_PUBLICATION_UNFURL_RETRIES = 1;
+
+    /** @var array<string, int> */
+    protected $attributes = [
+        'publication_unfurl_retries' => 0,
+    ];
+
     /**
      * @return array<string, string>
      */
@@ -54,11 +64,56 @@ public function casts(): array
             'site_name' => 'string',
             'gif_url' => 'string',
             'fetched_at' => 'datetime',
+            'unfurl_failed_at' => 'datetime',
+            'publication_unfurl_retries' => 'integer',
             'created_at' => 'datetime',
             'updated_at' => 'datetime',
         ];
     }
 
+    public function prepareUnfurlForPublication(): bool
+    {
+        if ($this->fetched_at === null) {
+            return true;
+        }
+
+        return $this->retryTransientFailureForPublication();
+    }
+
+    public function retryTransientFailureForPublication(): bool
+    {
+        return self::query()
+            ->whereKey($this->id)
+            ->whereNotNull('unfurl_failed_at')
+            ->where('publication_unfurl_retries', '<', self::MAX_PUBLICATION_UNFURL_RETRIES)
+            ->update([
+                'fetched_at' => null,
+                'unfurl_failed_at' => null,
+                'publication_unfurl_retries' => DB::raw('publication_unfurl_retries + 1'),
+            ]) === 1;
+    }
+
+    /**
+     * @param  array<string, string|null>  $metadata
+     */
+    public function completeUnfurl(array $metadata): bool
+    {
+        return self::query()
+            ->whereKey($this->id)
+            ->where('publication_unfurl_retries', $this->publication_unfurl_retries)
+            ->whereNull('fetched_at')
+            ->update([...$metadata, 'fetched_at' => now(), 'unfurl_failed_at' => null]) === 1;
+    }
+
+    public function markUnfurlAsTransientFailure(int $publicationUnfurlRetries): void
+    {
+        self::query()
+            ->whereKey($this->id)
+            ->where('publication_unfurl_retries', $publicationUnfurlRetries)
+            ->whereNull('fetched_at')
+            ->update(['fetched_at' => now(), 'unfurl_failed_at' => now()]);
+    }
+
     /**
      * @return array<mixed>
      */
diff --git a/database/factories/LinkPreviewFactory.php b/database/factories/LinkPreviewFactory.php
index 49d5ccdb2..a61d83a3d 100644
--- a/database/factories/LinkPreviewFactory.php
+++ b/database/factories/LinkPreviewFactory.php
@@ -50,6 +50,7 @@ public function failed(): self
     {
         return $this->state(fn (array $attributes): array => [
             'fetched_at' => now(),
+            'unfurl_failed_at' => now(),
         ]);
     }
 }
diff --git a/database/migrations/2026_10_20_130000_add_unfurl_state_to_link_previews_table.php b/database/migrations/2026_10_20_130000_add_unfurl_state_to_link_previews_table.php
new file mode 100644
index 000000000..a540093d8
--- /dev/null
+++ b/database/migrations/2026_10_20_130000_add_unfurl_state_to_link_previews_table.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('link_previews', function (Blueprint $table): void {
+            $table->timestamp('unfurl_failed_at')->nullable()->after('fetched_at');
+            $table->unsignedTinyInteger('publication_unfurl_retries')->default(0)->after('unfurl_failed_at');
+        });
+    }
+};
diff --git a/tests/Feature/Controllers/ConversationMessageControllerTest.php b/tests/Feature/Controllers/ConversationMessageControllerTest.php
index f758ad103..57f523a45 100644
--- a/tests/Feature/Controllers/ConversationMessageControllerTest.php
+++ b/tests/Feature/Controllers/ConversationMessageControllerTest.php
@@ -2,13 +2,16 @@
 
 declare(strict_types=1);
 
+use App\Actions\UpdateLinkPreview;
 use App\Jobs\UnfurlLink;
 use App\Models\Conversation;
+use App\Models\LinkPreview;
 use App\Models\Message;
 use App\Models\User;
 use Illuminate\Http\UploadedFile;
 use Illuminate\Support\Facades\Crypt;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Queue;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
@@ -222,6 +225,50 @@
     'no card' => [['link_preview_url' => ''], null],
 ]);
 
+it('retries a failed draft preview when it is sent in a message', function (): void {
+    Queue::fake();
+    $url = 'https://93.184.216.34/retry';
+    Http::fake([$url => Http::response('<title>Back online</title>', 200, ['Content-Type' => 'text/html'])]);
+    $preview = LinkPreview::factory()->failed()->create(['url' => $url]);
+    $sender = User::factory()->withRemotes()->create();
+    $recipient = User::factory()->withRemotes()->create();
+
+    $this->actingAs($sender)->postJson(route('conversation-message.store', $recipient), [
+        'body' => 'Look at '.$url,
+        'client_id' => Str::uuid()->toString(),
+    ])->assertCreated()
+        ->assertJsonPath('message.link_preview.is_pending', true);
+
+    $messagePreview = LinkPreview::query()->findOrFail($preview->id);
+
+    expect($messagePreview)
+        ->id->toBe($preview->id)
+        ->fetched_at->toBeNull();
+    Queue::assertPushed(UnfurlLink::class, fn (UnfurlLink $job): bool => $job->linkPreview->is($preview));
+
+    new UnfurlLink($messagePreview)->handle(resolve(UpdateLinkPreview::class));
+
+    expect($preview->refresh())
+        ->title->toBe('Back online')
+        ->fetched_at->not->toBeNull();
+});
+
+it('enqueues a draft preview that is already pending when it is sent in a message', function (): void {
+    Queue::fake();
+    $url = 'https://example.com/pending';
+    LinkPreview::factory()->create(['url' => $url]);
+    $sender = User::factory()->withRemotes()->create();
+    $recipient = User::factory()->withRemotes()->create();
+
+    $this->actingAs($sender)->postJson(route('conversation-message.store', $recipient), [
+        'body' => 'Look at '.$url,
+        'client_id' => Str::uuid()->toString(),
+    ])->assertCreated()
+        ->assertJsonPath('message.link_preview.is_pending', true);
+
+    Queue::assertPushed(UnfurlLink::class);
+});
+
 it('refuses a link card for a link that is not in the message', function (): void {
     $mark = User::factory()->withRemotes()->create();
     $nuno = User::factory()->withRemotes()->create();
diff --git a/tests/Fixtures/unfurl-link.php b/tests/Fixtures/unfurl-link.php
new file mode 100644
index 000000000..f1297a648
--- /dev/null
+++ b/tests/Fixtures/unfurl-link.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Actions\UpdateLinkPreview;
+use App\Jobs\UnfurlLink;
+use App\Models\LinkPreview;
+use Illuminate\Contracts\Console\Kernel;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Sleep;
+
+const RELEASE_TIMEOUT_SECONDS = 20;
+const POLL_INTERVAL_MICROSECONDS = 10_000;
+
+require __DIR__.'/../../vendor/autoload.php';
+
+if (($source = getenv('PEST_MUTATION_FILE')) !== false && getenv('PEST_MUTATION_TESTING') === realpath(__DIR__.'/../../app/Jobs/UnfurlLink.php')) {
+    require $source;
+}
+
+$app = require __DIR__.'/../../bootstrap/app.php';
+$app->make(Kernel::class)->bootstrap();
+
+$preview = LinkPreview::query()->findOrFail($argv[1]);
+$directory = $argv[2];
+$isFirst = $argv[3] === 'first';
+$job = new UnfurlLink($preview);
+$pid = DB::selectOne('select pg_backend_pid() as pid')->pid;
+fwrite(STDOUT, "PID:{$pid}\n");
+
+Http::preventStrayRequests();
+Http::fake(function () use ($directory, $isFirst) {
+    file_put_contents($directory.'/requests', "request\n", FILE_APPEND | LOCK_EX);
+
+    if ($isFirst) {
+        fwrite(STDOUT, "FETCHING\n");
+        $deadline = microtime(true) + RELEASE_TIMEOUT_SECONDS;
+
+        while (! is_file($directory.'/release')) {
+            throw_if(microtime(true) > $deadline, RuntimeException::class, 'Concurrent unfurl fixture was not released.');
+
+            Sleep::usleep(POLL_INTERVAL_MICROSECONDS);
+        }
+    }
+
+    return Http::response('<title>Concurrent preview</title>', 200, ['Content-Type' => 'text/html']);
+});
+
+$job->handle($app->make(UpdateLinkPreview::class));
diff --git a/tests/Mutation/php-gif-mutations.ts b/tests/Mutation/php-gif-mutations.ts
index ae8c05f80..a254509f7 100644
--- a/tests/Mutation/php-gif-mutations.ts
+++ b/tests/Mutation/php-gif-mutations.ts
@@ -7,6 +7,34 @@ export type GifMutation = {
 };
 
 export const phpGifMutations: GifMutation[] = [
+    {
+        name: 'concurrent workers must serialize an unfurl',
+        source: 'app/Jobs/UnfurlLink.php',
+        test: 'tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php',
+        before: '->lock(self::METADATA_LOCK)',
+        after: '',
+    },
+    {
+        name: 'unfurl workers must allow foreign-key references',
+        source: 'app/Jobs/UnfurlLink.php',
+        test: 'tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php',
+        before: '->lock(self::METADATA_LOCK)',
+        after: '->lockForUpdate()',
+    },
+    {
+        name: 'publication retries stay bounded',
+        source: 'app/Models/LinkPreview.php',
+        test: 'tests/Unit/Actions/CreateCommitTest.php',
+        before: "            ->where('publication_unfurl_retries', '<', self::MAX_PUBLICATION_UNFURL_RETRIES)\n",
+        after: '',
+    },
+    {
+        name: 'definitive unfurl outcomes remain cached',
+        source: 'app/Models/LinkPreview.php',
+        test: 'tests/Unit/Actions/CreateCommitTest.php',
+        before: "            ->whereNotNull('unfurl_failed_at')\n",
+        after: '',
+    },
     {
         name: 'redirect limit cannot increase',
         source: 'app/Actions/UpdateLinkPreview.php',
diff --git a/tests/Unit/Actions/CreateCommitTest.php b/tests/Unit/Actions/CreateCommitTest.php
index b708c731a..091709ea0 100644
--- a/tests/Unit/Actions/CreateCommitTest.php
+++ b/tests/Unit/Actions/CreateCommitTest.php
@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use App\Actions\CreateCommit;
+use App\Actions\UpdateLinkPreview;
 use App\Dto\NewPoll;
 use App\Enums\CommitStatus;
 use App\Enums\NotificationType;
@@ -18,6 +19,8 @@
 use App\Services\TheAlgorithm;
 use Illuminate\Database\QueryException;
 use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Bus;
+use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Queue;
 use Illuminate\Support\Facades\Storage;
 
@@ -346,6 +349,88 @@
     Queue::assertNothingPushed();
 });
 
+it('keeps a definitive empty draft preview cached when it is published', function (): void {
+    Queue::fake();
+    $url = 'https://93.184.216.34/retry';
+    $preview = LinkPreview::factory()->create(['url' => $url]);
+    Http::fakeSequence('https://93.184.216.34/*')
+        ->push('', 404);
+    new UnfurlLink($preview)->handle(resolve(UpdateLinkPreview::class));
+    expect($preview->refresh())
+        ->title->toBeNull()
+        ->fetched_at->not->toBeNull()
+        ->unfurl_failed_at->toBeNull();
+    Http::assertSentCount(1);
+
+    $commit = resolve(CreateCommit::class)->handle(User::factory()->create(), 'Look at '.$url);
+
+    expect($commit->linkPreview)
+        ->id->toBe($preview->id)
+        ->fetched_at->not->toBeNull()
+        ->toArray()->is_pending->toBeFalse();
+    Queue::assertNothingPushed();
+    Http::assertSentCount(1);
+});
+
+it('retries a transient draft preview only once when it is published', function (): void {
+    Queue::fake();
+    $preview = LinkPreview::factory()->failed()->create(['url' => 'https://example.com/retry']);
+    $action = resolve(CreateCommit::class);
+
+    $action->handle(User::factory()->create(), 'Look at '.$preview->url);
+
+    expect($preview->refresh())
+        ->fetched_at->toBeNull()
+        ->publication_unfurl_retries->toBe(1);
+    Queue::assertPushed(UnfurlLink::class, 1);
+
+    $preview->markUnfurlAsTransientFailure(1);
+    $action->handle(User::factory()->create(), 'Look at '.$preview->url);
+
+    expect($preview->refresh())
+        ->fetched_at->not->toBeNull()
+        ->publication_unfurl_retries->toBe(1);
+    Queue::assertPushed(UnfurlLink::class, 1);
+});
+
+it('queues a new link preview after the commit transaction commits', function (): void {
+    Bus::shouldReceive('dispatch')->once()
+        ->withArgs(function (UnfurlLink $job): bool {
+            expect($job->afterCommit)->toBeTrue();
+
+            return true;
+        })
+        ->andReturnNull();
+
+    resolve(CreateCommit::class)->handle(User::factory()->create(), 'Look at https://example.com/new');
+});
+
+it('enqueues a draft preview that is already pending when it is published', function (): void {
+    Queue::fake();
+    LinkPreview::factory()->create(['url' => 'https://example.com/pending']);
+
+    resolve(CreateCommit::class)->handle(User::factory()->create(), 'Look at https://example.com/pending');
+
+    Queue::assertPushed(UnfurlLink::class);
+});
+
+it('keeps completed GIF preview metadata when it is published', function (): void {
+    Queue::fake();
+    $preview = LinkPreview::factory()->create([
+        'url' => 'https://example.com/cat.gif',
+        'gif_url' => 'https://cdn.example.com/cat.gif',
+        'fetched_at' => now(),
+    ]);
+
+    $commit = resolve(CreateCommit::class)->handle(User::factory()->create(), 'Look at https://example.com/cat.gif');
+
+    expect($commit->linkPreview)
+        ->id->toBe($preview->id)
+        ->gif_url->toBe('https://cdn.example.com/cat.gif')
+        ->fetched_at->not->toBeNull();
+    Queue::assertNothingPushed();
+});
+
 it('queues the link preview for the saved commit', function (): void {
     Queue::fake();
 
diff --git a/tests/Unit/Actions/CreateLinkPreviewJobTest.php b/tests/Unit/Actions/CreateLinkPreviewJobTest.php
new file mode 100644
index 000000000..a5732000b
--- /dev/null
+++ b/tests/Unit/Actions/CreateLinkPreviewJobTest.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Actions\CreateLinkPreviewJob;
+use App\Models\LinkPreview;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Queue;
+
+it('does not queue a preview that completed before its dispatch callback runs', function (): void {
+    Queue::fake();
+    $preview = LinkPreview::factory()->fetched()->create();
+
+    resolve(CreateLinkPreviewJob::class)->handle($preview);
+
+    Queue::assertNothingPushed();
+});
+
+it('does not queue a preview deleted before its dispatch callback runs', function (): void {
+    Queue::fake();
+    $preview = LinkPreview::factory()->create();
+    $preview->delete();
+
+    resolve(CreateLinkPreviewJob::class)->handle($preview);
+
+    Queue::assertNothingPushed();
+});
+
+it('records a transient failure when the queue driver rejects a preview', function (): void {
+    config(['queue.default' => 'database']);
+    Queue::swap(Queue::fake()->queue);
+    DB::connection()->beforeExecuting(function (string $query): void {
+        throw_if(str_starts_with($query, 'insert into "jobs"'), RuntimeException::class, 'Queue unavailable');
+    });
+    $preview = LinkPreview::factory()->create();
+
+    expect(fn () => resolve(CreateLinkPreviewJob::class)->handle($preview))
+        ->toThrow(RuntimeException::class, 'Queue unavailable');
+
+    expect($preview->refresh())
+        ->fetched_at->not->toBeNull()
+        ->unfurl_failed_at->not->toBeNull()
+        ->publication_unfurl_retries->toBe(0);
+});
diff --git a/tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php b/tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php
new file mode 100644
index 000000000..1c037b412
--- /dev/null
+++ b/tests/Unit/Jobs/UnfurlLinkConcurrencyTest.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Models\LinkPreview;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\File;
+use Illuminate\Support\Sleep;
+use Illuminate\Support\Str;
+use Symfony\Component\Process\Process;
+
+const UNFURL_CONCURRENCY_TIMEOUT_SECONDS = 10;
+const UNFURL_LOCK_POLL_MICROSECONDS = 10_000;
+
+it('concurrent duplicate workers fetch a shared preview only once', function (): void {
+    $connection = DB::getDefaultConnection();
+    $settings = config()->array('database.connections.'.$connection);
+    config()->set('database.connections.unfurl_concurrency', $settings);
+    $fixtures = DB::connection('unfurl_concurrency');
+    $id = (string) Str::uuid();
+    $url = 'https://93.184.216.34/concurrent/'.$id;
+    $directory = sys_get_temp_dir().'/unfurl-concurrency-'.$id;
+    File::makeDirectory($directory);
+
+    // A separate connection commits this fixture so both worker processes can see it.
+    $fixtures->table('link_previews')->insert([
+        'id' => $id,
+        'url' => $url,
+        'url_hash' => hash('sha256', $url),
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $environment = [
+        'APP_ENV' => 'testing',
+        'DB_CONNECTION' => $connection,
+        'DB_URL' => '',
+        'DB_HOST' => config()->string('database.connections.'.$connection.'.host'),
+        'DB_PORT' => (string) config('database.connections.'.$connection.'.port'),
+        'DB_DATABASE' => config()->string('database.connections.'.$connection.'.database'),
+        'DB_USERNAME' => config()->string('database.connections.'.$connection.'.username'),
+        'DB_PASSWORD' => config()->string('database.connections.'.$connection.'.password'),
+        'CACHE_STORE' => 'array',
+    ];
+    $fixture = base_path('tests/Fixtures/unfurl-link.php');
+    $first = new Process([PHP_BINARY, $fixture, $id, $directory, 'first'], base_path(), $environment);
+    $second = new Process([PHP_BINARY, $fixture, $id, $directory, 'second'], base_path(), $environment);
+
+    try {
+        Sleep::fake(false);
+        $first->setTimeout(UNFURL_CONCURRENCY_TIMEOUT_SECONDS)->start();
+        $first->waitUntil(static fn (string $type, string $output): bool => $type === Process::OUT && str_contains($output, 'FETCHING'));
+        expect($fixtures->selectOne('select id from link_previews where id = ? for key share nowait', [$id])?->id)->toBe($id);
+        $second->setTimeout(UNFURL_CONCURRENCY_TIMEOUT_SECONDS)->start();
+        $second->waitUntil(static fn (string $type, string $output): bool => $type === Process::OUT && str_contains($output, 'PID:'));
+        throw_unless(preg_match('/PID:(\d+)/', $second->getOutput(), $match) === 1, RuntimeException::class, 'Second worker did not report its database session.');
+
+        $deadline = microtime(true) + UNFURL_CONCURRENCY_TIMEOUT_SECONDS;
+        $isWaiting = false;
+
+        while ($second->isRunning() && microtime(true) < $deadline) {
+            $isWaiting = $fixtures->selectOne('select wait_event_type from pg_stat_activity where pid = ?', [(int) $match[1]])?->wait_event_type === 'Lock';
+
+            if ($isWaiting) {
+                break;
+            }
+
+            Sleep::usleep(UNFURL_LOCK_POLL_MICROSECONDS);
+        }
+
+        touch($directory.'/release');
+        $first->wait();
+        $second->wait();
+
+        expect($first->isSuccessful())->toBeTrue($first->getErrorOutput())
+            ->and($second->isSuccessful())->toBeTrue($second->getErrorOutput())
+            ->and(file_get_contents($directory.'/requests'))->toBe("request\n")
+            ->and($isWaiting)->toBeTrue()
+            ->and(LinkPreview::query()->findOrFail($id)->title)->toBe('Concurrent preview');
+    } finally {
+        Sleep::fake();
+        touch($directory.'/release');
+        $first->stop();
+        $second->stop();
+        $fixtures->table('link_previews')->where('id', $id)->delete();
+        DB::purge('unfurl_concurrency');
+        File::deleteDirectory($directory);
+    }
+});
diff --git a/tests/Unit/Jobs/UnfurlLinkTest.php b/tests/Unit/Jobs/UnfurlLinkTest.php
index c859be632..7673d0a04 100644
--- a/tests/Unit/Jobs/UnfurlLinkTest.php
+++ b/tests/Unit/Jobs/UnfurlLinkTest.php
@@ -2,6 +2,8 @@
 
 declare(strict_types=1);
 
+use App\Actions\UpdateLinkPreview;
+use App\Contracts\Services\DnsResolver;
 use App\Jobs\UnfurlLink;
 use App\Models\LinkPreview;
 use Illuminate\Support\Facades\DB;
@@ -38,6 +40,26 @@ function runNextQueuedJob(): void
     expect($linkPreview->refresh()->title)->toBe('Fetched before');
 });
 
+it('keeps a blocked address as a definitive empty preview', function (): void {
+    $this->app->instance(DnsResolver::class, new readonly class implements DnsResolver
+    {
+        /** @return list<string> */
+        public function resolve(string $host): array
+        {
+            return ['10.0.0.1'];
+        }
+    });
+    $linkPreview = LinkPreview::factory()->create(['url' => 'https://blocked.example.com/']);
+
+    new UnfurlLink($linkPreview)->handle(resolve(UpdateLinkPreview::class));
+
+    expect($linkPreview->refresh())
+        ->fetched_at->not->toBeNull()
+        ->unfurl_failed_at->toBeNull()
+        ->and($linkPreview->prepareUnfurlForPublication())->toBeFalse();
+    Http::assertNothingSent();
+});
+
 it('retries a page that may be reachable later', function (): void {
     Exceptions::fake();
 
@@ -87,11 +109,51 @@ function runNextQueuedJob(): void
     expect($linkPreview->refresh())
         ->title->toBeNull()
         ->fetched_at->not->toBeNull()
+        ->unfurl_failed_at->not->toBeNull()
         ->and(DB::table('jobs')->count())->toBe(0);
 
     Http::assertSentCount(3);
 });
 
+it('queues one job for a preview while its retries are pending', function (): void {
+    Queue::fake();
+    $linkPreview = LinkPreview::factory()->create();
+
+    dispatch(new UnfurlLink($linkPreview));
+    dispatch(new UnfurlLink($linkPreview));
+
+    Queue::assertPushed(UnfurlLink::class, 1);
+});
+
+it('does not let a stale failed callback overwrite a completed publication retry', function (): void {
+    Http::fake(['https://93.184.216.34/*' => Http::response('<title>Recovered</title>', 200, ['Content-Type' => 'text/html'])]);
+    $linkPreview = LinkPreview::factory()->create(['url' => 'https://93.184.216.34/']);
+    $staleJob = new UnfurlLink($linkPreview);
+
+    $linkPreview->markUnfurlAsTransientFailure(0);
+    $retry = LinkPreview::query()->findOrFail($linkPreview->id);
+    $retry->retryTransientFailureForPublication();
+
+    new UnfurlLink(LinkPreview::query()->findOrFail($linkPreview->id))->handle(resolve(UpdateLinkPreview::class));
+    $staleJob->failed();
+
+    expect($linkPreview->refresh())
+        ->title->toBe('Recovered')
+        ->fetched_at->not->toBeNull()
+        ->unfurl_failed_at->toBeNull()
+        ->publication_unfurl_retries->toBe(1);
+});
+
+it('keeps old queued job payloads compatible with the first unfurl cycle', function (): void {
+    $job = new UnfurlLink(LinkPreview::factory()->create());
+    $payload = $job->__serialize();
+    unset($payload['publicationUnfurlRetries']);
+    $legacyJob = new ReflectionClass(UnfurlLink::class)->newInstanceWithoutConstructor();
+    $legacyJob->__unserialize($payload);
+
+    expect($legacyJob->publicationUnfurlRetries)->toBe(0);
+});
+
 it('is dropped when its link preview is gone', function (): void {
     Queue::connection('database')->push(new UnfurlLink(LinkPreview::factory()->create()));
 
diff --git a/tests/Unit/Models/LinkPreviewTest.php b/tests/Unit/Models/LinkPreviewTest.php
index fc5b061e2..2cf3d12d6 100644
--- a/tests/Unit/Models/LinkPreviewTest.php
+++ b/tests/Unit/Models/LinkPreviewTest.php
@@ -27,6 +27,41 @@
         ->and(LinkPreview::factory()->failed()->create()->toArray()['is_pending'])->toBeFalse();
 });
 
+it('lets only one stale instance start the publication retry', function (): void {
+    $preview = LinkPreview::factory()->failed()->create();
+    $first = LinkPreview::query()->findOrFail($preview->id);
+    $second = LinkPreview::query()->findOrFail($preview->id);
+
+    expect($first->prepareUnfurlForPublication())->toBeTrue()
+        ->and($second->prepareUnfurlForPublication())->toBeFalse()
+        ->and($preview->refresh())
+        ->fetched_at->toBeNull()
+        ->publication_unfurl_retries->toBe(1);
+});
+
+it('distinguishes definitive completion from a recorded transient failure', function (): void {
+    $completed = LinkPreview::factory()->create();
+    $completed->completeUnfurl(['title' => null]);
+
+    $transientFailure = LinkPreview::factory()->failed()->create();
+
+    expect($completed->fresh()->prepareUnfurlForPublication())->toBeFalse()
+        ->and($transientFailure->prepareUnfurlForPublication())->toBeTrue();
+});
+
+it('does not let an old completion overwrite a newer publication retry', function (): void {
+    $preview = LinkPreview::factory()->create();
+    $oldCycle = LinkPreview::query()->findOrFail($preview->id);
+    $oldCycle->markUnfurlAsTransientFailure(0);
+
+    $retry = LinkPreview::query()->findOrFail($preview->id);
+    $retry->prepareUnfurlForPublication();
+
+    expect($oldCycle->completeUnfurl(['title' => 'Old']))->toBeFalse()
+        ->and(LinkPreview::query()->findOrFail($preview->id)->completeUnfurl(['title' => 'New']))->toBeTrue()
+        ->and($preview->refresh()->title)->toBe('New');
+});
+
 it('has an embed when its link can be played in place', function (): void {
     expect(LinkPreview::factory()->create(['url' => 'https://youtu.be/dQw4w9WgXcQ'])->toArray()['embed'])->toMatchArray([
         'provider' => 'YouTube',

From 621bc9a6efa408d91ff29abf753f63c6e6761e3f Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:18:01 -0400
Subject: [PATCH 20/25] feat: queue draft link previews through the shared
 cache

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 .../DraftLinkPreviewController.php            | 104 +++++
 .../Requests/ShowDraftLinkPreviewRequest.php  |  26 ++
 routes/web.php                                |   4 +
 .../DraftLinkPreviewControllerTest.php        | 421 ++++++++++++++++++
 4 files changed, 555 insertions(+)
 create mode 100644 app/Http/Controllers/DraftLinkPreviewController.php
 create mode 100644 app/Http/Requests/ShowDraftLinkPreviewRequest.php
 create mode 100644 tests/Feature/Controllers/DraftLinkPreviewControllerTest.php

diff --git a/app/Http/Controllers/DraftLinkPreviewController.php b/app/Http/Controllers/DraftLinkPreviewController.php
new file mode 100644
index 000000000..70c07a9cb
--- /dev/null
+++ b/app/Http/Controllers/DraftLinkPreviewController.php
@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Actions\CreateLinkPreviewJob;
+use App\Dto\LinkPreviewMetadata;
+use App\Enums\EmbedKind;
+use App\Http\Requests\ShowDraftLinkPreviewRequest;
+use App\Models\LinkPreview;
+use App\Models\User;
+use App\Services\Embeds;
+use Carbon\CarbonInterface;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\RateLimiter;
+use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
+use Uri\WhatWg\Url;
+
+final readonly class DraftLinkPreviewController
+{
+    public const int READS_PER_MINUTE = 120;
+
+    private const int UNFURLS_PER_MINUTE = 10;
+
+    public function __construct(private CreateLinkPreviewJob $createLinkPreviewJob)
+    {
+        //
+    }
+
+    public function show(ShowDraftLinkPreviewRequest $request, Embeds $embeds): JsonResponse
+    {
+        $user = $request->user();
+        assert($user instanceof User);
+
+        $url = $request->string('url')->value();
+
+        Log::info('Draft link preview requested', [
+            'user_id' => $user->id,
+            'host' => Url::parse($url)?->getAsciiHost(),
+        ]);
+
+        if ($embeds->for($url)?->kind === EmbedKind::Gif) {
+            return $this->response($this->preview($url, new LinkPreviewMetadata));
+        }
+
+        $key = "draft-link-unfurls:{$user->id}";
+
+        return $this->response($this->cachedPreview($url, $key));
+    }
+
+    private function cachedPreview(string $url, string $key): LinkPreview
+    {
+        $cached = LinkPreview::query()->where('url_hash', hash('sha256', $url))->first();
+
+        if ($cached instanceof LinkPreview) {
+            return $cached;
+        }
+
+        if (RateLimiter::tooManyAttempts($key, self::UNFURLS_PER_MINUTE)) {
+            throw new TooManyRequestsHttpException(RateLimiter::availableIn($key));
+        }
+
+        RateLimiter::increment($key, CarbonInterface::SECONDS_PER_MINUTE);
+
+        return $this->createPreview($url);
+    }
+
+    private function createPreview(string $url): LinkPreview
+    {
+        return DB::transaction(function () use ($url): LinkPreview {
+            $preview = LinkPreview::query()->firstOrCreate(
+                ['url_hash' => hash('sha256', $url)],
+                ['url' => $url, ...(new LinkPreviewMetadata)->toArray()],
+            );
+
+            if ($preview->wasRecentlyCreated) {
+                DB::afterCommit(function () use ($preview): void {
+                    $this->createLinkPreviewJob->handle($preview);
+                });
+            }
+
+            return $preview;
+        });
+    }
+
+    private function response(LinkPreview $preview): JsonResponse
+    {
+        return response()->json([
+            'link_preview' => $preview,
+        ])->header('Cache-Control', 'private, no-store');
+    }
+
+    private function preview(string $url, LinkPreviewMetadata $metadata): LinkPreview
+    {
+        return new LinkPreview([
+            'url' => $url,
+            ...$metadata->toArray(),
+            'fetched_at' => now(),
+        ]);
+    }
+}
diff --git a/app/Http/Requests/ShowDraftLinkPreviewRequest.php b/app/Http/Requests/ShowDraftLinkPreviewRequest.php
new file mode 100644
index 000000000..82026b282
--- /dev/null
+++ b/app/Http/Requests/ShowDraftLinkPreviewRequest.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests;
+
+use App\Services\Urls;
+use Illuminate\Foundation\Http\FormRequest;
+
+final class ShowDraftLinkPreviewRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, list<string>>
+     */
+    public function rules(): array
+    {
+        return [
+            'url' => ['required', 'string', 'url:http,https', 'max:'.Urls::MAX_LENGTH],
+        ];
+    }
+}
diff --git a/routes/web.php b/routes/web.php
index 8512038a6..153e6fbe9 100644
--- a/routes/web.php
+++ b/routes/web.php
@@ -36,6 +36,7 @@
 use App\Http\Controllers\ConversationReadController;
 use App\Http\Controllers\ConversationTypingController;
 use App\Http\Controllers\DeviceController;
+use App\Http\Controllers\DraftLinkPreviewController;
 use App\Http\Controllers\ExportController;
 use App\Http\Controllers\FailedJobController;
 use App\Http\Controllers\FailedJobRetryController;
@@ -249,6 +250,9 @@
         ->name('commit.store');
     Route::post('commits/preview', [CommitPreviewController::class, 'store'])
         ->name('commit-preview.store');
+    Route::get('draft-link-preview', [DraftLinkPreviewController::class, 'show'])
+        ->middleware('throttle:'.DraftLinkPreviewController::READS_PER_MINUTE.',1,draft-link-preview-reads:')
+        ->name('draft-link-preview.show');
     Route::post('commits/{commit}/translation', [CommitTranslationController::class, 'store'])
         ->middleware('throttle:10,1,translations:')
         ->name('commit-translation.store');
diff --git a/tests/Feature/Controllers/DraftLinkPreviewControllerTest.php b/tests/Feature/Controllers/DraftLinkPreviewControllerTest.php
new file mode 100644
index 000000000..bb236150b
--- /dev/null
+++ b/tests/Feature/Controllers/DraftLinkPreviewControllerTest.php
@@ -0,0 +1,421 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Actions\CreateCommit;
+use App\Actions\UpdateLinkPreview;
+use App\Contracts\Services\DnsResolver;
+use App\Jobs\UnfurlLink;
+use App\Models\Commit;
+use App\Models\LinkPreview;
+use App\Models\User;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Bus;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Queue;
+use Illuminate\Support\Facades\RateLimiter;
+
+beforeEach(function (): void {
+    Queue::fake();
+    $this->app->instance(DnsResolver::class, new readonly class implements DnsResolver
+    {
+        private const array HOSTS = [
+            'example.com' => ['93.184.216.34'],
+            'www.example.com' => ['93.184.216.35'],
+            'giphy.com' => ['104.16.105.123'],
+            'mixed.example.com' => ['93.184.216.34', '64:ff9b:2::7f00:1'],
+            'nat64.example.com' => ['64:ff9b:2::7f00:1'],
+        ];
+
+        public function resolve(string $host): array
+        {
+            return self::HOSTS[$host] ?? [];
+        }
+    });
+});
+
+function draftPreviewUrl(string $url): string
+{
+    return '/draft-link-preview?'.http_build_query(['url' => $url]);
+}
+
+function fetchQueuedDraftPreview(): LinkPreview
+{
+    $preview = LinkPreview::query()->sole();
+    Queue::assertPushed(UnfurlLink::class, fn (UnfurlLink $job): bool => $job->linkPreview->is($preview));
+    new UnfurlLink($preview)->handle(resolve(UpdateLinkPreview::class));
+
+    return $preview->refresh();
+}
+
+it('requires authentication', function (): void {
+    Log::spy();
+    $this->getJson(draftPreviewUrl('https://example.com/cat.gif'))->assertUnauthorized();
+
+    Http::assertNothingSent();
+    Queue::assertNothingPushed();
+    Log::shouldNotHaveReceived('info');
+    expect(LinkPreview::query()->count())->toBe(0);
+});
+
+it('validates draft link preview URLs before creating cache entries', function (mixed $url): void {
+    Log::spy();
+    $this->actingAs(User::factory()->create())
+        ->getJson('/draft-link-preview', ['url' => $url])
+        ->assertUnprocessable()
+        ->assertJsonValidationErrors('url');
+
+    Http::assertNothingSent();
+    Queue::assertNothingPushed();
+    Log::shouldNotHaveReceived('info');
+    expect(LinkPreview::query()->count())->toBe(0);
+})->with([
+    'missing' => null,
+    'empty' => '',
+    'unsupported protocol' => 'ftp://example.com/cat.gif',
+    'too long' => 'https://example.com/'.str_repeat('x', 2048),
+]);
+
+it('returns a Giphy embed without fetching or caching a draft', function (string $host): void {
+    $url = 'https://'.$host.'/gifs/JIX9t2j0ZTN9S';
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($url))
+        ->assertOk()
+        ->assertHeader('Cache-Control', 'no-store, private')
+        ->assertExactJson(['link_preview' => [
+            'url' => $url,
+            'title' => null,
+            'description' => null,
+            'image_url' => null,
+            'site_name' => null,
+            'is_pending' => false,
+            'embed' => [
+                'provider' => 'GIPHY',
+                'kind' => 'gif',
+                'src' => 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif',
+                'aspect_ratio' => null,
+                'height' => null,
+                'poster' => 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy_s.gif',
+            ],
+        ]]);
+
+    Http::assertNothingSent();
+    Queue::assertNothingPushed();
+    expect(LinkPreview::query()->count())->toBe(0);
+})->with(['giphy.com', 'www.giphy.com']);
+
+it('queues a plain Giphy card when GIF embeds are unavailable', function (array $config): void {
+    config($config);
+    $url = 'https://giphy.com/gifs/JIX9t2j0ZTN9S';
+    Http::fake([$url => Http::response('<title>Giphy card</title>', 200, ['Content-Type' => 'text/html'])]);
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+
+    Http::assertNothingSent();
+    fetchQueuedDraftPreview();
+    $this->getJson(draftPreviewUrl($url))
+        ->assertOk()
+        ->assertJsonPath('link_preview.title', 'Giphy card')
+        ->assertJsonPath('link_preview.embed', null);
+
+    Http::assertSentCount(1);
+})->with([
+    'embeds disabled' => [['embeds.enabled' => false]],
+    'Giphy excluded' => [['embeds.only' => ['youtube']]],
+]);
+
+it('queues uncached previews without resolving DNS or publishing content', function (): void {
+    $this->app->instance(DnsResolver::class, new readonly class implements DnsResolver
+    {
+        public function resolve(string $host): array
+        {
+            throw new RuntimeException('DNS must run on the queue worker.');
+        }
+    });
+    $url = 'https://example.com/cat.gif';
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($url).'&gif_url=https%3A%2F%2Fevil.example%2Fcat.gif')
+        ->assertOk()
+        ->assertExactJson(['link_preview' => [
+            'url' => $url,
+            'title' => null,
+            'description' => null,
+            'image_url' => null,
+            'site_name' => null,
+            'is_pending' => true,
+            'embed' => null,
+        ]]);
+
+    Http::assertNothingSent();
+    $preview = LinkPreview::query()->sole();
+    expect($preview->url_hash)->toBe(hash('sha256', $url))
+        ->and($preview->gif_url)->toBeNull()
+        ->and(Commit::query()->count())->toBe(0);
+    Queue::assertPushed(UnfurlLink::class, fn (UnfurlLink $job): bool => $job->linkPreview->is($preview));
+});
+
+it('returns verified GIFs from the shared cache after the queued fetch', function (bool $redirect): void {
+    $source = 'https://example.com/cat.gif';
+    $final = $redirect ? 'https://www.example.com/media?id=cat' : $source;
+    Http::fake([
+        $source => $redirect
+            ? Http::response(status: 302, headers: ['Location' => $final])
+            : Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 206, ['Content-Type' => 'image/gif']),
+        ...($redirect ? [$final => Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 206, ['Content-Type' => 'image/gif'])] : []),
+    ]);
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($source))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+    Http::assertNothingSent();
+    fetchQueuedDraftPreview();
+
+    $this->getJson(draftPreviewUrl($source))
+        ->assertOk()
+        ->assertJsonPath('link_preview.url', $source)
+        ->assertJsonPath('link_preview.is_pending', false)
+        ->assertJsonPath('link_preview.embed.provider', 'GIF')
+        ->assertJsonPath('link_preview.embed.kind', 'gif')
+        ->assertJsonPath('link_preview.embed.src', $final)
+        ->assertJsonPath('link_preview.embed.aspect_ratio', null);
+
+    Http::assertSentCount($redirect ? 2 : 1);
+    Queue::assertPushed(UnfurlLink::class, 1);
+    expect(LinkPreview::query()->count())->toBe(1);
+})->with(['direct' => false, 'extensionless redirect' => true]);
+
+it('does not create an embed when the queued GIF check fails', function (): void {
+    $url = 'https://example.com/cat.gif';
+    Http::fake([$url => Http::response('<title>Not a GIF</title>', 200, ['Content-Type' => 'image/gif'])]);
+
+    $this->actingAs(User::factory()->create())->getJson(draftPreviewUrl($url))->assertOk();
+    fetchQueuedDraftPreview();
+    $this->getJson(draftPreviewUrl($url))
+        ->assertOk()->assertJsonPath('link_preview.is_pending', false)->assertJsonPath('link_preview.embed', null);
+});
+
+it('keeps the shared address guard on queued draft fetches', function (string $host): void {
+    $url = 'https://'.$host.'/cat.gif';
+    $this->actingAs(User::factory()->create())->getJson(draftPreviewUrl($url))->assertOk();
+    fetchQueuedDraftPreview();
+
+    $this->getJson(draftPreviewUrl($url))
+        ->assertOk()->assertJsonPath('link_preview.is_pending', false)->assertJsonPath('link_preview.embed', null);
+    Http::assertNothingSent();
+})->with(['mixed.example.com', 'nat64.example.com']);
+
+it('does not follow queued redirects to an unsafe DNS destination', function (): void {
+    $url = 'https://example.com/cat.gif';
+    Http::fake([$url => Http::response(status: 302, headers: ['Location' => 'https://nat64.example.com/cat.gif'])]);
+
+    $this->actingAs(User::factory()->create())->getJson(draftPreviewUrl($url))->assertOk();
+    fetchQueuedDraftPreview();
+    $this->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.embed', null);
+    Http::assertSentCount(1);
+});
+
+it('leaves a transient failure pending for the existing job retry policy', function (): void {
+    $url = 'https://example.com/cat.gif';
+    Http::fake([$url => Http::failedConnection()]);
+
+    $this->actingAs(User::factory()->create())->getJson(draftPreviewUrl($url))->assertOk();
+    expect(fn (): LinkPreview => fetchQueuedDraftPreview())->toThrow(ConnectionException::class);
+    $this->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+    Queue::assertPushed(UnfurlLink::class, 1);
+    Http::assertSentCount(1);
+});
+
+it('reuses completed metadata without an independent expiry policy', function (int $ageInDays): void {
+    $preview = LinkPreview::factory()->fetched()->create([
+        'url' => 'https://example.com/cat.gif',
+        'gif_url' => 'https://www.example.com/media?id=cat',
+        'fetched_at' => now()->subDays($ageInDays),
+    ]);
+    $original = $preview->refresh()->getAttributes();
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($preview->url))
+        ->assertOk()
+        ->assertJsonPath('link_preview.title', $preview->title)
+        ->assertJsonPath('link_preview.embed.src', $preview->gif_url)
+        ->assertJsonPath('link_preview.is_pending', false);
+
+    Http::assertNothingSent();
+    Queue::assertNothingPushed();
+    expect($preview->fresh()->getAttributes())->toBe($original)
+        ->and(LinkPreview::query()->count())->toBe(1);
+})->with([0, 30]);
+
+it('does not retry a terminal empty cache row just because a draft polls it', function (): void {
+    $preview = LinkPreview::factory()->failed()->create(['url' => 'https://example.com/unavailable']);
+    $this->actingAs(User::factory()->create());
+
+    foreach (range(1, 7) as $attempt) {
+        $this->getJson(draftPreviewUrl($preview->url))
+            ->assertOk()
+            ->assertJsonPath('link_preview.is_pending', false)
+            ->assertJsonPath('link_preview.title', null)
+            ->assertJsonPath('link_preview.embed', null);
+    }
+
+    Queue::assertNothingPushed();
+    Http::assertNothingSent();
+});
+
+it('reuses pending rows and polling never enqueues duplicate work', function (): void {
+    $url = 'https://example.com/article';
+    $this->actingAs(User::factory()->create());
+    foreach (range(1, 7) as $attempt) {
+        $this->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+    }
+
+    Queue::assertPushed(UnfurlLink::class, 1);
+    Http::assertNothingSent();
+    expect(LinkPreview::query()->count())->toBe(1);
+});
+
+it('dispatches only after its cache transaction commits', function (): void {
+    $transactionLevel = DB::transactionLevel();
+    Bus::shouldReceive('dispatch')->once()
+        ->withArgs(fn (UnfurlLink $job): bool => DB::transactionLevel() === $transactionLevel)
+        ->andReturnNull();
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl('https://example.com/article'))->assertOk();
+});
+
+it('ends the pending state when the real queue driver cannot enqueue the job', function (): void {
+    config(['queue.default' => 'database']);
+    Queue::swap(Queue::fake()->queue);
+    DB::connection()->beforeExecuting(function (string $query): void {
+        throw_if(str_starts_with($query, 'insert into "jobs"'), RuntimeException::class, 'Queue unavailable');
+    });
+    $this->withoutExceptionHandling();
+    $user = User::factory()->create();
+    $this->actingAs($user);
+
+    expect(fn () => $this->getJson(draftPreviewUrl('https://example.com/article')))
+        ->toThrow(RuntimeException::class, 'Queue unavailable');
+
+    expect(LinkPreview::query()->sole()->fetched_at)->not->toBeNull()
+        ->and(DB::table('jobs')->count())->toBe(0)
+        ->and(RateLimiter::attempts('draft-link-unfurls:'.$user->id))->toBe(1);
+    Http::assertNothingSent();
+});
+
+it('runs an uncached preview on the database queue and returns it on polling', function (): void {
+    config(['queue.default' => 'database']);
+    Queue::swap(Queue::fake()->queue);
+    $url = 'https://example.com/article';
+    Http::fake([$url => Http::response('<title>Queued article</title>', 200, ['Content-Type' => 'text/html'])]);
+
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+    Http::assertNothingSent();
+
+    expect(DB::table('jobs')->count())->toBe(1);
+    $this->artisan('queue:work', ['connection' => 'database', '--once' => true])->assertSuccessful();
+    expect(DB::table('failed_jobs')->count())->toBe(0);
+    Http::assertSentCount(1);
+    $this->getJson(draftPreviewUrl($url))
+        ->assertOk()->assertJsonPath('link_preview.title', 'Queued article')->assertJsonPath('link_preview.is_pending', false);
+    Http::assertSentCount(1);
+});
+
+it('looks up only the requested URL hash', function (): void {
+    LinkPreview::factory()->fetched()->create(['url' => 'https://example.com/other']);
+    $url = 'https://example.com/article';
+    $this->actingAs(User::factory()->create())
+        ->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+    expect(LinkPreview::query()->count())->toBe(2);
+    Queue::assertPushed(UnfurlLink::class, fn (UnfurlLink $job): bool => $job->linkPreview->url === $url);
+    Http::assertNothingSent();
+});
+
+it('records the authenticated user and host without logging draft URL secrets', function (): void {
+    Log::spy();
+    $user = User::factory()->create();
+    $this->actingAs($user)
+        ->getJson(draftPreviewUrl('https://example.com/cat.gif?token=private-draft-token'))->assertOk();
+    Log::shouldHaveReceived('info')->once()->with('Draft link preview requested', [
+        'user_id' => $user->id,
+        'host' => 'example.com',
+    ]);
+    Http::assertNothingSent();
+});
+
+it('reuses the fetched draft metadata when the URL is published', function (): void {
+    $url = 'https://example.com/cat.gif';
+    Http::fake([$url => Http::response("GIF89a\x01\x00\x01\x00\x80\x00\x00", 206, ['Content-Type' => 'image/gif'])]);
+    $user = User::factory()->create();
+    $this->actingAs($user)->getJson(draftPreviewUrl($url))->assertOk();
+    $preview = fetchQueuedDraftPreview();
+    Queue::fake();
+
+    $commit = resolve(CreateCommit::class)->handle($user, 'Look at '.$url);
+    expect($commit->link_preview_id)->toBe($preview->id)
+        ->and(LinkPreview::query()->count())->toBe(1);
+    Queue::assertNotPushed(UnfurlLink::class);
+    Http::assertSentCount(1);
+});
+
+it('limits new unfurls without charging cached polls to that budget', function (): void {
+    $this->actingAs(User::factory()->create());
+    foreach (range(1, 10) as $attempt) {
+        $this->getJson(draftPreviewUrl('https://example.com/article/'.$attempt))->assertOk();
+    }
+
+    $blocked = 'https://example.com/another';
+    $this->getJson(draftPreviewUrl($blocked))->assertTooManyRequests()->assertHeader('Retry-After');
+    expect(LinkPreview::query()->count())->toBe(10);
+
+    foreach (range(1, 7) as $attempt) {
+        $this->getJson(draftPreviewUrl('https://example.com/article/1'))->assertOk();
+    }
+
+    Queue::assertPushed(UnfurlLink::class, 10);
+    $this->actingAs(User::factory()->create())->getJson(draftPreviewUrl($blocked))->assertOk();
+    Queue::assertPushed(UnfurlLink::class, 11);
+    Http::assertNothingSent();
+});
+
+it('allows two pending cards to complete their polling cycles in one minute', function (): void {
+    $this->actingAs(User::factory()->create());
+    foreach (['https://example.com/first', 'https://example.com/second'] as $url) {
+        foreach (range(1, 7) as $attempt) {
+            $this->getJson(draftPreviewUrl($url))->assertOk()->assertJsonPath('link_preview.is_pending', true);
+        }
+    }
+
+    Queue::assertPushed(UnfurlLink::class, 2);
+    Http::assertNothingSent();
+});
+
+it('allows new unfurls again after the work budget expires', function (): void {
+    $this->actingAs(User::factory()->create());
+    foreach (range(1, 10) as $attempt) {
+        $this->getJson(draftPreviewUrl('https://example.com/article/'.$attempt))->assertOk();
+    }
+
+    $url = 'https://example.com/after-limit';
+    $this->getJson(draftPreviewUrl($url))->assertTooManyRequests();
+    $this->travel(61)->seconds();
+    $this->getJson(draftPreviewUrl($url))->assertOk();
+    Queue::assertPushed(UnfurlLink::class, 11);
+});
+
+it('limits preview reads separately from new work', function (): void {
+    $this->actingAs(User::factory()->create());
+    $url = draftPreviewUrl('https://giphy.com/gifs/JIX9t2j0ZTN9S');
+    foreach (range(1, 120) as $attempt) {
+        $this->getJson($url)->assertOk();
+    }
+
+    $this->getJson($url)->assertTooManyRequests();
+    Queue::assertNothingPushed();
+    Http::assertNothingSent();
+});

From 7cd2f6655c95638cd4967eb71d6086b7b84d0967 Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:18:08 -0400
Subject: [PATCH 21/25] feat: show link previews while composing commits and
 replies

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 KNOWLEDGE_BASE.md                             |   2 +-
 README.md                                     |   2 +-
 resources/js/components/commit-composer.tsx   |   4 +-
 resources/js/components/commit-thread.tsx     |   3 +-
 resources/js/components/composer-preview.tsx  |  37 +-
 .../js/components/draft-link-preview.tsx      |  75 ++++
 resources/js/components/link-preview.tsx      | 203 ++++++++--
 resources/js/hooks/use-draft-link-preview.ts  |  55 +++
 tests/Unit/ComposerPreview.test.tsx           |  32 +-
 tests/Unit/DraftLinkPreview.test.tsx          | 162 ++++++++
 tests/Unit/DraftLinkPreviewRequest.test.tsx   | 130 ++++++
 tests/Unit/LinkPreviewRequest.test.tsx        | 369 ++++++++++++++++++
 tests/draft-images.config.ts                  |   3 +
 tests/tsconfig.json                           |   4 +
 14 files changed, 1002 insertions(+), 79 deletions(-)
 create mode 100644 resources/js/components/draft-link-preview.tsx
 create mode 100644 resources/js/hooks/use-draft-link-preview.ts
 create mode 100644 tests/Unit/DraftLinkPreview.test.tsx
 create mode 100644 tests/Unit/DraftLinkPreviewRequest.test.tsx
 create mode 100644 tests/Unit/LinkPreviewRequest.test.tsx

diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md
index 0e66a1846..7008e84f5 100644
--- a/KNOWLEDGE_BASE.md
+++ b/KNOWLEDGE_BASE.md
@@ -203,7 +203,7 @@ Sources: [body renderer](resources/js/components/commit-body.tsx), [code blocks]
 
 ### Draft previews and secret warnings
 
-Use the composer's eye button or **⌘/Ctrl+Shift+P** to preview a commit or reply before submitting it. Preview shows the rendered code, emoji, mentions, links, and images, and identifies the link selected for a card. Esc returns from preview to writing.
+Use the composer's eye button or **⌘/Ctrl+Shift+P** to preview a commit or reply. The selected link card also loads while writing; direct GIFs appear after verification. Selected URLs and metadata share the posted-link cache, even if the draft is never published. Uncached links load in the background. Esc returns to writing.
 
 The composer checks text for recognizable secrets, such as credentials, and asks for confirmation before posting a flagged draft. The warning can be minimized to a shield icon while you keep editing, for example after a false positive. Draft text containing detected secrets is not persisted in the local stash. Treat this as a warning, not a guarantee that all secrets will be detected: review text and images yourself before publishing. Public GitHub issue drafts require detected secrets to be removed rather than offering a publish-anyway option.
 
diff --git a/README.md b/README.md
index 9e34a3619..8f058dc35 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ A link card for a video, song or pen becomes a player that loads when clicked. T
 | `giphy` | `giphy.com/gifs/{id-or-slug-id}` and `giphy.com/embed/{id}` |
 | `gif` | Public HTTPS `.gif` links |
 
-GIFs load from their external host with Play and Stop controls. Verified GIFs autoplay while visible; reduced-motion users press Play to start playback.
+Link cards preview while writing. GIFs load from their external host with Play/Stop controls and autoplay while visible. Reduced-motion users press Play.
 
 | Variable | Default | |
 |---|---|---|
diff --git a/resources/js/components/commit-composer.tsx b/resources/js/components/commit-composer.tsx
index 9bd0dd22b..309678444 100644
--- a/resources/js/components/commit-composer.tsx
+++ b/resources/js/components/commit-composer.tsx
@@ -18,6 +18,7 @@ import {
     PreviewToggle,
     useComposerPreview,
 } from '@/components/composer-preview';
+import { DraftLinkPreview } from '@/components/draft-link-preview';
 import { GraphRail, RailAvatar } from '@/components/graph-rail';
 import InputError from '@/components/input-error';
 import type { UseIssueCommandReturn } from '@/components/issue-command';
@@ -286,7 +287,6 @@ function CommitComposerBody({
                         {preview.isPreviewing && (
                             <ComposerPreviewBody
                                 preview={preview}
-                                url={linkCard.link}
                                 images={attachments.images}
                                 descriptions={attachments.descriptions}
                                 className="col-start-1 row-start-1 py-1.5"
@@ -294,6 +294,8 @@ function CommitComposerBody({
                         )}
                     </div>
 
+                    <DraftLinkPreview url={isIssue ? null : linkCard.link} />
+
                     {issue.hint && (
                         <IssueCommandHint
                             command={issue.hint}
diff --git a/resources/js/components/commit-thread.tsx b/resources/js/components/commit-thread.tsx
index 367b55eea..01672f18b 100644
--- a/resources/js/components/commit-thread.tsx
+++ b/resources/js/components/commit-thread.tsx
@@ -32,6 +32,7 @@ import {
     PreviewToggle,
     useComposerPreview,
 } from '@/components/composer-preview';
+import { DraftLinkPreview } from '@/components/draft-link-preview';
 import { RailDot } from '@/components/graph-rail';
 import InputError from '@/components/input-error';
 import { LinkCardPicker } from '@/components/link-card-picker';
@@ -1373,7 +1374,6 @@ function ReplyComposer({
                 {preview.isPreviewing && (
                     <ComposerPreviewBody
                         preview={preview}
-                        url={linkCard.link}
                         images={attachments.images}
                         descriptions={attachments.descriptions}
                         className="col-start-1 row-start-1 px-1"
@@ -1384,6 +1384,7 @@ function ReplyComposer({
                 message={errors.body ?? errors.link_preview_url}
                 className="px-1"
             />
+            <DraftLinkPreview url={linkCard.link} />
             {!preview.isPreviewing && (
                 <ImagePickerPreviews
                     images={attachments.images}
diff --git a/resources/js/components/composer-preview.tsx b/resources/js/components/composer-preview.tsx
index b0646a9de..b9843ad92 100644
--- a/resources/js/components/composer-preview.tsx
+++ b/resources/js/components/composer-preview.tsx
@@ -1,5 +1,5 @@
 import { useHttp, usePage } from '@inertiajs/react';
-import { Eye, Link2 } from 'lucide-react';
+import { Eye } from 'lucide-react';
 import type { KeyboardEvent, RefObject } from 'react';
 import { useId, useState } from 'react';
 import CommitPreviewController from '@/actions/App/Http/Controllers/CommitPreviewController';
@@ -29,11 +29,6 @@ const isPreviewShortcut = (event: KeyboardEvent) =>
 
 export type ComposerPreview = ReturnType<typeof useComposerPreview>;
 
-/**
- * Switches a composer between writing and previewing its draft as the commit it becomes. The draft is rendered right
- * away, and its code blocks are highlighted and its mentions linked once the server, the only place code is
- * highlighted and usernames are looked up, sends them back.
- */
 export function useComposerPreview({
     body,
     textareaRef,
@@ -106,9 +101,7 @@ export function useComposerPreview({
         previewId,
         toggle: (moveFocus = false) => show(!isPreviewing, moveFocus),
         close: () => setIsPreviewing(false),
-        /**
-         * Handles ⌘/Ctrl + Shift + P in the textarea, and tells whether it did.
-         */
+
         handleShortcut: (event: KeyboardEvent<HTMLTextAreaElement>) => {
             if (!isPreviewShortcut(event)) {
                 return false;
@@ -172,13 +165,11 @@ export function ComposerPreviewBody({
     preview,
     images,
     descriptions = [],
-    url,
     className,
 }: {
     preview: ComposerPreview;
     images: File[];
     descriptions?: string[];
-    url: string | null;
     className?: string;
 }) {
     return (
@@ -210,34 +201,10 @@ export function ComposerPreviewBody({
                     description: descriptions[index]?.trim() || null,
                 }))}
             />
-
-            {url && (
-                <div
-                    className="mt-3 flex items-center gap-3 rounded-lg border border-dashed px-3 py-2"
-                    data-test="link-card-preview"
-                >
-                    <Link2
-                        aria-hidden
-                        className="size-4 shrink-0 text-muted-foreground"
-                    />
-                    <div className="min-w-0">
-                        <p className="truncate font-mono text-[13px]">
-                            {url.replace(/^https?:\/\//i, '')}
-                        </p>
-                        <p className="text-sm leading-snug text-muted-foreground">
-                            Unfurls into a link card after you commit.
-                        </p>
-                    </div>
-                </div>
-            )}
         </div>
     );
 }
 
-/**
- * Shows a poll draft as it reads once committed: open right away for admins, whose commits skip moderation, and
- * waiting for approval for everyone else.
- */
 export function ComposerPollPreview({
     poll,
     className,
diff --git a/resources/js/components/draft-link-preview.tsx b/resources/js/components/draft-link-preview.tsx
new file mode 100644
index 000000000..797f4c42f
--- /dev/null
+++ b/resources/js/components/draft-link-preview.tsx
@@ -0,0 +1,75 @@
+import { Link2 } from 'lucide-react';
+import DraftLinkPreviewController from '@/actions/App/Http/Controllers/DraftLinkPreviewController';
+import { GifEmbed } from '@/components/gif-embed';
+import { LinkPreview } from '@/components/link-preview';
+import { useDraftLinkPreview } from '@/hooks/use-draft-link-preview';
+import { isGifUrl } from '@/lib/gifs';
+import { hostname } from '@/lib/urls';
+
+function DraftLinkPreviewFallback({
+    url,
+    isLoading,
+}: {
+    url: string;
+    isLoading: boolean;
+}) {
+    return (
+        <div className="mt-3 flex items-center gap-3 rounded-lg border border-dashed px-3 py-2">
+            <Link2
+                aria-hidden
+                className="size-4 shrink-0 text-muted-foreground"
+            />
+            <div className="min-w-0">
+                <p className="truncate font-mono text-[13px]">
+                    {url.replace(/^https?:\/\//i, '')}
+                </p>
+                <p
+                    className="text-sm leading-snug text-muted-foreground"
+                    role="status"
+                >
+                    {isLoading
+                        ? 'Loading link preview…'
+                        : 'Link preview unavailable'}
+                </p>
+            </div>
+        </div>
+    );
+}
+
+export function DraftLinkPreview({ url }: { url: string | null }) {
+    const { preview, isLoading } = useDraftLinkPreview(url);
+
+    if (url === null) {
+        return null;
+    }
+
+    return (
+        <div data-test="link-card-preview" aria-busy={isLoading}>
+            {preview ? (
+                <LinkPreview
+                    key={preview.url}
+                    preview={preview}
+                    refreshUrl={DraftLinkPreviewController.show.url({
+                        query: { url },
+                    })}
+                    emptyState={
+                        <DraftLinkPreviewFallback url={url} isLoading={false} />
+                    }
+                />
+            ) : isGifUrl(url) || hostname(url) === 'giphy.com' ? (
+                <GifEmbed
+                    preview={{
+                        url,
+                        title: null,
+                        description: null,
+                        image_url: null,
+                        site_name: null,
+                        is_pending: isLoading,
+                    }}
+                />
+            ) : (
+                <DraftLinkPreviewFallback url={url} isLoading={isLoading} />
+            )}
+        </div>
+    );
+}
diff --git a/resources/js/components/link-preview.tsx b/resources/js/components/link-preview.tsx
index 700848f6d..3631a224b 100644
--- a/resources/js/components/link-preview.tsx
+++ b/resources/js/components/link-preview.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useState, type ReactNode } from 'react';
 import { GifEmbed } from '@/components/gif-embed';
 import { LinkEmbed } from '@/components/link-embed';
 import { Skeleton } from '@/components/ui/skeleton';
@@ -7,27 +7,132 @@ import { hostname } from '@/lib/urls';
 import type { LinkPreview as LinkPreviewData } from '@/types';
 
 const POLL_DELAYS = [1000, 2000, 3000, 5000, 8000, 13000];
+const MAX_RETRY_AFTER_MS = 60_000;
+const MILLISECONDS_PER_SECOND = 1000;
+const HTTP_TOO_MANY_REQUESTS = 429;
+
+type PollState = {
+    refreshUrl: string;
+    url: string;
+    isPending: boolean;
+    fetched: LinkPreviewData | null;
+    hasGivenUp: boolean;
+};
+
+function retryAfterDelay(response: Response, fallback: number): number | null {
+    const retryAfter = response.headers.get('Retry-After');
+
+    if (retryAfter === null) {
+        return fallback;
+    }
+
+    const seconds = Number(retryAfter);
+
+    if (Number.isFinite(seconds)) {
+        return retryAfterMilliseconds(
+            seconds * MILLISECONDS_PER_SECOND,
+            fallback,
+        );
+    }
+
+    const date = Date.parse(retryAfter);
+
+    if (Number.isNaN(date)) {
+        return fallback;
+    }
+
+    return retryAfterMilliseconds(Math.max(date - Date.now(), 0), fallback);
+}
+
+function retryAfterMilliseconds(
+    delay: number,
+    fallback: number,
+): number | null {
+    if (delay > MAX_RETRY_AFTER_MS) {
+        return null;
+    }
+
+    return Math.max(fallback, delay);
+}
+
+function isCurrentPollCycle(
+    state: PollState,
+    refreshUrl: string,
+    url: string,
+    isPending: boolean,
+): boolean {
+    return (
+        state.refreshUrl === refreshUrl &&
+        state.url === url &&
+        state.isPending === isPending
+    );
+}
+
+function syncPollState(
+    state: PollState,
+    refreshUrl: string,
+    url: string,
+    isPending: boolean,
+): PollState {
+    if (isCurrentPollCycle(state, refreshUrl, url, isPending)) {
+        return state;
+    }
+
+    return {
+        refreshUrl,
+        url,
+        isPending,
+        fetched: null,
+        hasGivenUp: false,
+    };
+}
 
-/**
- * A link is unfurled in the background after its commit or message is posted, so a pending preview is fetched again
- * from the refresh URL until the page behind it has been read, instead of only showing up after a reload.
- */
 function useFetchedLinkPreview(
     refreshUrl: string,
     preview: LinkPreviewData,
 ): { preview: LinkPreviewData; isWaiting: boolean } {
-    const [fetched, setFetched] = useState<LinkPreviewData | null>(null);
-    const [hasGivenUp, setHasGivenUp] = useState(false);
+    const { url, is_pending: isPending } = preview;
+    const [pollState, setPollState] = useState<PollState>({
+        refreshUrl,
+        url,
+        isPending,
+        fetched: null,
+        hasGivenUp: false,
+    });
+    const currentPollState = syncPollState(
+        pollState,
+        refreshUrl,
+        url,
+        isPending,
+    );
+
+    if (currentPollState !== pollState) {
+        setPollState(currentPollState);
+    }
 
     useEffect(() => {
-        if (!preview.is_pending) {
+        if (!isPending) {
             return;
         }
 
         const controller = new AbortController();
         let timeout = 0;
+        let isCurrent = true;
+
+        const hasBeenReplaced = () => !isCurrent || controller.signal.aborted;
+        const giveUp = () => {
+            setPollState((state) => {
+                if (!isCurrentPollCycle(state, refreshUrl, url, isPending)) {
+                    return state;
+                }
+
+                return { ...state, hasGivenUp: true };
+            });
+        };
 
         const poll = async (attempt: number) => {
+            let delay = POLL_DELAYS[attempt + 1];
+
             try {
                 const response = await fetch(refreshUrl, {
                     headers: { Accept: 'application/json' },
@@ -35,49 +140,95 @@ function useFetchedLinkPreview(
                     signal: controller.signal,
                 });
 
-                if (!response.ok) {
-                    setHasGivenUp(true);
-
+                if (hasBeenReplaced()) {
                     return;
                 }
 
-                const { link_preview } = (await response.json()) as {
-                    link_preview: LinkPreviewData | null;
-                };
+                if (!response.ok) {
+                    if (
+                        response.status !== HTTP_TOO_MANY_REQUESTS ||
+                        delay === undefined
+                    ) {
+                        giveUp();
+
+                        return;
+                    }
 
-                if (link_preview && !link_preview.is_pending) {
-                    setFetched(link_preview);
+                    const retryAfter = retryAfterDelay(response, delay);
 
-                    return;
+                    if (retryAfter === null) {
+                        giveUp();
+
+                        return;
+                    }
+
+                    delay = retryAfter;
+                } else {
+                    const { link_preview } = (await response.json()) as {
+                        link_preview: LinkPreviewData | null;
+                    };
+
+                    if (hasBeenReplaced()) {
+                        return;
+                    }
+
+                    if (link_preview && !link_preview.is_pending) {
+                        setPollState((state) => {
+                            if (
+                                !isCurrentPollCycle(
+                                    state,
+                                    refreshUrl,
+                                    url,
+                                    isPending,
+                                )
+                            ) {
+                                return state;
+                            }
+
+                            return { ...state, fetched: link_preview };
+                        });
+
+                        return;
+                    }
                 }
             } catch {
-                if (controller.signal.aborted) {
+                if (hasBeenReplaced()) {
                     return;
                 }
             }
 
-            if (attempt + 1 < POLL_DELAYS.length) {
+            if (hasBeenReplaced()) {
+                return;
+            }
+
+            if (delay !== undefined) {
                 timeout = window.setTimeout(
                     () => void poll(attempt + 1),
-                    POLL_DELAYS[attempt + 1],
+                    delay,
                 );
             } else {
-                setHasGivenUp(true);
+                giveUp();
             }
         };
 
         timeout = window.setTimeout(() => void poll(0), POLL_DELAYS[0]);
 
         return () => {
+            isCurrent = false;
             window.clearTimeout(timeout);
             controller.abort();
         };
-    }, [refreshUrl, preview.is_pending]);
+    }, [isPending, refreshUrl, url]);
 
     const current =
-        preview.is_pending && fetched?.url === preview.url ? fetched : preview;
+        isPending && currentPollState.fetched?.url === url
+            ? currentPollState.fetched
+            : preview;
 
-    return { preview: current, isWaiting: current.is_pending && !hasGivenUp };
+    return {
+        preview: current,
+        isWaiting: current.is_pending && !currentPollState.hasGivenUp,
+    };
 }
 
 function LinkPreviewSkeleton() {
@@ -109,10 +260,12 @@ export function LinkPreview({
     refreshUrl,
     preview: initialPreview,
     isStatic = false,
+    emptyState = null,
 }: {
     refreshUrl: string;
     preview: LinkPreviewData;
     isStatic?: boolean;
+    emptyState?: ReactNode;
 }) {
     const { preview, isWaiting } = useFetchedLinkPreview(
         refreshUrl,
@@ -142,7 +295,7 @@ export function LinkPreview({
     }
 
     if (!preview.title) {
-        return null;
+        return emptyState;
     }
 
     const content = (
diff --git a/resources/js/hooks/use-draft-link-preview.ts b/resources/js/hooks/use-draft-link-preview.ts
new file mode 100644
index 000000000..bbdeba812
--- /dev/null
+++ b/resources/js/hooks/use-draft-link-preview.ts
@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react';
+import DraftLinkPreviewController from '@/actions/App/Http/Controllers/DraftLinkPreviewController';
+import type { LinkPreview } from '@/types';
+
+const PREVIEW_DELAY_MS = 400;
+
+type PreviewResult = { url: string; preview: LinkPreview | null };
+
+export function useDraftLinkPreview(url: string | null) {
+    const [result, setResult] = useState<PreviewResult | null>(null);
+
+    useEffect(() => {
+        if (url === null) {
+            return;
+        }
+
+        const controller = new AbortController();
+        const load = async () => {
+            try {
+                const response = await fetch(
+                    DraftLinkPreviewController.show.url({ query: { url } }),
+                    {
+                        headers: { Accept: 'application/json' },
+                        signal: controller.signal,
+                    },
+                );
+                const data = response.ok
+                    ? ((await response.json()) as {
+                          link_preview: LinkPreview | null;
+                      })
+                    : { link_preview: null };
+
+                if (!controller.signal.aborted) {
+                    setResult({ url, preview: data.link_preview });
+                }
+            } catch {
+                if (!controller.signal.aborted) {
+                    setResult({ url, preview: null });
+                }
+            }
+        };
+
+        const timeout = window.setTimeout(() => void load(), PREVIEW_DELAY_MS);
+
+        return () => {
+            window.clearTimeout(timeout);
+            controller.abort();
+        };
+    }, [url]);
+
+    return {
+        preview: result?.url === url ? result.preview : null,
+        isLoading: url !== null && result?.url !== url,
+    };
+}
diff --git a/tests/Unit/ComposerPreview.test.tsx b/tests/Unit/ComposerPreview.test.tsx
index b23a97eae..1b3576e40 100644
--- a/tests/Unit/ComposerPreview.test.tsx
+++ b/tests/Unit/ComposerPreview.test.tsx
@@ -13,6 +13,7 @@ import {
     useComposerPreview,
     type ComposerPreview,
 } from '../../resources/js/components/composer-preview';
+import { DraftLinkPreview } from '../../resources/js/components/draft-link-preview';
 import { hasMention } from '../../resources/js/components/linkified-text';
 import { TooltipProvider } from '../../resources/js/components/ui/tooltip';
 import { bodySegments } from '../../resources/js/lib/code';
@@ -204,16 +205,8 @@ test('keeps the composer avatar unlinked inside the dialog', () => {
 });
 
 test('previews the chosen link card instead of the first link in the body', () => {
-    const preview = previewFor({
-        body: 'https://first.example.com https://second.example.com',
-        isSubmittable: true,
-    });
     const markup = renderPage(
-        <ComposerPreviewBody
-            preview={preview}
-            images={[]}
-            url="https://second.example.com"
-        />,
+        <DraftLinkPreview url="https://second.example.com" />,
     );
     const card = markup.match(/data-test="link-card-preview"[\s\S]*/)?.[0];
 
@@ -228,7 +221,10 @@ test('omits the preview card when the author chooses no card', () => {
         isSubmittable: true,
     });
     const markup = renderPage(
-        <ComposerPreviewBody preview={preview} images={[]} url={null} />,
+        <>
+            <ComposerPreviewBody preview={preview} images={[]} />
+            <DraftLinkPreview url={null} />
+        </>,
     );
 
     assert.ok(markup.includes('href="https://first.example.com"'));
@@ -252,6 +248,15 @@ test('retains the link card picker and scheduling beside preview', () => {
     assert.ok(!/\sdisabled(?:=|\s|>)/.test(schedule));
 });
 
+test('shows a pending GIF card while writing before Preview or Commit', () => {
+    const markup = renderComposer('https://example.com/cat.gif');
+
+    assert.ok(markup.includes('data-test="gif-embed"'));
+    assert.ok(markup.includes('Loading GIF'));
+    assert.ok(!markup.includes('data-test="gif-animation"'));
+    assert.ok(!markup.includes('data-test="composer-preview"'));
+});
+
 const secret = 'ghp_' + 'Ab3dEf6hIj9kLm2nOp5qRs8tUv1wXy4zABCD';
 
 test('keeps the sensitive text warning beside preview', () => {
@@ -323,7 +328,6 @@ test('links the mentions the server found in the preview', () => {
                 mentions: { alice: '019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b' },
             }}
             images={[]}
-            url={null}
         />,
     );
 
@@ -338,7 +342,7 @@ test('shows mentions as text until the server has found them', () => {
         isSubmittable: true,
     });
     const markup = renderPage(
-        <ComposerPreviewBody preview={preview} images={[]} url={null} />,
+        <ComposerPreviewBody preview={preview} images={[]} />,
     );
 
     assert.equal(preview.mentions, null);
@@ -358,8 +362,7 @@ test('previews attached image descriptions without a published photo link', () =
                 preview={previewFor({ isSubmittable: true })}
                 images={images}
                 descriptions={['  Build output in the terminal  ', '']}
-                url={null}
-            />,
+                />,
         );
 
         assert.ok(markup.includes('alt="Build output in the terminal"'));
@@ -388,7 +391,6 @@ for (const pasteisMode of [false, true]) {
                     <ComposerPreviewBody
                         preview={preview}
                         images={[]}
-                        url={null}
                     />
                 ),
                 pasteisMode,
diff --git a/tests/Unit/DraftLinkPreview.test.tsx b/tests/Unit/DraftLinkPreview.test.tsx
new file mode 100644
index 000000000..db9873cb9
--- /dev/null
+++ b/tests/Unit/DraftLinkPreview.test.tsx
@@ -0,0 +1,162 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import * as React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, test, vi } from 'vite-plus/test';
+import type { LinkPreview } from '../../resources/js/types/commit';
+
+let result: {
+    preview: LinkPreview | null;
+    isLoading: boolean;
+} = { preview: null, isLoading: true };
+
+vi.doMock('../../resources/js/hooks/use-draft-link-preview', () => ({
+    useDraftLinkPreview: () => result,
+}));
+
+const { DraftLinkPreview } =
+    await import('../../resources/js/components/draft-link-preview');
+
+const directGif = 'https://images.example.test/cat.gif';
+
+function render(url: string | null): string {
+    return renderToStaticMarkup(<DraftLinkPreview url={url} />);
+}
+
+afterEach(() => {
+    result = { preview: null, isLoading: true };
+});
+
+test('renders nothing without a selected link card', () => {
+    assert.equal(render(null), '');
+});
+
+test('keeps an unverified GIF pending without requesting media or exposing Play', () => {
+    const markup = render(directGif);
+
+    assert.ok(markup.includes('data-test="gif-embed"'));
+    assert.ok(markup.includes('aspect-square'));
+    assert.ok(markup.includes('Loading GIF'));
+    assert.ok(!markup.includes('<img'));
+    assert.ok(!markup.includes('Play GIF'));
+});
+
+test('keeps a pending www Giphy share link in the GIF card', () => {
+    const markup = render('https://www.giphy.com/gifs/JIX9t2j0ZTN9S');
+
+    assert.ok(markup.includes('data-test="gif-embed"'));
+    assert.ok(markup.includes('aspect-square'));
+    assert.ok(markup.includes('Loading GIF'));
+    assert.ok(!markup.includes('<img'));
+});
+
+test('renders a pending backend preview through the shared preview poller', async () => {
+    let refreshUrl: string | null = null;
+
+    vi.resetModules();
+    vi.doMock('../../resources/js/hooks/use-draft-link-preview', () => ({
+        useDraftLinkPreview: () => ({
+            preview: pendingPreview('https://example.test/article'),
+            isLoading: false,
+        }),
+    }));
+    vi.doMock('../../resources/js/components/link-preview', () => ({
+        LinkPreview: ({ refreshUrl: url }: { refreshUrl: string }) => {
+            refreshUrl = url;
+
+            return <div data-test="shared-link-preview" />;
+        },
+    }));
+
+    const { DraftLinkPreview: PendingDraftLinkPreview } =
+        await import('../../resources/js/components/draft-link-preview');
+    const markup = renderToStaticMarkup(
+        <PendingDraftLinkPreview url="https://example.test/article" />,
+    );
+
+    assert.ok(markup.includes('data-test="shared-link-preview"'));
+    assert.equal(
+        refreshUrl,
+        '/draft-link-preview?url=https%3A%2F%2Fexample.test%2Farticle',
+    );
+
+    vi.doUnmock('../../resources/js/components/link-preview');
+    vi.resetModules();
+});
+
+test('renders verified Giphy and direct GIFs through the shared GIF component', () => {
+    for (const preview of [
+        verifiedGif('https://giphy.com/gifs/JIX9t2j0ZTN9S', {
+            provider: 'GIPHY',
+            src: 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif',
+            poster: 'https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy_s.gif',
+        }),
+        verifiedGif(directGif, {
+            provider: 'GIF',
+            src: directGif,
+            poster: null,
+        }),
+    ]) {
+        result = { preview, isLoading: false };
+        const markup = render(preview.url);
+
+        assert.ok(markup.includes('data-test="gif-embed"'));
+        assert.ok(markup.includes(`href="${preview.url}"`));
+    }
+});
+
+test('shows loading and unavailable states for non-GIF links', () => {
+    const url = 'https://example.test/article';
+
+    assert.ok(render(url).includes('Loading link preview…'));
+
+    result = { preview: null, isLoading: false };
+
+    assert.ok(render(url).includes('Link preview unavailable'));
+});
+
+test('keeps an unavailable card when a completed draft has no metadata', () => {
+    const url = 'https://example.test/unavailable';
+    result = {
+        preview: {
+            ...pendingPreview(url),
+            is_pending: false,
+        },
+        isLoading: false,
+    };
+
+    const markup = render(url);
+
+    assert.ok(markup.includes('data-test="link-card-preview"'));
+    assert.ok(markup.includes('Link preview unavailable'));
+});
+
+function verifiedGif(
+    url: string,
+    embed: Omit<
+        NonNullable<LinkPreview['embed']>,
+        'kind' | 'aspect_ratio' | 'height'
+    >,
+): LinkPreview {
+    return {
+        url,
+        title: null,
+        description: null,
+        image_url: null,
+        site_name: null,
+        is_pending: false,
+        embed: { kind: 'gif', aspect_ratio: null, height: null, ...embed },
+    };
+}
+
+function pendingPreview(url: string): LinkPreview {
+    return {
+        url,
+        title: null,
+        description: null,
+        image_url: null,
+        site_name: null,
+        is_pending: true,
+        embed: null,
+    };
+}
diff --git a/tests/Unit/DraftLinkPreviewRequest.test.tsx b/tests/Unit/DraftLinkPreviewRequest.test.tsx
new file mode 100644
index 000000000..8594c078b
--- /dev/null
+++ b/tests/Unit/DraftLinkPreviewRequest.test.tsx
@@ -0,0 +1,130 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import * as React from 'react';
+import { afterAll, afterEach, test, vi } from 'vite-plus/test';
+import type { LinkPreview } from '../../resources/js/types/commit';
+
+type Effect = () => void | (() => void);
+type StateUpdate = { url: string; preview: LinkPreview | null };
+
+let effects: Effect[] = [];
+let states: unknown[] = [];
+let stateIndex = 0;
+const updates: StateUpdate[] = [];
+
+vi.doMock('react', () => ({
+    ...React,
+    useEffect: (effect: Effect) => effects.push(effect),
+    useState: (initial: unknown) => {
+        const index = stateIndex++;
+        states[index] ??= typeof initial === 'function' ? initial() : initial;
+
+        return [states[index], (update: StateUpdate) => updates.push(update)];
+    },
+}));
+
+const { useDraftLinkPreview } =
+    await import('../../resources/js/hooks/use-draft-link-preview');
+
+let nextTimer = 0;
+const timers = new Map<number, () => void>();
+
+vi.stubGlobal('window', {
+    setTimeout: (callback: () => void) => {
+        nextTimer++;
+        timers.set(nextTimer, callback);
+
+        return nextTimer;
+    },
+    clearTimeout: (timer: number) => timers.delete(timer),
+});
+
+afterAll(() => vi.unstubAllGlobals());
+afterEach(() => {
+    effects = [];
+    states = [];
+    stateIndex = 0;
+    updates.length = 0;
+    timers.clear();
+    nextTimer = 0;
+});
+
+test('debounces one request for the chosen URL', () => {
+    const fetch = vi.fn();
+    vi.stubGlobal('fetch', fetch);
+    const url = 'https://example.test/a?tag=gif';
+
+    const cleanup = mount(url);
+
+    assert.equal(fetch.mock.calls.length, 0);
+    runTimers();
+
+    assert.equal(fetch.mock.calls.length, 1);
+    assert.equal(
+        fetch.mock.calls[0]?.[0],
+        '/draft-link-preview?url=https%3A%2F%2Fexample.test%2Fa%3Ftag%3Dgif',
+    );
+
+    cleanup();
+});
+
+test('aborts an in-flight request when the selected URL changes without applying its late result', async () => {
+    let resolveResponse: (response: Response) => void;
+    let signal: AbortSignal | undefined;
+    const fetch = vi.fn(
+        (_url: string, options: { signal: AbortSignal }) =>
+            new Promise<Response>((resolve) => {
+                signal = options.signal;
+                resolveResponse = resolve;
+            }),
+    );
+    vi.stubGlobal('fetch', fetch);
+
+    const firstCleanup = mount('https://example.test/first');
+    runTimers();
+
+    firstCleanup();
+    mount('https://example.test/second');
+    resolveResponse!({
+        ok: true,
+        json: async () => ({ link_preview: null }),
+    } as Response);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    assert.equal(signal?.aborted, true);
+    assert.deepEqual(updates, []);
+});
+
+test('aborts an in-flight request when the component unmounts', () => {
+    let signal: AbortSignal | undefined;
+    const fetch = vi.fn((_url: string, options: { signal: AbortSignal }) => {
+        signal = options.signal;
+
+        return new Promise<Response>(() => {});
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount('https://example.test/first');
+    runTimers();
+
+    cleanup();
+
+    assert.equal(signal?.aborted, true);
+});
+
+function mount(url: string | null): () => void {
+    stateIndex = 0;
+    useDraftLinkPreview(url);
+    const effect = effects.at(-1);
+
+    return effect?.() ?? (() => {});
+}
+
+function runTimers(): void {
+    for (const callback of timers.values()) {
+        callback();
+    }
+
+    timers.clear();
+}
diff --git a/tests/Unit/LinkPreviewRequest.test.tsx b/tests/Unit/LinkPreviewRequest.test.tsx
new file mode 100644
index 000000000..66f12b862
--- /dev/null
+++ b/tests/Unit/LinkPreviewRequest.test.tsx
@@ -0,0 +1,369 @@
+/// <reference types="node" />
+import assert from 'node:assert/strict';
+import * as React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterAll, afterEach, test, vi } from 'vite-plus/test';
+import type { LinkPreview as LinkPreviewData } from '../../resources/js/types/commit';
+
+type Effect = () => void | (() => void);
+type EffectState = {
+    dependencies: readonly unknown[] | undefined;
+    effect: Effect;
+    cleanup?: () => void;
+    shouldRun: boolean;
+};
+
+let effectStates: EffectState[] = [];
+let states: unknown[] = [];
+let stateIndex = 0;
+let effectIndex = 0;
+
+vi.doMock('react', () => ({
+    ...React,
+    useEffect: (effect: Effect, dependencies?: readonly unknown[]) => {
+        const index = effectIndex++;
+        const previous = effectStates[index];
+        const shouldRun =
+            previous === undefined ||
+            !haveSameDependencies(previous.dependencies, dependencies);
+
+        effectStates[index] = {
+            cleanup: previous?.cleanup,
+            dependencies,
+            effect,
+            shouldRun,
+        };
+    },
+    useState: (initial: unknown) => {
+        const index = stateIndex++;
+        states[index] ??= typeof initial === 'function' ? initial() : initial;
+
+        return [
+            states[index],
+            (update: unknown) => {
+                const next =
+                    typeof update === 'function'
+                        ? update(states[index])
+                        : update;
+
+                if (Object.is(states[index], next)) {
+                    return;
+                }
+
+                states[index] = next;
+            },
+        ];
+    },
+}));
+
+const { LinkPreview } =
+    await import('../../resources/js/components/link-preview');
+
+type Timer = { callback: () => void; delay: number };
+let nextTimer = 0;
+const timers = new Map<number, Timer>();
+
+vi.stubGlobal('window', {
+    setTimeout: (callback: () => void, delay: number) => {
+        nextTimer++;
+        timers.set(nextTimer, { callback, delay });
+
+        return nextTimer;
+    },
+    clearTimeout: (timer: number) => timers.delete(timer),
+});
+
+afterAll(() => vi.unstubAllGlobals());
+afterEach(() => {
+    cleanupEffects();
+    effectStates = [];
+    states = [];
+    stateIndex = 0;
+    effectIndex = 0;
+    timers.clear();
+    nextTimer = 0;
+});
+
+test('retries a rate-limited draft poll instead of hiding its pending card', async () => {
+    const fetch = vi
+        .fn()
+        .mockResolvedValueOnce({
+            ok: false,
+            status: 429,
+            headers: new Headers({ 'Retry-After': '60' }),
+        })
+        .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                link_preview: {
+                    ...pendingPreview,
+                    is_pending: false,
+                    title: 'Recovered preview',
+                },
+            }),
+        });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+    await runNextTimer();
+
+    assert.ok(renderPreview().includes('data-test="link-preview-skeleton"'));
+    assert.equal(timers.size, 1);
+    assert.equal([...timers.values()][0]?.delay, 60000);
+
+    await runNextTimer();
+
+    const markup = renderPreview();
+
+    assert.ok(markup.includes('Recovered preview'));
+    cleanup();
+});
+
+test('gives up only after the bounded poll cycle remains pending', async () => {
+    const fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ link_preview: pendingPreview }),
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+
+    for (let attempt = 0; attempt < 6; attempt++) {
+        await runNextTimer();
+    }
+
+    assert.equal(fetch.mock.calls.length, 6);
+    assert.equal(timers.size, 0);
+    const markup = renderPreview(
+        pendingPreview,
+        '/draft-link-preview?url=https%3A%2F%2Fexample.test%2Farticle',
+        <div data-test="draft-preview-unavailable">
+            Link preview unavailable
+        </div>,
+    );
+
+    assert.ok(markup.includes('data-test="draft-preview-unavailable"'));
+    runPendingEffects();
+    assert.equal(timers.size, 0);
+    cleanup();
+});
+
+test('starts a fresh poll cycle when a pending preview changes URL', async () => {
+    const fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ link_preview: pendingPreview }),
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+
+    for (let attempt = 0; attempt < 6; attempt++) {
+        await runNextTimer();
+    }
+
+    const nextPreview = {
+        ...pendingPreview,
+        url: 'https://example.test/another-article',
+    };
+    const markup = renderPreview(nextPreview);
+
+    assert.ok(markup.includes('data-test="link-preview-skeleton"'));
+    const nextCleanup = runPendingEffects();
+    assert.equal(timers.size, 1);
+    cleanup();
+    nextCleanup();
+});
+
+test('starts a fresh poll cycle when its refresh URL changes', async () => {
+    const fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ link_preview: pendingPreview }),
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+
+    for (let attempt = 0; attempt < 6; attempt++) {
+        await runNextTimer();
+    }
+
+    const markup = renderPreview(
+        pendingPreview,
+        '/draft-link-preview?url=https%3A%2F%2Fexample.test%2Farticle&refresh=1',
+    );
+
+    assert.ok(markup.includes('data-test="link-preview-skeleton"'));
+    const nextCleanup = runPendingEffects();
+    assert.equal(timers.size, 1);
+    cleanup();
+    nextCleanup();
+});
+
+test('starts a fresh poll cycle when a preview becomes pending again', async () => {
+    const fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ link_preview: pendingPreview }),
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+
+    for (let attempt = 0; attempt < 6; attempt++) {
+        await runNextTimer();
+    }
+
+    mount({ ...pendingPreview, is_pending: false });
+
+    const markup = renderPreview();
+
+    assert.ok(markup.includes('data-test="link-preview-skeleton"'));
+    const nextCleanup = runPendingEffects();
+    assert.equal(timers.size, 1);
+    cleanup();
+    nextCleanup();
+});
+
+test('ignores a previous cycle response that completes after a new render', async () => {
+    let resolvePreview: (value: unknown) => void;
+    const deferredPreview = new Promise((resolve) => {
+        resolvePreview = resolve;
+    });
+    const fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => deferredPreview,
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+    await runNextTimer();
+    const nextPreview = {
+        ...pendingPreview,
+        url: 'https://example.test/another-article',
+    };
+
+    assert.ok(
+        renderPreview(nextPreview).includes(
+            'data-test="link-preview-skeleton"',
+        ),
+    );
+
+    resolvePreview!({
+        link_preview: {
+            ...pendingPreview,
+            is_pending: false,
+            title: 'Stale preview',
+        },
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const markup = renderPreview(nextPreview);
+
+    assert.ok(markup.includes('data-test="link-preview-skeleton"'));
+    assert.equal(markup.includes('Stale preview'), false);
+    cleanup();
+});
+
+test('gives up when a rate limit outlasts the visible retry window', async () => {
+    const fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 429,
+        headers: new Headers({ 'Retry-After': '61' }),
+    });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+    await runNextTimer();
+
+    assert.equal(timers.size, 0);
+    const markup = renderPreview(
+        pendingPreview,
+        undefined,
+        <div data-test="draft-preview-unavailable">
+            Link preview unavailable
+        </div>,
+    );
+
+    assert.ok(markup.includes('data-test="draft-preview-unavailable"'));
+    cleanup();
+});
+
+const pendingPreview: LinkPreviewData = {
+    url: 'https://example.test/article',
+    title: null,
+    description: null,
+    image_url: null,
+    site_name: null,
+    is_pending: true,
+};
+
+function mount(
+    preview = pendingPreview,
+    refreshUrl = '/draft-link-preview?url=https%3A%2F%2Fexample.test%2Farticle',
+): () => void {
+    renderPreview(preview, refreshUrl);
+
+    return runPendingEffects();
+}
+
+function renderPreview(
+    preview = pendingPreview,
+    refreshUrl = '/draft-link-preview?url=https%3A%2F%2Fexample.test%2Farticle',
+    emptyState?: React.ReactNode,
+): string {
+    stateIndex = 0;
+    effectIndex = 0;
+
+    return renderToStaticMarkup(
+        LinkPreview({
+            refreshUrl,
+            preview,
+            emptyState,
+        }),
+    );
+}
+
+function runPendingEffects(): () => void {
+    for (const effectState of effectStates) {
+        if (!effectState.shouldRun) {
+            continue;
+        }
+
+        effectState.cleanup?.();
+        effectState.cleanup = effectState.effect() ?? undefined;
+        effectState.shouldRun = false;
+    }
+
+    return cleanupEffects;
+}
+
+function cleanupEffects(): void {
+    for (const effectState of effectStates) {
+        effectState.cleanup?.();
+        effectState.cleanup = undefined;
+    }
+}
+
+function haveSameDependencies(
+    previous: readonly unknown[] | undefined,
+    next: readonly unknown[] | undefined,
+): boolean {
+    if (previous === undefined || next === undefined) {
+        return previous === next;
+    }
+
+    return (
+        previous.length === next.length &&
+        previous.every((dependency, index) =>
+            Object.is(dependency, next[index]),
+        )
+    );
+}
+
+async function runNextTimer(): Promise<void> {
+    const [timer, value] = timers.entries().next().value as [number, Timer];
+    timers.delete(timer);
+    value.callback();
+    await Promise.resolve();
+    await Promise.resolve();
+}
diff --git a/tests/draft-images.config.ts b/tests/draft-images.config.ts
index 41cdb5729..b4c67ad55 100644
--- a/tests/draft-images.config.ts
+++ b/tests/draft-images.config.ts
@@ -12,6 +12,9 @@ export default defineConfig({
             'tests/Unit/GifEmbed.test.tsx',
             'tests/Unit/GifEmbedPlayback.test.tsx',
             'tests/Unit/GifPlaybackHook.test.tsx',
+            'tests/Unit/DraftLinkPreview.test.tsx',
+            'tests/Unit/DraftLinkPreviewRequest.test.tsx',
+            'tests/Unit/LinkPreviewRequest.test.tsx',
             'tests/Unit/CommitPhoto.test.tsx',
             'tests/Unit/CommitSize.test.tsx',
             'tests/Unit/ThreadHistory.test.tsx',
diff --git a/tests/tsconfig.json b/tests/tsconfig.json
index 21be43335..ef776a2a3 100644
--- a/tests/tsconfig.json
+++ b/tests/tsconfig.json
@@ -11,6 +11,10 @@
         "Unit/GifEmbed.test.tsx",
         "Unit/GifEmbedPlayback.test.tsx",
         "Unit/GifPlaybackHook.test.tsx",
+        "Unit/ComposerPreview.test.tsx",
+        "Unit/DraftLinkPreview.test.tsx",
+        "Unit/DraftLinkPreviewRequest.test.tsx",
+        "Unit/LinkPreviewRequest.test.tsx",
         "Unit/CommitPhoto.test.tsx",
         "Unit/DraftStash.test.tsx",
         "Unit/ComposerDraft.test.tsx",

From a2a974952af28a6c1e7466a90840d9674c78a354 Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:22:37 -0400
Subject: [PATCH 22/25] refactor: simplify draft preview request handling

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 resources/js/hooks/use-draft-link-preview.ts | 50 +++++++++--------
 tests/Unit/DraftLinkPreviewRequest.test.tsx  | 57 +++++++++++++++++++-
 2 files changed, 84 insertions(+), 23 deletions(-)

diff --git a/resources/js/hooks/use-draft-link-preview.ts b/resources/js/hooks/use-draft-link-preview.ts
index bbdeba812..3e8e7ddb7 100644
--- a/resources/js/hooks/use-draft-link-preview.ts
+++ b/resources/js/hooks/use-draft-link-preview.ts
@@ -5,6 +5,29 @@ import type { LinkPreview } from '@/types';
 const PREVIEW_DELAY_MS = 400;
 
 type PreviewResult = { url: string; preview: LinkPreview | null };
+type PreviewResponse = { link_preview: LinkPreview | null };
+
+async function fetchDraftLinkPreview(
+    url: string,
+    signal: AbortSignal,
+): Promise<LinkPreview | null> {
+    try {
+        const response = await fetch(
+            DraftLinkPreviewController.show.url({ query: { url } }),
+            { headers: { Accept: 'application/json' }, signal },
+        );
+
+        if (!response.ok) {
+            return null;
+        }
+
+        const data = (await response.json()) as PreviewResponse;
+
+        return data.link_preview;
+    } catch {
+        return null;
+    }
+}
 
 export function useDraftLinkPreview(url: string | null) {
     const [result, setResult] = useState<PreviewResult | null>(null);
@@ -16,28 +39,13 @@ export function useDraftLinkPreview(url: string | null) {
 
         const controller = new AbortController();
         const load = async () => {
-            try {
-                const response = await fetch(
-                    DraftLinkPreviewController.show.url({ query: { url } }),
-                    {
-                        headers: { Accept: 'application/json' },
-                        signal: controller.signal,
-                    },
-                );
-                const data = response.ok
-                    ? ((await response.json()) as {
-                          link_preview: LinkPreview | null;
-                      })
-                    : { link_preview: null };
-
-                if (!controller.signal.aborted) {
-                    setResult({ url, preview: data.link_preview });
-                }
-            } catch {
-                if (!controller.signal.aborted) {
-                    setResult({ url, preview: null });
-                }
+            const preview = await fetchDraftLinkPreview(url, controller.signal);
+
+            if (controller.signal.aborted) {
+                return;
             }
+
+            setResult({ url, preview });
         };
 
         const timeout = window.setTimeout(() => void load(), PREVIEW_DELAY_MS);
diff --git a/tests/Unit/DraftLinkPreviewRequest.test.tsx b/tests/Unit/DraftLinkPreviewRequest.test.tsx
index 8594c078b..586d3be58 100644
--- a/tests/Unit/DraftLinkPreviewRequest.test.tsx
+++ b/tests/Unit/DraftLinkPreviewRequest.test.tsx
@@ -1,5 +1,6 @@
 /// <reference types="node" />
 import assert from 'node:assert/strict';
+import { setImmediate } from 'node:timers/promises';
 import * as React from 'react';
 import { afterAll, afterEach, test, vi } from 'vite-plus/test';
 import type { LinkPreview } from '../../resources/js/types/commit';
@@ -89,8 +90,7 @@ test('aborts an in-flight request when the selected URL changes without applying
         ok: true,
         json: async () => ({ link_preview: null }),
     } as Response);
-    await Promise.resolve();
-    await Promise.resolve();
+    await setImmediate();
 
     assert.equal(signal?.aborted, true);
     assert.deepEqual(updates, []);
@@ -113,6 +113,59 @@ test('aborts an in-flight request when the component unmounts', () => {
     assert.equal(signal?.aborted, true);
 });
 
+test('applies the returned metadata to the selected preview', async () => {
+    const url = 'https://example.test/preview';
+    const preview: LinkPreview = {
+        url,
+        title: 'Example',
+        description: null,
+        image_url: null,
+        site_name: null,
+        is_pending: false,
+    };
+    vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => ({
+            ok: true,
+            json: async () => ({ link_preview: preview }),
+        })),
+    );
+
+    mount(url);
+    runTimers();
+    await setImmediate();
+
+    assert.deepEqual(updates, [{ url, preview }]);
+});
+
+test.each([
+    [
+        'the request fails',
+        async () => {
+            throw new Error('Offline');
+        },
+    ],
+    ['the server rejects the request', async () => ({ ok: false })],
+    [
+        'the response is malformed',
+        async () => ({
+            ok: true,
+            json: async () => {
+                throw new SyntaxError('Invalid JSON');
+            },
+        }),
+    ],
+])('leaves the preview unavailable when %s', async (_reason, fetch) => {
+    const url = 'https://example.test/preview';
+    vi.stubGlobal('fetch', vi.fn(fetch));
+
+    mount(url);
+    runTimers();
+    await setImmediate();
+
+    assert.deepEqual(updates, [{ url, preview: null }]);
+});
+
 function mount(url: string | null): () => void {
     stateIndex = 0;
     useDraftLinkPreview(url);

From 4e152c4cfd91f1851168fceaff9bc097645686ff Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:33:58 -0400
Subject: [PATCH 23/25] refactor: separate link preview polling from rendering

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 resources/js/components/link-preview.tsx      | 228 +-----------------
 .../js/hooks/use-fetched-link-preview.ts      | 206 ++++++++++++++++
 tests/Unit/LinkPreviewRequest.test.tsx        |  70 +++++-
 3 files changed, 274 insertions(+), 230 deletions(-)
 create mode 100644 resources/js/hooks/use-fetched-link-preview.ts

diff --git a/resources/js/components/link-preview.tsx b/resources/js/components/link-preview.tsx
index 3631a224b..979c38abb 100644
--- a/resources/js/components/link-preview.tsx
+++ b/resources/js/components/link-preview.tsx
@@ -1,236 +1,12 @@
-import { useEffect, useState, type ReactNode } from 'react';
+import { useState, type ReactNode } from 'react';
 import { GifEmbed } from '@/components/gif-embed';
 import { LinkEmbed } from '@/components/link-embed';
 import { Skeleton } from '@/components/ui/skeleton';
+import { useFetchedLinkPreview } from '@/hooks/use-fetched-link-preview';
 import { isGifUrl } from '@/lib/gifs';
 import { hostname } from '@/lib/urls';
 import type { LinkPreview as LinkPreviewData } from '@/types';
 
-const POLL_DELAYS = [1000, 2000, 3000, 5000, 8000, 13000];
-const MAX_RETRY_AFTER_MS = 60_000;
-const MILLISECONDS_PER_SECOND = 1000;
-const HTTP_TOO_MANY_REQUESTS = 429;
-
-type PollState = {
-    refreshUrl: string;
-    url: string;
-    isPending: boolean;
-    fetched: LinkPreviewData | null;
-    hasGivenUp: boolean;
-};
-
-function retryAfterDelay(response: Response, fallback: number): number | null {
-    const retryAfter = response.headers.get('Retry-After');
-
-    if (retryAfter === null) {
-        return fallback;
-    }
-
-    const seconds = Number(retryAfter);
-
-    if (Number.isFinite(seconds)) {
-        return retryAfterMilliseconds(
-            seconds * MILLISECONDS_PER_SECOND,
-            fallback,
-        );
-    }
-
-    const date = Date.parse(retryAfter);
-
-    if (Number.isNaN(date)) {
-        return fallback;
-    }
-
-    return retryAfterMilliseconds(Math.max(date - Date.now(), 0), fallback);
-}
-
-function retryAfterMilliseconds(
-    delay: number,
-    fallback: number,
-): number | null {
-    if (delay > MAX_RETRY_AFTER_MS) {
-        return null;
-    }
-
-    return Math.max(fallback, delay);
-}
-
-function isCurrentPollCycle(
-    state: PollState,
-    refreshUrl: string,
-    url: string,
-    isPending: boolean,
-): boolean {
-    return (
-        state.refreshUrl === refreshUrl &&
-        state.url === url &&
-        state.isPending === isPending
-    );
-}
-
-function syncPollState(
-    state: PollState,
-    refreshUrl: string,
-    url: string,
-    isPending: boolean,
-): PollState {
-    if (isCurrentPollCycle(state, refreshUrl, url, isPending)) {
-        return state;
-    }
-
-    return {
-        refreshUrl,
-        url,
-        isPending,
-        fetched: null,
-        hasGivenUp: false,
-    };
-}
-
-function useFetchedLinkPreview(
-    refreshUrl: string,
-    preview: LinkPreviewData,
-): { preview: LinkPreviewData; isWaiting: boolean } {
-    const { url, is_pending: isPending } = preview;
-    const [pollState, setPollState] = useState<PollState>({
-        refreshUrl,
-        url,
-        isPending,
-        fetched: null,
-        hasGivenUp: false,
-    });
-    const currentPollState = syncPollState(
-        pollState,
-        refreshUrl,
-        url,
-        isPending,
-    );
-
-    if (currentPollState !== pollState) {
-        setPollState(currentPollState);
-    }
-
-    useEffect(() => {
-        if (!isPending) {
-            return;
-        }
-
-        const controller = new AbortController();
-        let timeout = 0;
-        let isCurrent = true;
-
-        const hasBeenReplaced = () => !isCurrent || controller.signal.aborted;
-        const giveUp = () => {
-            setPollState((state) => {
-                if (!isCurrentPollCycle(state, refreshUrl, url, isPending)) {
-                    return state;
-                }
-
-                return { ...state, hasGivenUp: true };
-            });
-        };
-
-        const poll = async (attempt: number) => {
-            let delay = POLL_DELAYS[attempt + 1];
-
-            try {
-                const response = await fetch(refreshUrl, {
-                    headers: { Accept: 'application/json' },
-                    cache: 'no-store',
-                    signal: controller.signal,
-                });
-
-                if (hasBeenReplaced()) {
-                    return;
-                }
-
-                if (!response.ok) {
-                    if (
-                        response.status !== HTTP_TOO_MANY_REQUESTS ||
-                        delay === undefined
-                    ) {
-                        giveUp();
-
-                        return;
-                    }
-
-                    const retryAfter = retryAfterDelay(response, delay);
-
-                    if (retryAfter === null) {
-                        giveUp();
-
-                        return;
-                    }
-
-                    delay = retryAfter;
-                } else {
-                    const { link_preview } = (await response.json()) as {
-                        link_preview: LinkPreviewData | null;
-                    };
-
-                    if (hasBeenReplaced()) {
-                        return;
-                    }
-
-                    if (link_preview && !link_preview.is_pending) {
-                        setPollState((state) => {
-                            if (
-                                !isCurrentPollCycle(
-                                    state,
-                                    refreshUrl,
-                                    url,
-                                    isPending,
-                                )
-                            ) {
-                                return state;
-                            }
-
-                            return { ...state, fetched: link_preview };
-                        });
-
-                        return;
-                    }
-                }
-            } catch {
-                if (hasBeenReplaced()) {
-                    return;
-                }
-            }
-
-            if (hasBeenReplaced()) {
-                return;
-            }
-
-            if (delay !== undefined) {
-                timeout = window.setTimeout(
-                    () => void poll(attempt + 1),
-                    delay,
-                );
-            } else {
-                giveUp();
-            }
-        };
-
-        timeout = window.setTimeout(() => void poll(0), POLL_DELAYS[0]);
-
-        return () => {
-            isCurrent = false;
-            window.clearTimeout(timeout);
-            controller.abort();
-        };
-    }, [isPending, refreshUrl, url]);
-
-    const current =
-        isPending && currentPollState.fetched?.url === url
-            ? currentPollState.fetched
-            : preview;
-
-    return {
-        preview: current,
-        isWaiting: current.is_pending && !currentPollState.hasGivenUp,
-    };
-}
-
 function LinkPreviewSkeleton() {
     return (
         <div
diff --git a/resources/js/hooks/use-fetched-link-preview.ts b/resources/js/hooks/use-fetched-link-preview.ts
new file mode 100644
index 000000000..f2c1d3824
--- /dev/null
+++ b/resources/js/hooks/use-fetched-link-preview.ts
@@ -0,0 +1,206 @@
+import { useEffect, useState } from 'react';
+import type { LinkPreview } from '@/types';
+
+const POLL_DELAYS = [1000, 2000, 3000, 5000, 8000, 13000];
+const MAX_RETRY_AFTER_MS = 60_000;
+const MILLISECONDS_PER_SECOND = 1000;
+const HTTP_TOO_MANY_REQUESTS = 429;
+
+type PollCycle = { refreshUrl: string; url: string; isPending: boolean };
+type PollState = PollCycle & {
+    fetched: LinkPreview | null;
+    hasGivenUp: boolean;
+};
+type PreviewResponse = { link_preview: LinkPreview | null };
+type PollResponse = { response: Response; preview: LinkPreview | null };
+
+async function requestLinkPreview(
+    refreshUrl: string,
+    signal: AbortSignal,
+): Promise<PollResponse | null> {
+    try {
+        const response = await fetch(refreshUrl, {
+            headers: { Accept: 'application/json' },
+            cache: 'no-store',
+            signal,
+        });
+
+        if (signal.aborted) {
+            return null;
+        }
+
+        if (!response.ok) {
+            return { response, preview: null };
+        }
+
+        const data = (await response.json()) as PreviewResponse;
+
+        if (signal.aborted) {
+            return null;
+        }
+
+        return { response, preview: data.link_preview };
+    } catch {
+        return null;
+    }
+}
+
+function nextPollDelay(
+    response: Response | null,
+    fallback: number | null,
+): number | null {
+    if (response === null || response.ok) {
+        return fallback;
+    }
+
+    if (response.status !== HTTP_TOO_MANY_REQUESTS || fallback === null) {
+        return null;
+    }
+
+    return retryAfterDelay(response, fallback);
+}
+
+function retryAfterDelay(response: Response, fallback: number): number | null {
+    const retryAfter = response.headers.get('Retry-After');
+
+    if (retryAfter === null) {
+        return fallback;
+    }
+
+    const seconds = Number(retryAfter);
+
+    if (Number.isFinite(seconds)) {
+        return retryAfterMilliseconds(
+            seconds * MILLISECONDS_PER_SECOND,
+            fallback,
+        );
+    }
+
+    const date = Date.parse(retryAfter);
+
+    if (Number.isNaN(date)) {
+        return fallback;
+    }
+
+    return retryAfterMilliseconds(Math.max(date - Date.now(), 0), fallback);
+}
+
+function retryAfterMilliseconds(
+    delay: number,
+    fallback: number,
+): number | null {
+    if (delay > MAX_RETRY_AFTER_MS) {
+        return null;
+    }
+
+    return Math.max(fallback, delay);
+}
+
+function isCurrentPollCycle(state: PollState, cycle: PollCycle): boolean {
+    return (
+        state.refreshUrl === cycle.refreshUrl &&
+        state.url === cycle.url &&
+        state.isPending === cycle.isPending
+    );
+}
+
+function syncPollState(state: PollState, cycle: PollCycle): PollState {
+    if (isCurrentPollCycle(state, cycle)) {
+        return state;
+    }
+
+    return { ...cycle, fetched: null, hasGivenUp: false };
+}
+
+export function useFetchedLinkPreview(
+    refreshUrl: string,
+    preview: LinkPreview,
+): { preview: LinkPreview; isWaiting: boolean } {
+    const { url, is_pending: isPending } = preview;
+    const cycle = { refreshUrl, url, isPending };
+    const [pollState, setPollState] = useState<PollState>({
+        ...cycle,
+        fetched: null,
+        hasGivenUp: false,
+    });
+    const currentPollState = syncPollState(pollState, cycle);
+
+    if (currentPollState !== pollState) {
+        setPollState(currentPollState);
+    }
+
+    useEffect(() => {
+        if (!isPending) {
+            return;
+        }
+
+        const activeCycle = { refreshUrl, url, isPending };
+        const controller = new AbortController();
+        let timeout = 0;
+
+        const giveUp = () => {
+            setPollState((state) => {
+                if (!isCurrentPollCycle(state, activeCycle)) {
+                    return state;
+                }
+
+                return { ...state, hasGivenUp: true };
+            });
+        };
+
+        const poll = async (attempt: number) => {
+            const result = await requestLinkPreview(
+                refreshUrl,
+                controller.signal,
+            );
+
+            if (controller.signal.aborted) {
+                return;
+            }
+
+            const fetched = result?.preview;
+
+            if (fetched && !fetched.is_pending) {
+                setPollState((state) => {
+                    if (!isCurrentPollCycle(state, activeCycle)) {
+                        return state;
+                    }
+
+                    return { ...state, fetched };
+                });
+
+                return;
+            }
+
+            const delay = nextPollDelay(
+                result?.response ?? null,
+                POLL_DELAYS[attempt + 1] ?? null,
+            );
+
+            if (delay === null) {
+                giveUp();
+
+                return;
+            }
+
+            timeout = window.setTimeout(() => void poll(attempt + 1), delay);
+        };
+
+        timeout = window.setTimeout(() => void poll(0), POLL_DELAYS[0]);
+
+        return () => {
+            window.clearTimeout(timeout);
+            controller.abort();
+        };
+    }, [isPending, refreshUrl, url]);
+
+    const current =
+        isPending && currentPollState.fetched?.url === url
+            ? currentPollState.fetched
+            : preview;
+
+    return {
+        preview: current,
+        isWaiting: current.is_pending && !currentPollState.hasGivenUp,
+    };
+}
diff --git a/tests/Unit/LinkPreviewRequest.test.tsx b/tests/Unit/LinkPreviewRequest.test.tsx
index 66f12b862..2ef44c8c1 100644
--- a/tests/Unit/LinkPreviewRequest.test.tsx
+++ b/tests/Unit/LinkPreviewRequest.test.tsx
@@ -1,5 +1,6 @@
 /// <reference types="node" />
 import assert from 'node:assert/strict';
+import { setImmediate } from 'node:timers/promises';
 import * as React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { afterAll, afterEach, test, vi } from 'vite-plus/test';
@@ -254,8 +255,7 @@ test('ignores a previous cycle response that completes after a new render', asyn
             title: 'Stale preview',
         },
     });
-    await Promise.resolve();
-    await Promise.resolve();
+    await setImmediate();
 
     const markup = renderPreview(nextPreview);
 
@@ -288,6 +288,69 @@ test('gives up when a rate limit outlasts the visible retry window', async () =>
     cleanup();
 });
 
+test('does not retry a rejected poll response', async () => {
+    vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({ ok: false, status: 403 }),
+    );
+
+    const cleanup = mount();
+    await runNextTimer();
+
+    assert.equal(timers.size, 0);
+    assert.ok(
+        renderPreview(
+            pendingPreview,
+            undefined,
+            <div>Unavailable</div>,
+        ).includes('Unavailable'),
+    );
+    cleanup();
+});
+
+test.each([
+    [
+        'a network failure',
+        async () => {
+            throw new Error('Offline');
+        },
+    ],
+    [
+        'invalid JSON',
+        async () => ({
+            ok: true,
+            json: async () => {
+                throw new SyntaxError('Invalid JSON');
+            },
+        }),
+    ],
+])('retries a pending preview after %s', async (_reason, request) => {
+    const fetch = vi
+        .fn()
+        .mockImplementationOnce(request)
+        .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                link_preview: {
+                    ...pendingPreview,
+                    is_pending: false,
+                    title: 'Recovered preview',
+                },
+            }),
+        });
+    vi.stubGlobal('fetch', fetch);
+
+    const cleanup = mount();
+    await runNextTimer();
+
+    assert.equal(timers.size, 1);
+    assert.ok(renderPreview().includes('data-test="link-preview-skeleton"'));
+    await runNextTimer();
+
+    assert.ok(renderPreview().includes('Recovered preview'));
+    cleanup();
+});
+
 const pendingPreview: LinkPreviewData = {
     url: 'https://example.test/article',
     title: null,
@@ -364,6 +427,5 @@ async function runNextTimer(): Promise<void> {
     const [timer, value] = timers.entries().next().value as [number, Timer];
     timers.delete(timer);
     value.callback();
-    await Promise.resolve();
-    await Promise.resolve();
+    await setImmediate();
 }

From f92df4c9c886b447eb6aa2517d1a801cc20718de Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:34:02 -0400
Subject: [PATCH 24/25] refactor: simplify GIF and draft preview rendering

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 .../js/components/draft-link-preview.tsx      | 73 ++++++++++++-------
 resources/js/components/gif-embed.tsx         | 37 +++++++---
 2 files changed, 73 insertions(+), 37 deletions(-)

diff --git a/resources/js/components/draft-link-preview.tsx b/resources/js/components/draft-link-preview.tsx
index 797f4c42f..b4b5b6b30 100644
--- a/resources/js/components/draft-link-preview.tsx
+++ b/resources/js/components/draft-link-preview.tsx
@@ -5,6 +5,7 @@ import { LinkPreview } from '@/components/link-preview';
 import { useDraftLinkPreview } from '@/hooks/use-draft-link-preview';
 import { isGifUrl } from '@/lib/gifs';
 import { hostname } from '@/lib/urls';
+import type { LinkPreview as LinkPreviewData } from '@/types';
 
 function DraftLinkPreviewFallback({
     url,
@@ -45,31 +46,53 @@ export function DraftLinkPreview({ url }: { url: string | null }) {
 
     return (
         <div data-test="link-card-preview" aria-busy={isLoading}>
-            {preview ? (
-                <LinkPreview
-                    key={preview.url}
-                    preview={preview}
-                    refreshUrl={DraftLinkPreviewController.show.url({
-                        query: { url },
-                    })}
-                    emptyState={
-                        <DraftLinkPreviewFallback url={url} isLoading={false} />
-                    }
-                />
-            ) : isGifUrl(url) || hostname(url) === 'giphy.com' ? (
-                <GifEmbed
-                    preview={{
-                        url,
-                        title: null,
-                        description: null,
-                        image_url: null,
-                        site_name: null,
-                        is_pending: isLoading,
-                    }}
-                />
-            ) : (
-                <DraftLinkPreviewFallback url={url} isLoading={isLoading} />
-            )}
+            <DraftLinkPreviewContent
+                url={url}
+                preview={preview}
+                isLoading={isLoading}
+            />
         </div>
     );
 }
+
+function DraftLinkPreviewContent({
+    url,
+    preview,
+    isLoading,
+}: {
+    url: string;
+    preview: LinkPreviewData | null;
+    isLoading: boolean;
+}) {
+    if (preview) {
+        return (
+            <LinkPreview
+                key={preview.url}
+                preview={preview}
+                refreshUrl={DraftLinkPreviewController.show.url({
+                    query: { url },
+                })}
+                emptyState={
+                    <DraftLinkPreviewFallback url={url} isLoading={false} />
+                }
+            />
+        );
+    }
+
+    if (isGifUrl(url) || hostname(url) === 'giphy.com') {
+        return (
+            <GifEmbed
+                preview={{
+                    url,
+                    title: null,
+                    description: null,
+                    image_url: null,
+                    site_name: null,
+                    is_pending: isLoading,
+                }}
+            />
+        );
+    }
+
+    return <DraftLinkPreviewFallback url={url} isLoading={isLoading} />;
+}
diff --git a/resources/js/components/gif-embed.tsx b/resources/js/components/gif-embed.tsx
index 56f84d429..552f16022 100644
--- a/resources/js/components/gif-embed.tsx
+++ b/resources/js/components/gif-embed.tsx
@@ -7,6 +7,8 @@ import { hostname } from '@/lib/urls';
 import { cn } from '@/lib/utils';
 import type { Embed, LinkPreview } from '@/types';
 
+const GIF_LABEL = 'GIF';
+
 type GifEmbedProps = {
     preview: LinkPreview;
     embed?: Embed | null;
@@ -35,7 +37,7 @@ export function GifEmbed({
             onClick={isStatic ? undefined : (event) => event.stopPropagation()}
             className="mt-3 overflow-hidden rounded-lg border"
             data-test="gif-embed"
-            data-provider={embed?.provider ?? 'GIF'}
+            data-provider={embed?.provider ?? GIF_LABEL}
         >
             <div className="group/gif relative mx-auto aspect-square w-full max-w-80 overflow-hidden bg-muted">
                 <GifMedia preview={preview} embed={embed} playback={playback} />
@@ -126,20 +128,31 @@ function GifStatus({ preview, embed, playback }: GifMediaProps) {
             className="absolute inset-0 flex items-center justify-center px-4 text-center text-sm text-muted-foreground"
             role={playback.hasFailed ? 'status' : undefined}
         >
-            {playback.hasFailed && 'GIF could not load'}
-            {!playback.hasFailed && embed && 'GIF'}
-            {!playback.hasFailed &&
-                !embed &&
-                preview.is_pending &&
-                'Loading GIF…'}
-            {!playback.hasFailed &&
-                !embed &&
-                !preview.is_pending &&
-                'GIF preview unavailable'}
+            {gifStatusMessage(preview, embed, playback.hasFailed)}
         </span>
     );
 }
 
+function gifStatusMessage(
+    preview: LinkPreview,
+    embed: Embed | null,
+    hasFailed: boolean,
+) {
+    if (hasFailed) {
+        return 'GIF could not load';
+    }
+
+    if (embed) {
+        return GIF_LABEL;
+    }
+
+    if (preview.is_pending) {
+        return 'Loading GIF…';
+    }
+
+    return 'GIF preview unavailable';
+}
+
 function GifPlaybackButton({
     embed,
     playback,
@@ -213,7 +226,7 @@ function GifDetails({ preview, embed }: GifEmbedProps) {
                 {embed?.provider ?? hostname(preview.url)}
             </span>
             <span className="block truncate text-sm leading-snug font-medium">
-                {preview.title ?? 'GIF'}
+                {preview.title ?? GIF_LABEL}
             </span>
         </>
     );

From 5c02ed7804d5cf9074acd55b1a660c08f8c3d352 Mon Sep 17 00:00:00 2001
From: devjerry0 <99199491+devjerry0@users.noreply.github.com>
Date: Mon, 26 Oct 2026 12:13:38 -0400
Subject: [PATCH 25/25] fix: validate GIF sources before manual playback

Apply the existing HTTPS URL guard before every playback mode so Play
and Retry follow the same source checks as autoplay. Extend the existing
regressions and mutation controls.

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce
---
 resources/js/lib/gifs.ts             |  5 +++--
 tests/Mutation/playback-mutations.ts | 10 +++++-----
 tests/Unit/GifPlayback.test.ts       | 10 ++++++++--
 3 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/resources/js/lib/gifs.ts b/resources/js/lib/gifs.ts
index bb5a50ce0..00138046c 100644
--- a/resources/js/lib/gifs.ts
+++ b/resources/js/lib/gifs.ts
@@ -144,7 +144,8 @@ export function isGifPlaying({
         isStatic ||
         hasFailed ||
         !isVisible ||
-        playback === GIF_PLAYBACK_MODE.STOPPED
+        playback === GIF_PLAYBACK_MODE.STOPPED ||
+        parseHttpsUrl(source) === null
     ) {
         return false;
     }
@@ -153,5 +154,5 @@ export function isGifPlaying({
         return true;
     }
 
-    return !reducedMotion && parseHttpsUrl(source) !== null;
+    return !reducedMotion;
 }
diff --git a/tests/Mutation/playback-mutations.ts b/tests/Mutation/playback-mutations.ts
index 567f98db9..6cf818f17 100644
--- a/tests/Mutation/playback-mutations.ts
+++ b/tests/Mutation/playback-mutations.ts
@@ -2,18 +2,18 @@ import type { GifMutation } from './php-gif-mutations.ts';
 
 export const playbackMutations: GifMutation[] = [
     {
-        name: 'autoplay invalid verified GIF sources',
+        name: 'play unsafe verified GIF sources',
         source: 'resources/js/lib/gifs.ts',
         test: 'tests/Unit/GifPlayback.test.ts',
-        before: '!reducedMotion && parseHttpsUrl(source) !== null',
-        after: '!reducedMotion',
+        before: 'parseHttpsUrl(source) === null',
+        after: 'false',
     },
     {
         name: 'ignore reduced motion',
         source: 'resources/js/lib/gifs.ts',
         test: 'tests/Unit/GifPlayback.test.ts',
-        before: '!reducedMotion && parseHttpsUrl(source) !== null',
-        after: 'parseHttpsUrl(source) !== null',
+        before: 'return !reducedMotion;',
+        after: 'return true;',
     },
     {
         name: 'ignore visibility',
diff --git a/tests/Unit/GifPlayback.test.ts b/tests/Unit/GifPlayback.test.ts
index 5a76b1986..dba5398cf 100644
--- a/tests/Unit/GifPlayback.test.ts
+++ b/tests/Unit/GifPlayback.test.ts
@@ -5,6 +5,7 @@ import {
     canLoadGifPoster,
     canRetryGifLoad,
     failGifLoad,
+    GIF_PLAYBACK_MODE,
     hasGifLoadFailed,
     isGifPlaying,
     isGifUrl,
@@ -75,8 +76,13 @@ for (const source of [
     'https://user:secret@example.com/media?id=cat',
     'https://example.com:8443/media?id=cat',
 ]) {
-    void test(`does not autoplay an unsafe verified GIF source: ${source}`, () => {
-        assert.equal(isGifPlaying({ ...playback, source }), false);
+    void test(`rejects an unsafe verified GIF source in every playback mode: ${source}`, () => {
+        for (const mode of Object.values(GIF_PLAYBACK_MODE)) {
+            assert.equal(
+                isGifPlaying({ ...playback, source, playback: mode }),
+                false,
+            );
+        }
     });
 }