@superbuilders/primer-tives 0.6.0 → 0.8.0

package/README.md

@@ -1,21 +1,6 @@
 # @superbuilders/primer-tives
 
-Client SDK for the Primer adaptive learning engine.
-
-> **Breaking change**: Auth is a server-minted Primer JWT access token. `create()` takes `accessToken` (not `publishableKey`), and `client.start()` is parameterless — the student identity lives in the token's `sub` claim. Mint tokens on your backend via `POST /api/v0/auth/exchange` with your `sk_` and either a Primer-minted `student_id` (provider `native`) or a Timeback OneRoster `sourcedId` (provider `timeback`). The exchange body now uses `student_id` in place of the old `sourced_id`.
-
-This package turns the Primer HTTP protocol into a strongly typed, server-driven state machine. Your app renders the current frame, calls the method that is valid for that frame, and the server decides what comes next.
-
-The SDK does **not** know about routines, curricula, storage schemas, or routing rules. It only knows how to:
-
-- start a student session
-- submit answers or timeouts
-- normalize transport failures into sentinel errors plus `retriable` semantics
-- expose the current step as an ergonomic TypeScript union
-- expose interaction-native review data for feedback rendering
-- preserve full type safety for portable custom interactions (PCIs)
-
-## Install
+TypeScript SDK for the Primer adaptive learning engine. Wraps the raw HTTP protocol in two tiny, fully typed surfaces — one for your backend, one for the browser — so it's mechanically impossible to misuse.
 
 ```sh
 bun add @superbuilders/primer-tives
@@ -23,38 +8,63 @@ bun add @superbuilders/primer-tives
 
 Dependency: `@superbuilders/errors` is installed automatically.
 
-## What you get
+## Two entrypoints
+
+The package ships two subpaths. There is no root export — you must pick the side of the wire you're on:
 
-- **Single entry point**: `create(config)`
-- **Single wire endpoint**: `POST ${origin}/api/v0/advance`
-- **Single runtime model**: `PrimerState`
-- **Six phases/kinds to handle**:
-  - phases: `observation`, `interaction`, `feedback`, `completed`, `errored`, `fatal`
-  - interaction kinds: `choice`, `text-entry`, `extended-text`, `order`, `match`, `portable-custom`
-- **Typed PCI submissions** driven by the `PciRegistry`
-- **Live in-memory state objects** with action methods like `advance()`, `submitChoice()`, `submitOrder()`, `submitMatch()`, `submit()`, `timeout()`, and `retry()`
+| Import | Runs on | Wraps |
+|---|---|---|
+| `@superbuilders/primer-tives/server` | your backend | `POST /api/v0/auth/exchange`, `POST /api/v0/students`, `PATCH /api/v0/students/{id}` |
+| `@superbuilders/primer-tives/client` | the browser | `POST /api/v0/advance` (the lesson state machine) |
 
-## Quick start
+No route strings, no `fetch()` calls, no snake_case wire bodies on your side. Both surfaces normalize transport failures into sentinel errors from `@superbuilders/errors`.
+
+## Round trip
+
+Your backend provisions a student (once), exchanges a `sk_` for a short-lived access token (each session), and hands the token to your frontend. Your frontend passes the token to `create()` and drives the returned state machine.
 
 ```ts
+// ── your backend ─────────────────────────────────────────────────────
 import * as errors from "@superbuilders/errors"
+import { createPrimerServer } from "@superbuilders/primer-tives/server"
+
+const primer = createPrimerServer({
+  origin: "https://primer.example.com",
+  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV
+})
+
+// One-time per user: provision a Primer-owned student.
+const studentId = await primer.createNativeStudent("4")
+// persist `studentId` alongside your user record
+
+// Every session: mint a short-lived access token.
+const result = await errors.try(
+  primer.exchangeNativeStudentForAccessToken(studentId)
+)
+if (result.error) {
+  // map ErrInvalidSecretKey / ErrStudentNotFound / ErrServerError etc.
+  throw result.error
+}
+const { accessToken, expiresInSeconds } = result.data
+// ship `accessToken` to the browser
+```
+
+```ts
+// ── your frontend ────────────────────────────────────────────────────
 import {
   create,
   ErrRateLimited,
-  type PrimerState,
-} from "@superbuilders/primer-tives"
+  type PrimerState
+} from "@superbuilders/primer-tives/client"
 
-// Mint accessToken on your backend via POST /api/v0/auth/exchange
-// (sk_ + { provider, student_id }) then pass it here. Tokens are short-lived
-// (15 min default).
 const client = create({
-  accessToken: "<primer JWS minted by /auth/exchange>",
-  origin: "https://sb-primer.vercel.app",
+  accessToken,                            // from your backend
+  origin: "https://primer.example.com",
+  subject: "math",
   supportedPcis: [
     "urn:primer:pci:division-remainder",
-    "urn:primer:pci:fraction-addition",
-  ],
-  subject: "math",
+    "urn:primer:pci:fraction-addition"
+  ]
 })
 
 let state: PrimerState = await client.start()
@@ -65,569 +75,281 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
       renderStimulus(state.stimulus)
       state = await state.advance()
       break
-
     case "interaction":
