@superbuilders/primer-tives 3.5.1 → 3.6.0

package/README.md

@@ -2,13 +2,14 @@
 
 TypeScript SDK primitives for the Primer adaptive learning runtime.
 
-The public lifecycle is one async call:
+The public lifecycle starts with one async call and one optional auth transition:
 
 ```txt
-create(options) -> Promise<PrimerState>
+start(options) -> Promise<PrimerState>
+UnauthenticatedState.login() -> Promise<PrimerState>
 ```
 
-`create` resolves learner auth, opens the first Primer learning state, and returns the live state machine object your renderer drives.
+`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.
 
 ```sh
 bun add @superbuilders/primer-tives
@@ -16,7 +17,7 @@ bun add @superbuilders/primer-tives
 
 ## Version
 
-The current SDK version is `3.5.1`.
+The current SDK version is `3.6.0`.
 
 ## Entrypoints
 
@@ -24,7 +25,7 @@ There is no package-root export. Import from the public subpath that owns the su
 
 | Subpath | Owns |
 | --- | --- |
-| `@superbuilders/primer-tives/client` | `create`, `PrimerOptions`, `PrimerState`, all state interfaces, PCI render props |
+| `@superbuilders/primer-tives/client` | `start`, `PrimerOptions`, `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 |
@@ -38,100 +39,135 @@ Math content can require the fraction-input PCI capability, so a math renderer m
 
 ```ts
 import * as logger from "@superbuilders/slog"
-import { create } from "@superbuilders/primer-tives/client"
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
 
-let state = await create({
+const options = {
 	origin: "https://primerlearn.dev",
 	publishableKey: "pk_...",
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-})
+} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+
+let state = await start(options)
 ```
 
-If your application already has a learner access token, pass it directly. The SDK will use that token and skip SDK-managed auth.
+If your application already has a learner access token, pass it directly. `start` uses that token for the learning runtime.
 
 ```ts
-let state = await create({
+const options = {
 	origin: "https://primerlearn.dev",
 	publishableKey: "pk_...",
 	accessToken,
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-})
+} satisfies PrimerOptions<"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:
+
+```ts
+import type { PrimerState, UnauthenticatedState } from "@superbuilders/primer-tives/client"
+
+let state: PrimerState = await start(options)
+
+if (state.phase === "unauthenticated") {
+	renderSignInButton(state)
+}
+
+function handleSignInClick(authState: UnauthenticatedState): void {
+	void authState.login().then(function continueAfterLogin(nextState) {
+		state = nextState
+		renderPrimer(state)
+	})
+}
+```
+
+For Chrome and other popup blockers, `login()` must be called directly from the click or tap handler. Do not put `await`, `setTimeout`, dynamic imports, analytics calls, or other async work before `state.login()`.
+
 Vocabulary and science currently have no required PCI capabilities, so `supportedPcis` can be omitted for those subjects.
 
 ```ts
-let state = await create({
+const options = {
 	origin: "https://primerlearn.dev",
 	publishableKey: "pk_...",
 	subject: "vocabulary",
 	logger
-})
+} satisfies PrimerOptions<"vocabulary">
+
+let state = await start(options)
 ```
 
 Omitting `subject` means the SDK asks Primer for the all-subject runtime scope. Because that scope can include math, it requires the union of all subject-required PCIs.
 
 ```ts
-let state = await create({
+const options = {
 	origin: "https://primerlearn.dev",
 	publishableKey: "pk_...",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-})
+} satisfies PrimerOptions<undefined, readonly ["urn:primer:pci:fraction-input"]>
+
+let state = await start(options)
 ```
 
-## `create(options)`
+## `start(options)`
 
 ```ts
-function create<
+function start<
 	const S extends Subject | undefined = undefined,
 	const Supported extends readonly PciId[] = []
 >(options: PrimerOptions<S, Supported>): Promise<PrimerState>
 ```
 
-`create` can fail in two different ways:
+`start` is the first SDK lifecycle operation. It may return any current state the renderer must handle:
 
