app-indexer-first-paint

Instruction file imported from OnSocial-Labs/onsocial-protocol (.cursor/rules/app-indexer-first-paint.mdc). Copyright stays with the author.

App indexer-first paint

For @onsocial/app (and SDK query helpers it consumes), browse/list/detail first paint must be indexer-first. Do not reintroduce chain RPC fan-out on critical paths.

Source of truth by concern

Required patterns

1. SSR critical path — batch indexer reads only (createServerOnSocialClient). No viewNearContract, get_collection, nft_tokens_for_owner, social.getOne, or N× getConfig before first paint on the happy path.
2. Soft-fill after paint — structure, brand, ACL, sheet detail may reconcile client-side; never blank a painted shell for it.
3. No duplicate keyed refetch — if SSR seed matches the active lens/sort/filter, skip the immediate client re-query (home hot/global and guild default feed are the model).
4. No N× RPC under the API key — lists use batch/indexed helpers (activeListings, memberCountsFor, ownedBy, enrichIndexedGuildSummaryCards). Never N× get_lazy_listing, isAdmin/canModerate, or getConfig per row for browse.
5. Owned vault — os.query.scarces.ownedBy + catalog enrich; RPC nft_tokens_for_owner only on Hasura failure.
6. Feed scarce CTAs — activeListings / post path match; get_lazy_listing only in buy/bid verify sheets.
7. Drop counters — soft refresh via collectionCurrent / fetchCollectionPreferIndexer; RPC only if catalog thin/missing.
8. Browser OnAPI — all client graph traffic still burns ONSOCIAL_API_KEY via /api/onapi. Treat extra soft-fetches as load. Prefer fewer, batched queries.

Explicitly OK soft paths (not first paint)

• Guild getConfig after SSR for structure/ACL
• Series brand social.getOne after drops paint
• DAO roles via /api/profile/dao-roles after portfolio paint
• Sheet-open verify (get_lazy_listing, auction/offer views, nft_token traits)

When adding a feature

1. Can first paint come from an existing Substreams view / SDK query? Use it.
2. If not, add/extend the indexer + SDK query — do not paper over with browse RPC.
3. Soft-fill or action-time RPC only for money, permissions to mutate, or true lag catch-up.
4. Skip client refetch when SSR already matches.
5. Add a unit test that mocks the indexer client and asserts RPC is not called on the happy path (see market-listings-indexer.test.ts).

Closed hardening (do not regress)

• Portfolio SSR trusts indexer only; empty page/main soft-fills client-side
• Owned vault catalog enrich uses collectionsCurrentByIds (one round-trip)
• Series catalog headings prefetch brands with one social.get per creator
• Market default browse + sales skip duplicate SSR refetch; collection skips first soft refresh when SSR solid
• Guild writers sheet / counts paint from permissions.forPath fold; permissions.has stay mutate-time
• DAO get_policy soft-fill uses short process TTL cache (never SSR)
• Home + personal + guild post SSR seed engagement counts and lazy scarce CTAs (feed-paint-hydrate) — no empty→fill for first page
• Feed engagement row always mounts (EMPTY_POST_ENGAGEMENT fallback); scarce seeds via seedScarceEmbedsFromSsr