@pie-players/pie-players-shared 0.3.73 → 0.3.75

package/dist/types/index.d.ts

@@ -16,79 +16,6 @@ export interface BaseEntity {
     createdAt?: Date;
     updatedAt?: Date;
 }
-export interface CollectionEntity extends BaseEntity {
-    name: string;
-    organization: string | OrganizationEntity;
-}
-export interface OrganizationEntity extends BaseEntity {
-    name: string;
-    defaultCollection?: string | CollectionEntity;
-}
-export interface UserEntity extends BaseEntity {
-    email: string;
-    name?: string;
-}
-export interface ClientEntity extends BaseEntity {
-    name: string;
-    secret: string;
-    user: string | UserEntity;
-    organization: string | OrganizationEntity;
-}
-export interface AssignmentEntity extends BaseEntity {
-    organization: string | OrganizationEntity;
-}
-export interface SessionEntity extends BaseEntity {
-    item: ItemEntity;
-    assignment?: string | AssignmentEntity;
-    organization?: string | OrganizationEntity;
-}
-export declare enum SessionEventType {
-    SAVE = "save",
-    MODEL = "model",
-    SCORE = "score",
-    MANUAL_SCORE = "manual-score"
-}
-export declare enum ScoreType {
-    AUTO = "auto",
-    MANUAL = "manual"
-}
-export interface SessionScore {
-    points?: number;
-    max?: number;
-    type?: ScoreType;
-    partialScoring?: boolean;
-    message?: string;
-    errors?: string[];
-}
-export interface SessionAutoScore extends SessionScore {
-    elements?: any[];
-    extraProps?: any;
-}
-export interface SessionManualScore extends SessionScore {
-}
-export interface SessionEventEntity extends BaseEntity {
-    session: string | SessionEntity;
-    type?: SessionEventType;
-    saveEventId?: string;
-    score?: number;
-}
-export declare enum ModeType {
-    GATHER = "gather",
-    VIEW = "view",
-    EVALUATE = "evaluate"
-}
-export interface FlatSession {
-    id: string;
-    assignment: AssignmentEntity;
-    item: string;
-    data: any[];
-    createdAt: Date;
-    updatedAt: Date;
-    mode: ModeType;
-    autoScore: SessionAutoScore;
-    manualScore: SessionManualScore;
-    events: SessionEventEntity[];
-}
 export interface SemVerPrerelease {
     tag: string;
     version: number;
@@ -152,8 +79,8 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     /**
      * `null` as well as absent, because importers write it. JSON has no
      * `undefined`, so an item transformed from another format carries an explicit
-     * `passage: null` for "no passage" — `isPassageEntity` has always tested for
-     * null, so the runtime expected it while the type denied it. Excluding null
+     * `passage: null` for "no passage" — the runtime has always tested for
+     * null, so it expected it while the type denied it. Excluding null
      * only meant a host feeding real importer output through a typed path had to
      * cast it away.
      */
@@ -165,12 +92,23 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     configuration?: any;
     highlights?: Record<string, string[]>;
 }
