@superbuilders/primer-tives 3.5.0 → 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 frame, and returns a live learning state. There is no public auth result union, client wrapper, `start()` method, `snapshot()` API, or branded state type.
+`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,80 +17,163 @@ bun add @superbuilders/primer-tives
 
 ## Version
 
-The current SDK version is `3.5.0`.
-
-The SDK sends `X-Primer-SDK-Version: 3.5.0` on `/api/v0/advance`.
+The current SDK version is `3.6.0`.
 
 ## Entrypoints
 
-There is no package-root export.
+There is no package-root export. Import from the public subpath that owns the surface you need.
 
 | Subpath | Owns |
 | --- | --- |
-| `@superbuilders/primer-tives/client` | `create`, `PrimerOptions`, `PrimerState`, state interfaces, PCI render props |
-| `@superbuilders/primer-tives/contracts` | Content, stimulus, interaction, submission, review, PCI types, validation helpers |
-| `@superbuilders/primer-tives/errors` | SDK error sentinels |
+| `@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 |
 | `@superbuilders/primer-tives/subject` | `Subject`, `SUBJECTS` |
-| `@superbuilders/primer-tives/subject-pcis` | Subject-required PCI helpers |
+| `@superbuilders/primer-tives/subject-pcis` | Subject-required PCI helpers and type helpers |
 | `@superbuilders/primer-tives/grade-level` | `GradeLevel`, `GRADE_LEVELS` |
 
 ## Quick Start
 
-Math requires the fraction-input PCI capability:
+Math content can require the fraction-input PCI capability, so a math renderer must declare it.
 
 ```ts
 import * as logger from "@superbuilders/slog"
-import { create } from "@superbuilders/primer-tives/client"
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
 
-const 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 you already have a Cognito/OIDC access token, pass it directly:
+If your application already has a learner access token, pass it directly. `start` uses that token for the learning runtime.
 
 ```ts
-const 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)
 ```
 
-Vocabulary has no required PCI capability, so `supportedPcis` can be omitted:
+When `start` returns `UnauthenticatedState`, render sign-in UI and call `login()` directly from a user gesture:
 
 ```ts
-const state = await create({
+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
+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 internal all-subject runtime scope. Because that can include any subject, the required PCI set is the union of all subject-required PCIs:
+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
-const 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)
+```
+
+## `start(options)`
+
+```ts
+function start<
+	const S extends Subject | undefined = undefined,
+	const Supported extends readonly PciId[] = []
+>(options: PrimerOptions<S, Supported>): Promise<PrimerState>
+```
+
+`start` is the first SDK lifecycle operation. It may return any current state the renderer must handle:
+
+| Result | Meaning |
+| --- | --- |
+| `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. |
+
+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 { 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
+	}
+	renderSignInButton(state)
+	return
+}
+
+if (state.phase === "fatal") {
+	if (errors.is(state.error, ErrMalformedAccessToken)) {
+		renderSignInAgain()
+		return
+	}
+	logger.error("primer fatal state", { error: state.error })
+	throw state.error
+}
 ```
 
-## PrimerOptions
+## `PrimerOptions`
 
 ```ts
