Functions

• Purpose: App Router page for /pos. Wraps PosScreen in AppShell and OnboardingGate screen="profile".
• Inputs: None.
• Returns / side effects: The page element. No direct I/O.
• Used by: Route /pos.

• Purpose: App Router page for /pos/amount. Wraps PosAmount in AppShell and OnboardingGate screen="profile". The top-left arrow returns to the previous in-app view in this tab, or /welcome when this tab has none. It does not jump to /pos.
• Inputs: None.
• Returns / side effects: The page element. No direct I/O.
• Used by: Route /pos/amount.

• Purpose: Signed-in QR page on /pos. Renders PosTill.
• Inputs: None.
• Returns / side effects: The till card.
• Used by: /pos.

• Purpose: Amount-only card on /pos/amount. Keypad and Create payment. No QR and no address. A failed till load shows the alert and Try again. A created charge, an already open charge, or a member who cannot charge returns to /pos.
• Inputs: None. Reads the auth store.
• Returns / side effects: React element. Calls createPosCharge. On success, router.replace('/pos').
• Used by: PosAmountPage.

• Purpose: The QR card on /pos only. Centered truncated 21.gifts address, the same Open CryptoPay QR as the profile card including on a smartphone, content-width Set an amount linking to /pos/amount when no charge is open, otherwise the open charge (countdown, including 0:00, sat amount, default fiat when a gift-day rate exists, and Cancel) until the server returns no charge. A slower refresh cannot replace a newer create or cancel. No keypad on this card. No paid status. The wallet does not mount this card.
• Inputs: None. Reads the auth store.
• Returns / side effects: React element. Calls fetchPosState and cancelPosCharge.
• Used by: PosScreen.

• Purpose: Drop the module-level till write so a later test does not wait on a request the previous test left hanging.
• Inputs: None.
• Returns / side effects: Sets the in-flight write to null. Production clears that write when the request settles.
• Used by: PosScreen tests.

• Purpose: GET /pos/charge for the signed-in till.
• Inputs: Bearer sessionToken.
• Returns / side effects: { charge, history }. Throws when the response is not OK.
• Used by: PosTill, PosAmount.

• Purpose: POST /pos/charge with { amountSats }.
• Inputs: Bearer sessionToken and a whole sat amount.
• Returns / side effects: The created charge. Throws with the API error string.
• Used by: PosAmount.

• Purpose: DELETE /pos/charge.
• Inputs: Bearer sessionToken.
• Returns / side effects: Resolves when the open charge is cancelled. Throws otherwise.
• Used by: PosTill.

• Purpose: Same-origin proxy of api GET /pos.
• Inputs: Incoming Request.
• Returns / side effects: Upstream response.
• Used by: GET /pos/charge.

• Purpose: Same-origin proxy of api POST /pos.
• Inputs: Incoming Request.
• Returns / side effects: Upstream response.
• Used by: POST /pos/charge.

• Purpose: Same-origin proxy of api DELETE /pos.
• Inputs: Incoming Request.
• Returns / side effects: Upstream response.
• Used by: DELETE /pos/charge.

• Purpose: Shared export name for App Router GET handlers. Healthz and /maps/key use export function GET (/maps/key is always 200 { key: string | null }); same-origin api proxies re-export unique functions as GET (including /forum/messages, /forum/messages/places which re-exports proxyMessagesPlacesGet, /forum/messages/hidden which re-exports proxyMessagesHiddenGet, /forum/notifications which re-exports proxyNotificationsGet, /messages/[id]/photo, /messages/[id]/photo/[file] ({1-9}.{jpg|jpeg|png|webp}, proxy always requests {n}.jpg from the api), /conversations/[id]/messages/[messageId]/photo, /conversations/[id]/messages/[messageId]/photo/[file] ({1-9}.{jpg|jpeg|png|webp}, proxy always requests {n}.jpg from the api), /messages/[id]/[file], /messages/[id]/repayment which re-exports proxyMessagesRepaymentGet, /view-key/[viewKey], /push/vapid-public, /trust/graph, /trust/proposals which re-exports proxyTrustProposalsGet, /funding/applications which re-exports proxyFundingApplicationsGet, /funding/daily-roster which re-exports proxyFundingDailyRosterGet, and /funding/applications/[accountId] which calls proxyFundingApplicationGet). /translate re-exports proxyTranslateAvailableGet (api GET /translate). HTML /messages is the inbox page, not a GET proxy. HTML /notifications is the notifications page, not a GET proxy. HTML /moderate is the moderation hub, not a GET proxy. HTML /moderate/hidden is the hidden-notes page, not a GET proxy. HTML /moderate/proposals is the confirm/reject queue, not a GET proxy. HTML /moderate/applications is the grant-application queue, not a GET proxy. HTML /grants/payments/comment and /grants/payments/amounts are the daily payment pages, not GET proxies. HTML /moderate/applications/[accountId] is the grant-application review, not a GET proxy. HTML /moderate/group is the closed staff-room page, not a GET proxy. The signed-in HTML page /trust-chain is TrustChainPage, not this GET. GET /l/[code] redirects an 8-hex short code or calls notFound(). GET /links/[code] re-exports proxyShortLinkGet. HTML /pos is the till page, not a GET proxy; GET /pos/charge re-exports proxyPosGet. /forum/messages/[id]/edits re-exports proxyMessagesEditsGet.
• Inputs: Incoming Request on proxy routes (plus async params on dynamic photo, /messages/[id]/photo/[file] (id + file matching {1-9}.{jpg|jpeg|png|webp}; proxy always requests {n}.jpg from the api), /conversations/[id]/messages/[messageId]/photo (id + messageId), /conversations/[id]/messages/[messageId]/photo/[file] (id + messageId + file matching {1-9}.{jpg|jpeg|png|webp}; proxy always requests {n}.jpg from the api), file, and view-key); none on healthz or /maps/key; /translate takes the incoming Request.
• Returns / side effects: Response. Healthz is { status: 'ok' } 200; /maps/key is always 200 { key: string | null }; /translate is 200 { available: boolean } or 502; proxies return the upstream api response (JSON or raw photo/video bytes).
• Used by: Container probes, browser/wallet same-origin calls, and fetchTranslateAvailable via GET /translate. GET /.well-known/nostr.json proxies NIP-05. GET /.well-known/lnurlp/[username] proxies LUD-16.

• Purpose: CORS preflight for /.well-known/nostr.json and /.well-known/lnurlp/[username].
• Inputs: none.
• Returns / side effects: 204 with Access-Control-Allow-Origin: *.
• Used by: Damus NIP-05 fetch and LUD-16 payRequest preflight.

• Purpose: True when a picker file is MP4, WebM, QuickTime, or MPEG-4 video (type video/mp4 / video/webm / video/quicktime / video/x-m4v, or .mp4/.webm/.mov/.m4v name).
• Inputs: File.
• Returns / side effects: boolean.
• Used by: ForumLoader attach control.

• Purpose: Size-check (32 MiB) and capture a first-frame JPEG poster when the browser can decode the clip. If capture fails (iPhone HEVC / Dolby Vision), still return ok with a fallback JPEG poster.
• Inputs: File.
• Returns / side effects: { ok: true, video } with file, JPEG poster, and previewUrl; or { ok: false, error: 'unsupported' | 'tooLarge' }. Errors are only type/name (unsupported) and oversize (tooLarge) — a failed poster capture is not an error.
• Used by: ForumLoader.

• Purpose: Multipart POST /forum/messages with video + optional poster, optional goalCurrency and goalAmount (trimmed draft, comma stays; omitted from the form when either is missing, and on replies), optional placeLat / placeLng / placeLabel (only when a pin is set; replies must not send them), and optional shopUsername (leading @ stripped; omitted when blank). Not goalSats.
• Inputs: session token, { text, video, poster?, goalCurrency?, goalAmount?, place?, shopUsername? }.
• Returns / side effects: ForumMessage. On 400, 404, or 429 uses the api error string when present; otherwise throws Could not post your message.
• Used by: ForumLoader submit.

• Purpose: Build the same-origin forum video path for a message from its MIME type so playback uses .mp4, .webm, or .mov correctly.
• Inputs: messageId string and optional contentType (video/mp4 | video/webm | video/quicktime | null | undefined).
• Returns / side effects: /messages/{id}/video.mp4 | .webm | .mov (defaults to .mp4 when type is missing or unknown). No I/O.
• Used by: ForumBoard playback src when no local preview URL is set.

