From 818be1d5a014976cfbaf5fe0fe63e244abfe3a7e Mon Sep 17 00:00:00 2001
From: sasha gudulin <alexander@gudulin.com>
Date: Sun, 23 Aug 2026 16:52:06 +0200
Subject: [PATCH] portrait cleanup

---
 .../at/[actor]/[collection]/[rkey]/page.tsx   |  21 +-
 src/components/avatar-portrait.module.css     |   4 -
 src/components/avatar-portrait.tsx            |  11 +-
 src/components/player-card.module.css         |   4 +-
 src/components/player-card.tsx                |   3 +-
 src/components/player-grid.module.css         |  12 --
 src/components/player-grid.tsx                |  15 +-
 src/components/portrait-card.tsx              |  35 +---
 src/lib/avatar.ts                             | 190 +++++++++---------
 src/lib/player.ts                             |  48 ++---
 10 files changed, 132 insertions(+), 211 deletions(-)

diff --git a/src/app/at/[actor]/[collection]/[rkey]/page.tsx b/src/app/at/[actor]/[collection]/[rkey]/page.tsx
index add4ba0..de97aa8 100644
--- a/src/app/at/[actor]/[collection]/[rkey]/page.tsx
+++ b/src/app/at/[actor]/[collection]/[rkey]/page.tsx
@@ -26,7 +26,7 @@ import {
   normalizeActor,
   tidToDate,
 } from "@/lib/atproto/uri";
-import { avatarBlobUrl, buildDrawPlan, getAvatarCatalog } from "@/lib/avatar";
+import { avatarBlobUrl, buildDrawPlan } from "@/lib/avatar";
 import { BADGE_AWARD, isBadgeCollection, loadBadge } from "@/lib/badge";
 import { registerFolkYurei } from "@/lib/diffs-theme";
 import { breadcrumbList } from "@/lib/jsonld";
@@ -155,31 +155,24 @@ function parseTryOn(
   );
 }
 
