@superbuilders/primer-tives 1.2.0 → 2.2.0

package/README.md

@@ -1,705 +1,882 @@
 # @superbuilders/primer-tives
 
-TypeScript SDK for the Primer adaptive learning engine.
+TypeScript SDK primitives for the Primer adaptive learning runtime.
+
+The package gives you two runtime surfaces:
+
+- 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.
+
+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.
 
 ```sh
 bun add @superbuilders/primer-tives
 ```
 
-`@superbuilders/errors` is installed automatically. The SDK throws sentinel-wrapped errors and the recommended consumer pattern uses `errors.try` / `errors.is` / `errors.wrap` from that library.
+The SDK uses sentinel errors from `@superbuilders/errors`. Use `errors.try()` to capture failures and `errors.is()` to classify them.
 
-## Subpaths
+## Package Version
 
-Every symbol is exported from exactly one subpath. Import from the subpath that owns the thing you need.
+The current SDK version is `2.2.0`.
 
-| Subpath | What it owns |
-|---|---|
-| `@superbuilders/primer-tives/server` | `createPrimerServer` and the four `PrimerServer` methods, the config and return types |
-| `@superbuilders/primer-tives/client` | `create` (browser SDK), the `PrimerState` discriminated union, every `*State` interface, the PCI render props |
-| `@superbuilders/primer-tives/contracts` | wire-shape types (`RendererInteraction`, `RendererSubmission`, `ContentInline`, PCI base types, review types), Zod schemas, the optional submission validator |
-| `@superbuilders/primer-tives/errors` | every error sentinel (`Err…`) |
-| `@superbuilders/primer-tives/logger` | the `PrimerLogger` interface, accepted by both server and client config |
-| `@superbuilders/primer-tives/grade-level` | `GradeLevel` type and the `GRADE_LEVELS` constant |
-| `@superbuilders/primer-tives/subject` | `Subject`, `SubjectScope`, the `SUBJECTS` constant |
+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`.
 
-## End-to-end examples
+## Entrypoints
 
-### Native/manual student flow
+There is no package-root export. Pick the subpath for the runtime boundary you are on.
 
-```ts
-import * as errors from "@superbuilders/errors"
-import * as logger from "@superbuilders/slog"
-import { createPrimerServer } from "@superbuilders/primer-tives/server"
-import {
-  ErrBadRequest,
-  ErrConflict,
-  ErrInvalidSecretKey,
-  ErrStudentNotFound
-} from "@superbuilders/primer-tives/errors"
+| 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` |
 
-const primer = createPrimerServer({
-  origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_DEMO_SECRET_KEY ?? "",
-  logger
-})
+## Architecture
 
-// One time per user.
-const createResult = await errors.try(primer.createStudent())
-if (createResult.error) {
-  if (errors.is(createResult.error, ErrInvalidSecretKey)) {
-    logger.error("primer secret key invalid", { error: createResult.error })
-    throw errors.wrap(createResult.error, "primer client init")
-  }
-  if (errors.is(createResult.error, ErrConflict)) {
-    logger.error("primer frontend not provisioned", { error: createResult.error })
-    throw errors.wrap(createResult.error, "primer frontend provisioning")
-  }
-  logger.error("primer create student failed", { error: createResult.error })
-  throw errors.wrap(createResult.error, "primer create student")
-}
-const studentId = createResult.data
-// persist `studentId` alongside your own user record.
-
-// Required before the first session for native students.
-const hintsResult = await errors.try(primer.setStudentHints(studentId, { gradeLevel: "3" }))
-if (hintsResult.error) {
-  if (errors.is(hintsResult.error, ErrStudentNotFound)) {
-    logger.error("primer student id not found on this frontend", {
-      studentId,
-      error: hintsResult.error
-    })
-    throw errors.wrap(hintsResult.error, "primer set hints")
-  }
-  if (errors.is(hintsResult.error, ErrBadRequest)) {
-    logger.error("primer hint payload rejected", { error: hintsResult.error })
-    throw errors.wrap(hintsResult.error, "primer set hints")
-  }
-  logger.error("primer set hints failed", { error: hintsResult.error })
-  throw errors.wrap(hintsResult.error, "primer set hints")
-}
+Primer's runtime has three identities in play:
 
-// Every session start.
-const tokenResult = await errors.try(primer.exchangeStudentForAccessToken(studentId))
-if (tokenResult.error) {
-  if (errors.is(tokenResult.error, ErrInvalidSecretKey)) {
-    logger.error("primer secret key invalid", { error: tokenResult.error })
-    throw errors.wrap(tokenResult.error, "primer token exchange")
-  }
-  if (errors.is(tokenResult.error, ErrStudentNotFound)) {
-    logger.error("primer student id stale", { studentId, error: tokenResult.error })
-    throw errors.wrap(tokenResult.error, "primer token exchange")
-  }
-  logger.error("primer token exchange failed", { error: tokenResult.error })
-  throw errors.wrap(tokenResult.error, "primer token exchange")
-}
+| 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 |
 
-const { accessToken, expiresInSeconds } = tokenResult.data
-```
+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, ... })`.
+
+Primer stores a secret-keyed SHA3 digest of normalized email, not raw email. The browser never sees your Primer secret key and never sends the email to `/advance`.
 
-### Live-authoritative Timeback flow
+## End-To-End Backend Example
 
 ```ts
 import * as errors from "@superbuilders/errors"
 import * as logger from "@superbuilders/slog"
 import { createPrimerServer } from "@superbuilders/primer-tives/server"