-      renderStimulus(state.stimulus)
-
-      switch (state.kind) {
-        case "choice":
-          state = await state.submitChoice(["option-a"])
-          break
-
-        case "text-entry":
-          state = await state.submitText("42")
-          break
-
-        case "extended-text":
-          if (state.cardinality === "single") {
-            state = await state.submitText("answer")
-          } else {
-            state = await state.submitTexts(["first", "second"])
-          }
-          break
-
-        case "order":
-          state = await state.submitOrder(["choice-1", "choice-2", "choice-3"])
-          break
-
-        case "match":
-          state = await state.submitMatch([
-            { source: "left-1", target: "right-2" },
-            { source: "left-2", target: "right-1" },
-          ])
-          break
-
-        case "portable-custom":
-          switch (state.pciId) {
-            case "urn:primer:pci:division-remainder":
-              state = await state.submit({ quotient: "3", remainder: "1" })
-              break
-            case "urn:primer:pci:fraction-addition":
-              state = await state.submit({ numerator: "5", denominator: "6" })
-              break
-          }
-          break
-      }
+      state = await runInteraction(state)
       break
-
     case "feedback":
-      renderFeedback({
-        correct: state.isCorrect,
-        content: state.feedbackContent,
-        review: state.review,
-        interaction: state.interaction,
-        submission: state.submission,
-      })
+      renderFeedback(state.feedbackContent, state.isCorrect)
       state = await state.advance()
       break
-
     case "errored":
-      if (!state.retriable) {
+      if (state.retriable) {
+        state = await state.retry()
+      } else {
         throw state.error
       }
-      if (errors.is(state.error, ErrRateLimited)) {
-        await delay(1000)
-      }
-      state = await state.retry()
       break
   }
 }
 ```
 
-Both `state.phase` and `state.kind` are discriminated unions, so TypeScript narrows automatically inside each branch.
+---
 
-## Mental model
-
-Primer is **server-authored**.
-
-- The client sends an **intent**: advance, submit, or timeout.
-- The server evaluates that intent and returns the next frame.
-- The SDK wraps that frame in a typed state object.
-- Your UI renders the state and calls the next valid method.
-
-In other words, your code does not calculate progression locally. The server owns progression; the SDK owns transport, typing, and ergonomics.
-
-## Configuration
+# `/server`
 
 ```ts
-interface Config<Pcis extends PciId = PciId> {
-  readonly accessToken: string
-  readonly supportedPcis: readonly Pcis[]
-  readonly origin: string
-  readonly subject: Subject | "all"
-  readonly fetch?: typeof globalThis.fetch
-  readonly abort?: AbortController
-  readonly logger?: PrimerLogger
-}
-
-type Subject = "math" | "vocabulary"
+import {
+  createPrimerServer,
+  type PrimerServer,
+  type PrimerServerConfig,
+  type SessionToken,
+  type GradeLevel,
+  GRADE_LEVELS
+} from "@superbuilders/primer-tives/server"
 ```
 
-| Field | Required | Description |
-|---|---|---|
-| `accessToken` | yes | Primer JWT minted by your backend via `POST /api/v0/auth/exchange`. Sent as `Authorization: Bearer <jwt>`. Short-lived (15 min default). |
-| `supportedPcis` | yes | PCI URNs the renderer can handle. Use `[]` if none |
-| `origin` | yes | Full Primer API base URL, for example `https://sb-primer.vercel.app` |
-| `subject` | yes | Subject scope for this session. `"math"` or `"vocabulary"` restricts drill selection to courses of that subject; `"all"` disables the filter |
-| `fetch` | no | Custom fetch implementation. Defaults to `globalThis.fetch` |
-| `abort` | no | `AbortController` whose `signal` is passed to every request |
-| `logger` | no | Structured logger with `debug`, `info`, `warn`, and `error` methods |
-
-`create()` does a cheap structural check on the token (must start with `eyJ` and contain exactly two dots) and throws `ErrMalformedAccessToken` if the shape is wrong. Signature verification happens on the server.
+## `createPrimerServer(config)`
 
