在 Seeker 手机浏览器 dapp 中连接内置钱包…

在 Seeker 设备浏览器中为 Web dapp 接入内置 Solana 钱包，完成连接、SIWS 登录、消息/交易签名及错误处理。

适用场景

解决思路

1. 新项目：运行 `npx solana-mobile@latest create my-app --template react-kit-shadcn`；该模板已内置 Seeker Connect，并使用默认 relay `relay.primal.net`。
2. 现有应用：运行 `npm install @solana-mobile/seeker-connect-wallet-standard @solana/wallet-standard-features @wallet-standard/app @wallet-standard/features`。
3. 如果应用直接 import `@solana-mobile/seeker-connect-ui` 或 `@solana-mobile/seeker-connect-web`，也要显式安装它们；Wallet Standard 包会把 core/ui/web 作为依赖拉取但不 re-export，pnpm 等严格包管理器会拒绝未声明的传递依赖 import。
4. 包角色：`@solana-mobile/seeker-connect-core` 提供 config、error taxonomy、`SeekerLink` port；`@solana-mobile/seeker-connect-ui` 提供 Lit elements（progress overlay、error dialog、branded button）；`@solana-mobile/seeker-connect-wallet-standard` 是 Wallet Standard 入口；`@solana-mobile/seeker-connect-web` 提供 MWA-over-Nostr transport 和 imperative SDK。
5. 默认使用 `relay.primal.net` 作为 `relayDomain`；它通过 kind 20012 ephemeral events、无 rate limiting、有资金运营者、Cloudflare anycast 的重复探测。把该值读自应用环境配置（例如 `VITE_SEEKER_RELAY_DOMAIN`）并把它作为 fallback，使开发者无需改代码即可切换 relay。
6. 选择 relay 时必须确认它接受来自未知 pubkey 的 ephemeral events（kind 20012），不能要求认证、付费、allowlist 或 web-of-trust；每次 session 会生成新的 Nostr keypair 并发布此类事件。
7. Payloads 在 dapp 与钱包之间端到端加密；relay 只承载密文，所以坏 relay 影响可用性，不影响机密性。
8. 如果开发者指定 relay，使用其指定值；否则只用 `relay.primal.net` 或 [references/troubleshooting.md](references/troubleshooting.md#association-failed-on-every-connect) 中 verified list 的 relay。
9. 不要自行把 Solana Mobile 的 relay domain 写进应用：不要凭记忆、从其他项目复制、或从搜索结果复制。它只在 https://docs.solanamobile.com/solana-mobile-stack/seeker-connect-quickstart 上由开发者接受 terms 后发布；如果开发者想要，引导他们去该页面并让他们把值粘贴回来。
10. 不要编造任何其他 hostname；许多公共 relay 会拒绝未知 pubkey 或 ephemeral kinds，失败会晚些表现为 `association-failed`，而不是清晰的配置错误。
11. 在 UI 渲染前调用 `registerSeekerConnect`，确保 wallet discovery 从第一次渲染就能看到它。
12. `registerSeekerConnect` 必须在浏览器中运行；代码读取 `window`，所以在 SSR（如 Next.js）中把调用放到 client-only module，或用 `typeof window !== 'undefined'` 守护；纯客户端渲染应用可放在入口文件的模块作用域。
13. 注册时传入必填 `identity`：`name`、`uri`，可选 `icon`；这些会显示在钱包 consent UI。
14. 注册时传入必填 `relayDomain`：Nostr relay，默认用 `relay.primal.net`。
15. 可选 `associationTimeoutMs`：一次 launch 允许等待多久后报 `association-failed`，默认 30s。
16. 可选 `chain`：authorization 时请求的链，默认 `solana:mainnet`。
17. `firstConnectWalletBaseUri` 除非 Solana Mobile 发布可粘贴值，否则保持 unset；unset 时首次连接使用通用 `solana-wallet:` scheme，set 时页面导航到该 host。
18. `registerSeekerConnect` 还接受 `seekerLink`、`authorizationCache`、`presenter` 覆盖项，详见 [references/imperative-api.md](references/imperative-api.md)。
19. 注册后，“Seeker Connect” 会出现在 Wallet Standard registry；wallet-adapter、ConnectorKit、`@solana/react-hooks` 或原始 `@wallet-standard/app` listing 都会自动发现它，无需额外 wiring；现有连接按钮和签名代码继续可用。
20. 可直接使用这些 features：`standard:connect`、`standard:disconnect`、`standard:events`、`solana:signMessage`、`solana:signIn`；首次 connect 后根据钱包上报能力还会提供 `solana:signTransaction` 和/或 `solana:signAndSendTransaction`。
21. 直接使用 Wallet Standard 时：从 `@wallet-standard/app` 的 `getWallets().get()` 中按 `wallet.name === SeekerConnectWalletName` 找到钱包，然后调用 `seeker.features[StandardConnect].connect()` 获取 accounts。
22. 页面加载恢复会话：调用 `seeker.features[StandardConnect].connect({ silent: true })`；silent connect 只读缓存、从不启动钱包，没有缓存时返回零 accounts。
23. 不要构建 reconnect loops 或 keep-alive 逻辑：每次钱包交互都会打开自己的短生命周期 MWA session，执行一个请求后销毁；每次交互会启动钱包 app 并显示 branded progress overlay，silent connect 是唯一例外。
24. 理解“connected”表示“持有缓存授权”：第一次 `connect()` 存储钱包签发的 `authToken`、accounts 和 capabilities（默认 localStorage）；后续操作静默重放该 token，不再重复 consent 提示。
25. `disconnect` 只在本地忘记 token，故意不调用钱包的 `deauthorize`；不要为断开连接而启动钱包 app。
26. 首次 connect 前，两个 transaction features 被假定存在；首次 connect 后根据钱包实际上报能力重新推导，并通过 `standard:events` 的 `change` 事件通告；调用前检查 feature 是否存在。
27. `chain` 是 Wallet Standard input 的一部分，但此钱包忽略它；网络是传给 `registerSeekerConnect` 的那个，并在每次调用时从缓存授权重放。没有交叉检查，所以 per-call `solana:devnet` 配 mainnet registration 会在 mainnet 提交且不报错。传 `seeker.chains[0]`，使两者不会不一致，并通过 registration 切换网络。
28. 交易以原始序列化字节（`Uint8Array`）跨越 feature 边界，legacy 和 v0 都支持；用应用已有客户端库序列化。
29. Sign-in 通过 `solana:signIn` 遵循 SIWS spec；`domain` 默认 `window.location.host`。
30. 当 sign-in 用于认证用户时，服务器是 authority：服务端签发 single-use、短有效期 nonce，并在创建 session 前在服务端验证返回的 message 和 signature，包括预期 domain 和 validity window。
31. 错误 `association-failed`：没有钱包完成 launch，可能是超时、relay 不可达或配置错误、或不在 Seeker 上。
32. 错误 `authorization-declined`：用户拒绝授权；缓存 token 被清除，下次 connect 会重新请求 consent。
33. 错误 `cancelled`：用户关闭 progress overlay；这是正常结果，绝不要作为错误展示。
34. 错误 `request-declined`：钱包拒绝签名或提交。
35. 错误 `session-closed`：交互完成前 session 结束。
36. 错误 `wallet-error`：其他任何钱包报告的错误。
37. 三个失败是普通 `Error` 而非钱包结果，并且属于误用：对报告不支持的 wallet 调用 `signAndSendTransaction`；成功 connect 前调用任何签名；wallet 对 sign-in 未返回 result。
38. 错误展示：branded dialog 只对 `SeekerConnectError` 触发，且除 `cancelled` 外所有 code 都触发；`cancelled` 保持静默。三个普通 `Error` 永远不会到达 presenter，所以如果应用自己什么也不显示，就会静默失败。
39. 在 catch 中先 branch on type，再 branch on `.code`：若 `error instanceof SeekerConnectError`，当 `error.code === SeekerConnectErrorCode.cancelled` 直接 return；否则记录日志并保持 UI 为 disconnected（SDK 已展示对话框）。若不是 `SeekerConnectError`，没有对话框，需用应用自己的错误 UI（如 `showToast`）展示并 `console.error`。
40. 可选 branded button：`@solana-mobile/seeker-connect-ui` 提供 Shadow DOM 中的 `<seeker-connect-button>` custom element，无需 host CSS；在启动时调用 `defineSeekerConnectElements()` 以立即定义元素。
41. 按钮属性：`disabled`、`theme="light" | "dark"`（指明宿主页面主题）、`variant="connect"`（默认）或 `variant="sign-in"`（标签）；自己把 `click` 接到 connect 或 sign-in 调用，按钮只负责展示。
42. 非 Wallet Standard 路径：需要 imperative API 时用 [references/imperative-api.md](references/imperative-api.md) 中的 `createNostrSeekerLink().transact`，以及 `seekerLink`、`authorizationCache`、`presenter` 覆盖项。
43. 排障参考：association failures、desktop testing、capability-derived features、cache behavior 见 [references/troubleshooting.md](references/troubleshooting.md)。
44. 显示 `.skr` 名称而非原始地址时用 `seeker-domains` skill；连接后验证 Seeker 设备所有权时用 `seeker-genesis-token` skill；CLI、templates 和 toolchain 用 `solana-mobile` skill；React Native 应用中的钱包连接用 `solana-mobile-wallet` skill（直接使用 Mobile Wallet Adapter）。

适用边界 · 注意事项

• 不要在桌面浏览器上期望连接成功：Seeker Connect 只能在设备上完成；桌面 connect 通常几秒内以 `association-failed` 失败。
• 不要在 React Native 或 Expo 应用中用它；目前只有 Web 可用，React Native 和 Android (Kotlin) 计划中；在 Expo/React Native 内连接钱包应使用 `solana-mobile-wallet` skill。
• 不要自行填写 Solana Mobile 的 relay domain，也不要编造其他 relay hostname；应让开发者到 quickstart 页面接受 terms 后粘贴，或使用默认/已验证的 relay。