-import {
-  ErrConflict,
-  ErrInvalidSecretKey,
-  ErrStudentNotFound,
-  ErrTimebackUnavailable,
-  ErrUnsupportedGrade
-} from "@superbuilders/primer-tives/errors"
+import { ErrBadRequest, ErrInvalidSecretKey, ErrNetwork, ErrTimeout } from "@superbuilders/primer-tives/errors"
 
 const primer = createPrimerServer({
-  origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_DEMO_SECRET_KEY ?? "",
-  logger
+	origin: "https://sb-primer.vercel.app",
+	secretKey: process.env.PRIMER_SECRET_KEY,
+	logger
 })
 
-const sessionResult = await errors.try(
-  primer.exchangeTimebackStudentForAccessToken(sourcedId)
-)
-if (sessionResult.error) {
-  if (errors.is(sessionResult.error, ErrInvalidSecretKey)) {
-    logger.error("primer secret key invalid", { error: sessionResult.error })
-    throw errors.wrap(sessionResult.error, "primer timeback exchange")
-  }
-  if (errors.is(sessionResult.error, ErrStudentNotFound)) {
-    logger.error("timeback sourcedId not found upstream", {
-      sourcedId,
-      error: sessionResult.error
-    })
-    throw errors.wrap(sessionResult.error, "primer timeback exchange")
-  }
-  if (errors.is(sessionResult.error, ErrUnsupportedGrade)) {
-    logger.error("timeback grade outside supported range", { error: sessionResult.error })
-    throw errors.wrap(sessionResult.error, "primer timeback exchange")
-  }
-  if (errors.is(sessionResult.error, ErrConflict)) {
-    logger.error("primer frontend not provisioned for routing", { error: sessionResult.error })
-    throw errors.wrap(sessionResult.error, "primer timeback exchange")
-  }
-  if (errors.is(sessionResult.error, ErrTimebackUnavailable)) {
-    logger.error("timeback authority temporarily unavailable", { error: sessionResult.error })
-    throw errors.wrap(sessionResult.error, "primer timeback exchange")
-  }
-  logger.error("primer timeback exchange failed", { error: sessionResult.error })
-  throw errors.wrap(sessionResult.error, "primer timeback exchange")
+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
 }
-
-const { studentId, accessToken, expiresInSeconds } = sessionResult.data
 ```
 
-### Browser flow
+## End-To-End Browser Example
 
 ```ts
-import { create } from "@superbuilders/primer-tives/client"
-import type { PrimerState } from "@superbuilders/primer-tives/client"
+import * as logger from "@superbuilders/slog"
+import { create, type PrimerState } from "@superbuilders/primer-tives/client"
 
 const client = create({
-  accessToken,
-  origin: "https://sb-primer.vercel.app",
-  subject: "math",
-  supportedPcis: [
-    "urn:primer:pci:division-remainder",
-    "urn:primer:pci:fraction-addition"
-  ]
+	origin: "https://sb-primer.vercel.app",
+	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":
-      renderStimulus(state.stimulus)
-      state = await state.advance()
-      break
-    case "interaction":
-      state = await runInteraction(state)
-      break
-    case "feedback":
-      renderFeedback(state.feedbackContent, state.isCorrect)
-      state = await state.advance()
-      break
-    case "errored":
-      if (state.retriable) {
-        state = await state.retry()
-        break
-      }
-      throw state.error
-  }
+	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
+		}
+	}
 }
-```
 
----
+if (state.phase === "fatal") {
+	throw state.error
+}
+```
 
 # `/server`
 
+The server subpath is backend-only. It wraps the token endpoint and hides raw HTTP response details.
+
 ```ts
 import { createPrimerServer } from "@superbuilders/primer-tives/server"
-import type {
-  PrimerServer,
-  PrimerServerConfig,
-  SessionToken,
-  TimebackSession,
-  PlacementHints,
-  PlacementHintsResult
-} from "@superbuilders/primer-tives/server"
-import type { PrimerLogger } from "@superbuilders/primer-tives/logger"
-import { GRADE_LEVELS, type GradeLevel } from "@superbuilders/primer-tives/grade-level"
+import type { GetTokenInput, PrimerServer, PrimerServerConfig } from "@superbuilders/primer-tives/server"
 ```
 
 ## `createPrimerServer(config)`
 
 ```ts
 interface PrimerServerConfig {
-  readonly origin: string                  // e.g. https://sb-primer.vercel.app (no trailing slash)
-  readonly secretKey: string               // your sk_… key
-  readonly fetch?: typeof globalThis.fetch // override (tests, proxies, instrumentation)
-  readonly abort?: AbortController         // wired into every request signal
-  readonly logger: PrimerLogger            // required debug/info/warn/error logger
+	readonly origin: string
+	readonly secretKey: string
+	readonly fetch?: typeof globalThis.fetch
+	readonly abort?: AbortController
+	readonly logger: PrimerLogger
 }
 
 function createPrimerServer(config: PrimerServerConfig): PrimerServer
 ```
 
