Host-provided identity: show your app's users in the chat (0.2.0)

[macoeshka]

Base is main — this repo has no develop branch. Version bumped 0.1.6 → 0.2.0 (additive only); the CDN snippets in the README and integration guide now point at it too.

Lets a host app supply the display names and avatars for the wallets in its
chat, so the widget renders its own users instead of a .sol domain or a
shortened address. Visual and scoped to one running embed: Cherry persists none
of it, the wallet stays the author of every message, and the Cherry app is
unaffected.

Surface

The iframe pulls — only it knows which wallets are on screen:

const chat = new CherryEmbed({
  appId, container, roomId,

  resolveUsers: async (wallets) => { /* ≤50 at a time; null = "don't know" */ },
  searchUsers:  async ({ query, cursor, limit }) => { /* @mention autocomplete */ },
});

The host pushes what changes — an open chat would otherwise never notice a
rename, since the iframe only asks about wallets it hasn't resolved yet:

chat.setUserProfiles({ [wallet]: { displayName } });  // merged: avatar kept
chat.invalidateUserProfiles([wallet]);
chat.setIdentityToken(token);   // Authorization for the profile endpoint

Plus userProfiles in the config (right first paint, no round-trip) and
getUser, reserved for the profile view.

Test bench — example/host-identity/

One page, one small backend, and a checklist of what "working" looks like. It
covers both transports (page handlers vs. a profile endpoint the iframe calls
directly), a live rename, invalidateUserProfiles(), a null profile falling
back to the Cherry identity, @mention autocomplete over the app's own
directory, and a "Serve hostile profiles" button that answers with a bidi
override, an embedded newline, zero-width padding, 400 characters and a
javascript: avatar — so the sanitizer can be checked by eye.

Runs authenticated with no wallet extension: with APP_SECRET set it mints an
embedToken server-side, which is what makes it a one-command bench.

Verified end to end

Ran the bench against a full local stack (server + realtime + embed + traefik).
Every claim above was checked in a live chat, not just in unit tests: names and
avatars replaced, both transports answering, a live rename applying instantly,
the hostile payload rendering flattened and pictureless, and @mention
autocomplete finding directory users Cherry has never heard of — with the
picked wallet riding along invisibly, so mention routing still works.

Two bugs the live run caught, both fixed:

• Bench: demo wallets were sliced out of a sha256 hex digest, so they
  weren't valid base58 — the invisible wallet tag on a picked mention went
  unrecognised and the address rendered as visible junk beside the name. A
  bench that lies about the feature is worse than none; the roster now
  base58-encodes the digest.
• Runtime (cherrydotfun/messaging-server#313): pushing only a name wiped
  the avatar. users.update now merges field-wise — documented here in the
  method's JSDoc, the type, the README and the changelog.

Notes for review

• Registering nothing keeps the previous behaviour exactly. Handlers are
  wired only when supplied, so an unregistered method gets METHOD_NOT_FOUND
  immediately — which the iframe reads as "this host cannot answer" and stops
  asking. A handler resolving empty instead would look like "nobody is known"
  and cache negatives for every wallet in the room.
• A thrown handler surfaces as an error, not as an empty result — same reason.
• setIdentityToken keeps the token in memory only; it is re-sent after an
  iframe reload alongside the profile map, exactly like the auth token.
• Requires "Who your users appear as" on the embed at portal.cherry.fun
  (cherrydotfun/self-service-portal#270). Integrators who prefer answering from
  their backend configure a profile endpoint there and register no handlers at
  all — the better fit for mobile WebViews, where the host page is a thin shim.

Docs

• integration_instructions.md: a section that applies to all three auth modes
  (auth decides who may post, this decides what their row says), both
  transports, push semantics, and the five ways it goes wrong in practice.
  Mode 1's "No host-side identity" bullet was flatly false and is fixed.
• skills/cherry-embed-integration: the same ground as hard rules an agent can
  check, a Discovery question so the feature gets raised at all, and
  verification steps. Its jsDelivr pin was still 0.1.5 while every other file
  said 0.2.0.
• docs/react-native.md: why mobile wants the profile endpoint rather than page
  handlers (resolveUsers is a function and the bridge config crosses as a JSON
  string, so it cannot travel), and which lines to add to the example host page
  if a rename has to be pushed from native.
• README: links the reference page and the bench, and states the sanitizing
  rules, since a refused avatar or a truncated name reads as a bug otherwise.
• Two doc comments no longer matched the shipped behaviour and were corrected:
  invalidateUserProfiles marks profiles stale rather than forgetting them (the
  name on screen stays while the fresh answer is in flight), and resolveUsers
  batching is a 16 ms window, not an animation frame.
• Full reference on the portal: cherrydotfun/self-service-portal#272.

Checks

• 260 tests green (14 new here, the rest from develop), tsc --noEmit clean, npm run build clean
• README section + CHANGELOG entry for 0.2.0
• CDN pins stay at 0.1.7, the published release. This branch had moved them to 0.2.0 before it exists; bumping them belongs in the commit that publishes to npm. package.json is 0.2.0 -- that is the package's own version, not a pin.

Merged develop (0.1.7: unread API, chatBubble launcher, painted iframe ground,
the bridge's sender-window check). Five of the six conflicts were two independent
additions in the same spot; the real one was Marketing.tsx, where develop
rewrote buildSnippet to return { code, shown, total } while this branch had
only touched the pin inside it — took develop's function and re-pinned in place.

Publish to npm only after the embed half is in production: cherrydotfun/messaging-server#313
and #316 are in develop, riding the release in cherrydotfun/messaging-server#318.
Until that ships, the new methods have nothing on the other side. The portal docs
(cherrydotfun/self-service-portal#272, merged) describe 0.2.0, so the npm release
is what closes that gap.

🤖 Generated with Claude Code

[macoeshka]

Added example/host-identity/ — a runnable bench for this feature, plus the
checklist of what "working" looks like.

It covers both transports (page handlers vs. a profile endpoint the iframe calls
directly) and the paths a unit test can't show: a live rename through
setUserProfiles(), invalidateUserProfiles(), a null profile falling back to
the Cherry identity, and @mention autocomplete searching the app's own directory.

There is also a "Serve hostile profiles" button — it answers with a bidi
override, an embedded newline, zero-width padding, 400 characters and a
javascript: avatar, so the sanitizer can be checked by eye. The matching
assertion now lives on the runtime side in
cherrydotfun/messaging-server#313 (sanitize.test.ts), so the README's promise
and the code can't drift apart.

The demo directory maps any wallet to a stable fake user, so the bench stays
useful in a room full of strangers, and avatars are SVGs served by the example
itself — it works offline.

Verified locally: the page renders, /identity/resolve, /identity/search and
the avatar route all answer, and the call log fills in. The embed itself does not
mount yet against production — the runtime half of this feature isn't deployed —
so steps 3–6 of the README are what to run once messaging-server#313 is out.