@superbuilders/primer-tives 4.0.2 → 4.0.4

package/README.md

@@ -2,14 +2,16 @@
 
 TypeScript SDK primitives for the Primer adaptive learning runtime.
 
-The public lifecycle starts with one async call and one optional auth transition:
+The public lifecycle starts with one async call and, when hosted auth is needed, one user-gesture auth transition:
 
 ```txt
-start(options) -> Promise<PrimerState>
-UnauthenticatedState.login() -> Promise<PrimerState>
+start(options with accessToken) -> Promise<AccessTokenStartState>
+start(options without accessToken) -> Promise<ManagedStartState>
+SignInRequiredState.login() -> Promise<ManagedStartState>
+SignInFailedState.login() -> Promise<ManagedStartState>
 ```
 
-`start` resolves existing learner auth when available, enters the first Primer learning state when the learner is ready, and returns the live state machine object your renderer drives. When learner sign-in is needed, `start` returns `UnauthenticatedState`; render a sign-in button and call `state.login()` directly from that button's click or tap handler.
+`start` enters the first Primer learning state when learner auth is ready and returns the live state machine object your renderer drives. When learner sign-in is needed, managed-auth `start` returns `SignInRequiredState`; render a sign-in button and call `state.login()` directly from that button's click or tap handler.
 
 ```sh
 bun add @superbuilders/primer-tives
@@ -17,7 +19,7 @@ bun add @superbuilders/primer-tives
 
 ## Version
 
-The current SDK version is `4.0.2`.
+The current SDK version is `4.0.4`.
 
 ## Entrypoints
 
@@ -25,7 +27,7 @@ There is no package-root export. Import from the public subpath that owns the su
 
 | Subpath | Owns |
 | --- | --- |
-| `@superbuilders/primer-tives/client` | `start`, `PrimerOptions`, `PrimerState`, all state interfaces, PCI render props |
+| `@superbuilders/primer-tives/client` | `start`, `PrimerOptions`, auth-specific start option types, `PrimerState`, all state interfaces, PCI render props |
 | `@superbuilders/primer-tives/contracts` | Content, stimulus, interaction, submission, review, PCI types, schemas, validation helpers |
 | `@superbuilders/primer-tives/errors` | Every SDK error sentinel |
 | `@superbuilders/primer-tives/logger` | `PrimerLogger` interface |
@@ -39,14 +41,18 @@ Math content can require the fraction-input PCI capability, so a math renderer m
 
 ```ts
 import { logger } from "@/logger"
-import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+import {
+	start,
+	type PrimerOptionsWithAccessToken,
+	type PrimerOptionsWithManagedAuth
+} from "@superbuilders/primer-tives/client"
 
 const options = {
 	publishableKey: "pk_...",
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+} satisfies PrimerOptionsWithManagedAuth<"math", readonly ["urn:primer:pci:fraction-input"]>
 
 let state = await start(options)
 ```
@@ -60,23 +66,23 @@ const options = {
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+} satisfies PrimerOptionsWithAccessToken<"math", readonly ["urn:primer:pci:fraction-input"]>
 
 let state = await start(options)
 ```
 
-When `start` returns `UnauthenticatedState`, render sign-in UI and call `login()` directly from a user gesture:
+When managed-auth `start` returns `SignInRequiredState`, render sign-in UI and call `login()` directly from a user gesture:
 
 ```ts
-import type { PrimerState, UnauthenticatedState } from "@superbuilders/primer-tives/client"
+import type { ManagedStartState, SignInRequiredState } from "@superbuilders/primer-tives/client"
 
-let state: PrimerState = await start(options)
+let state: ManagedStartState = await start(options)
 
-if (state.phase === "unauthenticated") {
+if (state.phase === "sign-in-required") {
 	renderSignInButton(state)
 }
 
-function handleSignInClick(authState: UnauthenticatedState): void {
+function handleSignInClick(authState: SignInRequiredState): void {
 	void authState.login().then(function continueAfterLogin(nextState) {
 		state = nextState
 		renderPrimer(state)
@@ -93,7 +99,7 @@ const options = {
 	publishableKey: "pk_...",
 	subject: "vocabulary",
 	logger
-} satisfies PrimerOptions<"vocabulary">
+} satisfies PrimerOptionsWithManagedAuth<"vocabulary">
 
 let state = await start(options)
 ```
