Skip to content

feat(thread): link cards update themselves on link_card.changed and after the app comes back - #5174

Merged
stamp-build[bot] merged 8 commits into
mainfrom
agent/lagoon/link-card-stale-reread
Nov 20, 2026
Merged

stamp-build[bot] merged 8 commits into
mainfrom
agent/lagoon/link-card-stale-reread

Conversation

@stamp-build

@stamp-build stamp-build Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Lagoon from raft opened this pull request through Stamp
View in Stamp →


Task: #proj-mobile:#213. Web/server reference: botiverse/slock staging at 080597aea6f3ea223afe2c786e89cbff4a73eb7b.

What changes for people

A link card whose App tells Raft its object changed (a PR merged, CI turned green) now updates in place while it is on screen, as on the web. After the app comes back to the foreground, or its realtime connection comes back, the cards that can update this way are read once more, quietly. Nothing spins, nothing collapses, no toast: the card shown stays until the new one arrives, and stays if the read fails.

There is no "Updated X ago" line on link cards: the web has none. message_card_updated (a replaced card message) is untouched.

A. link_card.changed, as the web does it

Rule Web (slock) App
Declare card.changed.v1; no client flag packages/web/src/components/message/linkCardRead.ts:41-43,50-53 APP_LINK_CARD_CHANGED_CAPABILITY in AppLinkCardV2.kt
Keep the item's object_key_sha256 (64 lowercase hex, only compared) packages/shared/src/appLinkPreview.ts:45-51,517-521; server services/linkCardReadService.ts:444-453 AppLinkResult.Card.objectKey
Event { app, object_key_sha256 } to the viewer's room on that Server packages/shared/src/appLinkPreview.ts:583-595; linkCardChangedRereads.ts:25,33-43 LinkCardChanged, RealtimeEventMapper, RaftLinkCardChangedHints
Wait until the row is on screen linkCardChangedRereads.ts:131-132,219 refreshCards step 1
Random 1 ms to 2 s linkCardChangedRereads.ts:23,221 APP_LINK_CARD_CHANGED_JITTER_MS
At least 10 s after this view's last re-read of that object (the came-back catch-up is timed under its own key, so a nudge's read and a catch-up read of one on-screen card can land within 10 s) linkCardChangedRereads.ts:75-80,220-221 APP_LINK_CARD_CHANGED_MIN_INTERVAL_MS
Wait while the person is on the message, then for the screen again linkCardChangedRereads.ts:185-187,225-226 AppLinkRowPresence.engaged
Read only the links of that object, as Refresh reads one; a card whose buttons are busy is left to that work useAppLinkPreviews.ts:949-966; linkCardChangedRereads.ts:64-72 rereadLinks, AppLinkRowPresence.busy
An answer with no card, rate_limited, or a failure keeps the card; nothing shows but the new card useAppLinkPreviews.ts:897-918; docs/development/app-link-previews.md:673-680 rereadLinks
rate_limited: again after the hold, as one of the view's rate-limited re-reads linkCardChangedRereads.ts:232; useAppLinkPreviews.ts:960-965 backoff from retry_after, APP_LINK_CARD_READ_RETRIES
Nudges while it waits are that read; one while it reads starts another after it linkCardChangedRereads.ts:241-246 startRefresh
An answer no row shows is marked and read when a row shown with it is on screen useAppLinkPreviews.ts:271-278,598; docs :684-686 AppLinkLoaded.changed, keepFresh

