[Plan] feat: Citizen SDK → Citizen Claim Widget Migration

[L03TJ3]

Original Prompt

Below is the prompt part for 'create an issue'.

The original prompt also included execution phases, the full prompt can be read here: https://github.com/GoodDollar/GoodWidget/tasks/6dea84d7-b70b-4375-a6ac-1dfa2d32f78d?author=L03TJ3

1) Required Inputs

Use all of the following as mandatory input references:

• GoodWidget PR Goodsdks migration setup #9: Goodsdks migration setup #9
• GoodSDKs PR #42: add: sdk capabilities summary for goodwidget UI migration GoodSDKs#42
• GoodWalletV2 claim flow source:
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/ClaimView.tsx
• related claim-flow files (must also be reviewed):
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/ClaimButton.tsx
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/ReadyToClaim.tsx
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/RequireWhitelist.tsx
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/Claimed.tsx
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/ClaimFooter.tsx
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/Countdown.tsx
  • GoodWalletV2/src/sections/GoodDollar/components/Claim/Claim.module.css
• GoodWidget design-demo reference:
  • GoodWidget/packages/claim-widget-theme-demo

If any required input is unavailable, stop and report exactly what is missing.

1.1) Start prerequisites

(GitHub Issue Flow)

Before starting executing on the ## 4) Execution Phases specified below make sure to:

• Open a concise implementation issue in the relevant repository
• Include scope, acceptance criteria, and checklist from this specification
• Assign issue to self
• Execute implementation against that issue
• Start implementation from a new branch created from:

goodsdks-migration-setup (GoodWidget, PR #9 branch context)

Branch rule:

• check out goodsdks-migration-setup
• create a new working branch from it
• perform all GoodWidget migration work on that new branch
• Do not start from unrelated or stale branches.

2) Scope (Do Not Change)

Implement the first real SDK-backed claim widget migration:

• target implementation package: GoodWidget/packages/citizen-claim-widget
• do not modify demo package behavior: GoodWidget/packages/claim-widget-theme-demo

Platform role boundaries (must be preserved):

• packages/ui: reusable primitives/composites only
• packages/core: runtime/provider/theming infrastructure
• packages/embed: web-component bridge
• SDK widgets (including citizen-claim-widget): full feature UI/UX flows

Primary deliverable:

• a functional, SDK-backed claim widget flow aligned to GoodWalletV2 claim behavior and visually aligned to claim-widget-theme-demo

Secondary deliverables:

• clear integration metadata and adapter runtime contracts that support implementation, stories, and tests

Existing scaffold continuation rule:

• GoodWidget/packages/citizen-claim-widget already exists
• continue from existing files; do not restart from scratch
• specifically use and extend:
  • packages/citizen-claim-widget/src/integration.ts
  • packages/citizen-claim-widget/src/widgetRuntimeContract.ts
• create new files only when required by concrete implementation gaps

GoodSDKs scope clarification:

• capability definition is expected to come from GoodSDKs PR #42
• do not add new GoodSDKs implementation changes unless a concrete capability-shape mismatch or blocker is discovered during migration
• if such a blocker is found, report it explicitly before changing GoodSDKs

3) Non-Goals (Do Not Add)

Do not add in this task:

• unrelated design-system refactors
• shifting SDK widget responsibilities into packages/ui

=======

Agent planning result

Scope

Implement the first real SDK-backed claim widget migration in packages/citizen-claim-widget.

Aligned with:

• GoodWidget PR Goodsdks migration setup #9 (scaffold: goodsdks-migration-setup branch)
• GoodSDKs PR #42 (citizenSdkCapabilities manifest + ClaimSDK/IdentitySDK classes)
• GoodWalletV2 ClaimView.tsx behavior reference

Acceptance Criteria

• packages/citizen-claim-widget builds successfully
• packages/claim-widget-theme-demo behavior is unchanged
• All 8 required states implemented: loading, not_connected, not_whitelisted, eligible, already_claimed, claiming, success, error
• All 5 required primary intents implemented: connect, verify, claim, refresh, switch_chain
• Provider-first runtime path preserved: host provider → GoodWidgetProvider → citizen-claim adapter → citizen-sdk
• src/integration.ts and src/widgetRuntimeContract.ts extended (not replaced)
• No scope leakage into packages/ui

GoodWalletV2 → Widget State Mapping

GoodWalletV2 State	Widget Status	SDK Call	Primary Action
Loading stores	loading	none	none
No wallet	not_connected	none	connect
!primaryWl.isWhitelisted	not_whitelisted	IdentitySDK.generateFVLink	verify
claim.status === 'can_claim'	eligible	ClaimSDK.checkEntitlement	claim
claim.status === 'has_claimed'	already_claimed	ClaimSDK.nextClaimTime	refresh
Claiming in progress	claiming	ClaimSDK.claim	none
Claim succeeded	success	—	none
Error thrown	error	—	refresh
Wrong chain	not_connected + switch_chain action	—	switch_chain

Checklist

• Phase A: Merge goodsdks-migration-setup branch
• Phase B: Contracts — verify integration.ts and widgetRuntimeContract.ts
• Phase C: Implement src/adapter.ts (useCitizenClaimAdapter hook)
• Phase C: Implement src/CitizenClaimWidget.tsx (full UI)
• Phase C: Add src/element.ts and src/register.ts (web component bridge)
• Phase C: Update src/index.ts exports
• Phase C: Update package.json with @goodsdks/citizen-sdk + viem deps
• Phase D: Build passes (tsup)
• Phase D: claim-widget-theme-demo behavior unchanged

Implementation Branch

copilot/citizen-claim-widget-migration (from goodsdks-migration-setup)