-| Moment | Behavior |
+| Result | Meaning |
 | --- | --- |
-| Auth or local token resolution fails | `create` rejects with an SDK sentinel error. |
-| The learning runtime cannot produce a normal first state | `create` resolves to `ErroredState` or `FatalState`. |
+| `UnauthenticatedState` | Learner sign-in is needed before runtime learning can begin. |
+| `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. |
+| `FatalState` | Startup or runtime communication failed terminally for this state object. |
 
-This distinction matters. Use `errors.try(create(...))` for startup failures, then handle `state.phase` for learning-state failures.
+Always switch on `state.phase`. Do not assume the first state is renderable learning content.
 
 ```ts
 import * as errors from "@superbuilders/errors"
 import * as logger from "@superbuilders/slog"
-import { create } from "@superbuilders/primer-tives/client"
-import { ErrAuthPopupBlocked, ErrMalformedAccessToken } from "@superbuilders/primer-tives/errors"
-
-const result = await errors.try(
-	create({
-		origin,
-		publishableKey,
-		accessToken,
-		subject: "math",
-		supportedPcis: ["urn:primer:pci:fraction-input"],
-		logger
-	})
-)
-if (result.error) {
-	if (errors.is(result.error, ErrAuthPopupBlocked)) {
-		renderStartButtonAgain()
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+import { ErrAuthUnavailable, ErrMalformedAccessToken } from "@superbuilders/primer-tives/errors"
+
+const options = {
+	origin,
+	publishableKey,
+	accessToken,
+	subject: "math",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+
+let state = await start(options)
+if (state.phase === "unauthenticated") {
+	if (errors.is(state.error, ErrAuthUnavailable)) {
+		renderUnsupportedBrowserMessage()
 		return
 	}
-	if (errors.is(result.error, ErrMalformedAccessToken)) {
+	renderSignInButton(state)
+	return
+}
+
+if (state.phase === "fatal") {
+	if (errors.is(state.error, ErrMalformedAccessToken)) {
 		renderSignInAgain()
 		return
 	}
-	logger.error("primer create failed", { error: result.error })
-	throw result.error
+	logger.error("primer fatal state", { error: state.error })
+	throw state.error
 }
-
-let state = result.data
 ```
 
 ## `PrimerOptions`
@@ -153,27 +189,29 @@ type PrimerOptions<S extends Subject | undefined = undefined, Supported extends
 | --- | --- | --- |
 | `origin` | Yes | Primer deployment origin. |
 | `publishableKey` | Yes | Public key identifying the Primer frontend your runtime belongs to. |
-| `accessToken` | No | Learner access token. When present, SDK-managed auth is skipped. |
+| `accessToken` | No | Learner access token. When present, `start` uses it for the learning runtime. |
 | `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. |
 | `abort` | No | Abort controller for SDK runtime work. |
 | `logger` | Yes | Structured logger implementing `debug`, `info`, `warn`, and `error`. |
 
-The presence or absence of `accessToken` selects auth semantics.
+The presence or absence of `accessToken` selects startup auth semantics.
 
 | Shape | Semantics |
 | --- | --- |
-| `accessToken` present | The SDK validates the token shape locally and uses it for learning runtime state. |
-| `accessToken` absent | The SDK resolves a learner token through SDK-managed browser auth, then starts learning runtime state. |
+| `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. |
+
+The public API exposes auth as state behavior. `UnauthenticatedState.login()` is the sign-in transition.
 
-The public API does not expose separate auth plumbing, auth result objects, or any auth lifecycle method. Auth is part of `create`.
+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", ...>`.
 
 ## Auth Semantics
 
-An access token is expected to be JWS-shaped: it starts with `eyJ` and contains exactly two dots. If a provided or SDK-managed token does not match that shape, `create` rejects with `ErrMalformedAccessToken`.
+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. These failures reject `create`:
+SDK-managed auth may require browser capabilities and learner interaction. Auth failures are exposed through `UnauthenticatedState.error`:
 
 | Sentinel | Meaning |
 | --- | --- |
@@ -196,22 +234,24 @@ import {
 	ErrAuthUnavailable
 } from "@superbuilders/primer-tives/errors"
 
-const result = await errors.try(create(options))
-if (result.error) {
-	if (errors.is(result.error, ErrAuthPopupBlocked)) {
-		renderPopupInstructions()
+let state = await start(options)
+if (state.phase === "unauthenticated") {
+	if (errors.is(state.error, ErrAuthPopupBlocked)) {
+		renderPopupInstructions(state)
 		return
 	}
-	if (errors.is(result.error, ErrAuthCancelled)) {
-		renderTryAgain()
+	if (errors.is(state.error, ErrAuthCancelled)) {
+		renderTryAgain(state)
 		return
 	}
-	if (errors.is(result.error, ErrAuthUnavailable)) {
+	if (errors.is(state.error, ErrAuthUnavailable)) {
 		renderUnsupportedBrowserMessage()
 		return
 	}
-	logger.error("primer auth failed", { error: result.error })
-	throw result.error
+	if (state.error !== null) {
+		logger.error("primer auth failed", { error: state.error })
+	}
+	renderSignInButton(state)
 }
 ```
 
@@ -247,7 +287,7 @@ Order does not matter. Extra supported PCIs are allowed. `supportedPcis` is a re
 This fails at compile time because math can emit a required PCI:
 
 ```ts
-await create({
+await start({
 	origin,
 	publishableKey,
 	subject: "math",
@@ -258,27 +298,15 @@ await create({
 This passes:
 
 ```ts
-await create({
+const options = {
 	origin,
 	publishableKey,
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-})
-```
-
-If `subject` is a broad dynamic `Subject` value, TypeScript requires support for the union of all PCIs required by the possible subjects.
+} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
 
-```ts
-declare const subject: Subject
-
-await create({
-	origin,
-	publishableKey,
-	subject,
-	supportedPcis: ["urn:primer:pci:fraction-input"],
-	logger
-})
+await start(options)
 ```
 
 The runtime also protects the trust boundary. If Primer presents a portable custom interaction that is not declared in `supportedPcis`, the SDK returns `FatalState` with `ErrUnsupportedPci`.
@@ -296,6 +324,9 @@ async function runPrimer(initialState: PrimerState): Promise<void> {
 
 	while (state.phase !== "completed" && state.phase !== "fatal") {
 		switch (state.phase) {
+			case "unauthenticated":
+				renderSignInButton(state)
+				return
 			case "observation":
 				renderFrame(state.body, state.stimulus)
 				state = await state.advance()
@@ -328,6 +359,7 @@ State transitions:
 
 | Current state | Valid operation | Next result |
 | --- | --- | --- |
+| `UnauthenticatedState` | `login()` | `Promise<PrimerState>` |
 | `ObservationState` | `advance()` | `Promise<PrimerState>` |
 | `ChoiceState` | `submitChoice(selectedKeys)` or `timeout()` | `Promise<PrimerState>` |
 | `TextEntryState` | `submitText(value)` or `timeout()` | `Promise<PrimerState>` |
@@ -345,6 +377,7 @@ State transitions:
 
 ```ts
 type PrimerState<Pcis extends PciId = PciId> =
+	| UnauthenticatedState<Pcis>
 	| ObservationState<Pcis>
 	| InteractionState<Pcis>
 	| FeedbackState<Pcis>
@@ -355,7 +388,63 @@ type PrimerState<Pcis extends PciId = PciId> =
 
 `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`.
 
-Recreate state by calling `create` again after a reload, remount, account switch, or subject switch.
+Start a new state by calling `start` again after a reload, remount, account switch, or subject switch.
+
+## `UnauthenticatedState`
+
+```ts
+interface UnauthenticatedState<Pcis extends PciId = PciId> {
+	readonly phase: "unauthenticated"
+	readonly error: Error | null
+	login(): Promise<PrimerState<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.
+
+Correct browser-safe pattern:
+
+```ts
+function handleSignInClick(state: UnauthenticatedState): void {
+	void state.login().then(function continueAfterLogin(nextState) {
+		renderPrimer(nextState)
+	})
+}
+```
+
+React renderers should use the same direct-call rule:
+
+```tsx
+function SignInButton({ state }: { state: UnauthenticatedState }) {
+	async function handleClick() {
+		const nextState = await state.login()
+		renderPrimer(nextState)
+	}
+
+	return <button type="button" onClick={handleClick}>Sign in to continue</button>
+}
+```
+
+For Chrome popup blocking, `state.login()` must be the first async-producing operation in the click or tap handler. This is correct:
+
+```ts
+async function handleClick() {
+	const nextState = await state.login()
+	renderPrimer(nextState)
+}
+```
+
+This is not browser-safe:
+
+```ts
+async function handleClick() {
+	await recordAnalyticsClick()
+	const nextState = await state.login()
+	renderPrimer(nextState)
+}
+```
+
+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.
 
 ## Common State Fields
 
@@ -672,7 +761,7 @@ interface FatalState {
 }
 ```
 
-Fatal state means the SDK cannot recover by retrying the current learner intent. Render a terminal error UI, require a new `create` call, or send the learner through auth again depending on the sentinel.
+Fatal state means the SDK cannot recover by retrying the current learner intent. Render a terminal error UI, call `start` again with valid options, or send the learner through auth again depending on the sentinel.
 
 Fatal sentinels:
 
@@ -1010,7 +1099,7 @@ type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRe
 
 ## Subject PCI Helpers
 
-Use `@superbuilders/primer-tives/subject-pcis` when renderer tooling needs the same subject-to-PCI contract as `create`.
+Use `@superbuilders/primer-tives/subject-pcis` when renderer tooling needs the same subject-to-PCI contract as `start`.
 
 ```ts
 import {
@@ -1073,17 +1162,17 @@ import {
 } from "@superbuilders/primer-tives/errors"
 ```
 
-## Create-Time Errors
+## Auth And Startup Errors
 
-These are most often thrown by `create` before a `PrimerState` exists.
+Auth and startup failures are represented as state whenever possible.
 
 | Sentinel | Meaning | Typical handling |
 | --- | --- | --- |
-| `ErrAuthUnavailable` | SDK-managed auth cannot run in the current host environment. | Show unsupported-runtime or fallback sign-in UI. |
+| `ErrAuthUnavailable` | SDK-managed auth cannot run in the current host environment. | Render unsupported-runtime or externally managed sign-in UI. |
 | `ErrAuthConfigInvalid` | Public auth configuration is invalid. | Log and treat as integration error. |
 | `ErrAuthCallbackInvalid` | Learner auth did not complete with an acceptable result. | Offer sign-in retry; log if unexpected. |
-| `ErrAuthStateMismatch` | Auth result does not match the initiated auth attempt. | Restart auth. |
-| `ErrAuthPopupBlocked` | Browser blocked learner auth UI. | Ask learner to allow popups or retry from a user gesture. |
+| `ErrAuthStateMismatch` | Auth result does not match the initiated auth attempt. | Offer sign-in retry. |
+| `ErrAuthPopupBlocked` | Browser blocked learner auth UI. | Render sign-in instructions and retry from a direct user gesture. |
 | `ErrAuthCancelled` | Learner auth was closed or timed out. | Offer retry. |
 | `ErrMalformedAccessToken` | Provided or resolved token is not shaped like a learner access token. | Re-authenticate learner or fix token source. |
 
@@ -1112,20 +1201,32 @@ Runtime errors are represented as `ErroredState` or `FatalState`.
 
 ## Error-Handling Recipes
 
-Handle create-time errors before using state:
+Handle auth-needed state before rendering learning content:
 
 ```ts
-const result = await errors.try(create(options))
-if (result.error) {
-	if (errors.is(result.error, ErrAuthCancelled)) {
-		renderTryAgain()
+let state = await start(options)
+
+if (state.phase === "unauthenticated") {
+	if (errors.is(state.error, ErrAuthCancelled)) {
+		renderTryAgain(state)
 		return
 	}
-	logger.error("primer create failed", { error: result.error })
-	throw result.error
+	if (state.error !== null) {
+		logger.error("primer auth needed", { error: state.error })
+	}
+	renderSignInButton(state)
+	return
 }
+```
+
+Bind login directly to the sign-in button:
 
-let state = result.data
+```ts
+function handleSignInClick(state: UnauthenticatedState): void {
+	void state.login().then(function continueAfterLogin(nextState) {
+		renderPrimer(nextState)
+	})
+}
 ```
 
 Handle runtime errors through the state machine:
@@ -1184,13 +1285,16 @@ interface PrimerLogger {
 
 ```ts
 import * as logger from "@superbuilders/slog"
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
 
-const state = await create({
+const options = {
 	origin,
 	publishableKey,
 	subject: "vocabulary",
 	logger
-})
+} satisfies PrimerOptions<"vocabulary">
+
+const state = await start(options)
 ```
 
 ## Grade Levels
@@ -1208,20 +1312,21 @@ const GRADE_LEVELS = ["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "1
 type GradeLevel = (typeof GRADE_LEVELS)[number]
 ```
 
-Grade level is not a `create` option. Treat grade-level identifiers as content/runtime data when Primer presents them, not as an SDK lifecycle input.
+Grade level is not a `start` option. Treat grade-level identifiers as content/runtime data when Primer presents them, not as an SDK lifecycle input.
 
 ## Testing
 
-`PrimerOptions.fetch` exists so tests, host runtimes, and instrumentation can provide a fetch-compatible function. The SDK treats it exactly as the runtime communication function for `create`, transitions, submissions, retries, and timeouts.
+`PrimerOptions.fetch` exists so tests, host runtimes, and instrumentation can provide a fetch-compatible function. The SDK treats it exactly as the runtime communication function for `start`, transitions, submissions, retries, and timeouts.
 
-The runtime exchange shape is not public SDK surface. Tests should assert SDK semantics after `create` resolves or rejects:
+The runtime exchange shape is not public SDK surface. Tests should assert SDK semantics after `start` resolves:
 
 | Scenario | Assert |
 | --- | --- |
-| auth fails | `create` rejects with the expected auth sentinel |
-| first runtime work fails recoverably | `create` resolves to `ErroredState` with `retriable: true` |
-| first runtime work fails terminally | `create` resolves to `FatalState` |
-| unsupported PCI is presented | `create` resolves to `FatalState` with `ErrUnsupportedPci` |
+| auth is needed | `start` resolves to `UnauthenticatedState` |
+| auth login fails | `login()` resolves to `UnauthenticatedState` with the expected auth sentinel |
+| 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` |
 | standard submission is invalid | submit method resolves to `ErroredState` with `ErrInvalidSubmission` |
 | concurrent submit/timeout conflict occurs | transition resolves to `ErroredState` with `ErrConflict` |
 | state is serialized | serialization throws `ErrNotSerializable` |
@@ -1230,19 +1335,21 @@ Example test shape:
 
 ```ts
 import * as errors from "@superbuilders/errors"
-import { create } from "@superbuilders/primer-tives/client"
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
 import { ErrUnsupportedPci } from "@superbuilders/primer-tives/errors"
 
 declare const fetchMock: typeof globalThis.fetch
 
-const state = await create({
+const options = {
 	origin: "https://primer.test",
 	publishableKey: "pk_test",
 	accessToken: "eyJ.test.token",
-	subject: "math",
+	subject: "vocabulary",
 	fetch: fetchMock,
 	logger
-})
+} satisfies PrimerOptions<"vocabulary">
+
+const state = await start(options)
 
 if (state.phase === "fatal") {
 	if (errors.is(state.error, ErrUnsupportedPci)) {
@@ -1278,20 +1385,21 @@ grade level
 
 ## Integration Checklist
 
-1. Import `create` from `@superbuilders/primer-tives/client`.
+1. Import `start` and `PrimerOptions` from `@superbuilders/primer-tives/client`.
 2. Import shared renderer contracts from `@superbuilders/primer-tives/contracts`.
-3. Pass `origin`, `publishableKey`, and `logger` to `create`.
-4. Either pass `accessToken` or let `create` perform SDK-managed auth.
-5. Choose a public `subject`, or omit `subject` for all-subject runtime scope.
-6. Declare every required renderer PCI in `supportedPcis`.
-7. Await `create` and handle create-time errors with `errors.try`.
-8. Render by switching on `state.phase`.
-9. For interaction states, render by switching on `state.kind`.
-10. Use only the transition methods exposed by the current state.
-11. Handle `ErroredState` through `retriable` and `retry()`.
-12. Handle `FatalState` as terminal for the current state object.
-13. Never serialize `PrimerState`.
-14. Recreate state with `create` after reload, remount, account switch, or subject switch.
+3. Define options with `satisfies PrimerOptions<...>` so subject and PCI requirements stay visible at the declaration site.
+4. Pass `origin`, `publishableKey`, and `logger` to `start`.
+5. Either pass `accessToken` or handle `UnauthenticatedState`.
+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.
+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()`.
+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.
 
 ## What This SDK Does Not Expose
 
@@ -1301,12 +1409,11 @@ 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 | `create` |
-| separate auth API | `create` |
-| client wrapper object | `create` returning `Promise<PrimerState>` |
-| `start()` | `create` already starts the first state |
+| public auth result union | `UnauthenticatedState` |
+| separate auth API object | `UnauthenticatedState.login()` |
+| client wrapper object | `start` returning `Promise<PrimerState>` |
 | `snapshot()` | live `PrimerState` only |
-| serializable state | recreate with `create` |
+| serializable state | start a new state with `start` |
 | public `"all"` subject value | omit `subject` |
 | implicit PCI negotiation | explicit `supportedPcis` |
 | grade-level lifecycle option | runtime content/state handling |
@@ -1314,10 +1421,11 @@ The current SDK intentionally does not expose:
 ## Final Invariants
 
 ```txt
-create is the only public lifecycle operation
-create returns Promise<PrimerState>
-accessToken present skips SDK-managed auth
-accessToken absent uses SDK-managed auth
+start is the public lifecycle entrypoint
+start returns Promise<PrimerState>
+accessToken present is used for learner runtime auth
+accessToken absent may produce UnauthenticatedState
+UnauthenticatedState.login is the hosted-auth user-gesture transition
 subject is optional; omitted means all-subject runtime scope
 subject determines required renderer PCI capabilities
 supportedPcis declares renderer PCI capabilities

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

@@ -8,7 +8,22 @@ type AccessTokenResolverOptions = {
     readonly hostedAuth?: HostedAuthOptions;
     readonly logger: PrimerLogger;
 };
-declare function resolveRuntimeAccessToken(options: AccessTokenResolverOptions): Promise<ResolvedAccessToken>;
-export { resolveRuntimeAccessToken };
-export type { AccessTokenResolverOptions };
+type ResolvedAccessTokenResult = {
+    readonly kind: "resolved";
+    readonly accessToken: ResolvedAccessToken;
+};
+type UnauthenticatedAccessTokenResult = {
+    readonly kind: "unauthenticated";
+    readonly error: Error | null;
+};
+type FatalAccessTokenResult = {
+    readonly kind: "fatal";
+    readonly error: Error;
+};
+type ExistingAccessTokenResult = ResolvedAccessTokenResult | UnauthenticatedAccessTokenResult | FatalAccessTokenResult;
+type HostedLoginResult = ResolvedAccessTokenResult | UnauthenticatedAccessTokenResult;
+declare function resolveExistingAccessToken(options: AccessTokenResolverOptions): ExistingAccessTokenResult;
+declare function beginHostedLogin(options: AccessTokenResolverOptions): Promise<HostedLoginResult>;
+export { beginHostedLogin, resolveExistingAccessToken };
+export type { AccessTokenResolverOptions, ExistingAccessTokenResult, HostedLoginResult };
 //# sourceMappingURL=provider.d.ts.map