-type PrimerOptions<S extends Subject | undefined = undefined, Pcis extends PciId = never> = {
+type PrimerOptions<S extends Subject | undefined = undefined, Supported extends readonly PciId[] = []> = {
 	readonly origin: string
 	readonly publishableKey: string
 	readonly accessToken?: string
@@ -101,53 +185,109 @@ type PrimerOptions<S extends Subject | undefined = undefined, Pcis extends PciId
 }
 ```
 
-| Field | Meaning |
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `origin` | Yes | Primer deployment origin. |
+| `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. |
+| `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 startup auth semantics.
+
+| Shape | Semantics |
 | --- | --- |
-| `origin` | Primer deployment origin. |
-| `publishableKey` | Public Primer frontend key. |
-| `accessToken` | Optional Cognito/OIDC learner access token. When present, hosted auth is skipped. |
-| `subject` | Optional content scope. Omitted means internal all-subject scope. Public callers do not pass `"all"`. |
-| `supportedPcis` | Renderer PCI capabilities. Required or optional based on `subject`. |
-| `fetch` | Optional fetch override for tests/instrumentation. |
-| `abort` | Optional abort controller for runtime requests. |
-| `logger` | Structured logger implementing `debug`, `info`, `warn`, and `error`. |
-
-The presence or absence of `accessToken` selects auth behavior:
-
-| Shape | Behavior |
+| `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.
+
+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 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`:
+
+| Sentinel | Meaning |
 | --- | --- |
-| `accessToken` present | Use provided access token, then call `/api/v0/advance`. |
-| `accessToken` absent | Resolve a token through Primer-hosted auth, then call `/api/v0/advance`. |
+| `ErrAuthUnavailable` | SDK-managed auth requires browser functionality that is unavailable in the current runtime. |
+| `ErrAuthConfigInvalid` | SDK-managed auth was given invalid public configuration. |
+| `ErrAuthCallbackInvalid` | The auth result could not be accepted as a successful learner auth result. |
+| `ErrAuthStateMismatch` | The auth result did not match the auth attempt that initiated it. |
+| `ErrAuthPopupBlocked` | The browser blocked the learner auth window. |
+| `ErrAuthCancelled` | The learner auth interaction was closed or exceeded its allowed time. |
+| `ErrMalformedAccessToken` | The resolved token was not shaped like a learner access token. |
 
-Hosted auth storage, callback parsing, popup details, and state handling are SDK internals.
+Applications should handle user-actionable auth failures directly and log unexpected failures before propagating them.
+
+```ts
+import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import {
+	ErrAuthCancelled,
+	ErrAuthPopupBlocked,
+	ErrAuthUnavailable
+} from "@superbuilders/primer-tives/errors"
+
+let state = await start(options)
+if (state.phase === "unauthenticated") {
+	if (errors.is(state.error, ErrAuthPopupBlocked)) {
+		renderPopupInstructions(state)
+		return
+	}
+	if (errors.is(state.error, ErrAuthCancelled)) {
+		renderTryAgain(state)
+		return
+	}
+	if (errors.is(state.error, ErrAuthUnavailable)) {
+		renderUnsupportedBrowserMessage()
+		return
+	}
+	if (state.error !== null) {
+		logger.error("primer auth failed", { error: state.error })
+	}
+	renderSignInButton(state)
+}
+```
 
 ## Subject And PCI Contract
 
 `subject` selects content scope and determines required renderer capabilities.
 
-`supportedPcis` declares which Portable Custom Interactions the host renderer can render. It may be a superset of the required PCIs.
+```ts
+import { SUBJECTS } from "@superbuilders/primer-tives/subject"
+import type { Subject } from "@superbuilders/primer-tives/subject"
 
-The SDK enforces subject-required PCI capability in TypeScript:
+const subjects = SUBJECTS
+type RuntimeSubject = Subject
+```
+
+Current public subjects:
 
-| Public subject option | Required `supportedPcis` |
+| Subject | Required PCI support |
 | --- | --- |
-| omitted | union of all subject-required PCIs, currently `"urn:primer:pci:fraction-input"` |
 | `"math"` | `"urn:primer:pci:fraction-input"` |
 | `"vocabulary"` | none |
 | `"science"` | none |
+| omitted subject | union of all subject-required PCIs, currently `"urn:primer:pci:fraction-input"` |
 
-The check is a subset check:
+The type-level rule is a subset check:
 
 ```txt
-required PCIs for subject ⊆ supportedPcis
+required PCIs for selected scope <= supportedPcis
 ```
 
-Order does not matter. Extra supported PCIs are allowed.
+Order does not matter. Extra supported PCIs are allowed. `supportedPcis` is a renderer capability declaration, not a content request.
 
-This fails at compile time:
+This fails at compile time because math can emit a required PCI:
 
 ```ts
-await create({
+await start({
 	origin,
 	publishableKey,
 	subject: "math",
@@ -158,25 +298,86 @@ await create({
 This passes:
 
 ```ts
-await create({
+const options = {
 	origin,
 	publishableKey,
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
-})
+} satisfies PrimerOptions<"math", readonly ["urn:primer:pci:fraction-input"]>
+
+await start(options)
 ```
 
-If `subject` is a broad dynamic `Subject` value, TypeScript requires the union of possible subject-required PCIs. This lets renderer wrappers pass their full supported PCI registry once and get subject-level safety for free.
+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`.
+
+## Runtime Loop
+
+Every renderer should switch on `state.phase`. Interaction rendering should then switch on `state.kind`.
 
-The runtime still protects the trust boundary. If the server returns a PCI not declared in `supportedPcis`, the SDK returns `FatalState` with `ErrUnsupportedPci`.
+```ts
+import * as logger from "@superbuilders/slog"
+import type { PrimerState } from "@superbuilders/primer-tives/client"
+
+async function runPrimer(initialState: PrimerState): Promise<void> {
+	let state = initialState
+
+	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()
+				break
+			case "interaction":
+				state = await renderAndSubmitInteraction(state)
+				break
+			case "feedback":
+				renderFeedback(state.feedbackContent, state.isCorrect, state.review)
+				state = await state.advance()
+				break
+			case "errored":
+				if (state.retriable) {
+					state = await state.retry()
+					break
+				}
+				logger.error("primer state error", { error: state.error })
+				throw state.error
+		}
+	}
 
-## PrimerState
+	if (state.phase === "fatal") {
+		logger.error("primer fatal state", { error: state.error })
+		throw state.error
+	}
+}
+```
 
-`create` returns a `PrimerState` only after auth and the first runtime request have succeeded.
+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>` |
+| `ExtendedTextSingleState` | `submitText(value)` or `timeout()` | `Promise<PrimerState>` |
+| `ExtendedTextMultipleState` | `submitTexts(values)` or `timeout()` | `Promise<PrimerState>` |
+| `OrderState` | `submitOrder(orderedKeys)` or `timeout()` | `Promise<PrimerState>` |
+| `MatchState` | `submitMatch(pairs)` or `timeout()` | `Promise<PrimerState>` |
+| `PciInteractionState` | `submit(value)` or `timeout()` | `Promise<PrimerState>` |
+| `FeedbackState` | `advance()` | `Promise<PrimerState>` |
+| `CompletedState` | none | terminal |
+| `ErroredState` | `retry()` when `retriable` is `true` | `Promise<PrimerState>` |
+| `FatalState` | none | terminal |
+
+## `PrimerState`
 
 ```ts
 type PrimerState<Pcis extends PciId = PciId> =
+	| UnauthenticatedState<Pcis>
 	| ObservationState<Pcis>
 	| InteractionState<Pcis>
 	| FeedbackState<Pcis>
@@ -185,168 +386,976 @@ type PrimerState<Pcis extends PciId = PciId> =
 	| FatalState
 ```
 
-The state machine is structural and discriminated by `phase`, then by `kind` for interactions. Each state exposes only transitions valid from that state.
+`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`.
 
-```txt
-observation -> advance
-feedback -> advance
-choice -> submitChoice / timeout
-text-entry -> submitText / timeout
-extended-text -> submitText or submitTexts / timeout
-order -> submitOrder / timeout
-match -> submitMatch / timeout
-portable-custom -> submit / timeout
-completed -> no transition
-fatal -> no transition
+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>>
+}
 ```
 
-The state object is live and non-serializable. Do not put it in storage, JSON, or server data.
+`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.
 
-## Runtime Loop
+Correct browser-safe pattern:
 
 ```ts
-let state = await create({
-	origin,
-	publishableKey,
-	subject: "math",
-	supportedPcis: ["urn:primer:pci:fraction-input"],
-	logger
-})
+function handleSignInClick(state: UnauthenticatedState): void {
+	void state.login().then(function continueAfterLogin(nextState) {
+		renderPrimer(nextState)
+	})
+}
+```
 
-while (state.phase !== "completed" && state.phase !== "fatal") {
-	switch (state.phase) {
-		case "observation":
-			renderFrame(state.body, state.stimulus)
-			state = await state.advance()
-			break
-		case "interaction":
-			state = await renderAndSubmitInteraction(state)
-			break
-		case "feedback":
-			renderFeedback(state.feedbackContent, state.isCorrect, state.review)
-			state = await state.advance()
-			break
-		case "errored":
-			if (state.retriable) {
-				state = await state.retry()
-				break
-			}
-			throw state.error
+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>
 }
+```
 
-if (state.phase === "fatal") {
-	throw state.error
+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
+
+Learning states that render content expose `body` and `stimulus`.
+
+```ts
+interface RenderableState {
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+}
+```
+
+`body` is the main instructional content. `stimulus` is optional supporting material. Current stimulus support is image-only, but it is still a discriminated union so renderers can remain future-safe.
+
+## `ObservationState`
+
+```ts
+interface ObservationState<Pcis extends PciId = PciId> {
+	readonly phase: "observation"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	advance(): Promise<PrimerState<Pcis>>
+}
+```
+
+Render the frame, then call `advance()` when the learner is ready to continue. Observation states have no answer to submit.
+
+Repeated `advance()` calls while the first one is pending return the same pending result.
+
+## `InteractionState`
+
+```ts
+type InteractionState<Pcis extends PciId = PciId> =
+	| ChoiceState<Pcis>
+	| TextEntryState<Pcis>
+	| ExtendedTextState<Pcis>
+	| OrderState<Pcis>
+	| MatchState<Pcis>
+	| PciInteractionState<Pcis>
+```
+
+Every interaction state includes:
+
+| Field | Meaning |
+| --- | --- |
+| `phase: "interaction"` | State-machine discriminator. |
+| `kind` | Renderer-facing interaction kind. |
+| `body` | Frame content. |
+| `stimulus` | Optional frame stimulus. |
+| `interaction` | Full interaction contract object. |
+| submit method | Kind-specific learner submission operation. |
+| `timeout()` | Records that the learner timed out or the host chose to end the attempt without a submission. |
+
+Submission methods validate standard interaction payloads before runtime submission. Invalid standard submissions return `ErroredState` with `ErrInvalidSubmission`.
+
+Concurrent interaction operations are guarded:
+
+| Situation | SDK behavior |
+| --- | --- |
+| Same submit payload while submit is pending | Returns the same pending result. |
+| Different submit payload while submit is pending | Returns `ErroredState` with `ErrConflict`. |
+| Submit while timeout is pending | Returns `ErroredState` with `ErrConflict`. |
+| Timeout while submit is pending | Returns `ErroredState` with `ErrConflict`. |
+| Repeated timeout while timeout is pending | Returns the same pending result. |
+
+## `ChoiceState`
+
+```ts
+interface ChoiceState<Pcis extends PciId = PciId> {
+	readonly phase: "interaction"
+	readonly kind: "choice"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: Extract<StandardRendererInteraction, { type: "choice" }>
+	readonly options: RendererChoice[]
+	readonly minChoices: number
+	readonly maxChoices: number
+	submitChoice(selectedKeys: string[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
+```
+
+Use `minChoices` and `maxChoices` to decide whether the UI should submit immediately or require an explicit submit action.
+
+Valid `submitChoice` payloads:
+
+| Requirement | Error if violated |
+| --- | --- |
+| At least `minChoices` identifiers | `ErrInvalidSubmission` |
+| At most `maxChoices` identifiers | `ErrInvalidSubmission` |
+| Every identifier exists in `options` | `ErrInvalidSubmission` |
+| No duplicate identifiers | `ErrInvalidSubmission` |
+
+## `TextEntryState`
+
+```ts
+interface TextEntryState<Pcis extends PciId = PciId> {
+	readonly phase: "interaction"
+	readonly kind: "text-entry"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: Extract<StandardRendererInteraction, { type: "text-entry" }>
+	submitText(value: string): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
+```
+
+The interaction may include `expectedLength`, `patternMask`, and `placeholderText`. These are renderer hints. The SDK requires the submission to be a text-entry submission with a string value.
+
+## `ExtendedTextState`
+
+Extended text has two cardinalities.
+
+```ts
+interface ExtendedTextSingleState<Pcis extends PciId = PciId> {
+	readonly phase: "interaction"
+	readonly kind: "extended-text"
+	readonly cardinality: "single"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: Extract<
+		StandardRendererInteraction,
+		{ type: "extended-text"; cardinality: "single" }
+	>
+	submitText(value: string): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
+
+interface ExtendedTextMultipleState<Pcis extends PciId = PciId> {
+	readonly phase: "interaction"
+	readonly kind: "extended-text"
+	readonly cardinality: "multiple"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: Extract<
+		StandardRendererInteraction,
+		{ type: "extended-text"; cardinality: "multiple" }
+	>
+	readonly minStrings: number
+	readonly maxStrings: number
+	submitTexts(values: string[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
 }
 ```
 
-## PCI Type Safety
+For single-cardinality extended text, call `submitText(value)`. For multiple-cardinality extended text, call `submitTexts(values)`.
 
-Portable Custom Interactions are typed by PCI id.
+Valid multiple-cardinality payloads:
+
+| Requirement | Error if violated |
+| --- | --- |
+| At least `minStrings` values | `ErrInvalidSubmission` |
+| At most `maxStrings` values | `ErrInvalidSubmission` |
+| No duplicate values | `ErrInvalidSubmission` |
+
+`expectedLength`, `expectedLines`, `patternMask`, and `placeholderText` are renderer hints.
+
+## `OrderState`
 
 ```ts
-import type { PciProps, PciValue } from "@superbuilders/primer-tives/contracts"
+interface OrderState<Pcis extends PciId = PciId> {
+	readonly phase: "interaction"
+	readonly kind: "order"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: Extract<StandardRendererInteraction, { type: "order" }>
+	readonly choices: RendererChoice[]
+	readonly minChoices: number
+	readonly maxChoices: number
+	submitOrder(orderedKeys: string[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
+```
+
+Submit identifiers in learner-selected order.
+
+Valid `submitOrder` payloads:
+
+| Requirement | Error if violated |
+| --- | --- |
+| At least `minChoices` identifiers | `ErrInvalidSubmission` |
+| At most `maxChoices` identifiers | `ErrInvalidSubmission` |
+| Every identifier exists in `choices` | `ErrInvalidSubmission` |
+| No duplicate identifiers | `ErrInvalidSubmission` |
+
+## `MatchState`
+
+```ts
+interface MatchPair {
+	source: string
+	target: string
+}
+
+interface MatchState<Pcis extends PciId = PciId> {
+	readonly phase: "interaction"
+	readonly kind: "match"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: Extract<StandardRendererInteraction, { type: "match" }>
+	readonly sourceChoices: RendererMatchChoice[]
+	readonly targetChoices: RendererMatchChoice[]
+	readonly minAssociations: number
+	readonly maxAssociations: number
+	submitMatch(pairs: MatchPair[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
+```
+
+Each pair connects one source identifier to one target identifier.
+
+Valid `submitMatch` payloads:
+
+| Requirement | Error if violated |
+| --- | --- |
+| At least `minAssociations` pairs | `ErrInvalidSubmission` |
+| At most `maxAssociations` pairs | `ErrInvalidSubmission` |
+| Every source identifier exists in `sourceChoices` | `ErrInvalidSubmission` |
+| Every target identifier exists in `targetChoices` | `ErrInvalidSubmission` |
+| No duplicate source-target pairs | `ErrInvalidSubmission` |
+| Every choice respects its `matchMin` | `ErrInvalidSubmission` |
+| Every choice respects its `matchMax` when `matchMax` is nonzero | `ErrInvalidSubmission` |
+
+`matchMax: 0` means unbounded.
+
+## `PciInteractionState`
+
+Portable Custom Interaction state is typed by PCI id.
 
-type FractionProps = PciProps<"urn:primer:pci:fraction-input">
-type FractionValue = PciValue<"urn:primer:pci:fraction-input">
+```ts
+type PciInteractionState<Pcis extends PciId = PciId> = {
+	[K in Pcis]: {
+		readonly phase: "interaction"
+		readonly kind: "portable-custom"
+		readonly body: ContentBlock[]
+		readonly stimulus: RendererStimulus | null
+		readonly interaction: PciInteraction<K>
+		readonly pciId: K
+		readonly properties: PciProps<K>
+		submit(value: PciValue<K>): Promise<PrimerState<Pcis>>
+		timeout(): Promise<PrimerState<Pcis>>
+	}
+}[Pcis]
 ```
 
 When the state is narrowed to a PCI id, `submit` accepts only that PCI's value type.
 
 ```ts
+import type { PciValue } from "@superbuilders/primer-tives/contracts"
+
 if (state.phase === "interaction" && state.kind === "portable-custom") {
 	if (state.pciId === "urn:primer:pci:fraction-input") {
-		const value = readFractionInput(state.properties)
+		const value: PciValue<"urn:primer:pci:fraction-input"> = readFractionInput(
+			state.properties
+		)
 		state = await state.submit(value)
 	}
 }
 ```
 
-## Subject PCI Helpers
+## `FeedbackState`
+
+```ts
+interface FeedbackState<Pcis extends PciId = PciId> {
+	readonly phase: "feedback"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	readonly interaction: RendererInteraction<Pcis>
+	readonly submission: RendererSubmission<Pcis>
+	readonly isCorrect: boolean
+	readonly feedbackContent: ContentInline[]
+	readonly review: InteractionReview<Pcis> | null
+	advance(): Promise<PrimerState<Pcis>>
+}
+```
+
+Feedback state is returned after a successful learner submission. Render the submitted frame, submitted value, correctness, feedback content, and optional review data. Call `advance()` when the learner is ready to continue.
+
+Repeated `advance()` calls while the first one is pending return the same pending result.
 
-Use `@superbuilders/primer-tives/subject-pcis` when tooling needs the same contract as the SDK.
+## `CompletedState`
 
 ```ts
-import { requiredPcisForSubject } from "@superbuilders/primer-tives/subject-pcis"
+interface CompletedState {
+	readonly phase: "completed"
+}
+```
+
+Terminal state. There is no transition method.
+
+## `ErroredState`
 
-const required = requiredPcisForSubject("math")
+```ts
+interface ErroredState<Pcis extends PciId = PciId> {
+	readonly phase: "errored"
+	readonly error: Error
+	readonly retriable: boolean
+	retry(): Promise<PrimerState<Pcis>>
+}
 ```
 
-`requiredPcisForSubject(undefined)` returns the all-subject required PCI union.
+`ErroredState` means the current learner intent could not complete, but the learning session itself is not necessarily terminal.
 
-## Errors
+If `retriable` is `true`, `retry()` repeats the exact failed intent. If `retriable` is `false`, `retry()` resolves to the same errored state.
+
+`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.
+
+## `FatalState`
 
-Errors are sentinel values from `@superbuilders/errors`.
+```ts
+interface FatalState {
+	readonly phase: "fatal"
+	readonly error: Error
+	readonly retriable: false
+}
+```
 
-Common sentinels:
+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:
 
 | Sentinel | Meaning |
 | --- | --- |
-| `ErrAuthUnavailable` | Hosted auth needs browser APIs that are unavailable. |
-| `ErrAuthConfigInvalid` | Hosted auth internal URL/config state was invalid. |
-| `ErrAuthCallbackInvalid` | Hosted auth callback was malformed or rejected. |
-| `ErrAuthStateMismatch` | Callback state did not match stored state. |
-| `ErrAuthPopupBlocked` | Browser blocked the hosted auth popup. |
-| `ErrAuthCancelled` | Hosted auth popup was closed or timed out. |
-| `ErrMalformedAccessToken` | Access token is not JWS-shaped. |
-| `ErrInvalidAccessToken` | Server rejected the access token. |
-| `ErrTokenExpired` | Server rejected an expired token. |
-| `ErrUnsupportedPci` | Server returned an undeclared PCI. |
-| `ErrInvalidSubmission` | Submission did not match the active interaction. |
-| `ErrSdkUpgradeRequired` | Server requires a newer SDK version. |
-| `ErrNetwork` | Fetch failed before an HTTP response. |
-| `ErrTimeout` | Request was aborted. |
-| `ErrJsonParse` | Server returned invalid JSON. |
+| `ErrBadRequest` | Primer rejected the runtime request as invalid for the SDK contract. |
+| `ErrInvalidAccessToken` | The learner token was rejected. |
+| `ErrTokenExpired` | The learner token expired. |
+| `ErrForbidden` | The learner is not allowed to continue in this runtime scope. |
+| `ErrNotFound` | The requested runtime scope or state could not be found. |
+| `ErrSdkUpgradeRequired` | The installed SDK is too old for the current Primer runtime. |
+| `ErrUnsupportedPci` | Primer presented a PCI that the renderer did not declare in `supportedPcis`. |
+
+## `/contracts`
+
+The contracts subpath contains renderer-facing data types and validation helpers.
+
+```ts
+import {
+	ChoiceSubmissionSchema,
+	ExtendedTextSubmissionSchema,
+	FractionInputPciSubmissionSchema,
+	MatchPairSchema,
+	MatchSubmissionSchema,
+	OrderSubmissionSchema,
+	PCI_IDS,
+	RendererSubmissionSchema,
+	TextEntrySubmissionSchema,
+	blocksToPlainText,
+	inlinesToPlainText,
+	isPciId,
+	submissionValidationMessage,
+	validateSubmissionForInteraction
+} from "@superbuilders/primer-tives/contracts"
+
+import type {
+	ContentBlock,
+	ContentInline,
+	ContentSpan,
+	FractionInputForm,
+	FractionInputProps,
+	FractionInputSubmission,
+	ImageStimulus,
+	InteractionReview,
+	MatchPair,
+	PciId,
+	PciInteraction,
+	PciProps,
+	PciRegistry,
+	PciSubmission,
+	PciUrn,
+	PciValue,
+	RendererChoice,
+	RendererInteraction,
+	RendererMatchChoice,
+	RendererStimulus,
+	RendererSubmission,
+	StandardRendererInteraction
+} from "@superbuilders/primer-tives/contracts"
+```
+
+## Content
+
+```ts
+type ContentSpan = { type: "text"; value: string } | { type: "italic"; value: string }
+type ContentInline = ContentSpan | { type: "latex"; value: string }
+type ContentBlock = { type: "paragraph"; children: ContentInline[] }
+```
+
+Helpers:
+
+```ts
+function inlinesToPlainText(nodes: ContentInline[]): string
+function blocksToPlainText(blocks: ContentBlock[]): string
+```
+
+Use the plain-text helpers for accessibility labels, logging summaries, search snippets, and renderer fallbacks. LaTeX inline nodes contribute their raw `value` to plain text.
+
+## Stimulus
+
+```ts
+interface ImageStimulus {
+	kind: "image"
+	alt: ContentInline[]
+	src: string
+}
+
+type RendererStimulus = ImageStimulus
+```
+
+`RendererStimulus` is currently image-only. Always switch on `stimulus.kind` anyway.
+
+## Interactions
+
+```ts
+type RendererInteraction<Pcis extends PciId = PciId> =
+	| StandardRendererInteraction
+	| PciInteraction<Pcis>
+```
+
+Standard interactions:
+
+| Type | Key fields |
+| --- | --- |
+| `choice` | `prompt`, `options`, `shuffle`, `minChoices`, `maxChoices` |
+| `text-entry` | `prompt`, `base`, `expectedLength`, `patternMask`, `placeholderText` |
+| `extended-text` single | `prompt`, `format`, `expectedLines`, `expectedLength`, `patternMask`, `placeholderText` |
+| `extended-text` multiple | single fields plus `minStrings`, `maxStrings` |
+| `order` | `prompt`, `choices`, `shuffle`, `minChoices`, `maxChoices` |
+| `match` | `prompt`, `sourceChoices`, `targetChoices`, `shuffle`, `minAssociations`, `maxAssociations` |
+| `portable-custom` | `prompt`, `pciId`, `properties` |
+
+Choice objects:
+
+```ts
+interface RendererChoice {
+	identifier: string
+	content: ContentInline[]
+}
+```
+
+Match choice objects:
+
+```ts
+interface RendererMatchChoice {
+	identifier: string
+	content: ContentInline[]
+	matchMax: number
+	matchMin: number
+}
+```
+
+## Submissions
+
+```ts
+type RendererSubmission<Pcis extends PciId = PciId> =
+	| { type: "choice"; selectedKeys: string[] }
+	| { type: "text-entry"; value: string }
+	| { type: "extended-text"; values: string[] }
+	| { type: "order"; orderedKeys: string[] }
+	| { type: "match"; pairs: MatchPair[] }
+	| PciSubmission<Pcis>
+```
+
+Public schemas:
+
+| Schema | Validates |
+| --- | --- |
+| `MatchPairSchema` | `{ source, target }` match pair shape |
+| `ChoiceSubmissionSchema` | choice submission shape |
+| `TextEntrySubmissionSchema` | text-entry submission shape |
+| `ExtendedTextSubmissionSchema` | extended-text submission shape |
+| `OrderSubmissionSchema` | order submission shape |
+| `MatchSubmissionSchema` | match submission shape |
+| `FractionInputPciSubmissionSchema` | fraction-input PCI submission shape |
+| `RendererSubmissionSchema` | union of all supported submission shapes |
+
+Always use `safeParse` when parsing arbitrary input.
+
+```ts
+import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import { RendererSubmissionSchema } from "@superbuilders/primer-tives/contracts"
+
+const parsed = RendererSubmissionSchema.safeParse(payload)
+if (!parsed.success) {
+	logger.error("submission payload invalid", { error: parsed.error })
+	throw errors.wrap(parsed.error, "submission payload")
+}
+
+const submission = parsed.data
+```
+
+## Semantic Submission Validation
+
+Shape validation answers “does this look like a submission?” Semantic validation answers “is this submission valid for this exact interaction?”
+
+```ts
+function validateSubmissionForInteraction(
+	interaction: RendererInteraction,
+	submission: RendererSubmission
+): SubmissionValidationResult
+
+function submissionValidationMessage(result: SubmissionValidationFailure): string
+```
+
+Result shape:
+
+```ts
+type SubmissionValidationResult =
+	| { ok: true; value: RendererSubmission }
+	| { ok: false; issues: readonly string[] }
+```
+
+Validation checks:
+
+| Interaction | Checks |
+| --- | --- |
+| `choice` | type match, min/max selection count, duplicate identifiers, unknown identifiers |
+| `text-entry` | type match |
+| `extended-text` single | type match, exactly one value |
+| `extended-text` multiple | type match, min/max value count, duplicate values |
+| `order` | type match, min/max selection count, duplicate identifiers, unknown identifiers |
+| `match` | type match, min/max association count, duplicate pairs, unknown sources, unknown targets, `matchMin`, `matchMax` |
+| `portable-custom` | type match, PCI id match, PCI value schema |
+
+The built-in standard interaction state methods call this before submitting. Custom renderer utilities that build `RendererSubmission` values directly should call it too.
 
 ```ts
 import * as errors from "@superbuilders/errors"
-import { ErrAuthPopupBlocked, ErrTokenExpired } from "@superbuilders/primer-tives/errors"
-
-const result = await errors.try(
-	create({
-		origin,
-		publishableKey,
-		subject: "math",
-		supportedPcis: ["urn:primer:pci:fraction-input"],
-		logger
+import * as logger from "@superbuilders/slog"
+import {
+	submissionValidationMessage,
+	validateSubmissionForInteraction
+} from "@superbuilders/primer-tives/contracts"
+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 })
+	throw errors.wrap(ErrInvalidSubmission, message)
+}
+```
+
+## Review Types
+
+`FeedbackState.review` is `InteractionReview | null`.
+
+```ts
+type InteractionReview<Pcis extends PciId = PciId> =
+	| ChoiceReview
+	| TextEntryReview
+	| ExtendedTextReview
+	| OrderReview
+	| MatchReview
+	| PciReview<Pcis>
+```
+
+Review variants:
+
+| Type | Data |
+| --- | --- |
+| `choice` | `correctKeys: string[]` |
+| `text-entry` | `correctValue: ReviewScalarValue | null` |
+| `extended-text` | `correctValues: ReviewScalarValue[]` |
+| `order` | `correctOrder: string[]` |
+| `match` | `correctPairs: MatchPair[]` |
+| `portable-custom` | `pciId`, `fields: ReviewRecordField[]` |
+
+Review scalar values:
+
+```ts
+type ReviewScalarValue =
+	| { kind: "identifier"; value: string }
+	| { kind: "string"; value: string }
+	| { kind: "integer"; value: number }
+	| { kind: "float"; value: number }
+	| { kind: "pair"; source: string; target: string }
+```
+
+`review` is for renderer display and inspection. Correctness already lives on `FeedbackState.isCorrect`.
+
+## PCI Registry
+
+The current PCI registry contains one PCI.
+
+```ts
+const PCI_IDS = ["urn:primer:pci:fraction-input"] as const
+```
+
+```ts
+type PciId = "urn:primer:pci:fraction-input"
+type PciProps<K extends PciId> = PciRegistry[K]["props"]
+type PciValue<K extends PciId> = PciRegistry[K]["value"]
+```
+
+Use `isPciId(value)` to narrow an arbitrary string to the current `PciId` union.
+
+## Fraction Input PCI
+
+```ts
+type FractionInputForm = "whole" | "proper" | "improper" | "mixed"
+
+interface FractionInputProps {
+	form: FractionInputForm
+	requireSimplified: boolean
+}
+```
+
+Submitted value:
+
+```ts
+type FractionInputSubmission =
+	| { form: "whole"; whole: string }
+	| { form: "proper"; numerator: string; denominator: string }
+	| { form: "improper"; numerator: string; denominator: string }
+	| { form: "mixed"; whole: string; numerator: string; denominator: string }
+```
+
+Example renderer branch:
+
+```ts
+if (state.phase === "interaction" && state.kind === "portable-custom") {
+	if (state.pciId === "urn:primer:pci:fraction-input") {
+		renderFractionInput({
+			mode: "pending",
+			properties: state.properties,
+			onValueChange: handleFractionValueChange
+		})
+	}
+}
+```
+
+## PCI Render Props
+
+PCI render props are convenience types for renderer components.
+
+```ts
+type PciPendingRenderProps<K extends PciId> = {
+	mode: "pending"
+	properties: PciProps<K>
+	onValueChange: (value: PciValue<K> | null) => void
+}
+
+type PciSubmittedRenderProps<K extends PciId> = {
+	mode: "submitted"
+	properties: PciProps<K>
+	submission: PciValue<K>
+	review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
+}
+
+type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRenderProps<K>
+```
+
+## Subject PCI Helpers
+
+Use `@superbuilders/primer-tives/subject-pcis` when renderer tooling needs the same subject-to-PCI contract as `start`.
+
+```ts
+import {
+	REQUIRED_PCIS_BY_SUBJECT,
+	missingPcisForSubject,
+	requiredPcisForSubject
+} from "@superbuilders/primer-tives/subject-pcis"
+import type {
+	HasRequiredPcis,
+	MissingRequiredPcis,
+	RequiredPciForSubject
+} from "@superbuilders/primer-tives/subject-pcis"
+
+const requiredForMath = requiredPcisForSubject("math")
+const missingForMath = missingPcisForSubject("math", [])
+```
+
+`requiredPcisForSubject(undefined)` returns the all-subject required PCI union.
+
+## Errors
+
+All SDK sentinels are exported from `@superbuilders/primer-tives/errors` and are compatible with `errors.is()` from `@superbuilders/errors`.
+
+```ts
+import * as errors from "@superbuilders/errors"
+import { ErrTokenExpired } from "@superbuilders/primer-tives/errors"
+
+if (errors.is(err, ErrTokenExpired)) {
+	renderSignInAgain()
+}
+```
+
+Complete export set:
+
+```ts
+import {
+	ErrAuthCallbackInvalid,
+	ErrAuthCancelled,
+	ErrAuthConfigInvalid,
+	ErrAuthPopupBlocked,
+	ErrAuthStateMismatch,
+	ErrAuthUnavailable,
+	ErrBadRequest,
+	ErrConflict,
+	ErrForbidden,
+	ErrInvalidAccessToken,
+	ErrInvalidSubmission,
+	ErrJsonParse,
+	ErrMalformedAccessToken,
+	ErrNetwork,
+	ErrNotFound,
+	ErrNotSerializable,
+	ErrRateLimited,
+	ErrSdkUpgradeRequired,
+	ErrServerError,
+	ErrServiceUnavailable,
+	ErrTimeout,
+	ErrTokenExpired,
+	ErrUnsupportedPci
+} from "@superbuilders/primer-tives/errors"
+```
+
+## Auth And Startup Errors
+
+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. | 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. | 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. |
+
+## Runtime Error States
+
+Runtime errors are represented as `ErroredState` or `FatalState`.
+
+| Sentinel | State | Retriable | Meaning |
+| --- | --- | --- | --- |
+| `ErrNetwork` | `ErroredState` | yes | Runtime communication failed before a usable Primer result existed. |
+| `ErrTimeout` | `ErroredState` | yes | Runtime work was aborted or exceeded the host's allowed time. |
+| `ErrServerError` | `ErroredState` | yes | Primer could not produce a normal runtime result. |
+| `ErrServiceUnavailable` | `ErroredState` | yes | Primer is temporarily unavailable. |
+| `ErrRateLimited` | `ErroredState` | yes | Runtime work is temporarily rate limited. |
+| `ErrConflict` | `ErroredState` | yes | The learner intent conflicts with another in-flight or current runtime action. |
+| `ErrJsonParse` | `ErroredState` | yes | Runtime data could not be interpreted as the SDK contract. |
+| `ErrInvalidSubmission` | `ErroredState` | no | Renderer submitted a value that is invalid for the active interaction. |
+| `ErrBadRequest` | `FatalState` | no | Runtime request violates the SDK contract. |
+| `ErrInvalidAccessToken` | `FatalState` | no | Learner token is invalid. |
+| `ErrTokenExpired` | `FatalState` | no | Learner token expired. |
+| `ErrForbidden` | `FatalState` | no | Learner cannot continue in this runtime scope. |
+| `ErrNotFound` | `FatalState` | no | Runtime scope or state is unavailable. |
+| `ErrSdkUpgradeRequired` | `FatalState` | no | Installed SDK version is too old for Primer. |
+| `ErrUnsupportedPci` | `FatalState` | no | Renderer did not declare support for the presented PCI. |
+| `ErrNotSerializable` | thrown by `toJSON` | no | A live `PrimerState` was serialized. |
+
+## Error-Handling Recipes
+
+Handle auth-needed state before rendering learning content:
+
+```ts
+let state = await start(options)
+
+if (state.phase === "unauthenticated") {
+	if (errors.is(state.error, ErrAuthCancelled)) {
+		renderTryAgain(state)
+		return
+	}
+	if (state.error !== null) {
+		logger.error("primer auth needed", { error: state.error })
+	}
+	renderSignInButton(state)
+	return
+}
+```
+
+Bind login directly to the sign-in button:
+
+```ts
+function handleSignInClick(state: UnauthenticatedState): void {
+	void state.login().then(function continueAfterLogin(nextState) {
+		renderPrimer(nextState)
 	})
-)
-if (result.error) {
-	if (errors.is(result.error, ErrAuthPopupBlocked)) {
-		renderStartButtonAgain()
+}
+```
+
+Handle runtime errors through the state machine:
+
+```ts
+if (state.phase === "errored") {
+	if (state.retriable) {
+		state = await state.retry()
 		return
 	}
-	if (errors.is(result.error, ErrTokenExpired)) {
+	logger.error("primer non-retriable state", { error: state.error })
+	throw state.error
+}
+
+if (state.phase === "fatal") {
+	if (errors.is(state.error, ErrTokenExpired)) {
 		renderSignInAgain()
 		return
 	}
-	throw result.error
+	if (errors.is(state.error, ErrSdkUpgradeRequired)) {
+		renderSdkUpgradeMessage()
+		return
+	}
+	logger.error("primer fatal state", { error: state.error })
+	throw state.error
 }
 ```
 
-## Testing
+Handle invalid submissions by fixing renderer state, not by retrying the same invalid intent:
+
+```ts
+const next = await state.submitChoice(selectedKeys)
+if (next.phase === "errored") {
+	if (errors.is(next.error, ErrInvalidSubmission)) {
+		renderSelectionError(next.error.message)
+		return
+	}
+}
+state = next
+```
 
-Use a custom fetch to test runtime behavior without a live Primer server.
+## Logger
 
 ```ts
-const fetchMock: typeof globalThis.fetch = async function fetchPrimer() {
-	return new Response(
-		JSON.stringify({
-			outcome: "advanced",
-			frame: { body: [], stimulus: null, interaction: null }
-		}),
-		{ status: 200, headers: { "Content-Type": "application/json" } }
-	)
+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
 }
+```
+
+`@superbuilders/slog` matches this interface directly.
+
+```ts
+import * as logger from "@superbuilders/slog"
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+
+const options = {
+	origin,
+	publishableKey,
+	subject: "vocabulary",
+	logger
+} satisfies PrimerOptions<"vocabulary">
+
+const state = await start(options)
+```
+
+## Grade Levels
+
+```ts
+import { GRADE_LEVELS } from "@superbuilders/primer-tives/grade-level"
+import type { GradeLevel } from "@superbuilders/primer-tives/grade-level"
 
-const state = await create({
+const gradeLevels = GRADE_LEVELS
+type RuntimeGradeLevel = GradeLevel
+```
+
+```ts
+const GRADE_LEVELS = ["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"] as const
+type GradeLevel = (typeof GRADE_LEVELS)[number]
+```
+
+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 `start`, transitions, submissions, retries, and timeouts.
+
+The runtime exchange shape is not public SDK surface. Tests should assert SDK semantics after `start` resolves:
+
+| Scenario | Assert |
+| --- | --- |
+| 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` |
+
+Example test shape:
+
+```ts
+import * as errors from "@superbuilders/errors"
+import { start, type PrimerOptions } from "@superbuilders/primer-tives/client"
+import { ErrUnsupportedPci } from "@superbuilders/primer-tives/errors"
+
+declare const fetchMock: typeof globalThis.fetch
+
+const options = {
 	origin: "https://primer.test",
 	publishableKey: "pk_test",
 	accessToken: "eyJ.test.token",
 	subject: "vocabulary",
 	fetch: fetchMock,
 	logger
-})
+} satisfies PrimerOptions<"vocabulary">
+
+const state = await start(options)
+
+if (state.phase === "fatal") {
+	if (errors.is(state.error, ErrUnsupportedPci)) {
+		renderRendererCapabilityError()
+	}
+}
 ```
 
 ## Security Model
@@ -355,35 +1364,76 @@ The browser may hold:
 
 ```txt
 publishable key
-Cognito/OIDC access token
+learner access token
 ```
 
-The publishable key identifies the Primer frontend. It does not authenticate the learner.
+The publishable key identifies the Primer frontend. It is not learner auth.
 
-The access token authenticates the learner. Primer verifies it server-side before touching routing or learning state.
+The access token authenticates the learner. Primer verifies it before producing learning state.
 
-Primer does not need:
+PCI support is a renderer capability declaration. It is not negotiated implicitly. If a renderer cannot handle a required PCI, it must not claim that PCI in `supportedPcis`.
+
+Primer does not need these as public SDK inputs:
 
 ```txt
 learner email
 verified email
-Primer learner JWT
-frontend secret key for learner runtime
-game backend token exchange
+frontend secret key
+student id
+grade level
 ```
 
+## Integration Checklist
+
+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.
+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
+
+The current SDK intentionally does not expose:
+
+| Not exposed | Use instead |
+| --- | --- |
+| 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>` |
+| `snapshot()` | live `PrimerState` only |
+| 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 |
+
 ## Final Invariants
 
 ```txt
-create is the only public lifecycle operation
-create returns Promise<PrimerState>
-accessToken present skips hosted auth
-accessToken absent uses hosted auth
-subject is optional; omitted means internal all-subject scope
+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
-PrimerState is the learning state machine
+PrimerState is the live learning state machine
 only valid state variants expose learning transitions
+standard interaction submissions are validated before runtime submission
+fatal state is terminal for the current state object
+live state is not serializable
 ```
 
-Keep these concepts separate. The publishable key is not learner auth. The access token is not content authorization. PCI support is not negotiated implicitly. The state object is not serializable.
+Keep these concepts separate: publishable key is not learner auth; access token is not content authorization; subject selects scope but does not prove renderer capability; PCI support is explicit; `PrimerState` is live behavior, not data.