-Returns a `PrimerServer` with exactly four methods:
+Config fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `origin` | Yes | Primer deployment origin, for example `https://sb-primer.vercel.app`. |
+| `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`. |
+
+## `PrimerServer`
 
 ```ts
 interface PrimerServer {
-  createStudent(): Promise<string>
-  setStudentHints(studentId: string, hints: PlacementHints): Promise<PlacementHintsResult>
-  exchangeStudentForAccessToken(studentId: string): Promise<SessionToken>
-  exchangeTimebackStudentForAccessToken(sourcedId: string): Promise<TimebackSession>
+	getToken(input: GetTokenInput): Promise<string>
+}
+
+type GetTokenInput = {
+	readonly verifiedEmail: string
 }
 ```
 
-## Method reference
+`getToken` returns the browser access token string directly. It does not return a session object because the browser only needs the token.
 
-### `createStudent()`
+The SDK sends this wire body:
 
-Provision a new frontend-owned Primer student and return its stable `studentId`. Use only for the native/manual flow.
+```json
+{
+	"verified_email": "student@example.com"
+}
+```
+
+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.
 
-Persist the returned `studentId` in your own database. Before the student's first session, call `setStudentHints(studentId, { gradeLevel })`.
+## `verifiedEmail`
 
-### `setStudentHints(studentId, hints)`
+`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.
 
-Partial upsert of a native/manual student's placement-routing hints. Omitted fields are left untouched; the server returns the persisted state after upsert.
+Correct usage:
 
 ```ts
-const { gradeLevel } = await primer.setStudentHints(studentId, { gradeLevel: "3" })
+const accessToken = await primer.getToken({ verifiedEmail: authenticatedUser.email })
 ```
 
-- Required for native/manual students before their first session. If the browser calls `/advance` without a `gradeLevel` on record, the server returns HTTP 412 `needs_hints` and the SDK surfaces it as `ErrNeedsHints` on a `fatal` state.
-- Safe to call repeatedly. Each call is a partial upsert.
-- Not needed for Timeback-linked students: `exchangeTimebackStudentForAccessToken` syncs the grade level from the authority on every call.
-- Throws `ErrStudentNotFound` if `studentId` is unknown; `ErrBadRequest` if the payload fails validation (e.g. unsupported `gradeLevel`).
+Only do this after your own auth system has verified `authenticatedUser.email`.
+
+Incorrect usage:
+
+```ts
+const accessToken = await primer.getToken({ verifiedEmail: request.body.email })
+```
 
-### `exchangeStudentForAccessToken(studentId)`
+That treats an untrusted browser payload as identity proof and defeats the security model.
 
-Mint a short-lived access token for an existing native/manual Primer student. Call at every session start.
+## Server Error Sentinels
 
-If `studentId` belongs to a Timeback-linked student, throws `ErrExternalAuthorityRequired`. Tokens are short-lived (typically 15 minutes).
+Import sentinels from `/errors`, not `/server`.
 
-### `exchangeTimebackStudentForAccessToken(sourcedId)`
+```ts
+import { ErrInvalidSecretKey, ErrBadRequest } from "@superbuilders/primer-tives/errors"
+```
 
-Live Timeback session start. Verifies the learner against Timeback on every call, resolves or provisions the corresponding Primer student row, and returns the stable `studentId`, the short-lived `accessToken`, and `expiresInSeconds`.
+`getToken` can surface:
 
-Use at every Timeback session start. Persist `studentId` if you need a stable Primer foreign key.
+| Sentinel | Raised when |
+| --- | --- |
+| `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. |
 
-## Return types
+Recommended pattern:
 
 ```ts
-interface SessionToken {
-  readonly accessToken: string
-  readonly expiresInSeconds: number
+import * as errors from "@superbuilders/errors"
+import * as logger from "@superbuilders/slog"
+import { ErrBadRequest, ErrInvalidSecretKey } from "@superbuilders/primer-tives/errors"
+
+const result = await errors.try(primer.getToken({ verifiedEmail }))
+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")
+	}
+	logger.error("primer token failed", { error: result.error })
+	throw errors.wrap(result.error, "primer token")
 }
 
-interface TimebackSession {
-  readonly studentId: string
-  readonly accessToken: string
-  readonly expiresInSeconds: number
-}
+const accessToken = result.data
+```
 
-interface PlacementHints {
-  readonly gradeLevel?: GradeLevel
-}
+# `/client`
+
+The client subpath owns the browser runtime state machine.
+
+```ts
+import { create } from "@superbuilders/primer-tives/client"
+import type { Client, Config, PrimerState } from "@superbuilders/primer-tives/client"
+```
+
+## `create(config)`
+
+```ts
+function create<const S extends SubjectScope, const Pcis extends PciId = never>(
+	config: Config<S, Pcis>
+): Client<PciId>
+```
+
+Config shape:
+
+```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>
+```
+
+Fields:
+
+| 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:
+
+- `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`.
 
