[v3 stable] Verify exact Better Auth UI override contracts across repositories

[olliethedev]

Stable-v3 cohort note — 2026-08-31

The override contract remains unchanged, but final acceptance must run against the corrected companion candidate from better-auth-ui#22 on the retained Better Auth 1.6.16 database cohort. @btst/db@2.2.3 and the 2.2.3 adapters remain unchanged.

---

This was generated by AI during triage.

Current status — 2026-08-31

The companion implementation dependency is complete: better-auth-ui#20 merged through PR #21, and @btst/better-auth-ui@2.0.0-rc.3 is published. Core #202 is also complete.

This issue remains open only for its cross-repository acceptance scope:

• prove the final override contract through core scaffold/docs/generated examples owned by [v3 stable] Restore the Better Auth UI CLI scaffold and documentation #219;
• compile the public packed declarations in clean consumer fixtures, coordinated with Add packed npm/pnpm compatibility smoke tests #174;
• verify auth-plus-account and optional organization behavior across the maintained Next.js, React Router, and TanStack targets; and
• link the generated/runtime evidence here before closing.

The bridge/API migration is complete, but stable-v3 acceptance must use the corrected dependency-cohort candidate from better-auth-ui#22 rather than the published RC3 package. This remains a stable-v3 acceptance gate and does not reopen the completed bridge design.

---

Parent

• [v3] Resolve RC3 findings and publish stable v3 #153

Original RC2 reproduction — preserve this regression

Environment:

• @btst/stack@3.0.0-rc.2
• @btst/better-auth-ui@2.0.0-rc.1
• @btst/yar@1.3.2

Following the RC2 Better Auth UI guide, both the primary provider example and Avatar Upload recipe put avatar configuration under account:

overrides={{
  account: {
    authClient,
    basePath: "/p/account",
    avatar: {
      upload: async (file) => myUploader(file),
      size: 128,
      extension: "png",
    },
  },
}}

This type-checks because AccountPluginOverrides extends Partial<AuthPluginOverrides>. The released RC1 bridge, however, constructs avatar configuration only from authOverrides.avatar. It never reads accountOverrides.avatar, so the documented configuration compiles and is silently ignored. Moving the same block to auth.avatar makes it work; the retained Better Stack Web RC2 audit verified the real Vercel Blob/session flow through that undocumented location.

Evidence: RC2 report section.

Broader defect

Avatar exposed a structural contract failure rather than a one-field typo. Account and organization publicly inherit auth options that the bridge does not read at those locations. TypeScript therefore accepts auth clients, credentials, callbacks, feature flags, page props, and route bases that may be ignored or interpreted elsewhere. Independently configurable route base paths can also make Better Auth UI links disagree with BTST's registered routes.

RC3 must make accepted configuration and consumed configuration identical across the external companion, core documentation/scaffolding, generated fixtures, and public declarations.

Final contract to validate

The implementation belongs to better-stack-ai/better-auth-ui#20. This issue owns cross-repository acceptance of that contract after #202.

The decision-rich shape is:

interface AuthPluginOverrides {
  authClient: AnyAuthClient
  redirectTo?: string
  onSessionChange?: () => void | Promise<void>
  // auth-only flags, hooks, mutators, localization, and auth page props
}

interface AccountPluginOverrides {
  account?: boolean | AccountOptionsWithoutRouteBasePath
  avatar?: boolean | AvatarOptions
  deleteUser?: boolean | DeleteUserOptions
  teams?: boolean | TeamOptions
  onRouteError?: OnRouteError
  pageProps?: AccountPagePropsMap
}

interface OrganizationPluginOverrides {
  organization?: boolean | OrganizationOptionsWithoutRouteBasePath
  teams?: boolean | TeamOptions
  onRouteError?: OnRouteError
  pageProps?: OrganizationPagePropsMap
}

Exact names may follow the final #202 API, but these semantics are fixed:

