@superbuilders/primer-tives 0.3.2 → 0.5.0

package/README.md

@@ -1,8 +1,17 @@
 # @superbuilders/primer-tives
 
-Client SDK for the Primer adaptive learning engine. Drives a state machine over HTTP POST — the client renders frames, the server controls all routing and assessment.
+Client SDK for the Primer adaptive learning engine.
 
-The SDK has no concept of routines, curricula, or backend storage structure. It advances a student through whatever the server decides to serve next.
+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
 
@@ -12,19 +21,37 @@ bun add @superbuilders/primer-tives
 
 Dependency: `@superbuilders/errors` is installed automatically.
 
+## What you get
+
+- **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()`
+
 ## Quick start
 
 ```ts
-import { create, ErrRateLimited } from "@superbuilders/primer-tives"
 import * as errors from "@superbuilders/errors"
+import {
+  create,
+  ErrRateLimited,
+  type PrimerState,
+} from "@superbuilders/primer-tives"
 
 const client = create({
   publishableKey: "pk_live_abc123",
   origin: "https://sb-primer.vercel.app",
-  supportedPcis: ["urn:primer:pci:division-remainder"],
+  supportedPcis: [
+    "urn:primer:pci:division-remainder",
+    "urn:primer:pci:fraction-addition",
+  ],
 })
 
-let state = await client.start("student-uuid")
+let state: PrimerState = await client.start("student-uuid")
 
 while (state.phase !== "completed" && state.phase !== "fatal") {
   switch (state.phase) {
@@ -34,32 +61,64 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
       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(["a", "b"])
+            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":
-          state = await state.submit({ quotient: "3", remainder: "1" })
+          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
       }
       break
 
     case "feedback":
-      renderFeedback(state.isCorrect, state.feedbackContent, state.correctAnswer)
+      renderFeedback({
+        correct: state.isCorrect,
+        content: state.feedbackContent,
+        review: state.review,
+        interaction: state.interaction,
+        submission: state.submission,
+      })
       state = await state.advance()
       break
 
     case "errored":
+      if (!state.retriable) {
+        throw state.error
+      }
       if (errors.is(state.error, ErrRateLimited)) {
         await delay(1000)
       }
@@ -69,27 +128,18 @@ while (state.phase !== "completed" && state.phase !== "fatal") {
 }
 ```
 
-Both `state.phase` and `state.kind` are discriminated unions — TypeScript narrows the type in each `case` branch automatically. The outer switch on `phase` is exhaustive over the 6 states (`observation`, `interaction`, `feedback`, `completed`, `errored`, `fatal`). The inner switch on `kind` is exhaustive over the 4 interaction types (`choice`, `text-entry`, `extended-text`, `portable-custom`).
+Both `state.phase` and `state.kind` are discriminated unions, so TypeScript narrows automatically inside each branch.
 
-## Wire protocol
+## Mental model
 
-Every request is a POST to `https://${origin}/api/v0/advance`:
+Primer is **server-authored**.
 
-```
-POST /api/v0/advance
-Header: Authorization: Bearer pk_...
-Body: { studentId, supportedPcis, intent }
-```
+- 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.
 
-The `origin` field is required and must be the full Primer API base URL (e.g., `https://sb-primer.vercel.app`). All requests are made as absolute URLs so the browser sends the `Origin` header for server-side origin validation. The path constant `ADVANCE_PATH` is exported for reference.
-
-The server identifies the student, determines which content to serve based on the frontend's assigned courses, evaluates submissions, and returns the next frame. The client sends:
-
-- `studentId` — who is being advanced
-- `supportedPcis` — which custom interaction types the renderer can handle
-- `intent` — `{ kind: "observation" }`, `{ kind: "interaction", submission: ... }`, or `{ kind: "timeout" }`
-
-Course resolution is entirely server-side. The publishable key identifies the frontend, and the server looks up which courses are assigned to that frontend. The client has no knowledge of courses, subjects, or form factors.
+In other words, your code does not calculate progression locally. The server owns progression; the SDK owns transport, typing, and ergonomics.
 
 ## Configuration
 
@@ -106,208 +156,374 @@ interface Config<Pcis extends PciId = PciId> {
 
 | Field | Required | Description |
 |---|---|---|
-| `publishableKey` | yes | Must start with `pk_`. Sent as `Authorization: Bearer pk_...` header |
-| `supportedPcis` | yes | PCI URNs the renderer handles. `[]` if none |
-| `origin` | yes | Base URL for the Primer API (e.g., `https://sb-primer.vercel.app`). All requests are cross-origin to ensure the browser sends the Origin header for server-side validation |
-| `fetch` | no | Custom fetch. Defaults to `globalThis.fetch` |
-| `abort` | no | AbortController for cancelling in-flight requests |
-| `logger` | no | Structured logger (`debug`, `info`, `warn`, `error`) |
+| `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
+
+```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
+}
+```
+
+## Wire protocol
+
+Every request is a `POST` to:
+
+```txt
+${origin}/api/v0/advance
+```
+
+The path constant is exported as:
+
+```ts
+const ADVANCE_PATH = "/api/v0/advance"
+```
+
+### Headers
+
+```txt
+Authorization: Bearer pk_...
+Content-Type: application/json
+```
+
+### Request body
+
+```ts
+interface WireRequestBody<Pcis extends PciId = PciId> {
+  studentId: string
+  supportedPcis: readonly PciId[]
+  intent: WireIntent<Pcis>
+}
+```
 
-`create()` validates the key prefix immediately — throws `ErrMalformedPublishableKey` if invalid.
+```ts
+type WireIntent<Pcis extends PciId = PciId> =
+  | { kind: "observation" }
+  | { kind: "interaction"; submission: RendererSubmission<Pcis> }
+  | { kind: "timeout" }
+```
+
+### Response outcomes
+
+Conceptually, the server returns one of three outcomes:
+
+```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" }
+```
+
+### Important notes
+
+- `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.
 
 ## State machine
 
 `PrimerState` is a discriminated union on `phase`:
 
-```
-observation → interaction → feedback → observation → ... → completed
+```txt
+observation -> interaction -> feedback -> observation -> ... -> completed
      |  \          |  \          |  \
-     ↓   ↘         ↓   ↘         ↓   ↘
+     v   \         v   \         v   \
   errored fatal  errored fatal  errored fatal
 
-errored → (retry) → replays failed action
-interaction timeout → same as submit (server evaluates)
+errored -> retry() -> replays exact failed action
+interaction timeout -> same transport path, intent kind "timeout"
 ```
 
-Any action (`advance()`, `submitChoice()`, `timeout()`, etc.) can fail. Transient failures (network, timeout, 5xx) become `errored` with `retry()`. Permanent failures (401, 403, 404) become `fatal` — session is dead, no recovery.
-
-Calling an action twice (e.g., double-clicking `advance()`) returns the same promise — the SDK memoizes in-flight requests internally. No special handling needed.
-
 ### `observation`
 
-Display-only frame. Show the stimulus, call `advance()`.
+Display-only frame. Render `state.stimulus`, then call `advance()`.
 
 ```ts
+state.phase === "observation"
 state.stimulus  // RendererStimulus | null
 state.advance() // Promise<PrimerState>
 ```
 
-Stimulus is a discriminated union on `type`:
-- `BodyStimulus` — `{ type: "body", body: ContentBlock[] }` — text-only
-- `ImageStimulus` — `{ type: "image", description: ContentInline[], src: string }` — image-backed
-- `null` — no stimulus
-
 ### `interaction`
 
-Student must respond. Discriminate on `state.kind`:
+Student must respond. Discriminate on `state.kind`.
 
-| `state.kind` | Submit | Key fields |
-|---|---|---|
-| `"choice"` | `submitChoice(keys: string[])` | `options`, `maxChoices`, `minChoices` |
-| `"text-entry"` | `submitText(value: string)` | — |
-| `"extended-text"` (single) | `submitText(value: string)` | `cardinality: "single"` |
-| `"extended-text"` (multiple) | `submitTexts(values: string[])` | `cardinality: "multiple"`, `maxStrings`, `minStrings` |
-| `"portable-custom"` | `submit(value: PciValue<K>)` | `pciId`, `properties` |
+All interaction states also expose:
 
-All interaction states also have a `timeout()` method that advances the state machine as if the student ran out of time.
+- `state.stimulus`
+- `state.interaction`
+- `timeout()`
 
-All submit and timeout methods return `Promise<PrimerState>`.
+#### Interaction kinds
 
-Every interaction state carries `interaction.prompt` (`ContentInline[]`) and `interaction.type` (the discriminant matching `state.kind`).
+| `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` |
 
 ### `feedback`
 
-Server evaluated the submission. Show result, call `advance()`.
+The server has evaluated the submission. Render feedback, then call `advance()`.
 
 ```ts
+state.phase === "feedback"
 state.stimulus         // RendererStimulus | null
-state.interaction      // the original interaction
-state.submission       // the student's submission
+state.interaction      // RendererInteraction<Pcis>
+state.submission       // RendererSubmission<Pcis>
 state.isCorrect        // boolean
 state.feedbackContent  // ContentInline[]
-state.correctAnswer    // RendererCorrectAnswer | null
+state.review           // InteractionReview<Pcis> | null
 state.advance()        // Promise<PrimerState>
 ```
 
-`correctAnswer` carries the canonical correct response, or `null` when unavailable:
+`review` is interaction-native feedback data when available:
 
 ```ts
-type RendererCorrectScalarValue =
-  | { kind: "identifier"; value: string }
-  | { kind: "string"; value: string }
-  | { kind: "integer"; value: number }
-  | { kind: "float"; value: number }
-
-type RendererCorrectAnswer =
-  | { kind: "single"; value: RendererCorrectScalarValue | null }
-  | { kind: "multiple"; values: RendererCorrectScalarValue[] }
+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 }> }
   | {
-      kind: "record"
+      type: "portable-custom"
+      pciId: Pcis
       fields: Array<{
         fieldIdentifier: string
-        baseType: "identifier" | "string" | "integer" | "float"
-        value: RendererCorrectScalarValue | null
+        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 }
 ```
 
-For choice interactions, extract correct option identifiers from `kind: "identifier"` scalars. For text-entry, check `kind: "string"` or `kind: "integer"`. For PCI record responses, iterate `fields`. `null` means the server could not determine a correct response.
+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. No further actions.
+Session finished successfully. No further actions.
 
 ### `errored`
 
-Transient failure. The request might succeed on retry.
+Recoverable or user-correctable failure.
 
 ```ts
-state.error        // Error sentinel (use errors.is())
-state.failedPhase  // "observation" | "interaction" | "timeout"
-state.retry()      // Promise<PrimerState> — replays exact failed intent
+state.phase === "errored"
+state.error      // Error sentinel
+state.retriable  // boolean
+state.retry()    // Promise<PrimerState>
 ```
 
-Retryable sentinels: `ErrNetwork`, `ErrTimeout`, `ErrRateLimited`, `ErrServerError`, `ErrServiceUnavailable`, `ErrJsonParse`, `ErrConflict`.
+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. No `retry()`.
+Permanent failure. Session cannot recover.
 
 ```ts
-state.error  // Error sentinel (use errors.is())
+state.phase === "fatal"
+state.error // Error sentinel
 ```
 
-Causes:
-- Invalid publishable key (401 — `ErrInvalidPublishableKey`)
-- Origin not allowed (403 — `ErrForbidden`)
-- Resource not found (404 — `ErrNotFound`)
-- Malformed request (400 — `ErrBadRequest`)
-- Unsupported PCI (422 — `ErrUnsupportedPci`)
+Fatal states can come from:
 
-## Client-side validation
+- 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`
+
+## Interaction payloads
 
-The SDK validates submissions before sending them to the server:
+```ts
+type PciSubmission<Pcis extends PciId = PciId> = {
+  [K in Pcis]: {
+    type: "portable-custom"
+    pciId: K
+    value: PciValue<K>
+  }
+}[Pcis]
 
-**Choice:** rejects fewer than `minChoices`, more than `maxChoices`, duplicates, unknown option identifiers.
+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>
+```
+
+Notes:
 
-**Extended text (multiple):** rejects fewer than `minStrings`, more than `maxStrings`.
+- 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
 
-Failed validation returns `errored` (not `fatal`) with `ErrInvalidSubmission`. The original interaction state is still usable — call the submit method again with corrected input. The `retry()` on the errored state replays the same invalid submission and is not useful for validation errors.
+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
 
 ## Error sentinels
 
 ```ts
 import * as errors from "@superbuilders/errors"
-import { ErrNetwork, ErrRateLimited } from "@superbuilders/primer-tives"
-
-if (errors.is(state.error, ErrNetwork)) { /* handle */ }
+import {
+  ErrInvalidSubmission,
+  ErrNetwork,
+  ErrRateLimited,
+  ErrUnsupportedPci,
+} from "@superbuilders/primer-tives"
+
+if (errors.is(state.error, ErrNetwork)) {
+  // handle offline / DNS / CORS / fetch failure
+}
 ```
 
-**Retryable** — surface as `errored`, consumer can call `retry()`:
+### Surfaced as `errored`
 
-| Sentinel | Cause |
-|---|---|
-| `ErrNetwork` | Fetch failed (offline, DNS, CORS) |
-| `ErrTimeout` | Request aborted or timed out |
-| `ErrRateLimited` | 429 |
-| `ErrServerError` | 500 or unrecognized 5xx |
-| `ErrServiceUnavailable` | 502/503/504 |
-| `ErrJsonParse` | Response not valid JSON |
-| `ErrConflict` | 409 — server already processed this advance |
-| `ErrInvalidSubmission` | Client-side validation failed |
-
-**Permanent** — surface as `fatal`, session is dead:
-
-| Sentinel | Cause |
+| 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 — malformed request |
-| `ErrInvalidPublishableKey` | 401 — wrong publishable key |
-| `ErrForbidden` | 403 — origin not allowed |
-| `ErrNotFound` | 404 — resource not found |
-| `ErrUnsupportedPci` | 422 — server sent a PCI the client can't handle |
+| `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` |
 
-**Thrown directly** (not wrapped in errored/fatal):
+### Thrown directly
 
-| Sentinel | Cause |
+| Sentinel | Meaning |
 |---|---|
-| `ErrMalformedPublishableKey` | Key doesn't start with `pk_` — thrown by `create()` |
-| `ErrNotSerializable` | Attempted to JSON.stringify PrimerState — thrown by `toJSON()` |
+| `ErrMalformedPublishableKey` | `create()` received a key that does not start with `pk_` |
+| `ErrNotSerializable` | code attempted to serialize a live `PrimerState` |
 
-## Submission payloads
+## Content format
 
 ```ts
-type RendererSubmission =
-  | { type: "choice"; selectedKeys: string[] }
-  | { type: "text-entry"; value: string }
-  | { type: "extended-text"; values: string[] }
-  | { type: "portable-custom"; pciId: PciId; value: PciValue<PciId> }
+type ContentSpan =
+  | { type: "text"; value: string }
+  | { type: "italic"; value: string }
+
+type ContentInline =
+  | ContentSpan
+  | { type: "latex"; value: string }
+
+type ContentBlock = { type: "paragraph"; children: ContentInline[] }
 ```
 
-## Content format
+### Helpers
 
 ```ts
-type ContentInline =
-  | { type: "text"; value: string }
-  | { type: "italic"; children: ContentInline[] }
+inlinesToPlainText(nodes: ContentInline[]): string
+blocksToPlainText(blocks: ContentBlock[]): string
+```
 
-type ContentBlock = { type: "paragraph"; children: ContentInline[] }
+- `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
+
+```ts
+interface BodyStimulus {
+  type: "body"
+  body: ContentBlock[]
+}
+
+interface ImageStimulus {
+  type: "image"
+  description: ContentInline[]
+  src: string
+}
+
+type RendererStimulus = BodyStimulus | ImageStimulus
 ```
 
-`inlinesToPlainText(nodes)` strips inline formatting for accessibility labels. `blocksToPlainText(blocks)` flattens blocks to plain text.
+A frame can also have `stimulus: null`.
 
 ## PCI system
 
-Portable Custom Interactions handle domain-specific input types with full type safety.
+Portable Custom Interactions let Primer serve domain-specific input types while preserving compile-time type safety.
 
 ### Registry
 
@@ -330,31 +546,112 @@ interface PciRegistry {
 ### Type helpers
 
 ```ts
+type PciUrn = `urn:primer:pci:${string}`
 type PciId = keyof PciRegistry & string
-type PciProps<K extends PciId>   // server-provided props
-type PciValue<K extends PciId>   // submission value
+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 entry to `PciRegistry` in `src/pci.ts`
-2. URN format: `urn:primer:pci:<name>`
-3. Include in `supportedPcis` when calling `create()`
-4. Build renderer with `PciRenderProps<"urn:primer:pci:your-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
+## Import guide
 
 Everything is exported from the package root:
 
 ```ts
-import { create, ADVANCE_PATH } from "@superbuilders/primer-tives"
-import { ErrNetwork, ErrTimeout, ErrUnsupportedPci } from "@superbuilders/primer-tives"
-import { inlinesToPlainText, blocksToPlainText } from "@superbuilders/primer-tives"
-import type { PrimerState, Config, Client, PrimerLogger } from "@superbuilders/primer-tives"
-import type { ContentBlock, ContentInline } from "@superbuilders/primer-tives"
-import type { PciId, PciProps, PciValue, PciRenderProps } from "@superbuilders/primer-tives"
+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"
 ```
 
-## Non-serializable state
+## 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`.
+
+Do **not**:
+
+- `JSON.stringify(state)`
+- persist a state object to storage
+- send a state object over the network
+- treat a state object as a durable snapshot
+
+Instead, keep it in memory and render it immediately.
+
+### Repeated actions are deduplicated narrowly
+
+State objects memoize only true re-entry of the same in-flight action.
 
-`PrimerState` contains closures. Every state object has a poisoned `toJSON()` that throws `ErrNotSerializable`. Do not persist, stringify, or transfer `PrimerState` — it is ephemeral in-memory state.
+- 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
+
+### `start()` is memoized per client instance
+
+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.
+
+## Build and publish
+
+The package is built as browser-targeted ESM from `src/index.ts`, emits declaration files, and publishes `dist/` plus this README.
+
+Useful package scripts:
+
+```sh
+bun run build
+bun run typecheck
+```