-### What `subject` controls
-
-`subject` is sent on every `/advance` request and narrows the set of drill courses the server can serve:
-
-- `"math"` / `"vocabulary"` — only drills whose `drill_courses.subject` matches are eligible. The bootstrap router, trigger-driven re-routes, and active-frame lookups all respect the scope.
-- `"all"` — no filter; the server treats the session as federated and may serve drills from any subject the frontend is bound to.
-
-The scope is **per-session**. To switch subjects, construct a new client with a different `subject`; you cannot mutate it on an existing client. Student placements are isolated per subject: a student with an in-progress math placement resumes it when a math-scoped client reconnects, and a vocabulary-scoped client will bootstrap a new placement in that subject without disturbing the math one. If a student submits or times out under a scope that does not match their current placement, the server reports no active frame and the client's next observation bootstraps a fresh placement in the declared subject.
-
-Curriculum routing is not affected by `subject` in this release — only drill selection is scoped.
-
-### Credentials
-
-Each integration has one credential pair:
-
-- **`client_id`** — your Primer frontend ID (a UUIDv7). Not currently required in request bodies; it's embedded in the `sk_` record server-side and surfaced as the `tenant_id` claim on minted JWTs.
-- **`client_secret`** — your `sk_` secret key. Sent as `Authorization: Bearer sk_…` on both `/api/v0/students` and `/api/v0/auth/exchange`. Stored only as a SHA-256 hash at rest — the raw value is returned exactly once at generation time.
-
-Never expose `sk_` keys to the browser. Use them only from your backend.
-
-### Minting a student (native provider)
-
-If your integration does not front a Timeback OneRoster tenant, mint a Primer-native student for each of your users and persist the returned `student_id`. Your users exist in your system; Primer just needs a stable UUID to attach session state to.
-
-```sh
-curl -X POST "$ORIGIN/api/v0/students" \
-  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"grade_level":"9"}'
-```
-
-Response:
+```ts
+interface PrimerServerConfig {
+  readonly origin: string                     // e.g. https://primer.example.com (no trailing slash)
+  readonly secretKey: string                  // your sk_… key
+  readonly fetch?: typeof globalThis.fetch    // override (defaults to globalThis.fetch)
+  readonly abort?: AbortController            // wired into every request signal
+  readonly logger?: PrimerLogger              // optional structured logger
+}
 
-```json
-{ "student_id": "019d3e6f-5f6d-7000-8000-..." }
+function createPrimerServer(config: PrimerServerConfig): PrimerServer
 ```
 
-- `grade_level` is required. Valid values: `"K"`, `"1"`, `"2"`, …, `"12"`. Primer routes lessons by grade, so it must be set at mint time.
-- The returned `student_id` is owned by the frontend the `sk_` belongs to. Another frontend's `sk_` cannot exchange for it.
-- Store the `student_id` in your own database keyed by your user. It does not change.
+Returns a `PrimerServer` with four methods. Each method throws a sentinel-wrapped `Error` — use `errors.try()` from `@superbuilders/errors` at the call site.
 
-### Minting an access token
+### `createNativeStudent(gradeLevel): Promise<string>`
 
-`POST /api/v0/auth/exchange` takes your `sk_` bearer and a body describing which student you want a token for.
+Provision a new Primer-owned student. Returns the `studentId` string — persist it in your own database keyed by your user. Call this **once per user**.
 
-**Native** (you minted the student via `POST /api/v0/students` above):
-
-```sh
-curl -X POST "$ORIGIN/api/v0/auth/exchange" \
-  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"provider":"native","student_id":"<primer-uuid-you-stored>"}'
+```ts
+const studentId = await primer.createNativeStudent("5")
 ```
 
-**Timeback** (`student_id` carries a OneRoster `sourcedId`):
+**Do not call this for Timeback integrations.** Timeback students are provisioned automatically on first `exchangeTimebackStudentForAccessToken`.
 
-```sh
-curl -X POST "$ORIGIN/api/v0/auth/exchange" \
-  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"provider":"timeback","student_id":"<oneroster-sourced-id>"}'
-```
+### `updateNativeStudentGradeLevel(studentId, gradeLevel): Promise<void>`
 
-The request body is `.strict()` — both `provider` and `student_id` are required and the field names are snake_case. A successful response is:
+Change a Primer student's grade level.
 
 ```ts
-{
-  access_token: string,   // HS256 JWS, use as Bearer for /api/v0/advance
-  token_type: "Bearer",
-  expires_in: 900,        // seconds (15 min default)
-  scope: "frame:advance",
-}
+await primer.updateNativeStudentGradeLevel(studentId, "6")
 ```
 
-Server-side flow:
-
-1. **Authenticate the `sk_`.** SHA-256 the bearer, look up `iam_frontend_secret_keys.key_hash` with `status = 'active'`. The matching `frontend_id` + `key_id` are captured for the token claims.
-2. **Resolve the student.**
-   - `provider: "native"` — join `iam_frontend_students` on `(frontend_id, student_id)`. If no row exists, return `404 student_not_found`. This stops one frontend from minting tokens against another frontend's UUIDs.
-   - `provider: "timeback"` — look up `iam_student_timeback_identities` by `sourced_id`. If a row exists, reuse the linked `iam_students.id`. Otherwise call Timeback OneRoster, map the grade, and insert `iam_students` + `iam_student_timeback_identities` rows in a single transaction. If OneRoster returns 404, return `404 student_not_found`.
-3. **Mint the JWS.** HS256 with claims `{ sub: <iam_students.id>, tenant_id: <frontend_id>, client_id: <key_id>, scope: "frame:advance", iss: "primer", aud: "primer-api", iat, exp, jti }`. Signed but not encrypted — tamper-proof, not opaque.
-
-Error responses:
-
-| Status | Body                         | Cause                                                                 |
-| ------ | ---------------------------- | --------------------------------------------------------------------- |
-| 401    | `invalid_request`            | Missing/malformed `sk_` bearer                                        |
-| 400    | `invalid_request`            | Body failed schema validation                                          |
-| 404    | `student_not_found`          | Native: no junction row. Timeback: OneRoster returned 404.            |
-| 400    | `unsupported_grade`          | Timeback: OneRoster returned a grade we don't route.                  |
-| 502    | `timeback_unavailable`       | Timeback OneRoster / Cognito failure.                                  |
+**Do not call this for Timeback students.** Grade-level changes flow from the SIS.
 
-### Local dev (seeded fixtures)
+### `exchangeNativeStudentForAccessToken(studentId): Promise<SessionToken>`
 
-The Primer repo ships a seed script that populates a self-contained dev tenant so SDK integrators can develop against a real `/api/v0/auth/exchange` without any Timeback/OneRoster credentials. The seed is idempotent: every run tears down and re-creates the `Primer Dev` frontend, re-hashes the current `env.PRIMER_SECRET_KEY`, deletes any previous dev students owned by this frontend, and mints a fresh one with a random UUIDv7.
+Mint a short-lived access token for an existing Primer-owned student. Call this **every session start**; tokens expire in 15 minutes by default.
 
