feat(web,api): a market link unfurled as one line, and a stalled market never said so

TWO ENDPOINTS THAT NOTHING WAS READING
Both already existed, fully built and documented, and both named the reader they
were missing.

`/markets/:token/preview.svg` renders a 1200x630 card per market — the thing a
link to a token becomes when it is pasted into X, Telegram or Discord.
`generateMetadata` on the market page returned a bare `title` and nothing else,
so the card had never been referenced and never been seen.

`/graduations/pending` carries `waitingBlocks`, and its own note says who wants
it: "the keeper reads it, the operator alerts on it, and a UI can offer the
finalise to whoever is looking at a stalled market. All three want the same
list." Two of the three were using it. `MarketDetail` has no graduation
timestamp, so without this the finalise panel could not tell a market that
entered GRADUATING a minute ago from one that entered a week ago — which is the
entire decision it asks someone to make.

The panel now says which. Under the threshold it reads as context, in the same
grey as the rest of the prose: a few hundred blocks is waiting for the large
lane, produced about once in 120. Past it, the sentence changes to a reason to
act and takes the warning colour §42 reserves for exactly that. The read fails
silently — the finalise works without knowing the age, so a reconnecting
endpoint takes the sentence away and not the button.

WHO DECIDES "STALLED"
The API, now per row. The client had been importing `STALLED_AFTER_BLOCKS` from
the handlers module to compare for itself, which is either a server module in a
browser bundle or a copied threshold that drifts (§1064). Each pending row
carries its own `stalled` and the panel renders the judgement rather than
repeating it.

I expected removing that import to shrink the bundle and it did not — /t/[token]
is 13.7 kB either way. The growth is `lib/chain.ts` pulling viem's ABI
encode/decode into the client, which the wrap flow genuinely needs. The change
stands on the one-definition argument, not the size one.

THE IMAGE IS SVG, AND THAT IS THE OPEN HALF
X, Discord and Telegram do not render SVG in an unfurl. Slack does, and the rest
omit the image and show the text card — strictly better than the bare title they
showed before. `og:image:type` is declared so a crawler skips it cleanly instead
of guessing at the bytes.

Rasterising to PNG needs a native dependency and a runtime §434 has not fixed.
That is a deployment decision; picking one here would be choosing for someone
else. When a PNG endpoint lands, only the URL and the type change.

Verified in Chrome against a market held in GRADUATING: og:title, og:description,
og:image and the twitter card all carry the market's own values; at 240 blocks
the panel shows the calm line, at 4820 it shows the amber one and the intent's
review gains a "4820 blocks ago" row. 181 API checks green.

Author: Sent-lab

apps/web/src/app/t/[token]/page.tsx

@@ -24,7 +24,7 @@
 
 import { notFound } from "next/navigation";
 
