Skip to content

feat(setup): country stickers on the Residence step (TASK-24899) - #4114

Merged
0xkkonrad merged 12 commits into
devfrom
feat/residence-easter-eggs-24899
Nov 16, 2026
Merged

0xkkonrad merged 12 commits into
devfrom
feat/residence-easter-eggs-24899

Conversation

@0xkkonrad

@0xkkonrad 0xkkonrad commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The sign-up Residence step showed a generic loop. Konrad approved a country easter egg instead. The approved mock is mono _temp/residence-easter-eggs/picker/template.html; the doc is mono engineering/ui/signup-hero-loops.md.

  • The hero shows the approved mascot pose waving-hello.
  • When the residence country is one of 20 sticker countries, the mascot switches to cheering, the country's three stickers are slapped on 170 ms apart, and five landing-page stars and sparkles pop in and twinkle. The stickers keep a slow idle wobble.
  • Any other country keeps the waving mascot alone.
  • The compare view and every other step are unchanged.

Task

TASK-24899 — https://app.notion.com/p/41783811757981c3b815c24ea4737d66

How it works

  • ResidenceHero.tsx reads residenceCountry from the setup flow context. The celebration never starts in the first 2 s after the hero first mounts (RESIDENCE_WAVE_MS). A country prefilled from geo therefore gets the wave first.
  • The wave happens once per sign-up. The compare view and Back unmount the hero; the flow provider remembers that the wave has run (residenceWaveDone), and a hero that returns with a country celebrates at once.
  • The mascot keeps waving until the cheering pose has loaded, with no time limit and under reduced motion too, so it never blanks. The stickers wait for the pose and their three files, 1.5 s at most (RESIDENCE_STICKER_LOAD_MS). They are plain img elements with the preloaded URL, so each file is fetched once; a sticker whose file fails is left out and the rest carry on.
  • A country picked by hand also waits 400 ms (RESIDENCE_PICK_DELAY_MS), because the picker drawer is still closing over the hero.
  • The sticker layer is keyed by country. Another sticker country remounts it, so the slap replays with the new stickers. A non-sticker country removes it and the mascot waves again.
  • Both poses are drawn on one shared canvas box, as in the mock, so the mascot keeps its size and ground line when the pose changes. PeanutMascot has a new optional prop fit="canvas" for this; the default (fit="art") is unchanged for every other call site.
  • The picture is laid out in a box centred in the hero and at most 1.05 times as tall as wide. On a phone this box is the hero. On a tall desktop column the stickers stay around the mascot.
  • The sequence is CSS only (.residence-* in globals.css): one animation-delay per element, slap then idle in one animation list. Motion values are the ones in the approved mock. The last sparkle (bottom left) is mirrored with scaleX(-1).
  • prefers-reduced-motion: reduce: no wave wait, stickers and decorations appear at once and stay still.
  • Stickers are 320 px webp files in public/residence-stickers/ (60 files, 1.09 MB in total, 18 kB on average). They are fetched only when their country is shown and are not in the JS bundle. residence-stickers.consts.ts maps iso2 to its three files. next.config.js gives the folder the same Cache-Control rule as /flags (UNHASHED_STATIC_CACHE_CONTROL: one day, stale-while-revalidate one week).
  • The cheering chunk is fetched only for a sticker country.
  • Stickers and decorations are decorative: alt="", aria-hidden, pointer-events: none.
  • No art is drawn in code. Stickers are the approved generated PNGs; decorations are the existing star.svg and sparkle.svg, unmodified; the mascot Lottie files are untouched.
  • PeanutMascot frame clock: the counter now wraps with modulo. A swap from a 53-frame pose to a 22-frame one could ask Lottie for a frame past the end for one tick.
  • src/assets/onboarding/residence.json and its loader entry are removed, because nothing uses them now.

Sizes

Mascot canvas height = hero height minus 3 rem (the top bar), at most 80% of the hero width. Sticker width = 25% of the hero width, at most 40% of the canvas height and 11 rem. The mock has canvas 79% of its hero and sticker 0.31 of the canvas; its hero is about square, the real one is wider than tall.

Viewport Hero Canvas / hero height Drawn figure, wave → cheer Sticker Sticker / canvas
375×667 375×267 219 px, 82% 168 → 180 px 88 px 0.40
390×844 390×338 290 px, 86% 220 → 237 px 98 px 0.34
430×932 430×373 325 px, 87% 248 → 266 px 108 px 0.33
320×568 320×193 145 px, 75% 110 → 122 px 58 px 0.40
375×560 375×224 176 px, 79% 134 → 144 px 70 px 0.40

