@superbuilders/primer-tives 2.2.1 → 3.5.1

package/README.md

@@ -2,378 +2,346 @@
 
 TypeScript SDK primitives for the Primer adaptive learning runtime.
 
-The package gives you two runtime surfaces:
+The public lifecycle is one async call:
 
-- A **server SDK** for trusted backend code. It exchanges an already-verified learner email for a short-lived Primer browser token.
-- A **browser SDK** for interactive UI code. It drives Primer's `/advance` state machine and returns typed states for observations, interactions, feedback, completion, retriable errors, and fatal errors.
+```txt
+create(options) -> Promise<PrimerState>
+```
 
-Primer intentionally does not expose a public student-management lifecycle through this SDK. Your app proves identity; Primer resolves the internal student and routing state behind the token.
+`create` resolves learner auth, opens the first Primer learning state, and returns the live state machine object your renderer drives.
 
 ```sh
 bun add @superbuilders/primer-tives
 ```
 
-The SDK uses sentinel errors from `@superbuilders/errors`. Use `errors.try()` to capture failures and `errors.is()` to classify them.
-
-## Package Version
-
-The current SDK version is `2.2.1`.
+## Version
 
-The browser SDK sends `SDK_VERSION` as `X-Primer-SDK-Version` on `/api/v0/advance`. If the server requires a newer SDK, the browser state becomes `fatal` with `ErrSdkUpgradeRequired`.
+The current SDK version is `3.5.1`.
 
 ## Entrypoints
 
-There is no package-root export. Pick the subpath for the runtime boundary you are on.
-
-| Subpath | Runtime | Owns |
-| --- | --- | --- |
-| `@superbuilders/primer-tives/server` | Backend only | `createPrimerServer`, `PrimerServer`, `PrimerServerConfig`, `GetTokenInput` |
-| `@superbuilders/primer-tives/client` | Browser | `create`, `Client`, `Config`, `PrimerState`, every state interface, PCI render props |
-| `@superbuilders/primer-tives/contracts` | Shared | Content, stimulus, interaction, submission, review, PCI types, Zod schemas, validation helpers |
-| `@superbuilders/primer-tives/errors` | Shared | Every SDK error sentinel |
-| `@superbuilders/primer-tives/logger` | Shared | `PrimerLogger` interface |
-| `@superbuilders/primer-tives/subject` | Shared | `Subject`, `SubjectScope`, `SUBJECTS` |
-| `@superbuilders/primer-tives/subject-pcis` | Shared | Required PCI helpers for subject scopes |
-| `@superbuilders/primer-tives/grade-level` | Shared | `GradeLevel`, `GRADE_LEVELS` |
-
-## Architecture
+There is no package-root export. Import from the public subpath that owns the surface you need.
 
-Primer's runtime has three identities in play:
-
-| Identity | Owner | Where it lives |
-| --- | --- | --- |
-| Host user | Your app | Your auth/user tables |
-| Verified email | Your backend proves it; Primer hashes it | Sent only from trusted backend to Primer |
-| Primer student | Primer | Internal DB, scoped to a Primer frontend |
-
-The SDK only asks your backend for `verifiedEmail`. That name is deliberate. It means your backend has already verified email ownership through your own auth system. Primer does not send a verification email in this flow.
-
-The backend token flow is:
-
-1. Your app authenticates a user.
-2. Your app verifies the user's email.
-3. Your backend calls `primer.getToken({ verifiedEmail: user.email })` with a Primer `sk_...` secret key.
-4. Primer normalizes and hashes the email server-side.
-5. Primer resolves or creates the internal frontend-scoped student.
-6. Primer returns a short-lived browser access token.
-7. Your browser UI passes that token to `create({ accessToken, ... })`.
+| Subpath | Owns |
+| --- | --- |
+| `@superbuilders/primer-tives/client` | `create`, `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 and type helpers |
+| `@superbuilders/primer-tives/grade-level` | `GradeLevel`, `GRADE_LEVELS` |
 
-Primer stores a secret-keyed SHA-512/256 digest of normalized email, not raw email. The browser never sees your Primer secret key and never sends the email to `/advance`.
+## Quick Start
 
-## End-To-End Backend Example
+Math content can require the fraction-input PCI capability, so a math renderer must declare it.
 
 ```ts
-import * as errors from "@superbuilders/errors"
 import * as logger from "@superbuilders/slog"
-import { createPrimerServer } from "@superbuilders/primer-tives/server"
-import { ErrBadRequest, ErrInvalidSecretKey, ErrNetwork, ErrTimeout } from "@superbuilders/primer-tives/errors"
+import { create } from "@superbuilders/primer-tives/client"
 