-interface PlacementHintsResult {
-  readonly studentId: string
-  readonly gradeLevel: GradeLevel | null
+## `Client`
+
+```ts
+interface Client<Pcis extends PciId = PciId> {
+	start(): Promise<PrimerState<Pcis>>
 }
 ```
 
-`gradeLevel` in `PlacementHintsResult` is `null` only on native students who have never had one set.
+`start()` sends the first observation request. It is idempotent: multiple calls return the same pending promise.
 
-## Rules of the road
+## Subject Scopes
 
-- Native/manual flow: `createStudent()` once, then `exchangeStudentForAccessToken(studentId)` every session.
-- Timeback flow: `exchangeTimebackStudentForAccessToken(sourcedId)` every session.
-- Student ids are stable identifiers, not browser credentials. Always hand the browser a fresh `accessToken` from your backend.
-- Server-only secrets: keep `secretKey` on your backend; never ship it to the browser.
+```ts
+import { SUBJECTS } from "@superbuilders/primer-tives/subject"
+import type { Subject, SubjectScope } from "@superbuilders/primer-tives/subject"
 
----
+const SUBJECTS = ["math", "vocabulary", "science"] as const
+type Subject = (typeof SUBJECTS)[number]
+type SubjectScope = Subject | "all"
+```
 
-# `/client`
+| 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.
+
+## Required PCIs
+
+Math currently requires the fraction-input PCI. Vocabulary and science currently require none.
 
 ```ts
-import { create } from "@superbuilders/primer-tives/client"
-import type {
-  Client,
-  Config,
-  PrimerState,
-  ObservationState,
-  InteractionState,
-  ChoiceState,
-  TextEntryState,
-  ExtendedTextState,
-  ExtendedTextSingleState,
-  ExtendedTextMultipleState,
-  OrderState,
-  MatchState,
-  PciInteractionState,
-  FeedbackState,
-  CompletedState,
-  ErroredState,
-  FatalState,
-  NonSerializable,
-  PciPendingRenderProps,
-  PciSubmittedRenderProps,
-  PciRenderProps
-} from "@superbuilders/primer-tives/client"
-```
-
-The `/client` subpath owns the **runtime state machine** only. Wire-shape types (`RendererInteraction`, `RendererSubmission`, `ContentInline`, PCI base types, review types) come from `/contracts`.
+import { missingPcisForSubject, requiredPcisForSubject } from "@superbuilders/primer-tives/subject-pcis"
 
-## `create(config)`
+requiredPcisForSubject("math")
+// ["urn:primer:pci:fraction-input"]
+```
+
+For math or `all`, pass a `supportedPcis` literal array that includes `"urn:primer:pci:fraction-input"`.
+
+```ts
+const client = create({
+	origin,
+	accessToken,
+	subject: "math",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+})
+```
+
+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.
+
+# `PrimerState`
+
+`PrimerState` is a discriminated union over `phase`.
 
 ```ts
-function create<const Pcis extends PciId>(config: Config<Pcis>): Client<Pcis>
+type PrimerState<Pcis extends PciId = PciId> =
+	| ObservationState<Pcis>
+	| InteractionState<Pcis>
+	| FeedbackState<Pcis>
+	| CompletedState
+	| ErroredState<Pcis>
+	| 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.
+
+## `ObservationState`
 
-interface Config<Pcis extends PciId = PciId> {
-  readonly accessToken: string
-  readonly supportedPcis: readonly Pcis[]
-  readonly origin: string
-  readonly subject: SubjectScope
-  readonly fetch?: typeof globalThis.fetch
-  readonly abort?: AbortController
-  readonly logger?: PrimerLogger
+```ts
+interface ObservationState<Pcis extends PciId = PciId> extends NonSerializable {
+	readonly phase: "observation"
+	readonly body: ContentBlock[]
+	readonly stimulus: RendererStimulus | null
+	advance(): Promise<PrimerState<Pcis>>
 }
+```
 
-interface Client<Pcis extends PciId = PciId> {
-  start(): Promise<PrimerState<Pcis>>          // idempotent
+Render `body` and `stimulus`, then call `advance()` when the learner is ready to continue. Observation frames have no interaction to submit.
+
+## `InteractionState`
+
+`InteractionState` is a union over `kind`.
+
+| `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>)` |
+
+Every interaction state includes:
+
+- `phase: "interaction"`
+- `body`
+- `stimulus`
+- `interaction`
+- a typed submit method
+- `timeout(): Promise<PrimerState<Pcis>>`
+
+Interaction submissions are validated client-side before transport. Invalid payloads return an `errored` state with `ErrInvalidSubmission`; they are not sent to the server.
+
+### Choice
+
+```ts
+interface ChoiceState<Pcis extends PciId = PciId> extends NonSerializable {
+	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
+	submitChoice(selectedKeys: string[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
 }
 ```
 
-`create()` does a structural check on the token (must start with `eyJ` and contain two dots) and throws `ErrMalformedAccessToken` if the shape is wrong. Signature verification happens on the server.
+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.
 
-## `PrimerState` — the state machine
+### Text Entry
 
 ```ts
-type PrimerState =
-  | ObservationState     // .advance()
-  | InteractionState     // .submit…() / .timeout()
-  | FeedbackState        // .advance()
-  | CompletedState       // terminal
-  | ErroredState         // .retry() — .retriable: boolean
-  | FatalState           // terminal
+interface TextEntryState<Pcis extends PciId = PciId> extends NonSerializable {
+	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>>
+}
 ```
 
-### Interaction action methods
+`interaction` may include `expectedLength`, `patternMask`, and `placeholderText` for UI hints.
 
-`InteractionState` is a discriminated union over `kind`:
+### Extended Text
 
-| `kind` | method |
-|---|---|
-| `choice` | `submitChoice(selectedKeys: string[])` |
-| `text-entry` | `submitText(value: string)` |
-| `extended-text` (single) | `submitText(value: string)` |
-| `extended-text` (multiple) | `submitTexts(values: string[])` |
-| `order` | `submitOrder(orderedKeys: string[])` |
-| `match` | `submitMatch(pairs: MatchPair[])` |
-| `portable-custom` | `submit(value: PciValue<K>)` |
+Extended text has two cardinalities.
+
+```ts
+interface ExtendedTextSingleState<Pcis extends PciId = PciId> extends NonSerializable {
+	readonly phase: "interaction"
+	readonly kind: "extended-text"
+	readonly cardinality: "single"
+	submitText(value: string): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
 
-Every `InteractionState` shape also exposes `timeout(): Promise<PrimerState>`.
+interface ExtendedTextMultipleState<Pcis extends PciId = PciId> extends NonSerializable {
+	readonly phase: "interaction"
+	readonly kind: "extended-text"
+	readonly cardinality: "multiple"
+	readonly minStrings: number
+	readonly maxStrings: number
+	submitTexts(values: string[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
+}
+```
 
-`MatchPair`, `PciValue<K>` come from `/contracts`.
+Both include `body`, `stimulus`, and `interaction` fields like every other interaction state.
 
-### `FeedbackState`
+### Order
 
 ```ts
-interface FeedbackState extends NonSerializable {
-  readonly phase: "feedback"
-  readonly stimulus: RendererStimulus | null
-  readonly interaction: RendererInteraction
-  readonly submission: RendererSubmission
-  readonly isCorrect: boolean
-  readonly feedbackContent: ContentInline[]
-  readonly review: InteractionReview | null
-  advance(): Promise<PrimerState>
+interface OrderState<Pcis extends PciId = PciId> extends NonSerializable {
+	readonly phase: "interaction"
+	readonly kind: "order"
+	readonly choices: RendererChoice[]
+	readonly minChoices: number
+	readonly maxChoices: number
+	submitOrder(orderedKeys: string[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
 }
 ```
 
-`RendererStimulus`, `RendererInteraction`, `RendererSubmission`, `ContentInline`, `InteractionReview` all come from `/contracts`.
+Submit identifiers in learner-selected order.
 
-### `ErroredState`
+### Match
 
 ```ts
-interface ErroredState extends NonSerializable {
-  readonly phase: "errored"
-  readonly error: Error                       // sentinel-wrapped
-  readonly retriable: boolean
-  retry(): Promise<PrimerState>               // no-op on non-retriable
+interface MatchPair {
+	source: string
+	target: string
+}
+
+interface MatchState<Pcis extends PciId = PciId> extends NonSerializable {
+	readonly phase: "interaction"
+	readonly kind: "match"
+	readonly sourceChoices: RendererMatchChoice[]
+	readonly targetChoices: RendererMatchChoice[]
+	readonly minAssociations: number
+	readonly maxAssociations: number
+	submitMatch(pairs: MatchPair[]): Promise<PrimerState<Pcis>>
+	timeout(): Promise<PrimerState<Pcis>>
 }
 ```
 
-`errored.retriable === false` for client-validation errors (e.g. wrapped `ErrInvalidSubmission`) and for non-recoverable transports. Those must be fixed, not retried.
+Each `RendererMatchChoice` has `matchMin` and `matchMax`. A `matchMax` of `0` means unbounded.
 
-### `FatalState`
+### Portable Custom Interaction
+
+```ts
+type PciInteractionState<Pcis extends PciId = PciId> = {
+	[K in Pcis]: NonSerializable & {
+		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]
+```
 
-Unrecoverable failure (bad request, invalid token, expired token, unsupported PCI, forbidden):
+For `urn:primer:pci:fraction-input`, `properties` has:
 
 ```ts
-interface FatalState extends NonSerializable {
-  readonly phase: "fatal"
-  readonly error: Error
-  readonly retriable: false
+interface FractionInputProps {
+	form: "whole" | "proper" | "improper" | "mixed"
+	requireSimplified: boolean
 }
 ```
 
-## PCI render props
+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 }
+```
 
-Only the renderer-side render props live here. PCI base types (`PciId`, `PciProps`, `PciValue`, `PciRegistry`, `PciUrn`, plus the per-PCI `*Props`/`*Submission` interfaces) come from `/contracts`.
+## `FeedbackState`
 
 ```ts
-type PciPendingRenderProps<K extends PciId> = {
-  mode: "pending"
-  properties: PciProps<K>
-  onValueChange: (value: PciValue<K> | null) => void
+interface FeedbackState<Pcis extends PciId = PciId> extends NonSerializable {
+	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 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.
+
+## `CompletedState`
 
-type PciSubmittedRenderProps<K extends PciId> = {
-  mode: "submitted"
-  properties: PciProps<K>
-  submission: PciValue<K>
-  review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
+```ts
+interface CompletedState extends NonSerializable {
+	readonly phase: "completed"
 }
+```
+
+Terminal state. There is no action method.
 
-type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRenderProps<K>
+## `ErroredState`
+
+```ts
+interface ErroredState<Pcis extends PciId = PciId> extends NonSerializable {
+	readonly phase: "errored"
+	readonly error: Error
+	readonly retriable: boolean
+	retry(): Promise<PrimerState<Pcis>>
+}
 ```
 
-## Behavioral notes
+`retry()` re-runs the exact same intent that failed. If `retriable` is false, `retry()` resolves to the same errored state.
 
-- `start()` is idempotent — calling it twice returns the same promise.
-- A returning student resumes wherever the server last placed them. No client-side cursor management.
-- `PrimerState` holds real closures (action methods, pending-promise caches). Don't serialize it; don't store it across reloads. Call `start()` again on boot.
-- `Config.supportedPcis` is a `const` generic; only those URNs flow through `PciInteractionState` at the type level. Mismatch at runtime is a `fatal` with `ErrUnsupportedPci`.
+## `FatalState`
 
----
+```ts
+interface FatalState extends NonSerializable {
+	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.
 
 # `/contracts`
 
-Wire-shape types, Zod schemas, review types, and an optional submission validator. Safe to import from either side of the wire — backend code lives here too.
+The contracts subpath contains renderer wire shapes and helpers shared between custom renderers and server-adjacent tooling.
 
 ```ts
 import {
-  ChoiceSubmissionSchema,
-  TextEntrySubmissionSchema,
-  ExtendedTextSubmissionSchema,
-  OrderSubmissionSchema,
-  MatchSubmissionSchema,
-  MatchPairSchema,
-  DivisionRemainderPciSubmissionSchema,
-  FractionAdditionPciSubmissionSchema,
-  RendererSubmissionSchema,
-  validateSubmissionForInteraction,
-  submissionValidationMessage,
-  blocksToPlainText,
-  inlinesToPlainText
+	RendererSubmissionSchema,
+	blocksToPlainText,
+	inlinesToPlainText,
+	submissionValidationMessage,
+	validateSubmissionForInteraction
 } from "@superbuilders/primer-tives/contracts"
-
 import type {
-  // interaction & submission shapes
-  RendererInteraction,
-  RendererSubmission,
-  StandardRendererInteraction,
-  PciInteraction,
-  PciSubmission,
-  // stimulus shapes
-  RendererStimulus,
-  BodyStimulus,
-  ImageStimulus,
-  // choice shapes
-  RendererChoice,
-  RendererMatchChoice,
-  MatchPair,
-  // content
-  ContentBlock,
-  ContentInline,
-  ContentSpan,
-  // PCI base
-  PciId,
-  PciUrn,
-  PciRegistry,
-  PciProps,
-  PciValue,
-  DivisionRemainderProps,
-  DivisionRemainderSubmission,
-  FractionAdditionProps,
-  FractionAdditionSubmission,
-  // review (server emits these, client consumes)
-  InteractionReview,
-  ChoiceReview,
-  TextEntryReview,
-  ExtendedTextReview,
-  OrderReview,
-  MatchReview,
-  PciReview,
-  ReviewRecordField,
-  ReviewRecordFieldBaseType,
-  ReviewScalarValue,
-  // validation result
-  SubmissionValidationResult,
-  SubmissionValidationSuccess,
-  SubmissionValidationFailure
+	ContentBlock,
+	ContentInline,
+	ContentSpan,
+	ImageStimulus,
+	InteractionReview,
+	MatchPair,
+	PciId,
+	PciInteraction,
+	PciProps,
+	PciSubmission,
+	PciValue,
+	RendererChoice,
+	RendererInteraction,
+	RendererMatchChoice,
+	RendererStimulus,
+	RendererSubmission,
+	StandardRendererInteraction
 } from "@superbuilders/primer-tives/contracts"
 ```
 
-## Schemas
+## Content
 
-Every `RendererSubmission` variant has a Zod schema; `RendererSubmissionSchema` is the discriminated union over all of them and is the canonical `safeParse`-able wire shape.
+```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
-import * as errors from "@superbuilders/errors"
-import * as logger from "@superbuilders/slog"
-import { RendererSubmissionSchema } from "@superbuilders/primer-tives/contracts"
+inlinesToPlainText(nodes: ContentInline[]): string
+blocksToPlainText(blocks: ContentBlock[]): string
+```
+
+Use these helpers for accessibility labels, alt fallbacks, logging summaries, and non-rich previews.
 
-const result = RendererSubmissionSchema.safeParse(unknownPayload)
-if (!result.success) {
-  logger.error("submission payload failed schema parse", { issues: result.error.issues })
-  throw errors.wrap(result.error, "renderer submission parse")
+## Stimulus
+
+```ts
+interface ImageStimulus {
+	kind: "image"
+	alt: ContentInline[]
+	src: string
 }
-const submission = result.data
+
+type RendererStimulus = ImageStimulus
 ```
 
-## `validateSubmissionForInteraction(interaction, submission)`
+`RendererStimulus` is currently image-only, but it is still a discriminated union so renderers stay future-safe.
 
-Optional semantic validator. Checks a submission against the interaction it claims to answer (cardinality bounds, identifier membership, duplicate rules, PCI payload shape).
+## Interactions
 
 ```ts
-function validateSubmissionForInteraction(
-  interaction: RendererInteraction,
-  submission: RendererSubmission
-): SubmissionValidationResult
-
-type SubmissionValidationResult =
-  | { ok: true;  value: RendererSubmission }
-  | { ok: false; issues: readonly string[] }
+type RendererInteraction<Pcis extends PciId = PciId> =
+	| StandardRendererInteraction
+	| PciInteraction<Pcis>
 ```
 
-`submissionValidationMessage(failure)` joins `failure.issues` with `"; "` for a single string.
+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
-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"
+interface RendererChoice {
+	identifier: string
+	content: ContentInline[]
+}
+```
 
-const validation = validateSubmissionForInteraction(interaction, submission)
-if (!validation.ok) {
-  logger.warn("submission rejected by contract validation", { issues: validation.issues })
-  throw errors.wrap(ErrInvalidSubmission, submissionValidationMessage(validation))
+Match choice objects:
+
+```ts
+interface RendererMatchChoice {
+	identifier: string
+	content: ContentInline[]
+	matchMax: number
+	matchMin: number
 }
 ```
 
-Validation is **optional at every layer**. The Primer server grades submissions independently and is the only correctness boundary that matters. The browser SDK's built-in interaction state machines call this validator on your behalf before each submit; if you bypass those state machines and write to the wire yourself, you decide whether to validate.
+## 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>
+```
 
-# `/errors`
+Schemas:
 
-Every sentinel `Err…` value used by the SDK lives here and only here. Use `errors.is()` from `@superbuilders/errors` to type-check against them.
+```ts
+ChoiceSubmissionSchema
+TextEntrySubmissionSchema
+ExtendedTextSubmissionSchema
+OrderSubmissionSchema
+MatchSubmissionSchema
+FractionInputPciSubmissionSchema
+RendererSubmissionSchema
+```
+
+Always use `safeParse` when parsing arbitrary input:
 
 ```ts
-import {
-  // shared (server + client transport)
-  ErrBadRequest,
-  ErrConflict,
-  ErrJsonParse,
-  ErrNetwork,
-  ErrServerError,
-  ErrTimeout,
-  // /server-thrown
-  ErrInvalidSecretKey,
-  ErrStudentNotFound,
-  ErrUnsupportedGrade,
-  ErrTimebackUnavailable,
-  ErrExternalAuthorityRequired,
-  // /client surfaced as `errored`
-  ErrServiceUnavailable,
-  ErrRateLimited,
-  ErrInvalidSubmission,
-  // /client surfaced as `fatal`
-  ErrInvalidAccessToken,
-  ErrTokenExpired,
-  ErrForbidden,
-  ErrNotFound,
-  ErrNeedsHints,
-  ErrUnsupportedPci,
-  // /client thrown directly by `create()`
-  ErrMalformedAccessToken,
-  ErrNotSerializable
-} from "@superbuilders/primer-tives/errors"
+const parsed = RendererSubmissionSchema.safeParse(payload)
+if (!parsed.success) {
+	throw parsed.error
+}
 ```
 
-## Server-side method failures
+## Semantic Validation
 
-| Sentinel | Raised when |
-|---|---|
-| `ErrInvalidSecretKey` | HTTP 401 — missing, malformed, or unknown `sk_` |
-| `ErrStudentNotFound` | HTTP 404 — native `studentId` unknown on this frontend, or Timeback `sourcedId` unknown upstream |
-| `ErrUnsupportedGrade` | HTTP 400 — Timeback returned a grade outside Primer's supported range |
-| `ErrTimebackUnavailable` | HTTP 502 — Timeback OneRoster endpoint failed during live exchange |
-| `ErrExternalAuthorityRequired` | HTTP 409 — attempted native/manual exchange for a Timeback-linked student |
-| `ErrConflict` | HTTP 409 — frontend not provisioned for routing/content |
-| `ErrBadRequest` | HTTP 400 — validation failure |
-| `ErrServerError` | HTTP 5xx |
-| `ErrJsonParse` | response body was not valid JSON or had the wrong shape |
-| `ErrNetwork` | `fetch()` rejected (DNS, connection, TLS, etc.) |
-| `ErrTimeout` | `fetch()` aborted |
-
-## Client `errored.error`
+`RendererSubmissionSchema` validates shape. `validateSubmissionForInteraction` validates a submission against a specific interaction.
 
-| Sentinel | Raised when |
-|---|---|
-| `ErrNetwork` | `fetch()` rejected |
-| `ErrTimeout` | `fetch()` aborted |
-| `ErrServerError` | HTTP 5xx |
-| `ErrServiceUnavailable` | HTTP 502/503/504 |
-| `ErrRateLimited` | HTTP 429 |
-| `ErrConflict` | HTTP 409 |
-| `ErrJsonParse` | success body wasn't valid JSON |
-| `ErrInvalidSubmission` | client-side validation rejected the submission |
-
-## Client `fatal.error`
+```ts
+const validation = validateSubmissionForInteraction(interaction, submission)
+if (!validation.ok) {
+	throw errors.wrap(ErrInvalidSubmission, submissionValidationMessage(validation))
+}
+```
 
-| Sentinel | Raised when |
-|---|---|
-| `ErrBadRequest` | HTTP 400 |
-| `ErrInvalidAccessToken` | HTTP 401 |
-| `ErrTokenExpired` | HTTP 401 with token-expired detail |
-| `ErrForbidden` | HTTP 403 |
-| `ErrNotFound` | HTTP 404 |
-| `ErrNeedsHints` | HTTP 412 — the student has no `gradeLevel` on record; backend must call `setStudentHints` and mint a fresh access token |
-| `ErrUnsupportedPci` | HTTP 422 or a frame asks for a PCI not in `supportedPcis` |
+Checks include:
 
-## Thrown directly by `create()`
+- 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
 
-| Sentinel | Raised when |
-|---|---|
-| `ErrMalformedAccessToken` | token doesn't start with `eyJ` or lacks two dots |
-| `ErrNotSerializable` | you called `JSON.stringify()` on a live `PrimerState` (don't) |
+The built-in browser state objects call this before submitting. Custom renderers that bypass state methods should call it themselves.
 
-## Recommended consumer pattern
+## Review Types
 
-Per `@superbuilders/errors`: log every error before throwing, wrap external errors with terse Go-style context, never bare `throw new Error(...)`.
+`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` is for display and inspection. Correctness already lives on `FeedbackState.isCorrect`.
+
+# `/errors`
+
+All sentinels are exported from `/errors`.
 
 ```ts
-import * as errors from "@superbuilders/errors"
-import * as logger from "@superbuilders/slog"
 import {
-  ErrExternalAuthorityRequired,
-  ErrInvalidSecretKey,
-  ErrStudentNotFound
+	ErrBadRequest,
+	ErrConflict,
+	ErrForbidden,
+	ErrInvalidAccessToken,
+	ErrInvalidSecretKey,
+	ErrInvalidSubmission,
+	ErrJsonParse,
+	ErrMalformedAccessToken,
+	ErrMissingRequiredPci,
+	ErrNetwork,
+	ErrNotFound,
+	ErrNotSerializable,
+	ErrRateLimited,
+	ErrSdkUpgradeRequired,
+	ErrServerError,
+	ErrServiceUnavailable,
+	ErrTimeout,
+	ErrTokenExpired,
+	ErrUnsupportedPci
 } from "@superbuilders/primer-tives/errors"
-
-const tokenResult = await errors.try(primer.exchangeStudentForAccessToken(studentId))
-if (tokenResult.error) {
-  if (errors.is(tokenResult.error, ErrInvalidSecretKey)) {
-    logger.error("primer secret key invalid", { error: tokenResult.error })
-    throw errors.wrap(tokenResult.error, "primer token exchange")
-  }
-  if (errors.is(tokenResult.error, ErrStudentNotFound)) {
-    logger.error("primer student id stale", { studentId, error: tokenResult.error })
-    throw errors.wrap(tokenResult.error, "primer token exchange")
-  }
-  if (errors.is(tokenResult.error, ErrExternalAuthorityRequired)) {
-    logger.error("primer student requires timeback exchange", {
-      studentId,
-      error: tokenResult.error
-    })
-    throw errors.wrap(tokenResult.error, "primer token exchange")
-  }
-  logger.error("primer token exchange failed", { error: tokenResult.error })
-  throw errors.wrap(tokenResult.error, "primer token exchange")
-}
-const { accessToken } = tokenResult.data
 ```
 
----
+## Server SDK 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. |
+
+## Browser Transport Errors
+
+These become `ErroredState` unless classified as fatal:
+
+| 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. |
+
+## Browser Fatal Errors
+
+These become `FatalState`:
+
+| 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`. |
+
+## Direct Client Construction Errors
+
+| 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`. |
 
 # `/logger`
 
@@ -707,16 +884,21 @@ const { accessToken } = tokenResult.data
 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
+	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
 }
 ```
 
-Required by `PrimerServerConfig`, optional on `Config` (the client config). `@superbuilders/slog` matches this shape directly — `import * as logger from "@superbuilders/slog"` and pass `logger`.
+The same logger shape is used by server and browser SDKs. `@superbuilders/slog` matches it directly:
+
+```ts
+import * as logger from "@superbuilders/slog"
 
----
+const primer = createPrimerServer({ origin, secretKey, logger })
+const client = create({ origin, accessToken, subject: "vocabulary", logger })
+```
 
 # `/grade-level`
 
@@ -728,26 +910,55 @@ const GRADE_LEVELS = ["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "1
 type GradeLevel = (typeof GRADE_LEVELS)[number]
 ```
 
-Used as the `gradeLevel` field on `PlacementHints` / `PlacementHintsResult`.
+The server SDK no longer accepts a grade argument. Primer asks the learner for selected grade inside the browser runtime if needed.
 
----
+# Onboarding Grade Selection
 
-# `/subject`
+Grade selection is not a separate SDK API.
 
-```ts
-import { SUBJECTS } from "@superbuilders/primer-tives/subject"
-import type { Subject, SubjectScope } from "@superbuilders/primer-tives/subject"
+If the learner's email profile has no selected grade yet, the first `/advance` response is a normal `choice` interaction:
 
-const SUBJECTS = ["math", "vocabulary", "science"] as const
-type Subject = (typeof SUBJECTS)[number]
-type SubjectScope = Subject | "all"
-```
+- `phase: "interaction"`
+- `kind: "choice"`
+- `minChoices: 1`
+- `maxChoices: 1`
+- options with identifiers from `GRADE_LEVELS`
+
+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.
+
+This design keeps the SDK small:
+
+- 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
+
+# Integration Checklist
+
+Use this as the minimum correct integration:
+
+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.
+
+# What This SDK Does Not Do
 
-Used as the `subject` field on the client `Config`.
+The current SDK does not expose:
 
-| Value | Behavior |
-|---|---|
-| `"math"` / `"vocabulary"` / `"science"` | restrict drill selection to courses of that subject |
-| `"all"` | no filter; drills from any subject the frontend is bound to |
+- 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
 
-Per-session. To switch subjects, construct a new client. Student placements are isolated per subject — a student with an in-progress math placement resumes it on a math-scoped reconnect, a new vocabulary-scoped client bootstraps a fresh vocabulary placement, and neither disturbs the other. Curriculum routing is not affected by `subject`.
+Those omissions are intentional. The public integration point is one backend method, `getToken`, and one browser state machine, `create(...).start()`.