-export interface AssignmentSessionData {
-    assignment: AssignmentEntity;
-    sessions: FlatSession[];
-    items: ItemEntity[];
-    error?: string;
-}
+/**
+ * `baseId` and `version` are optional on an entity a section references. They
+ * identify a stored version, which a host building a section from an item
+ * config does not have, and no player reads either.
+ */
+type WithOptionalVersion<T extends VersionEntity> = Omit<T, "baseId" | "version"> & Partial<Pick<VersionEntity, "baseId" | "version">>;
+/**
+ * A passage as a section's item references it. `name` is optional on the same
+ * ground: the section player reads it only as a fallback for a missing `id`.
+ */
+export type ReferencedPassageEntity = Omit<WithOptionalVersion<PassageEntity>, "name"> & {
+    name?: string;
+};
+/** An item as `AssessmentItemRef.item` references it. */
+export type ReferencedItemEntity = Omit<WithOptionalVersion<ItemEntity>, "passage"> & {
+    passage?: string | ReferencedPassageEntity | null;
+};
 /**
  * Metadata specifically for interpretation by clients, typically containing
  * options that are relevant for the user interface. This is not indexed for search.
@@ -185,15 +123,6 @@ export interface SettingsMetaData {
 export interface SettingsMetaDataEntity {
     settings?: SettingsMetaData;
 }
-/**
- * A reference to an item with optionally a title, settings and metadata.
- */
-export interface QuestionEntity extends SearchMetaDataEntity, SettingsMetaDataEntity {
-    id?: string;
-    title?: string;
-    itemVId: string;
-    item?: ItemEntity;
-}
 export type RubricBlockView = "author" | "candidate" | "proctor" | "scorer" | "testConstructor" | "tutor";
 export interface RubricBlock {
     identifier?: string;
@@ -234,7 +163,7 @@ export interface AssessmentItemRef extends SearchMetaDataEntity {
      * Resolved item entity with PIE config.
      * This is populated by the client before passing to the player.
      */
-    item?: ItemEntity;
+    item?: ReferencedItemEntity;
     /** Item-level settings for tool requirements and customization */
     settings?: ItemSettings;
     /**
@@ -270,14 +199,6 @@ export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDat
      */
     assessmentItemRefs?: AssessmentItemRef[];
     rubricBlocks?: RubricBlock[];
-    /**
-     * QTI 3.0: Personal Needs Profile (PNP 3.0) for section-scoped delivery.
-     *
-     * Section players read this (falling back to `settings.personalNeedsProfile`,
-     * then to the computed default profile) to drive PNP policy when a section is
-     * delivered without an enclosing assessment.
-     */
-    personalNeedsProfile?: PersonalNeedsProfile;
     /**
      * Formative delivery policy for this section: how many Tries a learner gets
      * on each item, when feedback is revealed, and whether the behavior is on at
@@ -554,15 +475,7 @@ export interface AccessibilityCatalog {
 export interface PersonalNeedsProfile {
     supports: string[];
     prohibitedSupports?: string[];
-    activateAtInit?: string[];
 }
-/**
- * QTI 3.0: Reference to a shared stimulus (passage).
- * Maps to qti-assessment-stimulus-ref element.
- *
- * NOTE: Not currently used. We embed PassageEntity directly in RubricBlock instead.
- * Kept for potential future use if we need to support external stimulus references.
- */
 export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
     name?: string;
     title?: string;
@@ -582,117 +495,41 @@ export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
      * QTI 3.0: testParts structure (authoritative for QTI format).
      */
     testParts?: TestPart[];
-    /** QTI 3.0: Stimulus material references (Phase 3 - placeholder) */
-    stimulusRefs?: any[];
 }
 /**
- * Enhanced settings structure for assessment configuration.
- * Provides structured fields for district policies, test administration,
- * tool configurations, and theme settings while remaining extensible.
+ * Assessment settings the tool policy reads: district policy, test
+ * administration and per-tool parameters.
  */
 export interface AssessmentSettings {
     /** District/organization policies */
     districtPolicy?: {
         blockedTools?: string[];
         requiredTools?: string[];
-        policies?: Record<string, any>;
     };
     /** Test administration configuration */
     testAdministration?: {
-        mode?: "practice" | "test" | "benchmark";
+        /**
+         * Per-session override by tool id. `false` withdraws the tool and
+         * outranks every policy level except a district block. `true` grants it
+         * below a district block, an item's `restrictedTools` and the profile's
+         * `prohibitedSupports`, and above requirements and profile supports.
+         */
         toolOverrides?: Record<string, boolean>;
-        startDate?: string;
-        endDate?: string;
     };
-    /** Tool-specific provider configurations */
+    /**
+     * Parameters by tool id, handed to a tool a grant or requirement admits;
+     * an item's `toolParameters` entry wins. Provider configuration belongs in
+     * the toolkit's `tools.providers`.
+     */
     toolConfigs?: {
         calculator?: AssessmentCalculatorConfig;
-        /**
-         * Text-to-speech configuration.
-         *
-         * Standard parameters (voice, rate, pitch) are portable across providers
-         * and follow W3C Web Speech API specifications.
-         *
-         * Provider-specific extensions should be placed in providerOptions.
-         *
-         * @see https://w3c.github.io/speech-api/
-         */
-        textToSpeech?: {
-            /**
-             * TTS provider
-             *
-             * @standard "browser" uses W3C Web Speech API
-             * @extension "polly" and "custom" are provider-specific
-             */
-            provider?: "browser" | "polly" | "custom";
-            /**
-             * Voice identifier (provider-specific names)
-             *
-             * @standard W3C Web Speech API (concept)
-             * @example "Joanna" (Polly), "en-US-Standard-A" (Google), browser voices
-             */
-            voice?: string;
-            /**
-             * Speech rate (speed multiplier)
-             *
-             * @standard W3C Web Speech API
-             * @range 0.25 to 4.0
-             * @default 1.0
-             */
-            rate?: number;
-            /**
-             * Pitch adjustment
-             *
-             * @standard W3C Web Speech API
-             * @range 0 to 2 (as multiplier)
-             * @default 1.0
-             */
-            pitch?: number;
-            /**
-             * Speech Rule Engine options for generated MathML speech.
-             *
-             * `style` is passed to SRE directly; ClearSpeak combines multiple
-             * preferences with ":" (for example,
-             * "ImpliedTimes_MoreImpliedTimes:Paren_Silent").
-             *
-             * Mirrors assessment-toolkit's SREMathSpeechOptions without importing
-             * toolkit service types into the shared content contract package.
-             */
-            mathSpeech?: {
-                domain?: string;
-                style?: string;
-                engineOptions?: Record<string, unknown>;
-            };
-            /**
-             * Provider-specific options (extensions)
-             *
-             * @extension Not portable across providers
-             * @example For AWS Polly: { engine: "neural", region: "us-east-1" }
-             * @example For Google Cloud: { audioEncoding: "MP3", effectsProfileId: ["headphone-class-device"] }
-             */
-            providerOptions?: Record<string, any>;
-        };
-        [toolId: string]: any;
+        [toolId: string]: Record<string, unknown> | undefined;
     };
-    /** Theme configuration (not in PNP) */
-    themeConfig?: {
-        scheme?: "default" | "high-contrast" | "dark";
-        fontSize?: number;
-        fontFamily?: string;
-        lineHeight?: number;
-        reducedMotion?: boolean;
-    };
-    /** Product-specific extensions */
-    [key: string]: any;
 }
-/**
- * Calculator options exposed through assessment settings.
- * The engine is implicit (Desmos).
- */
-export interface AssessmentCalculatorConfig {
+/** Calculator parameters in assessment settings. */
+export type AssessmentCalculatorConfig = {
     type?: "basic" | "scientific" | "graphing";
-    [key: string]: any;
-}
+};
 /**
  * Item-level settings for tool requirements.
  * Used in AssessmentItemRef.settings to specify item-specific tool needs.
@@ -700,34 +537,8 @@ export interface AssessmentCalculatorConfig {
 export interface ItemSettings {
     requiredTools?: string[];
     restrictedTools?: string[];
-    toolParameters?: Record<string, any>;
-    [key: string]: any;
-}
-export interface SanctionedVersionEntity extends BaseEntity {
-    organization?: string | OrganizationEntity;
-    match: string;
-    pie: string;
-    version: string;
-}
-export declare enum SanctionedVersionChangeStatus {
-    PENDING = "pending",
-    IN_PROGRESS = "in_progress",
-    COMPLETED = "completed",
-    FAILED = "failed"
-}
-export interface SanctionedVersionChangeRequest {
-    pie: string;
-    match: string;
-    version: string;
-}
-export interface SanctionedVersionChangeEntity extends BaseEntity {
-    organization?: string | OrganizationEntity;
-    createdBy: string | UserEntity;
-    status: SanctionedVersionChangeStatus;
-    requestedChanges: SanctionedVersionChangeRequest[];
-    beforeState: SanctionedVersionEntity[];
-    summary?: string;
-    jobId: string;
+    /** Parameters by tool id; outranks the assessment's `toolConfigs` entry. */
+    toolParameters?: Record<string, Record<string, unknown>>;
 }
 export type PlayerMode = "gather" | "view" | "evaluate" | "author";
 export type PlayerRole = "student" | "instructor";
