Adapter framework strategy: extract framework-agnostic client core (deferred)

[Bccorb]

Summary

Extract a framework-agnostic client core so new SDKs (Vue, Angular, and similar) are thin bindings over one shared implementation instead of parallel reimplementations.

This issue has been re-scoped after review. The actionable near-term pieces were split into #76, #77, and #78. What remains here is the deferred extraction itself.

Key correction: the client is not the hard part

The obvious assumption is that the shared core is the HTTP client. It is not. These modules already have zero React imports and are effectively extraction-ready today:

• src/client/createSeamlessAuthClient.ts
• src/client/webauthnPrf.ts
• src/client/webauthnSupport.ts
• src/fetchWithAuth.ts
• src/scopedRoles.ts
• src/types.ts

The part that will actually be duplicated is the session state machine in src/AuthProvider.tsx: loading state, user, credentials, organizations, active organization, step-up status, validateToken, logout-on-401, markSignedIn, and refresh-after-mutation. That logic is React-only today. If a Vue composable and an Angular service each reimplement it, they will drift, and they will drift on auth state, which is the worst place for divergence.

So the core should expose a framework-agnostic session store (getState, subscribe, and actions), not just a fetch client. Each adapter then becomes a thin binding:

• React: useSyncExternalStore
• Vue: a composable or Pinia store
• Angular: an injectable service exposing an observable

That reframes this work from moving files to extracting a state machine, which is the part that needs real design.

Naming constraints

• @seamless-auth/core is already taken by the server monorepo (seamless-auth-server/packages/core), so it is not available for a client core.
• @seamless-auth/types already exists as a separate package that this repo does not currently consume. Decide how it relates before introducing a third naming lane.
• Suggested name: @seamless-auth/client.

Prerequisites

• Enforce framework-agnostic boundary in the client layer #76: enforce the framework-agnostic boundary by lint, so the extraction is a mechanical move.
• [Feature]: Improve headless client ergonomics for custom UI consumers #24: settle the return-shape convention (some client methods return raw Response, others return parsed result objects). With one SDK this is a wart. With four, each adapter bakes in its own error-handling convention and they will disagree. Settle this before the extraction, not after.

Timing

Do this as step one of the first non-React adapter (Vue or Angular), not as a speculative refactor. Extracting earlier costs a repo restructure, dual publishing, changesets reconfiguration, and a consumer migration, in exchange for benefits that cannot be collected until a second SDK exists.

Next.js (#78) explicitly does not depend on this work, because Next.js is React and needs SSR safety rather than a new binding.

Cross-repo note

The conformance harness in seamless-cli takes per-repo refs (react-ref, templates-ref, and similar). Each new adapter will need a ref and a lane there, so the harness needs generalizing as adapters are added. That work lives in seamless-cli, not this repo.

Related

• Enforce framework-agnostic boundary in the client layer #76 boundary enforcement (prerequisite, do now)
• isPlatformAuthenticatorAvailable throws during server-side rendering #77 SSR guard fix
• Add Next.js support #78 Next.js support (independent of this work)
• [Feature]: Improve headless client ergonomics for custom UI consumers #24 headless client ergonomics (prerequisite)
• [Feature]: Expand custom UI docs and examples #25 custom UI docs and examples

[Bccorb]

Re-scoped after a design review. The near-term actionable pieces are split out so this issue is not perpetually blocked on the large version:

• Enforce framework-agnostic boundary in the client layer #76 enforce the framework-agnostic boundary by lint (cheap, do now, prerequisite)
• isPlatformAuthenticatorAvailable throws during server-side rendering #77 fix the unguarded window access that blocks SSR
• Add Next.js support #78 add Next.js support (does not depend on this issue, since Next.js is React and needs SSR safety rather than a new binding)

The substantive change to this issue: the shared core is not primarily the HTTP client, which is already extraction-ready. It is the session state machine currently living in AuthProvider. The core should expose a framework-agnostic session store so Vue and Angular bindings cannot drift on auth state. Also noting that @seamless-auth/core is already taken by the server monorepo, so a client core needs a different name.

[Bccorb]

Scan update, current as of the 0.5.0 release candidate. Two of the three prerequisites this issue named are now met:

• The client layer is fully framework-agnostic and lint-enforced (Enforce framework-agnostic boundary in the client layer #76). Verified: nothing under src/client, src/fetchWithAuth.ts, src/scopedRoles.ts, or src/types.ts imports React or the router.
• The return-shape convention is settled ([Feature]: Improve headless client ergonomics for custom UI consumers #24). All 41 request methods return SeamlessAuthResult, so adapters cannot each invent their own error handling.

What still blocks the extraction is unchanged and is the part that actually needs design: the session state machine in AuthProvider is still React-only, and that is what Vue and Angular bindings would otherwise each reimplement and drift on.

One newly surfaced dependency: #92 asks whether provider helpers should throw or return results. That answer propagates directly into whatever the extracted bindings expose, so it is worth settling before this work starts rather than during it.