-const primer = createPrimerServer({
+let state = await create({
 	origin: "https://primerlearn.dev",
-	secretKey: process.env.PRIMER_SECRET_KEY,
+	publishableKey: "pk_...",
+	subject: "math",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
 })
-
-async function getPrimerAccessToken(user: { email: string; emailVerified: boolean }): Promise<string> {
-	if (!user.emailVerified) {
-		logger.error("user email not verified")
-		throw errors.new("email not verified")
-	}
-
-	const result = await errors.try(primer.getToken({ verifiedEmail: user.email }))
-	if (result.error) {
-		if (errors.is(result.error, ErrInvalidSecretKey)) {
-			logger.error("primer secret key invalid", { error: result.error })
-			throw errors.wrap(result.error, "primer token")
-		}
-		if (errors.is(result.error, ErrBadRequest)) {
-			logger.error("primer token request rejected", { error: result.error })
-			throw errors.wrap(result.error, "primer token")
-		}
-		if (errors.is(result.error, ErrNetwork) || errors.is(result.error, ErrTimeout)) {
-			logger.error("primer token transport failed", { error: result.error })
-			throw errors.wrap(result.error, "primer token")
-		}
-		logger.error("primer token failed", { error: result.error })
-		throw errors.wrap(result.error, "primer token")
-	}
-
-	return result.data
-}
 ```
 
-## End-To-End Browser Example
+If your application already has a learner access token, pass it directly. The SDK will use that token and skip SDK-managed auth.
 
 ```ts
-import * as logger from "@superbuilders/slog"
-import { create, type PrimerState } from "@superbuilders/primer-tives/client"
-
-const client = create({
+let state = await create({
 	origin: "https://primerlearn.dev",
+	publishableKey: "pk_...",
 	accessToken,
 	subject: "math",
 	supportedPcis: ["urn:primer:pci:fraction-input"],
 	logger
 })
+```
 
-let state: PrimerState = await client.start()
-
-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
-		}
-	}
-}
+Vocabulary and science currently have no required PCI capabilities, so `supportedPcis` can be omitted for those subjects.
 
-if (state.phase === "fatal") {
-	throw state.error
-}
+```ts
+let state = await create({
+	origin: "https://primerlearn.dev",
+	publishableKey: "pk_...",
+	subject: "vocabulary",
+	logger
+})
 ```
 
-# `/server`
-
-The server subpath is backend-only. It wraps the token endpoint and hides raw HTTP response details.
+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
-import { createPrimerServer } from "@superbuilders/primer-tives/server"
-import type { GetTokenInput, PrimerServer, PrimerServerConfig } from "@superbuilders/primer-tives/server"
+let state = await create({
+	origin: "https://primerlearn.dev",
+	publishableKey: "pk_...",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+})
 ```
 
-## `createPrimerServer(config)`
+## `create(options)`
 
 ```ts
-interface PrimerServerConfig {
-	readonly origin: string
-	readonly secretKey: string
-	readonly fetch?: typeof globalThis.fetch
-	readonly abort?: AbortController
-	readonly logger: PrimerLogger
-}
-
-function createPrimerServer(config: PrimerServerConfig): PrimerServer
+function create<
+	const S extends Subject | undefined = undefined,
+	const Supported extends readonly PciId[] = []
+>(options: PrimerOptions<S, Supported>): Promise<PrimerState>
 ```
 
-Config fields:
+`create` can fail in two different ways:
 
-| Field | Required | Description |
-| --- | --- | --- |
-| `origin` | Yes | Primer deployment origin, for example `https://primerlearn.dev`. |
-| `secretKey` | Yes | Primer `sk_...` frontend secret. Keep it on the backend. |
-| `fetch` | No | Custom fetch for tests, proxies, tracing, or platform adapters. Defaults to `globalThis.fetch`. |
-| `abort` | No | `AbortController`; its signal is passed to every server SDK request. |
-| `logger` | Yes | Structured logger implementing `debug`, `info`, `warn`, `error`. |
+| Moment | Behavior |
+| --- | --- |
+| 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`. |
 
-## `PrimerServer`
+This distinction matters. Use `errors.try(create(...))` for startup failures, then handle `state.phase` for learning-state failures.
 
 ```ts
-interface PrimerServer {
-	getToken(input: GetTokenInput): Promise<string>
-}
-
-type GetTokenInput = {
-	readonly verifiedEmail: string
+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()
+		return
+	}
+	if (errors.is(result.error, ErrMalformedAccessToken)) {
+		renderSignInAgain()
+		return
+	}
+	logger.error("primer create failed", { error: result.error })
+	throw result.error
 }
-```
-
-`getToken` returns the browser access token string directly. It does not return a session object because the browser only needs the token.
-
-The SDK sends this wire body:
 
-```json
-{
-	"verified_email": "student@example.com"
-}
+let state = result.data
 ```
 
-The raw API response includes token metadata and internal student identity, but the SDK deliberately returns only `access_token`. That keeps the public SDK focused on the one value the app has to pass to the browser runtime.
-
-## `verifiedEmail`
-
-`verifiedEmail` must be server-trusted. The SDK does not validate that the user owns this address. It only validates that Primer accepts the request shape.
-
-Correct usage:
+## `PrimerOptions`
 
 ```ts
-const accessToken = await primer.getToken({ verifiedEmail: authenticatedUser.email })
+type PrimerOptions<S extends Subject | undefined = undefined, Supported extends readonly PciId[] = []> = {
+	readonly origin: string
+	readonly publishableKey: string
+	readonly accessToken?: string
+	readonly subject?: S
+	readonly supportedPcis: subject-dependent
+	readonly fetch?: typeof globalThis.fetch
+	readonly abort?: AbortController
+	readonly logger: PrimerLogger
+}
 ```
 
-Only do this after your own auth system has verified `authenticatedUser.email`.
-
-Incorrect usage:
+| 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, SDK-managed auth is skipped. |
+| `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`. |
 
-```ts
-const accessToken = await primer.getToken({ verifiedEmail: request.body.email })
-```
+The presence or absence of `accessToken` selects auth semantics.
 
-That treats an untrusted browser payload as identity proof and defeats the security model.
+| 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. |
 
-## Server Error Sentinels
+The public API does not expose separate auth plumbing, auth result objects, or any auth lifecycle method. Auth is part of `create`.
 
-Import sentinels from `/errors`, not `/server`.
+## Auth Semantics
 
-```ts
-import { ErrInvalidSecretKey, ErrBadRequest } from "@superbuilders/primer-tives/errors"
-```
+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`.
 
-`getToken` can surface:
+SDK-managed auth may require browser capabilities and learner interaction. These failures reject `create`:
 
-| Sentinel | Raised when |
+| Sentinel | Meaning |
 | --- | --- |
-| `ErrInvalidSecretKey` | Primer returned HTTP 401. The `sk_...` key is missing, malformed, inactive, or unknown. |
-| `ErrBadRequest` | Primer returned HTTP 400. The request body was invalid, usually a malformed email. |
-| `ErrServerError` | Primer returned another unexpected non-2xx status. |
-| `ErrJsonParse` | Primer returned 2xx but the response body was not valid JSON or lacked `access_token`. |
-| `ErrNetwork` | `fetch` rejected before a response arrived. |
-| `ErrTimeout` | Fetch was aborted. |
+| `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. |
 
-Recommended pattern:
+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 { ErrBadRequest, ErrInvalidSecretKey } from "@superbuilders/primer-tives/errors"
+import {
+	ErrAuthCancelled,
+	ErrAuthPopupBlocked,
+	ErrAuthUnavailable
+} from "@superbuilders/primer-tives/errors"
 
-const result = await errors.try(primer.getToken({ verifiedEmail }))
+const result = await errors.try(create(options))
 if (result.error) {
-	if (errors.is(result.error, ErrInvalidSecretKey)) {
-		logger.error("primer secret key invalid", { error: result.error })
-		throw errors.wrap(result.error, "primer token")
+	if (errors.is(result.error, ErrAuthPopupBlocked)) {
+		renderPopupInstructions()
+		return
 	}
-	if (errors.is(result.error, ErrBadRequest)) {
-		logger.error("primer token request rejected", { error: result.error })
-		throw errors.wrap(result.error, "primer token")
+	if (errors.is(result.error, ErrAuthCancelled)) {
+		renderTryAgain()
+		return
 	}
-	logger.error("primer token failed", { error: result.error })
-	throw errors.wrap(result.error, "primer token")
+	if (errors.is(result.error, ErrAuthUnavailable)) {
+		renderUnsupportedBrowserMessage()
+		return
+	}
+	logger.error("primer auth failed", { error: result.error })
+	throw result.error
 }
-
-const accessToken = result.data
 ```
 
-# `/client`
+## Subject And PCI Contract
 
-The client subpath owns the browser runtime state machine.
+`subject` selects content scope and determines required renderer capabilities.
 
 ```ts
-import { create } from "@superbuilders/primer-tives/client"
-import type { Client, Config, PrimerState } from "@superbuilders/primer-tives/client"
+import { SUBJECTS } from "@superbuilders/primer-tives/subject"
+import type { Subject } from "@superbuilders/primer-tives/subject"
+
+const subjects = SUBJECTS
+type RuntimeSubject = Subject
 ```
 
-## `create(config)`
+Current public subjects:
 
-```ts
-function create<const S extends SubjectScope, const Pcis extends PciId = never>(
-	config: Config<S, Pcis>
-): Client<PciId>
-```
+| Subject | Required PCI support |
+| --- | --- |
+| `"math"` | `"urn:primer:pci:fraction-input"` |
+| `"vocabulary"` | none |
+| `"science"` | none |
+| omitted subject | union of all subject-required PCIs, currently `"urn:primer:pci:fraction-input"` |
 
-Config shape:
+The type-level rule is a subset check:
 
-```ts
-type Config<S extends SubjectScope, Pcis extends PciId = never> = {
-	readonly accessToken: string
-	readonly subject: S
-	readonly origin: string
-	readonly fetch?: typeof globalThis.fetch
-	readonly abort?: AbortController
-	readonly logger: PrimerLogger
-} & PciConfigForSubject<S, Pcis>
+```txt
+required PCIs for selected scope <= supportedPcis
 ```
 
-Fields:
+Order does not matter. Extra supported PCIs are allowed. `supportedPcis` is a renderer capability declaration, not a content request.
 
-| Field | Required | Description |
-| --- | --- | --- |
-| `accessToken` | Yes | Token string returned by `primer.getToken`. |
-| `subject` | Yes | `"math"`, `"vocabulary"`, `"science"`, or `"all"`. |
-| `origin` | Yes | Primer deployment origin. |
-| `supportedPcis` | Conditionally | Literal array of PCI URNs your renderer supports. Required when the chosen subject can emit required PCIs. |
-| `fetch` | No | Custom fetch implementation. |
-| `abort` | No | `AbortController`; signal passed to `/advance`. |
-| `logger` | Yes | Structured logger. |
-
-`create` performs local checks before any network request:
+This fails at compile time because math can emit a required PCI:
 
-- `accessToken` must look like a JWS: starts with `eyJ` and has two dots. Otherwise it throws `ErrMalformedAccessToken`.
-- `supportedPcis` must include all PCIs required by the selected subject. Missing support throws `ErrMissingRequiredPci` immediately and logs `renderer missing required pcis`.
+```ts
+await create({
+	origin,
+	publishableKey,
+	subject: "math",
+	logger
+})
+```
 
-## `Client`
+This passes:
 
 ```ts
-interface Client<Pcis extends PciId = PciId> {
-	start(): Promise<PrimerState<Pcis>>
-}
+await create({
+	origin,
+	publishableKey,
+	subject: "math",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+})
 ```
 
-`start()` sends the first observation request. It is idempotent: multiple calls return the same pending promise.
-
-## Subject Scopes
+If `subject` is a broad dynamic `Subject` value, TypeScript requires support for the union of all PCIs required by the possible subjects.
 
 ```ts
-import { SUBJECTS } from "@superbuilders/primer-tives/subject"
-import type { Subject, SubjectScope } from "@superbuilders/primer-tives/subject"
+declare const subject: Subject
 
-const SUBJECTS = ["math", "vocabulary", "science"] as const
-type Subject = (typeof SUBJECTS)[number]
-type SubjectScope = Subject | "all"
+await create({
+	origin,
+	publishableKey,
+	subject,
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+})
 ```
 
-| Scope | Behavior |
-| --- | --- |
-| `"math"` | Runtime is scoped to math content and math-required PCIs. |
-| `"vocabulary"` | Runtime is scoped to vocabulary content. |
-| `"science"` | Runtime is scoped to science content. |
-| `"all"` | Runtime can draw from all subjects available to the Primer frontend. |
-
-To change subjects, create a new client. Placement state is server-owned and subject-scoped; the browser does not manage cursors.
+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`.
 
-## Required PCIs
+## Runtime Loop
 
-Math currently requires the fraction-input PCI. Vocabulary and science currently require none.
+Every renderer should switch on `state.phase`. Interaction rendering should then switch on `state.kind`.
 
 ```ts
-import { missingPcisForSubject, requiredPcisForSubject } from "@superbuilders/primer-tives/subject-pcis"
+import * as logger from "@superbuilders/slog"
+import type { PrimerState } from "@superbuilders/primer-tives/client"
 
-requiredPcisForSubject("math")
-// ["urn:primer:pci:fraction-input"]
-```
+async function runPrimer(initialState: PrimerState): Promise<void> {
+	let state = initialState
 
-For math or `all`, pass a `supportedPcis` literal array that includes `"urn:primer:pci:fraction-input"`.
+	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
+				}
+				logger.error("primer state error", { error: state.error })
+				throw state.error
+		}
+	}
 
-```ts
-const client = create({
-	origin,
-	accessToken,
-	subject: "math",
-	supportedPcis: ["urn:primer:pci:fraction-input"],
-	logger
-})
+	if (state.phase === "fatal") {
+		logger.error("primer fatal state", { error: state.error })
+		throw state.error
+	}
+}
 ```
 
-The array values are not sent to the server. They exist so TypeScript and client-side runtime preflight can prove that the renderer has declared support for required PCI URNs before `/advance` is called.
+State transitions:
 
-# `PrimerState`
-
-`PrimerState` is a discriminated union over `phase`.
+| Current state | Valid operation | Next result |
+| --- | --- | --- |
+| `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> =
@@ -385,12 +353,27 @@ type PrimerState<Pcis extends PciId = PciId> =
 	| FatalState
 ```
 
-Every state is intentionally non-serializable. It contains closures for advancing, submitting, retrying, and deduplicating in-flight calls. Do not store it in localStorage, persist it through JSON, or treat it as data. Keep it in memory and call `client.start()` again after reload.
+`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.
+
+## 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> extends NonSerializable {
+interface ObservationState<Pcis extends PciId = PciId> {
 	readonly phase: "observation"
 	readonly body: ContentBlock[]
 	readonly stimulus: RendererStimulus | null
@@ -398,56 +381,78 @@ interface ObservationState<Pcis extends PciId = PciId> extends NonSerializable {
 }
 ```
 
-Render `body` and `stimulus`, then call `advance()` when the learner is ready to continue. Observation frames have no interaction to submit.
+Render the frame, then call `advance()` when the learner is ready to continue. Observation states have no answer to submit.
 
-## `InteractionState`
+Repeated `advance()` calls while the first one is pending return the same pending result.
 
-`InteractionState` is a union over `kind`.
+## `InteractionState`
 
-| `kind` | State type | Submit method |
-| --- | --- | --- |
-| `choice` | `ChoiceState` | `submitChoice(selectedKeys: string[])` |
-| `text-entry` | `TextEntryState` | `submitText(value: string)` |
-| `extended-text` single | `ExtendedTextSingleState` | `submitText(value: string)` |
-| `extended-text` multiple | `ExtendedTextMultipleState` | `submitTexts(values: string[])` |
-| `order` | `OrderState` | `submitOrder(orderedKeys: string[])` |
-| `match` | `MatchState` | `submitMatch(pairs: MatchPair[])` |
-| `portable-custom` | `PciInteractionState` | `submit(value: PciValue<K>)` |
+```ts
+type InteractionState<Pcis extends PciId = PciId> =
+	| ChoiceState<Pcis>
+	| TextEntryState<Pcis>
+	| ExtendedTextState<Pcis>
+	| OrderState<Pcis>
+	| MatchState<Pcis>
+	| PciInteractionState<Pcis>
+```
 
 Every interaction state includes:
 
-- `phase: "interaction"`
-- `body`
-- `stimulus`
-- `interaction`
-- a typed submit method
-- `timeout(): Promise<PrimerState<Pcis>>`
+| 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`.
 
-Interaction submissions are validated client-side before transport. Invalid payloads return an `errored` state with `ErrInvalidSubmission`; they are not sent to the server.
+Concurrent interaction operations are guarded:
 
-### Choice
+| 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> extends NonSerializable {
+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 maxChoices: number
 	readonly minChoices: number
+	readonly maxChoices: number
 	submitChoice(selectedKeys: string[]): Promise<PrimerState<Pcis>>
 	timeout(): Promise<PrimerState<Pcis>>
 }
 ```
 
-Use `minChoices` and `maxChoices` to decide whether to auto-submit on click or require a Submit button. Primer's grade onboarding prompt is currently delivered as a normal single-choice interaction.
+Use `minChoices` and `maxChoices` to decide whether the UI should submit immediately or require an explicit submit action.
+
+Valid `submitChoice` payloads:
 
-### Text Entry
+| 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> extends NonSerializable {
+interface TextEntryState<Pcis extends PciId = PciId> {
 	readonly phase: "interaction"
 	readonly kind: "text-entry"
 	readonly body: ContentBlock[]
@@ -458,25 +463,37 @@ interface TextEntryState<Pcis extends PciId = PciId> extends NonSerializable {
 }
 ```
 
-`interaction` may include `expectedLength`, `patternMask`, and `placeholderText` for UI hints.
+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.
 
-### Extended Text
+## `ExtendedTextState`
 
 Extended text has two cardinalities.
 
 ```ts
-interface ExtendedTextSingleState<Pcis extends PciId = PciId> extends NonSerializable {
+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> extends NonSerializable {
+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>>
@@ -484,14 +501,27 @@ interface ExtendedTextMultipleState<Pcis extends PciId = PciId> extends NonSeria
 }
 ```
 
-Both include `body`, `stimulus`, and `interaction` fields like every other interaction state.
+For single-cardinality extended text, call `submitText(value)`. For multiple-cardinality extended text, call `submitTexts(values)`.
+
+Valid multiple-cardinality payloads:
+
+| Requirement | Error if violated |
+| --- | --- |
+| At least `minStrings` values | `ErrInvalidSubmission` |
+| At most `maxStrings` values | `ErrInvalidSubmission` |
+| No duplicate values | `ErrInvalidSubmission` |
 
-### Order
+`expectedLength`, `expectedLines`, `patternMask`, and `placeholderText` are renderer hints.
+
+## `OrderState`
 
 ```ts
-interface OrderState<Pcis extends PciId = PciId> extends NonSerializable {
+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
@@ -502,7 +532,16 @@ interface OrderState<Pcis extends PciId = PciId> extends NonSerializable {
 
 Submit identifiers in learner-selected order.
 
-### Match
+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 {
@@ -510,9 +549,12 @@ interface MatchPair {
 	target: string
 }
 
-interface MatchState<Pcis extends PciId = PciId> extends NonSerializable {
+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
@@ -522,13 +564,29 @@ interface MatchState<Pcis extends PciId = PciId> extends NonSerializable {
 }
 ```
 
-Each `RendererMatchChoice` has `matchMin` and `matchMax`. A `matchMax` of `0` means unbounded.
+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` |
 
-### Portable Custom Interaction
+`matchMax: 0` means unbounded.
+
+## `PciInteractionState`
+
+Portable Custom Interaction state is typed by PCI id.
 
 ```ts
 type PciInteractionState<Pcis extends PciId = PciId> = {
-	[K in Pcis]: NonSerializable & {
+	[K in Pcis]: {
 		readonly phase: "interaction"
 		readonly kind: "portable-custom"
 		readonly body: ContentBlock[]
@@ -542,29 +600,25 @@ type PciInteractionState<Pcis extends PciId = PciId> = {
 }[Pcis]
 ```
 
-For `urn:primer:pci:fraction-input`, `properties` has:
+When the state is narrowed to a PCI id, `submit` accepts only that PCI's value type.
 
 ```ts
-interface FractionInputProps {
-	form: "whole" | "proper" | "improper" | "mixed"
-	requireSimplified: boolean
+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: PciValue<"urn:primer:pci:fraction-input"> = readFractionInput(
+			state.properties
+		)
+		state = await state.submit(value)
+	}
 }
 ```
 
-The submitted value is one of:
-
-```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 }
-```
-
 ## `FeedbackState`
 
 ```ts
-interface FeedbackState<Pcis extends PciId = PciId> extends NonSerializable {
+interface FeedbackState<Pcis extends PciId = PciId> {
 	readonly phase: "feedback"
 	readonly body: ContentBlock[]
 	readonly stimulus: RendererStimulus | null
@@ -577,22 +631,24 @@ interface FeedbackState<Pcis extends PciId = PciId> extends NonSerializable {
 }
 ```
 
-Feedback state is returned after a successful interaction submission. Render the submitted frame, the submitted value, correctness, server feedback, and optional review data. Call `advance()` when the learner is ready to continue.
+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.
 
 ## `CompletedState`
 
 ```ts
-interface CompletedState extends NonSerializable {
+interface CompletedState {
 	readonly phase: "completed"
 }
 ```
 
-Terminal state. There is no action method.
+Terminal state. There is no transition method.
 
 ## `ErroredState`
 
 ```ts
-interface ErroredState<Pcis extends PciId = PciId> extends NonSerializable {
+interface ErroredState<Pcis extends PciId = PciId> {
 	readonly phase: "errored"
 	readonly error: Error
 	readonly retriable: boolean
@@ -600,43 +656,74 @@ interface ErroredState<Pcis extends PciId = PciId> extends NonSerializable {
 }
 ```
 
-`retry()` re-runs the exact same intent that failed. If `retriable` is false, `retry()` resolves to the same errored state.
+`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.
+
+`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`
 
 ```ts
-interface FatalState extends NonSerializable {
+interface FatalState {
 	readonly phase: "fatal"
 	readonly error: Error
 	readonly retriable: false
 }
 ```
 
-Fatal means the browser cannot recover by retrying the current intent. Examples include invalid token, expired token, forbidden request, unsupported PCI, or SDK upgrade required.
+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 sentinels:
+
+| Sentinel | Meaning |
+| --- | --- |
+| `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`
+## `/contracts`
 
-The contracts subpath contains renderer wire shapes and helpers shared between custom renderers and server-adjacent tooling.
+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,
@@ -658,11 +745,11 @@ type ContentBlock = { type: "paragraph"; children: ContentInline[] }
 Helpers:
 
 ```ts
-inlinesToPlainText(nodes: ContentInline[]): string
-blocksToPlainText(blocks: ContentBlock[]): string
+function inlinesToPlainText(nodes: ContentInline[]): string
+function blocksToPlainText(blocks: ContentBlock[]): string
 ```
 
-Use these helpers for accessibility labels, alt fallbacks, logging summaries, and non-rich previews.
+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
 
@@ -676,7 +763,7 @@ interface ImageStimulus {
 type RendererStimulus = ImageStimulus
 ```
 
-`RendererStimulus` is currently image-only, but it is still a discriminated union so renderers stay future-safe.
+`RendererStimulus` is currently image-only. Always switch on `stimulus.kind` anyway.
 
 ## Interactions
 
@@ -730,50 +817,86 @@ type RendererSubmission<Pcis extends PciId = PciId> =
 	| PciSubmission<Pcis>
 ```
 
-Schemas:
+Public schemas:
 
-```ts
-ChoiceSubmissionSchema
-TextEntrySubmissionSchema
-ExtendedTextSubmissionSchema
-OrderSubmissionSchema
-MatchSubmissionSchema
-FractionInputPciSubmissionSchema
-RendererSubmissionSchema
-```
+| 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:
+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) {
-	throw parsed.error
+	logger.error("submission payload invalid", { error: parsed.error })
+	throw errors.wrap(parsed.error, "submission payload")
 }
+
+const submission = parsed.data
 ```
 
-## Semantic Validation
+## Semantic Submission Validation
 
-`RendererSubmissionSchema` validates shape. `validateSubmissionForInteraction` validates a submission against a specific interaction.
+Shape validation answers “does this look like a submission?” Semantic validation answers “is this submission valid for this exact interaction?”
 
 ```ts
-const validation = validateSubmissionForInteraction(interaction, submission)
-if (!validation.ok) {
-	throw errors.wrap(ErrInvalidSubmission, submissionValidationMessage(validation))
-}
+function validateSubmissionForInteraction(
+	interaction: RendererInteraction,
+	submission: RendererSubmission
+): SubmissionValidationResult
+
+function submissionValidationMessage(result: SubmissionValidationFailure): string
 ```
 
-Checks include:
+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 |
 
-- submission type matches interaction type
-- choice identifiers exist
-- choice cardinality is within `minChoices` and `maxChoices`
-- duplicate choice/order identifiers are rejected
-- extended-text value count matches cardinality bounds
-- match source/target identifiers exist
-- match min/max usage bounds hold
-- portable-custom `pciId` matches and payload parses against the PCI schema
+The built-in standard interaction state methods call this before submitting. Custom renderer utilities that build `RendererSubmission` values directly should call it too.
 
-The built-in browser state objects call this before submitting. Custom renderers that bypass state methods should call it themselves.
+```ts
+import * as errors from "@superbuilders/errors"
+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
 
@@ -800,23 +923,143 @@ Review variants:
 | `match` | `correctPairs: MatchPair[]` |
 | `portable-custom` | `pciId`, `fields: ReviewRecordField[]` |
 
-`review` is for display and inspection. Correctness already lives on `FeedbackState.isCorrect`.
+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:
 
-# `/errors`
+```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 `create`.
+
+```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.
 
-All sentinels are exported from `/errors`.
+## 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,
-	ErrInvalidSecretKey,
 	ErrInvalidSubmission,
 	ErrJsonParse,
 	ErrMalformedAccessToken,
-	ErrMissingRequiredPci,
 	ErrNetwork,
 	ErrNotFound,
 	ErrNotSerializable,
@@ -830,55 +1073,101 @@ import {
 } from "@superbuilders/primer-tives/errors"
 ```
 
-## Server SDK Errors
+## Create-Time Errors
 
-| Sentinel | Meaning |
-| --- | --- |
-| `ErrInvalidSecretKey` | Secret key rejected by Primer. |
-| `ErrBadRequest` | Token request was malformed. |
-| `ErrServerError` | Primer returned an unexpected non-2xx status. |
-| `ErrJsonParse` | Successful response did not parse or lacked token shape. |
-| `ErrNetwork` | Fetch rejected before response. |
-| `ErrTimeout` | Fetch aborted. |
+These are most often thrown by `create` before a `PrimerState` exists.
 
-## Browser Transport Errors
+| Sentinel | Meaning | Typical handling |
+| --- | --- | --- |
+| `ErrAuthUnavailable` | SDK-managed auth cannot run in the current host environment. | Show unsupported-runtime or fallback 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. |
+| `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 create-time errors before using state:
 
-These become `ErroredState` unless classified as fatal:
+```ts
+const result = await errors.try(create(options))
+if (result.error) {
+	if (errors.is(result.error, ErrAuthCancelled)) {
+		renderTryAgain()
+		return
+	}
+	logger.error("primer create failed", { error: result.error })
+	throw result.error
+}
 
-| Sentinel | Meaning |
-| --- | --- |
-| `ErrNetwork` | Fetch rejected. |
-| `ErrTimeout` | Fetch aborted. |
-| `ErrServerError` | HTTP 5xx not otherwise mapped. |
-| `ErrServiceUnavailable` | HTTP 502, 503, or 504. |
-| `ErrRateLimited` | HTTP 429. |
-| `ErrConflict` | HTTP 409. |
-| `ErrJsonParse` | Successful response body failed to parse. |
-| `ErrInvalidSubmission` | Local semantic validation rejected the submission. |
+let state = result.data
+```
 
-## Browser Fatal Errors
+Handle runtime errors through the state machine:
 
-These become `FatalState`:
+```ts
+if (state.phase === "errored") {
+	if (state.retriable) {
+		state = await state.retry()
+		return
+	}
+	logger.error("primer non-retriable state", { error: state.error })
+	throw state.error
+}
 
-| Sentinel | Meaning |
-| --- | --- |
-| `ErrBadRequest` | HTTP 400. |
-| `ErrInvalidAccessToken` | HTTP 401. |
-| `ErrTokenExpired` | HTTP 401 with token-expired detail. |
-| `ErrForbidden` | HTTP 403. |
-| `ErrNotFound` | HTTP 404. |
-| `ErrSdkUpgradeRequired` | Server requires a newer SDK. |
-| `ErrUnsupportedPci` | Server returned a portable-custom interaction whose `pciId` is not declared in `supportedPcis`. |
+if (state.phase === "fatal") {
+	if (errors.is(state.error, ErrTokenExpired)) {
+		renderSignInAgain()
+		return
+	}
+	if (errors.is(state.error, ErrSdkUpgradeRequired)) {
+		renderSdkUpgradeMessage()
+		return
+	}
+	logger.error("primer fatal state", { error: state.error })
+	throw state.error
+}
+```
 
-## Direct Client Construction Errors
+Handle invalid submissions by fixing renderer state, not by retrying the same invalid intent:
 
-| Sentinel | Meaning |
-| --- | --- |
-| `ErrMalformedAccessToken` | Token string does not look like a JWS. |
-| `ErrMissingRequiredPci` | `create` was called for a subject whose required PCI URNs are not present in `supportedPcis`. |
-| `ErrNotSerializable` | `JSON.stringify` was called on live `PrimerState`. |
+```ts
+const next = await state.submitChoice(selectedKeys)
+if (next.phase === "errored") {
+	if (errors.is(next.error, ErrInvalidSubmission)) {
+		renderSelectionError(next.error.message)
+		return
+	}
+}
+state = next
+```
 
-# `/logger`
+## Logger
 
 ```ts
 import type { PrimerLogger } from "@superbuilders/primer-tives/logger"
@@ -891,74 +1180,152 @@ interface PrimerLogger {
 }
 ```
 
-The same logger shape is used by server and browser SDKs. `@superbuilders/slog` matches it directly:
+`@superbuilders/slog` matches this interface directly.
 
 ```ts
 import * as logger from "@superbuilders/slog"
 
-const primer = createPrimerServer({ origin, secretKey, logger })
-const client = create({ origin, accessToken, subject: "vocabulary", logger })
+const state = await create({
+	origin,
+	publishableKey,
+	subject: "vocabulary",
+	logger
+})
 ```
 
-# `/grade-level`
+## Grade Levels
 
 ```ts
 import { GRADE_LEVELS } from "@superbuilders/primer-tives/grade-level"
 import type { GradeLevel } from "@superbuilders/primer-tives/grade-level"
 
+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]
 ```
 
-The server SDK no longer accepts a grade argument. Primer asks the learner for selected grade inside the browser runtime if needed.
+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.
+
+## 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.
 
-# Onboarding Grade Selection
+The runtime exchange shape is not public SDK surface. Tests should assert SDK semantics after `create` resolves or rejects:
 
-Grade selection is not a separate SDK API.
+| 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` |
+| 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 { create } from "@superbuilders/primer-tives/client"
+import { ErrUnsupportedPci } from "@superbuilders/primer-tives/errors"
+
+declare const fetchMock: typeof globalThis.fetch
+
+const state = await create({
+	origin: "https://primer.test",
+	publishableKey: "pk_test",
+	accessToken: "eyJ.test.token",
+	subject: "math",
+	fetch: fetchMock,
+	logger
+})
 
-If the learner's email profile has no selected grade yet, the first `/advance` response is a normal `choice` interaction:
+if (state.phase === "fatal") {
+	if (errors.is(state.error, ErrUnsupportedPci)) {
+		renderRendererCapabilityError()
+	}
+}
+```
 
-- `phase: "interaction"`
-- `kind: "choice"`
-- `minChoices: 1`
-- `maxChoices: 1`
-- options with identifiers from `GRADE_LEVELS`
+## Security Model
 
-Your renderer should treat it like any other single-choice interaction. Submit the selected option through `submitChoice([grade])`. The server captures that answer, stores the selected grade on the hashed email profile, bootstraps placement, and returns real content.
+The browser may hold:
 
-This design keeps the SDK small:
+```txt
+publishable key
+learner access token
+```
 
-- no grade argument to `getToken`
-- no server-side student creation method
-- no separate onboarding endpoint
-- no browser special case beyond rendering a normal choice interaction
+The publishable key identifies the Primer frontend. It is not learner auth.
 
-# Integration Checklist
+The access token authenticates the learner. Primer verifies it before producing learning state.
 
-Use this as the minimum correct integration:
+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`.
 
-1. Backend imports `createPrimerServer` from `/server`.
-2. Backend keeps `secretKey` server-only.
-3. Backend calls `getToken` only for an authenticated user with a verified email.
-4. Backend returns the token string to the browser.
-5. Browser imports `create` from `/client`.
-6. Browser passes `accessToken`, `origin`, `subject`, `logger`, and required `supportedPcis`.
-7. Browser calls `start()` once per runtime mount.
-8. Browser renders by switching on `state.phase`.
-9. Browser never serializes `PrimerState`.
-10. Browser recreates the client after reload or subject switch.
+Primer does not need these as public SDK inputs:
 
-# What This SDK Does Not Do
+```txt
+learner email
+verified email
+frontend secret key
+student id
+grade level
+```
 
-The current SDK does not expose:
+## Integration Checklist
 
-- raw student creation
-- student ids as public integration inputs
-- SIS-specific identity-provider flows
-- host-app email verification
-- Primer-sent email verification links
-- a grade-level argument on token creation
-- persistent browser sessions
-- root package exports
+1. Import `create` 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.
+
+## 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 | `create` |
+| separate auth API | `create` |
+| client wrapper object | `create` returning `Promise<PrimerState>` |
+| `start()` | `create` already starts the first state |
+| `snapshot()` | live `PrimerState` only |
+| serializable state | recreate with `create` |
+| 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 SDK-managed auth
+accessToken absent uses SDK-managed auth
+subject is optional; omitted means all-subject runtime scope
+subject determines required renderer PCI capabilities
+supportedPcis declares renderer PCI capabilities
+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
+```
 
-Those omissions are intentional. The public integration point is one backend method, `getToken`, and one browser state machine, `create(...).start()`.
+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.