feat: multi-buyer identity support in AI Credits widget

[Copilot]

A payer wallet was limited to a single deterministic buyer identity. This adds full multi-buyer identity management: create additional derived buyers, import via private key, register address-only (view/consent) buyers, switch between them, and deep-link assign a partner buyer via URL params.

Runtime contract & session model

• BuyerRecord type with type: 'derived' | 'imported' | 'address-only', derivationIndex, and label
• payerSession now stores buyers: BuyerRecord[] + activeBuyerAddress; old single-buyer sessions auto-migrate on first read
• State gains buyers and activeBuyerAddress; buyerPubKey/buyerPrvKey remain as computed fields from the active buyer

Derivation

• buildBuyerKeyMessage(address, index) — index 0 preserves the exact legacy message for backward compatibility; index > 0 appends (buyer N)

New adapter actions

Action	Behavior
createBuyer	Signs wallet message at next derivation index, adds to session
selectBuyer(address)	Switches active buyer, resets consent/chain state
importBuyerFromPrivateKey(key)	Validates 0x…64hex, derives address, registers as imported
selectBuyerByAddress(address)	Registers address-only buyer; sign-required actions disabled
applyDeepLinkBuyer(address, sig)	Validates ?buyerAddress=&buyerSignature= URL params on mount, registers partner buyer

UI

• BuyerOperatorCard: buyer selector list (visible when >1 buyer), "New Buyer" button, collapsible "Import Key" / "Watch Address" panel; address-only buyers show a "view only" badge and Sign Consent is disabled
• HistoryTab: BuyerFilterSelect dropdown fed via new knownBuyers prop; defaults to active buyer on history tab open
• useAiCreditsHistory: buyerAddressFilter state + setBuyerAddressFilter action; client-side filtering on entry.buyerAddress

Stories & tests

Three new QA fixtures (MultiBuyerManage, AddressOnlyBuyer, MultiBuyerHistory) and four Playwright smoke tests covering the new flows.

• Fixes Multi-buyer support in AI Credits widget #123

[Copilot]

Pull request overview

This PR expands the AI Credits widget runtime/session model from a single deterministic buyer identity to a multi-buyer identity system per payer wallet, adding UI affordances to create/import/watch buyers, switching active buyer context, and filtering history by buyer.

Changes:

• Introduces BuyerRecord[] + activeBuyerAddress into runtime state/session (with legacy session migration) and adds new adapter actions for buyer lifecycle (create/select/import/watch/deep-link).
• Updates Manage + History UI to support buyer selection and buyer-based history filtering.
• Adds Storybook QA fixtures and Playwright smoke coverage for multi-buyer flows.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/widgets/ai-credits-widget/states.spec.ts	Adds Playwright smoke tests + screenshots for multi-buyer UI states.
packages/ai-credits-widget/src/widgetRuntimeContract.ts	Extends adapter state/actions for multi-buyer support and re-exports BuyerRecord.
packages/ai-credits-widget/src/useAiCreditsHistory.ts	Adds buyer filter state/action and client-side filtering by entry.buyerAddress.
packages/ai-credits-widget/src/payerSession.ts	Replaces legacy single-buyer session fields with buyers[] + activeBuyerAddress and migration logic.
packages/ai-credits-widget/src/index.ts	Exports the new buyer-related types for consumers.
packages/ai-credits-widget/src/components/manage/BuyerOperatorCard.tsx	Adds buyer selector UI and import/watch panel; disables signing for address-only buyers.
packages/ai-credits-widget/src/components/history/HistoryTab.tsx	Adds buyer filter dropdown fed by known buyers.
packages/ai-credits-widget/src/buyerKeyDerivation.ts	Makes derivation message index-aware while preserving index 0 legacy message.
packages/ai-credits-widget/src/AiCreditsWidget.tsx	Wires knownBuyers to History UI and defaults history filter to active buyer.
packages/ai-credits-widget/src/adapter.ts	Implements multi-buyer session wiring + new actions (create/select/import/watch/deep-link) and URL param parsing.
examples/storybook/src/stories/helpers/aiCreditsWidgetStories.tsx	Adds multi-buyer QA fixture stories.
examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetQA.stories.tsx	Exposes new QA fixtures in Storybook.

Suppressed comments (3)

packages/ai-credits-widget/src/adapter.ts:894

• Deep-link signature validation currently accepts any non-empty hex string (/^0x[0-9a-fA-F]{2,}$/), so malformed/too-short signatures will be treated as “valid”. At minimum, require a 64- or 65-byte signature (EIP-2098 compact or standard) before accepting URL params.

      if (!/^0x[0-9a-fA-F]{2,}$/.test(trimmedSignature)) {
        setState((prev) =>
          withDerivedStatus(prev, { error: 'Deep-link buyer signature is invalid' }, true),
        )
        return

packages/ai-credits-widget/src/adapter.ts:1457

• Deep-link parsing runs before a payer wallet is connected. When buyerAddress/buyerSignature are present but address is still null, handleApplyDeepLinkBuyer sets an error (“Connect your wallet…”) on mount. Since the effect re-runs after connect anyway, defer applying deep-link params until address is available to avoid a spurious error flash.

  useEffect(() => {
    if (typeof window === 'undefined') return
    const params = new URLSearchParams(window.location.search)
    const urlBuyerAddress = params.get('buyerAddress')
    const urlBuyerSignature = params.get('buyerSignature')

packages/ai-credits-widget/src/components/history/HistoryTab.tsx:524

• Options in BuyerFilterSelect have role="option" but don’t indicate selection via aria-selected, which is part of the listbox pattern. This makes it harder for screen readers to announce which buyer filter is currently selected.

              tag="button"
              role="option"
              paddingHorizontal="$3"
              paddingVertical="$2"
              cursor="pointer"

[sirpy]

@blueogin is mock delay set to 0 in non storybook env? it should. it shouldnt be in production

[sirpy]

i dont understand the latest changes.
buyers is very simple
user add buyer via private key, or generate one based on signature or add it via url params.
when user add buyer it is saved on localstorage.
this is the list of user buyers.
that's it. simple.

[blueogin]

MOCK_DELAY_MS is only in the Storybook/QA mock client (@goodwidget/ai-credits-widget/mocked). Production uses the real backendClient and never hits that delay.