The drawn figure is the union of the painted SVG paths in the frame of the screenshot, so it moves a few pixels with the frame.

Assumptions

  • The trigger is the residence country, not the nationality.
  • The 2 s wave is measured from the first hero mount, not from the geo answer. A slow geo answer shortens the wave.
  • A country that arrives after the wave and differs from the country at mount counts as picked by hand.
  • Sticker positions follow the mock's p-around placement, mapped onto the real hero box. The first two stickers sit below the top bar. The fourth decoration sits left of the third sticker, because the real hero is too short for the mock's gap between the two right stickers.
  • The optional phone "thud" shake from the mock is not built.
  • EGG2_US_MAILBOX.png exists in the source folder but is not in the approved order file, so it is not shipped.

Risks / breaking changes

  • No API change, no backend change, no new dependency.
  • 1.09 MB of new static files in public/. On the web each visitor fetches at most three (about 55 kB), and only in a sticker country.
  • The native build copies public/ wholesale, so all 60 files (1.09 MB) ship in every APK, IPA and OTA bundle.
  • PeanutMascot is shared. Two changes touch it: the modulo wrap (same result for a pose that never swaps) and the opt-in fit prop (default unchanged).
  • globals.css grows by the .residence-* rules.
  • Reduced motion with a geo prefill: the country reaches the hero one effect after the mount (Residence.tsx commits the geo suggestion in an effect), so the waving state can show for a frame before the still set. A hero that mounts with the country already in the context draws the final state at once.

QA

No backend is needed. Build with NEXT_PUBLIC_VERCEL_ENV=preview, run next start, open /dev/surfaces?s=03-a-residence-select&__fixture=profile-edit at 375×667.

  • Geo prefill of a sticker country: the mascot waves for 2 s, then cheers with stickers, at the same size.
  • Pick Brazil by hand: new stickers slap on as the picker closes. Pick Japan: the mascot waves, no stickers.
  • Open the compare view or go Back and return: no second wave.
  • The back button, the language switcher, both country pickers and Continue stay tappable.
  • Reduced motion: all art appears at once and stays still.

Unit tests: residence-stickers.consts.test.ts (20 countries, three files each, every file on disk, no unused file), ResidenceHero.test.tsx (23 tests: pick just before the wave ends, preloaded URL equals rendered src, failed sticker left out, pose held past the fallback, wave delay, non-sticker country, swap, return to wave, reduced motion, load gate and its 1.5 s limit, failed fetch, pick delay, country arriving during the wave, timer cleanup on unmount, remount after the wave, cheering fetched only for a sticker country, decorative markup, decoration order and mirror) and PeanutMascot.test.tsx (canvas fit).

Checks on the current head cd01f6329, run on the boat.dev sandbox on a copy of the working tree that was committed unchanged as this head:

  • npm run typecheck: exit 0.
  • npx jest src/components/Setup src/features/setup src/components/Global/PeanutMascot 'src/app/\(setup\)': 59 suites, 1,200 tests, all passed.
  • npm run build (preview build): exit 0.
  • Full npm test was not rerun on this head. Its last full run was on the first version of this branch, before the rebase and before the QA fixes: 1,436 of 1,437 suites passed; the one failure was scripts/__tests__/capgo-release-guard.test.js, which runs git and the sandbox copy is not a git repository. CI runs the full suite on this head.

Screenshots

Real step through the dev surface harness with fixture mode, headless Chromium, production build. The yellow "Fixture" banner belongs to the harness. The top inset is forced by setting --safe-top: 59px on :root.

Argentina, during the first 2 s
Argentina, prefilled, after the wave
United States
Japan (no stickers)
Reduced motion
Changed by hand to Brazil
390×844, wave
390×844
430×932
390×844 with a 59 px top inset
Small 320×568, wave
Small 320×568
Compact 375×560, wave
Compact 375×560
375×667 with a 59 px top inset
Country picker open

The assets branch pr-assets-4114 is deleted after the merge.

Konrad approved three stickers per country for the sign-up Residence
step (TASK-24899). They ship as 320 px webp files in public/ so they
load only when a sticker country is shown and stay out of the JS bundle.
The typed map is the one place that names a country's three files, and
the approved-assets page lists them so the inventory stays complete.
…idence step