-Run the seed:
-
-```sh
-bun db:seed
+```ts
+const { accessToken, expiresInSeconds } = await primer.exchangeNativeStudentForAccessToken(studentId)
 ```
 
-This invokes `src/db/scripts/seed/index.ts`, which chains:
-
-- `seedFrontend()` — inserts `iam_frontends { name: "Primer Dev" }` and `iam_frontend_secret_keys { key_hash: sha256(env.PRIMER_SECRET_KEY), key_preview, name: "dev-seed", status: "active" }`.
-- `seedTestCourse(frontendId)` — re-inserts `iam_students { id: HARDCODED_USER.studentId }` (stable dev UUID `019d0000-0000-7000-8000-000000000001`) and an `iam_frontend_students { frontend_id, student_id }` native-ownership row, then binds the frontend to the dev curriculum course.
-
-The dev environment is native-first; the seed does **not** create a `iam_student_timeback_identities` row. If you want to exercise the timeback exchange path against the sandbox, hit it with a real OneRoster `sourcedId` (the first call will provision the junction).
-
-Three fixture values a client needs:
+### `exchangeTimebackStudentForAccessToken(sourcedId): Promise<SessionToken>`
 
-| Fixture            | Value                                            | Source                                                                           |
-| ------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------- |
-| Frontend name      | `Primer Dev`                                     | `DEV_FRONTEND_NAME` in `src/db/scripts/seed/constants.ts`                        |
-| Secret key (`sk_`) | whatever `env.PRIMER_SECRET_KEY` is at seed time | hashed at rest; the raw value is unrecoverable after seeding, so keep it in `.env` |
-| Dev student id     | `019d0000-0000-7000-8000-000000000001`           | `HARDCODED_USER.studentId` in `src/lib/auth/hardcoded-user.ts`                   |
+Mint a short-lived access token by OneRoster `sourcedId`. The server contacts the Timeback API to verify identity and grade, auto-provisions the Primer student row on first use, and returns the token. Subsequent exchanges for the same `sourcedId` reuse the existing row.
 
-Mint a native access token off the seeded student:
-
-```sh
-curl -X POST "$ORIGIN/api/v0/auth/exchange" \
-  -H "Authorization: Bearer $PRIMER_SECRET_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"provider":"native","student_id":"019d0000-0000-7000-8000-000000000001"}'
-```
-
-Expected response:
-
-```json
-{
-  "access_token": "eyJ...",
-  "token_type": "Bearer",
-  "expires_in": 900,
-  "scope": "frame:advance"
-}
+```ts
+const { accessToken, expiresInSeconds } = await primer.exchangeTimebackStudentForAccessToken(sourcedId)
 ```
 
-Hand `access_token` to `create({ accessToken, origin, supportedPcis })` and you're up. The repo's root `/` page does this automatically — opening it in the browser after `bun db:seed` renders the SDK against the seeded student.
-
-**Integration contract.** The seed script is the contract. As long as it runs cleanly, nothing on the client side has to change when the Primer auth model evolves — drop the DB, re-run `bun db:seed`, and the same `sk_` keeps working. If a future schema change breaks this guarantee, it breaks the seed first; fix the seed and the contract holds.
-
-### Logger interface
+## `SessionToken`
 
 ```ts
-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
+interface SessionToken {
+  readonly accessToken: string          // HS256 JWS — pass to client SDK as Config.accessToken
+  readonly expiresInSeconds: number     // typically 900 (15 min)
 }
 ```
 
-## Wire protocol
-
-Every request is a `POST` to:
-
-```txt
-${origin}/api/v0/advance
-```
+Hand `accessToken` to your frontend over whatever channel you already use (cookie, HTML response, WebSocket, API response). The browser passes it to `create()`.
 
-The path constant is exported as:
+## `GradeLevel`
 
 ```ts
-const ADVANCE_PATH = "/api/v0/advance"
+type GradeLevel = "K" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12"
 ```
 
-### Headers
+Exported as both `GradeLevel` and the `GRADE_LEVELS` readonly tuple.
 
-```txt
-Authorization: Bearer <primer jwt>
-Content-Type: application/json
-```
+## Error sentinels (`/server`)
 
-### Request body
+| Sentinel | Raised when |
+|---|---|
+| `ErrInvalidSecretKey` | HTTP 401 — missing, malformed, or unknown `sk_` |
+| `ErrStudentNotFound` | HTTP 404 — student doesn't exist (native) or sourced ID unknown (timeback) |
+| `ErrUnsupportedGrade` | HTTP 400 — Timeback user's grade is outside K–12 |
+| `ErrTimebackUnavailable` | HTTP 502 — Timeback OneRoster endpoint failed |
+| `ErrBadRequest` | HTTP 400 (non-grade) — validation failure |
+| `ErrServerError` | HTTP 5xx |
+| `ErrJsonParse` | Success response body wasn't valid JSON |
+| `ErrNetwork` | fetch() rejected (DNS, connection, TLS) |
+| `ErrTimeout` | fetch() aborted (your `AbortController` or `TimeoutError`) |
+
+All server methods follow the same pattern:
 
 ```ts
-interface WireRequestBody<Pcis extends PciId = PciId> {
-  supportedPcis: readonly PciId[]
-  intent: WireIntent<Pcis>
-  subject: Subject | "all"
+const result = await errors.try(primer.createNativeStudent("5"))
+if (result.error) {
+  if (errors.is(result.error, ErrInvalidSecretKey)) {
+    // rotate the sk_ and retry
+  }
+  throw result.error
 }
+const studentId = result.data
 ```
 
