feat(paywall): show a receipt for the settled payment before loading the content

[pedro-pelicioni]

feat(paywall): show a receipt for the settled payment before loading the content

Branch: feat/paywall-receipt
Screenshot: harness/shots/after-receipt.png

The gap

On success the paywall calls onSuccessfulResponse immediately, and the default
implementation in entry.tsx does:

document.documentElement.innerHTML = await response.text();

The whole document is replaced. The payer never sees what they were charged,
which account was paid, or the hash it settled under — the one piece of evidence
that the payment was real and checkable on-ledger.

examples/simple-paywall works around this by injecting a {{TX_LINK}}
placeholder into its own paid page (txHashInjector.ts), but that only helps
hosts serving HTML they control. Anyone serving JSON, a file, or a page they do
not template gets nothing.

The change

• useStellarPayment decodes the PAYMENT-RESPONSE header on the settled
  response and times the settlement, then reports both through a new optional
  onReceipt.
• onReceipt is awaited, so the caller can hold the hand-off. The paywall
  shows amount, recipient, transaction hash linked to Stellar Expert, and how
  long settlement took, then loads the content after receiptDelayMs (default
  3000) or as soon as Continue is pressed.
• Hosts control this through stellarReceiptDelayMs on PaywallConfig.
  Setting it to 0 skips the receipt and restores exactly the previous
  hand-off-immediately behaviour.

Behaviour change

The 3000ms pause is the one behavioural change in this PR. I think a payer
should see proof of a payment they just authorised, but it is your call —
happy to ship it as 0 by default so the receipt is opt-in. Everything else
here is additive.

Details worth flagging

• The explorer link falls back to the network named in the payment requirement
  when the facilitator reports one that is not CAIP-2, rather than dropping the
  link.
• A hand-off left pending at unmount is resolved in a cleanup effect, so the
  paid content can never be stranded behind an unresolved promise.
• Both success paths — first response and the 402-retry path — go through the
  same completePayment, each timed from its own submission.

Tests

12 new cases covering the explorer URL builder (testnet, the pubnet → public
mapping, missing inputs, non-Stellar networks, and path-escaping a hostile
hash), hash truncation, and duration formatting.

---

Part of #74.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[pedro-pelicioni]

Reopened from the Nearx-Labs fork as #82 — same commits, same diff. Closing this one to keep a single thread per change.