The Residence step showed a generic loop. Konrad approved a country
easter egg instead (TASK-24899): the mascot waves, and when the residence
country is one of the 20 sticker countries it cheers while that country's
three stickers are slapped on and landing-page stars and sparkles twinkle.

The celebration never starts in the first 2 s after the hero arrives, so
a country prefilled from geo still gets the wave; a country picked by
hand celebrates at once. The sequence is CSS only (delays per element),
so reduced motion shows everything at once and nothing can block the
country pickers. The residence loop file has no user left and is removed.
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
peanut-wallet Ready Ready Preview Nov 16, 2026 10:30am UTC

Request Review

@notion-workspace

Copy link
Copy Markdown

The ds-lint ratchet counts inline styles and does not let the count rise.
The per-element delay index now comes from the data attribute rules that
already place each sticker and decoration.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

🧪 UI test report — ✅ all green

Suites

  • ✅ unit: 21811 ran, 0 failed, 0 skipped, 8.6m

📊 Coverage (unit)

metric %
statements 88.6%
branches 81.9%
functions 82.8%
lines 90.1%
⏱ 10 slowest test cases
time test
🐢 24.5s scripts/__tests__/screens-adapter.test.js › runs the existing synthetic screen adapter Node acceptance suite
🐢 13.5s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › keeps unavailable Argentina searchable and opens its residence explanation with Enter
🐢 13.1s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › keeps unavailable Argentina searchable and opens its residence explanation with pointer
🐢 12.4s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › keeps unavailable Argentina searchable and opens its residence explanation with Space
🐢 9.0s src/app/(mobile-ui)/qr-pay/__tests__/qr-pay-states.test.tsx › Network failure keeps loading while retries remain, then shows the generic error
🐢 7.2s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › preserves ordinary Argentina selection for residence null
🐢 6.4s scripts/__tests__/signup-attribution-paths.test.ts › includes newly published articles and locale fallbacks without editing the manifest
🐢 6.2s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › preserves ordinary Argentina selection for residence AR
🐢 5.4s scripts/__tests__/indexable-urls.test.ts › excludes missing locale files, drafts, redirects, and retired pages from crawl and submission lists
4.1s src/features/payments/flows/qr-pay/__tests__/usePixPayment.test.tsx › reads a paid payment once more when its reward is not issued yet, then stops (API-CONTRACT-M5 §3)
📍 Inline annotations are in the **Unit test report** check above. Coverage artifact: `coverage-unit`. Generated by `.github/workflows/tests.yml`.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Code-analysis diff

Painscore total: 11090.26 → 11102.19 (+11.93)
Findings: +8 net (+57 new, -49 resolved)

🆕 New findings (57)

  • critical complexity — src/app/(setup)/setup/page.tsx — CC 252, MI 55.98, SLOC 727
  • critical complexity — src/components/Setup/components/SetupWrapper.tsx — CC 109, MI 62.66, SLOC 206
  • high hotspot — src/components/Setup/components/SetupWrapper.tsx — 89 commits, +1758/-1448 lines since 6 months ago
  • high hotspot — src/app/(setup)/setup/page.tsx — 77 commits, +1425/-754 lines since 6 months ago
  • high complexity — src/components/Setup/components/OnboardingAnimation.tsx — CC 46, MI 64.07, SLOC 168
  • high complexity — src/components/Global/PeanutMascot/index.tsx — CC 40, MI 63.44, SLOC 132
  • high complexity — src/components/Setup/components/ResidenceHero.tsx — CC 40, MI 66.45, SLOC 119
  • high method-complexity — src/components/Setup/components/SetupWrapper.tsx:383 — SetupWrapper CC 37 SLOC 46
  • high complexity — src/components/Setup/Setup.consts.tsx — CC 2, MI 44.65, SLOC 93
  • medium high-mdd — src/app/(setup)/setup/page.tsx:81 — SetupPageContent: MDD 195.9 (uses across many lines from declarations)
  • medium high-mdd — src/components/Setup/components/SetupWrapper.tsx:383 — SetupWrapper: MDD 67.5 (uses across many lines from declarations)
  • medium high-mdd — src/components/Setup/components/SetupWrapper.tsx:227 — ImageSection: MDD 64.5 (uses across many lines from declarations)
  • medium high-mdd — src/features/setup/SetupFlowContext.tsx:118 — SetupFlowProvider: MDD 63.0 (uses across many lines from declarations)
  • medium high-mdd — src/components/Setup/components/OnboardingAnimation.tsx:30 — OnboardingAnimation: MDD 41.3 (uses across many lines from declarations)
  • medium high-mdd — src/components/Setup/components/OnboardingAnimation.tsx:39 — : MDD 38.8 (uses across many lines from declarations)
  • medium high-dlt — src/app/(setup)/setup/page.tsx:563 — : DLT 32 (calls 32 distinct functions — high context load)
  • medium high-mdd — src/components/Setup/components/SetupWrapper.tsx:157 — Navigation: MDD 32.0 (uses across many lines from declarations)
  • medium method-complexity — src/app/(setup)/setup/page.tsx:563 — CC 29 SLOC 82
  • medium high-mdd — src/components/Setup/components/ResidenceHero.tsx:50 — ResidenceHero: MDD 27.7 (uses across many lines from declarations)
  • medium high-mdd — src/app/(setup)/setup/page.tsx:715 — : MDD 26.7 (uses across many lines from declarations)

