PIE-619: add accessibility catalog model contract

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chillenious

docs/API_REFERENCE.md

@@ -44,14 +44,33 @@ interface PieEnvironment {
 Base interface that all element models extend.
 
 ```typescript
+interface AccessibilityCatalogCard {
+  catalog: string;                  // e.g., "spoken"
+  language?: string;                // BCP 47 language tag, e.g., "en-US"
+  content: string;                  // Authored alternative content, often SSML
+}
+
+interface AccessibilityCatalog {
+  identifier: string;               // Stable ID referenced by visible content
+  cards: AccessibilityCatalogCard[];
+}
+
 interface PieModel {
   id: string;                     // Unique identifier
   element: string;                // Element type (e.g., "@pie-element/multiple-choice")
+  accessibilityCatalogs?: AccessibilityCatalog[];
 }
 ```
 
 Element-specific models extend this with additional properties.
 
+`accessibilityCatalogs` is an optional, QTI-aligned contract for authored
+accessibility alternatives. PIE players/toolkits can use spoken catalog entries
+to replace visible model content during text-to-speech playback, for example
+when visible math or abbreviated text needs a clearer spoken representation.
+Individual elements are not expected to render this field directly, and default
+models should omit it unless authored content provides catalog entries.
+
 ### PieSession
 
 Represents student response data.

packages/core/src/types.ts

@@ -2,10 +2,24 @@
  * Core PIE specification types
  */
 
+// QTI-aligned accessibility catalog entry for spoken alternatives.
+// Players/toolkits may use this to map visible model content to authored TTS.
+export interface AccessibilityCatalogCard {
+  catalog: string;
+  language?: string;
+  content: string;
+}
+
+export interface AccessibilityCatalog {
+  identifier: string;
+  cards: AccessibilityCatalogCard[];
+}
+
 // Base PIE model (all elements extend this)
 export interface PieModel {
   id: string;
   element: string; // e.g., "@pie-element/multiple-choice"
+  accessibilityCatalogs?: AccessibilityCatalog[];
 }
 
 // Environment configuration

packages/shared/types/src/types.ts

@@ -2,10 +2,24 @@
  * Core PIE specification types
  */
 
+// QTI-aligned accessibility catalog entry for spoken alternatives.
+// Players/toolkits may use this to map visible model content to authored TTS.
+export interface AccessibilityCatalogCard {
+  catalog: string;
+  language?: string;
+  content: string;
+}
+
+export interface AccessibilityCatalog {
+  identifier: string;
+  cards: AccessibilityCatalogCard[];
+}
+
 // Base PIE model (all elements extend this)
 export interface PieModel {
   id: string;
   element: string; // e.g., "@pie-element/multiple-choice"
+  accessibilityCatalogs?: AccessibilityCatalog[];
 }
 
 // Theme configuration (from DaisyUI or custom)