-async function renderPortrait(
+function renderPortrait(
   value: Record<string, unknown>,
   tryOn: Record<string, string>,
   owner: { pds: string; did: string },
-): Promise<Portrait | null> {
+): Portrait {
   // A composited blob has nothing to layer onto, so an explicit `?try=` falls
-  // through to the catalog and renders a speculative portrait instead.
+  // through to the trait stack and renders a speculative portrait instead.
   const cid = blobCid(value.avatar);
   if (cid && Object.keys(tryOn).length === 0) {
     const url = avatarBlobUrl(value.avatar, owner);
     if (url) return { kind: "blob", url, cid };
   }
 
-  const resolved = await getAvatarCatalog();
-  if (!resolved) return null;
   // A blob's own keys (`ref`, `size`, `mimeType`) are not slot ids. Spreading
   // them would silently resolve every slot to its default and pass that off as
   // the user's avatar, so the blob contributes nothing to the draw plan.
   const stored = cid ? {} : ((value.avatar ?? {}) as Record<string, unknown>);
-  const layers = buildDrawPlan(
-    resolved.catalog,
-    { ...stored, ...tryOn },
-    { pds: resolved.pds, did: resolved.did },
-  );
-  return layers.length > 0 ? { kind: "traits", layers, stored } : null;
+  return { kind: "traits", layers: buildDrawPlan({ ...stored, ...tryOn }) };
 }
 
 export default async function RecordPage({
@@ -211,7 +204,7 @@ export default async function RecordPage({
     const tryOn = parseTryOn((await searchParams).try);
     const portrait =
       collection === "lol.folk.profile"
-        ? await renderPortrait(record.value, tryOn, {
+        ? renderPortrait(record.value, tryOn, {
             pds: identity.pds,
             did: identity.did,
           })
@@ -289,7 +282,7 @@ export default async function RecordPage({
         {portrait && (
           <>
             <SectionTitle>portrait</SectionTitle>
-            <PortraitCard portrait={portrait} tryOn={tryOn} />
+            <PortraitCard portrait={portrait} />
           </>
         )}
 
diff --git a/src/components/avatar-portrait.module.css b/src/components/avatar-portrait.module.css
index 4832991..c00fb52 100644
--- a/src/components/avatar-portrait.module.css
+++ b/src/components/avatar-portrait.module.css
@@ -30,7 +30,3 @@
   object-fit: cover;
   pointer-events: none;
 }
-
-.pixelated {
-  image-rendering: pixelated;
-}
diff --git a/src/components/avatar-portrait.tsx b/src/components/avatar-portrait.tsx
index 76c98ef..340295c 100644
--- a/src/components/avatar-portrait.tsx
+++ b/src/components/avatar-portrait.tsx
@@ -4,18 +4,11 @@ import styles from "./avatar-portrait.module.css";
 export function AvatarPortrait({
   layers,
   size = 160,
-  pixelated = true,
   shape = "rounded",
 }: {
   layers: Layer[];
   size?: number;
   shape?: "rounded" | "squircle";
-  /**
-   * Catalog trait art is stacked at its native size and upscaled, so it keeps
-   * nearest-neighbour sampling. A composited avatar blob is downscaled into the
-   * frame instead, where nearest-neighbour only adds aliasing.
-   */
-  pixelated?: boolean;
 }) {
   const background = layers.find((l) => l.kind === "color");
   const images = layers.filter((l) => l.kind === "image");
@@ -39,9 +32,7 @@ export function AvatarPortrait({
         // biome-ignore lint/performance/noImgElement: layers come from arbitrary PDS hosts
         <img
           key={`${layer.slot}-${layer.key}`}
-          className={
-            pixelated ? `${styles.layer} ${styles.pixelated}` : styles.layer
-          }
+          className={styles.layer}
           src={layer.url}
           alt=""
         />
diff --git a/src/components/player-card.module.css b/src/components/player-card.module.css
index 3160019..993b922 100644
--- a/src/components/player-card.module.css
+++ b/src/components/player-card.module.css
@@ -9,8 +9,8 @@
 
 /* Same footprint as the portrait, so a missing profile does not reflow. */
 .faceless {
-  width: 200px;
-  height: 200px;
+  width: 156px;
+  height: 156px;
   background: var(--raised);
   -webkit-mask-image: var(--squircle);
   mask-image: var(--squircle);
diff --git a/src/components/player-card.tsx b/src/components/player-card.tsx
index 116b26a..80e32a8 100644
--- a/src/components/player-card.tsx
+++ b/src/components/player-card.tsx
@@ -2,7 +2,7 @@ import type { Player, PlayerBadge } from "@/lib/player";
 import { AvatarPortrait } from "./avatar-portrait";
 import styles from "./player-card.module.css";
 
-const PORTRAIT_SIZE = 200;
+const PORTRAIT_SIZE = 156;
 const BADGE_SIZE = 56;
 
 /** A face and a name. Anything technical lives on the repo page instead. */
@@ -13,7 +13,6 @@ export function PlayerCard({ player }: { player: Player }) {
         <AvatarPortrait
           layers={player.portrait.layers}
           size={PORTRAIT_SIZE}
-          pixelated={player.portrait.pixelated}
           shape="squircle"
         />
       ) : (
diff --git a/src/components/player-grid.module.css b/src/components/player-grid.module.css
index 391ae07..6c7efc9 100644
--- a/src/components/player-grid.module.css
+++ b/src/components/player-grid.module.css
@@ -26,18 +26,6 @@
   border-color: var(--border-soft);
 }
 
-.faceless {
-  width: 84px;
-  height: 84px;
-  background: var(--raised);
-  -webkit-mask-image: var(--squircle);
-  mask-image: var(--squircle);
-  -webkit-mask-size: 100% 100%;
-  mask-size: 100% 100%;
-  -webkit-mask-repeat: no-repeat;
-  mask-repeat: no-repeat;
-}
-
 .name {
   margin-top: 0.6rem;
   font-size: 0.85rem;
diff --git a/src/components/player-grid.tsx b/src/components/player-grid.tsx
index e20597f..4ab7953 100644
--- a/src/components/player-grid.tsx
+++ b/src/components/player-grid.tsx
@@ -12,16 +12,11 @@ export function PlayerGrid({ players }: { players: PlayerSummary[] }) {
       {players.map((player) => (
         <li key={player.actor}>
           <Link className={styles.player} href={playerHref(player.actor)}>
-            {player.portrait ? (
-              <AvatarPortrait
-                layers={player.portrait.layers}
-                size={SIZE}
-                pixelated={player.portrait.pixelated}
-                shape="squircle"
-              />
-            ) : (
-              <div className={styles.faceless} aria-hidden="true" />
-            )}
+            <AvatarPortrait
+              layers={player.portrait.layers}
+              size={SIZE}
+              shape="squircle"
+            />
             <span className={styles.name}>{player.name}</span>
             {player.handle && (
               <span className={styles.handle}>@{player.handle}</span>
diff --git a/src/components/portrait-card.tsx b/src/components/portrait-card.tsx
index 4ac1d2a..051aa8d 100644
--- a/src/components/portrait-card.tsx
+++ b/src/components/portrait-card.tsx
@@ -3,23 +3,14 @@ import { AvatarPortrait } from "./avatar-portrait";
 import styles from "./portrait-card.module.css";
 import { Card } from "./ui/card";
 
-/**
- * Either the composited blob the repo stores, or a stack of catalog traits
- * resolved slot by slot. `stored` records which of those traits actually came
- * from the record, so the rest can be labelled as defaults.
- */
+const SIZE = 120;
+
+/** Either the composited blob the repo stores, or a stack of traits. */
 export type Portrait =
   | { kind: "blob"; url: string; cid: string }
-  | { kind: "traits"; layers: Layer[]; stored: Record<string, unknown> };
+  | { kind: "traits"; layers: Layer[] };
 
-export function PortraitCard({
-  portrait,
-  tryOn,
-}: {
-  portrait: Portrait;
-  /** Slots overridden through `?try=`, shown as such next to the layer. */
-  tryOn: Record<string, string>;
-}) {
+export function PortraitCard({ portrait }: { portrait: Portrait }) {
   return (
     <Card className={styles.card}>
       {portrait.kind === "blob" ? (
@@ -33,7 +24,7 @@ export function PortraitCard({
                 key: "blob",
               },
             ]}
-            pixelated={false}
+            size={SIZE}
             shape="squircle"
           />
           <div className={`${styles.meta} ${styles.cid}`}>
@@ -42,19 +33,7 @@ export function PortraitCard({
           </div>
         </>
       ) : (
-        <>
-          <AvatarPortrait layers={portrait.layers} shape="squircle" />
-          <div className={styles.meta}>
-            {portrait.layers.map((l) => (
-              <div key={`${l.slot}-${l.key}`}>
-                {l.slot} · {l.kind === "color" ? l.color : l.key}
-                {tryOn[l.slot] !== undefined
-                  ? " (try-on)"
-                  : portrait.stored[l.slot] === undefined && " (default)"}
-              </div>
-            ))}
-          </div>
-        </>
+        <AvatarPortrait layers={portrait.layers} size={SIZE} shape="squircle" />
       )}
     </Card>
   );
diff --git a/src/lib/avatar.ts b/src/lib/avatar.ts
index 9ea0417..5c63201 100644
--- a/src/lib/avatar.ts
+++ b/src/lib/avatar.ts
@@ -1,45 +1,80 @@
-import { cache } from "react";
-import { blobCid, blobUrl, getRecord } from "./atproto/repo";
-import { resolveActor } from "./atproto/resolve";
-import { LEXICON_AUTHORITY } from "./folk";
+import { blobCid, blobUrl } from "./atproto/repo";
 
-const CATALOG = "lol.folk.meta.avatar";
+const ART_BASE = "https://folk.lol/avatar";
 
-type BlobRef = {
-  $type: "blob";
-  ref: { $link: string };
-  mimeType: string;
-  size: number;
+export type Layer =
+  | { kind: "color"; color: string; slot: string; key: string }
+  | { kind: "image"; url: string; slot: string; key: string };
+
+/** Image slots, in the order they stack over the background. */
+type ImageSlot =
+  | "skin"
+  | "eyes"
+  | "hair"
+  | "lips"
+  | "shirt"
+  | "outerwear"
+  | "extra";
+
+const BACKGROUND_COLORS: Record<string, string> = {
+  "grass-green": "#a1e770",
+  red: "#ff6b55",
+  yellow: "#f7ce01",
+  pink: "#ffacc8",
+  "orange-dark": "#fe9347",
+  "blue-sky": "#00a8ff",
+  "blue-sky-night": "#5b87ff",
+  "orbs-light": "#a875cd",
+  "grey-arena-light": "#8eb4d6",
+  "dark-green": "#50bc65",
+  "egg-dark": "#ffd99e",
+  black: "#1b3937",
 };
 
-export type CatalogTrait = {
-  key: string;
-  image?: BlobRef;
-  src?: string;
-  color?: string;
-  label?: string;
+const keys = (prefix: string, count: number): string[] =>
+  Array.from(
+    { length: count },
+    (_, i) => `${prefix}_${String(i + 1).padStart(2, "0")}`,
+  );
+
+/** One entry per asset the game serves under `/avatar/<slot>`. */
+const TRAITS: Record<ImageSlot, string[]> = {
+  skin: keys("skin", 16),
+  eyes: keys("eyes", 22),
+  hair: keys("hair", 25),
+  lips: keys("lips", 22),
+  shirt: keys("shirt", 16),
+  outerwear: keys("jacket", 8),
+  extra: keys("items", 16),
 };
 
-export type CatalogSlot = {
-  id: string;
-  render: "color" | "image" | "fixed";
-  label?: string;
-  traits: CatalogTrait[];
+export const DEFAULT_AVATAR: Record<string, string> = {
+  background: "grass-green",
+  skin: "skin_01",
+  hair: "hair_04",
+  eyes: "eyes_01",
+  lips: "lips_01",
+  shirt: "shirt_01",
+  outerwear: "jacket_01",
+  extra: "items_01",
 };
 
-export type AvatarCatalog = { slots: CatalogSlot[]; updatedAt?: string };
+/** Drawn between the skin and everything above it. */
+const BASE_BODY = `${ART_BASE}/avatar.webp`;
 
-export type Layer =
-  | { kind: "color"; color: string; slot: string; key: string }
-  | { kind: "image"; url: string; slot: string; key: string };
+const ABOVE: ImageSlot[] = [
+  "eyes",
+  "hair",
+  "lips",
+  "shirt",
+  "outerwear",
+  "extra",
+];
 
 /**
  * Newer profiles store the avatar as a single pre-composited blob instead of a
- * map of catalog trait keys. Both shapes are live in the wild, so the shape of
- * `avatar` — not the record's age — decides which renderer applies.
- *
- * The blob lives in the *profile owner's* repo, unlike catalog trait art, which
- * is served from the lexicon authority. Passing the wrong pair yields a 404.
+ * map of trait keys. Both shapes are live in the wild, so the shape of `avatar`
+ * - not the record's age - decides which renderer applies.
  */
 export function avatarBlobUrl(
   avatar: unknown,
@@ -49,74 +84,39 @@ export function avatarBlobUrl(
   return cid ? blobUrl(owner.pds, owner.did, cid) : null;
 }
 
-/** The catalog as published by the game. No local copy: if it is unreachable, no portrait. */
-export const getAvatarCatalog = cache(
-  async (): Promise<{
-    catalog: AvatarCatalog;
-    pds: string;
-    did: string;
-  } | null> => {
-    try {
-      const authority = await resolveActor({
-        type: "handle",
-        handle: LEXICON_AUTHORITY,
-      });
-      const record = await getRecord(
-        authority.pds,
-        authority.did,
-        CATALOG,
-        "self",
-      );
-      return {
-        catalog: record.value as unknown as AvatarCatalog,
-        pds: authority.pds,
-        did: authority.did,
-      };
-    } catch {
-      return null;
-    }
-  },
-);
-
 /**
- * Resolve a profile's chosen trait keys against the catalog into an ordered list
- * of layers, bottom first. An absent or unknown key falls back to the slot's
- * first trait, so a profile with no avatar still renders the default portrait.
+ * Resolve chosen trait keys into an ordered list of layers, bottom first.
+ * Values come from arbitrary repos, so an absent or unknown key falls back to
+ * the default rather than pointing an `img` at a 404.
  */
-export function buildDrawPlan(
-  catalog: AvatarCatalog,
-  chosen: Record<string, unknown> | undefined,
-  ctx: { pds: string; did: string },
-): Layer[] {
-  const layers: Layer[] = [];
-
-  for (const slot of catalog.slots ?? []) {
-    const want =
-      typeof chosen?.[slot.id] === "string"
-        ? (chosen[slot.id] as string)
-        : undefined;
-    const trait =
-      slot.render === "fixed"
-        ? slot.traits[0]
-        : (slot.traits.find((t) => t.key === want) ?? slot.traits[0]);
-    if (!trait) continue;
+export function buildDrawPlan(chosen?: Record<string, unknown>): Layer[] {
+  const pick = (slot: ImageSlot): string => {
+    const want = chosen?.[slot];
+    return typeof want === "string" && TRAITS[slot].includes(want)
+      ? want
+      : (DEFAULT_AVATAR[slot] as string);
+  };
 
-    if (slot.render === "color") {
-      if (trait.color)
-        layers.push({
-          kind: "color",
-          color: trait.color,
-          slot: slot.id,
-          key: trait.key,
-        });
-      continue;
-    }
+  const layer = (slot: ImageSlot): Layer => {
+    const key = pick(slot);
+    return { kind: "image", url: `${ART_BASE}/${slot}/${key}.webp`, slot, key };
+  };
 
-    const url = trait.image
-      ? ctx.pds && blobUrl(ctx.pds, ctx.did, trait.image.ref.$link)
-      : trait.src;
-    if (url) layers.push({ kind: "image", url, slot: slot.id, key: trait.key });
-  }
+  const wantBackground = chosen?.background;
+  const background =
+    typeof wantBackground === "string" && BACKGROUND_COLORS[wantBackground]
+      ? wantBackground
+      : (DEFAULT_AVATAR.background as string);
 
-  return layers;
+  return [
+    {
+      kind: "color",
+      color: BACKGROUND_COLORS[background] as string,
+      slot: "background",
+      key: background,
+    },
+    layer("skin"),
+    { kind: "image", url: BASE_BODY, slot: "base", key: "avatar" },
+    ...ABOVE.map(layer),
+  ];
 }
diff --git a/src/lib/player.ts b/src/lib/player.ts
index 8ca6084..0fae455 100644
--- a/src/lib/player.ts
+++ b/src/lib/player.ts
@@ -6,12 +6,7 @@ import {
 } from "./atproto/cached";
 import { blobCid } from "./atproto/repo";
 import type { Identity } from "./atproto/resolve";
-import {
-  avatarBlobUrl,
-  buildDrawPlan,
-  getAvatarCatalog,
-  type Layer,
-} from "./avatar";
+import { avatarBlobUrl, buildDrawPlan, type Layer } from "./avatar";
 import { BADGE_AWARD, type Badge, loadBadge } from "./badge";
 import { getFolkLexicons, getFolkRepos } from "./folk";
 
@@ -21,7 +16,6 @@ const MAX_BADGES = 50;
 
 export type PlayerPortrait = {
   layers: Layer[];
-  pixelated: boolean;
   /** Set only for a composited blob, the one shape Satori can put on a card. */
   blobUrl: string | null;
 };
@@ -33,7 +27,7 @@ export type PlayerSummary = {
   actor: string;
   handle: string | null;
   name: string;
-  portrait: PlayerPortrait | null;
+  portrait: PlayerPortrait;
 };
 
 export type Player = {
@@ -50,37 +44,25 @@ function str(value: unknown): string | null {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-/**
- * Two avatar shapes are live in the wild: a composited blob in the player's own
- * repo, and a map of trait keys resolved against art the lexicon authority
- * publishes. The record decides which, not its age.
- */
-async function buildPortrait(
+/** A blob if the profile has one, else the trait stack - which defaults to a face. */
+function buildPortrait(
   avatar: unknown,
   owner: { pds: string; did: string },
-): Promise<PlayerPortrait | null> {
+): PlayerPortrait {
   const cid = blobCid(avatar);
   if (cid) {
     const url = avatarBlobUrl(avatar, owner);
     if (url) {
       return {
         layers: [{ kind: "image", url, slot: "avatar", key: "blob" }],
-        pixelated: false,
         blobUrl: url,
       };
     }
   }
 
-  const resolved = await getAvatarCatalog();
-  if (!resolved) return null;
-
   // A blob's own keys (`ref`, `size`, `mimeType`) are not slot ids.
   const stored = cid ? {} : ((avatar ?? {}) as Record<string, unknown>);
-  const layers = buildDrawPlan(resolved.catalog, stored, {
-    pds: resolved.pds,
-    did: resolved.did,
-  });
-  return layers.length > 0 ? { layers, pixelated: true, blobUrl: null } : null;
+  return { layers: buildDrawPlan(stored), blobUrl: null };
 }
 
 async function loadBadges(identity: Identity): Promise<PlayerBadge[]> {
@@ -133,7 +115,7 @@ export async function listPlayers(): Promise<PlayerSummary[]> {
             handle: identity.handle,
             name:
               str(profile.value.displayName) ?? identity.handle ?? identity.did,
-            portrait: await buildPortrait(profile.value.avatar, {
+            portrait: buildPortrait(profile.value.avatar, {
               pds: identity.pds,
               did: identity.did,
             }),
@@ -161,15 +143,13 @@ export async function loadPlayer(actor: string): Promise<Player> {
     PROFILE_RKEY,
   ).catch(() => null);
 
-  const [portrait, badges] = await Promise.all([
-    profile
-      ? buildPortrait(profile.value.avatar, {
-          pds: identity.pds,
-          did: identity.did,
-        })
-      : null,
-    loadBadges(identity),
-  ]);
+  const badges = await loadBadges(identity);
+  const portrait = profile
+    ? buildPortrait(profile.value.avatar, {
+        pds: identity.pds,
+        did: identity.did,
+      })
+    : null;
 
   return {
     did: identity.did,
-- 
knotmirror 0.0.1