@@ -736,6 +547,27 @@ export interface Env {
     role: PlayerRole;
     partialScoring?: boolean;
 }
+/** The `detail` of the `player-error` event `pie-item-player` dispatches. */
+export interface PieItemPlayerErrorDetail {
+    /** The failure, e.g. `ITEM_PLAYER_LOAD_ERROR` or `PIE_CONTROLLER_RUNTIME_ERROR`. */
+    code: string;
+    message: string;
+    /**
+     * True when the item stays usable: a failed update leaves it as it was, and
+     * a failed controller falls back to the authored model. False when the
+     * player has no item to show.
+     */
+    recoverable: boolean;
+    /** On a load error, the loading step that failed, and the strategy and mode it loaded under. */
+    stage?: string;
+    strategy?: string;
+    mode?: string;
+    cause?: unknown;
+    /** On a controller error, the element's tag and id, and what the controller looked like. */
+    elementName?: string;
+    elementId?: string;
+    controllerShape?: string;
+}
 export interface OutcomeResponse {
     id: string;
     element: string;
@@ -744,8 +576,14 @@ export interface OutcomeResponse {
     completed?: boolean;
     [key: string]: any;
 }
+/**
+ * Persists `properties` into the stored session `id` of element `element`. The
+ * player passes it to `model()`, as `PieUpdateSession` in
+ * `@pie-element/shared-types` declares.
+ */
+export type PieUpdateSession = (id: string, element: string, properties: Record<string, unknown>) => Promise<void>;
 export interface PieController {
-    model(model: PieModel, sessionData: any[], env?: any): Promise<PieModel>;
+    model(model: PieModel, sessionData: any[], env?: any, updateSession?: PieUpdateSession): Promise<PieModel>;
     outcome(modelOrSessionData: PieModel | any[], sessionOrEnv?: any, env?: any): Promise<OutcomeResponse>;
     score: (config: object, session: object, env: object) => Promise<object>;
     createCorrectResponseSession: (config: object, env: object) => Promise<object>;
@@ -856,202 +694,8 @@ export declare class InsertSoundEvent extends CustomEvent<SoundHandler> {
     static TYPE: string;
     constructor(handler: SoundHandler);
 }
-export declare const isPassageEntity: (passage: string | PassageEntity | null | undefined) => passage is PassageEntity;
-export declare function isPrerelease(version: any): version is SemVer;
-export declare function formatVersion(semVer: SemVer): string;
 export interface PieElement extends HTMLElement {
     model: PieModel;
     configuration: any;
     session: any[];
 }
-export type SessionChangedDetail = {
-    complete: boolean;
-    component: any;
-};
-export declare class SessionChangedEvent extends CustomEvent<SessionChangedDetail> {
-    readonly component: string;
-    readonly complete: boolean;
-    static TYPE: string;
-    constructor(component: string, complete: boolean);
-}
-interface ItemCfg extends ConfigEntity {
-}
-interface ItemWPassageCfg {
-    pie: ItemCfg;
-    passage: ConfigEntity;
-}
-export interface LoadResponse {
-    js: {
-        view: string[];
-    };
-    item: ItemCfg | ItemWPassageCfg;
-    session: {
-        id: string;
-        data: any[];
-    };
-}
-export interface Tracker {
-    track(message: string, ...args: any[]): void;
-    start(label: string): void;
-    end(label: string, metadata?: {
-        [key: string]: any;
-    }): void;
-}
-/**
- * Interface for storing tracker messages with timestamps
- */
-/**
- * Interface for storing tracker messages with timestamps
- */
-export interface TrackerMessage {
-    timestamp: Date;
-    message: string;
-    args: any[];
-    formattedMessage: string;
-}
-/**
- * Enhanced tracker that stores messages with timestamps
- */
-export interface EnhancedTracker extends Tracker {
-    /**
-     * Get all raw tracker messages ordered by timestamp (ascending)
-     */
-    getMessages(): TrackerMessage[];
-    /**
-     * Get a formatted multi-line representation of all tracker messages
-     */
-    getFormattedMessages(): string;
-}
-export interface ScoreResponse {
-    session: FlatSession;
-    score: SessionScore;
-    empty?: boolean;
-    [key: string]: any;
-}
-export interface VersionDiff {
-    version: SemVer;
-    previousVersion: SemVer | null;
-    createdAt: Date;
-    changes: {
-        added: Record<string, any>;
-        removed: Record<string, any>;
-        modified: Record<string, {
-            previous: any;
-            current: any;
-        }>;
-    };
-    changeCount: number;
-}
-export interface RoleToOrganizationsMapping {
-    id?: string;
-    role: string;
-    organizations: OrganizationEntity[] | string[];
-    createdAt?: Date;
-    updatedAt?: Date;
-}
-export declare enum StandardType {
-    ROOT = 0,
-    SUBJECT = 1,
-    LEVEL = 2,
-    STANDARD = 3
-}
-export interface HierarchyInfo {
-    root?: {
-        id: string;
-        guid: string;
-        title: string;
-    };
-    subject?: {
-        id: string;
-        guid: string;
-        title: string;
-    };
-    level?: {
-        id: string;
-        guid: string;
-        title: string;
-        grades: number[];
-    };
-}
-export interface CmsLearningStandardEntity extends BaseEntity {
-    guid: string;
-    abbr?: string;
-    type: StandardType;
-    parentId?: string;
-    parentGuid?: string;
-    path?: string;
-    depth: number;
-    ancestors: string[];
-    hierarchy?: HierarchyInfo;
-    title?: string;
-    description?: string;
-    sequence?: string;
-    orderIndex?: number;
-    subjectArea?: string;
-    subjectName?: string;
-    category?: string;
-    abType?: string;
-    abLabel?: string;
-    setName?: string;
-    publication?: string;
-    adopted?: string;
-    grades: number[];
-    gradeNames?: string[];
-    properties: Record<string, string>;
-    status?: "active" | "retired" | "deprecated";
-    lastModifiedAt?: Date;
-    replacesGuid?: string;
-    replacedByGuid?: string;
-    descriptionHtml?: string;
-    lastSyncedAt?: Date;
-}
-export interface ItemBankConfig {
-    collectionId: string;
-    subject?: string;
-    gradeLevels?: number[];
-    orderIndex: number;
-}
-export interface DOKDistribution {
-    dok1?: number;
-    dok2?: number;
-    dok3?: number;
-    dok4?: number;
-}
-export interface AssessmentGoal {
-    dokDistribution?: DOKDistribution;
-    constructedResponseCount?: number;
-    passageGoals?: string;
-    totalItemCount?: {
-        target?: number;
-        min?: number;
-        max?: number;
-    };
-}
-export interface StudioImportMetadata {
-    studioAssessmentProgramId?: string;
-    studioPublicId?: string;
-    importedAt?: Date;
-}
-export interface CmsBlueprintEntity extends BaseEntity {
-    name: string;
-    description?: string;
-    subject?: string;
-    standardSet?: string;
-    gradeLevels: number[];
-    states?: string[];
-    itemBankConfigs: ItemBankConfig[];
-    assessmentGoal?: AssessmentGoal;
-    claimFramework?: "SBAC" | "PARCC" | "STATE" | "CUSTOM";
-    claimTargets?: string[];
-    useSBACClusterTarget?: boolean;
-    clusters?: string[];
-    studioImportMetadata?: StudioImportMetadata;
-    originalPrompt?: string;
-}
-export interface CmsBlueprintItemEntity extends BaseEntity {
-    blueprintId: string;
-    standardGuid: string;
-    count: number;
-    details?: string;
-    assessmentId?: string;
-}

package/dist/types/index.js

@@ -1,28 +1,3 @@
-export var SessionEventType;
-(function (SessionEventType) {
-    SessionEventType["SAVE"] = "save";
-    SessionEventType["MODEL"] = "model";
-    SessionEventType["SCORE"] = "score";
-    SessionEventType["MANUAL_SCORE"] = "manual-score";
-})(SessionEventType || (SessionEventType = {}));
-export var ScoreType;
-(function (ScoreType) {
-    ScoreType["AUTO"] = "auto";
-    ScoreType["MANUAL"] = "manual";
-})(ScoreType || (ScoreType = {}));
-export var ModeType;
-(function (ModeType) {
-    ModeType["GATHER"] = "gather";
-    ModeType["VIEW"] = "view";
-    ModeType["EVALUATE"] = "evaluate";
-})(ModeType || (ModeType = {}));
-export var SanctionedVersionChangeStatus;
-(function (SanctionedVersionChangeStatus) {
-    SanctionedVersionChangeStatus["PENDING"] = "pending";
-    SanctionedVersionChangeStatus["IN_PROGRESS"] = "in_progress";
-    SanctionedVersionChangeStatus["COMPLETED"] = "completed";
-    SanctionedVersionChangeStatus["FAILED"] = "failed";
-})(SanctionedVersionChangeStatus || (SanctionedVersionChangeStatus = {}));
 /**
  * During the loading of elements from PIE bundles, we do a trick where we make
  * editor components available as web components by appending this to the element name.
@@ -74,46 +49,3 @@ export class InsertSoundEvent extends CustomEvent {
         this.handler = handler;
     }
 }
-export const isPassageEntity = (passage) => typeof passage === "object" && passage !== null;
-export function isPrerelease(version) {
-    return (typeof version === "object" &&
-        version !== null &&
-        typeof version.major === "number" &&
-        typeof version.minor === "number" &&
-        typeof version.patch === "number" &&
-        !!version.prerelease && // Check if prerelease exists
-        typeof version.prerelease.tag === "string" &&
-        typeof version.prerelease.version === "number");
-}
-export function formatVersion(semVer) {
-    if (!semVer)
-        return "";
-    const base = [semVer.major, semVer.minor, semVer.patch].join(".");
-    if (isPrerelease(semVer) && semVer.prerelease) {
-        const prerelease = [semVer.prerelease.tag, semVer.prerelease.version].join(".");
-        return `${base}-${prerelease}`;
-    }
-    return base;
-}
-export class SessionChangedEvent extends CustomEvent {
-    component;
-    complete;
-    static TYPE = "session-changed";
-    constructor(component, complete) {
-        super(SessionChangedEvent.TYPE, {
-            bubbles: true,
-            composed: true,
-            detail: { complete, component },
-        });
-        this.component = component;
-        this.complete = complete;
-    }
-}
-// CMS Types (copied from @pie-api-aws/datastore to avoid importing server-only package)
-export var StandardType;
-(function (StandardType) {
-    StandardType[StandardType["ROOT"] = 0] = "ROOT";
-    StandardType[StandardType["SUBJECT"] = 1] = "SUBJECT";
-    StandardType[StandardType["LEVEL"] = 2] = "LEVEL";
-    StandardType[StandardType["STANDARD"] = 3] = "STANDARD";
-})(StandardType || (StandardType = {}));

package/dist/ui/attribute-coercion.d.ts

@@ -1 +1,13 @@
 export declare function coerceBooleanLike(value: boolean | string | null | undefined, defaultValue?: boolean): boolean;
+/**
+ * Reads a boolean attribute value: present is true and absent is false, as in
+ * HTML, except that the words `coerceBooleanLike` reads as false stay false.
+ */
+export declare function coerceBooleanAttribute(value: string | null): boolean;
+/**
+ * `customElement.extend` hook for a Svelte element with `type: "Boolean"`
+ * props. Svelte reads those by presence, so `show-bottom-border="false"` sets
+ * the prop to `true`; this passes Svelte a removed attribute whenever
+ * `coerceBooleanAttribute` reads the value as false.
+ */
+export declare function coerceBooleanAttributes<Base extends CustomElementConstructor>(ElementClass: Base): Base;