1. authClient is configured once under auth.
2. account.avatar is the only wrapper-facing avatar location; auth.avatar is rejected.
3. Account and organization do not publicly extend auth override types.
4. Auth-only credentials, callbacks, hooks/mutators, feature flags, and auth page props are rejected under account/organization.
5. Each page-prop map accepts only pages owned by that plugin.
6. Shared internal behavior may use private composition; it must not widen public interfaces.
7. No override exposes a root or nested route basePath. /auth, /account, and /organization are relative plugin routes derived from [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202's resolved site runtime.
8. A public field that type-checks is read from that exact location at runtime.
9. Omitted override blocks are valid; empty objects are not plugin-activation signals.
10. Provider keys and values are inferred from the registered client stack rather than a manually assembled override map.

Cross-repository acceptance coverage

• Package-level positive type fixtures cover intended auth, account, and organization overrides.
• Negative type fixtures cover auth.avatar, account.authClient, organization.authClient, misplaced auth credentials/hooks/callbacks/feature flags/page props, cross-plugin page keys, and every removed basePath placement.
• Runtime bridge tests prove account.avatar reaches the upstream avatar context and the configured upload/delete callbacks.
• Runtime tests prove every accepted override is consumed from the location exposed by its public type.
• Route tests prove a site mount such as /pages consistently yields /pages/auth, /pages/account, and /pages/organization for matching, links, redirects, metadata, and sitemap output.
• Auth-plus-account works without organization; organization remains an explicit opt-in.
• Core docs, CLI examples, generated code, and Better Auth UI docs use the same exact locations and contain no stale accepted-but-ignored examples.
• Packed consumer fixtures compile the public declarations rather than relying on workspace-only source types.

Acceptance criteria

• The original RC2 example remains captured as a regression fixture or equivalent consumer test.
• account.avatar type-checks and invokes upstream upload/delete behavior.
• auth.avatar fails to type-check with no compatibility alias or precedence rule.
• Account and organization no longer inherit auth overrides publicly.
• authClient is accepted only at the auth seam and consumed once.
• Misplaced auth-only settings and cross-plugin page props fail compile-time fixtures.
• Every field accepted by a public override type is consumed from the same object at runtime.
• Independent route base-path overrides are absent; resolved site runtime is the sole route-base source.
• Omitted override blocks work and inferred provider types reject unregistered plugin keys.
• Companion package tests, public declaration fixtures, core documentation, and generated examples all encode the same contract.
• Next.js, React Router, and TanStack clean consumer fixtures compile/build the minimal auth-plus-account configuration from the packed corrected companion candidate on the retained Better Auth 1.6.16 cohort.
• The issue is not closed solely because the external implementation merged; cross-repository docs/generated acceptance evidence is linked here.

Out of scope

• Recreating Better Auth native permissions through BTST authorization.
• Exporting Better Auth-to-BTST identity/auth factories.
• Generating a Better Auth backend, database, schema, providers, or secrets.
• Making organization or optional Better Auth features mandatory.

Blocked by

• [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 — final resolved runtime, route ownership, and inferred provider override contract.
• better-stack-ai/better-auth-ui#20 — completed companion implementation and declarations.
• better-stack-ai/better-auth-ui#22 — corrected dependency-cohort candidate used by final packed acceptance.

Related

• [v3 stable] Restore the Better Auth UI CLI scaffold and documentation #219 consumes this exact contract when restoring the optional CLI/catalog/docs path.

[olliethedev]

The complete RC2 existing-app audit, exact package cohort, and runtime avatar verification are now published in the better-stack-web RC2 report.

[olliethedev]

Cross-repository acceptance of the final override contract is complete.

Evidence:

• Companion implementation and package-level positive/negative/runtime regression coverage: fix: align Better Auth UI with retained 1.6 cohort better-auth-ui#23
• Public declaration npm/pnpm consumer gate: test: add packed npm and pnpm consumer gates #251
• Public tarball gate run: https://github.com/better-stack-ai/better-stack/actions/runs/33447678962
• Core scaffold, documentation, and generated all-framework fixtures: feat(cli): restore Better Auth UI scaffold #252
• Packed Better Auth UI fixture run: https://github.com/better-stack-ai/better-stack/actions/runs/33450708155
• Next.js, React Router, and TanStack codegen/build E2Es: https://github.com/better-stack-ai/better-stack/actions/runs/33450708157

The accepted contract has a single auth-client seam; account.avatar is the wrapper-facing avatar location; auth/account/organization surfaces are not publicly widened into each other; independent route-base overrides are absent; omitted blocks remain valid; organization stays opt-in; and the generated minimal auth-plus-account path compiles/builds on the retained Better Auth 1.6.16 cohort using the public RC4 companion tarball.

Two independent reviews of the core implementation found no spec or repository-standards issues. Closing as complete.