-The student identity is **not** in the body. The server reads it from the verified JWT's `sub` claim.
+---
 
-The `subject` field is required on every request and validated server-side. A missing or invalid value is rejected with `400 invalid_request`.
+# `/client`
 
 ```ts
-type WireIntent<Pcis extends PciId = PciId> =
-  | { kind: "observation" }
-  | { kind: "interaction"; submission: RendererSubmission<Pcis> }
-  | { kind: "timeout" }
+import {
+  create,
+  type Client,
+  type Config,
+  type PrimerState,
+  type PrimerLogger,
+  type Subject,
+  type SubjectScope,
+  SUBJECTS,
+  ErrRateLimited,
+  // …sentinels + every state/interaction/content/PCI type
+} from "@superbuilders/primer-tives/client"
 ```
 
-### Response outcomes
-
-Conceptually, the server returns one of three outcomes:
+## `create(config)`
 
 ```ts
-type WireResult<Pcis extends PciId = PciId> =
-  | {
-      outcome: "advanced"
-      stimulus: RendererStimulus | null
-      interaction: RendererInteraction<Pcis> | null
-    }
-  | {
-      outcome: "submitted"
-      stimulus: RendererStimulus | null
-      interaction: RendererInteraction<Pcis>
-      submission: RendererSubmission<Pcis>
-      isCorrect: boolean
-      feedbackContent: ContentInline[]
-      review: InteractionReview<Pcis> | null
-    }
-  | { outcome: "completed" }
+function create<const Pcis extends PciId>(config: Config<Pcis>): Client<Pcis>
+
+interface Config<Pcis extends PciId = PciId> {
+  readonly accessToken: string                 // JWS from /server
+  readonly supportedPcis: readonly Pcis[]      // PCI URNs this renderer handles ([] if none)
+  readonly origin: string                      // same origin you gave /server
+  readonly subject: SubjectScope               // "math" | "vocabulary" | "science" | "all"
+  readonly fetch?: typeof globalThis.fetch
+  readonly abort?: AbortController
+  readonly logger?: PrimerLogger
+}
+
+interface Client<Pcis extends PciId = PciId> {
+  start(): Promise<PrimerState<Pcis>>          // idempotent
+}
 ```
 
-### Important notes
+`create()` does a cheap 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.
 
-- `origin` must be the **full base URL**. The SDK constructs requests as `${origin}${ADVANCE_PATH}`.
-- `supportedPcis` is sent on every request so the server knows which portable custom interactions the client can render.
-- The client also uses `supportedPcis` as an inbound safety check: if the server returns a PCI frame the client did not advertise support for, the SDK returns a fatal `ErrUnsupportedPci` state.
+### `subject` scope
 
-## State machine
+| 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 |
 
-`PrimerState` is a discriminated union on `phase`:
+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`.
 
-```txt
-observation -> interaction -> feedback -> observation -> ... -> completed
-     |  \          |  \          |  \
-     v   \         v   \         v   \
-  errored fatal  errored fatal  errored fatal
+## `PrimerState` — the state machine
 
-errored -> retry() -> replays exact failed action
-interaction timeout -> same transport path, intent kind "timeout"
+`start()` returns a `PrimerState` union. Each phase has its own shape and action methods.
+
+```ts
+type PrimerState =
+  | ObservationState                // advance()
+  | InteractionState                // submit…() / timeout()
+  | FeedbackState                   // advance()
+  | CompletedState                  // terminal
+  | ErroredState                    // retry() — retriable:boolean
+  | FatalState                      // terminal
 ```
 
 ### `observation`
 
-Display-only frame. Render `state.stimulus`, then call `advance()`.
+Server wants you to show a stimulus and the student to indicate they're done reading.
 
 ```ts
-state.phase === "observation"
-state.stimulus  // RendererStimulus | null
-state.advance() // Promise<PrimerState>
+interface ObservationState {
+  readonly phase: "observation"
+  readonly stimulus: RendererStimulus | null
+  advance(): Promise<PrimerState>
+}
 ```
 
 ### `interaction`
 
-Student must respond. Discriminate on `state.kind`.
+Server wants an answer. `InteractionState` is a discriminated union over `kind`:
 
-All interaction states also expose:
-
-- `state.stimulus`
-- `state.interaction`
-- `timeout()`
-
-#### Interaction kinds
+| `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>)` |
 