Off-screen cards, what the web does: a mounted row off screen (in the list's overscan) waits for the screen and then follows the steps above; an unmounted row's cached answer is marked changed and the whole message is read again once a row mounted with it is seen. The app does the same, with one difference listed below.

The server's flag link_card_changed_hints only decides whether Raft records readers and sends nudges (docs :1585-1589); the client has none, on the web or here.

B. Mobile only: catch-up for missed nudges

The web has no such rule (a tab stays connected). On RaftFreshnessSignal (#5115) the store, as a data owner with its own RaftFreshnessGate on the monotonic clock, marks the answers that have a card with an object key: all Servers' on Foreground, one Server's on its socket's return. Rows on screen read those cards once (after the same 1 ms to 2 s, since a server restart reconnects everyone together); the others when they are next on screen. No timer and no time-based staleness. NetworkRestored alone reads nothing: the socket's own return follows it.

Where the app differs from the web, and why

  1. A marked answer reads its keyed links, not the whole message. The web reads the whole message again when a row mounts with a changed answer. Here it is one request for just the links whose card has an object key, merged the way a nudge's re-read is. A whole read replaces every result, so a link answered rate_limited would turn a card into a plain link until its re-read; this way the card shown always stays.
  2. Came-back catch-up (B): mobile only, and only for cards whose App named an object. A card with no object key cannot be nudged on the web either, so it is never read again here.
  3. "The person is on the message" is touch-shaped: a card of the message open, the first-view question open, or Raft's confirmation open on one of its cards. The web also counts the pointer over the message, focus inside it and any open menu of it; a touch leaves nothing over a row, and the row does not know about the message's long-press menu.
  4. "On screen" is the row's text and cards drawn inside the window (onGloballyPositioned + boundsInWindow), since there is no IntersectionObserver. A list composes a row or two ahead without placing them; those are not on screen. A list recycles its rows, so a row that scrolls away is always a new row when it comes back (the web keeps rows mounted in its overscan).
  5. No page-wide read hold; the wait is the message's. The web holds every link-card read of the person after a 429 or rate_limited answer (useAppLinkPreviews.ts:176-206); the app has no such hold yet. A rate_limited re-read waits Raft's retry_after (doubling, 60 s at most) per message, kept in the store, so a row that scrolls away and back does not read sooner. The 10 s interval per object is kept per message the same way (the web keeps it per mounted view, which a list here recreates on every scroll-in).
  6. The GET fallback is re-read with the GET. A server without the batched read gives each card its digest in the GET's objectKeys (slock packages/shared/src/appLinkPreview.ts:60-68). The GET has no read of one link, so a nudge or the catch-up reads the message with the GET and takes only the cards of that object from it. The web marks such a cached answer and reads it on the next mount; it does not re-read a mounted GET row.
  7. 30 s cooldown on a failed first read. On the web a remounted row reads a failed message again at once and the 30 s cooldown (useAppLinkPreviews.ts:320-325,690-731) applies to a mounted row coming back on screen. Here every return is a remount, so a failing message was read on every scroll past it. Now a message with nothing to show whose last read failed waits out the rest of the 30 s while its row stays, and is not read if the row leaves first. A read again after Allow is the person's own and goes at once.
  8. One return is one read. The socket usually comes back a moment after the foreground, and feat(freshness): one data-layer "came back" signal; Computers and Artifacts catch up silently (#198) #5115's gate lets every new socket connection through. A socket that comes back within 30 s of the app's last coming back marks only the answers not read since then (the app's own number, APP_LINK_CARD_RETURN_WINDOW_MS); a later one is a return of its own.
  9. A re-read keeps the card when Raft answers no item (see the Refresh section): the web shows the plain link.
  10. A press runs its read on the store's dispatcher and a superseded press reports the newer read's outcome; both are the app's way to the web's single-threaded readSome.

Refresh that changed nothing (report on Android 1.27.0, release/1.27.0 @ de4ec5c)

Report: a Stamp request card in a task conversation still said "waiting for approval" about 50 minutes after the request was done; Refresh changed nothing however often it was pressed; the same link in two messages showed two stale cards. Stamp's log shows six card fetches for the six presses, each answered with the new card.

Cause: the answer was dropped because the row's view was not the view that first read the message. In 1.27.0 SharedAppLinkPreviewStore.rereadLink (SharedAppLinkPreviewStore.kt:444-461 at de4ec5c) sends the read, then applies the answer only if the stored answer of that message was read by the same message view (line 457, takeIf { it.viewId == batch.view.id } ?: return@update state) and returns true, so no toast. A row makes a new view every time it is composed (ThreadAppLinkPreviews.kt:308-313), while the stored answer is kept for the session and reused without a read. So the check fails for any row that is not the one that did the first read: after scrolling away and back, after leaving the conversation and returning, or when the message was first read in another place that shows it (the channel, then its task conversation). From then on every Refresh reaches Raft and the App, gets the fresh card, and throws it away. Nothing else read a card again before this PR, so the card stayed as first read until the app process ended.

The three candidate paths, checked against de4ec5c and main (the code is the same in both):

  1. The answer keyed by another form of the URL: not this case. The row sends card.url, which is the normalized key; the server only returns items for URLs it finds in urls (slock linkCardReadService.ts:381-384), and Stamp was fetched, so the URL matched; the item's url is normalized the same way before the lookup (AppLinkCardV2.kt parseAppLinkCardReadAnswer). A Stamp request URL is already in canonical form.
  2. Another viewId: this is it, as above.
  3. Another scope (block vs hover): no. The row draws from and re-reads into the same scope (mode = batch.read?.mode, ThreadAppLinkPreviews.kt:199 and :253); block and hover cards are fields of the one result per link.

There is no revision or version comparison in the merge, on the web or in the app: an answer with the same card_revision / business_revision replaces the card. The Raft server relays nothing stale: Refresh is not an execute, it is the batched read for that one link, and the server asks the App on every read and caches nothing across reads (slock linkCardReadService.ts:376-386,470-472).

Fixed here, as the web does it (useAppLinkPreviews.ts:897-931):

  • The view check is gone: the answer replaces the result of that link in the message's stored answer, whichever view read it first.
  • A re-read never removes a card. The web makes the link the author's plain link when Raft answers no item (useAppLinkPreviews.ts:923-925). Here the card stays and the press says it could not refresh: Raft answers no item alike when the App says the link is plain, when the App's call failed and when its answer was invalid (slock linkCardReadService.ts:219-221, 411-414, 457, all omit), and an item this client refuses reads the same, so absence is not evidence that the link is gone. A refused item is reported (projection_value_rejected source=app_link_cards_read ... item_refused).
  • A Refresh that does not end with its answer on screen returns failure, and the press shows "Couldn't refresh this card. Try again." (web linkCardExecute.tsx:750-755): a failed read, rate_limited, or no stored answer to put it in. A press whose read is superseded by a later request of the same view (two quick presses) waits for that request and reports its outcome: no toast while the card updates from the second press. Only when that request did not bring the link is the read sent again, three sends at most (web readSome, PARTIAL_READ_TRIES, useAppLinkPreviews.ts:530-545).

Diagnostics, so the next report can be read from a log (1.27.0 logged only failed reads, which is why that device's log had nothing):

  • app_link_cards_read message=<first 8 of id> links=<all|n> result=answered|failed|superseded code= items= cards= limited=: one per batched read. items above cards + limited means this client refused an item of the answer.
  • app_link_card_reread message=<8> why=press|changed links=n result=applied | kept reason=rate_limited|no_card | dropped reason=superseded|no_answer_held|signed_out | failed.
  • app_link_card_changed rows=n, app_link_card_came_back server=<bool>.
    No link, host, title or card text is logged.

Verified: the code path at de4ec5c and on main, the web's handling, the server's read, and the fix (regression test below, which fails on main because the answer is dropped at the view check). Inferred: that the phone hit exactly this path. It fits everything reported (requests went out, fresh answers came back, no change, no toast, no log line) and needs only that the row was not the first reader of the message. One thing I cannot rule out without the payload: that the app's strict reader refuses the "done" card; 1.27.0 would also have kept the old card in silence then. With this PR that case shows the plain link and logs items=1 cards=0.

The same link in two messages: each message has its own stored answer (the read, its ticket and its handles are per message), so each card is refreshed by its own Refresh, as on the web. Both now update on a nudge and after the app comes back, when the App names its object.

Tests

SharedAppLinkPreviewStoreChangedRereadTest (commonTest, virtual time):

  • nudge matching (object, Server), the jitter boundary, the card kept until the answer;
  • 10 s interval boundary, nudges coalesced while waiting, one more read after a nudge that comes while reading;
  • a row composed but not on screen is not read until it is;
  • an answer no row shows: marked, read once on next appearance, not again;
  • came back: keyed cards on screen once, an unkeyed card never, a repeated Foreground and NetworkRestored nothing, the socket coming back within 30 s of the foreground no second read, a later socket return only that Server's cards, an off-screen answer once when next shown and not twice;
  • a failed re-read keeps the card and waits the 30 s; rate_limited keeps the card and follows retry_after;
  • waits while the person is on the message; a busy card is skipped;
  • a failed first read is not repeated on every return (30 s boundary, leaving ends the wait);
  • the 1.27.0 report: Refresh on a row composed again replaces the card although its revisions are the same; the same link in another message is its own card and updates on its own Refresh;
  • two quick presses: the superseded one reports the newer read's outcome and is not sent again; when the newer read fails it is sent again;
  • a card read with the GET gets its digest from objectKeys (the web's shape) and is re-read with the GET on a nudge;
  • a failed, rate_limited, empty or refused answer to Refresh keeps the card and reports failure; a rate_limited link written in another form (upper-case host) is matched by its normalized href;
  • a press from another dispatcher reads on the store's; the 10 s interval and the rate_limited wait outlive the row;

LinkCardChangedHintTest: the event is subscribed and mapped from the snake_case wire; object_key_sha256 on v1, v2 and v3 items; an item whose key is not a digest is refused, as the strict schema does.

No screenshot golden is added or changed: nothing new is drawn. The message body is now wrapped in a Box(propagateMinConstraints = true) that only reports its position; the existing thread goldens cover that the layout is unchanged.

Not tested

Nothing here ran on a device. A device check should look at:

  • a card on screen updating in place after the App reports a change (needs link_card_changed_hints on for the Server and an App that sends object_ref and calls /api/oauth/link-preview/changed), with no flicker and the reading position kept when the card's height changes;
  • no re-read while the chip's card is open or Raft's confirmation is up, then one after closing;
  • background the app, change the object, come back: the card on screen updates within about 2 s; a card further up updates when scrolled to;
  • a row that is only prefetched (just off screen) is not read (app_link_card_changed rows= in the diagnostics, and the request log);
  • Refresh on a card after scrolling away and back, and after leaving the conversation and returning (the 1.27.0 report), with a card whose state really changed;
  • iOS: link_card.changed arriving through the Swift socket host (the event list is generated).

🤖 Generated with Claude Code

Lagoon and others added 5 commits November 20, 2026 16:51
…fter the app comes back

Port the web's "link cards that update themselves" (botiverse/slock staging
080597aea, docs/development/app-link-previews.md "Telling Raft a card changed",
web linkCardChangedRereads.ts / useAppLinkPreviews.ts):

- declare card.changed.v1 on the batched read and keep each card item's
  object_key_sha256 (AppLinkResult.Card.objectKey);
- subscribe to link_card.changed (realtime contract, mapper, LinkCardChanged)
  and hand it to SharedAppLinkPreviewStore through RaftLinkCardChangedHints;
- a row on screen whose answer shows a card of that object reads it again as
  Refresh does: after a random 1 ms-2 s, at least 10 s after its last re-read
  of that object, not while the person is on the message, never for a row that
  is only composed ahead of the scroll. Silent: the card shown stays until the
  new one comes and stays when none does;
- an answer no row shows is marked (web Loaded.changed) and read once when its
  row is next on screen.

Mobile only: the app misses nudges while it is in the background or its socket
is down, so on RaftFreshnessSignal (foreground, or a Server's socket back) the
answers with a keyed card are marked the same way. No timer, no time-based
staleness.

Also: a message whose first read failed is read again no sooner than 30 s
after that read went out (web LINK_CARD_REENTRY_COOLDOWN_MS) instead of on
every return of its row, and Refresh on a row that scrolled away and back now
replaces the card (the answer of the row before it was left untouched).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
On 1.27.0 a card kept an old state however often Refresh was pressed: the
answer to a re-read was applied only to an answer read by the same message
view, and a row composed again (scrolled away, conversation reopened) has a
new view. The request went out, the fresh answer was dropped and nothing was
said. (The view check went with the previous commit; this adds the test that
reproduces the report.)

Also as the web's reread (useAppLinkPreviews.ts:919-929): a link Raft answers
with no card on the person's own Refresh is the author's link again instead of
the old card kept in silence. A nudge's re-read still keeps the card.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… became of the answer

app_link_cards_read message=<8> links=<all|n> result=answered|failed|superseded code= items= cards= limited=
app_link_card_reread message=<8> why=press|changed links=n result=applied|kept reason=…|dropped reason=…|failed
No link, no card text. items above cards+limited means this client refused an item.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
rereadLink returns false (the press shows its toast) whenever the card shown is
not what the read answered: also when a later request of the view superseded
it, or no answer of the message is held. The person's own press takes whatever
Raft answered for the link, as the web's reread does.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@stamp-build stamp-build Bot added the build-alpha Build a cloud-hosted .alpha validation APK label Nov 20, 2026
Lagoon and others added 3 commits November 20, 2026 19:46
…arry object keys

- A press whose read a later request of the same view supersedes waits for that
  request and reports its outcome (no "Couldn't refresh" while the card updates
  from the second press); only when that read did not bring the link is the read
  sent again, three sends at most (web readSome / PARTIAL_READ_TRIES).
- The GET's objectKeys (shared appLinkPreviewListResponseSchema) gives a
  fallback card its digest, and its nudge or catch-up re-read goes with the GET.
- Say where the 10 s interval is kept that the catch-up has a key of its own.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… keep the card, one read per return

Review of #5174 at 22cd509:
1. rereadLink runs on the store's dispatcher whoever calls it (the press calls
   from the UI thread; the view's request count and tickets are the store's).
2. The 10 s interval and the rate_limited wait are the message's, kept in the
   store by read scope, so a row recreated by scrolling does not read sooner.
3. A re-read never removes a card: Raft answers no item alike for a plain link,
   a failed App call and an invalid answer, so absence is not evidence. The
   press reports failure instead. rate_limited links are matched by their
   normalized href; an item this client refuses is reported.
4. A socket that comes back within 30 s of the foreground is the same return:
   cards read for it are not read again.
Also: a superseded nudge re-read follows the newer read or goes again; a nudge
during a rate_limited wait is that read.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@stamp-build
stamp-build Bot merged commit 52a64fd into main Nov 20, 2026
13 checks passed
@stamp-build

stamp-build Bot commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

New failure in post-merge full tests: workflow App link diagnose on branch main after PR 5174 merged.

Newly failing:

  • Report (possibly flaky)

It could be any of PR 5160, PR 5162, PR 5164, PR 5165, PR 5167, PR 5168, PR 5169, PR 5170 and 14 more.

Please fix. See logs: stamp run view 44849680002 --repo botiverse/mobile --log-failed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

build-alpha Build a cloud-hosted .alpha validation APK

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants