@pie-players/pie-players-shared 0.3.72 → 0.3.74

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,6 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     configuration?: any;
     highlights?: Record<string, string[]>;
 }
-export interface AssignmentSessionData {
-    assignment: AssignmentEntity;
-    sessions: FlatSession[];
-    items: ItemEntity[];
-    error?: string;
-}
 /**
  * Metadata specifically for interpretation by clients, typically containing
  * options that are relevant for the user interface. This is not indexed for search.
@@ -185,15 +106,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;
@@ -703,32 +615,6 @@ export interface ItemSettings {
     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;
-}
 export type PlayerMode = "gather" | "view" | "evaluate" | "author";
 export type PlayerRole = "student" | "instructor";
 export interface Env {
@@ -736,6 +622,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 +651,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 +769,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;

package/dist/ui/attribute-coercion.js

@@ -17,3 +17,36 @@ export function coerceBooleanLike(value, defaultValue = false) {
     }
     return Boolean(normalizedValue);
 }
+/**
+ * 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 function coerceBooleanAttribute(value) {
+    return value !== null && coerceBooleanLike(value, true);
+}
+const isBooleanProp = (element, attribute) => {
+    const definitions = element.$$p_d;
+    if (!definitions)
+        return false;
+    return Object.entries(definitions).some(([prop, definition]) => definition.type === "Boolean" &&
+        (definition.attribute ?? prop.toLowerCase()) === attribute);
+};
+/**
+ * `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 function coerceBooleanAttributes(ElementClass) {
+    const baseCallback = ElementClass.prototype.attributeChangedCallback;
+    return class extends ElementClass {
+        attributeChangedCallback(name, oldValue, newValue) {
+            const value = newValue !== null &&
+                isBooleanProp(this, name) &&
+                !coerceBooleanAttribute(newValue)
+                ? null
+                : newValue;
+            baseCallback?.call(this, name, oldValue, value);
+        }
+    };
+}

package/dist/ui/content-styles.d.ts

@@ -19,7 +19,7 @@
  * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages
  * import it with Vite's `?raw` and hand the text over.
  */
-export type ContentStylesResult = "installed" | "already-installed" | "opted-out" | "no-document";
+export type ContentStylesResult = "installed" | "already-installed" | "host-supplied" | "opted-out" | "no-document";
 /**
  * True when the host declared `<html data-pie-content-styles="host">`, i.e. it
  * takes ownership of loading the stylesheet.
@@ -42,7 +42,16 @@ export declare function contentStylesOptedOut(): boolean;
  */
 export declare function contentStylesPresent(): boolean;
 /**
- * Installs `cssText` as a document-level stylesheet, once per document.
+ * Installs `cssText` as a document-level stylesheet, once per document, unless
+ * the host already supplies one.
+ *
+ * A host copy is recognised by the sentinel wherever it sits, including one
+ * confined to the host's player subtree with `@scope`. Such a host scoped its
+ * copy because the stylesheet's bare element selectors would otherwise reach
+ * its own UI, so a global copy from the player would reintroduce exactly that.
+ * A host copy can also land after this runs — a lazily injected `<style>`, a
+ * `<link>` still loading — so the installed copy keeps watching and removes
+ * itself when one appears, as it does when the host sets the opt-out late.
  *
  * The stylesheet is **prepended** to `<head>` and deliberately left out of a
  * cascade layer. Prepending reproduces the placement hosts were told to use by
@@ -60,22 +69,15 @@ export declare function contentStylesPresent(): boolean;
  */
 export declare function installContentStyles(cssText: string, source: string): ContentStylesResult;
 /**
- * Reports, once per page, the two ways content styling can go wrong. Neither is
- * detectable synchronously — a host copy may still be in flight as an async
- * `<link>` — so the check is deferred.
- *
- * - **Missing**: the host opted out and then loaded nothing, so authored content
- *   renders unstyled. This is the failure the old host-import contract produced
- *   silently.
- * - **Duplicated**: the host still imports `components.css` itself *and* the
- *   player installed a copy. Rendering is correct while the two agree, but the
- *   host's copy loads later and therefore wins ties at equal specificity — so a
- *   host copy pinned to an older `@pie-players/pie-theme` silently overrides the
- *   player's newer rules. Harmless today, a confusing override tomorrow.
+ * Reports, once per page, a host that opted out and then loaded no content
+ * stylesheet, so authored content renders unstyled — the failure the old
+ * host-import contract produced silently. Not detectable synchronously — a host
+ * copy may still be in flight as an async `<link>` — so the check is deferred.
  */
 export declare function auditContentStyles(source: string): void;
 /**
- * Test-only: clears the once-per-page warning latch and cancels any pending
- * deferred check, so a timer scheduled by one test cannot warn during the next.
+ * Test-only: clears the once-per-page warning latch, cancels any pending
+ * deferred check and stops watching for a host copy, so state from one test
+ * cannot act during the next.
  */
 export declare function resetContentStylesWarningForTesting(): void;