-| `state.kind` | Submit method | Key fields |
-|---|---|---|
-| `"choice"` | `submitChoice(selectedKeys: string[])` | `options`, `minChoices`, `maxChoices` |
-| `"text-entry"` | `submitText(value: string)` | `interaction.base`, `interaction.expectedLength?`, `interaction.patternMask?`, `interaction.placeholderText?` |
-| `"extended-text"` + `cardinality: "single"` | `submitText(value: string)` | `interaction.format`, `interaction.expectedLength?`, `interaction.expectedLines?`, `interaction.patternMask?`, `interaction.placeholderText?` |
-| `"extended-text"` + `cardinality: "multiple"` | `submitTexts(values: string[])` | `minStrings`, `maxStrings`, plus the same metadata as single-cardinality extended text |
-| `"order"` | `submitOrder(orderedKeys: string[])` | `choices`, `minChoices`, `maxChoices`, `interaction.shuffle` |
-| `"match"` | `submitMatch(pairs: Array<{ source: string; target: string }>)` | `sourceChoices`, `targetChoices`, `minAssociations`, `maxAssociations`, `interaction.shuffle` |
-| `"portable-custom"` | `submit(value: PciValue<K>)` | `pciId`, `properties` |
+All six shapes also expose `timeout(): Promise<PrimerState>`.
 
 ### `feedback`
 
-The server has evaluated the submission. Render feedback, then call `advance()`.
-
-```ts
-state.phase === "feedback"
-state.stimulus         // RendererStimulus | null
-state.interaction      // RendererInteraction<Pcis>
-state.submission       // RendererSubmission<Pcis>
-state.isCorrect        // boolean
-state.feedbackContent  // ContentInline[]
-state.review           // InteractionReview<Pcis> | null
-state.advance()        // Promise<PrimerState>
-```
-
-`review` is interaction-native feedback data when available:
+Server has graded the submission and returned feedback content.
 
 ```ts
-type InteractionReview<Pcis extends PciId = PciId> =
-  | { type: "choice"; correctKeys: string[] }
-  | { type: "text-entry"; correctValue: ReviewScalarValue | null }
-  | { type: "extended-text"; correctValues: ReviewScalarValue[] }
-  | { type: "order"; correctOrder: string[] }
-  | { type: "match"; correctPairs: Array<{ source: string; target: string }> }
-  | {
-      type: "portable-custom"
-      pciId: Pcis
-      fields: Array<{
-        fieldIdentifier: string
-        baseType: "identifier" | "string" | "integer" | "float" | "pair"
-        value: ReviewScalarValue | null
-      }>
-    }
-
-type ReviewScalarValue =
-  | { kind: "identifier"; value: string }
-  | { kind: "string"; value: string }
-  | { kind: "integer"; value: number }
-  | { kind: "float"; value: number }
-  | { kind: "pair"; source: string; target: string }
+interface FeedbackState {
+  readonly phase: "feedback"
+  readonly stimulus: RendererStimulus | null
+  readonly interaction: RendererInteraction
+  readonly submission: RendererSubmission
+  readonly isCorrect: boolean
+  readonly feedbackContent: ContentInline[]   // server-provided, localized feedback
+  readonly review: InteractionReview | null   // correct answers etc., if available
+  advance(): Promise<PrimerState>
+}
 ```
 
-Notes:
-
-- `null` means the server did not provide review data.
-- order review preserves ordering directly.
-- match review preserves directional `{ source, target }` pairs directly.
-- PCI review uses record fields and can carry `pair` values without flattening them into strings.
-- `feedback.advance()` uses the same observation intent as `observation.advance()`.
-
-### `completed`
-
-Session finished successfully. No further actions.
-
 ### `errored`
 
-Recoverable or user-correctable failure.
+Transport or validation failure that might be recoverable.
 
 ```ts
-state.phase === "errored"
-state.error      // Error sentinel
-state.retriable  // boolean
-state.retry()    // Promise<PrimerState>
+interface ErroredState {
+  readonly phase: "errored"
+  readonly error: Error                       // sentinel-wrapped
+  readonly retriable: boolean
+  retry(): Promise<PrimerState>               // no-op on non-retriable
+}
 ```
 
-Caller guidance:
-
-- switch on sentinel identity with `errors.is(...)`
-- check `state.retriable` before calling `retry()`
-- non-retriable errored states keep the original sentinel but do not replay the failed action
-
 ### `fatal`
 
-Permanent failure. Session cannot recover.
+Unrecoverable failure (bad request, invalid token, expired token, unsupported PCI, forbidden).
 
 ```ts
-state.phase === "fatal"
-state.error // Error sentinel
-```
-
-Fatal states can come from:
-
-- malformed request semantics on the server (`400`)
-- missing, invalid, or expired access token (`401`)
-- forbidden (`403`)
-- missing resource (`404`)
-- unsupported PCI (`422`)
-- a successful response that still contains a `portable-custom` frame whose `pciId` is not in `supportedPcis`
-
-## Interaction payloads
-
-```ts
-type PciSubmission<Pcis extends PciId = PciId> = {
-  [K in Pcis]: {
-    type: "portable-custom"
-    pciId: K
-    value: PciValue<K>
-  }
-}[Pcis]
-
-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: Array<{ source: string; target: string }> }
-  | PciSubmission<Pcis>
+interface FatalState {
+  readonly phase: "fatal"
+  readonly error: Error
+  readonly retriable: false
+}
 ```
 