…and 37 more.

✅ Resolved (49)

  • src/app/(setup)/setup/page.tsx — CC 249, MI 55.87, SLOC 722
  • src/components/Setup/components/SetupWrapper.tsx — CC 106, MI 62.77, SLOC 205
  • src/components/Setup/components/SetupWrapper.tsx — 88 commits, +1746/-1444 lines since 6 months ago
  • src/app/(setup)/setup/page.tsx — 76 commits, +1421/-754 lines since 6 months ago
  • src/components/Setup/components/OnboardingAnimation.tsx — CC 47, MI 64.34, SLOC 172
  • src/components/Global/PeanutMascot/index.tsx — CC 38, MI 63.63, SLOC 131
  • src/components/Setup/components/SetupWrapper.tsx:375 — SetupWrapper CC 37 SLOC 46
  • src/components/Setup/Setup.consts.tsx — CC 2, MI 44.62, SLOC 93
  • src/app/(setup)/setup/page.tsx:81 — SetupPageContent: MDD 197.1 (uses across many lines from declarations)
  • src/features/setup/SetupFlowContext.tsx:103 — SetupFlowProvider: MDD 71.5 (uses across many lines from declarations)
  • src/components/Setup/components/SetupWrapper.tsx:375 — SetupWrapper: MDD 67.5 (uses across many lines from declarations)
  • src/components/Setup/components/SetupWrapper.tsx:226 — ImageSection: MDD 62.6 (uses across many lines from declarations)
  • src/components/Setup/components/OnboardingAnimation.tsx:31 — OnboardingAnimation: MDD 41.3 (uses across many lines from declarations)
  • src/components/Setup/components/OnboardingAnimation.tsx:40 — : MDD 38.8 (uses across many lines from declarations)
  • src/app/(setup)/setup/page.tsx:559 — : DLT 32 (calls 32 distinct functions — high context load)
  • src/components/Setup/components/SetupWrapper.tsx:156 — Navigation: MDD 32.0 (uses across many lines from declarations)
  • src/app/(setup)/setup/page.tsx:559 — CC 29 SLOC 82
  • src/app/(setup)/setup/page.tsx:711 — : MDD 26.7 (uses across many lines from declarations)
  • src/app/(setup)/setup/page.tsx:559 — : MDD 24.3 (uses across many lines from declarations)
  • src/app/(setup)/setup/page.tsx:714 — determineInitialStep: MDD 22.0 (uses across many lines from declarations)

…and 29 more.

📈 Painscore deltas (top movers)

File Before After Δ
src/components/Setup/components/ResidenceHero.tsx 0.0 7.3 +7.3
src/components/Setup/components/residence-stickers.consts.ts 0.0 3.4 +3.4

…fset

The onboarding shell already reserves the top inset above the hero, so
inside the hero the top bar ends 3.5rem down. Adding the inset again
pushed the two top stickers 59px too low on notched phones and shrank
them on compact screens.
The compare view and Back unmount the hero, so the 2 s wave replayed on
every return. The flow provider now remembers that the wave has run and
a remount with a country celebrates at once.

The sticker layer started its slap before the three files arrived, so a
slow connection animated empty boxes. The layer now waits for the files,
with a 1.5 s limit so a failed fetch never blocks the celebration.

The cheering pose is fetched only for a sticker country; other visitors
never need it.
The frame counter survives a pose change. Going from a 53-frame pose to
a 22-frame one left it past the end after a single subtraction, so one
held tick asked Lottie for a frame that does not exist. Poses that never
swap behave as before.
…atic files

