@superbuilders/primer-tives 2.2.1 → 3.5.0

package/README.md

@@ -2,378 +2,178 @@
 
 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 frame, and returns a live learning state. There is no public auth result union, client wrapper, `start()` method, `snapshot()` API, or branded state type.
 
 ```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
+## Version
 
-The current SDK version is `2.2.1`.
+The current SDK version is `3.5.0`.
 
-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 SDK sends `X-Primer-SDK-Version: 3.5.0` on `/api/v0/advance`.
 
 ## 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
-
-Primer's runtime has three identities in play:
+There is no package-root export.
 
-| 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`, state interfaces, PCI render props |
+| `@superbuilders/primer-tives/contracts` | Content, stimulus, interaction, submission, review, PCI types, validation helpers |
+| `@superbuilders/primer-tives/errors` | SDK error sentinels |
+| `@superbuilders/primer-tives/logger` | `PrimerLogger` interface |
+| `@superbuilders/primer-tives/subject` | `Subject`, `SUBJECTS` |
+| `@superbuilders/primer-tives/subject-pcis` | Subject-required PCI 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 requires the fraction-input PCI capability:
 
 ```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({
+const 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 you already have a Cognito/OIDC access token, pass it directly:
 
 ```ts
-import * as logger from "@superbuilders/slog"
-import { create, type PrimerState } from "@superbuilders/primer-tives/client"
-
-const client = create({
+const 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
-		}
-	}
-}
-
-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 { GetTokenInput, PrimerServer, PrimerServerConfig } from "@superbuilders/primer-tives/server"
 ```
 
-## `createPrimerServer(config)`
+Vocabulary has no required PCI capability, so `supportedPcis` can be omitted:
 
 ```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
-```
-
-Config fields:
-
-| 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`. |
-
-## `PrimerServer`
-
-```ts
-interface PrimerServer {
-	getToken(input: GetTokenInput): Promise<string>
-}
-
-type GetTokenInput = {
-	readonly verifiedEmail: string
-}
-```
-
-`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"
-}
-```
-
-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:
-
-```ts
-const accessToken = await primer.getToken({ verifiedEmail: authenticatedUser.email })
-```
-
-Only do this after your own auth system has verified `authenticatedUser.email`.
-
-Incorrect usage:
-
-```ts
-const accessToken = await primer.getToken({ verifiedEmail: request.body.email })
-```
-
-That treats an untrusted browser payload as identity proof and defeats the security model.
-
-## Server Error Sentinels
-
-Import sentinels from `/errors`, not `/server`.
-
-```ts
-import { ErrInvalidSecretKey, ErrBadRequest } from "@superbuilders/primer-tives/errors"
-```
-
-`getToken` can surface:
-
-| 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. |
-
-Recommended pattern:
-
-```ts
-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")
-}
-
-const accessToken = result.data
-```
-
-# `/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"
+const state = await create({
+	origin: "https://primerlearn.dev",
+	publishableKey: "pk_...",
+	subject: "vocabulary",
+	logger
+})
 ```
 
-## `create(config)`
+Omitting `subject` means the SDK asks Primer for the internal all-subject runtime scope. Because that can include any subject, the required PCI set is the union of all subject-required PCIs:
 
 ```ts
-function create<const S extends SubjectScope, const Pcis extends PciId = never>(
-	config: Config<S, Pcis>
-): Client<PciId>
+const state = await create({
+	origin: "https://primerlearn.dev",
+	publishableKey: "pk_...",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+})
 ```
 
-Config shape:
+## PrimerOptions
 
 ```ts