-Notes:
-
-- single-cardinality extended text is still submitted as `type: "extended-text"` with a one-element `values` array
-- match submissions are directional `{ source, target }` pairs
-- portable custom submissions carry both `pciId` and a typed PCI `value`
-
-## Client-side validation
-
-The SDK performs **selective** client-side validation before sending some submissions.
-
-| Interaction kind | Validation performed |
-|---|---|
-| `choice` | min selections, max selections, duplicate keys, unknown option identifiers |
-| `text-entry` | none |
-| `extended-text` + `single` | none |
-| `extended-text` + `multiple` | `minStrings`, `maxStrings` |
-| `order` | min selections, max selections, duplicate keys, unknown choice identifiers |
-| `match` | `minAssociations`, `maxAssociations`, unknown source/target identifiers, and per-choice `matchMin` / `matchMax` caps on both sides |
-| `portable-custom` | no outbound value validation |
-
-If validation fails:
-
-- the submit call resolves to an `errored` state
-- `state.error` will match `ErrInvalidSubmission`
-- `state.retriable` will be `false`
-- the original interaction object is still usable for a corrected resubmission
-- `retry()` returns the same errored state instead of replaying the invalid payload
+### `completed`
 
-## Error sentinels
+Terminal. Session is done.
 
 ```ts
-import * as errors from "@superbuilders/errors"
-import {
-  ErrInvalidSubmission,
-  ErrNetwork,
-  ErrRateLimited,
-  ErrUnsupportedPci,
-} from "@superbuilders/primer-tives"
-
-if (errors.is(state.error, ErrNetwork)) {
-  // handle offline / DNS / CORS / fetch failure
+interface CompletedState {
+  readonly phase: "completed"
 }
 ```
 
-### Surfaced as `errored`
-
-| Sentinel | Meaning | `state.retriable` |
-|---|---|---|
-| `ErrNetwork` | fetch failed before a response was received | `true` |
-| `ErrTimeout` | request was aborted or timed out | `true` |
-| `ErrRateLimited` | `429` | `true` |
-| `ErrServiceUnavailable` | `502`, `503`, or `504` | `true` |
-| `ErrServerError` | any other unhandled HTTP error status | `true` |
-| `ErrJsonParse` | response body was not valid JSON | `true` |
-| `ErrConflict` | `409`, or a local conflicting in-flight action | `true` |
-| `ErrInvalidSubmission` | client-side validation failed | `false` |
-
-### Permanent: surfaced as `fatal`
-
-| Sentinel | Meaning |
-|---|---|
-| `ErrBadRequest` | `400` |
-| `ErrInvalidAccessToken` | `401` with an invalid signature / unknown key / malformed claims |
-| `ErrTokenExpired` | `401` with an `exp` claim in the past |
-| `ErrForbidden` | `403` |
-| `ErrNotFound` | `404` |
-| `ErrUnsupportedPci` | server rejected the request with `422`, or the server returned a PCI frame the client did not advertise in `supportedPcis` |
-
-### Thrown directly
-
-| Sentinel | Meaning |
-|---|---|
-| `ErrMalformedAccessToken` | `create()` received a token whose shape is not a JWS (must start with `eyJ` and contain two dots) |
-| `ErrNotSerializable` | code attempted to serialize a live `PrimerState` |
-
 ## Content format
 
 ```ts
@@ -642,177 +364,107 @@ type ContentInline =
 type ContentBlock = { type: "paragraph"; children: ContentInline[] }
 ```
 
-### Helpers
+All three inline variants share the uniform `{ type, value: string }` shape. `ContentSpan` covers HTML-ish rich-text formatting. `latex` is for inline math expressions (render via Temml).
+
+Helpers:
 
 ```ts
 inlinesToPlainText(nodes: ContentInline[]): string
 blocksToPlainText(blocks: ContentBlock[]): string
 ```
 
-- `inlinesToPlainText()` strips formatting and concatenates inline values
-- `blocksToPlainText()` flattens block content with newlines between paragraphs
-
-Typical use cases:
-
-- accessibility labels
-- plain-text fallbacks
-- analytics or logging output that should ignore inline formatting
-
-## Stimulus model
+## PCI system (Portable Custom Interactions)
 
 ```ts
-interface BodyStimulus {
-  type: "body"
-  body: ContentBlock[]
-}
-
-interface ImageStimulus {
-  type: "image"
-  description: ContentInline[]
-  src: string
-}
-
-type RendererStimulus = BodyStimulus | ImageStimulus
-```
-
-A frame can also have `stimulus: null`.
-
-## PCI system
-
-Portable Custom Interactions let Primer serve domain-specific input types while preserving compile-time type safety.
+type PciUrn = "urn:primer:pci:division-remainder" | "urn:primer:pci:fraction-addition"
 
-### Registry
-
-```ts
-interface PciRegistry {
+type PciRegistry = {
   "urn:primer:pci:division-remainder": {
-    props: { dividend: number; divisor: number }
-    value: { quotient: string; remainder: string }
+    props: DivisionRemainderProps
+    value: DivisionRemainderSubmission
   }
   "urn:primer:pci:fraction-addition": {
-    props: {
-      left: { numerator: number; denominator: number }
-      right: { numerator: number; denominator: number }
-    }
-    value: { numerator: string; denominator: string }
+    props: FractionAdditionProps
+    value: FractionAdditionSubmission
   }
 }
-```
 
-### Type helpers
-
-```ts
-type PciUrn = `urn:primer:pci:${string}`
-type PciId = keyof PciRegistry & string
+type PciId = keyof PciRegistry
 type PciProps<K extends PciId> = PciRegistry[K]["props"]
 type PciValue<K extends PciId> = PciRegistry[K]["value"]
 ```
 
