feat!: migrate shared UI packages to capability-based runtime APIs#113
Merged
feat!: migrate shared UI packages to capability-based runtime APIs#113
Conversation
Implements capability-based adapter architecture (US4 / Phase 2): 13 tiered capabilities, profile runtime types, EcosystemRuntime, CapabilityFactoryMap, runtime errors, and updated EcosystemExport. Removes ContractAdapter and related types; shared primitives live in adapters/common. Adds major changeset for @openzeppelin/ui-types.
replace shared ui adapter dependencies with narrow capability and runtime apis so each package surface only requires the behavior it actually consumes. add shared capability bundle aliases and a major changeset for the published packages affected by the phase. BREAKING CHANGE: shared ui packages now expose capability-based props and runtime-oriented react exports instead of ContractAdapter and FullContractAdapter interfaces.
Move the basic React example from ContractAdapter usage to profile-based runtimes and capability helpers, and align wallet and ui-kit APIs with partial ui-kit configuration. Update the shared local-dev pnpm hook to resolve internal adapter workspace packages so the example app can run against local adapters again.
Switch the basic example app onto the shared adapters-vite helper and add a changeset for the local-dev and ui-kit runtime follow-up updates across ui-dev-cli, ui-react, and ui-types.
…r caching Introduce WalletSessionRegistry to cache provider components and facade hooks per ecosystem, preventing wallet provider remounts on same-ecosystem network switches. Extend DerivedAccountStatus with isConnecting, isDisconnected, isReconnecting, and status fields. Add cross-ecosystem transition detection to WalletConnectionUI and useWalletComponents to suppress stale UI during ecosystem switches. Clean up verbose debug logging in wallet connection components.
Add releaseRuntime to RuntimeProvider so WalletStateProvider can dispose superseded runtimes after the replacement has been fully loaded, UI-kit configured, and promoted to activeRuntime. This prevents stale runtimes from accumulating in the registry while preserving the ecosystem-scoped wallet session across switches.
React 19's development-mode commit phase introspects old prop values via addObjectDiffToProperties. When a disposed runtime's proxy trap throws RuntimeDisposedError on property access, this crashes the commit. Deferring dispose() to the next macrotask via setTimeout(fn, 0) lets React finish its commit cycle before the proxy becomes hostile.
… terminology Replace leftover "adapter" references in code snippets, comments, and UI copy with the current capability-based naming (runtime, capabilities, contractLoading, typeMapping, relayer, etc.).
…ruth Serialize pnpmfile STANDARD_FAMILIES from families.ts at generation time instead of hardcoding a duplicate copy in the template string.
Extend tidy-clocks-repair changeset to cover deriving pnpmfile STANDARD_FAMILIES from families.ts.
Restore the shared build-time bootstrap hook on EcosystemExport so consumers and adapters can rely on the common contract instead of local type extensions.
Refresh adapter-facing type documentation and export comments to reflect the capability-based runtime model. Also update the wallet state context note so its bundled-adapter example uses the current adapter package namespace.
Contributor
There was a problem hiding this comment.
Pull request overview
Migrates shared UI packages from the legacy monolithic ContractAdapter API to the new capability-based runtime model (EcosystemRuntime + per-capability interfaces), aligning components, utilities, docs, and the example app with profile-scoped capability consumption.
Changes:
- Replaces adapter-shaped props and helpers with narrow capability interfaces across renderer/components/utils.
- Introduces
EcosystemRuntime, capability factory maps, profile runtime types, and new capability bundles in@openzeppelin/ui-types. - Updates
@openzeppelin/ui-reactto manage runtimes (provider/contexts/hooks), adds a wallet session registry, and updates the example app to the new runtime pattern.
Reviewed changes
Copilot reviewed 119 out of 120 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/utils/src/requiredInputs.ts | Switches required-input snapshot logic to ContractLoadingCapability. |
| packages/utils/src/contractInputs.ts | Migrates missing-required-input detection to ContractLoadingCapability. |
| packages/utils/src/tests/contractInputs.test.ts | Updates utility tests to stub ContractLoadingCapability. |
| packages/types/src/forms/fields.ts | Introduces TransactionFormCapabilities and updates TransactionFormProps to use capability intersections. |
| packages/types/src/common/index.ts | Re-exports new capability-bundles module. |
| packages/types/src/common/capability-bundles.ts | Adds shared capability intersection aliases and prop fragments. |
| packages/types/src/common/address-book-widget.ts | Migrates address book widget props from adapter to addressing capability + resolver. |
| packages/types/src/adapters/runtime.ts | Adds RuntimeCapability, EcosystemRuntime, and CapabilityFactoryMap types. |
| packages/types/src/adapters/profiles/viewer.ts | Adds viewer profile runtime type. |
| packages/types/src/adapters/profiles/transactor.ts | Adds transactor profile runtime type. |
| packages/types/src/adapters/profiles/profile-name.ts | Adds ProfileName union for runtime creation. |
| packages/types/src/adapters/profiles/operator.ts | Adds operator profile runtime type. |
| packages/types/src/adapters/profiles/index.ts | Exports profile runtime types and ProfileName. |
| packages/types/src/adapters/profiles/declarative.ts | Adds declarative profile runtime type. |
| packages/types/src/adapters/profiles/composer.ts | Adds composer profile runtime type. |
| packages/types/src/adapters/index.ts | Reworks adapter exports to capability/runtime-based surface and removes FullContractAdapter. |
| packages/types/src/adapters/export.ts | Updates export bootstrap docs to refer to runtime/capability surface. |
| packages/types/src/adapters/errors.ts | Adds runtime lifecycle errors (RuntimeDisposedError, UnsupportedProfileError). |
| packages/types/src/adapters/ecosystem-export.ts | Updates EcosystemExport to expose capability factories and createRuntime. |
| packages/types/src/adapters/contract-state.ts | Removes legacy ContractStateCapabilities. |
| packages/types/src/adapters/common.ts | Adds shared adapter primitives for capabilities (connectors, type mapping metadata, etc.). |
| packages/types/src/adapters/capabilities/wallet.ts | Adds wallet capability interface. |
| packages/types/src/adapters/capabilities/ui-labels.ts | Adds UI labels capability interface. |
| packages/types/src/adapters/capabilities/ui-kit.ts | Adds UI kit capability interface. |
| packages/types/src/adapters/capabilities/type-mapping.ts | Adds type mapping capability interface. |
| packages/types/src/adapters/capabilities/schema.ts | Adds schema capability interface (absorbs view-function helpers). |
| packages/types/src/adapters/capabilities/relayer.ts | Adds relayer capability interface. |
| packages/types/src/adapters/capabilities/query.ts | Adds query capability interface (absorbs view calls + formatting). |
| packages/types/src/adapters/capabilities/network-catalog.ts | Adds network catalog capability interface. |
| packages/types/src/adapters/capabilities/index.ts | Exports all capability interfaces. |
| packages/types/src/adapters/capabilities/explorer.ts | Adds explorer capability interface. |
| packages/types/src/adapters/capabilities/execution.ts | Adds execution capability interface. |
| packages/types/src/adapters/capabilities/contract-loading.ts | Adds contract loading capability interface. |
| packages/types/src/adapters/capabilities/addressing.ts | Adds addressing capability interface. |
| packages/types/src/adapters/capabilities/access-control.ts | Adds access control capability interface. |
| packages/types/src/adapters/README.md | Updates adapter docs to capability tiers + profiles + runtime model. |
| packages/types/README.md | Updates package README to reflect runtime/capability types. |
| packages/renderer/src/utils/formUtils.ts | Migrates address transforms and field transforms to AddressingCapability. |
| packages/renderer/src/utils/tests/formUtils.test.ts | Updates renderer transform tests for AddressingCapability. |
| packages/renderer/src/components/transaction/TransactionStatusDisplay.tsx | Migrates formatting/explorer linking to query + explorer capabilities. |
| packages/renderer/src/components/network/NetworkSettingsDialog.tsx | Reworks network settings dialog to use RelayerCapability and external refresh callback. |
| packages/renderer/src/components/network/NetworkServiceSettingsPanel.tsx | Migrates service form validation/testing to RelayerCapability. |
| packages/renderer/src/components/fieldRegistry.ts | Changes field registry prop shape to DynamicFormContextProps. |
| packages/renderer/src/components/WalletConnectionWithSettings.tsx | Uses runtime-based wallet state and reconfigures UI kit after settings changes. |
| packages/renderer/src/components/TransactionForm.tsx | Passes specific capabilities (addressing, typeMapping, query, explorer, execution, relayer). |
| packages/renderer/src/components/ExecutionConfigDisplay/hooks/useExecutionValidation.ts | Validates execution via ExecutionCapability. |
| packages/renderer/src/components/ExecutionConfigDisplay/components/RelayerConfigDetails.tsx | Switches UI labels retrieval to activeRuntime.uiLabels. |
| packages/renderer/src/components/ExecutionConfigDisplay/ExecutionConfigDisplay.tsx | Migrates execution config UI to execution + relayer capability props. |
| packages/renderer/src/components/DynamicFormField.tsx | Migrates to DynamicFormContextProps and enforces typeMapping for nested generation. |
| packages/renderer/src/components/ContractStateWidget/components/ViewFunctionsPanel.tsx | Migrates state queries to query and schema filtering to schema. |
| packages/renderer/src/components/ContractStateWidget/ContractStateWidget.tsx | Migrates widget contract state logic to capability props. |
| packages/renderer/src/components/AddressBookWidget/AddressBookWidget.tsx | Renames widget inputs to addressing + resolveAddressing. |
| packages/renderer/src/components/AddressBookWidget/AddAliasDialog.tsx | Updates dialog to use addressing capability resolution per network. |
| packages/renderer/README.md | Updates renderer documentation to capability-based props. |
| packages/react/src/index.ts | Exports runtime-oriented provider/context/hook names. |
| packages/react/src/hooks/walletSessionRegistry.ts | Adds ecosystem-scoped wallet session caching helpers. |
| packages/react/src/hooks/walletSessionRegistry.test.ts | Adds unit tests for wallet session registry behavior. |
| packages/react/src/hooks/useWalletReconnectionHandler.ts | Generalizes reconnection handler to any RuntimeCapability. |
| packages/react/src/hooks/useWalletComponents.ts | Migrates wallet components resolution to runtime uiKit capability + cross-ecosystem guard. |
| packages/react/src/hooks/useDerivedAccountStatus.ts | Expands derived wallet status shape and safe field extraction. |
| packages/react/src/hooks/useAdapterContext.ts | Renames adapter context hook to useRuntimeContext. |
| packages/react/src/hooks/tests/useWalletComponents.test.tsx | Updates hook tests for runtime + uiKit capability access. |
| packages/react/src/hooks/tests/useDerivedAccountStatus.test.tsx | Adds test coverage for derived account status extraction/fallbacks. |
| packages/react/src/hooks/WalletStateContext.ts | Migrates wallet state context from adapter to runtime terminology and fields. |
| packages/react/src/hooks/AdapterProvider.tsx | Reworks provider to manage and dispose EcosystemRuntime instances; introduces releaseRuntime. |
| packages/react/src/hooks/AdapterContext.tsx | Renames adapter registry/context types to runtime equivalents and adds releaseRuntime. |
| packages/react/src/components/WalletConnectionUI.tsx | Migrates wallet UI to runtime uiKit capability with cross-ecosystem transition guard. |
| packages/react/src/components/WalletConnectionHeader.tsx | Updates header skeleton logic to runtime loading state. |
| packages/react/src/components/NetworkSwitchManager.tsx | Migrates network switching to WalletCapability + NetworkCatalogCapability inputs. |
| packages/react/README.md | Updates public docs and examples to runtime providers/capabilities. |
| packages/dev-cli/src/lib/init.ts | Derives pnpmfile family data from canonical STANDARD_FAMILIES and adds workspace fallback resolution. |
| packages/dev-cli/src/lib/init.test.ts | Updates CLI tests for pnpmfile workspace fallback helpers. |
| packages/components/src/components/network-errors/useNetworkErrors.ts | Migrates error reporting helper to accept RuntimeCapability. |
| packages/components/src/components/network-errors/NetworkErrorAwareAdapter.tsx | Generalizes proxy wrapper to RuntimeCapability generics. |
| packages/components/src/components/fields/ObjectField.tsx | Switches nested field generation to TypeMappingCapability. |
| packages/components/src/components/fields/ArrayObjectField.tsx | Switches nested array-object generation to TypeMappingCapability. |
| packages/components/src/components/fields/AddressField.tsx | Migrates address validation to AddressingCapability. |
| packages/components/src/components/contract-definition/ContractDefinitionSettingsPanel.tsx | Migrates provider settings to ContractLoadingCapability. |
| examples/basic-react-app/src/utils/schemaMocking.ts | Migrates preview schema mocking to TypeMappingCapability. |
| examples/basic-react-app/src/stores/index.ts | Removes adapter selector export from store API. |
| examples/basic-react-app/src/stores/ecosystemStore.ts | Makes ecosystem store runtime-agnostic; delegates runtime resolution to provider layer. |
| examples/basic-react-app/src/providers/AppProviders.tsx | Switches app wiring to RuntimeProvider and runtime-derived demo capability bundle. |
| examples/basic-react-app/src/core/runtimeCapabilities.ts | Adds demo helper to flatten runtime capabilities into a single object. |
| examples/basic-react-app/src/core/networkUtils.ts | Reworks helpers to be runtime-led and adds addressing resolver. |
| examples/basic-react-app/src/core/ecosystemManager.ts | Updates demo ecosystem loading to runtime creation/caching and runtime disposal on cache clear. |
| examples/basic-react-app/src/context/useEcosystem.ts | Updates docs/examples to reference capabilities rather than adapter. |
| examples/basic-react-app/src/context/ecosystemContextDef.ts | Updates context shape to include runtime and flattened demo capabilities. |
| examples/basic-react-app/src/context/EcosystemContext.tsx | Updates standalone provider to load runtimes and derive demo capability bundle. |
| examples/basic-react-app/src/components/WalletDemo/config-loaders.ts | Updates snippets to use reconfigureActiveUiKit. |
| examples/basic-react-app/src/components/WalletDemo/code-snippets.ts | Updates tutorial snippets to reflect runtime + uiKit model. |
| examples/basic-react-app/src/components/WalletDemo/WalletStatusPanel.tsx | Updates status panel to runtime-based state and isRuntimeLoading. |
| examples/basic-react-app/src/components/WalletDemo/WalletKitSwitcher.tsx | Fetches kits via activeRuntime.uiKit and uses reconfigureActiveUiKit. |
| examples/basic-react-app/src/components/WalletDemo/WalletDemo.tsx | Updates runtime terminology and UI kit reconfiguration calls. |
| examples/basic-react-app/src/components/WalletDemo/LearnSections.tsx | Updates copy to runtime naming and new hook name. |
| examples/basic-react-app/src/components/TypeMappingDemo.tsx | Migrates demo from adapter to capability bundle inputs. |
| examples/basic-react-app/src/components/RendererDemo.tsx | Uses addressing + typeMapping demo capabilities for DynamicFormField. |
| examples/basic-react-app/src/components/NetworkDemo.tsx | Migrates network demo settings to relayer capability usage. |
| examples/basic-react-app/src/components/HomeDemo.tsx | Migrates address validation demo to capability-based validation. |
| examples/basic-react-app/src/components/FormFieldsDemo.tsx | Migrates field demos to addressing capability prop. |
| examples/basic-react-app/src/components/EcosystemIndicator.tsx | Updates loading copy to runtime naming. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/utils.ts | Migrates schema generation to TypeMappingCapability. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/useContractLoader.ts | Migrates contract loading hook to ContractLoadingCapability. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/constants.ts | Updates learning snippets to runtime/capability APIs. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/LearnTab.tsx | Updates documentation copy to reference capabilities instead of adapter methods. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/ExecuteTransactionCard.tsx | Uses TransactionFormCapabilities instead of adapter prop. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/ContractLoadingCard.tsx | Updates copy to reference contractLoading capability. |
| examples/basic-react-app/src/components/ContractInteractionsDemo/ContractInteractionsDemo.tsx | Migrates demo to runtime + toTransactionFormCapabilities and passes query/schema capabilities. |
| examples/basic-react-app/src/components/ArchitectureDemo.tsx | Updates architecture demo to RuntimeProvider + EcosystemRuntime model. |
| examples/basic-react-app/src/components/AddressDisplayDemo.tsx | Uses explorer capability for explorer URLs. |
| examples/basic-react-app/src/components/AccountAliasDemo.tsx | Migrates address book demo to addressing capability + runtime placeholders. |
| .specify/memory/constitution.md | Updates constitution language to runtime/capability model and bumps version metadata. |
| .pnpmfile.cjs | Adds workspace fallback package resolution for local-dev rewrites. |
| .changeset/tidy-clocks-repair.md | Adds changeset for pnpmfile family derivation and local dev improvements. |
| .changeset/fresh-candles-learn.md | Adds changeset for major capability/runtime migration across packages. |
| .changeset/capability-interface-types.md | Adds changeset documenting @openzeppelin/ui-types breaking changes. |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Comments suppressed due to low confidence (3)
packages/renderer/src/components/transaction/TransactionStatusDisplay.tsx:1
- The fallback
explorer?.getExplorerUrl(txHash)is likely incorrect becausegetExplorerUrlis documented as an address URL resolver, not a transaction URL resolver. This can produce malformed links (or even a valid-but-wrong address link) whengetExplorerTxUrlis not implemented. Suggestion (mandatory): only usegetExplorerTxUrlfor tx links; if it’s absent, fall back to the explicitexplorerUrlprop (ornull) rather than callinggetExplorerUrlwith a tx hash.
.pnpmfile.cjs:1 - This change now iterates over all dependencies and attempts workspace fallback resolution via directory scanning. Concretely, this can degrade install performance since
resolvePackageDirectoryByNamemay traverserepoRoot/packages/*(and parse manypackage.jsonfiles) once per dependency key, including third-party deps that will never resolve. Suggestion (mandatory): restrict fallback resolution to known first-party scopes (e.g.@openzeppelin/) or to packages present in the packed manifest; and/or introduce a simple memo/cache map inside the pnpmfile forpackageName -> resolvedPath|nilso each name is scanned at most once per run.
/**
packages/utils/src/contractInputs.ts:1
- The docstring still refers to "adapter-declared" required inputs, but this utility now depends on
ContractLoadingCapability. Suggestion (optional): update the comment to reflect capability terminology (e.g. "contract-loading capability-declared required inputs") to match the new public model and avoid confusion for consumers reading utility docs.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates all shared UI packages from the monolithic
ContractAdaptersurface to the new capability-based runtime architecture introduced inopenzeppelin-adapters.What changed
@openzeppelin/ui-types— ReplaceContractAdapter,FullContractAdapter, andContractStateCapabilitieswith 13 capability interfaces, profile runtime types,EcosystemRuntime,CapabilityFactoryMap, and updatedEcosystemExport@openzeppelin/ui-react—RuntimeProvider/AdapterProvidernow managesEcosystemRuntimeinstances;WalletStateProviderconsumes narrow capability props; new wallet session registry for ecosystem-scoped provider caching; safe runtime handoff on network switches@openzeppelin/ui-renderer— All component props migrated fromContractAdapterto narrow capability interfaces@openzeppelin/ui-components— Component props updated for capability-based consumption@openzeppelin/ui-utils— Helper functions updated to accept capability interfaces@openzeppelin/ui-dev-cli— pnpmfile family data derived from canonical source; local adapter dev supportbasic-react-appfully migrated to runtime/capability consumption patternPackages affected
@openzeppelin/ui-typesContractAdapter@openzeppelin/ui-react@openzeppelin/ui-renderer@openzeppelin/ui-components@openzeppelin/ui-utils@openzeppelin/ui-dev-cliCross-repo coordination
Merge and publish order:
Test plan
pnpm testand format checks