-type Config<S extends SubjectScope, Pcis extends PciId = never> = {
-	readonly accessToken: string
-	readonly subject: S
+type PrimerOptions<S extends Subject | undefined = undefined, Pcis extends PciId = never> = {
 	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
-} & 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. |
+| Field | Meaning |
+| --- | --- |
+| `origin` | Primer deployment origin. |
+| `publishableKey` | Public Primer frontend key. |
+| `accessToken` | Optional Cognito/OIDC learner access token. When present, hosted auth is skipped. |
+| `subject` | Optional content scope. Omitted means internal all-subject scope. Public callers do not pass `"all"`. |
+| `supportedPcis` | Renderer PCI capabilities. Required or optional based on `subject`. |
+| `fetch` | Optional fetch override for tests/instrumentation. |
+| `abort` | Optional abort controller for runtime requests. |
+| `logger` | Structured logger implementing `debug`, `info`, `warn`, and `error`. |
+
+The presence or absence of `accessToken` selects auth behavior:
+
+| Shape | Behavior |
+| --- | --- |
+| `accessToken` present | Use provided access token, then call `/api/v0/advance`. |
+| `accessToken` absent | Resolve a token through Primer-hosted auth, then call `/api/v0/advance`. |
 
-`create` performs local checks before any network request:
+Hosted auth storage, callback parsing, popup details, and state handling are SDK internals.
 
-- `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`.
+## Subject And PCI Contract
 
-## `Client`
+`subject` selects content scope and determines required renderer capabilities.
 
-```ts
-interface Client<Pcis extends PciId = PciId> {
-	start(): Promise<PrimerState<Pcis>>
-}
-```
+`supportedPcis` declares which Portable Custom Interactions the host renderer can render. It may be a superset of the required PCIs.
 
-`start()` sends the first observation request. It is idempotent: multiple calls return the same pending promise.
+The SDK enforces subject-required PCI capability in TypeScript:
 
-## Subject Scopes
+| Public subject option | Required `supportedPcis` |
+| --- | --- |
+| omitted | union of all subject-required PCIs, currently `"urn:primer:pci:fraction-input"` |
+| `"math"` | `"urn:primer:pci:fraction-input"` |
+| `"vocabulary"` | none |
+| `"science"` | none |
 
-```ts
-import { SUBJECTS } from "@superbuilders/primer-tives/subject"
-import type { Subject, SubjectScope } from "@superbuilders/primer-tives/subject"
+The check is a subset check:
 
-const SUBJECTS = ["math", "vocabulary", "science"] as const
-type Subject = (typeof SUBJECTS)[number]
-type SubjectScope = Subject | "all"
+```txt
+required PCIs for subject ⊆ supportedPcis
 ```
 
-| 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.
+Order does not matter. Extra supported PCIs are allowed.
 
-## Required PCIs
-
-Math currently requires the fraction-input PCI. Vocabulary and science currently require none.
+This fails at compile time:
 
 ```ts
-import { missingPcisForSubject, requiredPcisForSubject } from "@superbuilders/primer-tives/subject-pcis"
-
-requiredPcisForSubject("math")
-// ["urn:primer:pci:fraction-input"]
+await create({
+	origin,
+	publishableKey,
+	subject: "math",
+	logger
+})
 ```
 
-For math or `all`, pass a `supportedPcis` literal array that includes `"urn:primer:pci:fraction-input"`.
+This passes:
 
 ```ts
-const client = create({
+await create({
 	origin,
-	accessToken,
+	publishableKey,
 	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.
+If `subject` is a broad dynamic `Subject` value, TypeScript requires the union of possible subject-required PCIs. This lets renderer wrappers pass their full supported PCI registry once and get subject-level safety for free.
 
-# `PrimerState`
+The runtime still protects the trust boundary. If the server returns a PCI not declared in `supportedPcis`, the SDK returns `FatalState` with `ErrUnsupportedPci`.
 
-`PrimerState` is a discriminated union over `phase`.
+## PrimerState
+
+`create` returns a `PrimerState` only after auth and the first runtime request have succeeded.
 
 ```ts
 type PrimerState<Pcis extends PciId = PciId> =
@@ -385,580 +185,205 @@ 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.
-
-## `ObservationState`
-
-```ts
-interface ObservationState<Pcis extends PciId = PciId> extends NonSerializable {
-	readonly phase: "observation"
-	readonly body: ContentBlock[]
-	readonly stimulus: RendererStimulus | null
-	advance(): Promise<PrimerState<Pcis>>
-}
-```
-
-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>>
-}
-```
-
-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.
-
-### Text Entry
-
-```ts
-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` may include `expectedLength`, `patternMask`, and `placeholderText` for UI hints.
-
-### Extended Text
-
-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>>
-}
-
-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>>
-}
-```
-
-Both include `body`, `stimulus`, and `interaction` fields like every other interaction state.
+The state machine is structural and discriminated by `phase`, then by `kind` for interactions. Each state exposes only transitions valid from that state.
 
-### Order
-
-```ts
-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>>
-}
+```txt
+observation -> advance
+feedback -> advance
+choice -> submitChoice / timeout
+text-entry -> submitText / timeout
+extended-text -> submitText or submitTexts / timeout
+order -> submitOrder / timeout
+match -> submitMatch / timeout
+portable-custom -> submit / timeout
+completed -> no transition
+fatal -> no transition
 ```
 
-Submit identifiers in learner-selected order.
+The state object is live and non-serializable. Do not put it in storage, JSON, or server data.
 
-### Match
+## Runtime Loop
 
 ```ts
-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>>
-}
-```
-
-Each `RendererMatchChoice` has `matchMin` and `matchMax`. A `matchMax` of `0` means unbounded.
-
-### Portable Custom Interaction
+let state = await create({
+	origin,
+	publishableKey,
+	subject: "math",
+	supportedPcis: ["urn:primer:pci:fraction-input"],
+	logger
+})
 
-```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>>
+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
 	}
-}[Pcis]
-```
-
-For `urn:primer:pci:fraction-input`, `properties` has:
-
-```ts
-interface FractionInputProps {
-	form: "whole" | "proper" | "improper" | "mixed"
-	requireSimplified: boolean
 }
-```
-
-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 {
-	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>>
+if (state.phase === "fatal") {
+	throw state.error
 }
 ```
 
-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.
+## PCI Type Safety
 
-## `CompletedState`
+Portable Custom Interactions are typed by PCI id.
 
 ```ts
-interface CompletedState extends NonSerializable {
-	readonly phase: "completed"
-}
-```
+import type { PciProps, PciValue } from "@superbuilders/primer-tives/contracts"
 
-Terminal state. There is no action method.
-
-## `ErroredState`
-
-```ts
-interface ErroredState<Pcis extends PciId = PciId> extends NonSerializable {
-	readonly phase: "errored"
-	readonly error: Error
-	readonly retriable: boolean
-	retry(): Promise<PrimerState<Pcis>>
-}
+type FractionProps = PciProps<"urn:primer:pci:fraction-input">
+type FractionValue = PciValue<"urn:primer:pci:fraction-input">
 ```
 
-`retry()` re-runs the exact same intent that failed. If `retriable` is false, `retry()` resolves to the same errored state.
-
-## `FatalState`
+When the state is narrowed to a PCI id, `submit` accepts only that PCI's value type.
 
 ```ts
-interface FatalState extends NonSerializable {
-	readonly phase: "fatal"
-	readonly error: Error
-	readonly retriable: false
+if (state.phase === "interaction" && state.kind === "portable-custom") {
+	if (state.pciId === "urn:primer:pci:fraction-input") {
+		const value = readFractionInput(state.properties)
+		state = await state.submit(value)
+	}
 }
 ```
 
-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`
+## Subject PCI Helpers
 
-The contracts subpath contains renderer wire shapes and helpers shared between custom renderers and server-adjacent tooling.
+Use `@superbuilders/primer-tives/subject-pcis` when tooling needs the same contract as the SDK.
 
 ```ts
-import {
-	RendererSubmissionSchema,
-	blocksToPlainText,
-	inlinesToPlainText,
-	submissionValidationMessage,
-	validateSubmissionForInteraction
-} from "@superbuilders/primer-tives/contracts"
-import type {
-	ContentBlock,
-	ContentInline,
-	ContentSpan,
-	ImageStimulus,
-	InteractionReview,
-	MatchPair,
-	PciId,
-	PciInteraction,
-	PciProps,
-	PciSubmission,
-	PciValue,
-	RendererChoice,
-	RendererInteraction,
-	RendererMatchChoice,
-	RendererStimulus,
-	RendererSubmission,
-	StandardRendererInteraction
-} from "@superbuilders/primer-tives/contracts"
-```
+import { requiredPcisForSubject } from "@superbuilders/primer-tives/subject-pcis"
 
-## Content
-
-```ts
-type ContentSpan = { type: "text"; value: string } | { type: "italic"; value: string }
-type ContentInline = ContentSpan | { type: "latex"; value: string }
-type ContentBlock = { type: "paragraph"; children: ContentInline[] }
+const required = requiredPcisForSubject("math")
 ```
 
-Helpers:
+`requiredPcisForSubject(undefined)` returns the all-subject required PCI union.
 
-```ts
-inlinesToPlainText(nodes: ContentInline[]): string
-blocksToPlainText(blocks: ContentBlock[]): string
-```
-
-Use these helpers for accessibility labels, alt fallbacks, logging summaries, and non-rich previews.
+## Errors
 
-## Stimulus
+Errors are sentinel values from `@superbuilders/errors`.
 
-```ts
-interface ImageStimulus {
-	kind: "image"
-	alt: ContentInline[]
-	src: string
-}
+Common sentinels:
 
-type RendererStimulus = ImageStimulus
-```
-
-`RendererStimulus` is currently image-only, but it is still a discriminated union so renderers stay future-safe.
-
-## Interactions
-
-```ts
-type RendererInteraction<Pcis extends PciId = PciId> =
-	| StandardRendererInteraction
-	| PciInteraction<Pcis>
-```
-
-Standard interactions:
-
-| Type | Key fields |
+| Sentinel | Meaning |
 | --- | --- |
-| `choice` | `prompt`, `options`, `shuffle`, `minChoices`, `maxChoices` |
-| `text-entry` | `prompt`, `base`, `expectedLength`, `patternMask`, `placeholderText` |
-| `extended-text` single | `prompt`, `format`, `expectedLines`, `expectedLength`, `patternMask`, `placeholderText` |
-| `extended-text` multiple | single fields plus `minStrings`, `maxStrings` |
-| `order` | `prompt`, `choices`, `shuffle`, `minChoices`, `maxChoices` |
-| `match` | `prompt`, `sourceChoices`, `targetChoices`, `shuffle`, `minAssociations`, `maxAssociations` |
-| `portable-custom` | `prompt`, `pciId`, `properties` |
-
-Choice objects:
-
-```ts
-interface RendererChoice {
-	identifier: string
-	content: ContentInline[]
-}
-```
-
-Match choice objects:
-
-```ts
-interface RendererMatchChoice {
-	identifier: string
-	content: ContentInline[]
-	matchMax: number
-	matchMin: number
-}
-```
-
-## Submissions
-
-```ts
-type RendererSubmission<Pcis extends PciId = PciId> =
-	| { type: "choice"; selectedKeys: string[] }
-	| { type: "text-entry"; value: string }
-	| { type: "extended-text"; values: string[] }
-	| { type: "order"; orderedKeys: string[] }
-	| { type: "match"; pairs: MatchPair[] }
-	| PciSubmission<Pcis>
-```
-
-Schemas:
+| `ErrAuthUnavailable` | Hosted auth needs browser APIs that are unavailable. |
+| `ErrAuthConfigInvalid` | Hosted auth internal URL/config state was invalid. |
+| `ErrAuthCallbackInvalid` | Hosted auth callback was malformed or rejected. |
+| `ErrAuthStateMismatch` | Callback state did not match stored state. |
+| `ErrAuthPopupBlocked` | Browser blocked the hosted auth popup. |
+| `ErrAuthCancelled` | Hosted auth popup was closed or timed out. |
+| `ErrMalformedAccessToken` | Access token is not JWS-shaped. |
+| `ErrInvalidAccessToken` | Server rejected the access token. |
+| `ErrTokenExpired` | Server rejected an expired token. |
+| `ErrUnsupportedPci` | Server returned an undeclared PCI. |
+| `ErrInvalidSubmission` | Submission did not match the active interaction. |
+| `ErrSdkUpgradeRequired` | Server requires a newer SDK version. |
+| `ErrNetwork` | Fetch failed before an HTTP response. |
+| `ErrTimeout` | Request was aborted. |
+| `ErrJsonParse` | Server returned invalid JSON. |
 
 ```ts
-ChoiceSubmissionSchema
-TextEntrySubmissionSchema
-ExtendedTextSubmissionSchema
-OrderSubmissionSchema
-MatchSubmissionSchema
-FractionInputPciSubmissionSchema
-RendererSubmissionSchema
-```
-
-Always use `safeParse` when parsing arbitrary input:
-
-```ts
-const parsed = RendererSubmissionSchema.safeParse(payload)
-if (!parsed.success) {
-	throw parsed.error
+import * as errors from "@superbuilders/errors"
+import { ErrAuthPopupBlocked, ErrTokenExpired } from "@superbuilders/primer-tives/errors"
+
+const result = await errors.try(
+	create({
+		origin,
+		publishableKey,
+		subject: "math",
+		supportedPcis: ["urn:primer:pci:fraction-input"],
+		logger
+	})
+)
+if (result.error) {
+	if (errors.is(result.error, ErrAuthPopupBlocked)) {
+		renderStartButtonAgain()
+		return
+	}
+	if (errors.is(result.error, ErrTokenExpired)) {
+		renderSignInAgain()
+		return
+	}
+	throw result.error
 }
 ```
 
-## Semantic Validation
+## Testing
 
-`RendererSubmissionSchema` validates shape. `validateSubmissionForInteraction` validates a submission against a specific interaction.
+Use a custom fetch to test runtime behavior without a live Primer server.
 
 ```ts
-const validation = validateSubmissionForInteraction(interaction, submission)
-if (!validation.ok) {
-	throw errors.wrap(ErrInvalidSubmission, submissionValidationMessage(validation))
+const fetchMock: typeof globalThis.fetch = async function fetchPrimer() {
+	return new Response(
+		JSON.stringify({
+			outcome: "advanced",
+			frame: { body: [], stimulus: null, interaction: null }
+		}),
+		{ status: 200, headers: { "Content-Type": "application/json" } }
+	)
 }
-```
-
-Checks include:
 
-- 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 browser state objects call this before submitting. Custom renderers that bypass state methods should call it themselves.
-
-## Review Types
-
-`FeedbackState.review` is `InteractionReview | null`.
-
-```ts
-type InteractionReview<Pcis extends PciId = PciId> =
-	| ChoiceReview
-	| TextEntryReview
-	| ExtendedTextReview
-	| OrderReview
-	| MatchReview
-	| PciReview<Pcis>
+const state = await create({
+	origin: "https://primer.test",
+	publishableKey: "pk_test",
+	accessToken: "eyJ.test.token",
+	subject: "vocabulary",
+	fetch: fetchMock,
+	logger
+})
 ```
 
-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`.
+## Security Model
 
-# `/errors`
+The browser may hold:
 
-All sentinels are exported from `/errors`.
-
-```ts
-import {
-	ErrBadRequest,
-	ErrConflict,
-	ErrForbidden,
-	ErrInvalidAccessToken,
-	ErrInvalidSecretKey,
-	ErrInvalidSubmission,
-	ErrJsonParse,
-	ErrMalformedAccessToken,
-	ErrMissingRequiredPci,
-	ErrNetwork,
-	ErrNotFound,
-	ErrNotSerializable,
-	ErrRateLimited,
-	ErrSdkUpgradeRequired,
-	ErrServerError,
-	ErrServiceUnavailable,
-	ErrTimeout,
-	ErrTokenExpired,
-	ErrUnsupportedPci
-} from "@superbuilders/primer-tives/errors"
+```txt
+publishable key
+Cognito/OIDC access token
 ```
 
-## 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`. |
+The publishable key identifies the Primer frontend. It does not authenticate the learner.
 
-# `/logger`
+The access token authenticates the learner. Primer verifies it server-side before touching routing or learning state.
 
-```ts
-import type { PrimerLogger } from "@superbuilders/primer-tives/logger"
+Primer does not need:
 
-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
-}
+```txt
+learner email
+verified email
+Primer learner JWT
+frontend secret key for learner runtime
+game backend token exchange
 ```
 
-The same logger shape is used by server and browser SDKs. `@superbuilders/slog` matches it directly:
-
-```ts
-import * as logger from "@superbuilders/slog"
+## Final Invariants
 
-const primer = createPrimerServer({ origin, secretKey, logger })
-const client = create({ origin, accessToken, subject: "vocabulary", logger })
+```txt
+create is the only public lifecycle operation
+create returns Promise<PrimerState>
+accessToken present skips hosted auth
+accessToken absent uses hosted auth
+subject is optional; omitted means internal all-subject scope
+subject determines required renderer PCI capabilities
+supportedPcis declares renderer PCI capabilities
+PrimerState is the learning state machine
+only valid state variants expose learning transitions
 ```
 
-# `/grade-level`
-
-```ts
-import { GRADE_LEVELS } from "@superbuilders/primer-tives/grade-level"
-import type { GradeLevel } from "@superbuilders/primer-tives/grade-level"
-
-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.
-
-# Onboarding Grade Selection
-
-Grade selection is not a separate SDK API.
-
-If the learner's email profile has no selected grade yet, the first `/advance` response is a normal `choice` interaction:
-
-- `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
-
-The current SDK does not expose:
-
-- 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
-
-Those omissions are intentional. The public integration point is one backend method, `getToken`, and one browser state machine, `create(...).start()`.
+Keep these concepts separate. The publishable key is not learner auth. The access token is not content authorization. PCI support is not negotiated implicitly. The state object is not serializable.