• Purpose: Client button beside a handbook heading, chapter, screen heading, or figure-card permalink. Copies origin + pathname + #id to the clipboard, sets location.hash, and flashes a check icon for 1.2s (textarea execCommand fallback).
• Inputs: targetId (DOM id without #) and label (interpolated into handbook.copyLink via useTranslations as { label }). Optional tone ('app' | 'dark', default 'dark'). Copied Check uses text-accent when dark and text-app-fg when app.
• Visible UI: Idle Link2 icon; copied Check icon. No visible "Copy link" or "Copied" text (title and aria-label keep the accessible name).
• Returns / side effects: A <button type="button">. Clipboard write; hash update. No network.
• Used by: HandbookPage (page title), HandbookMarkdown (every heading), HandbookFigure, HandbookSectionHeading, and ModerateHandbookScreen.

• Purpose: Render parsed handbook markdown as Tailwind-styled headings, paragraphs, lists, links, and images. Every heading has a sibling HandbookCopyLink. A paragraph whose only inline is an image becomes a HandbookFigure (thumbnail, lightbox, deep link) instead of <p><img>.
• Inputs: markdown string and idPrefix for heading ids.
• Returns / side effects: React fragment. No network.
• Used by: HandbookFunctionsPage and HandbookEndpointsPage.

• Purpose: Server-presentational chrome for the /handbook title, intro sentence, and section-nav aria-label (already-translated copy).
• Inputs: title, introBefore, introAfter, navAria (already-translated strings), headingAction (node beside the h1, e.g. copy-link), and children (the section links).
• Returns / side effects: Heading, intro with the api-handbook GitHub link, and a nav whose accessible name comes from navAria. No network.
• Used by: HandbookPage, HandbookScreensPage, HandbookFunctionsPage, HandbookEndpointsPage.

• Purpose: Async Next.js hub for /handbook. Resolves locale via getRequestLocale and links to /handbook/screens, /handbook/functions, and /handbook/endpoints without dumping those markdown files. Title copy-link uses handbook.title; intro chrome via already-translated props on HandbookIntro.
• Inputs: None (calls getRequestLocale()).
• Returns / side effects: The handbook hub inside MarketingLayout.
• Used by: Route /handbook.

• Purpose: Client loader for /stats. Fetches gift totals on mount and retry, ignores stale responses after unmount, and renders StatsDashboard.
• Inputs: None.
• Returns / side effects: React element. Calls fetchGiftStats.
• Used by: StatsPage.

• Purpose: Renders gift KPIs (formatBitcoin(totalSats) plus formatFiatDisplay of the preferred fiat from useFiatPreference; a null fiat total is —, not CHF 0) and SVG diagrams (cumulative spend over time, by person, by month), plus loading/error/empty states. FiatPicker (CHF | EUR | USD | PHP) above the KPI cards only when unsigned (useHydrateSession().ready && session === null). Signed-in visitors still display and scale with the preferred code and cannot change it here. Total spend over time links each non-zero UTC day on the chart (not as a wrapping text list) to /stats/{day}. Each of Total spend over time, By person, and By month uses SegmentedControl tone="gift" shell="dark" for ₿ | {preferred FiatCode} via BarScale 'btc' | 'fiat' (default ₿). Over time shows one cumulative series. Person and month rescale bar size while labels stay both units. Footnote is the USD daily-close sentence, or {code} is USD at each gift's UTC-day close, converted with that day's ECB rate. for CHF/EUR/PHP.
• Inputs: stats, error, loading, onRetry.
• Returns / side effects: React element. Reads useFiatPreference. No network.
• Used by: StatsLoader.

• Purpose: Next.js page for /stats. Renders StatsLoader.
• Inputs: None.
• Returns / side effects: The statistics screen inside MarketingLayout. Renders StatsLoader.
• Used by: Route /stats.

• Purpose: Next.js page for /stats/[day]. Invalid UTC days call notFound(). Valid days render DayLoader.
• Inputs: params Promise { day }.
• Returns / side effects: The day screen inside MarketingLayout.
• Used by: Route /stats/[day].

• Purpose: Client loader for /stats/[day]. Fetches GET /gifts?day=, date input navigates, retry on error. FiatPicker on the loaded table only when unsigned (useHydrateSession().ready && session === null). The summary line is {n} gift(s) · ₿ · formatFiatDisplay(total, selected fiat, numberFormat).
• Inputs: day UTC YYYY-MM-DD.
• Returns / side effects: React element. Calls fetchGiftDay. Reads useFiatPreference and useNumberFormat and passes both into GiftDayTable.
• Used by: GiftDayPage.

• Purpose: Table of individual gifts on one UTC day (Time, Recipient, ₿, {FiatCode}), or empty copy No gifts recorded on this day.
• Inputs: day: GiftDay, fiat: FiatCode, and required numberFormat (ch / us / de) for ₿ and fiat cells.
• Returns / side effects: React element. Fourth column header is the selected code; cells use formatBitcoin and formatFiatDisplay with numberFormat. No network.
• Used by: DayLoader.

• Purpose: Four-way CHF | EUR | USD | PHP control, no ₿. Optional shell default 'dark' AND optional tone default 'gift' (unsigned chart, stats, day). Profile settings (FiatPreferenceSwitcher) pass tone="neutral". Required ariaLabel (Profile and the unsigned activity chart pass catalog profile.fiatCurrency). Chart scale stays a separate ₿ | selected fiat control. Unsigned chart / stats / day mounts mean useHydrateSession().ready && session === null, not merely a null session. Forum, the public thread (PublicMessageLoader), and the pay sheet do not mount it.
• Inputs: value (FiatCode) and onChange; optional shell ('app' | 'dark', default 'dark'); optional tone ('gift' | 'neutral', default 'gift'); required ariaLabel.
• Returns / side effects: React element. No network.
• Used by: FiatPreferenceSwitcher (always, signed-in profile); AccountActivityChart, StatsDashboard, DayLoader when unsigned.

• Purpose: GET /gifts?day= and parse the per-day gift list payload.
• Inputs: UTC day string.
• Returns / side effects: GiftDay. Throws visitor copy on non-OK or invalid JSON.
• Used by: DayLoader.

• Purpose: Validate a UTC calendar day string YYYY-MM-DD.
• Inputs: Candidate day.
• Returns / side effects: true only for a real calendar date. No I/O.
• Used by: GiftDayPage, DayLoader.

• Purpose: Same-origin proxy helper for api GET /gifts (forwards day).
• Inputs: Incoming Request.
• Returns / side effects: Upstream Response.
• Used by: Route GET /gifts.

• Purpose: Next.js page for /. Marketing landing: pitch, how it works, why, project donate (#project, address [email protected] for running 21.gifts itself — distinct from /donate forum gifts), FAQ, CTAs to /login (Ask for help) and /donate (Send help), plus PwaInstall (tone="dark" placement="hero") after Send help, all via translate for the negotiated locale.
• Inputs: None. Calls getRequestLocale().
• Returns / side effects: The home screen element.
• Used by: Route /.

• Purpose: Custom language listbox (not a native <select>) that persists the visitor's override in a locale cookie and refreshes the App Router tree. Public / unsigned chrome only (Globe pill + absolute popover). Signed-in language lives on Profile.
• Inputs: tone (dark for marketing chrome, light for login, donate, unsigned /rules, unsigned /messages/[id], and /view/[viewKey]). Reads current locale via useTranslations and an optional session token from storage. No embedded prop.
• Returns / side effects: Combobox + absolute popover listbox with endonym labels. A same-locale click is a no-op. With a session token, a new locale first calls bumpLocaleGeneration(), then setAccountLocale(token, next, false); failure, a stale generation, or a response for a different account writes no cookie and does not refresh, while success merges only locale onto the current same-id account before writing the cookie and refreshing. Without a token it does not bump or POST and writes locale=<code>; Path=/; Max-Age=31536000; SameSite=Lax plus ; Secure on HTTPS before router.refresh(), as before. Never set on first visit.
• Used by: MarketingHeader (always visible), /login, /donate, unsigned /rules, unsigned /messages/[id], /view/[viewKey].

• Purpose: Profile identity-card settings section: uppercase language.label kicker and SegmentedControl tone="neutral" (default one-row rounded-full track, same as ThemeSwitcher) for English / Deutsch / Español / Filipino. Always visible on the signed-in Profile card. Not page chrome, not a Menu disclosure.
• Inputs: None. Reads current locale via useTranslations and an optional session token from storage. Catalog keys language.label, aria.language. Option labels are native endonyms (not catalogized).
• Returns / side effects: Settings row matching PushToggle chrome. A same-locale click is a no-op. With a session token, a new locale first calls bumpLocaleGeneration(), then setAccountLocale(token, next, false); failure, a stale generation, or a response for a different account writes no cookie and does not refresh, while success merges only locale onto the current same-id account before writing the cookie and refreshing. Without a token it does not bump or POST and writes the locale cookie, including Secure on HTTPS, then refreshes as before.
• Used by: ProfileScreen.

• Purpose: Profile identity-card settings section: uppercase numberFormat.label kicker and SegmentedControl tone="neutral" for the three sample labels (10'000.23 / 10,000.23 / 23.000,33). Always visible on the signed-in Profile card. Not page chrome, not a Menu disclosure.
• Inputs: None. Reads numberFormat / setNumberFormat from useNumberFormat. Catalog keys numberFormat.label, aria.numberFormat. Option labels are samples from formatGroupedNumber.
• Returns / side effects: Settings row matching PushToggle chrome. Pressing an option calls setNumberFormat (cookie write via NumberFormatProvider).
• Used by: ProfileScreen.

• Purpose: Logged-in form to set or edit a display name. Onboarding (variant="onboarding"): field at the top, Continue and labeled Skip at the bottom. Profile / overlay: icon-only actions (no Skip). Optional onSaved after a successful save.
• Inputs: Reads useAuthStore. User input: name string. Visitor-facing copy via useTranslations. Empty and request failures are typed keys so they re-render after a locale change.
• Returns / side effects: React element or null when logged out. POST /me/name on save; POST /me/setup/skip on Skip. Merges name, setup, and missing.
• Used by: NameSetup on /setup/name, ProfileScreen on /profile, and RequirementsOverlay.

• Purpose: Logged-in profile row to set, edit, or clear a free-text location. Icon-only actions (pencil / check / X / trash). Empty after trim is a valid save and clears. Not an onboarding step and has no Skip.
• Inputs: Reads useAuthStore. Optional startEditing opens the field on mount. User input: location string. Visitor-facing copy via useTranslations (location.*). Request failures use location.errorRequest.
• Returns / side effects: React element or null when logged out. POST /me/location on save or clear. Merges only location so a concurrent name or address write is not overwritten.
• Used by: ProfileScreen on /profile. FundingApplyScreen renders it in the apply walk, which is shown while applications are paused only for a verified account named joey-rosima, vincent, or jewel-bacolbas with status none or rejected, and, when the switch is off, for a verified account with status none or rejected.

• Purpose: Logged-in form to link, edit, or unlink a Wallet of Satoshi address. Onboarding (variant="onboarding"): field at the top, Continue and labeled Skip at the bottom. Profile / overlay: icon-only actions (no Skip). Optional onSaved after a successful address save (not Skip or unlink).
• Inputs: Reads useAuthStore. User input: address string. Visitor-facing copy via useTranslations. Empty, not-found, request, and notZap failures are typed keys (la.errorEmpty, la.errorNotFound, la.errorRequest, la.errorNotZap) so they re-render after a locale change. After notZap, Continue/Save stays disabled while the trimmed draft equals the blocked address; changing the draft clears the alert and re-enables; restoring the blocked address re-locks. Inline alerts (empty / notFound / request / notZap) are not separate screen variants.
• Returns / side effects: React element or null when logged out. POST /me/lightning-address on save; POST /me/setup/skip on Skip. Merges address fields plus setup and missing.
• Used by: AddressSetup on /setup/address, ProfileScreen on /profile, and RequirementsOverlay.

• Purpose: Client context provider that exposes the negotiated locale and a bound t helper to visitor-facing components.
• Inputs: locale, messages for that locale, and children.
• Returns / side effects: React provider element. No network; does not write cookies.
• Used by: RootLayout wraps every page; consumed via useTranslations (see that function).

• Purpose: Client context provider that exposes the negotiated number-format style and a setter that writes the numberFormat cookie. Nest is LocaleProvider → NumberFormatProvider initial={numberFormat} → FiatPreferenceProvider initial={fiat} → ThemeProvider.
• Inputs: initial (NumberFormatStyle from getRequestNumberFormat) and children.
• Returns / side effects: React provider element. setNumberFormat writes numberFormat=<id>; Path=/; Max-Age=31536000; SameSite=Lax and ; Secure on HTTPS. Same-id is a no-op when the cookie is already ch/us/de; selecting ch while the cookie is absent still writes so the choice persists.
• Used by: RootLayout wraps every page; consumed via useNumberFormat (see that function).

• Purpose: Client context provider that exposes the preferred fiat and a setter that writes the fiat cookie. Nest is LocaleProvider → NumberFormatProvider → FiatPreferenceProvider initial={fiat} → ThemeProvider.
• Inputs: initial (FiatCode from getRequestFiat) and children.
• Returns / side effects: React provider element. Syncs in-memory code to initial when that prop changes and no valid cookie is set (locale default after router.refresh() with no cookie). A valid fiat cookie wins over a stale initial. setFiat does not rewrite the cookie when it already equals next; in-memory state still syncs to next if it is stale. Otherwise writes fiat=<code>; Path=/; Max-Age=31536000; SameSite=Lax and ; Secure on HTTPS.
• Used by: RootLayout wraps every page; consumed via useFiatPreference.

• Purpose: Reads preferred FiatCode and setFiat from {@link FiatPreferenceProvider}.
• Inputs: None (context).
• Returns / side effects: { fiat, setFiat }. Throws outside the provider.
• Used by: FiatPreferenceSwitcher, AccountActivityChart, ForumBoard, PublicMessageLoader, StatsDashboard, DayLoader.

• Purpose: Profile identity-card settings row: uppercase profile.fiatCurrency kicker plus FiatPicker shell="app" tone="neutral" (same chrome as ThemeSwitcher / NumberFormatSwitcher / LanguagePreferenceSwitcher; selected is bg-app-btn, not orange). The only signed-in control that writes the fiat cookie. Unsigned chart / stats / day FiatPickers still write that cookie and keep default tone="gift".
• Inputs: None. Uses useFiatPreference, useTranslations, and an optional session token from storage.
• Returns / side effects: A same-fiat choice is a no-op. With a session token, a new choice first calls bumpFiatGeneration(), then setAccountFiat(token, next, false); failure, a stale generation, or a response for a different account does not call setAccount or setFiat, while success merges only fiat onto the current same-id account before setFiat. Without a token it does not bump or POST and only calls setFiat. Unsigned FiatPicker instances remain cookie-only.
• Used by: ProfileScreen.

• Purpose: Reconciles nullable signed-in account locale and fiat preferences with the screen and supported preference cookies once per account id.
• Inputs: Hydrated auth session and account, screen locale, fiat context, preference generations, and the router.
• Returns / side effects: Returns null; fills explicit null values with onlyIfUnset=true only when the generation captured before hydration still matches, mirrors a stored fiat into its cookie even when the visible code already matches, merges only that one field onto the current account, stops when the session is gone, ignores missing keys, and discards a stale response without replacing the other preference.
• Used by: RootLayout inside FiatPreferenceProvider.

• Purpose: Marks a newer explicit locale choice so older asynchronous locale work cannot overwrite it.
• Inputs: None.
• Returns / side effects: Increments and returns the module-local locale generation counter.
• Used by: Language controls before an authenticated locale POST.

• Purpose: Reads the current locale generation for stale-response guards.
• Inputs: None.
• Returns / side effects: Returns the module-local counter without changing it.
• Used by: Language controls and AccountPreferenceSync.

• Purpose: Marks a newer explicit fiat choice so older asynchronous fiat work cannot overwrite it.
• Inputs: None.
• Returns / side effects: Increments and returns the module-local fiat generation counter.
• Used by: FiatPreferenceSwitcher before an authenticated fiat POST.

• Purpose: Reads the current fiat generation for stale-response guards.
• Inputs: None.
• Returns / side effects: Returns the module-local counter without changing it.
• Used by: FiatPreferenceSwitcher and AccountPreferenceSync.

• Purpose: Accept a raw cookie/option string if it is exactly one of CHF|EUR|USD|PHP; otherwise return fallback.
• Inputs: value (optional string) and fallback (FiatCode).
• Returns / side effects: A FiatCode. No side effects.
• Used by: getRequestFiat, FiatPreferenceProvider.

• Purpose: Cookie fiat if valid; otherwise defaultFiatForLocale(locale). Never writes.
• Inputs: Request locale.
• Returns / side effects: FiatCode for this request.
• Used by: RootLayout.

• Purpose: Shared escape UI when a passkey ceremony cannot run inside Telegram or another in-app browser: heading Open this page in your browser, body copy, optional iOS hint, Open in browser, and Copy link.
• Inputs: None. Uses useTranslations, openInSystemBrowser, and origin + pathname as the URL to open or copy (so on /view/<key> the invite URL is used).
• Returns / side effects: Fragment with the escape controls. No WebAuthn. Clipboard via execCommand('copy') fallback then navigator.clipboard.
• Used by: LoginCard (in-app / unsupported branch) and ViewProfileClaim (same branch under the public view card).

• Purpose: Login UI: one Log in button (authenticate-first), an account-choice card after browser NotAllowedError (Log in with existing account / Open a new account), an unknown-passkey card after authenticate finish Unknown credential (heading login.unknownHeading, muted login.unknownBody, Open a new account and secondary Try again that calls passkey.login; dismissing the Try again login prompt stays on this card and does not open the account-choice card), preparing, error, or an in-app browser escape card via InAppBrowserView (Open in browser + Copy link, no passkey ceremony). After success, OnboardingGate leaves /login. Open a new account opens the name form. Passkey and account exist only after a valid name is submitted and the create ceremony is finished. Error uses login.error plus Try again, except a wrong-account 403 (wrongAccount or passkey error equal to that api string) which uses login.wrongAccount with the same layout. Try again on that hint calls clearWrongAccount then passkey.login (never retry, so it cannot create another account). Generic errors still call passkey.retry. When the mounted user agent is iOS below 18, Start, Choice, and Unknown show a muted login.iosVersion line (installed version and minimum iOS 18). When the mounted user agent is Android below 9, Start, Choice, and Unknown show a muted login.androidVersion line (installed version and minimum Android 9). iOS is chosen when both would match. The alert is that same sentence when passkey.error is login.iosVersion or login.androidVersion, and the muted line is then hidden. Other errors keep their own copy and still show the muted line. The line is absent until after mount. Desktop pictures omit it. Phone pictures include it, because those baselines use an iPhone user agent below iOS 18.
• Inputs: Uses usePasskeyLogin, useAuthStore, isInAppBrowser, iosPasskeyBlock, androidPasskeyBlock, and InAppBrowserView.
• Returns / side effects: React element covering idle/choice/unknown/name/starting/error/wrong-account/in-app. A signed-in account shows the preparing spinner until redirect. Detects in-app browsers after mount; never starts WebAuthn from the in-app card.
• Used by: Screen /login.

• Purpose: Next.js page for /login. The visible heading lives in LoginCard (login.heading).
• Inputs: None.
• Returns / side effects: AppShell with ProfileChromeLeft (wordmark HomeWordmark: / unsigned, /welcome when a session is hydrated) and LanguageSwitcher top-right, wrapping OnboardingGate around LoginCard. The arrow returns to the previous in-app view, or /welcome when this tab has none. Signed-in visitors are sent to /setup/name, /setup/username, /setup/address, /setup/rules, or /welcome. The recovery phrase is not part of that path.
• Used by: Route /login.

• Purpose: Next.js page for /donate. Guest-visible Send help explainer: pick a forum message, then send Bitcoin; CTA to /welcome. No address/amount form and no QR.
• Inputs: None. Calls getRequestLocale() for localized copy.
• Returns / side effects: AppShell with ProfileChromeLeft (wordmark HomeWordmark: / unsigned, /welcome when a session is hydrated) and LanguageSwitcher top-right; heading, lead, Open the forum ButtonLink. The arrow returns to the previous in-app view, or /welcome when this tab has none. No OnboardingGate.
• Used by:

- **Route /donate - Home CTA home.ctaSend - LanguageSwitcher on /donate**

• Purpose: Second post-login screen: Wallet of Satoshi address form after the name is saved. No LogoutButton.
• Inputs: Reads account.name from useAuthStore for the greeting.
• Returns / side effects: Heading Your Wallet of Satoshi address at the top and LightningAddressForm (variant="onboarding") with Continue at the bottom of the screen. No LogoutButton.
• Used by: Screen /setup/address.

• Purpose: Next.js page for /setup/address.
• Inputs: None.
• Returns / side effects: AppShell with ProfileChromeLeft top-left (non-link Wordmark span) and SignedInChrome top-right, and OnboardingGate around AddressSetup. The arrow returns to the previous in-app view, or /welcome when this tab has none.
• Used by: Route /setup/address.

• Purpose: Third post-login screen: one living-room rules chapter at a time. Intermediate Continue clicks only advance the chapter. The last I agree to these rules POSTs and merges rulesAgreedAt, setup, and missing into the auth-store account.
• Inputs: chapters — ordered server-rendered RulesDocument elements (one per RULES_CHAPTER_IDS id).
• Returns / side effects: Heading, prompt, progress, current chapter, error alert, full-width Continue until the last chapter, then I agree to these rules, Wordmark is a non-link span. Chapter 0 shows one arrow that returns to the previous in-app view in this tab, or /welcome when this tab has none. Later chapters replace that arrow with the previous-chapter arrow. One arrow. Continue and Back also reset the fill inner scroller to the top. POSTs /me/rules-agreement via agreeToRules only on the last chapter. Renders null without a session or when chapters is empty.
• Used by: Screen /setup/rules.

• Purpose: Next.js page for /setup/rules.
• Inputs: None. Calls getRequestLocale() / getCatalog for the rules body.
• Returns / side effects: Fill AppShell (align="start") with SignedInChrome top-right and OnboardingGate around RulesSetup (RULES_CHAPTER_IDS mapped to RulesDocument chapters, showNav={false}, chapter={id}). RulesSetup portals the one top-left arrow: chapter 0 returns to the previous in-app view, or /welcome when this tab has none; later chapters reuse that slot for the previous chapter.
• Used by: Route /setup/rules.

• Purpose: Matching icon+text log-out inside the signed-in Menu dropdown (not a free top-right action); clears the session and returns the visitor to /login.
• Inputs: useAuthStore.clearAuth, usePasskeyLogin.cancel, useRouter, disablePush.
• Returns / side effects: Full-width Menu-row icon+text button (same row chrome as Home / Profile / Contact). Best-effort disablePush (unsubscribe) while the session token is still valid, then clears the session and router.replace('/login'); a disablePush failure does not block log out.
• Used by: SignedInChrome Menu dropdown.

• Purpose: Display-name form when account.setup === 'name'.
• Inputs: None besides NameForm store reads.
• Returns / side effects: Heading Your name at the top and NameForm (variant="onboarding") with Continue at the bottom of the screen. No LogoutButton.
• Used by: Screen /setup/name.

• Purpose: Username field and Continue. Posts POST /me/username. Cannot skip.
• Inputs: Auth store session; optional onSaved.
• Returns / side effects: Taken/invalid/request stay on the form. Success updates the store and calls onSaved.
• Used by: UsernameSetup, RequirementsOverlay.

• Purpose: Post-login screen to choose the unique @21.gifts username. Cannot skip.
• Inputs: Auth store session; UsernameForm.
• Returns / side effects: Heading Your 21.gifts name, hint, field, Continue. Posts POST /me/username. Taken/invalid stay on the form.
• Used by: Screen /setup/username.

• Purpose: Next.js page for /setup/username.
• Inputs: None.
• Returns / side effects: AppShell with ProfileChromeLeft top-left (non-link Wordmark span) and SignedInChrome top-right, and OnboardingGate around UsernameSetup. The arrow returns to the previous in-app view, or /welcome when this tab has none.
• Used by: Route /setup/username.

• Purpose: Next.js page for /setup/name.
• Inputs: None.
• Returns / side effects: AppShell with ProfileChromeLeft top-left (non-link Wordmark span) and SignedInChrome top-right, and OnboardingGate around NameSetup. The arrow returns to the previous in-app view, or /welcome when this tab has none.
• Used by: Route /setup/name.

• Purpose: Best-effort handoff from an in-app WebView to the system browser so the visitor can complete a passkey login or invite claim in Safari or Chrome.
• Inputs: Absolute https login url, and optional SystemBrowserHost (win; defaults to globalThis.window). Missing window is a no-op.
• Returns / side effects: On Android, sets location.href to a Chrome Intent URL with an encoded fallback. Else if Telegram.WebApp.openLink is a function, calls it. Else on iOS Telegram (JS bridges or UA Telegram), sets location.href to x-safari- + url. Otherwise calls host.open(url, '_blank', 'noopener,noreferrer'). No network of its own.
• Used by: InAppBrowserView Open in browser (via LoginCard and ViewProfileClaim), the /login and /view/[viewKey] in-app e2e flows, and handbook coverage for those in-app variants.

• Purpose: Hydrates the session and sends the visitor to the matching post-login screen (or keeps a complete account on /profile, /wallet, and /members/[accountId]).
• Inputs: screen (login / wallet / name / username / address / rules / welcome / profile), children, and optional allowGuest. Members use screen="profile". /wallet uses screen="wallet". /welcome passes allowGuest.
• Returns / side effects: Children on the correct screen, otherwise a spinner. Follows nextOnboardingPath. The recovery phrase is not a setup step and does not replace the opened page; nextOnboardingPath never returns /wallet. /wallet itself stays on screen when setup is 'wallet' or the next step is /welcome. allowGuest on /welcome renders the children with no session instead of /login. Profile and members stay only when the next step is /welcome. Name, username, address, and rules still redirect when that is the next step. Other router.replace targets are /login, /setup/name, /setup/username, /setup/address, /setup/rules, or /welcome (nextOnboardingPath never returns /profile).
• Used by: Screens /login, /wallet, /setup/name, /setup/username, /setup/address, /setup/rules, /welcome, /profile, /pos, /members/[accountId], /contact, /messages, /notifications, /moderate, /moderate/hidden, /moderate/proposals, /grants, /grants/apply, /grants/applications, /grants/applications/[accountId], /trust-chain, /shops, /statistics.

• Purpose: Top-right signed-in chrome: one Menu control; open it for icon+label dropdown rows (Home /welcome lucide Home nav.home — when the path is already /welcome, Home preventDefaults and dispatches FORUM_HOME_EVENT instead of a no-op navigation; Shops (/shops, lucide Store, nav.shops); Point of sale (/pos, lucide Banknote, pos.nav); User Profile (/profile, lucide User, profile.title) with no given or received amounts; Grants (/grants, lucide HandCoins, nav.grants) for every signed-in member; Wallet (/wallet); ScrollText Living room rules /rules; Habit-Tracker (/habit-tracker, lucide ListChecks, nav.habitTracker); Trust Chain; Statistics (/statistics, lucide BarChart3, nav.statistics) for every signed-in account, immediately after Trust Chain, with no unread count; Moderation (/moderate, lucide Shield, nav.moderate) only when roleAtLeast(account?.role, 'moderator') — aria-label nav.moderateUnread with { count } when moderationUnreadCount > 0 (staff-room unread plus open-proposal count) else nav.moderate; visible nav.moderate plus ml-auto tabular-nums count when > 0; Notifications (/notifications, lucide Bell, nav.notifications, unread count ml-auto only when unreadCount > 0, aria-label nav.notificationsUnread then); Messages /messages (nav.inbox, unread count ml-auto only when inbox unread > 0, aria-label nav.inboxUnread then); MessageCircle Contact /contact; optional Download Install app via PwaInstall placement="menu" when install is offered; LogOut log out; then a quiet Version line (app.version, getAppVersion())). On mount with a session, calls resyncPushSubscription. Clicking Notifications asks for OS permission via enablePush when it is not already granted and Service Worker plus PushManager exist (otherwise resync, which no-ops without those APIs). When account.setup is null and account.hasPosted is false, also mounts IntroduceYourselfOverlay (Close dismisses this mount only; Write an introduction calls requestForumCompose so a remount after router.push('/welcome') stays hidden).
• Inputs: Session account and session from useAuthStore (introduce overlay gate and push resync). Composes useUnreadCount(open) (default write-badge: writes the home-screen badge), PwaInstall (placement="menu", closes Menu via onMenuAction), and LogoutButton inside the Menu dropdown.
• Returns / side effects: Relative Menu button (aria-expanded, aria-controls) in the AppShell page-frame header ([data-app-chrome]). The panel stays mounted. Wide (frame content box at least 576px; until frameWidth is measured, matchMedia('(max-width: 36rem)'), and a missing matchMedia counts as wide): it portals to the trigger parent as absolute right-0 z-50 mt-2 w-72 (18rem, not a percentage, because a percentage would resolve against the trigger). When that wide panel's bottom would pass the window, the same panel uses mt-0, px-2 py-0, and the version line uses py-0. Rows stay min-h-11. If that compact panel still passes the window and a non-negative lift keeps the bottom inside, it is a fixed overlay. Its style sets the measured top, left, and width so the bottom sits on the window and the top is never less than 0. That left is the trigger parent's right edge minus the panel width, so a horizontal move of the frame does not keep the last inline left. It does not scroll, and it does not shorten a row. When that lift would still leave the bottom outside, the wide menu uses the same sheet as a narrow frame (w-full, html[data-menu-sheet='1'], no scroll) and does not use a negative top. The Menu button is relative z-[60] only while that fixed overlay is up, so a click on Menu still closes it when the panel covers the button, and a dialog in the same header still covers Menu. A window resize or a later change in the panel's own size measures again. The panel returns to mt-2 and p-2 only when the compact box still has 48px of room under the window, so the two layouts do not alternate. The scrim #signed-in-menu-scrim portals to [data-menu-scrim-host] inside [data-app-frame] as absolute inset-0 z-40 rounded-3xl (the radius is set on the scrim; the host is display: contents, so inherit would be 0). Narrow (content box under 576px): it portals to [data-menu-sheet-host] (px-8, the same horizontal inset as [data-scroll-page]) inside the one scrollport as w-full and stays in that host while closed (hidden), reads the scrollport scrollTop before it sets html[data-menu-sheet='1'] (which hides [data-scroll-page]), sets that scroll position to 0, and writes the saved position back after the page is shown again. Not a body portal. PwaInstall stays mounted via the hidden class when closed. When open, icon+label rows: Home (/welcome, lucide Home, nav.home), Shops (/shops, lucide Store, nav.shops), Point of sale (/pos, lucide Banknote, pos.nav), Profile link (/profile, lucide User, profile.title) with no given or received amounts, Grants (/grants, lucide HandCoins, nav.grants) for every signed-in member, Wallet (/wallet, lucide Wallet, wallet.title), Living room rules (/rules), Habit-Tracker (/habit-tracker, lucide ListChecks, nav.habitTracker), Trust Chain (/trust-chain), Statistics (/statistics, lucide BarChart3, nav.statistics) for every signed-in account, immediately after Trust Chain, with no unread count, Moderation (/moderate, lucide Shield, nav.moderate) only when roleAtLeast(account?.role, 'moderator') — aria-label nav.moderateUnread with { count } when moderationUnreadCount > 0 (staff-room unread plus open-proposal count) else nav.moderate; visible nav.moderate plus ml-auto tabular-nums count when > 0, Notifications (/notifications, lucide Bell, nav.notifications, unread count on the right when greater than zero), Messages (/messages, nav.inbox, inbox unread count on the right when greater than zero), Contact (/contact), optional Install app, and log out, then a quiet Version line (app.version, getAppVersion()). Escape always closes Menu and restores focus to Menu. Local useState dismissed flag for IntroduceYourselfOverlay (initialized from consumeSkipIntroduceOverlay); does not write forumLawsDismissed or any account field.
• Used by: NameSetupPage, UsernameSetupPage, AddressSetupPage, RulesSetupPage, WelcomePage, ShopsPage, PosPage, ProfilePage, GrantsPage, FundingApplyPage, WalletPage, MemberProfilePage, ContactPage, MessagesPage, NotificationsPage, ModeratePage, HiddenNotesPage, ProposalsPage, FundingApplicationsPage, FundingApplicationDetailPage, TrustChainPage, StatisticsPage, HabitTrackerPage, RulesPageChrome, PublicMessageChrome.

• Purpose: Next.js page for /profile.
• Inputs: None.
• Returns / side effects: AppShell with ProfileChromeLeft top-left, SignedInChrome top-right, and OnboardingGate around ProfileScreen.
• Used by: Route /profile.

• Purpose: Shared top-left chrome: one icon-only arrow (44px, ArrowLeft) plus a wordmark. The arrow returns to the previous in-app view in this tab, or /welcome when this tab has none. One arrow. The wordmark is not that control. An ask-wizard or shop-wizard override replaces the history link with a button. Optional onBackClick runs on an unmodified click (wallet hides the words or closes Advanced functions before leaving). Optional wordmark replaces the default wordmark. Optional wordmarkHref defaults to /welcome and is ignored when wordmark is set. tone="dark" is the ink marketing header. hideWithoutHistory omits the arrow only when this tab has no earlier view and no wizard override.
• Inputs: Optional onBackClick, wordmark, wordmarkHref, tone, and hideWithoutHistory; catalog via useTranslations; previous path via previousViewPath.
• Returns / side effects: A link (profile.back when this tab has no earlier view, otherwise nav.back), the override button, or no arrow when hideWithoutHistory has neither history nor an override, plus the wordmark. The first client render matches SSR (/welcome, profile.back) unless hideWithoutHistory hides that arrow. An unmodified primary click calls onBackClick or goToPreviousView and does not follow the href. Modified clicks follow the href. No network.
• Used by: ProfilePage, WelcomePage, MarketingHeader, LoginPage, DonatePage, PayLinkScreen, ViewProfilePage, NameSetupPage, UsernameSetupPage, AddressSetupPage, WalletChromeLeft, WalletScreenView (the visible /wallet Back, via AppShellTopLeft), ShopsPage, GrantsPage, FundingApplyPage, MemberProfilePage (/members/[accountId]), ContactPage, MessagesPage (via MessagesChromeLeft), MessagesChromeLeft, NotificationsPage, ModeratePage, HiddenNotesPage, ProposalsPage, FundingApplicationsPage, FundingApplicationDetailPage, ModeratorGroupPage, TrustChainPage, RulesPageChrome, PublicMessageChrome. WalletPage mounts WalletChromeLeft as page topLeft; the card's registration wins while Wallet is shown.

• Purpose: Clear the stored /wallet return path. The top-left arrow does not read this slot. It returns to the previous in-app view in this tab, or /welcome when this tab has none.
• Inputs: None.
• Returns / side effects: void. Drops the shared tab slot and sessionStorage key 21gifts.walletReturn. Does not touch localStorage.
• Used by: Wallet return tests, RememberWalletReturn tests, WalletChromeLeft tests (afterEach).

• Purpose: Remember a safe in-app path (not Wallet itself) as the /wallet back target. Rejects protocol-relative URLs, .., whitespace, #, overlong paths, and /wallet itself without clobbering a previous good path.
• Inputs: path string (pathname, optionally with a query string).
• Returns / side effects: void. Writes a globalThis slot and sessionStorage (21gifts.walletReturn) so every copy of the module in this tab sees the same path. No localStorage. No-op during SSR.
• Used by: RememberWalletReturn.

• Purpose: Read the path rememberWalletReturn stored, or /welcome when this tab has not stored one. The visible top-left arrow does not use this value. That arrow uses the in-app view stack.
• Inputs: None (reads the shared tab slot, which loads sessionStorage the first time).
• Returns / side effects: The stored path string, or WALLET_BACK_FALLBACK (/welcome). No network. The chrome arrow does not read this value.
• Used by: Unit tests of the wallet-return slot. Not the chrome arrow.

• Purpose: Client recorder mounted in the root layout. On each pathname/search change, calls rememberWalletReturn with the current in-app path. The top-left arrow does not read this slot.
• Inputs: usePathname and useSearchParams. Non-empty query is appended as ?….
• Returns / side effects: null. Calls rememberWalletReturn during render and again from an effect. No network.
• Used by: RootLayout (inside ThemeProvider, wrapped in Suspense).

• Purpose: Listens for 21gifts-push-open from the service worker and calls router.push only for a same-origin path, so an already open installed phone page can follow the notification URL. On mount, when the page becomes visible, and when it returns from the back-forward cache, it also opens a path the worker stored in the 21gifts-push-open cache (at most 60 seconds old) in case a frozen page missed the message. A query may contain ://. The page answers the worker; if that answer does not arrive and the window cannot navigate, the worker opens the href. Each click has its own id, and only that id is dropped after the page follows it.
• Inputs: MessageEvent on navigator.serviceWorker, plus a JSON { url, at, id } cache record at /push-open/{id}. Accepts only data.type === '21gifts-push-open' with a string data.url that starts with /, contains no \, and parses as this origin. A query or hash may contain ://. Drops a missing, stale, future, or unsafe cache record. A click id that is no longer the stored id is left in place.
• Returns / side effects: null. Navigates with router.push when the path is a same-origin in-app URL; ignores anything else. No network.
• Used by: RootLayout (inside ThemeProvider, after AccountPreferenceSync).

• Purpose: Page /wallet chrome. Renders ProfileChromeLeft only. The arrow returns to the previous in-app view in this tab, or /welcome when this tab has none. One arrow. The wordmark is not that control.
• Inputs: None. The previous path comes from the view stack inside ProfileChromeLeft.
• Returns / side effects: ProfileChromeLeft. The card's Back replaces this one while Wallet is shown. No network.
• Used by: WalletPage.

• Purpose: Client /messages chrome. Always renders ProfileChromeLeft. It does not read ?c= and it does not send every open thread to /messages. The view stack does: a thread opened from the list returns to the list; a thread opened from somewhere else returns there.
• Inputs: None.
• Returns / side effects: ProfileChromeLeft. The arrow returns to the previous in-app view in this tab, or /welcome when this tab has none. One arrow. The wordmark is not that control. No network.
• Used by: MessagesPage.

• Purpose: Read the in-app path this tab showed immediately before the current view. The top-left arrow uses it. The wordmark is not that control.
• Inputs: None. Reads the tab slot. When the slot is missing, reads 21gifts.viewHistory and restores it. An empty store stays missing.
• Returns / side effects: The previous path, or null on the server and when this tab has no earlier in-app view. No network.
• Used by: ProfileChromeLeft, RulesSetup.

• Purpose: Leave for the previous in-app view in this tab, or open /welcome when this tab has none. Does not jump to a fixed parent and does not leave the site.
• Inputs: None. Reads previousViewPath.
• Returns / side effects: location.assign of the previous path, or location.assign('/welcome') when this tab has none. Does not call history.back() and does not pop the stack before that load, so a second click assigns the same path. The next document steps the cursor back to the opened path. No network.
• Used by: ProfileChromeLeft, RulesSetup, WalletScreenView.

• Purpose: Record the current in-app path on this tab's view stack, or restore a stamped index on browser back and forward. A router pushState is a push, even when history.length does not grow. A URL-changing replaceState replaces the current entry once this document is anchored, so a replaced screen is not a previous view. The first path of a new document is a push, unless it is the arrow's one-shot target, which steps the cursor back. Unsafe paths are ignored. A real return to an earlier path is a new entry, not a collapse. The stack caps at 50 once a push is committed. A push that is not yet committed does not drop the oldest view; a later replace collapses that push first. A dropped entry keeps its absolute stamp, so browser back still finds it.
• Inputs: A pathname, optionally with a query string. Optional stampHistory defaults to true. False updates the stack and does not write giftsView, so the history entry being left keeps its stamp.
• Returns / side effects: Updates the module slot and sessionStorage (stack and cursor, plus base after a capped drop). When stampHistory is true, stamps giftsView with history.replaceState without pushing a history entry. A stored stack that contains an unsafe path is ignored. A thrown storage write leaves the slot intact. No network.
• Used by: ViewHistoryRoot.

• Purpose: Clear this tab's in-app view stack so the top-left arrow opens /welcome until another view is recorded.
• Inputs: None.
• Returns / side effects: Deletes the module slot and removes 21gifts.viewHistory from sessionStorage. No network.
• Used by: Unit tests that isolate the view stack.

• Purpose: Record the current pathname and search on the in-app view stack and provide the chrome back override. The top-left arrow returns to the previous in-app view in this tab, or /welcome when this tab has none. One arrow. The wordmark is not that control.
• Inputs: children — the page tree.
• Returns / side effects: ChromeBackProvider around children. A location recorder writes the stack during render without stamping history, and stamps giftsView from a layout effect after the router commits the history entry. A pathname the location has not reached yet is not recorded, so a query is not stored as its own hop. A replace committed after that render collapses the provisional push, so a replaced screen is not a previous view. Search comes from window.location.search when it matches the pathname, so a full navigation is stored before the load event. A suspended search recorder re-renders on a query-only change, including a cleared query, and records the live location — the same string as the location recorder, and only once that location has reached the pathname. No network.
• Used by: RootLayout, inside ThemeProvider, beside RememberWalletReturn.

• Purpose: Read and set the top-left arrow override for an in-page step such as the ask wizard. Without a provider, the override is null and the setter is a no-op, so a wizard render does not throw.
• Inputs: None. Reads ChromeBackProvider context when it is present.
• Returns / side effects: { override, setOverride }. Does not navigate by itself. No network.
• Used by: ProfileChromeLeft, ForumAskWizard, ShopAddWizard, the welcome top-left chrome.

• Purpose: Hold the top-left back overrides, one slot per caller. The chrome arrow runs the latest in-page step instead of the view history. Pay-sheet dismiss stays Close (X), not this control.
• Inputs: children.
• Returns / side effects: Context provider. Each caller has its own slot. The arrow shows the last set override. Clearing or unmounting a caller restores the previous. No network.
• Used by: ViewHistoryRoot.

• Purpose: Signed-in profile: single max-w-sm identity card with a resting header (round profile photo from GET /pictures/me and wide image from GET /banners/me when that slot is stored; a missing one is the button Add a profile photo or Add a wide image; choosing a wide image opens a 5:2 cropper in place of Add a wide image (Add a profile photo stays; Use this crop stores the framed JPEG; the X (Cancel crop) stores nothing; saving the profile photo, including from About me, reloads the header and leaves that open crop in place; a failed or empty reload clears that header picture, and the Add button stays hidden until the reload settles); neither is the About me photo), a compact Given/Received activity chart, About me (AboutMeSection owner: empty prompt + Write your About me, or filled text and/or photo + edit; Languages Translate on the filled read-only text when aboutMessageId is set; the editor is not translatable; copy-profile-link on the card — never a forum post), name, location, then the same public facts as /members/:id (MemberProfileScreen factsOnly: role pill, funding-program icon (pressing it reveals that one sentence; on this screen the pressed result is funding-program-press), [email protected], pay QR, Shop sticker, Posts/Reactions counts, and the activity feed), then Wallet of Satoshi address forms, then PushToggle (Notifications pills: All/Active/Mentions always; This device On/Off when Push APIs are ready), a language settings row (LanguagePreferenceSwitcher) after push and before theme, a theme settings row (ThemeSwitcher), a fiat settings row (FiatPreferenceSwitcher), and a number-format settings row (NumberFormatSwitcher) last. Never shows forum.loading on the card. The signed-in menu Profile row shows no amounts. Back + wordmark live in ProfileChromeLeft.
• Inputs: useAccountTotals for both receiveOverTime and donateOverTime (also returns failed); pass both to AccountActivityChart; AboutMeSection (putAboutMe text plus optional photo, fetchAboutMePhoto when aboutMeHasPhoto, fetchProfilePhoto, fetchWideBanner, name={account.name}); NameForm, LocationForm, and LightningAddressForm for edits; fetchMember(session, account.id) then MemberProfileScreen with factsOnly for the public gifts facts; PushToggle; LanguagePreferenceSwitcher; ThemeSwitcher; FiatPreferenceSwitcher; NumberFormatSwitcher; catalog via useTranslations.
• Returns / side effects: When a profile photo or wide image is stored, that header is above the heading (wide image aspect-[5/2], round photo overlapping its lower edge when both exist). Heading Profile, compact chart (empty: profile.chartEmpty with no chart FiatPicker, no SVG / no ₿|fiat scale; a thrown activity load shows profile.chartError (role="alert") instead of profile.chartEmpty; in-flight stays profile.chartEmpty; never Loading…; populated: legend + ₿ | selected fiat + SVG). The only FiatPicker on the card is FiatPreferenceSwitcher. About me, name form, location form, then the public member facts (role pill, funding-program icon (pressing it reveals that one sentence; on this screen the pressed result is funding-program-press), [email protected], QR, Shop sticker, post/reaction counts, and the on-demand feed), then the Wallet of Satoshi address form, then PushToggle (Notifications pills), Language (English / Deutsch / Español / Filipino), Theme (System / Light / Dark), Fiat currency (CHF|EUR|USD|PHP), and Number format (10'000.23 / 10,000.23 / 23.000,33) as the last settings row — all inside one identity card (no second panel). A failed fetchMember shows forum.error and Try again and leaves the editors up. MissingRequirementsError replaces to /setup/rules. No Message button and no staff actions. Back + wordmark live in ProfileChromeLeft.
• Used by: ProfilePage.

• Purpose: Profile-card About me block: heading plus filled text and/or photo (the note photo shows the whole picture (object-contain, max-h-80) and is not cropped, not the profile photo or the wide image), or the owner empty prompt (profile.about.empty Tell others who you are. and labeled Write your About me). Filled means trimmed aboutMe is a real bio (not the display name) or hasPhoto is true. Owner mode can edit (write / pencil, save, cancel) via onSave. The editor has three separate attaches, each its own ImagePlus and remove: the About me photo (JPEG/PNG/WebP via prepareForumPhoto, no video), the round profile photo, and the wide image. Each previews on its own. Choosing a wide image opens a 5:2 cropper above its preview; Use this crop stores that JPEG and the X (Cancel crop) stores nothing. Closing the editor, or a successful save, drops an unsaved crop. A whole portrait is not stored as the wide image. Optional icon-only copy-profile-link (profile.copyLink Copy link to this profile) when profileUrl is set; the URL is never shown as visible text. Public mode with no filled text, no photo, and no copy URL renders null. A filled read-only body uses TranslatableNoteBody when messageId is a non-empty string; otherwise LinkedText. The editor is not translatable.
• Inputs: aboutMe (string | null), mode (owner | public), optional name (string | null) for the filled comparison ((name ?? '').trim(); blank name applies only the trimmed-non-empty check), optional hasPhoto, optional loadPhoto (() => Promise<Blob>), optional profileUrl, optional messageId (stored About me note id; omitted or blank keeps LinkedText), optional onSave(text, photo?) (photo omitted keeps, null clears, object sets), optional loadPicture / onSavePicture for the round profile photo and optional loadBanner / onSaveBanner for the wide image (neither is the About me note photo; a non-image blob stays empty), optional startEditing to open the owner editor on mount.
• Returns / side effects: React element or null. Clipboard write for copy. Calls onSave on owner save, onSavePicture when the profile photo changes, and onSaveBanner when the wide image changes. Loads a blob URL when hasPhoto and loadPhoto are set and revokes it on unmount. Loads and revokes the profile-photo and wide-image blob URLs the same way when loadPicture or loadBanner is set.
• Used by: ProfileScreen (owner, name={account.name}), MemberProfileScreen (public, name={profile.name}), ViewProfileScreen (public, name={profile.name}), and FundingApplyScreen (apply walk, shown while applications are paused only for a verified account named joey-rosima, vincent, or jewel-bacolbas with status none or rejected, and, when the switch is off, for a verified account with status none or rejected).

• Purpose: Profile identity-card Notifications section: uppercase heading profile.push.heading, a SegmentedControl tone="neutral" All / Active / Mentions (profile.push.level.all / active / mentions, group profile.push.level.label) whenever a session exists (including while Push APIs are still being inspected), a muted hint (profile.push.level.hint), and a second On / Off SegmentedControl (profile.push.on / off, group aria.push This device) only when serviceWorker / PushManager are ready. No Bell / IconButton / trailing slot. Changing the level POSTs /me/notification-level via postNotificationLevel and merges notificationLevel into the current store account when the session still matches; a second change while the POST is in flight is ignored; failure keeps the previous value and shows profile.push.level.error. The device pill calls enablePush / disablePush; same-value or busy is a no-op. Renders nothing without a session. On iPhone Safari outside standalone, shows profile.push.installHint under the device pill.
• Inputs: Session and account from useAuthStore; catalog via useTranslations; postNotificationLevel / accountNotificationLevel / setAccount; enablePush / disablePush / isIosSafari / isStandaloneDisplay.
• Returns / side effects: Heading, All/Active/Mentions control (always when a session exists), muted hint, and (when Push APIs are ready) a This-device On/Off SegmentedControl. Level change calls postNotificationLevel then merges notificationLevel; On calls enablePush when not subscribed, Off calls disablePush when subscribed; may show profile.push.unavailable on push failure or profile.push.level.error on level failure.
• Used by: ProfileScreen.

• Purpose: Load signed-in unread notification, inbox, staff-room, and open-proposal counts in parallel (GET /forum/notifications + GET /conversations, plus GET /conversations/moderator-group and GET /trust/proposals when roleAtLeast(account?.role, 'moderator')). refreshKey retriggers the fetches (Menu open). Does not mark notifications or conversations read.
• Inputs: refreshKey boolean; optional options?: { writeBadge?: boolean } (omit the object to default). Default writes the home-screen badge. writeBadge: false fetches and returns the four counts but does not call setUnreadAppBadge (including the logout / session-null 0 write).
• Returns / side effects: { unreadCount, inboxUnreadCount, moderationUnreadCount, proposalCount }. unreadCount is the notifications unread count. inboxUnreadCount is the number of conversation rows with unread: true. proposalCount is the open-proposal list length. moderationUnreadCount is staff-room unread (0 or 1) plus proposalCount, for the Menu Moderation row. Hub Open proposals uses proposalCount alone. When badge writes are enabled (the default), the home-screen badge is notification unread + inbox unread + staff-room unread (0 or 1) — open-proposal count is not added (proposal rows already sit in notification unread) — written once all started fetches settle. A role below moderator skips the staff-room and proposals fetches and contributes 0. A thrown staff-room or proposals fetch contributes 0 without failing the other sides. Either of the other sides failing contributes 0 to the sum; the other sides still write. Epoch skip applies to that sum write. No session → all four counts 0; badge 0 only when writes are enabled and loadSession() === null (real logout). A hydrating store (session null, token still in storage) does not clear the badge. A cancelled fetch updates neither React state nor the badge.
• Used by: SignedInChrome (default write), ModerateScreen (writeBadge: false).

• Purpose: Set or clear the installed PWA home-screen unread badge via the Badging API (navigator.setAppBadge / navigator.clearAppBadge). When count > 0 and setAppBadge exists, sets that number; otherwise clears when clearAppBadge exists. Missing APIs are a no-op. Rejections are swallowed so unsupported or denied badge writes never throw into the UI.
• Inputs: count (number) — notification unread plus inbox unread plus staff-room unread (0 or 1). Positive values request a badge; 0 (and any non-positive) request a clear.
• Returns / side effects: void. Fire-and-forget promises; does not await. No network.
• Used by: useUnreadCount, NotificationsLoader, refreshUnreadAppBadge, useAuthStore.clearAuth.

• Purpose: Increment the home-screen badge epoch so in-flight unread fetches do not overwrite a mark-all-read clear, and after inbox mark-read so they do not overwrite the remaining sum.
• Inputs: None.
• Returns / side effects: The new epoch number.
• Used by: NotificationsLoader, InboxLoader, ModeratorGroupScreen, useAuthStore.clearAuth.

• Purpose: Read the current home-screen badge epoch. Capture before an async unread fetch; skip setUnreadAppBadge if it changed.
• Inputs: None.
• Returns / side effects: Current epoch number. No network.
• Used by: useUnreadCount, NotificationsLoader, refreshUnreadAppBadge.

• Purpose: Refresh the installed PWA home-screen badge to notification unread plus inbox unread plus staff-room unread (0 or 1). Signature refreshUnreadAppBadge(sessionToken, inboxUnreadOverride?, moderationUnreadOverride?). Fetches GET /forum/notifications and, unless an inbox override is passed, GET /conversations. When the moderation override is omitted, fetch GET /conversations/moderator-group only when roleAtLeast(account?.role, 'moderator') (unread true → 1, else 0; throw/404 → 0); a role below moderator contributes 0 without starting the request. When the moderation override is set, skip that fetch. Any side failing contributes 0. Captures the badge epoch at start; skips the write if the epoch changed or loadSession() is not still sessionToken. Never rejects.
• Inputs: sessionToken (string). Optional inboxUnreadOverride (number) — when set, skip the conversations fetch and use that inbox unread count (e.g. the local list after mark-read). Optional moderationUnreadOverride (number) — when set, skip the staff-room fetch and use that count (0 or 1). When the moderation override is omitted, skip the staff-room fetch unless the signed-in auth-store account is at least moderator.
• Returns / side effects: Promise<void>. Calls setUnreadAppBadge with the sum only when the epoch is unchanged and loadSession() === sessionToken. Fire-and-forget safe.
• Used by: InboxLoader after a successful thread load and mark-read (inbox override only; fetches staff-room only when the account is at least moderator). ModeratorGroupScreen after opening the room (moderation override 0).

• Purpose: Collapse tag for one in-app notification, matching the api: forum_post:<parentId>, forum_reply:<replyId>, forum_mention:<replyId>, zap:<replyId>, moderator_appointed:<parentId>. Any other type, including moderator_proposal, is null.
• Inputs: type, parentId, and replyId.
• Returns / side effects: Tag string or null. No network.
• Used by: NotificationsLoader before it closes the local banner for a row that is not a proposal, and ForumLoader after the welcome appointment pill's markNotificationRead succeeds.

• Purpose: Read this browser's Web Push subscription endpoint so a mark-read request can ask the api to skip this device. Calls getRegistration() and does not wait on ready.
• Inputs: None. Uses navigator.serviceWorker when it exists.
• Returns / side effects: The endpoint string, or undefined when Push APIs are missing, the lookup rejects, or the endpoint is empty. Never throws.
• Used by: markNotificationRead, markAllNotificationsRead, markNotificationsReadForMessage, and markVisibleForumNoteRead.

• Purpose: Close shown Web Push notifications whose tag is in the list, so a note already read on this device does not stay on screen. Calls getRegistration() and does not wait on ready.
• Inputs: Tag strings. An empty list is a no-op.
• Returns / side effects: Nothing. Missing serviceWorker or getNotifications is a no-op. Never throws.
• Used by: markAllNotificationsRead, markNotificationsReadForMessage, markVisibleForumNoteRead, NotificationsLoader when a row is opened, and ForumLoader after the welcome appointment pill's markNotificationRead succeeds.

• Purpose: Decode a VAPID application server public key (url-safe base64) to bytes for pushManager.subscribe.
• Inputs: Url-safe base64 public key string.
• Returns / side effects: Uint8Array. No network.
• Used by: enablePush.

• Purpose: Register the push-only service worker at /sw.js (scope /) and wait until ready.
• Inputs: None (uses navigator.serviceWorker).
• Returns / side effects: ServiceWorkerRegistration.
• Used by: enablePush, disablePush, resyncPushSubscription.

• Purpose: Push-only service worker at /sw.js. A payload whose type is dismiss closes the named tags, shows and closes a silent dismiss-ack, sets the badge to max(0, floor(unreadCount)) including 0, and returns before the Sunday check. On the device's local Sunday, a push whose type is not exactly conversation does not stay on screen and does not change the badge: it calls showNotification with tag sunday-quiet and closes that note in the same waitUntil, so the browser does not invent its own banner. Every other push, including a private message, shows a notification (registration.showNotification) and, when navigator.setAppBadge (or registration.setAppBadge as fallback) exists, sets the home-screen badge: floor payload.unreadCount first, use it when that integer is greater than 0, otherwise 1. setAppBadge rejections are swallowed so waitUntil still follows showNotification. Missing setAppBadge still shows the notification. A thrown weekday lookup does not pause notifications. No asset or offline cache. A notification click stores a short-lived 21gifts-push-open entry so a reloaded page can still open the path when postMessage was missed.
• Inputs: Push event with optional JSON payload (type, title, body, url, tag, tags, unreadCount).
• Returns / side effects: When type is dismiss, closes the named tags, shows and closes a silent dismiss-ack, sets the badge to max(0, floor(unreadCount)) when unreadCount is finite, and returns before the Sunday check. On a non-conversation Sunday push, event.waitUntil shows and closes sunday-quiet. Otherwise event.waitUntil of showNotification plus optional setAppBadge via Promise.all. Install skips waiting; activate claims clients. Notification click closes the note, stores the in-app path in the 21gifts-push-open cache, then the focused same-origin window (or the first one, if none is focused) is focused and, after that, receives { type: '21gifts-push-open', url } (pathname + search + hash) before navigate (only when that function exists and the URL differs; rejection or null still focuses). No window: clients.openWindow on the same-origin href. Empty, invalid, or foreign data.url becomes /welcome.
• Used by: Browser Web Push runtime (registered by registerPushWorker).

• Purpose: Detect installed / standalone display mode (display-mode: standalone or iOS navigator.standalone).
• Inputs: None (reads window / navigator).
• Returns / side effects: boolean. No network.
• Used by: PushToggle, shouldOfferIosInstall, PwaInstall.

• Purpose: Detect iPhone/iPod stock Safari (Safari in UA, not CriOS/FxiOS).
• Inputs: None (reads navigator.userAgent).
• Returns / side effects: boolean. No network.
• Used by: PushToggle only.

• Purpose: Read an iPhone, iPad, or iPod user agent and decide whether a new account can finish. iOS 18 is the first version with the extra key this sign-in needs. Older iOS returns the installed version and the minimum. Other browsers, iOS 18 or newer, and an iOS user agent with no version token return null.
• Inputs: userAgent string (navigator.userAgent).
• Returns / side effects: { installed, required } where required is 18 and installed is major.minor or major.minor.patch, or null. No network and no DOM writes.
• Used by: LoginCard (muted line after mount) and usePasskeyLogin (a new account that cannot finish fails with login.iosVersion and is not stored).

• Purpose: Read the installed iOS version from an iPhone, iPad, or iPod user agent, including iOS 18 and newer. iosPasskeyBlock still returns null on those newer versions.
• Inputs: userAgent string.
• Returns / side effects: Installed string (major.minor or major.minor.patch), or null when the token is missing or the browser is not iOS. No network.
• Used by: usePasskeyLogin, which puts that version at the front of a failed login or register diagnostic.

• Purpose: Android below 9 cannot finish a new-account passkey. Android 9 is the first version whose passkeys can carry the extra key. Older Android returns the installed version and the minimum. Android 9 and newer, other browsers, and an Android user agent with no version token return null.
• Inputs: userAgent string.
• Returns / side effects: { installed, required } where required is 9 and installed is major, major.minor, or major.minor.patch, or null. No network.
• Used by: LoginCard (muted line after mount) and usePasskeyLogin (a new account that cannot finish fails with login.androidVersion and is not stored).

• Purpose: Read the installed Android version, including Android 9 and newer. androidPasskeyBlock still returns null on those newer versions.
• Inputs: userAgent string.
• Returns / side effects: Installed string, or null when the token is missing. No network.
• Used by: usePasskeyLogin, which puts that version at the front of a failed login or register diagnostic.

• Purpose: True when an iPhone/iPod browser whose UA contains Safari (stock Safari, Chrome CriOS, Firefox FxiOS, Edge EdgiOS) is not standalone and not an in-app browser — the condition for the iOS Home Screen install sheet.
• Inputs: None. Reads navigator.userAgent plus isStandaloneDisplay and isInAppBrowser. Does not call isIosSafari.
• Returns / side effects: boolean. No network.
• Used by: PwaInstall.

• Purpose: Client install control for the PWA. First paint is null (no layout slot). After mount, hidden when standalone or in-app. On iPhone Home Screen browsers (Safari, Chrome, Firefox, Edge) (shouldOfferIosInstall) shows a labeled control that opens a three-step role="dialog" sheet (Share → Add to Home Screen → if Open as Web App is shown, leave it on). On Chromium, listens for beforeinstallprompt (preventDefault, store event), shows the control, and on click calls event.prompt() then drops the event (hides) regardless of accepted/dismissed; appinstalled also hides. Placements: header (compact secondary), hero (secondary md), menu (SignedInChrome Download + label row).
• Inputs: placement (header | hero | menu); optional tone (app | dark, default app); optional onMenuAction (menu row closes the Menu after click). Catalog via useTranslations.
• Returns / side effects: Install button and optional iOS sheet, or null. No new dependencies; Tailwind only.
• Used by: MarketingHeader (tone="dark" placement="header"), Home hero (tone="dark" placement="hero"), SignedInChrome Menu (placement="menu").

• Purpose: Register the worker, fetch the VAPID key, request notification permission, subscribe, and POST the subscription to the api. Shares a serial queue with resyncPushSubscription and disablePush; a later disable no-ops a queued enable.
• Inputs: sessionToken.
• Returns / side effects: void. Throws Notification permission denied or Push is not configured (and other api errors).
• Used by: PushToggle, SignedInChrome.

• Purpose: When Notification.permission is already granted and a local pushManager subscription exists, POST that endpoint to the api. Does not call requestPermission or subscribe(). Opt-out (no local subscription) is a no-op. POST failure leaves the local subscription in place. Shares a serial queue with enablePush and disablePush; a later disable no-ops a queued resync so it cannot POST after DELETE.
• Inputs: sessionToken.
• Returns / side effects: void. No-op when permission is not granted, Push APIs are missing, or getSubscription() is null. Throws api errors from postPushSubscription without unsubscribing.
• Used by: SignedInChrome (mount and Notifications click when permission is already granted).

• Purpose: When a local push subscription exists, DELETE its endpoint on the api then unsubscribe() locally. Bumps a generation so in-flight enable/resync cannot POST after this opt-out, and waits for the shared serial queue so DELETE is the last server mutation.
• Inputs: sessionToken.
• Returns / side effects: void. No-op when there is no subscription. Local unsubscribe() still runs if the api DELETE fails.
• Used by: PushToggle and LogoutButton.

• Purpose: GET /push/vapid-public with the bearer session and return the VAPID public key string.
• Inputs: sessionToken.
• Returns / side effects: string. Throws Push is not configured on 503; other non-2xx throw with status.
• Used by: enablePush.

• Purpose: POST /me/push-subscriptions with bearer + { endpoint, keys } and validate the response.
• Inputs: sessionToken, subscription endpoint + p256dh/auth keys.
• Returns / side effects: void. Throws Push is not configured on 503; 400 uses api error when present.
• Used by: enablePush, resyncPushSubscription.

• Purpose: DELETE /me/push-subscriptions with bearer + { endpoint }.
• Inputs: sessionToken, endpoint.
• Returns / side effects: void. 404 is success (already gone). Throws Push is not configured on 503.
• Used by: disablePush.

• Purpose: Bearer proxy GET /push/vapid-public to the 21.gifts api.
• Inputs: Incoming Request with Bearer session.
• Returns / side effects: Upstream Response via proxyApiRequest.
• Used by: Route GET /push/vapid-public.

• Purpose: Bearer proxy POST /me/push-subscriptions to the 21.gifts api.
• Inputs: Incoming Request with Bearer session and JSON body.
• Returns / side effects: Upstream Response via proxyApiRequest.
• Used by: Route POST /me/push-subscriptions.

• Purpose: Bearer proxy DELETE /me/push-subscriptions to the 21.gifts api.
• Inputs: Incoming Request with Bearer session and JSON body.
• Returns / side effects: Upstream Response via proxyApiRequest.
• Used by: Route DELETE /me/push-subscriptions.

• Purpose: Next.js MetadataRoute.Manifest for installable 21.gifts (/manifest.webmanifest).
• Inputs: None.
• Returns / side effects: Manifest with name/short_name 21.gifts, start_url /welcome, display standalone, theme/background colors, apple-touch-icon at 180×180, plus icon-192.png and icon-512.png.
• Used by: App Router manifest route.

• Purpose: Compact dual-line cumulative SVG of Given and Received. FiatPicker only when unsigned (useHydrateSession().ready && session === null; public view). Signed-in mounts (ProfileScreen, MemberProfileScreen, signed-in /view) omit it. Code from useFiatPreference. Empty/all-zero sats: unsigned shows picker plus profile.chartEmpty role="status"; signed-in empty is profile.chartEmpty alone (no SVG, no ₿|{fiat} scale). Empty/all-zero sats and failed show profile.chartError (role="alert", text-app-danger) instead of profile.chartEmpty; unsigned FiatPicker stays above. In-flight and successful empty stay profile.chartEmpty, never Loading…. Null usd/cumulativeUsd with positive cumulative sats still draws the satoshi chart (legend + scale + SVG). Populated: unsigned shows picker, then legend + SegmentedControl tone="gift" options ₿ | selected FiatCode (profile.chartScale), then SVG; signed-in populated starts at legend + ₿|{code} scale. Scale state is ActivityScale 'sat' | 'fiat'. Ticks: sat formatBitcoin; fiat formatFiatTick (USD may use formatUsdTick); USD scale uses an em dash when any raw cumulativeUsd is null; em dash when every source cumulative for the selected non-USD code is null. Wrapper role="group" uses profile.chartTitle as aria-label. No title heading; page heading is Profile. Given is donatedOverTime from account activity (no longer a hardcoded zero series).
• Inputs: received (AccountActivity.receivedOverTime); optional donated (default []) from AccountActivity.donatedOverTime; optional failed (default false).
• Returns / side effects: When unsigned, FiatPicker, then when the series is empty or all zeros: profile.chartEmpty (role="status") — no legend, ₿|{fiat} scale, or SVG — or profile.chartError (role="alert", text-app-danger) when failed. Signed-in empty is profile.chartEmpty alone (or profile.chartError when failed). In-flight and successful empty stay profile.chartEmpty, never Loading…. Null usd/cumulativeUsd with positive cumulative sats still draws the satoshi chart. Otherwise one chrome row (legend left, ₿ | selected FiatCode right) and SVG. Client state for scale; unsigned picker writes the fiat cookie. No network.
• Used by: ProfileScreen, ViewProfileScreen, MemberProfileScreen.

• Purpose: Labeled app button with primary (filled), secondary (bordered), or accent fill. Optional tone app (default) or dark for marketing-ink shells (same class split as ButtonLink). Size sm / md / lg (lg is full width). All sizes min-h-11.
• Inputs: Native button props plus optional variant (default primary), optional size (default md), optional tone (default app), optional leading icon, and children label. Default type="button".
• Returns / side effects: A <button> element. No network. Used across login, forum retry, public note retry, PWA install on dark shells, and forms.
• Used by: PublicMessageLoader, LightningAddressForm, ForumBoard, PwaInstall, setup and contact screens.

• Purpose: Labeled pill link matching Button anatomy (primary / secondary / accent, sm / md / lg, tone app or dark).
• Inputs: href, optional variant / size / tone / icon / className, children label.
• Returns / side effects: A Next.js <Link> for path hrefs, or a native <a> for protocol hrefs (https:). No network. Used on marketing CTAs, donate Open the forum, and rules nav. The 404 page does not use it.
• Used by: Home, MarketingHeader, DonatePage, RulesDocument.

• Purpose: Mutually exclusive option group with tone gift (compact ₿|USD cells, optional shell app/dark) or neutral (full-width pills for staff inbox and profile notifications). Gift hit target is min-h-11 min-w-11 on mobile and desktop. shell is ignored for neutral. Neutral role="group" is the pill; the forum composer Post/Ask !grid grid-cols-2 !rounded-2xl still lays out those option buttons via className on the group. The four forum view filters are ForumModeSelect, not this control. No trailing slot.
• Inputs: value, options (value + label, optional badge / badgeAriaLabel; chip omitted when badge is missing or ≤ 0), onChange, ariaLabel, tone, optional shell (default app, gift only), optional className (on the group).
• Returns / side effects: A role="group" track of type="button" options with aria-pressed. Neutral is that group as the pill (className lands there, including the composer Post/Ask !grid grid-cols-2 !rounded-2xl). No network.
• Used by: ForumBoard (tone="neutral"), PushToggle (tone="neutral", twice: level + device), AccountActivityChart (tone="gift"), StatsDashboard (tone="gift" shell="dark").

• Purpose: Closed combobox for the living-room forum view (Active, No gifts yet, All, Most popular). The trigger shows the selected label and a chevron. A positive unpaid badge is also shown as a count chip on the closed trigger. Opening the trigger shows a listbox of option rows; the selected row has a check. Choosing a row calls onChange and closes the list. Shops does not mount it. Post/Ask stays a SegmentedControl.
• Inputs: value; options (value, label, optional badge, optional badgeAriaLabel); onChange(value); ariaLabel (catalog forum.modeLabel).
• Returns: A relative wrapper with the combobox button and, only while open, the listbox.

• Purpose: Icon-only control with a required aria-label, variant (primary / secondary / ghost), size (sm / md / lg), and optional tone app (default) or dark for marketing-ink shells (ghost+dark is paper hover and focus-visible:outline-paper). sm is 24px paint with a 44px ::before hit slop; md is 44px; lg is 48px.
• Inputs: Native button props; aria-label is required for accessible naming. Default variant="secondary", size="md", tone="app", type="button".
• Returns / side effects: A <button> wrapping the icon child. No network. Used for attach/post/pay/copy/dismiss controls on the forum board and the handbook copy-link on marketing ink.
• Used by: ForumBoard, LightningAddressForm, InboxScreen, HandbookImageViewer, HandbookLightbox, ContactScreen, NameForm, RulesSetup, HandbookCopyLink.

• Purpose: Primary app content panel using semantic card tokens (bg-app-card, border, shadow) with optional max-width (sm / md / xl). surface default true draws that nested visual panel. surface={false} is a width + flex + gap column for page body inside the AppShell frame (no radius, border, bg, shadow, or p-8). Card never hosts page chrome.
• Inputs: children, optional className, optional maxWidth (default sm), optional surface (default true; false omits panel classes).
• Returns / side effects: A <section> wrapper. No network. Nested panel for public notes and overlays; page-body columns (LoginCard, profile, welcome, inbox) use surface={false}.
• Used by: PublicMessageLoader, LoginCard, profile and setup screens.

• Purpose: Every typed amount. Gift SegmentedControl (₿ and the member's fiat code) plus the other unit under the field. keypad (the /pos/amount page only) replaces the input with a non-focusable amount and an always-visible 3-column keypad. The page heading is already Amount, so the keypad does not repeat it; the amount keeps that name for assistive tech. Bitcoin offers no decimal key and ignores a typed decimal. Fiat shows the number-format decimal and keeps two fraction digits. A key scales down and darkens while it is held. When the amount changes and the device can vibrate, and reduced motion is off, it vibrates for 10 ms. Other screens keep the input. Switching the keypad to fiat rewrites the draft with the number-format decimal. Bitcoin shows the preferred fiat. Fiat shows formatBitcoin. The input box, its placeholder, and where the digits start do not change when the unit changes. A numeric placeholder is not rewritten. The switch and the counter do change. A signed-in toggle POSTs /me/amount-unit and writes account.amountUnit. No session keeps the choice on the control and starts at ₿. A locked invoice shows the sat amount and disables the switch. layout="composer" (inbox) puts the switch beside the input. layout="inline" (forum reply) puts the amount before the switch on one line. Both keep the label for assistive tech only and put the counter under the input.
• Inputs: label, value, onValueChange, rateDay, optional id, disabled, placeholder, className, lockedSats, onUnitChange, layout (field default, composer, or inline), optional keypad (default false; the /pos/amount page only).
• Returns / side effects: A labeled input, or with keypad a non-focusable amount plus the keypad and no input. The keypad does not show the label again. The switch and a counter line when an amount is defined. Signed-in toggle calls setAmountUnit. No other network.
• Used by: ForumAskWizard, ForumBoard pay sheet and reply, InboxScreen, PayLinkScreen, PosAmount.

• Purpose: Labeled text input or textarea using shared app field tokens; id is generated from the label when omitted.
• Inputs: label, optional id / className, multiline (textarea when true), plus native input or textarea attributes.
• Returns / side effects: A <label> wrapping an <input> or <textarea>. No network.
• Used by: Labeled text primitive. Amount fields use AmountEntry instead.

• Purpose: Blocking bootstrap IIFE string injected as a raw head script before paint. Sets --app-height to the visible viewport (visualViewport.height, else innerHeight) and writes visualViewport.offsetTop to --app-offset-top. The offset is never added into the height and the script does not take max with innerHeight. A taller frame would be a second scroll. Scale guard: skips both writes when visualViewport.scale is present and not ≈ 1.
• Inputs: None (constant string).
• Returns / side effects: Non-empty IIFE source mentioning visualViewport, --app-height, and --app-offset-top. It does not mention Math.max and it does not add the offset into the height.
• Used by: RootLayout <head> script.

• Purpose: Minimal visual-viewport fields (height, optional offsetTop, optional scale) used to resolve --app-height and --app-offset-top without depending on the DOM VisualViewport type in tests. offsetTop positions the body and is not part of the height.
• Inputs: height in CSS pixels; optional offsetTop; optional scale (omit when unknown — do not pass undefined).
• Returns / side effects: A structural type only — no runtime value. Callers pass { height } or { height, offsetTop, scale } into resolveAppHeight and resolveAppOffsetTop.
• Used by: resolveAppHeight, resolveAppOffsetTop; useAppHeight (live window.visualViewport).

• Purpose: Chooses the pixel value for --app-height. The result is visualViewport.height (else innerHeight). offsetTop is not added. A frame taller than the visible viewport would scroll the document under the one scrollport. Pinch-zoom skip: returns null (caller must not write) when scale is present and not ≈ 1 (|scale - 1| > 0.01). Null/undefined visualViewport falls back to innerHeight.
• Inputs: innerHeight (window.innerHeight); visualViewport (window.visualViewport or a stub; null/undefined allowed; offsetTop optional and not added into the result).
• Returns / side effects: Rounded CSS-pixel height, or null to skip the write. No DOM writes of its own.
• Used by: useAppHeight (AppHeightSync); bootstrap IIFE inlines the same visible-height path.

• Purpose: Chooses the pixel value for --app-offset-top, which positions the fixed body on the visual viewport. The value is rounded visualViewport.offsetTop, or 0 when the viewport or the offset is missing. It is never added into --app-height. Pinch-zoom returns null so the caller skips both writes.
• Inputs: visualViewport (AppHeightViewport or null/undefined). scale present and not ≈ 1 (|scale - 1| > 0.01) skips the write.
• Returns / side effects: Rounded CSS-pixel offset, 0 when there is no viewport, or null while pinch-zoomed. No DOM writes of its own.
• Used by: useAppHeight (AppHeightSync); the bootstrap IIFE writes the same offset before paint.

• Purpose: After hydration, keeps --app-height equal to visualViewport.height (else innerHeight) and --app-offset-top equal to the visual-viewport offset so the fixed body sits in the visible area. The offset is never added into the height. Pinch-zoom skips both writes. Viewport resize and scroll reveal the focused field; focus does the same on the next animation frame.
• Inputs: None (reads window.visualViewport / innerHeight inside a useEffect).
• Returns / side effects: void. Sets --app-height and --app-offset-top on document.documentElement. Registers window resize/orientationchange, document focusin/focusout, and visualViewport resize/scroll listeners; cleans them up on unmount. Reveals the focused input, textarea, or select inside the active scrollport.
• Used by:

- **AppHeightSync (same file; root layout mount) - Every hydrated app page (via that mount) - Fill/flow AppShell layouts** that consume --app-height

• Purpose: Client-only root mount that calls useAppHeight so --app-height stays the visible viewport height and --app-offset-top keeps the fixed body on that viewport after the blocking bootstrap script runs in <head>. The offset is never added into the height.
• Inputs: None.
• Returns / side effects: Renders null; side effect is the hook. Mounted as the first child of <body> in RootLayout.
• Used by:

- **RootLayout** (src/app/layout.tsx) - All app and marketing routes under that layout - **useAppHeight consumers** that rely on a single shared mount

• Purpose: App page shell driven by --app-height. Always draws one rounded-3xl page frame. fill and flow share that geometry: locked height, frame grow shrink basis-0 self-stretch (not flex-1), frame-header chrome row, one [data-scrollport] (Scrollport), footer host. The document does not scroll. Prefer this over Tailwind viewport-height utilities on app routes. Chrome (wordmark + Menu / language) is the frame’s first row ([data-app-chrome]). <main> has no overflow-hidden. The frame ([data-app-frame]) publishes its content-box width as frameWidth. [data-menu-scrim-host] sits on the frame. [data-menu-sheet-host] (px-8, the same horizontal inset as the page) and [data-scroll-page] sit inside the one scrollport. Card never hosts page chrome. Never justify-center on <main> or the scrollport. The center wrapper sets justify-content: center and then safe center, so content that fits stays centered, and where safe is supported a thread taller than the frame starts at the top and remains scrollable inside that one scrollport.
• Inputs: children, required mode (fill | flow; both values render the same frame), optional topLeft / topRight, optional className, optional align (start | center).
• Returns / side effects: A <main> layout with a rounded page frame, chrome row, header/footer portals, and inner scroller. useAppShellScroller reads that scroller from context. No network.
• Used by:

- Fill and flow app routes (LoginPage, DonatePage, setup, contact, inbox, notifications, public note, ProfilePage, WalletPage, ShopsPage, ViewProfilePage, MemberProfilePage) - **PageChrome** (still mode="flow"; AppShell draws the unified frame — welcome and public rules) - **AppShellHeader / AppShellFooter / AppShellTopLeft slot registrars - useAppShellScroller** (ForumBoard pull-to-refresh, ForumLoader atTop / scroll-to-top, InboxScreen open-thread pin to bottom / one-shot list reset to top)

• Purpose: The only layout scrollport. Renders [data-scrollport]. Overflow is the globals.css rule, not a Tailwind utility: clip until data-scroll-active, then the active port scrolls vertically only (overflow-x: clip and overflow-y: auto). The innermost bound port scrolls. Among siblings, the most recently bound one scrolls and gets data-scroll-active. Every other port gets data-scroll-locked. html and body stay overflow: clip.
• Inputs: children, optional className, optional scrollRef, optional onClick.
• Returns / side effects: A div. Binds on mount and releases on unmount. No network.
• Used by: AppShell, marketing layout, NotFound, HandbookLightbox.

• Purpose: Push a scrollport onto the active stack and resync. Binding the same element twice does not stack it twice. The innermost bound port may scroll; among those, the most recently bound. That port gets data-scroll-active.
• Inputs: The mounted scrollport element.
• Returns / side effects: Sets data-scroll-active on the port that may scroll and data-scroll-locked on the others, and clips stray scrolling elements. No network.
• Used by: Scrollport on mount.

• Purpose: Remove a scrollport from the active stack and resync. The innermost remaining port scrolls; among siblings, the most recently bound. Releasing an element that is not on the stack does nothing.
• Inputs: The unmounted scrollport element.
• Returns / side effects: Sets data-scroll-active on the port that may scroll and data-scroll-locked on the others, and clips stray scrolling elements. No network.
• Used by: Scrollport on unmount.

• Purpose: Leave exactly one scrollport unlocked. Every other element whose computed overflow can scroll (auto, scroll, or legacy overlay, on either axis) is forced to clip. Textareas grow to their text instead. Inputs and selects are left to the browser.
• Inputs: None. Reads the active stack and document.body.
• Returns / side effects: Sets data-scroll-active on the one port that may scroll and data-scroll-locked on the others, and may set inline overflow or textarea height. No network.
• Used by: bindScrollport, releaseScrollport, and ScrollSurfaceGuard.

• Purpose: Root watcher. On mount, and whenever class, style, or children change, it runs syncScrollSurfaces so a scrolling overflow added later cannot become a second surface. Typing in a textarea resyncs immediately so the field grows instead of scrolling.
• Inputs: None.
• Returns / side effects: Renders null. Observes document.body and listens for input. Disconnects on unmount. No network.
• Used by: RootLayout, mounted once for every page.

• Purpose: Returns the AppShell inner [data-scrollport] element, or null outside AppShell.
• Inputs: None (reads AppShell context).
• Returns / side effects: HTMLElement | null. No network.
• Used by: ForumBoard (pull-to-refresh pageScrollTop), ForumLoader (atTop / scroll-to-top), InboxScreen (open-thread pin to bottom / one-shot list reset to top), AppShell unit tests.

• Purpose: Registers flex-none header content into the nearest AppShell page frame (DOM portal into the shell <header> host). Without an AppShell ancestor, renders children inline.
• Inputs: children (typically an onboarding h1).
• Returns / side effects: Portal into the shell header host when present; otherwise the children. Layout only.
• Used by:

- **NameSetup - AddressSetup - RulesSetup**

• Purpose: Registers flex-none footer content (CTAs) into the nearest AppShell page frame (DOM portal into the shell <footer> host; pb-8 on that host). Without an AppShell ancestor, renders children inline.
• Inputs: children (typically Continue / Skip / Agree buttons).
• Returns / side effects: Portal into the shell footer host when present; otherwise the children. Layout only.
• Used by:

- **NameForm (onboarding) - LightningAddressForm (onboarding) - RulesSetup**

• Purpose: Registers top-left chrome into the nearest AppShell via DOM portal; child registration wins over the page topLeft prop. The host is the frame chrome row ([data-app-chrome]), not a Card. Without an AppShell ancestor, renders children inline.
• Inputs: children (back control + wordmark, etc.).
• Returns / side effects: Portal into the shell top-left host when present; otherwise the children. Layout only.
• Used by:

- **RulesSetup (chapter back + wordmark) - WalletScreenView** (Wallet Back and wordmark; wins over the page topLeft) - **AppShell unit tests** (child portal wins over the page topLeft prop)

• Purpose: Wrapper around AppShell (still mode="flow") with optional top-left (wordmark) and top-right (menu / language) slots. Chrome is the page-frame header, not page-absolute. Prefer AppShell directly on app routes.
• Inputs: children, optional topLeft, optional topRight, optional className on the outer <main>.
• Returns / side effects: Layout only (AppShell mode="flow"; AppShell draws the unified frame). No network.
• Used by: Flow app routes (WelcomePage, RulesPage) plus unit tests and the ui barrel. Fill routes use AppShell directly.

• Purpose: Text brand mark 21.gifts (header 17px/700, footer 15px/700). Link when href is set; otherwise a <span> (marketing footer).
• Inputs: optional href, optional tone (app / dark), optional size (header / footer, default header), optional className, optional onClick forwarded to the link only.
• Returns / side effects: A Next.js <Link> or <span>. No network.
• Used by: HomeWordmark, ForumHomeWordmark, MarketingFooter, ProfileChromeLeft, RulesSetup, setup name/username/address pages, and RulesPageChrome.

• Purpose: Welcome-page wordmark: linked 21.gifts to /welcome that preventDefaults and dispatches FORUM_HOME_EVENT so ForumLoader can scroll to top and apply new notes without a full reload.
• Inputs: None. Uses Wordmark and FORUM_HOME_EVENT.
• Returns / side effects: A client wordmark link. Dispatch only; no fetch of its own.
• Used by: WelcomePage.

• Purpose: Session-aware header wordmark: linked 21.gifts to /welcome when useHydrateSession is ready and useAuthStore has a session, otherwise /. Real navigation (no preventDefault, unlike ForumHomeWordmark).
• Inputs: Optional tone, size, className, onClick forwarded to Wordmark when set. Uses useHydrateSession and useAuthStore.
• Returns / side effects: A client Wordmark link. Hydrates the session; no other network of its own.
• Used by: MarketingHeader, LoginPage, DonatePage, ViewProfilePage, PayLinkScreen.

• Purpose: Client chrome wrapper for public /messages/[id], /messages/[id]/author, and /messages/[id]/repayment-list: when a session is hydrated (ready && session !== null), mounts signed-in shell (ProfileChromeLeft + SignedInChrome); otherwise ProfileChromeLeft with wordmark href / and light LanguageSwitcher. The arrow returns to the previous in-app view, or /welcome when this tab has none.
• Inputs: children (page body: PublicMessageLoader from PublicMessagePage, ExternalAuthorProfile from ExternalAuthorPage, or CreditLedger from RepaymentListPage). Uses useHydrateSession and useAuthStore for session.
• Returns / side effects: Fill AppShell (align="center") with the matching top-left / top-right slots around children. No network beyond session hydration.
• Used by: PublicMessagePage, ExternalAuthorPage, RepaymentListPage.

• Purpose: Next.js page for /messages/[id] — public HTML note by UUID. Unsigned visitors see a read-only thread. Signed-in React on the root note, copy, reply, and Gift on a payable nested reply run through PublicMessageLoader → PublicMessageThread. No OnboardingGate, top-level composer, or envelope. Wrapped in PublicMessageChrome (signed-in or unsigned chrome depending on hydrated session).
• Inputs: Dynamic route params (id).
• Returns / side effects: PublicMessageLoader inside PublicMessageChrome (chrome is no longer always unsigned Wordmark + LanguageSwitcher). Also exports generateMetadata for per-note Open Graph / Twitter tags. Unsigned chrome is ProfileChromeLeft with wordmark href /, not a bare wordmark.
• Used by: Route /messages/[id].

• Purpose: Next.js App Router metadata for /messages/[id]. Loads the public note via loadPublicMessageForOg and maps it through publicMessageOgMetadata so crawlers see the author, text, and photo without running JS. Missing or failed fetches inherit the root layout preview.
• Inputs: { params: Promise<{ id: string }> } from the dynamic route.
• Returns / side effects: Promise<Metadata> — per-note Open Graph / Twitter tags when the note is found, or {} so the site-wide layout preview is inherited. Does not render the visible page.
• Used by: Route /messages/[id] (PublicMessagePage).

• Purpose: Server fetch of api GET /messages/:id for Open Graph. Invalid UUIDs skip the network. Timeouts, non-OK responses, JSON/schema failures, and thrown errors (getApiUrl, network, abort) all return null and never throw.
• Inputs: id string from the route (forum message UUID).
• Returns / side effects: ForumMessage or null. Uses cache: 'no-store', Accept: application/json, and AbortSignal.timeout(2500).
• Used by: generateMetadata on /messages/[id].

• Purpose: Maps a loaded public note (or null) to Next.js Metadata. Found notes use the author name as title and never the marketing layout description, even when text is empty. Photo notes set og:image to /messages/{id}/photo; others keep /og.png. A note with any via value (written without a 21.gifts account) gets fully generic metadata instead: title External author on 21.gifts, description A reply from someone outside 21.gifts who sent bitcoin to a post., and always the default /og.png image — nothing from the note's name, text or photo reaches a link preview. Both strings are plain English constants, not from the catalog.
• Inputs: Route id and note (ForumMessage | null).
• Returns / side effects: {} when note is null. For a note with a via value the generic External title, description and default image described above. Otherwise title, description (trimmed text or ` ${name} on 21.gifts , truncated above 300 code units with …), Open Graph (type: website, url https://21.gifts/l/ plus the first 8 hex of a UUID id (otherwise https://21.gifts/messages/{id}), siteName 21.gifts), and Twitter summary_large_image`.
• Used by: generateMetadata on /messages/[id].

• Purpose: Client loader for the public thread page: validates UUID, waits for hydrate ready, then fetches. Staff (roleAtLeast(account.role, 'moderator') + session) use fetchForumMessage(session, routeId) and fetchReplies(session, root.id) so a soft-hidden row can load; others use fetchPublicMessage(routeId) / fetchPublicReplies. If parentId is set, fetches that parent (null → missing) then replies of the parent. Ready only with root + replies (empty replies → parent only). Replies throw → error + Try again (whole chain). Until hydrate ready, only forum.loading (no fetch, no cards). After ready, when the loaded root or the highlighted reply has deletedAt / deletedBy, a role="status" forum.hiddenNotice line sits above the thread (permalink target). Unsigned visitors (no session or no account) keep the PublicThreadCard stack (no pay/copy): vertical stack parent Card then reply Cards with pl-4. Gift-only replies (empty text, sats > 0): sats line via formatBitcoin plus optional preferred-fiat · formatFiatDisplay of the amount stored when the payment was made (a stored string as-is, a null or missing field on a passed stored object uses the gift-day rate), no empty <p>. When the route id is a reply, that unsigned reply card (or wrapper) has data-permalink-target="true" and ring-1 ring-app-fg. Photo/video per unsigned card via fetchPublicMessagePhoto. Unsigned gallery is ForumPhotoGallery (horizontal snap row, data-scroll-x, 88% peek, current/total chip, dots); data-photo-index keeps the original still index when an earlier extra still fails to load. Translate (Languages icon) under unsigned note and reply bodies via NoteTranslate when the language differs from the UI locale. A via === 'nostr' reply or note shows a non-interactive External <span> badge next to the name (no hint state on this card) and renders its body as plain text (TranslatableNoteBody plain) instead of ForumQuotedBody. Each unsigned card is ₿ plus optional preferred-fiat · formatFiatDisplay of the amount stored when the payment was made (useFiatPreference; cookie, otherwise locale default); otherwise the gift-day rate. On an unsigned reply with receivedSats greater than zero, that card uses ReplyDirectionAmounts instead of the single amount: sent and received stay separate lines and are not added. A top-level card keeps one amount, the collected total. fetchGiftStats / latestRateDay feed the pay sheet and an unpaid invoice preview. A posted goal bar uses the stored visitor snapshot when that string exists, otherwise this gift-day rate. A top-level unsigned note with a positive goalSats also shows ForumGoalBar, and the same Loan, Donation, or #Shop tag as the forum beside the name. When ready && session && account and the root is loaded, mounts PublicMessageThread instead of the unsigned cards, passing seedReply as the highlighted hidden reply (omit the prop when none). Auth CTA once below either stack from useHydrateSession is Log in when unsigned. Signed-in visitors have no text back link under the thread. The top-left arrow returns to the previous in-app view in this tab, or /welcome when this tab has none.
• Inputs: id string from the route. Also reads session and account from the auth store and hydrate ready.
• Returns / side effects: States loading / missing / error (with Try again) / ready unsigned stack or signed-in PublicMessageThread. Malformed UUID → missing without an api call. Photo blob URLs revoked on unmount or id change. Inline <video> keeps the clip aspect ratio (max-h-80 max-w-full, no full-width black canvas). A failed <video> error event hides the player and falls back to the photo when present. NoteTranslate on unsigned note and reply bodies (GET /translate on mount, POST on Translate). Unsigned stack has no pay, composer, copy, or FiatPicker. Hydrate-not-ready is only forum.loading (no unsigned cards). A hydrate drop after a note is loaded keeps the cards and shows forum.loading in the footer.
• Used by: PublicMessagePage.

• Purpose: Signed-in permalink thread: one root on ForumBoard with composerHidden and truncate={false} so the original body stays full, auto-expand via fetchReplies, and the same React, copy, reply, overlay, photo, and poll behavior as /welcome. React (forum.react, lucide Reply) on the root note; on every nested reply Gift when payable, copy (forum.copyReplyLink, the reply's own origin /l/<8 hex>, first group of that reply id) always, and trash for staff. Staff onDeleted on the root calls onRootDeleted (loader → missing); a nested reply is dropped from the list. Passes permalinkTargetId so only a matching nested reply is ringed. Owns payHost and passes it to ForumBoard: a compose-fee reply invoices 1 sat to 21.gifts on the composer slot (payHost: composer, payMessageId = compose-target note); extra gifts and Gift-open stay on the card (payHost: card).
• Inputs: { root, highlightId, seedReply?, onRootDeleted } as in src/components/PublicMessageThread.tsx: root is ForumMessage, highlightId is string | null (route id when it is a reply UUID), seedReply is the opened hidden reply when the route id is a hidden child, onRootDeleted is () => void. Session and account from the auth store.
• Returns / side effects: React tree. Auto-expands the root so Write a reaction is available. After Bearer fetchReplies of the root, merge seedReply into the list when it is missing so the signed-in board still shows the hidden permalink target. Passes permalinkTargetId={highlightId}. No top-level composer or feed filters. Owns payHost and passes it to ForumBoard: a compose-fee reply invoices 1 sat to 21.gifts on the composer slot (payHost: composer, payMessageId = compose-target note); extra gifts and Gift-open stay on the card (payHost: card).

• Used by: PublicMessageLoader.

• Purpose: Next.js page for /view/[viewKey] — public read-only profile by view key. No OnboardingGate, no SignedInChrome.
• Inputs: Dynamic route params (viewKey).
• Returns / side effects: Exports metadata.referrer = 'no-referrer'. AppShell with ProfileChromeLeft (wordmark HomeWordmark: / unsigned, /welcome when a session is hydrated) and light LanguageSwitcher top-right; body is ViewProfileLoader. The arrow returns to the previous in-app view, or /welcome when this tab has none. The card itself has no back control.
• Used by: Route /view/[viewKey].

• Purpose: Client loader for the public view page: validates the key, fetches the public profile, then fetchViewActivity even if the Lightning Address is blank. Does not use useAuthStore.
• Inputs: viewKey string from the route.
• Returns / side effects: States loading / missing / error (with Try again) / ready card. In ready, renders ViewProfileScreen plus ViewProfileClaim under the card (passes viewKey and hasPasskey from the fetched profile). Malformed keys (not 64 lowercase hex) → missing without an api call. After fetchViewProfile, always calls fetchViewActivity (even when address is blank) and maps both series onto the card. Activity failure still shows the card; the chart shows profile.chartError, not profile.chartEmpty. Successful empty series stays profile.chartEmpty. Chart never swapped for forum.loading.
• Used by: ViewProfilePage.

• Purpose: Presentational read-only identity card matching signed-in profile chrome: heading Profile, AccountActivityChart, About me inside the card (not a forum post; public AboutMeSection with name={profile.name} shows filled text and/or photo, or omits the heading when neither; Languages Translate when aboutMessageId is set), name, location, and public [email protected] rows (labels name.heading / location.heading / profile.giftsHeading) without edit or Message actions. Unset location shows location.unset. Missing username shows view.noGiftsAddress. Copy-profile-link on the card (profile.copyLink). When a username is set, a centered QrCode (label profile.giftsQr) under the address encodes openCryptoPayQrValue (https://<domain>/pl/?lightning= plus the uppercase LNURL of https://<domain>/.well-known/lnurlp/<local>), including on a smartphone. A missing username shows no QR.
• Inputs: { profile, viewKey, received, donated } — received is AccountActivity['receivedOverTime']; optional donated is AccountActivity['donatedOverTime']; optional activityFailed (default false), passed to the chart as failed. viewKey builds the copy URL /view/<viewKey>. profile includes aboutMe, aboutMeHasPhoto, and location. Public AboutMeSection hasPhoto from aboutMeHasPhoto with loadPhoto (fetchViewAboutMePhoto).
• Returns / side effects: No menu, logout, back, edit forms, or Message. Copy-profile-link on the card; URL/key never shown as visible text. Language switcher lives on the page, not in this card. When activityFailed is true and the series is empty, profile.chartError.
• Used by: ViewProfileLoader.

• Purpose: Public passkey claim control under the /view/[viewKey] card. Unclaimed invites (hasPasskey false) bind a passkey to the existing profile (name + Wallet of Satoshi already set), including when another 21.gifts session is already signed in.
• Inputs: viewKey (64 lowercase hex) and hasPasskey from the public profile. Uses usePasskeyLogin, useAuthStore, useRouter, isInAppBrowser, and InAppBrowserView.
• Returns / side effects: Waits for useHydrateSession ready. Claimed (hasPasskey true) → null (even in Telegram, even if signed in). In-app on mount or unsupported → same card chrome as login wrapping InAppBrowserView (no yellow Activate). Else in a real browser: yellow banner with view.activationRequired and Activate (view.activate) even when account !== null; click sets a claim-attempted flag, cancel + clearAuth when a session exists, then register(viewKey) (stays on the view page). Success → router.replace(nextOnboardingPath(account)) only when that claim was attempted (pre-existing sessions do not redirect on mount). 409 → view.alreadyClaimed plus Fingerprint that calls authenticate(); after that attempt the yellow Activate banner does not return (successful login hides the control; a dismissed prompt keeps the already-claimed copy). Status unknown shows view.claimError and Try again calls authenticate(), never register, and never the login unknown card. Other errors / starting stay visible even with a session → view.claimError + Try again (view.retry) or spinner.
• Used by: ViewProfileLoader (ready state only).

• Purpose: Fetches a public read-only profile by view key via the same-origin proxy.
• Inputs: viewKey string.
• Returns / side effects: Validated ViewProfile, or null on 404. Throws on other non-2xx or a body that fails viewProfileSchema. Hits /view-key/${encodeURIComponent(viewKey)}.
• Used by: ViewProfileLoader.

• Purpose: Same-origin proxy of api GET /view/:viewKey (public; no auth).
• Inputs: Incoming Request and viewKey path segment.
• Returns / side effects: Proxied upstream Response for /view/${encodeURIComponent(viewKey)}.
• Used by: App Router GET on /view-key/[viewKey].

• Purpose: Align receive and donate cumulative account-activity series onto one sorted UTC-day axis for the profile chart.
• Inputs: received (AccountActivity.receivedOverTime) and donated (AccountActivity.donatedOverTime).
• Returns / side effects: ActivityPoint[]. Empty+empty → []. Empty donated → zero Given on each received day. Non-empty both → day union with step-hold carry-forward. Also aligns CHF/EUR/PHP cumulatives (null string → 0); missing series side stays at the carried value (0 until first point).
• Used by: AccountActivityChart.

• Purpose: Read one cumulative chart value from an aligned activity point.
• Inputs: point, series (donated | received), scale (sat | fiat); when 'fiat', fiat (FiatCode) selects cumulative*Usd|*Chf|*Eur|*Php. 'sat' ignores fiat.
• Returns / side effects: Number used to place the polyline.
• Used by: AccountActivityChart, activityMaxY.

• Purpose: Y-axis max for the dual-line chart: max of both series at the active scale, or 1 when empty/all zeros.
• Inputs: points, scale (sat | fiat), optional fiat (FiatCode) — same as activityValue.
• Returns / side effects: Positive number for SVG scale.
• Used by: AccountActivityChart.

• Purpose: Session-based GET /me/activity via fetchAccountActivity; returns given/received sats plus donateOverTime and receiveOverTime. Fetches even with a blank Lightning Address and does not call fetchGiftStats.
• Inputs: Reads session and account.lightningAddress from useAuthStore; calls fetchAccountActivity whenever a session exists.
• Returns / side effects: { donatedSats, receivedSats, donateOverTime, receiveOverTime, loading, failed }. Fetch start: failed false, series empty, chart shows profile.chartEmpty. Success: failed false and series from the payload. Thrown fetch: failed true, zeros, empty series, chart profile.chartError. Session null: failed false, no fetch. On each fetch start (including session or Lightning Address change) totals and series reset to zeros/empty and failed is false; AccountActivityChart then shows profile.chartEmpty (no SVG) while in flight. Drops stale or cancelled responses when the session or address changes mid-flight and does not apply them.
• Used by: ProfileScreen.

• Purpose: Next.js page for /welcome.
• Inputs: None.
• Returns / side effects: Flow PageChrome (AppShell wrapper) with ProfileChromeLeft hideWithoutHistory and ForumHomeWordmark top-left, WelcomeTopRight (the member menu when a session exists, otherwise a link to /login), and OnboardingGate screen="welcome" allowGuest around WelcomeScreen. The arrow is omitted only when this tab has no earlier view. An ask-wizard step uses that same slot.
• Used by: Route /welcome.

• Purpose: Living-room screen. With a session it is the fourth post-login screen after name, address, and living-room rules agreement are saved. Without a session it is the public active list. Embeds ForumLoader below the heading. Page column is max-w-xl (Card surface={false}) so the AppShell frame is the only page-level rounded-3xl.
• Inputs: Reads session and account.name from useAuthStore.
• Returns / side effects: Gift icon with an integrated Bitcoin symbol. Heading Welcome, {name} when the account has a name, otherwise Welcome. Forum board. A session gets the composer. ForumLoader sets readOnly when there is no session. WelcomePage shows Log in in the chrome. No name or address form. No donate CTA. No LogoutButton in the page column.
• Used by: Screen /welcome.

• Purpose: Collapse a public forum note or reply body to a 280-character UTF-16 .length collapsed preview (FORUM_TEXT_PREVIEW_LIMIT) for the feed/profile timeline analog. Show more / truncated: true only when text.length is greater than twice that (560, FORUM_TEXT_FULL_LIMIT). A body of 560 characters or fewer is returned unchanged. Word/line boundary cut when the last space or newline in the slice sits at index >= floor(limit * 0.8); trailing spaces/tabs trimmed; no ellipsis in the helper. If the hard cut splits an http(s) URL (no whitespace across the boundary), that incomplete trailing URL is dropped from the preview so LinkedText cannot autolink a shorter href.
• Inputs: text — full body; optional limit is this collapsed preview length (default 280); the full-body ceiling is limit * 2.
• Returns / side effects: { preview, truncated }. Does not append …. No network.
• Used by: ForumNoteText.

• Purpose: Client paragraph for remaining note/reply text on the feed and profile (via ForumQuotedBody / QuotedForumNote when truncate is true). Empty text returns null. Bodies autolink http(s) URLs via LinkedText. Optional plain forwards plain rendering to LinkedText on both the full and truncated (Show more) path. Bodies longer than 560 characters (twice the 280-character preview) render a collapsed preview of 280 characters, …, and inline Show more (forum.showMore, app inline link) for callers that do not pass forceExpanded. Optional forceExpanded renders the full body and omits Show more. Expand in place; no Show less. Click and keydown stopPropagation so the parent card role="button" does not toggle replies. On /messages/[id], the original body is LinkedText (ForumQuotedBody with truncate={false}).
• Inputs: ForumNoteTextProps — text, className, optional plain, optional forceExpanded (default false).
• Returns / side effects: LinkedText (<p> plus optional overlay), or null when text === ''. Local React expand state only.
• Used by: ForumQuotedBody / QuotedForumNote (remaining text and nested quoted note bodies when truncate is true) and TranslatableNoteBody (original body only when truncate is true, not the translation).

• Purpose: Read a JPEG APP1 Exif capture time before the canvas re-encode strips it. Does not read GPS.
• Inputs: JPEG file bytes.
• Returns / side effects: YYYY-MM-DDTHH:MM:SS plus the matching offset when the file has one, or null. Prefers DateTimeOriginal, then DateTimeDigitized, then IFD0 DateTime. No I/O.
• Used by: prepareForumPhoto.

• Purpose: Horizontal snap row for a note with photoCount > 1. Earlier slides are 88% wide so the next still peeks; the last slide is full width. The row is data-scroll-x (sideways only, vertical axis clipped) and is not a second page scroll. A current/total chip (forum.galleryPosition) sits on the visible still. Dots (gap-5, IconButton sm ghost, forum.galleryDot) scroll that row. Empty photos returns null. Single still has the chip and no dots. The capture time is stored, not shown.
• Inputs: photos ({ index, url }[]), alt, optional className (ForumBoard passes mt-2), optional onPhotoClick (ForumBoard stopCardToggle).
• Returns / side effects: React element. Local scroll index only. No network. Blob <img> URLs from the parent.
• Used by: ForumBoard, PublicThreadCard in PublicMessageLoader.

Guided shop submission on /shops. Closed state is only Add a shop. The open steps are photos, a map place, text, an optional 21.gifts username, then a summary. Post on the summary is the only submit. The add photo step shows Next only. Edit mode shows an icon-only Close (X) on that step only. Its accessible name is Cancel, and there is no visible Cancel word. It closes the editor. From the place step on, the top-left arrow returns to the previous step. The card has no Back button. Photos, place, text, and the username can each be left empty; an empty summary still follows the forum rule that a note needs text or media.

• Purpose: Replace the living-room composer on the shops feed. The shop tag is added when the note is sent, not typed in the text step. That text step lists people as soon as @ is typed, the same way a post does. The summary shows the photo count (stills plus a video), the place name or coordinates, the text, and @username, or None when that part was skipped.
• Inputs: posting, draft / onDraftChange, photoDrafts, videoDraft, onPickFiles, onRemovePhoto, onClearPhoto, place / onPlaceChange, username / onUsernameChange, onSubmit, optional onCancel (edit mode only), resetToken (closes the wizard after a successful send), maxLength. Optional mode (create default, or edit), submitLabel, keptMedia, onRemoveKept, and imagesOnly.
• Returns / side effects: React tree. No network. File selection calls onPickFiles. The summary button calls onSubmit (Post, or submitLabel such as Save changes). In edit mode, the icon-only Close (X) on the photo step calls onCancel. Its accessible name is Cancel, and there is no visible Cancel word. From the place step on, the top-left arrow returns to the previous step and is disabled while posting is true. The card does not draw Back.
• Used by: ForumBoard when shopComposer is set, and ShopNoteEditControl in edit mode.

Ask composer on /welcome. A donation is four steps and the counter reads {step} of 4. A credit is nine steps and the counter reads {step} of 9. Step 1 starts with the One-time / Daily pill and a Donation / Credit pill under it. Photos and text follow the credit confirmations. The preview shows the same pills and ForumGoalBar at 0 collected versus the ask. The heading and the step counter share one row (step on the right). The labeled Post on the preview is the only Ask submit. Switching to Credit on the preview returns to step 1. A shown bitcoin amount on the plan also shows the visitor's fiat when a rate exists.

• Purpose: Walk Ask for money so Continue on the amount step still requires a local 1..10_000_000-sat parse. The amount step and the preview each start with a One-time / Daily SegmentedControl (tone="neutral", two columns, rounded-2xl). A Donation / Credit pill sits under One-time / Daily, same classes, Donation pressed by default. The photo and text steps do not show either pill. Default cadence is once. One-time / Daily is not posted. The post itself sends goalCurrency and goalAmount. Only Credit is posted as goalRepayable true, together with goalTermDays. A donation stays on the four steps. A credit, after the amount, explains that the debt is fixed in the selected currency (bitcoin uses a shorter sentence, with no conversion, and warns that a rising bitcoin price can hurt the author because they bear the full price movement; a fiat credit says payments stay bitcoin and are only priced in that currency at the rate of each payment, not exchanged, and that the author receives bitcoin and bears the full price risk if the price falls before they spend it), then offers 30 days, 1 year, 2 years, or a custom whole number of days from 1 to 3650, then states that repayment is daily and starts the day after the credit is paid in full, and shows the daily amount. The next screen repeats the amount, the currency sentence, the term, the daily rule, and the daily amount. Its button confirms the author wants the credit. The screen after that states the daily plan, and its button confirms the author can repay that plan. There is no checkbox. Photos are step 7 of 9, the message is step 8 of 9, and the preview is step 9 of 9 with Credit pressed, a Loan tag beside the author, and the daily plan. Post is the only submit. The credit counter reads n of 9. The daily amount is the total split across the days, and any remainder is added to the last day. A fiat-draft preview shows the typed amount plus local Bitcoin and no third currency; a Bitcoin-draft preview shows Bitcoin plus the last gift-day rate.
• Inputs: step / onStepChange, askDraft / onAskDraftChange, draft / onDraftChange, posting, photoDrafts, videoDraft, onPickFiles, onRemovePhoto, onClearPhoto, authorName, onPost, optional rateDay (Bitcoin-draft preview counterpart of the typed ask), optional composerMaxLength (default FORUM_MESSAGE_MAX_LENGTH, 8000), optional askCadence ('once' | 'daily', default once) and onAskCadenceChange, optional askObligation ('donation' | 'credit', default donation) and onAskObligationChange.
• Returns / side effects: React tree. The One-time / Daily pill and the Donation / Credit pill are on step 1 and step 4. Continue on step 1 stays disabled until the parsed sats are 1..10_000_000. Continue on step 2 goes to step 3 with photos optional. Step 4 Post stays disabled without text, photo, or video, then calls onPost. No network.
• Used by: ForumBoard when composeIntent is ask.

• Purpose: Parse the Ask amount draft into a whole-sat goal.
• Inputs: raw string.
• Returns / side effects: Integer 1..10_000_000, or null when empty, non-digits, 0, or above the max.
• Used by: ForumAskWizard, ForumLoader.

• Purpose: Days a credit is repaid over. Presets are 30, 365, and 730. Custom is a typed whole number.
• Inputs: Preset 30 | 365 | 730 | 'custom', and the raw custom field.
• Returns / side effects: Day count from 1 to 3650, or null when custom is empty, not digits, or out of range. No I/O.
• Used by: ForumAskWizard.

• Purpose: Smallest units of a typed credit. Bitcoin is whole sats. Fiat is cents.
• Inputs: Amount draft and whether that draft is bitcoin.
• Returns / side effects: Non-negative bigint, or null when the draft is not that shape. No I/O.
• Used by: ForumAskWizard, ForumGoalBar.

• Purpose: Split a credit into equal daily units. Any remainder is added to the last day so the days sum to the debt.
• Inputs: Total sats or cents, and a day count from 1 to 3650.
• Returns / side effects: { perDay, last, days, remainder }, or null when the day count is outside that range. No I/O.
• Used by: ForumAskWizard, ForumGoalBar.

SVG progress bar for a top-level forum note. One SVG: orange fill in user units 0–100; overflow past 100% continues in green (app-success) from x=100 at most another 100 units (visual max 200%). The {percent}% label is a sibling, so it stays readable, and is uncapped (110, 250, …). Above the track, the posted line is never one currency when a visitor figure exists. Ask label, then the defined fiat when goalCurrency is USD/CHF/EUR/PHP, then formatBitcoin(goalSats), then the visitor's default fiat unless the ask was defined in that same fiat. That visitor figure is the frozen snapshot when the string is present, otherwise the gift-day rate when one is loaded. If neither exists, the line stays bitcoin. Joined with ·. A legacy ask (goalSats, no goalCurrency) is bitcoin plus the visitor's fiat when that figure exists. Renders nothing when goalSats is missing or <= 0. Lengths use SVG width / x / viewBox attributes, not React style.

• Purpose: Show collected-versus-goal progress on a top-level note that has a positive goalSats. BTC and legacy use forumGoalPercent(sats, goalSats); a fiat Ask uses forumFiatGoalPercent of the payment snapshot (null collected is 0%, not sats). Orange through 100%, green overflow, uncapped label. The amount line pairs currencies when a visitor figure exists: defined fiat plus bitcoin when the ask is in the visitor's fiat; otherwise bitcoin plus the visitor's fiat (snapshot, or the gift-day rate when the snapshot is missing and a rate is loaded). If neither a snapshot string nor a loaded rate exists, a bitcoin ask stays bitcoin. A third fiat is shown only when the definition currency is a different fiat. A repayable ask shows a Loan tag beside the author. Any other ask shows a Donation tag. Pressing the tag explains it. The bar does not repeat that sentence. A shop note keeps the #Shop link.
• Inputs: sats (collected), goalSats (whole-sat counterpart), optional goalCurrency / goalAmount / goal snapshots / payment snapshots, optional rateDay, optional preview, optional goalRepayable, optional goalTermDays, optional messageId (posted credit; omitted in the wizard), optional ledgerCollapsed (feed and profile show a Repayment list link to /messages/<id>/repayment-list and do not mount CreditLedger; the open note leaves it false and renders CreditLedger with list="summary"). Non-positive or non-finite goalSats yields null.
• Returns / side effects: The bar, or null. A posted credit with messageId and ledgerCollapsed false loads the public ledger (CreditLedger summary), which fetches GET /messages/:id/repayment. When ledgerCollapsed is true the bar shows only the Repayment list link and does not fetch. No other network.
• Used by: ForumBoard (top-level notes only), PublicMessageLoader, and ForumAskWizard (preview at 0 collected).

Integer percent for a forum goal label. Uncapped (110, 250, …). Uses Math.floor((sats * 100) / goalSats) when goalSats is a positive finite number. Returns 0 when the goal is missing, not finite, or <= 0. Negative or non-finite collected sats count as 0 so the label never goes negative. Unchanged sats path for BTC and legacy; fiat Asks use forumFiatGoalPercent.

• Purpose: Compute the uncapped whole-percent label for ForumGoalBar on BTC and legacy Asks. Fiat Asks use forumFiatGoalPercent.
• Inputs: sats (collected) and goalSats (whole-sat goal).
• Returns / side effects: Floored percent number. No I/O.
• Used by: ForumGoalBar.

Integer percent of a fiat Ask from decimal strings. Uncapped. Scales collected and goalAmount to 8 decimal places with BigInt and floors the quotient. Does not use sats and does not use the goal snapshots.

• Purpose: Percent label for a fiat-defined Ask in the definition currency.
• Inputs: collected (payment snapshot amountUsd / amountChf / amountEur / amountPhp, two-decimal string or null) and goalAmount (defined amount string).
• Returns / side effects: Floored percent. Null, missing, or non-two-decimal collected is 0. Unusable or zero goal is 0. No I/O.
• Used by: ForumGoalBar.

Defined Ask amount for the goal line. Prefix $ for USD and ₱ for PHP, otherwise CODE . At most two fraction digits pad to two (200 → ₱200.00). More than two keep every digit (10.125 → ₱10.125). One comma is the decimal mark. Grouping uses the visitor number format. Not the two-decimal snapshot formatter.

• Purpose: Show goalAmount exactly, not the two-decimal snapshot of the same currency.
• Inputs: amount string, fiat code, number-format style.
• Returns / side effects: Prefixed string, or '' when the amount cannot be shown. No I/O.
• Used by: ForumGoalBar.

• Purpose: Draw the repayment plan. Each day is a bar for the amount due that day. A line starts at the whole debt and falls to zero on the last day. The horizontal axis is the first day and the last day. When the credit is fully given those labels are the UTC dates. Before that they are day numbers. The words Per day and Still owed name the bar and the line.
• Inputs: amounts (one positive number per day, same unit), from, to, and totalText (the whole debt, already formatted).
• Returns / side effects: A figure, or null when every amount is missing. No network.
• Used by: CreditLedger, ForumAskWizard plan and confirmation.

• Purpose: Keeps a focused field or reply form inside the one active scrollport. A target taller than the scroller minus 24px is aligned to the scroller bottom minus 12px. Otherwise only a bottom or top overflow is corrected by that same 12px margin. It never calls scrollIntoView and it never scrolls the document.
• Inputs: The active scrollport element and the target element (input, textarea, select, or reply form).
• Returns / side effects: Void. Mutates that scrollport's scrollTop only. No network and no window scroll.
• Used by: revealReplyForm, ForumBoard composer and reply focus, useAppHeight after a viewport change.

• Purpose: Keeps a forum reply form inside the AppShell scroller by delegating to revealInScrollport after the null guards. That helper also corrects a top overflow and a target taller than the scroller. A missing scroller or form leaves the scroll position unchanged.
• Inputs: The shell scroller (HTMLElement or null) and the reply <form> (or null).
• Returns / side effects: Void. Mutates that scrollport's scrollTop only when both arguments are present. No network. No scrollIntoView.
• Used by: ForumBoard after an expanded reply composer is laid out, and only when no pay sheet is open.

• Purpose: Pulls an open pay sheet back into the AppShell scroller only when a jump has placed its top above the shell. A sheet that starts below the fold is left alone, so the note above it stays on screen. The reply composer is not pinned while a sheet is open.
• Inputs: The shell scroller (HTMLElement or null) and the pay sheet element (or null).
• Returns / side effects: Void. When the sheet top is above the shell, subtracts that gap from scrollTop. A sheet that starts below the fold, a missing scroller or sheet, and a top that is already inside leave the scroll position unchanged. No network.
• Used by: ForumBoard while a pay sheet is mounted, including when that sheet or the reply form changes size.

• Purpose: Playable note video. No native controls; one play button while paused; a click on the playing video pauses it; the fullscreen button sits in an absolutely positioned wrapper because the small icon button stays relative; the frame is mx-auto w-fit so the picture stays centered and both controls sit on it. The fullscreen button calls requestFullscreen on that frame, or webkitEnterFullscreen when that API is missing. Composer and ask previews do not use it.
• Inputs: Native video attributes except controls, controlsList, and playsInline.
• Returns / side effects: The video, play button, and fullscreen button. No network.
• Used by: ForumBoard feed video, PublicMessageLoader public note video.

• Purpose: Presentational public forum: each post card body without the action row is the expand/collapse control (forum.expand / forum.collapse, role="button" wrapping header, media, and body text, not an IconButton; the footer ₿ amount button and the reply-count button (when shown) also call onToggleExpand; React on every top-level note (forum.react, lucide Reply; expands the reply composer; omitted when deletedAt is set), Pay today's repayment for the signed-in author of a top-level repayable note when sats >= goalSats and the note is not deleted (disabled while payBusy or while payInvoice.messageId is this note; a repayNotice error renders role="alert" (rateLimit, authorWallet, or request)), Translate (Languages icon, controlSlotId on TranslatableNoteBody in this row), a copy-link IconButton on every note and every reply, optional Gift on a payable reply, and optional delete sit outside that control as sibling IconButtons that stopPropagation; when shopNoteEdit is set, the shop pencil sits in that right-hand footer after copy and before the place control, and the reply count stays in the left group; when shopPlaceEdit is set, a compact place control (Add a place or Edit place) sits in that footer after the pencil and before the account control; when shopAccountEdit is set, a compact account control (Add an account or Edit account) sits after the place control; Gift/Delete/reply composer also omit when deletedAt is set). Optional dismissible living-room laws hint box (X control; two laws plus links to /rules and /contact) when lawsVisible, Active/No gifts yet/All/Most popular ForumModeSelect (closed dropdown; selected label and chevron on the trigger; unpaid count chip on the closed trigger when unpaidNewCount > 0 and unpaid is not selected), list of posts (name, the author row uses MessageKindTags (Loan and Donation buttons that show a sentence, #Shop stays a link), optional Founder / Moderator / Initiator / Verified role pill on notes and replies when role is one of those four (basis has no pill), top-level shop notes show a #Shop link to /shops and hide #21GiftsShop, timestamp, optional inline photo from blob URLs (single still when photoCount ≤ 1; a horizontal snap row (ForumPhotoGallery, data-scroll-x, 88% peek) when photoCount > 1 — sideways only, current/total chip, dots of loaded blob URLs keyed ${id}:${index}) then caption text below the photo, a link to /map?pin=<id> (the label, or coordinates when the label is null) on a top-level note that has a place, an @username link to /members/{id} on a top-level note that has a shop account, optional inline <video> playback for notes with video (player keeps the clip aspect ratio with max-h-80 max-w-full, no full-width black canvas), remaining body text through ForumQuotedBody / ForumNoteText (280-character preview plus forum.showMore only when the body is longer than 560 on the feed; signed-in /messages/[id] passes truncate={false} so the original stays full), Translate (Languages icon) / Show original / Show translation in the footer icon row via TranslatableNoteBody (controlSlotId), which portals NoteTranslate with placement="row" when the board has that row, a reply or note with via === 'nostr' (a Nostr zapper with no 21.gifts account) renders an External button in place of a role pill, sharing the same per-message hint toggle state as the role pill's hint, and renders its body via TranslatableNoteBody plain (no quoted-note unfurl, URLs stay visible text) instead of ForumQuotedBody, ₿ amount plus optional preferred-fiat · formatFiatDisplay of the amount stored when the payment was made (a stored string as-is; a null or missing field on a passed payment uses the gift-day rate) with a Gift pay icon only when the card is a payable reply (parentId set); the card's copy control is labelled forum.copyReplyLink when the card is a reply and forum.copyLink otherwise, and always copies the card's own origin /l/<8 hex> (first UUID group) when that id is a UUID, otherwise origin /messages/<id>) or empty/loading/error, messenger-style composer (Send a post / Ask for money pill; Post is Add a photo or video ImagePlus, then Add a place (MapPin, PlaceField) when onPlaceDraftChange is set, left of the textarea, Post Send icon to the right; Ask is ForumAskWizard (the amount step and the preview open with the One-time / Daily pill; the photo and text steps do not); when allowAsk is false the Post/Ask pill and Ask wizard are omitted; shopComposer shows ShopAddWizard instead of the post composer), optional photo draft preview (Selected photo) when photoDrafts.length === 1 with Remove photo X, composer gallery when photoDrafts.length > 1 (ul of Selected photo alts + per-index Remove photo), optional video draft preview with Remove video X — icon-only, catalog aria-labels, maxLength from optional composerMaxLength (default 8000)), in-card reply composer (amount row first: AmountEntry layout="inline" id="forum-reply-amount" with the bitcoin/fiat switch on that same line, then one text line and Post aligned beside it), and a pay sheet on a payable reply or, when payHost is composer, on the top-level composer: amount form with a live equivalent in the preferred fiat only when the conversion is non-null (no picker; after mint the equivalent uses the invoice amount, not an empty draft's 21-sat default), then every user-agent amount CTA is Continue (forum.payContinue) and only requests the invoice; after mint every user-agent shows the same invoice card (confirm sentence, wallet Button that sets window.location.href to the Android Intent or walletofsatoshi:); the card mounts QrCode only when the user-agent is not a smartphone (isSmartphoneUserAgent, not viewport); wallet Button uses forum.payOpenWallet / aria forum.payOpenWalletAria (no custom-scheme <a>); Close (X) dismisses the sheet and stays on the page. That control is not Back. Gift-only replies show send ₿… (forum.giftReply) plus the same optional preferred-fiat · as notes; a reply with text and sats shows that formatted amount under the text. When receivedSats is greater than zero, forum.receivedOnReply is a separate line and is not added to sats. A text reply that has both uses forum.sentOnReply for the sent line, and the two lines share a left rule. Clicking a role pill toggles a short explanation under that card header (one open at a time). Selector stays visible in every board state unless modeSelector is false or composerHidden is true. When modeSelector is false the list is every loaded row (mode all), including zero-sat basis notes; an empty loaded list still uses emptyKey, not forum.emptyPaid. Uses optional emptyKey (forum.empty default, shops.empty on shops) when the loaded list is empty, forum.emptyPaid when Active or Most popular hide every loaded row (Most popular remains paid-only; Active also keeps unpaid moderator notes; a top-level note with goalSats > 0 and zero sats is not Active), and forum.emptyUnpaid for No gifts yet when that filter hides all loaded rows. Props messages are newest-first (API window); Active, No gifts yet, and All keep that order (newest at the top). Most popular stays sats-descending. The composer sits under the mode selector / filters, above the newest-first list; replies remain oldest-first. When onRefresh is passed, pull-to-refresh from the top of the AppShell inner scroller (useAppShellScroller) calls it; while refreshing (or a pull that reached the arm threshold) a visually hidden (sr-only) role="status" with forum.refreshing is mounted for assistive tech only — idle markup has no status node so welcome screenshots stay unchanged. When newPostsAvailable is true, a labeled primary Button (forum.newPosts, decorative lucide ArrowUp) is sticky top-2 in the scroller; the node is omitted when the flag is false. When moderatorAppointedAvailable is true, a labeled primary Button (forum.moderatorAppointed, size sm with shadow-lg, decorative lucide ArrowUp) in the same visual language as New posts is sticky top-2 when it is the only pill and calls onShowModeratorAppointed; the node is omitted when the flag is falsy. When both this and newPostsAvailable are true, the appointment pill stays sticky top-2 and New posts is sticky top-14. Listens for FORUM_COMPOSE_EVENT / requestForumCompose: focuses the new-post textarea with preventScroll and then revealInScrollport when the shell scroller exists and consumes pending compose only when that textarea exists (composerHidden boards keep the flag). /messages/<uuid> and http(s)://<host>/l/<8 hex> HTTP(S) URLs in a body unfurl into a nested post and the URL is removed from the visible text once that note loads.
• Inputs: ForumBoardProps — messages, optional readOnly (signed-out living room: no composer, pay, delete, or @mention links; an author name with a non-empty accountId is still the profile button, including when readOnly is true; Enter or Space on that button opens the profile and does not toggle the card, because the card key handler ignores a descendant target; the mode selector stays), error (boolean load-failure flag), loading, optional refreshing / onRefresh (omit onRefresh to disable pull-to-refresh), optional newPostsAvailable / onShowNewPosts (pill omitted when the flag is falsy), optional moderatorAppointedAvailable / onShowModeratorAppointed (pill omitted when the flag is falsy), posting, draft, onDraftChange, askDraft / onAskDraftChange, optional allowAsk (default true; false omits the Post/Ask pill and the wizard) / optional composeIntent / onComposeIntentChange / askStep / onAskStepChange / askCadence ('once' | 'daily', default once) / onAskCadenceChange / authorName, onPost, onRetry, formError (empty / tooLong / ask / request / rateLimit / unsupported / tooLarge / tooMany; ForumFormError = 'empty' | 'tooLong' | 'ask' | 'request' | 'rateLimit' | 'unsupported' | 'tooLarge' | 'tooMany' | null), controlled mode / onModeChange, optional modeSelector (default true), optional nearEndRef (callback ref on the visible note about eight rows from the end so ForumLoader can prefetch the next page), optional unpaidNewCount (default 0), required lawsVisible / onDismissLaws, photoDrafts (ForumPhotoPayload[]), placeDraft (ForumPlacePin | null), optional onPlaceDraftChange (omit it and the place control is absent, so replies have none), videoDraft, onPickFiles(files: File[]), onRemovePhoto(index: number), onClearPhoto, photoUrls, videoUrls, optional composerHidden (hides the new-post composer; the textarea is absent so compose-pending is not consumed), optional composerMaxLength (default FORUM_MESSAGE_MAX_LENGTH; shops pass 7986 so the #21GiftsShop suffix fits), optional emptyKey (forum.empty default, shops.empty on shops), plus pay sheet props (payMessageId, optional payHost (composer keeps the sheet on the top-level composer; card binds to the matching parent or reply; omit/null infers from the list), payDraft, payBusy, payError (amount / request / rateLimit / authorWallet / deleted), payInvoice, optional replyPayPreview (string | null, default null; when set with a matching card invoice, ForumReplyPayPage replaces the reply composer), payWaiting, optional rateDay (FiatRateDay | null; omit or null leaves unsent previews bitcoin-only because no rate is loaded; a present rateDay is the gift-day rate when no stored string exists; a stored string stays visible), onPayOpen, optional viewerAccountId, optional onRepay, optional repayNotice (rateLimit / authorWallet / request as role="alert" on that card), onPayDraftChange, onPaySubmit, onPayCancel), expand/replies (expandedId, onToggleExpand, replies, repliesLoading, repliesError, onRetryReplies, reply composer with optional replyAmountDraft / onReplyAmountDraftChange, replyFormError including amount for a non-numeric or overflowing paid-reply sats field and deleted when that note is missing or was deleted), optional shopComposer (shops; ShopAddWizard instead of the post composer), shopUsername / onShopUsernameChange / shopResetToken, optional shopNoteEdit / onShopNoteUpdated (moderator pencil on a top-level shop note), optional shopPlaceEdit (true on shops; the footer place control is absent when omitted) and onShopPlaceUpdated (applies a saved or cleared pin to that row), optional shopAccountEdit (true on shops; the footer account control is absent when omitted) and onShopAccountUpdated (applies a saved or cleared shop account to that row), and optional onDeleted (moderator DeletePostControl on the parent footer and on nested replies with kind="reply"), optional permalinkTargetId (nested reply ring only: data-permalink-target="true" and ring-1 ring-app-fg; parent notes are not ringed), and optional truncate (default true; PublicMessageThread passes false). Gift-only replies (text === '' and sats > 0) render forum.giftReply with formatBitcoin plus the same optional preferred-fiat · formatFiatDisplay suffix as notes (the gift-day rate when the stored field is null or missing); text plus a gift shows that formatted amount under the text. receivedSats greater than zero adds forum.receivedOnReply with the received fiat fields, not a sum. A text reply with both amounts labels the sent line forum.sentOnReply. The video-draft X still calls onClearPhoto; each photo-draft X calls onRemovePhoto(index).
• Returns / side effects: React tree. Copy-link always copies origin /l/<8 hex> (first UUID group) when the id is a UUID, otherwise origin /messages/{id} — a note copies its own id, a reply copies its own id (no parent resolution). Filters via visibleForumMessages. Load error copy is forum.error via t(), never Error.message. Formats timestamps via formatForumTime. Hides empty text paragraphs; never points <img src> at /messages/.../photo without a blob URL. Feed video is ForumVideo (no native controls; one play button while paused; one fullscreen button on the picture). Inline feed <video> keeps the clip aspect ratio (max-h-80 max-w-full, no full-width black canvas). A failed <video> error event hides that player (photo fallback when a blob URL exists). Clicking a role pill toggles a short explanation under that card header (one open at a time). Dismiss control calls onDismissLaws only; persistence is owned by ForumLoader. ForumBoard itself does not fetch; nested NoteTranslate GETs /translate on mount and POSTs on Translate. No mode state of its own. After onPaySubmit resolves to an invoice, ForumBoard does not window.location.assign; every user-agent shows the same invoice card; the wallet Button sets window.location.href to the Android Intent or walletofsatoshi:; QrCode is mounted only when the user-agent is not a smartphone. A FORUM_COMPOSE_EVENT focuses the new-post composer when it is mounted; a composerHidden board leaves pending compose set for a later visible board. While a pay sheet is open, revealPaySheet runs instead of revealReplyForm. The scroll position from before the sheet opened is restored, so inserting the sheet does not scroll the note away, and a sheet that starts below the fold is not pulled to the top. The reply composer on that note is disabled while its invoice card is open and no reaction preview is set. A paid reaction replaces the reply composer with ForumReplyPayPage and the typed sentence is the preview. Gift-on-reply and composer-hosted sheets stay ForumPaySheet. The close control sits in an absolutely positioned wrapper at the sheet's top left, because the small icon button itself stays relative.
• Used by: ForumLoader, MemberProfileScreen, PublicMessageThread.

• Purpose: Money on a reply. What the author sent and what later arrived stay two lines and are never added. A gift-only reply (text === '' and sats > 0) is forum.giftReply. A reply with text and sats, and no later receipt, is the bare formatted amount under the body. When receivedSats is greater than zero, that receipt is forum.receivedOnReply on its own line. A text reply that also sent sats labels that line forum.sentOnReply, and the two lines share a left rule. Zero or a missing receipt draws no received line. Nothing to show returns null.
• Inputs: text, sats, optional receivedSats, rateDay, fiat, numberFormat, optional sent fiat fields for sats, optional received fiat fields for receivedSats.
• Returns / side effects: React element, or null when both amounts are absent. No network. Bitcoin via formatBitcoin. Fiat via preferredFiatSuffix (stored string, otherwise the gift-day rate).
• Used by: ForumBoard on every nested reply, and PublicThreadCard in PublicMessageLoader when the unsigned card is a reply with receivedSats greater than zero.

• Purpose: The amount form and invoice card already used for a payable forum reply. A habit comment uses this same sheet: Amount, Continue, then the confirmation, the desktop QR, and Pay with Wallet of Satoshi. It does not show the raw invoice. Close stays on the page.
• Inputs: messageId, the pay draft, busy, error, invoice, waiting flag, draft and unit callbacks, submit, cancel, the gift-day rate, optional ratePending (default false; Continue does not submit while it is true), whether to show the QR, and a click handler so the sheet does not toggle the card under it.
• Returns / side effects: The in-card sheet (data-pay-sheet). Continue calls onPaySubmit only when it is not busy and ratePending is false. The wallet button sets window.location.href to the Android Intent or walletofsatoshi:. No network of its own.
• Used by: ForumBoard and HabitComments.

• Purpose: Replaces the reply composer after a paid reaction is sent: it is a component in that same slot, not a new URL, and shows only a read-only preview of the submitted reply, the Pay ₿… amount line with the preferred-fiat suffix, the pay control (desktop QR plus Wallet of Satoshi button; smartphone: button only), and Waiting for payment… while polling.
• Inputs: preview (raw submitted text; a trimmed-empty string omits the paragraph), amountSats, pr, payWaiting, payBusy, showPaymentQr, rateDay, onCancel.
• Returns / side effects: React element with data-reply-pay-page and data-pay-sheet. Close (X) calls onCancel and stays on this view. It is not the top-left back arrow. The wallet button sets window.location.href to the Android Intent or walletofsatoshi: href. An empty trimmed preview omits the paragraph. The preview paragraph uses pl-12 so the close control, including its hit slop, does not cover the first glyphs.
• Used by: ForumBoard.

• Purpose: Client loader for in-app contact on /contact. Session from useAuthStore; returns null without a session. Posts via postContact. On success fetches conversations and navigates to /messages or /messages?c= for the official 21.gifts thread. No local success-hide of the form. Uses nextContactRequirement so missing name/rules open RequirementsOverlay (no Skip); Lightning Address is not required for contact.
• Inputs: None (reads session from the auth store).
• Returns / side effects: React element wrapping ContactScreen, or null. Owns draft/posting/formError. Empty or whitespace drafts set empty; trimmed text longer than 8000 characters sets tooLong and does not call postContact. After a successful post, fetchConversations then router.push to the inbox and posting stays true until unmount. A failed post sets request and clears posting so Send can retry.
• Used by: Screen /contact.

• Purpose: Next.js page for /contact.
• Inputs: None.
• Returns / side effects: AppShell with ProfileChromeLeft top-left, SignedInChrome top-right, and OnboardingGate around ContactLoader.
• Used by: Route /contact.

• Purpose: Presentational in-app contact: heading Contact, lead, link to living-room rules, and a messenger-style composer (textarea with icon-only Send IconButton, catalog aria-label contact.send, maxLength 8000). Success is owned by ContactLoader (navigate to the inbox thread), not a local success copy.
• Inputs: ContactScreenProps — posting, draft, onDraftChange, onPost, formError (empty / tooLong / request).
• Returns / side effects: React element. No network.
• Used by: ContactLoader.

• Purpose: Send an old /map address to the shops map. There is no map page.
• Inputs: The incoming request whose path is /map.
• Returns / side effects: Redirect to /shops#map. A query string such as ?pin= is kept (/shops?pin=#map).
• Used by: Route /map.

• Purpose: Presentational map card: heading Map, then every live forum pin from fetchPlaces. Without a Google key the pins are links. With a key the same pins are also markers. A 21.gifts author name links to /members/:accountId; an external name stays text. A moderator sees the shop pencil on a pin with shop: true; it loads that note and opens the same steps as editing a shop post. A failed load shows forum.editShopNoteLoadFailed, not the save-failure sentence. embedded returns that body without the heading or card. A long pin name or label wraps inside the row. With a key, one pin, or a ?pin= that matches a pin, centers that pin at zoom 14. Several pins and no matching ?pin= frame every pin (fitBounds, padding 32). A fitted zoom above 14 is set back to 14.
• Inputs: Optional embedded (default false). Catalog via useTranslations. Session from useAuthStore. Optional ?pin= id.
• Returns / side effects: Card maxWidth="xl" surface={false}, or only the body when embedded. Fetches places and /maps/key.
• Used by: ShopsScreen.

• Purpose: Load every live top-level forum pin for the signed-in session.
• Inputs: sessionToken bearer.
• Returns / side effects: ForumPlaceRow[] from GET /forum/messages/places. A row may include shop: true when the note is a shop. Throws the visitor-facing load error on a non-2xx status, a network failure, or a body that fails the schema.
• Used by: PlacesMapScreen.

• Purpose: Same-origin Bearer proxy of api GET /messages/places.
• Inputs: Incoming request.
• Returns / side effects: The upstream response. No session of its own.
• Used by: GET /forum/messages/places.

• Purpose: Optional place control on the top-level forum composer, and the compact editor a moderator uses on a shop note. Opens a map when /maps/key returns a key. Confirm stores { lat, lng, label }. No key shows the unavailable sentence and does not confirm a pin. On the device's local Sunday neither the preview nor the map panel is rendered; the pin stays inside the Sunday writing gate. Otherwise, once the frame box is measured, the preview and the map panel are fixed to the window and kept inside the app frame, and are not sized from the viewport (vw). Until that box is measured they sit under the pin as an absolute anchor. The map shrinks so the confirm control stays inside the window, and the page still has one scroller.
• Inputs: place, disabled, onChange. Optional buttonSize (lg default, or sm), buttonVariant (secondary default, or ghost), showPreview (default true), ariaLabel (default Add a place), and onCommit. Without onCommit, Done and Remove call onChange and close. With onCommit, those buttons wait; a rejection keeps the panel open and shows the save error; a success closes without calling onChange. When preview is hidden and a pin is already set, Remove stays inside the open panel, including when the map is unavailable.
• Returns / side effects: Attach button, optional preview, and panel. Fetches /maps/key when opened.
• Used by: ForumBoard (top-level composer) and ShopPlaceControl.

• Purpose: Places one popover inside the app frame. The width is the preferred width when it fits, otherwise the room between the insets. The left edge stays on the anchor unless that would cross an inset. Vertically it opens downward when that side has at least 280px and at least as much room as above, otherwise upward, otherwise from the top inset across the whole frame height. It returns null when the frame has no positive room or the preferred width is not positive.
• Inputs: Frame left, right, top, and bottom, anchor left, top, and bottom, gap, preferred width, inset, and viewport height, all in pixels.
• Returns / side effects: { left, width, maxHeight, top, bottom } with exactly one of top or bottom set, or null. No DOM writes and no network.
• Used by: PlaceField for the place preview and the map panel.

• Purpose: Reads the live document and lists sideways scroll of the document, sideways scroll of the active page scroller, and boxes whose border box leaves the window by more than one pixel on the left, right, top, or bottom. Content inside [data-scrollport] may sit past the top or bottom of the window unless it is position:fixed. A position:fixed box is still reported. A box inside [data-scroll-x] is ignored for the horizontal check unless it is position:fixed and its border box already crosses the left or right edge of the window. The sideways row itself is not ignored.
• Inputs: None. Uses the open document, window.innerWidth, and window.innerHeight.
• Returns / side effects: A string array. Empty means the page stays in the window. No DOM writes and no network.
• Used by: shotScreen in e2e/visual.spec.ts, before every screenshot, and the behavior test Function: pageFrameProblems.

• Purpose: Moderator-only place editor on a listed shop note. Hidden on replies, hidden notes, non-shop text, unsigned sessions, and ranks below moderator.
• Inputs: message (top-level shop note) and onUpdated (message id plus the saved pin, or null when cleared).
• Returns / side effects: Compact PlaceField (showPreview false, small ghost Add a place / Edit place). onCommit calls setMessagePlace; a failed save keeps the panel open and shows forum.placeSaveFailed.
• Used by: ForumBoard when shopPlaceEdit and onShopPlaceUpdated are set (ForumLoader feed="shops").

• Purpose: Moderator-only pencil on a listed shop note. Opens the same five steps as adding a shop, already filled in, plus the edit history. Hidden on replies, hidden notes, non-shop text, unsigned sessions, and ranks below moderator.
• Inputs: message (top-level shop note), onUpdated (the saved note), optional existingPhotos, optional existingVideoUrl, and optional startOpen.
• Returns / side effects: Small ghost pencil (Edit shop note). The summary button is Save changes. It writes only the text, place, account, or stills that changed. A video stays. Already-shown stills are copied onto addresses this editor owns before the steps open, so a partial save can revoke the feed addresses without blanking the open editor. A failed copy opens the steps with forum.editShopNoteFailed and no stills, and does not revoke the feed addresses. Stills are not replaced unless every current still loaded. A failed save keeps the panel open and shows forum.editShopNoteFailed. History rows show who, when, and the field (text, place, or account). A failed history load shows forum.editHistoryFailed.
• Used by: ForumBoard when shopNoteEdit and onShopNoteUpdated are set (ForumLoader for a moderator on every feed), ShopTable, and PlacesMapScreen for a pin with shop: true.

• Purpose: Moderator-only shop-account editor on a listed shop note. Hidden on replies, hidden notes, non-shop text, unsigned sessions, and ranks below moderator.
• Inputs: message (top-level shop note) and onUpdated (message id plus the saved { id, username, name }, or null when cleared).
• Returns / side effects: Small ghost Add an account / Edit account (User icon). The open field starts at @, or @username when an account is already attached, and the same People list as a forum post is visible immediately. Choosing a row fills @username. A space or any other non-username hides the list. The panel is fixed to the window so the page does not scroll sideways. A typed prefix immediately drops usernames that do not start with it. It shows at most eight people and does not scroll on its own. Rows drop until the box fits under the app chrome, and the list hides rather than covering that chrome. Save account strips one leading @. Optional Remove account. Empty or unknown username shows forum.shopAccountMissing and keeps the panel open; other failures show forum.shopAccountSaveFailed. Success calls setMessageShopAccount then onUpdated and closes.
• Used by: ForumBoard when shopAccountEdit and onShopAccountUpdated are set (ForumLoader feed="shops").

• Purpose: Next.js page for /shops. Flow AppShell (align="start") with ProfileChromeLeft + SignedInChrome, OnboardingGate screen="welcome", and ShopsScreen. No route.ts beside the page.
• Inputs: None.
• Returns / side effects: The shops screen.
• Used by: Route /shops.

• Purpose: Presentational shops card: heading Shops, lead shops.lead, a Post / Map / Table pill, then the selected body. Post is ForumLoader feed="shops". Map is PlacesMapScreen embedded. Table is ShopTable.
• Inputs: Catalog via useTranslations. The view stays unset until the hash is read. /shops#map and /shops#table open that view; /shops#post, a missing hash, or an unknown hash open Post. Choosing an option writes the same hash. Post clears it.
• Returns / side effects: Card maxWidth="xl" surface={false}. The post list, map, and table mount only after the hash is read. The map and table fetch only after their option is selected.
• Used by: ShopsPage.

• Purpose: Neutral SegmentedControl labelled Shop view that switches the shops page between post, map, and table.
• Inputs: value (post, map, or table) and onChange.
• Returns / side effects: A SegmentedControl tone="neutral". The pressed option uses the app button fill. No network.
• Used by: ShopsScreen.

• Purpose: Table of shop notes with name, place, and operator. A moderator sees the same shop pencil on each row.
• Inputs: Session from useAuthStore. Catalog via useTranslations.
• Returns / side effects: Loads GET /messages?hashtag=21GiftsShop&mode=all. Name is the first note line. Place links to /map?pin={id} (label, or coordinates). Operator links to /members/{id} as @username. A missing place or operator is an em dash (shops.missing). Show more loads the next page. If a page has no shop rows and another page exists, Show more stays and the empty sentence does not. If that page fails, the rows already shown stay, with the forum error and Try again, which reloads the same page. A failed first page replaces the table with that error. A missing-requirements response opens /setup/rules instead. Null without a session.
• Used by: ShopsScreen.

• Purpose: Author row for a note, plus one tag per kind. Loan and Donation are buttons. Pressing one shows its explanation and pressing it again hides it. #Shop stays a link to /shops.
• Inputs: kinds from noteKinds. children is the author name and any role tag.
• Returns / side effects: The row and, when a loan or donation tag is open, a role="status" sentence. No network.
• Used by: ForumBoard, the public note page, and the ForumAskWizard preview.

• Purpose: Which tags a note shows. A reply has none. A repayable ask is a loan. Any other positive ask is a donation. A #21GiftsShop token adds shop.
• Inputs: parentId, text, optional goalSats, optional goalRepayable.
• Returns / side effects: loan, donation, and shop in that order, or an empty list. No network.
• Used by: ForumBoard, ForumAskWizard.

• Purpose: True when text contains a #21GiftsShop token (case-insensitive; next character not [A-Za-z0-9_]).
• Inputs: text: string.
• Returns / side effects: boolean. No network.
• Used by: ForumLoader, ForumBoard, ensureShopHashtag.

• Purpose: Remove #21GiftsShop tokens from display text and collapse leftover blank lines.
• Inputs: text: string.
• Returns / side effects: Display string (empty if only the hashtag was present). No network.
• Used by: ForumBoard.

• Purpose: Append \n\n#21GiftsShop when missing; empty/whitespace becomes #21GiftsShop; already-tagged text is unchanged.
• Inputs: text: string.
• Returns / side effects: Text to POST when the author is unpaid-write exempt, otherwise the compose-fee invoice comment. No network.
• Used by: ForumLoader (shops compose).

• Purpose: Presentational living-room rules body from catalog keys: lead with the The test callout, three rule cards (rules.lawKicker with {n}, title, body, optional test callout), welcome / allowed / better-not / forbidden lists rendered as bordered cards with lucide glyphs (Check text-app-fg, Check muted, Minus, X text-app-danger), the Our house closing block (rules.houseBody + rules.houseClosing), and an optional Contact CTA to /contact. There is no forum back CTA in the document.
• Inputs: messages catalog for the request locale; optional showNav (default true); optional chapter (RulesChapterId). When chapter is set, only that chapter is rendered and the public nav is omitted (showNav ignored). When showNav is false and chapter is omitted, the public Contact nav is omitted.
• Returns / side effects: React element. Server component — uses translate, not useTranslations. No network.
• Used by: RulesPage, RulesSetupPage.

• Purpose: Client chrome wrapper for public /rules: when a session is hydrated (ready && session !== null), mounts signed-in shell (ProfileChromeLeft + SignedInChrome); otherwise mounts ProfileChromeLeft with wordmark href / plus LanguageSwitcher. The arrow returns to the previous in-app view, or /welcome when this tab has none.
• Inputs: children (heading + RulesDocument from RulesPage). Uses useHydrateSession and useAuthStore for session.
• Returns / side effects: PageChrome with the matching top-left / top-right slots around children. No network beyond session hydration.
• Used by: RulesPage.

• Purpose: Next.js page for /rules with localized heading and living-room rules document, wrapped in RulesPageChrome (signed-in or unsigned chrome depending on hydrated session).
• Inputs: None. Calls getRequestLocale() for the page title and document catalog.
• Returns / side effects: Heading + RulesDocument inside RulesPageChrome (chrome is no longer always unsigned Wordmark + Language).
• Used by: Route /rules.

• Purpose: Client loader for the public forum on /welcome and /shops with feed="shops" (filter #21GiftsShop, hide laws, append hashtag on compose, emptyKey shops.empty, pass shopPlaceEdit and onShopPlaceUpdated so a moderator can set, replace, or clear the pin on an existing shop note, and shopAccountEdit and onShopAccountUpdated so a moderator can set, replace, or clear the shop account). Session and account from useAuthStore; shops return null without a session, and the living room loads the public active page instead. The laws hint stays hidden without a session. Living-room default remains Active (first paint { mode: 'active', limit: 20 }, no hashtag). Shops always requests mode: 'all' with hashtag: '21GiftsShop' and does not mount the mode selector, the Post/Ask pill, or ForumAskWizard (allowAsk: false); it mounts ShopAddWizard through shopComposer and does not apply active/unpaid/popular. A moderator session passes shopNoteEdit on every feed, not only shops. A mode switch resets the loaded pages and refetches page 1 of the new mode without blanking the current list. An IntersectionObserver sentinel about eight notes from the visible end prefetches the next page when nextCursor is present. An empty shops page shows shops.empty immediately. The 30-second visible-tab poll, visibilitychange, persisted pageshow, and pull-to-refresh fetch page 1 only, without a cursor; applying page 1 does not replace already-loaded older pages. Fetches via fetchMessages, loads photos via fetchMessagePhoto into blob URLs (effect keyed on photoIdsKey so payable-poll list refreshes do not cancel in-flight photo fetches), loads rateDay via the shared useLatestRateDay() hook on mount (failure leaves rateDay null), posts via fetchComposeTarget then postMessageInvoice (1 sat to 21.gifts, payHost: composer) for anyone below verified, otherwise postMessage with a photos array so postMessage dual-sends { photo, photos } (non-empty photos wins; max 10) or postMessageVideo (multipart clip); composer submit is ignored while a note POST is in flight (sync notePostInFlightRef, not only the posting prop); prepares picks via prepareForumPhoto / isForumVideoFile / prepareForumVideo; owns photoDrafts (plural, not photoDraft), placeDraft, and videoDraft / videoUrls; onPickFiles appends stills and sets formError tooMany when the selected File list (not successful prepares) would exceed 10, preparing only the first remaining slots; video xor stills; video-only posts are allowed. Pay invoices via postMessageInvoice (optional text when the reply composer pays) and waits on fetchPublicMessage while the pay sheet is open (no attempt cap; aborts in-flight wait on Close / clear). A top-level note passes sinceSats and closes when sats rises. An existing reply passes sinceReceivedSats and closes when receivedSats rises. After that rise, the row is merged into loaded replies/messages (no thread refetch). Today's repayment uses postRepaymentInvoice (POST /messages/:id/repayment) and repayNotice; success opens the invoice card on the note; failure sets repayNotice with rateLimit / authorWallet / request; the alert sits on the card. Owns Active/No gifts yet/All/Most popular feed mode (default Active) and the No gifts yet last-visit stamp (21gifts.forum-unpaid-seen): hydrates it on mount, stamps on entering unpaid and while unpaid as the list refreshes, and passes unpaidNewCount to ForumBoard (0 while unpaid is selected or messages are still null). After a successful living-room post with created.sats === 0, switches mode to All so the author sees the note, including a positive goalSats Ask, because Active and Most popular hide a note that has not received sats. If All is already selected, loaded pages and nextCursor stay. Shops already lists with mode: 'all' and does not switch. The sheet clears when the pay target is no longer in the visible parent list and not in loaded replies (mode change, collapse, or delete), not when Active merely hides the parent note. Also polls GET /forum/messages until the merged list is payable (8 attempts, 2s; local extras kept until GET echoes), cancelled-flag fetch like StatsLoader. Silently re-fetches on visibilitychange (hidden→visible), on pageshow when persisted is true, on a FORUM_LIST_POLL_MS visible-tab interval, on FORUM_HOME_EVENT (wordmark / Menu Home while already on /welcome), and when the board pull-to-refresh calls onRefresh — shared load path with mount/retry; silent refresh does not flip the board to the loading copy when a list already exists, keeps the list when a silent refresh fails, and does not auto-scroll the newest note when a newer note arrives from refresh. When not at top (shellScrollTop(scroller) < 8 is at-top; window.scrollY is only the no-shell fallback) and hasUnseenForumPosts is true, the fetch is held and ForumBoard shows New posts; at the top the list is applied. With a session, fetches GET /forum/notifications via existing fetchNotifications (cancelled-flag fetch like other ForumLoader loads) and, when an unread moderator_appointed row exists (readAt === null), drives the ForumBoard pill (moderatorAppointedAvailable / onShowModeratorAppointed); click marks that row read via markNotificationRead and clears the flag, staying on /welcome without auto-scroll; a fetch error leaves the banner hidden; a mark-read failure leaves the banner (does not crash). The payable poll updates sats, payable, and the four payment snapshots (amountUsd, amountChf, amountEur, amountPhp) on already-listed ids only and does not insert unseen ids. Owns the living-room laws hint visibility from account.forumLawsDismissed and persists dismiss via dismissForumLaws (optimistic; applies the response or restores the previous flag only when the session token is unchanged and an account is still present). Owns expand/replies (fetchReplies, retry, moderator nested-reply hide via onDeleted / deleteMessage without removing the parent, reply composer: empty reply text and an empty amount invoices 21 sats even for verified; unpaid postMessage with inReplyTo only when there is text and the amount is empty, and only for verified; below verified invoices 1 sat to 21.gifts via the compose-target note (payHost: composer); expand is ignored while a reply posts). A signed-in note card fully inside the shell scrollport calls markVisibleForumNoteRead; expanding still calls markNotificationsReadForMessage. After a failed media POST following compose-pay, the pay sheet is cleared (payWaiting / payInvoice / payMessageId / payHost) so a later compose invoices 21.gifts again. Uses nextPostRequirement so a missing name, username, Lightning Address, or rules agreement opens RequirementsOverlay (no Skip) before a post or reply retries. After a successful top-level post or reply, sets hasPosted: true on the session account when the session token is unchanged and an account is still present (no persist-flag / Skip-forever POST).
• Inputs: Optional feed ('living-room' default, 'shops'). Reads session and account from the auth store.
• Returns / side effects: React element wrapping ForumBoard, or null. Owns draft/askDraft/composeIntent/askStep/askCadence/placeDraft/photoDrafts/videoDraft/photoUrls/videoUrls/posting/formError/feedMode/loaded-pages/nextCursor/pay/expand/replies/refreshing/rateDay state, the No gifts yet last-visit stamp, and retry attempts. askCadence defaults to once and returns to once after the visitor's own compose is paid (postAfterPay or switchToAll in the pay poll) and in applyCreatedNote. A gift or a reply does not clear it. Empty text without photos and without a video sets empty; trimmed text longer than 8000 characters sets tooLong and does not call postMessage / postMessageVideo. Photo-only and video-only posts are allowed. Empty reply text with an empty amount invoices 21 sats (pay-sheet default) and does not set empty, including when the parent omits accountId. A non-exempt reply with text and an empty amount still invoices 1 sat instead of setting amount. 0 is billed as 1 sat. Non-digits and overflowing amounts still set amount (forum.errorReplyPayment). When the parent omits accountId, an unpaid postMessage is attempted only for a reply that has text and an empty amount, and a payment 403 starts a 1-sat invoice. Fetch failure sets the error flag without clearing an already-posted list; the board still shows Try again. A failed silent refresh with an existing list does not set the error flag. A late GET merges locally posted rows that the response does not yet contain; a POST whose id is already in the list is not prepended again. An empty or whitespace-only pay amount requests 21 sats and does not fill payDraft. Invoice 400 author's-wallet copy maps to authorWallet; a missing or deleted note (NoteDeletedError, HTTP 404) maps to deleted on the pay sheet and on a paid reply; a 404 on the platform compose-target invoice stays request; other invoice failures stay request; rate limit stays rateLimit. Revokes photo and video blob URLs on unmount. May POST /me/forum-laws-dismissed. After a successful top-level post or reply, writes hasPosted: true on the session account only when the session token is unchanged and an account is still present (no persist-flag POST). On shops, passes shopComposer so the board mounts ShopAddWizard, shopPlaceEdit / onShopPlaceUpdated so a saved or cleared pin updates that row, and shopAccountEdit / onShopAccountUpdated so a saved or cleared shop account updates that row. For a moderator on every feed, including the living room, passes shopNoteEdit / onShopNoteUpdated. Passes lawsVisible / onDismissLaws, mode / onModeChange, nearEndRef, unpaidNewCount, refreshing / onRefresh, newPostsAvailable / onShowNewPosts, moderatorAppointedAvailable / onShowModeratorAppointed, and rateDay to ForumBoard. Stamps last visit on unpaid; mode is not persisted. Does not pass Error.message to the board. A paid reaction replaces the reply composer with ForumReplyPayPage and the typed sentence is the preview; the draft and amount stay until payment is observed, then both clear together with the preview; Close clears the preview and leaves the draft and amount in the composer. Gift-on-reply and composer-hosted sheets stay as they are.
• Used by: WelcomeScreen, ShopsScreen.

• Purpose: True when the account has a non-null display name that is non-empty after trim.
• Inputs: account.
• Returns / side effects: Boolean. No side effects.
• Used by: nextOnboardingPath, NameForm.

• Purpose: True when the account has a non-null Wallet of Satoshi address that is non-empty after trim.
• Inputs: account.
• Returns / side effects: Boolean. No side effects.
• Used by: nextOnboardingPath, LightningAddressForm.

• Purpose: True when the account has a non-null rulesAgreedAt timestamp (epoch ms of first living-room rules agreement).
• Inputs: account.
• Returns / side effects: Boolean. No side effects.
• Used by: UI that still checks agreement state (overlays, payable); wizard order uses account.setup only.

• Purpose: Picks /setup/name, /setup/username, /setup/address, /setup/rules, or /welcome from account.setup. setup === 'wallet' maps to name, username, lightning-address, rules, or /welcome from the other fields; it does not map to /wallet. Other values stay a 1:1 map (skips advance setup without clearing missing). Username still cannot be skipped.
• Inputs: account with required setup and missing.
• Returns / side effects: Path string. No side effects.
• Used by: OnboardingGate.

• Purpose: Skips the current onboarding name or Lightning Address step without filling the field.
• Inputs: Bearer session and step (name | lightning-address).
• Returns / side effects: Updated Account from POST /me/setup/skip; callers merge setup and missing into the auth store.
• Used by: NameForm and LightningAddressForm onboarding Skip buttons.

• Purpose: Loads a signed-in member profile by account id.
• Inputs: Bearer session and accountId.
• Returns / side effects: Validated MemberProfile, including postCount and replyCount, or null on 401/404. Throws MissingRequirementsError on 409. Hits /forum/members/:id.
• Used by: MemberProfileLoader.

• Purpose: Loads a member's top-level forum posts with GET /forum/members/:id/posts.
• Inputs: Bearer session and accountId.
• Returns / side effects: Parses forumListSchema and returns the messages newest-first, capped by the api at 200. A 401/404 uses the same visitor-facing message-list failure as fetchMessages; a 409 missing_requirements throws MissingRequirementsError as in fetchMember / fetchMessages.
• Used by: MemberProfileScreen.

• Purpose: Loads a member's forum replies with GET /forum/members/:id/replies.
• Inputs: Bearer session and accountId.
• Returns / side effects: Parses forumListSchema and returns the messages newest-first, capped by the api at 200; reply messages may be payable when the author has a published event and a Lightning Address, and may include parentId. A 401/404 uses the same visitor-facing message-list failure as fetchMessages; a 409 missing_requirements throws MissingRequirementsError as in fetchMember / fetchMessages.
• Used by: MemberProfileScreen.

• Purpose: Parses a 409 { error: 'missing_requirements', missing: [...] } body.
• Inputs: Unknown JSON body.
• Returns / side effects: MissingRequirementsError or null.
• Used by: fetchMessages, postMessage, postMessageVideo, postContact, fetchMember, fetchMemberPosts, fetchMemberReplies.

• Purpose: Typed error for api 409 missing name/rules (or lightning-address) requirements.
• Inputs: missing array from the api body.
• Returns / side effects: Error instance with missing field; not shown as a generic toast.
• Used by: Forum and contact loaders (open RequirementsOverlay) and member fetch.

• Purpose: Typed error for api 403 when the visitor signed in with an account whose session is refused.
• Inputs: None; message is the exact api English string.
• Returns / side effects: Error instance named WrongAccountError. Callers clear the session and show login.wrongAccount.
• Used by: fetchMe, finishPasskeyAuthentication, finishPasskeyRegistration, useHydrateSession, usePasskeyLogin.

• Purpose: Typed error when a forum reply or a payment invoice gets HTTP 404 because that note is missing or was deleted.
• Inputs: None. The message is exactly This note was deleted.
• Returns / side effects: Error instance named NoteDeletedError. Reply and pay-sheet callers show forum.errorNoteDeleted instead of the generic send error. A 404 on the platform compose-target invoice stays the generic request error.
• Used by: postMessage, postMessageInvoice, ForumLoader, PublicMessageThread, MemberProfileScreen.

• Purpose: Detects a wrong-account rejection (WrongAccountError or an Error whose message is exactly WRONG_ACCOUNT_ERROR).
• Inputs: error unknown.
• Returns / side effects: true for that instance or exact message; false otherwise.
• Used by: useHydrateSession, usePasskeyLogin.

• Purpose: Typed error for api 400 when authenticate finish rejects a credential the server does not store (Unknown credential).
• Inputs: None; message is the exact api English string.
• Returns / side effects: Error instance named UnknownCredentialError. usePasskeyLogin may signal the credential unknown and sets status unknown. LoginCard shows the unknown login card. ViewProfileClaim shows view.claimError and Try again calls authenticate(), never register.
• Used by: finishPasskeyAuthentication, usePasskeyLogin.

• Purpose: Detects an unknown-credential rejection (UnknownCredentialError or an Error whose message is exactly UNKNOWN_CREDENTIAL_ERROR).
• Inputs: error unknown.
• Returns / side effects: true for that instance or exact message; false otherwise.
• Used by: usePasskeyLogin.

• Purpose: Picks the next field to collect before a forum post (rules, then name, then username, then lightning-address).
• Inputs: missing array from the account or a 409 body.
• Returns / side effects: 'rules', 'name', 'username', 'lightning-address', or null. No side effects.
• Used by: ForumLoader, MemberProfileScreen, RequirementsOverlay flow.

• Purpose: Picks the next field to collect before a contact send (rules before name before username). Lightning-address gaps return null — contact does not require a Wallet of Satoshi address.
• Inputs: missing array from the account or a 409 body.
• Returns / side effects: 'rules', 'name', 'username', or null. No side effects.
• Used by: ContactLoader, RequirementsOverlay flow.

• Purpose: Modal to add a missing name (NameForm profile), username (UsernameForm), Wallet of Satoshi address (LightningAddressForm profile), or agree to rules before retrying a post. No Skip.
• Inputs: requirement (name | username | rules | lightning-address), onDismiss, onSatisfied.
• Returns / side effects: Dialog UI; merges account fields on success then calls onSatisfied. Title/aria-label from requirements.nameTitle, requirements.usernameTitle, requirements.rulesTitle, or requirements.addressTitle.
• Used by: ForumLoader, ContactLoader, MemberProfileScreen.

• Purpose: Modal that tells a signed-in member whose onboarding is complete (setup === null) and who has not posted (hasPosted === false) to introduce themselves in the forum. Close (X) dismisses this mount only. Primary CTA Write an introduction is a Button that dismisses, focuses the welcome composer (requestForumCompose / FORUM_COMPOSE_EVENT), and router.push('/welcome') only when the path is not already /welcome. No Skip-forever. Hidden when hasPosted is true or omitted (older api) and while setup is not null.
• Inputs: onDismiss.
• Returns / side effects: Dialog UI (role="dialog" aria-modal="true", fixed inset card z-50). Title/aria-label from introduce.title; body introduce.body; CTA introduce.cta as catalog Button type="button" size="lg"; close introduce.close. Does not write forumLawsDismissed or any account field.
• Used by: SignedInChrome.

• Purpose: Client loader for /members/[accountId]: UUID check, fetchMember, then fetchMemberActivity even if the Lightning Address is blank. It does not prefetch post/reply feeds; postCount and replyCount arrive with the profile JSON.
• Inputs: Route accountId; session from auth store.
• Returns / side effects: Loading / missing (view.missing) / error+retry / MemberProfileScreen. fetchMember 409 missing_requirements → /setup/rules. fetchMemberActivity 409 missing_requirements → /setup/rules. Any other activity error (other than MissingRequirementsError) keeps the card and the chart shows profile.chartError. MissingRequirementsError still goes to /setup/rules.
• Used by: MemberProfilePage.

• Purpose: Signed-in member identity card (chart from given and received activity, About me inside the card not as a forum post (Translate, Languages icon, when profileMessage.id is set), name, location, public [email protected] (profile.giftsHeading), role pill, optional funding-program icon-only button (pressing it reveals that one sentence; that result is the separate screenshot state funding-program-open) when fundingReviewedAt is a number, copy-profile-link, and post/reaction count toggles) plus stacked ForumBoard activity feeds loaded on demand. Location is read-only (location.unset when empty). Public AboutMeSection (name={profile.name}) shows filled text and/or photo, or omits the heading when neither. A labeled Message Button (profile.message) with a decorative Mail icon sits on the card when another member has a profileMessage — not on a post. Staff Trust Chain actions sit behind the closed Moderator functions disclosure when the viewer is a moderator and the subject is someone else. Clicking a count opens its feed below the card; clicking it again collapses it. There is no separately pinned profile-note ForumBoard; the posts feed lists that note when present. A feed shorter than its profile count gets a muted profile.activityLatest truncation line. Posts show React and do not show Send Bitcoin; a payable reply card in the replies feed shows Gift. Nested Gift Continue looks up sats on the visible feed only (reactions-feed cards when activity is replies; expanded-thread replies otherwise). Collapsing or switching Posts/Reactions cancels a Gift whose target is in the expanded thread or the reactions feed; a parent composer invoice stays. Expanding a reply with parentId navigates to /messages/{parentId}. Verified members may POST /messages unpaid only when there is text and the amount is empty; empty text and an empty amount invoices 21 sats even for verified; everyone else invoices ≥ 1 sat with optional text; typed 0 is always billed as 1 sat even for exempt. When a note omits accountId, a text reply with an empty amount tries unpaid POST /messages; a payment 403 starts a 1-sat compose invoice to 21.gifts on the composer slot (payHost: composer, payMessageId = compose-target note). Extra gifts and Gift-open stay on the card (payHost: card). Loads visible inline photos for posts and replies feeds via fetchMessagePhoto blob URLs, same as the home forum top-level cards, retrying a transient fetch once, leaving the row text-only after a second failure, and revoking object URLs on unmount. Blob URLs may also be fetched for expanded thread replies, but ForumBoard does not paint photos on nested replies. Loads GET /gifts/stats into rateDay via latestRateDay (failure leaves null) and passes it to every ForumBoard so unsent previews can use the latest rate; feed ₿ amounts show optional preferred-fiat · from the amount stored when the payment was made (a stored string as-is, a null or missing field on a passed stored object uses the gift-day rate) (no FiatPicker on the chart or the feed; member profiles are always signed-in). Uses nextPostRequirement so a missing name, username, Wallet of Satoshi address, or rules agreement opens RequirementsOverlay (no Skip) before a reply retries. When a username is set, a centered QrCode (label profile.giftsQr) under the address encodes openCryptoPayQrValue (https://<domain>/pl/?lightning= plus the uppercase LNURL of https://<domain>/.well-known/lnurlp/<local>), including on a smartphone. A missing username shows no QR. When a username is set, a labeled Shop sticker Button under the QR opens ShopStickerOverlay with the same openCryptoPayQrValue and the public handle, including on a smartphone; Close and Escape unmount it.
• Inputs: MemberProfile (includes aboutMe, aboutMeHasPhoto, and location) plus received and donated series; optional factsOnly (default false); optional activityFailed (default false), passed to the chart as failed; session/account from the auth store. Public AboutMeSection hasPhoto from aboutMeHasPhoto / profileMessage.hasPhoto with loadPhoto (fetchMessagePhoto).
• Returns / side effects: React tree with About me, copy-profile-link, optional Message, staff Trust Chain actions, and a read-only location row on the card; lazily fetches the selected member posts or replies; fetches GET /gifts/stats into rateDay; fetches photos for displayed hasPhoto cards into blob URLs via fetchMessagePhoto and revokes them on unmount; may POST invoice/conversation/replies and navigate to /messages?c= or a reply's /messages/{parentId}. When activityFailed is true and the series is empty, profile.chartError. factsOnly still has no chart. factsOnly returns only the role pill, the funding-program icon, the gifts address, QR, Shop sticker, count buttons, the activity feed, and RequirementsOverlay — no heading, chart, About me, name, location, Message, or staff block. ProfileScreen uses that mode so the owner sees the same public facts.
• Used by: MemberProfileLoader, ProfileScreen (factsOnly).