-import { getMarket, getTape, isOk } from "../../../lib/api.ts";
+import { getMarket, getTape, isOk, API_BASE } from "../../../lib/api.ts";
 import {
   formatCompact,
   formatQuoteCompact,
@@ -41,19 +41,76 @@ import { WrapPanel } from "../../../components/WrapPanel.tsx";
 
 import styles from "./terminal.module.css";
 import type { JSX } from "react";
+import type { Metadata } from "next";
 
 export const revalidate = 0;
 
+/**
+ * WHAT A LINK TO THIS MARKET LOOKS LIKE WHEN SOMEBODY PASTES IT (§117)
+ * ---------------------------------------------------------------------
+ * This returned a bare `title` and nothing else, so a market link pasted into
+ * X, Telegram or Discord unfurled as one line of text. The API has generated a
+ * 1200×630 card per market this whole time and served it at
+ * `/markets/:token/preview.svg`; nothing referenced it, so nothing ever saw it.
+ *
+ * The description is built from what the market IS rather than from marketing
+ * copy: the pair, the supply and the fee are the three facts someone deciding
+ * whether to open the link actually wants, and they are LOCKED values so they
+ * cannot go stale.
+ *
+ * THE IMAGE IS SVG, AND THAT IS THE OPEN HALF
+ * -------------------------------------------
+ * X, Discord and Telegram do not render SVG in an unfurl. Slack does, and every
+ * other crawler that cannot simply omits the image and shows the text card —
+ * which is strictly better than the bare title it showed before. So this is
+ * pointed at the SVG, with `og:image:type` declared so a crawler skips it
+ * cleanly instead of guessing at the bytes.
+ *
+ * Rasterising to PNG needs a native dependency — resvg, sharp, a headless
+ * browser — and which one depends on a runtime §434 has not fixed. That is a
+ * deployment decision, not a code one, and inventing it here would be picking
+ * for someone else. When a PNG endpoint lands, the only change is the URL and
+ * the type on the two lines below.
+ */
 export async function generateMetadata({
   params,
 }: {
   params: Promise<{ token: string }>;
-}): Promise<{ title: string }> {
+}): Promise<Metadata> {
   const { token } = await params;
   const result = await getMarket(token).catch(() => null);
 
   if (result === null || !isOk(result)) return { title: "Market" };
-  return { title: `${result.data.symbol} — ${result.data.name}` };
+
+  const market = result.data;
+  const title = `${market.symbol} — ${market.name}`;
+  const description =
+    `${market.symbol} is quoted against ${market.quoteSymbol} on SENT. ` +
+    `Fixed supply of one billion, no creator allocation, and liquidity that ` +
+    `locks permanently when the market graduates.`;
+
+  const image = `${API_BASE}/markets/${market.token}/preview.svg`;
+
+  return {
+    title,
+    description,
+    openGraph: {
+      title,
+      description,
+      siteName: "SENT",
+      type: "website",
+      images: [{ url: image, width: 1200, height: 630, type: "image/svg+xml", alt: title }],
+    },
+    twitter: {
+      // `summary_large_image` even though the image is SVG: the card type also
+      // decides the text layout, and a crawler that drops the image still lays
+      // the rest out correctly.
+      card: "summary_large_image",
+      title,
+      description,
+      images: [image],
+    },
+  };
 }
 
 export default async function TerminalPage({

apps/web/src/components/FinalizePanel.module.css

@@ -52,6 +52,28 @@
   line-height: 1.5;
 }
 
+/*
+ * How long it has been waiting.
+ *
+ * Two weights for the same fact. Under the threshold it is context and reads
+ * like the rest of the prose; past it, it is the reason the reader is being
+ * asked to act, and it takes the warning colour §42 reserves for exactly that.
+ */
+.waiting {
+  color: var(--text-dim);
+  font-size: var(--text-sm);
+  line-height: 1.5;
+}
+
+.stalled {
+  padding: var(--s-3);
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--warn);
+  color: var(--warn);
+  font-size: var(--text-sm);
+  line-height: 1.5;
+}
+
 .review {
   min-height: 3rem;
 }

apps/web/src/components/FinalizePanel.tsx

@@ -43,11 +43,12 @@
  * would overstate the pool by a factor of a trillion.
  */
 
-import { useMemo, useState, type JSX } from "react";
+import { useEffect, useMemo, useState, type JSX } from "react";
 
 import { buildFinalizeGraduationIntent, toRawForPayout } from "@sent/sdk";
 import { TOTAL_SUPPLY } from "@sent/economics";
 
+import { getPendingGraduations, isOk } from "../lib/api.ts";
 import { useWallet, CHAIN_ID } from "../lib/wallet.ts";
 import { IntentReview } from "./IntentReview.tsx";
 
