# UI Handoff Contracts

Future self-service and scope-admin UIs should consume user-engine through a
transport adapter that preserves the service shapes below.

USER-WP-0014 adds `RegistrationAccessManagementUi` as the first implemented
headless UI contract facade. It returns transport-neutral screen models,
route definitions, responsive layout metadata, and an accessible HTML
verification renderer.

## Self-Service Account UI

Required backend operations:

- `me` to resolve the current actor, user, account, and identity links.
- `RegistrationAccessManagementUi.start_registration` to create a UI-backed
  registration session.
- `RegistrationAccessManagementUi.attach_factor` to attach adapter-supplied
  factor evidence without rendering factor values.
- `RegistrationAccessManagementUi.complete_registration` to enforce UI
  terms/consent and complete the headless registration flow.
- `RegistrationAccessManagementUi.prepared_rights_review` and
  `accept_prepared_claim` to review and claim prepared rights.
- `RegistrationAccessManagementUi.hat_selection_view` and `select_hat` to show
  available hats and select active access context.
- `effective_profile` with the actor tenant and optional application id.
- `projection` with `SELF_SERVICE` for editable user-visible fields.
- `set_profile_value` for fields whose catalog mutability includes `USER`.
- `audit_records` or a filtered audit transport for recent user-visible
  account activity.

## Scope Admin UI

Required backend operations:

- `resolve_tenant_context` before all tenant-scoped screens.
- `RegistrationAccessManagementUi.admin_dashboard` for registration,
  prepared-account, access-profile, and onboarding diagnostics.
- `set_tenant_account_status` for in-scope account state.
- `add_membership` for tenant/team membership changes.
- `projection` with `ADMIN` or a future admin transport projection.
- `tenant_diagnostics` for onboarding and support readiness checks.

## UI Route Contract

`RegistrationAccessManagementUi.api_contract()` defines these route ids:

- `registration.start`
- `registration.factor`
- `registration.complete`
- `prepared_account.review`
- `prepared_account.accept`
- `prepared_account.deny`
- `access_profile.select_hat`
- `admin.dashboard`

Transport adapters may map these ids to HTTP, RPC, desktop, or CLI routes.
The route contract marks factor values, prepared-account factor matches,
profile defaults, claim values, and hidden policy details as redacted.

## Accessibility And Responsive Contract

`render_html` emits `banner`, `navigation`, and `main` landmarks. Section
navigation uses labels, controls expose `aria-label`, and screen models include
mobile and desktop layout metadata. Mobile screens use a one-column layout and
44px minimum touch target. Desktop screens use a two-column workbench layout.

## Fixtures

Use `user_engine.testing.scenarios` for human, tenant admin, platform
operator, delegated agent, invalid, expired, local issuer, and missing-tenant
fixtures. UIs should keep fixtures at the transport boundary and avoid
embedding identity-provider logic.