docs(blog-site): post on cards showing their live crawl status

[FagnerMartinsBrack]

What

Adds one blog post, card-shows-what-its-preview-is-doing.md, covering the work that landed on main after the last published post (save-newsletter-links-to-your-queue, 2026-07-20).

The post is built around the newsletter-inbox card cluster from that batch:

• a07d717 — the card names its own state instead of rendering every pending/failed/title-less link as the same grey URL ("Fetching preview…" / "Preview didn't arrive" / "No preview available"), read from the link's status rather than from whether it is still polling.
• 047897c — a live region beside the list announces a card's result once to a screen reader on the pending→terminal transition, and stays silent on an unchanged 3s tick.
• 23e8d18 — stable ids keep keyboard focus on a card's action across the 3s poll redraw instead of dropping to the top of the page for the whole 15-minute window.

Why this topic

Of the commits since the last post, this cluster is the most engaging and conversion-relevant reader-facing change: it answers the "did my save work, is anything happening?" anxiety, and the accessibility depth (screen-reader announcements, focus preservation) reads as a competitive-advantage signal for search and AI-assistant surfaces. The other candidates were internal (paid-ads landing pages), already covered by earlier posts (utm stripping overlaps the clean-link posts), or minor (iOS splash).

Editorial choices

• Voice: Principle — a single claim (a card that rewrites itself on a timer owes you a word about what it is doing), proven by the one inbox-card example across sight, screen reader, and keyboard. A fresh voice against the recent war-story and feature-announcement shapes.
• Structural variety: ran the 8-post lookback. Opens on "Three" enumerating three indistinguishable card states — a first word and shape none of the last 8 used. TL;DR opens on the reader's situation, not the product name. Headers are named for what they argue, avoiding "Why this matters" / "Try it". Closing sentence rewrites the templated sign-off while keeping both links.
• Non-changelog on purpose: no changelog tag or banner, so this refinement does not displace the day-old newsletter-inbox banner. Easy to flip to a banner post if preferred — suggested copy: "I made each card say what its preview is doing".

Verification

• Frontmatter satisfies the BlogFrontmatter schema (all required fields, YYYY-MM-DD date, tags defaults to [], no changelog tag so no banner required).
• Slug matches the filename (the load-time invariant).
• Hard-rule scan clean: no semicolons or em dashes in prose, no exclamation marks, no banned words, no "however".

Dependencies are not installed in this fresh container, so the blog-site test suite was not run here; the discovery/parse invariants are verified directly against the schema instead.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GRUUcnJKkR98T7DVmJAFnq

---

Generated by Claude Code

[FagnerMartinsBrack]

@claude Review this PR. Use your Read tool to read the local file .github/workflows/claude-PR-code-reviewer.md for instructions. The file is in the checked-out repository.

Context

• Repo: Readplace/readplace.com
• PR: docs(blog-site): post on cards showing their live crawl status #984
• Commit: 5e442c3

[claude]

Claude finished @FagnerMartinsBrack's task in 6m 25s —— View job

---

Review complete

• Read review instructions (.github/workflows/claude-PR-code-reviewer.md)
• Read the changed blog post file
• Read the blog-post-editor skill for authoring conventions
• Verify frontmatter against BlogFrontmatter schema
• Verify slug/filename invariant and hard-rule scan
• Cross-check the post's claims against the referenced commits
• Post review

High Priority Issues (Must Fix)

None found.

Medium Priority Issues

1. The TL;DR / opening "three states" don't match the shipped notes

The post's hook is three indistinguishable grey URLs, each now named. The opening (line 19) and the TL;DR (line 14) list that trio as still fetching, failed for good, and a page that came back with no title, then claim "Each card now carries a short note that names its state."

Checked against the shipped mapping in inbox-link-card.viewmodel.ts:42-59, the states and labels are:

Link state	statusState	Note shown
pending + still polling	working	"Fetching preview…"
pending + poll budget spent	stalled	"Preview didn't arrive"
failed	failed	"No preview available"
crawled (title or no title)	none	(empty — no note)

Two mismatches fall out of that table:

• A crawled page with no title gets no note. It renders statusState: "none" with an empty label — a bare URL, exactly the "grey web address" the post says it no longer is. So the third member of the headline trio is not one the feature names. The post even says elsewhere (line 31) "a page that comes back with a title says nothing" — that silence applies to the no-title case too.
• "Preview didn't arrive" belongs to a state the opening never lists — a pending link whose 15-minute poll budget expired (stalled), not to "failed for good" (which is "No preview available").

Notably, the body is already correct: the section "The state it was guessing" (line 31) gives the accurate four-way mapping (running → "Fetching preview…", budget spent → "Preview didn't arrive", can't be read → "No preview available", titled → says nothing). So the fix is to realign the opening scene and the TL;DR with the body the post already wrote, or drop "a page that came back with no title" from the headline trio. A reader who only skims the TL;DR currently comes away believing a no-title card shows a note. Fix this →

Low Priority Suggestions

1. "the browser matches each new button" attributes htmx's work to the browser

Line 47: "the browser matches each new button to the one it replaced and leaves focus where the reader put it." Per commit 23e8d18 and inbox-article-card.template.html, focus survives because htmx matches the stable ids (domId / buttonId) during its swap settle — remove the ids and focus drops to <body> again. A technical reader may take "the browser" to mean native behavior. Optional softening for precision. Fix this →

2. Quoted UI string apostrophe (cosmetic)

The shipped label is "Preview didn’t arrive" (curly apostrophe, inbox-link-card.viewmodel.ts:44); the post quotes "Preview didn't arrive" (straight). Harmless, and blog quoting normally normalizes punctuation — noting only for exactness.

Summary. Solid post — the frontmatter satisfies the BlogFrontmatter schema (all required fields, YYYY-MM-DD date, no changelog tag so no banner is required), the slug matches the filename (the load-time invariant in parseBlogFrontmatter), date: "2026-07-21" sorts it newest above the 2026-07-20 newsletter post without displacing that day-old changelog banner, the internal links all resolve to existing posts, and the hard-rule scan is clean (no semicolons, em dashes, exclamation marks, or "however" in prose). The one thing worth fixing before merge is the TL;DR/opening framing: the body already describes the real state→note mapping correctly, but the headline "three" contradicts it and the code. This PR has issues that should be addressed before merging.
· claude/gracious-rubin-6qoacx

[FagnerMartinsBrack]

⚠️ Auto-fix skipped: the review run produced no parseable review block (missing CLAUDE_REVIEW_START/END): no CLAUDE_REVIEW block found in the run output. The full review is in the run's tracking comment — address any high/medium findings manually.