@@ -75,6 +76,50 @@ export function FinalizePanel({
   const [submitting, setSubmitting] = useState(false);
   const [sent, setSent] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [waiting, setWaiting] = useState<{ blocks: bigint; stalled: boolean } | null>(null);
+
+  /*
+   * HOW LONG HAS THIS BEEN WAITING (§16, V-20)
+   * ------------------------------------------
+   * `MarketDetail` has no graduation timestamp, so the page cannot tell a
+   * market that entered GRADUATING a minute ago from one that entered a week
+   * ago. That difference is the entire decision this panel asks someone to
+   * make: a few hundred blocks is waiting for the large block lane, which is
+   * produced about once in 120 blocks; thousands means nobody finalised.
+   *
+   * `/graduations/pending` already carries it, and its own documentation names
+   * this exact reader — "a UI can offer the finalise to whoever is looking at a
+   * stalled market". It was serving the keeper and the operator and nothing
+   * else.
+   *
+   * Failure here is silent on purpose. The finalise works without knowing the
+   * age, so a reconnecting endpoint must not take the button away — it just
+   * takes the sentence away.
+   */
+  useEffect(() => {
+    const controller = new AbortController();
+
+    void (async () => {
+      const result = await getPendingGraduations({ signal: controller.signal }).catch(() => null);
+      if (controller.signal.aborted || result === null || !isOk(result)) return;
+
+      const row = result.data.pending.find(
+        (entry) => entry.market.toLowerCase() === market.toLowerCase(),
+      );
+
+      if (row === undefined) {
+        setWaiting(null);
+        return;
+      }
+
+      const blocks = parseDecimal(row.waitingBlocks);
+      // Whether this counts as stalled is the API's judgement, not a comparison
+      // repeated here against a copy of its threshold.
+      setWaiting(blocks === null ? null : { blocks, stalled: row.stalled });
+    })();
+
+    return () => controller.abort();
+  }, [market]);
 
   const intent = useMemo(() => {
     const dist = parseDecimal(distributed);
@@ -99,8 +144,10 @@ export function FinalizePanel({
       quoteAmount: toRawForPayout(collateral, quoteDecimals),
       quoteDecimals,
       quoteSymbol,
+      // Review only, and omitted rather than guessed when the read failed.
+      ...(waiting !== null ? { waitingBlocks: waiting.blocks } : {}),
     });
-  }, [curveCollateral, distributed, market, quoteDecimals, quoteSymbol, symbol]);
+  }, [curveCollateral, distributed, market, quoteDecimals, quoteSymbol, symbol, waiting]);
 
   const wire = useMemo(
     () =>
@@ -168,6 +215,22 @@ export function FinalizePanel({
         This costs real money and returns nothing. A user who finds that out
         from a gas estimate they cannot interpret has been surprised by us.
       */}
+      {/*
+        Said only when it is true.
+
+        A market a few hundred blocks in is waiting for a lane, and telling that
+        user something is wrong would be raising an alarm about a system working
+        as designed (§42). Past the threshold the API itself calls a fault, the
+        sentence changes from context to a reason to act.
+      */}
+      {waiting !== null && (
+        <p className={waiting.stalled ? styles.stalled : styles.waiting}>
+          {waiting.stalled
+            ? `Waiting ${waiting.blocks.toString()} blocks — long enough that nobody has finalised it. This is the case this button exists for.`
+            : `Waiting ${waiting.blocks.toString()} blocks. The large block lane is produced about once in 120, so a few hundred is normal.`}
+        </p>
+      )}
+
       <p className={styles.cost}>
         It costs about 5.4M gas and pays the sender nothing. That is over HyperEVM&apos;s
         default 3M block limit, so the transaction only gets included if your address is

apps/web/src/lib/api.ts

@@ -35,6 +35,7 @@ import type {
   AccountResponse,
   PlatformStatsResponse,
   HealthResponse,
+  PendingGraduationsResponse,
 } from "@sent/api/handlers";
 import type { IntentKind, IntentRow } from "@sent/sdk";
 import type { FreshnessEnvelope } from "@sent/realtime";
@@ -50,6 +51,7 @@ export type {
   AccountResponse,
   PlatformStatsResponse,
   HealthResponse,
+  PendingGraduationsResponse,
   IntentKind,
   IntentRow,
 };
@@ -496,6 +498,26 @@ export function getCreator(
   return request<CreatorResponse>(`/creators/${address}`, options, anyObject);
 }
 
+/**
+ * Markets whose curve has closed and whose pool has not been minted (§16, V-20).
+ *
+ * The API's own note on this endpoint says who wants it: "the keeper reads it,
+ * the operator alerts on it, and a UI can offer the finalise to whoever is
+ * looking at a stalled market. All three want the same list." Two of the three
+ * were using it.
+ *
+ * It carries `waitingBlocks`, which is the only place that number exists —
+ * `MarketDetail` has no graduation timestamp, so without this a finalise panel
+ * cannot say whether the market has been waiting a minute or a week. That
+ * difference is the whole decision: one is waiting for a block lane, the other
+ * has been forgotten.
+ */
+export function getPendingGraduations(
+  options?: RequestOptions,
+): Promise<ApiResult<PendingGraduationsResponse>> {
+  return request<PendingGraduationsResponse>("/graduations/pending", options, anyObject);
+}
+
 export function getHealth(options?: RequestOptions): Promise<ApiResult<HealthResponse>> {
   return request<HealthResponse>("/health", options, anyObject);
 }

services/api/src/handlers.ts

@@ -1642,6 +1642,16 @@ export interface PendingGraduationsResponse {
     readonly symbol: string;
     readonly graduatingAtBlock: string;
     readonly waitingBlocks: string;
+    /**
+     * Whether THIS market has waited past the threshold.
+     *
+     * Served rather than left for the caller to derive. A client that compared
+     * `waitingBlocks` itself would need `STALLED_AFTER_BLOCKS`, and the only
+     * ways to get it are to import this module into a browser bundle or to
+     * copy the number — one drags a server module into the client, the other
+     * is a second definition of a threshold that must have one (§1064).
+     */
+    readonly stalled: boolean;
   }[];
   /** True when at least one market has been waiting long enough to be a fault. */
   readonly stalled: boolean;
@@ -1668,6 +1678,7 @@ export function handlePendingGraduations(
       symbol: r.symbol,
       graduatingAtBlock: r.graduatingAtBlock.toString(),
       waitingBlocks: r.waitingBlocks.toString(),
+      stalled: r.waitingBlocks > STALLED_AFTER_BLOCKS,
     })),
     stalled: rows.some((r) => r.waitingBlocks > STALLED_AFTER_BLOCKS),
   });