@@ -105,7 +111,7 @@ const options = {
 	publishableKey: "pk_...",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-} satisfies PrimerOptions<undefined, readonly ["urn:primer:pci:fraction-input"]>
+} satisfies PrimerOptionsWithManagedAuth<undefined, readonly ["urn:primer:pci:fraction-input"]>
 
 let state = await start(options)
 ```
@@ -116,14 +122,22 @@ let state = await start(options)
 function start<
 	const S extends Subject | undefined = undefined,
 	const Supported extends readonly PciId[] = []
->(options: PrimerOptions<S, Supported>): Promise<PrimerState>
+>(options: PrimerOptionsWithAccessToken<S, Supported>): Promise<AccessTokenStartState>
+
+function start<
+	const S extends Subject | undefined = undefined,
+	const Supported extends readonly PciId[] = []
+>(options: PrimerOptionsWithManagedAuth<S, Supported>): Promise<ManagedStartState>
 ```
 
-`start` is the first SDK lifecycle operation. It may return any current state the renderer must handle:
+`start` is the first SDK lifecycle operation. Its return type depends on whether `accessToken` is present:
 
 | Result | Meaning |
 | --- | --- |
-| `UnauthenticatedState` | Learner sign-in is needed before runtime learning can begin. |
+| `SignInRequiredState` | Learner sign-in is needed before runtime learning can begin. Managed-auth mode only. |
+| `SignInFailedState` | Hosted sign-in failed but can be retried. Managed-auth mode only. |
+| `AuthUnavailableState` | Browser-hosted auth cannot run in the current runtime. Managed-auth mode only. |
+| `AuthConfigInvalidState` | Hosted-auth configuration is invalid and cannot be retried. Managed-auth mode only. |
 | `ObservationState`, `InteractionState`, or `FeedbackState` | A learning state is ready to render. |
 | `CompletedState` | The runtime scope is already complete. |
 | `ErroredState` | Startup or runtime communication failed but may be retriable. |
@@ -134,7 +148,7 @@ Always switch on `state.phase`. Do not assume the first state is renderable lear
 ```ts
 import * as errors from "@superbuilders/errors"
 import { logger } from "@/logger"
-import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+import { start, type PrimerOptionsWithAccessToken } from "@superbuilders/primer-tives/client"
 import { ErrAuthUnavailable, ErrMalformedAccessToken } from "@superbuilders/primer-tives/errors"
 
 const options = {
@@ -143,24 +157,15 @@ const options = {
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+} satisfies PrimerOptionsWithAccessToken<"math", readonly ["urn:primer:pci:fraction-input"]>
 
 let state = await start(options)
-if (state.phase === "unauthenticated") {
-	if (errors.is(state.error, ErrAuthUnavailable)) {
-		renderUnsupportedBrowserMessage()
-		return
-	}
-	renderSignInButton(state)
-	return
-}
-
 if (state.phase === "fatal") {
 	if (errors.is(state.error, ErrMalformedAccessToken)) {
 		renderSignInAgain()
 		return
 	}
-	logger.error("primer fatal state", { error: state.error })
+	logger.error({ error: state.error }, "primer fatal state")
 	throw state.error
 }
 ```
@@ -170,19 +175,28 @@ if (state.phase === "fatal") {
 ```ts
 type PrimerOptions<S extends Subject | undefined = undefined, Supported extends readonly PciId[] = []> = {
 	readonly publishableKey: string
-	readonly accessToken?: string
+	readonly origin?: string
 	readonly subject?: S
 	readonly supportedPcis: subject-dependent
 	readonly fetch?: typeof globalThis.fetch
 	readonly abort?: AbortController
 	readonly logger: PrimerLogger
 }
+
+type PrimerOptionsWithAccessToken<S, Supported> = PrimerOptions<S, Supported> & {
+	readonly accessToken: string
+}
+
+type PrimerOptionsWithManagedAuth<S, Supported> = PrimerOptions<S, Supported> & {
+	readonly accessToken?: undefined
+}
 ```
 
 | Field | Required | Meaning |
 | --- | --- | --- |
 | `publishableKey` | Yes | Public key identifying the Primer frontend your runtime belongs to. |
-| `accessToken` | No | Learner access token. When present, `start` uses it for the learning runtime. |
+| `origin` | No | Primer origin. Defaults to `https://primerlearn.dev`. |
+| `accessToken` | Mode-dependent | Learner access token. When present, `start` uses access-token mode. When absent, `start` uses managed hosted-auth mode. |
 | `subject` | No | Public content scope: `"math"`, `"vocabulary"`, or `"science"`. Omitted means all-subject scope. |
 | `supportedPcis` | Subject-dependent | Renderer capabilities for Portable Custom Interactions. Required when the chosen scope can emit required PCIs. |
 | `fetch` | No | Fetch override for tests, instrumentation, or host runtime integration. |
@@ -195,18 +209,18 @@ The SDK uses Primer's production runtime by default.
 
 | Shape | Semantics |
 | --- | --- |
-| `accessToken` present | `start` validates the token shape locally and uses it for learning runtime state. |
-| `accessToken` absent | `start` uses existing browser auth state when available, or returns `UnauthenticatedState` when learner sign-in is needed. |
+| `accessToken` present | `start` validates the token shape locally and returns `AccessTokenStartState`. This mode cannot return sign-in states. |
+| `accessToken` absent | `start` returns managed hosted-auth state or runtime state as `ManagedStartState`. This mode does not read browser storage and does not persist tokens. |
 
-The public API exposes auth as state behavior. `UnauthenticatedState.login()` is the sign-in transition.
+The public API exposes hosted auth as state behavior. `SignInRequiredState.login()` and `SignInFailedState.login()` are the sign-in transitions. `AuthUnavailableState` and `AuthConfigInvalidState` expose no login operation.
 
-When `subject` is present, it must be a concrete literal subject at the options declaration site. Do not pass a broad `Subject` value into `PrimerOptions`; narrow it in host control flow, then construct options with `satisfies PrimerOptions<"math", ...>`, `satisfies PrimerOptions<"vocabulary", ...>`, or `satisfies PrimerOptions<"science", ...>`.
+When `subject` is present, it must be a concrete literal subject at the options declaration site. Do not pass a broad `Subject` value into `PrimerOptions`; narrow it in host control flow, then construct options with `satisfies PrimerOptionsWithManagedAuth<"math", ...>`, `satisfies PrimerOptionsWithAccessToken<"math", ...>`, or the corresponding literal subject variant.
 
 ## Auth Semantics
 
 An access token is expected to be JWS-shaped: it starts with `eyJ` and contains exactly two dots. If a provided token does not match that shape, `start` returns `FatalState` with `ErrMalformedAccessToken`.
 
-SDK-managed auth may require browser capabilities and learner interaction. Auth failures are exposed through `UnauthenticatedState.error`:
+SDK-managed auth may require browser capabilities and learner interaction. Auth failures are represented by explicit auth states:
 
 | Sentinel | Meaning |
 | --- | --- |
@@ -230,7 +244,7 @@ import {
 } from "@superbuilders/primer-tives/errors"
 
 let state = await start(options)
-if (state.phase === "unauthenticated") {
+if (state.phase === "sign-in-failed") {
 	if (errors.is(state.error, ErrAuthPopupBlocked)) {
 		renderPopupInstructions(state)
 		return
@@ -239,13 +253,23 @@ if (state.phase === "unauthenticated") {
 		renderTryAgain(state)
 		return
 	}
-	if (errors.is(state.error, ErrAuthUnavailable)) {
-		renderUnsupportedBrowserMessage()
-		return
-	}
-	if (state.error !== null) {
-		logger.error("primer auth failed", { error: state.error })
-	}
+	logger.error({ error: state.error }, "primer auth failed")
+	renderSignInButton(state)
+	return
+}
+
+if (state.phase === "auth-unavailable") {
+	renderUnsupportedBrowserMessage(state.error)
+	return
+}
+
+if (state.phase === "auth-config-invalid") {
+	logger.error({ error: state.error }, "primer auth configuration invalid")
+	renderIntegrationError(state.error)
+	return
+}
+
+if (state.phase === "sign-in-required") {
 	renderSignInButton(state)
 }
 ```
@@ -297,7 +321,7 @@ const options = {
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+} satisfies PrimerOptionsWithManagedAuth<"math", readonly ["urn:primer:pci:fraction-input"]>
 
 await start(options)
 ```
@@ -317,9 +341,13 @@ async function runPrimer(initialState: PrimerState): Promise<void> {
 
 	while (state.phase !== "completed" && state.phase !== "fatal") {
 		switch (state.phase) {
-			case "unauthenticated":
-				renderSignInButton(state)
-				return
+		case "sign-in-required":
+		case "sign-in-failed":
+			renderSignInButton(state)
+			return
+		case "auth-unavailable":
+			renderUnsupportedBrowserMessage(state.error)
+			return
 			case "observation":
 				renderFrame(state.body, state.stimulus)
 				state = await state.advance()
@@ -336,13 +364,13 @@ async function runPrimer(initialState: PrimerState): Promise<void> {
 					state = await state.retry()
 					break
 				}
-				logger.error("primer state error", { error: state.error })
+				logger.error({ error: state.error }, "primer state error")
 				throw state.error
 		}
 	}
 
 	if (state.phase === "fatal") {
-		logger.error("primer fatal state", { error: state.error })
+		logger.error({ error: state.error }, "primer fatal state")
 		throw state.error
 	}
 }
@@ -352,7 +380,10 @@ State transitions:
 
 | Current state | Valid operation | Next result |
 | --- | --- | --- |
-| `UnauthenticatedState` | `login()` | `Promise<PrimerState>` |
+| `SignInRequiredState` | `login()` | `Promise<ManagedStartState>` |
+| `SignInFailedState` | `login()` | `Promise<ManagedStartState>` |
+| `AuthUnavailableState` | none | terminal for hosted auth in this runtime |
+| `AuthConfigInvalidState` | none | terminal for the current configuration |
 | `ObservationState` | `advance()` | `Promise<PrimerState>` |
 | `ChoiceState` | `submitChoice(selectedKeys)` or `timeout()` | `Promise<PrimerState>` |
 | `TextEntryState` | `submitText(value)` or `timeout()` | `Promise<PrimerState>` |
@@ -363,42 +394,48 @@ State transitions:
 | `PciInteractionState` | `submit(value)` or `timeout()` | `Promise<PrimerState>` |
 | `FeedbackState` | `advance()` | `Promise<PrimerState>` |
 | `CompletedState` | none | terminal |
-| `ErroredState` | `retry()` when `retriable` is `true` | `Promise<PrimerState>` |
+| `RetriableErroredState` | `retry()` | `Promise<PrimerState>` |
+| `NonRetriableErroredState` | none | terminal for the failed intent |
 | `FatalState` | none | terminal |
 
 ## `PrimerState`
 
 ```ts
 type PrimerState<Pcis extends PciId = PciId> =
-	| UnauthenticatedState<Pcis>
-	| ObservationState<Pcis>
-	| InteractionState<Pcis>
-	| FeedbackState<Pcis>
+	| SignInRequiredState<Pcis>
+	| SignInFailedState<Pcis>
+	| AuthUnavailableState
+	| AuthConfigInvalidState
+	| RuntimeState<Pcis>
 	| CompletedState
 	| ErroredState<Pcis>
 	| FatalState
+
+type RuntimeState<Pcis extends PciId = PciId> =
+	| ObservationState<Pcis>
+	| InteractionState<Pcis>
+	| FeedbackState<Pcis>
 ```
 
 `PrimerState` is live in-memory state. It contains transition closures, pending-operation guards, and retry behavior. Do not serialize it, store it, clone it through JSON, or pass it through host data. Calling `JSON.stringify(state)` throws `ErrNotSerializable`.
 
 Start a new state by calling `start` again after a reload, remount, account switch, or subject switch.
 
-## `UnauthenticatedState`
+## `SignInRequiredState`
 
 ```ts
-interface UnauthenticatedState<Pcis extends PciId = PciId> {
-	readonly phase: "unauthenticated"
-	readonly error: Error | null
-	login(): Promise<PrimerState<Pcis>>
+interface SignInRequiredState<Pcis extends PciId = PciId> {
+	readonly phase: "sign-in-required"
+	login(): Promise<ManagedStartState<Pcis>>
 }
 ```
 
-`UnauthenticatedState` means learner sign-in is required before learning content can be rendered. Render a sign-in button or equivalent learner action. Call `login()` only from that user action.
+`SignInRequiredState` means learner sign-in is required before learning content can be rendered. It has no `error` field because no sign-in attempt has failed. Render a sign-in button or equivalent learner action. Call `login()` only from that user action.
 
 Correct browser-safe pattern:
 
 ```ts
-function handleSignInClick(state: UnauthenticatedState): void {
+function handleSignInClick(state: SignInRequiredState): void {
 	void state.login().then(function continueAfterLogin(nextState) {
 		renderPrimer(nextState)
 	})
@@ -408,7 +445,7 @@ function handleSignInClick(state: UnauthenticatedState): void {
 React renderers should use the same direct-call rule:
 
 ```tsx
-function SignInButton({ state }: { state: UnauthenticatedState }) {
+function SignInButton({ state }: { state: SignInRequiredState }) {
 	async function handleClick() {
 		const nextState = await state.login()
 		renderPrimer(nextState)
@@ -437,7 +474,41 @@ async function handleClick() {
 }
 ```
 
-If `login()` cannot complete auth, it resolves to another `UnauthenticatedState` with `error` set to the auth sentinel. Render retry or unsupported-browser UI from that state.
+If `login()` fails in a retryable hosted-auth way, it resolves to `SignInFailedState`. If hosted auth cannot run in the current runtime, it resolves to `AuthUnavailableState`. If the public hosted-auth configuration is invalid, it resolves to `AuthConfigInvalidState`.
+
+## `SignInFailedState`
+
+```ts
+interface SignInFailedState<Pcis extends PciId = PciId> {
+	readonly phase: "sign-in-failed"
+	readonly error: Error
+	login(): Promise<ManagedStartState<Pcis>>
+}
+```
+
+`SignInFailedState` means a hosted sign-in attempt failed but another user gesture may retry it. Render the error and bind `login()` to a retry button.
+
+## `AuthUnavailableState`
+
+```ts
+interface AuthUnavailableState {
+	readonly phase: "auth-unavailable"
+	readonly error: Error
+}
+```
+
+`AuthUnavailableState` means the browser capabilities needed for hosted auth are unavailable. It does not expose `login()` because retrying the same operation cannot work in that runtime.
+
+## `AuthConfigInvalidState`
+
+```ts
+interface AuthConfigInvalidState {
+	readonly phase: "auth-config-invalid"
+	readonly error: Error
+}
+```
+
+`AuthConfigInvalidState` means hosted auth cannot run because the public configuration is invalid. It does not expose `login()` because retrying cannot fix invalid configuration.
 
 ## Common State Fields
 
@@ -730,17 +801,27 @@ Terminal state. There is no transition method.
 ## `ErroredState`
 
 ```ts
-interface ErroredState<Pcis extends PciId = PciId> {
+type ErroredState<Pcis extends PciId = PciId> =
+	| RetriableErroredState<Pcis>
+	| NonRetriableErroredState
+
+interface RetriableErroredState<Pcis extends PciId = PciId> {
 	readonly phase: "errored"
 	readonly error: Error
-	readonly retriable: boolean
+	readonly retriable: true
 	retry(): Promise<PrimerState<Pcis>>
 }
+
+interface NonRetriableErroredState {
+	readonly phase: "errored"
+	readonly error: Error
+	readonly retriable: false
+}
 ```
 
 `ErroredState` means the current learner intent could not complete, but the learning session itself is not necessarily terminal.
 
-If `retriable` is `true`, `retry()` repeats the exact failed intent. If `retriable` is `false`, `retry()` resolves to the same errored state.
+If `retriable` is `true`, `retry()` repeats the exact failed intent. If `retriable` is `false`, the state does not expose `retry()`.
 
 `ErrInvalidSubmission` is non-retriable because the submitted value was invalid for the active interaction. Renderer code should fix the payload before submitting again from a fresh interaction state.
 
@@ -922,7 +1003,7 @@ import { RendererSubmissionSchema } from "@superbuilders/primer-tives/contracts"
 
 const parsed = RendererSubmissionSchema.parse(payload)
 if (!parsed.success) {
-	logger.error("submission payload invalid", { error: parsed.error })
+	logger.error({ error: parsed.error }, "submission payload invalid")
 	throw errors.wrap(parsed.error, "submission payload")
 }
 
@@ -976,7 +1057,7 @@ import { ErrInvalidSubmission } from "@superbuilders/primer-tives/errors"
 const validation = validateSubmissionForInteraction(interaction, submission)
 if (!validation.ok) {
 	const message = submissionValidationMessage(validation)
-	logger.error("submission invalid", { issues: validation.issues })
+	logger.error({ issues: validation.issues }, "submission invalid")
 	throw errors.wrap(ErrInvalidSubmission, message)
 }
 ```
@@ -1200,23 +1281,31 @@ Handle auth-needed state before rendering learning content:
 ```ts
 let state = await start(options)
 
-if (state.phase === "unauthenticated") {
+if (state.phase === "sign-in-required") {
+	renderSignInButton(state)
+	return
+}
+
+if (state.phase === "sign-in-failed") {
 	if (errors.is(state.error, ErrAuthCancelled)) {
 		renderTryAgain(state)
 		return
 	}
-	if (state.error !== null) {
-		logger.error("primer auth needed", { error: state.error })
-	}
+	logger.error({ error: state.error }, "primer auth failed")
 	renderSignInButton(state)
 	return
 }
+
+if (state.phase === "auth-unavailable") {
+	renderUnsupportedBrowserMessage(state.error)
+	return
+}
 ```
 
 Bind login directly to the sign-in button:
 
 ```ts
-function handleSignInClick(state: UnauthenticatedState): void {
+function handleSignInClick(state: SignInRequiredState | SignInFailedState): void {
 	void state.login().then(function continueAfterLogin(nextState) {
 		renderPrimer(nextState)
 	})
@@ -1231,7 +1320,7 @@ if (state.phase === "errored") {
 		state = await state.retry()
 		return
 	}
-	logger.error("primer non-retriable state", { error: state.error })
+	logger.error({ error: state.error }, "primer non-retriable state")
 	throw state.error
 }
 
@@ -1244,7 +1333,7 @@ if (state.phase === "fatal") {
 		renderSdkUpgradeMessage()
 		return
 	}
-	logger.error("primer fatal state", { error: state.error })
+	logger.error({ error: state.error }, "primer fatal state")
 	throw state.error
 }
 ```
@@ -1267,25 +1356,20 @@ state = next
 ```ts
 import type { PrimerLogger } from "@superbuilders/primer-tives/logger"
 
-interface PrimerLogger {
-	debug(message: string, attributes?: Record<string, unknown>): void
-	info(message: string, attributes?: Record<string, unknown>): void
-	warn(message: string, attributes?: Record<string, unknown>): void
-	error(message: string, attributes?: Record<string, unknown>): void
-}
+type PrimerLogger = import("pino").Logger
 ```
 
-Pino through the central `@/logger` module matches this interface directly.
+Use a Pino-compatible logger. Pino calls are object-first when attributes are present.
 
 ```ts
 import { logger } from "@/logger"
-import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+import { start, type PrimerOptionsWithManagedAuth } from "@superbuilders/primer-tives/client"
 
 const options = {
 	publishableKey,
 	subject: "vocabulary",
 	logger
-} satisfies PrimerOptions<"vocabulary">
+} satisfies PrimerOptionsWithManagedAuth<"vocabulary">
 
 const state = await start(options)
 ```
@@ -1315,8 +1399,10 @@ The runtime exchange shape is not public SDK surface. Tests should assert SDK se
 
 | Scenario | Assert |
 | --- | --- |
-| auth is needed | `start` resolves to `UnauthenticatedState` |
-| auth login fails | `login()` resolves to `UnauthenticatedState` with the expected auth sentinel |
+| auth is needed | managed-auth `start` resolves to `SignInRequiredState` |
+| auth login fails | `login()` resolves to `SignInFailedState` with the expected auth sentinel |
+| auth cannot run | `login()` resolves to `AuthUnavailableState` |
+| auth config is invalid | `login()` resolves to `AuthConfigInvalidState` |
 | first runtime work fails recoverably | `start` resolves to `ErroredState` with `retriable: true` |
 | first runtime work fails terminally | `start` resolves to `FatalState` |
 | unsupported PCI is presented | `start` resolves to `FatalState` with `ErrUnsupportedPci` |
@@ -1328,7 +1414,7 @@ Example test shape:
 
 ```ts
 import * as errors from "@superbuilders/errors"
-import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+import { start, type PrimerOptionsWithAccessToken } from "@superbuilders/primer-tives/client"
 import { ErrUnsupportedPci } from "@superbuilders/primer-tives/errors"
 
 declare const fetchMock: typeof globalThis.fetch
@@ -1339,7 +1425,7 @@ const options = {
 	subject: "vocabulary",
 	fetch: fetchMock,
 	logger
-} satisfies PrimerOptions<"vocabulary">
+} satisfies PrimerOptionsWithAccessToken<"vocabulary">
 
 const state = await start(options)
 
@@ -1379,16 +1465,16 @@ grade level
 
 1. Import `start` and `PrimerOptions` from `@superbuilders/primer-tives/client`.
 2. Import shared renderer contracts from `@superbuilders/primer-tives/contracts`.
-3. Define options with `satisfies PrimerOptions<...>` so subject and PCI requirements stay visible at the declaration site.
+3. Define options with `satisfies PrimerOptionsWithManagedAuth<...>` or `satisfies PrimerOptionsWithAccessToken<...>` so subject and PCI requirements stay visible at the declaration site.
 4. Pass `publishableKey` and `logger` to `start`.
-5. Either pass `accessToken` or handle `UnauthenticatedState`.
+5. Either pass `accessToken` or handle managed-auth states.
 6. Choose a public `subject`, or omit `subject` for all-subject runtime scope.
 7. Declare every required renderer PCI in `supportedPcis`.
 8. Await `start` and render by switching on `state.phase`.
-9. If `state.phase === "unauthenticated"`, render sign-in UI and bind `state.login()` directly to the click or tap handler.
+9. If `state.phase === "sign-in-required"` or `"sign-in-failed"`, render sign-in UI and bind `state.login()` directly to the click or tap handler.
 10. For interaction states, render by switching on `state.kind`.
 11. Use only the transition methods exposed by the current state.
-12. Handle `ErroredState` through `retriable` and `retry()`.
+12. Handle `ErroredState` through `retriable`; call `retry()` only when `retriable` is `true`.
 13. Handle `FatalState` as terminal for the current state object.
 14. Never serialize `PrimerState`.
 15. Start a new state with `start` after reload, remount, account switch, or subject switch.
@@ -1401,9 +1487,9 @@ The current SDK intentionally does not expose:
 | --- | --- |
 | package-root exports | explicit public subpaths |
 | backend-only SDK surface | browser/client semantic SDK only |
-| public auth result union | `UnauthenticatedState` |
-| separate auth API object | `UnauthenticatedState.login()` |
-| client wrapper object | `start` returning `Promise<PrimerState>` |
+| separate auth API object | hosted-auth state variants with `login()` only on retryable sign-in states |
+| hosted-auth popup configuration | fixed popup defaults and current page redirect URI |
+| client wrapper object | `start` overloads returning live state |
 | `snapshot()` | live `PrimerState` only |
 | serializable state | start a new state with `start` |
 | public `"all"` subject value | omit `subject` |
@@ -1414,10 +1500,13 @@ The current SDK intentionally does not expose:
 
 ```txt
 start is the public lifecycle entrypoint
-start returns Promise<PrimerState>
+start returns AccessTokenStartState or ManagedStartState based on accessToken presence
 accessToken present is used for learner runtime auth
-accessToken absent may produce UnauthenticatedState
-UnauthenticatedState.login is the hosted-auth user-gesture transition
+accessToken present cannot produce hosted-auth states
+accessToken absent may produce SignInRequiredState
+SignInRequiredState.login and SignInFailedState.login are hosted-auth user-gesture transitions
+AuthUnavailableState has no login operation
+AuthConfigInvalidState has no login operation
 subject is optional; omitted means all-subject runtime scope
 subject determines required renderer PCI capabilities
 supportedPcis declares renderer PCI capabilities

package/dist/client/auth/browser.d.ts

@@ -1,17 +1,7 @@
 import type { PrimerLogger } from "../../logger";
-type HostedAuthOptions = {
-    readonly redirectUri?: string;
-    readonly storage?: Storage;
-    readonly currentUrl?: string;
-    readonly popupTarget?: string;
-    readonly popupFeatures?: string;
-    readonly popupTimeoutMs?: number;
-};
-declare function browserStorage(options: HostedAuthOptions | undefined, logger: PrimerLogger): Storage;
-declare function currentUrl(options: HostedAuthOptions | undefined, logger: PrimerLogger): URL;
-declare function redirectUri(options: HostedAuthOptions | undefined, url: URL, logger: PrimerLogger): string;
+declare function currentUrl(logger: PrimerLogger): URL;
+declare function redirectUri(url: URL): string;
 declare function randomClientState(logger: PrimerLogger): string;
-declare function openAuthPopup(url: string, options: HostedAuthOptions | undefined, logger: PrimerLogger): Window;
-export { browserStorage, currentUrl, openAuthPopup, randomClientState, redirectUri };
-export type { HostedAuthOptions };
+declare function openAuthPopup(url: string, logger: PrimerLogger): Window;
+export { currentUrl, openAuthPopup, randomClientState, redirectUri };
 //# sourceMappingURL=browser.d.ts.map

package/dist/client/auth/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/client/auth/browser.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAEtE,KAAK,iBAAiB,GAAG;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC,CAAA;AAED,iBAAS,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAS7F;AAED,iBAAS,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,GAAG,CAarF;AAED,iBAAS,WAAW,CACnB,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,YAAY,GAClB,MAAM,CASR;AAED,iBAAS,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAYvD;AAED,iBAAS,aAAa,CACrB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,MAAM,EAAE,YAAY,GAClB,MAAM,CAmBR;AAED,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAAA;AACpF,YAAY,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/client/auth/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAKtE,iBAAS,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAM7C;AAED,iBAAS,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAErC;AAED,iBAAS,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAYvD;AAED,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAWhE;AAED,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAAA"}