@superbuilders/primer-tives 4.0.3 → 4.0.5

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.3`.
+The current SDK version is `4.0.5`.
 
 ## 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,46 @@ 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` uses managed hosted-auth mode. It reads and writes the SDK-managed browser session token cache documented below. |
+
+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 PrimerOptionsWithManagedAuth<"math", ...>`, `satisfies PrimerOptionsWithAccessToken<"math", ...>`, or the corresponding literal subject variant.
+
+## Managed Auth Token Persistence
+
+Managed hosted auth is designed for browser-only consumers that do not have their own server-side token broker. When `accessToken` is absent, PrimerTives owns a session-scoped browser token cache with one fixed storage location:
+
+```txt
+sessionStorage["primer:access-token:<publishableKey>"]
+```
 
-The public API exposes auth as state behavior. `UnauthenticatedState.login()` is the sign-in transition.
+This is intentionally zero config. There is no storage selector and no persistence flag. Managed-auth mode always uses `globalThis.sessionStorage`; if `sessionStorage` is unavailable, `start` returns `AuthUnavailableState`.
 
-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", ...>`.
+The cache stores only the final Primer access token returned by hosted Timeback sign-in. OAuth transaction state, nonce, verifier, and callback validation state are not stored in browser storage; those remain server-managed by Primer.
+
+Managed-auth startup behavior is:
+
+| Situation | SDK behavior |
+| --- | --- |
+| Valid cached token exists | `start` uses it and enters the runtime without opening sign-in. |
+| No cached token exists | `start` returns `SignInRequiredState`. |
+| Cached token is malformed or expired | SDK clears the key and returns `SignInRequiredState`. |
+| Hosted sign-in succeeds | SDK validates the returned token, stores it at the documented key, then starts the runtime. |
+| Runtime rejects a managed cached token as expired or invalid | SDK clears the key and returns `SignInFailedState` so the app can ask the learner to sign in again. |
+
+Access-token mode bypasses this cache entirely. If `accessToken` is present in `start` options, PrimerTives does not read, write, or clear `sessionStorage`.
+
+The cached value is a bearer credential. Browser-only consumers get reload convenience from this default, but any script that can read the page can read the token. Host applications must maintain normal XSS protections and should use access-token mode if they need to own token storage themselves.
+
+The canonical managed sign-in endpoint is `/api/auth/timeback/start`. Legacy `/auth/timeback` URLs are not part of the PrimerTives 4.0.5 contract.
 
 ## 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 +272,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 +281,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 +349,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 +369,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 +392,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 +408,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 +422,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 +473,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 +502,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 +829,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 +1031,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 +1085,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 +1309,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 +1348,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 +1361,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 +1384,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 +1427,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 +1442,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 +1453,7 @@ const options = {
 	subject: "vocabulary",
 	fetch: fetchMock,
 	logger
-} satisfies PrimerOptions<"vocabulary">
+} satisfies PrimerOptionsWithAccessToken<"vocabulary">
 
 const state = await start(options)
 
@@ -1379,16 +1493,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 +1515,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 +1528,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