-### PCI renderer props
-
-```ts
-type PciRenderProps<K extends PciId> =
-  | {
-      mode: "pending"
-      properties: PciProps<K>
-      onValueChange: (value: PciValue<K> | null) => void
-    }
-  | {
-      mode: "submitted"
-      properties: PciProps<K>
-      submission: PciValue<K>
-      review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
-    }
-```
-
-### Adding a PCI
+Declare the PCI URNs your renderer can handle via `Config.supportedPcis`. Frames requiring an unsupported PCI resolve to `fatal` with `ErrUnsupportedPci`.
 
-1. Add a new entry to `PciRegistry` in `src/pci.ts`
-2. Use the URN format `urn:primer:pci:<name>`
-3. Add that PCI URN to `supportedPcis` when creating the client
-4. Make sure your renderer knows how to render and collect a `PciValue` for that PCI
-
-## Import guide
-
-Everything is exported from the package root:
+### Renderer props
 
 ```ts
-import {
-  ADVANCE_PATH,
-  ErrConflict,
-  ErrInvalidAccessToken,
-  ErrInvalidSubmission,
-  ErrMalformedAccessToken,
-  ErrNetwork,
-  ErrTimeout,
-  ErrTokenExpired,
-  ErrUnsupportedPci,
-  SUBJECTS,
-  blocksToPlainText,
-  create,
-  inlinesToPlainText,
-} from "@superbuilders/primer-tives"
-
-import type {
-  ChoiceState,
-  Client,
-  Config,
-  ContentBlock,
-  ContentInline,
-  FeedbackState,
-  MatchState,
-  ObservationState,
-  OrderState,
-  PciId,
-  PciProps,
-  PciRenderProps,
-  PciValue,
-  PrimerLogger,
-  PrimerState,
-  RendererInteraction,
-  RendererStimulus,
-  RendererSubmission,
-  Subject,
-  SubjectScope,
-} from "@superbuilders/primer-tives"
-```
-
-## Behavioral notes
-
-### States are not serializable
-
-`PrimerState` is live in-memory state that contains closures. Every state object has a poisoned `toJSON()` that throws `ErrNotSerializable`.
+type PciPendingRenderProps<K extends PciId> = {
+  mode: "pending"
+  properties: PciProps<K>
+  onValueChange: (value: PciValue<K> | null) => void
+}
 
-Do **not**:
+type PciSubmittedRenderProps<K extends PciId> = {
+  mode: "submitted"
+  properties: PciProps<K>
+  submission: PciValue<K>
+  review: Extract<InteractionReview<K>, { type: "portable-custom"; pciId: K }> | null
+}
 
-- `JSON.stringify(state)`
-- persist a state object to storage
-- send a state object over the network
-- treat a state object as a durable snapshot
+type PciRenderProps<K extends PciId> = PciPendingRenderProps<K> | PciSubmittedRenderProps<K>
+```
 
-Instead, keep it in memory and render it immediately.
+## Error sentinels (`/client`)
 
-### Repeated actions are deduplicated narrowly
+### Surfaced as `errored`
 
-State objects memoize only true re-entry of the same in-flight action.
+| 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 response body wasn't valid JSON |
+| `ErrInvalidSubmission` | client-side validation rejected the submission |
+
+### Surfaced as `fatal`
+
+| Sentinel | Raised when |
+|---|---|
+| `ErrBadRequest` | HTTP 400 |
+| `ErrInvalidAccessToken` | HTTP 401 |
+| `ErrTokenExpired` | HTTP 401 with token-expired detail |
+| `ErrForbidden` | HTTP 403 |
+| `ErrNotFound` | HTTP 404 |
+| `ErrUnsupportedPci` | HTTP 422 or a frame asks for a PCI not in `supportedPcis` |
 
-- calling `advance()` twice on the same observation state returns the same promise
-- calling the same submit method twice with the same payload returns the same promise
-- calling `retry()` twice on the same errored state returns the same promise
-- submit and timeout do **not** alias to each other anymore
-- conflicting in-flight actions surface `ErrConflict` instead of silently reusing the wrong promise
+### Thrown directly by `create()`
 
-### `start()` is memoized per client instance
+| 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) |
 
-A `Client` instance memoizes the first `start()` call and returns the same promise on later calls. In practice, create a fresh client instance per independently managed session.
+## Logger interface
 
-## Build and publish
+```ts
+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
+}
+```
 
-The package is built as browser-targeted ESM from `src/index.ts`, emits declaration files, and publishes `dist/` plus this README.
+Same shape on both sides. Plug in your slog/pino/console adapter.
 
-Useful package scripts:
+## Behavioral notes
 
-```sh
-bun run build
-bun run typecheck
-```
+- **`start()` is idempotent.** Calling it twice returns the same promise.
+- **Retry semantics.** `errored.retry()` re-runs the same intent. `errored.retriable === false` for client-validation errors (e.g. `ErrInvalidSubmission`) — those must be fixed, not retried.
+- **Session resumption.** A returning student resumes wherever the server last placed them. No client-side cursor management.
+- **Live state.** `PrimerState` holds real closures (action methods, pending-promise caches). Don't serialize it; don't store it across reloads. Call `start()` again on boot.
+- **PCI type safety.** `Config.supportedPcis` is a `const` generic; only those URNs flow through `PciInteractionState`/`PciSubmission` at the type level. Mismatch at runtime is a `fatal` with `ErrUnsupportedPci`.