Without a rule they fall back to the default header and are refetched on
each sign-up visit.
…work

Fitting each pose's artwork to the box makes every pose look the same
size in isolation, but two poses swapped in one box then change scale:
the cheering artwork includes the jump, so the figure came out a fifth
smaller than the waving one. With fit="canvas" both poses keep the
rig's own scale and ground line. The default is unchanged.
Visual QA against the approved mock:

- Both poses now share one canvas box, as in the mock, sized to the hero
  under the top bar. The mascot no longer shrinks or jumps when it
  starts to cheer, and stickers are capped at 40% of its canvas so it
  dominates on short phones too.
- The picture is laid out in a box centred on the mascot and never much
  taller than wide, so on a tall desktop column the stickers stay around
  the peanut instead of at the column's ends.
- The celebration waits for the cheering pose as well as the stickers,
  so the mascot never blanks, and a country picked by hand waits 400 ms
  for the picker to close so the first slap is seen.
- A hero that mounts already celebrating draws its final state at once.
The gate preloaded /residence-stickers/x.webp while next/image rendered
x.webp?dpl=..., so every sticker was fetched twice and the gate never
warmed the image on screen. The stickers are now plain img elements with
the preloaded URL: one fetch each.

A sticker whose file fails is left out instead of showing a broken-image
box; the cheer and the other stickers carry on.

The mascot now leaves the wave only once the cheering chunk has loaded,
with no time limit and under reduced motion too. The 1.5 s fallback
releases the stickers only, so a slow chunk no longer blanks the mascot.
The residence hero swaps waving-hello for cheering on a running clock. A
single subtraction left the carried frame past the shorter loop's end;
this pins the modulo.

@chip-peanut-bot chip-peanut-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chip review — no blocking findings — this is not an approval

Two minor findings: early sticker animation after a country pick during the opening wave, and stale Residence animation guidance.

Findings

  • MINOR · src/components/Setup/components/ResidenceHero.tsx:91 · Country picks near wave end can animate behind the closing picker
    Pick a sticker country about 1.9 seconds after the Residence hero mounts, with the pose and sticker files cached. residenceWaveDone.current is still false here, so the 400 ms picker hold is skipped; the wave ends at 2 seconds and the sticker slap starts 120 ms later, before the picker has finished closing. Preserve the 400 ms delay from a manual selection independently of the remaining wave time (celebrate after both gates), and cover a pick near the wave boundary.

  • MINOR · src/components/Setup/Setup.consts.tsx:41 · Residence animation guide still points to the deleted loop
    The mono engineering/ui/signup-hero-loops.md guide still lists residence.json as the Residence screen asset and instructs maintainers to replace that file to change its loop. This step now renders ResidenceHero and the JSON is deleted, so that instruction cannot work. Update the guide to describe the new hero and sticker asset workflow alongside this change.

Checked clean

  • Exact head and base SHA, PR metadata, and changed-code diff verified; no issue or review comments fetched.
  • Residence preload failure, slow pose, reduced motion, country swaps, and shared mascot pose sizing/clock reviewed against implementation and tests.
  • Design rulebook and signup hero guide checked; no security, privacy, or money surface in this diff.
  • CI at this head was still in progress at the latest check (including unit and typecheck); completed checks observed were successful or skipped.

Security review: did not run — this change has no security, privacy or money surface, so it was not asked. This review is one reviewer short.

Third opinion by claude-opus: 0 finding(s), marked with the model name. It answers only product truth, missing tests and the cross-repo contract, so treat its findings as advice.

Copy check by claude-haiku-5-5: 0 finding(s), titled "Copy now wrong". Every quoted passage was checked against the file.

Exact head: cd5bb7218b6a · Context: repo, design, engineering · Took 3m (queued 2m)

Comment thread src/components/Setup/Setup.consts.tsx Resolved
The 400 ms picker hold only applied after the wave, so a country picked
just before the wave ended slapped its stickers behind the closing picker
(Chip review). Any country that arrives after the mount now gets the hold;
for the geo prefill it runs out inside the wave and changes nothing.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

English

Open screen library dashboard

After merge: aa9dbf9 → 4c21680. Reviewable capture in English; newly registered states are marked in the report.

Before was captured with the base branch's own synthetic API because this PR changes it; differences can include synthetic-data changes.

@0xkkonrad
0xkkonrad merged commit 4c21680 into dev Nov 16, 2026
48 of 50 checks passed

This branch was successfully deployed

1 active deployment
Preview — e5df8a1c Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant