@superbuilders/primer-tives 0.5.0 → 0.8.0

package/README.md

@@ -1,19 +1,6 @@
 # @superbuilders/primer-tives
 
-Client SDK for the Primer adaptive learning engine.
-
-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
@@ -21,37 +8,66 @@ 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) |
+
+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
 
-## Quick start
+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"
 
 const client = create({
-  publishableKey: "pk_live_abc123",
-  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",
-  ],
+    "urn:primer:pci:fraction-addition"
+  ]
 })
 
-let state: PrimerState = await client.start("student-uuid")
+let state: PrimerState = await client.start()
 
 while (state.phase !== "completed" && state.phase !== "fatal") {
   switch (state.phase) {
@@ -59,418 +75,280 @@ 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 publishableKey: string
-  readonly supportedPcis: readonly Pcis[]
-  readonly origin: string
-  readonly fetch?: typeof globalThis.fetch
-  readonly abort?: AbortController
-  readonly logger?: PrimerLogger
-}
+import {
+  createPrimerServer,
+  type PrimerServer,
+  type PrimerServerConfig,
+  type SessionToken,
+  type GradeLevel,
+  GRADE_LEVELS
+} from "@superbuilders/primer-tives/server"
 ```
 
-| Field | Required | Description |
-|---|---|---|
-| `publishableKey` | yes | Must start with `pk_`. Sent as `Authorization: Bearer pk_...` |
-| `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` |
-| `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()` validates the publishable key prefix immediately and throws `ErrMalformedPublishableKey` if it does not start with `pk_`.
-
-### Logger interface
+## `createPrimerServer(config)`
 
 ```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 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
 }
+
+function createPrimerServer(config: PrimerServerConfig): PrimerServer
 ```
 
-## Wire protocol
+Returns a `PrimerServer` with four methods. Each method throws a sentinel-wrapped `Error` — use `errors.try()` from `@superbuilders/errors` at the call site.
 
-Every request is a `POST` to:
+### `createNativeStudent(gradeLevel): Promise<string>`
 
-```txt
-${origin}/api/v0/advance
-```
-
-The path constant is exported as:
+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**.
 
 ```ts
-const ADVANCE_PATH = "/api/v0/advance"
+const studentId = await primer.createNativeStudent("5")
 ```
 
-### Headers
+**Do not call this for Timeback integrations.** Timeback students are provisioned automatically on first `exchangeTimebackStudentForAccessToken`.
 
-```txt
-Authorization: Bearer pk_...
-Content-Type: application/json
-```
+### `updateNativeStudentGradeLevel(studentId, gradeLevel): Promise<void>`
 
-### Request body
+Change a Primer student's grade level.
 
 ```ts
-interface WireRequestBody<Pcis extends PciId = PciId> {
-  studentId: string
-  supportedPcis: readonly PciId[]
-  intent: WireIntent<Pcis>
-}
+await primer.updateNativeStudentGradeLevel(studentId, "6")
 ```
 
-```ts
-type WireIntent<Pcis extends PciId = PciId> =
-  | { kind: "observation" }
-  | { kind: "interaction"; submission: RendererSubmission<Pcis> }
-  | { kind: "timeout" }
-```
+**Do not call this for Timeback students.** Grade-level changes flow from the SIS.
 
-### Response outcomes
+### `exchangeNativeStudentForAccessToken(studentId): Promise<SessionToken>`
 
-Conceptually, the server returns one of three outcomes:
+Mint a short-lived access token for an existing Primer-owned student. Call this **every session start**; tokens expire in 15 minutes by default.
 
 ```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" }
+const { accessToken, expiresInSeconds } = await primer.exchangeNativeStudentForAccessToken(studentId)
 ```
 
-### Important notes
+### `exchangeTimebackStudentForAccessToken(sourcedId): Promise<SessionToken>`
 
-- `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.
+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.
 
-## State machine
-
-`PrimerState` is a discriminated union on `phase`:
+```ts
+const { accessToken, expiresInSeconds } = await primer.exchangeTimebackStudentForAccessToken(sourcedId)
+```
 
-```txt
-observation -> interaction -> feedback -> observation -> ... -> completed
-     |  \          |  \          |  \
-     v   \         v   \         v   \
-  errored fatal  errored fatal  errored fatal
+## `SessionToken`
 
-errored -> retry() -> replays exact failed action
-interaction timeout -> same transport path, intent kind "timeout"
+```ts
+interface SessionToken {
+  readonly accessToken: string          // HS256 JWS — pass to client SDK as Config.accessToken
+  readonly expiresInSeconds: number     // typically 900 (15 min)
+}
 ```
 
-### `observation`
+Hand `accessToken` to your frontend over whatever channel you already use (cookie, HTML response, WebSocket, API response). The browser passes it to `create()`.
 
-Display-only frame. Render `state.stimulus`, then call `advance()`.
+## `GradeLevel`
 
 ```ts
-state.phase === "observation"
-state.stimulus  // RendererStimulus | null
-state.advance() // Promise<PrimerState>
+type GradeLevel = "K" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12"
 ```
 
-### `interaction`
-
-Student must respond. Discriminate on `state.kind`.
-
-All interaction states also expose:
+Exported as both `GradeLevel` and the `GRADE_LEVELS` readonly tuple.
 
-- `state.stimulus`
-- `state.interaction`
-- `timeout()`
+## Error sentinels (`/server`)
 
-#### Interaction kinds
+| 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:
 
-| `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` |
+```ts
+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
+```
 
-### `feedback`
+---
 
-The server has evaluated the submission. Render feedback, then call `advance()`.
+# `/client`
 
 ```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>
+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"
 ```
 
-`review` is interaction-native feedback data when available:
+## `create(config)`
 
 ```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 }
+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
+}
 ```
 
-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.
 
-- `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()`.
+### `subject` scope
 
-### `completed`
+| 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 |
 
-Session finished successfully. No further actions.
+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`.
 
-### `errored`
+## `PrimerState` — the state machine
 
-Recoverable or user-correctable failure.
+`start()` returns a `PrimerState` union. Each phase has its own shape and action methods.
 
 ```ts
-state.phase === "errored"
-state.error      // Error sentinel
-state.retriable  // boolean
-state.retry()    // Promise<PrimerState>
+type PrimerState =
+  | ObservationState                // advance()
+  | InteractionState                // submit…() / timeout()
+  | FeedbackState                   // advance()
+  | CompletedState                  // terminal
+  | ErroredState                    // retry() — retriable:boolean
+  | FatalState                      // terminal
 ```
 
-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`
+### `observation`
 
-Permanent failure. Session cannot recover.
+Server wants you to show a stimulus and the student to indicate they're done reading.
 
 ```ts
-state.phase === "fatal"
-state.error // Error sentinel
+interface ObservationState {
+  readonly phase: "observation"
+  readonly stimulus: RendererStimulus | null
+  advance(): Promise<PrimerState>
+}
 ```
 
-Fatal states can come from:
+### `interaction`
 
-- malformed request semantics on the server (`400`)
-- invalid publishable key (`401`)
-- forbidden origin (`403`)
-- missing resource (`404`)
-- unsupported PCI (`422`)
-- a successful response that still contains a `portable-custom` frame whose `pciId` is not in `supportedPcis`
+Server wants an answer. `InteractionState` is a discriminated union over `kind`:
 
-## Interaction payloads
+| `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>)` |
 
-```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>
-```
+All six shapes also expose `timeout(): Promise<PrimerState>`.
 
-Notes:
+### `feedback`
 
-- 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`
+Server has graded the submission and returned feedback content.
 
-## Client-side validation
+```ts
+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>
+}
+```
 
-The SDK performs **selective** client-side validation before sending some submissions.
+### `errored`
 
-| 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 |
+Transport or validation failure that might be recoverable.
 
-If validation fails:
+```ts
+interface ErroredState {
+  readonly phase: "errored"
+  readonly error: Error                       // sentinel-wrapped
+  readonly retriable: boolean
+  retry(): Promise<PrimerState>               // no-op on non-retriable
+}
+```
 
-- 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
+### `fatal`
 
-## Error sentinels
+Unrecoverable failure (bad request, invalid token, expired token, unsupported PCI, forbidden).
 
 ```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 FatalState {
+  readonly phase: "fatal"
+  readonly error: Error
+  readonly retriable: false
 }
 ```
 
-### 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` |
-| `ErrInvalidPublishableKey` | `401` |
-| `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` |
+### `completed`
 
-### Thrown directly
+Terminal. Session is done.
 
-| Sentinel | Meaning |
-|---|---|
-| `ErrMalformedPublishableKey` | `create()` received a key that does not start with `pk_` |
-| `ErrNotSerializable` | code attempted to serialize a live `PrimerState` |
+```ts
+interface CompletedState {
+  readonly phase: "completed"
+}
+```
 
 ## Content format
 
@@ -486,172 +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.
-
-### Registry
+type PciUrn = "urn:primer:pci:division-remainder" | "urn:primer:pci:fraction-addition"
 
-```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
-
-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
+Declare the PCI URNs your renderer can handle via `Config.supportedPcis`. Frames requiring an unsupported PCI resolve to `fatal` with `ErrUnsupportedPci`.
 
-Everything is exported from the package root:
+### Renderer props
 
 ```ts
-import {
-  ADVANCE_PATH,
-  ErrConflict,
-  ErrInvalidSubmission,
-  ErrMalformedPublishableKey,
-  ErrNetwork,
-  ErrTimeout,
-  ErrUnsupportedPci,
-  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,
-} 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`.