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

package/dist/security/wrap-overwide.js

@@ -40,9 +40,18 @@ function isInsidePieCustomElement(node, root) {
     }
     return false;
 }
+/**
+ * Wrappers whose layout class was read from the live cascade. A wrapper built
+ * off-document saw only its node's inline style, so the first live pass to meet
+ * it reads the layout again; this set keeps that to once per wrapper.
+ */
+const liveLayoutRead = new WeakSet();
 /**
  * Wrap every unwrapped match under `root`. Returns the number newly wrapped so
  * callers can short-circuit when nothing changed. Idempotent.
+ *
+ * Under a connected `root`, a wrapper whose layout was never read live gains
+ * the layout class this pass would have given it.
  */
 export function wrapOverwideInElement(root, spec, options = {}) {
     const { skipPieDescendants = false } = options;
@@ -52,24 +61,59 @@ export function wrapOverwideInElement(root, spec, options = {}) {
     const ownerDocument = root.ownerDocument;
     if (!ownerDocument)
         return 0;
-    let wrapped = 0;
+    const readsLiveLayout = !!spec.layoutClass && !!ownerDocument.defaultView && root.isConnected;
+    const targets = [];
+    const unread = [];
     for (const node of nodes) {
         const parent = node.parentElement;
         if (!parent)
             continue;
         // Idempotency — already wrapped.
-        if (parent.classList?.contains(spec.wrapperClass))
+        const wrapped = parent.classList?.contains(spec.wrapperClass);
+        if (wrapped && (!readsLiveLayout || liveLayoutRead.has(parent)))
             continue;
         // Authored-markup pass: leave PIE custom-element internals alone.
         if (skipPieDescendants && isInsidePieCustomElement(node, root))
             continue;
         if (node.closest(EDITING_HOST_SELECTOR))
             continue;
+        if (!wrapped)
+            targets.push(node);
+        else if (!unread.some((other) => other.parentElement === parent))
+            unread.push(node);
+    }
+    // Layout is read for every node before the first insertion: a read after a
+    // wrap forces a fresh style resolution, one per node. A wrapper's own styles
+    // override its node's layout — the theme makes every wrapped image a block —
+    // so an existing wrapper is read with its classes lifted.
+    const unreadWrappers = unread.map((node) => node.parentElement);
+    const liftedClasses = unreadWrappers.map((wrapper) => wrapper.className);
+    for (const wrapper of unreadWrappers)
+        wrapper.className = "";
+    const layoutClasses = targets.map((node) => spec.layoutClass?.(node) ?? null);
+    const unreadLayoutClasses = unread.map((node) => spec.layoutClass?.(node) ?? null);
+    for (const [index, wrapper] of unreadWrappers.entries()) {
+        wrapper.className = liftedClasses[index];
+        const layoutClass = unreadLayoutClasses[index];
+        if (layoutClass)
+            wrapper.classList.add(layoutClass);
+        liveLayoutRead.add(wrapper);
+    }
+    let wrapped = 0;
+    for (const [index, node] of targets.entries()) {
+        const parent = node.parentElement;
+        if (!parent)
+            continue;
         const wrapper = ownerDocument.createElement(spec.wrapperTag);
-        wrapper.className = spec.wrapperClass;
+        const layoutClass = layoutClasses[index];
+        wrapper.className = layoutClass
+            ? `${spec.wrapperClass} ${layoutClass}`
+            : spec.wrapperClass;
         wrapper.setAttribute("tabindex", "0");
         wrapper.setAttribute("role", "region");
         wrapper.setAttribute("aria-label", spec.buildAriaLabel(node));
+        if (readsLiveLayout)
+            liveLayoutRead.add(wrapper);
         parent.insertBefore(wrapper, node);
         wrapper.appendChild(node);
         wrapped += 1;

package/dist/types/index.d.ts

@@ -92,6 +92,23 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     configuration?: any;
     highlights?: Record<string, 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.
@@ -146,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;
     /**
@@ -182,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
@@ -466,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;
@@ -494,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;
-    };
-    /** Theme configuration (not in PNP) */
-    themeConfig?: {
-        scheme?: "default" | "high-contrast" | "dark";
-        fontSize?: number;
-        fontFamily?: string;
-        lineHeight?: number;
-        reducedMotion?: boolean;
+        [toolId: string]: Record<string, unknown> | undefined;
     };
-    /** 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.
@@ -612,8 +537,8 @@ export interface AssessmentCalculatorConfig {
 export interface ItemSettings {
     requiredTools?: string[];
     restrictedTools?: string[];
-    toolParameters?: Record<string, any>;
-    [key: string]: any;
+    /** 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";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.74",
+	"version": "0.3.75",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -102,6 +102,7 @@
 		"dist"
 	],
 	"dependencies": {
+		"@pie-element/shared-utils": "0.1.3",
 		"@pie-lib/math-rendering-module": "6.0.0",
 		"dompurify": "^3.4.16",
 		"semver": "^7.8.5"
@@ -109,7 +110,7 @@
 	"scripts": {
 		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && node scripts/bundle-vendored-modules.mjs && mkdir -p dist/components && cp -R src/components/vendor dist/components/vendor",
 		"dev": "tsc -p tsconfig.json --watch",
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json",
 		"lint": "biome lint .",
 		"check": "tsc -p tsconfig.json --noEmit",
 		"test": "bun test",
@@ -119,7 +120,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
-		"@pie-element/shared-math-rendering-mathjax": "0.1.2",
+		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
 		"@playwright/test": "^1.63.0",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",

package/dist/loaders/mathjax-version-conflict.d.ts

@@ -1,17 +0,0 @@
-/**
- * Forwards the MathJax version-conflict event to instrumentation.
- *
- * The MathJax 4 adapter that browser ESM elements render with dispatches
- * `pie-mathjax-version-conflict` on `window`, once per condition per page, when
- * MathJax 3 runs on the same page — an unsupported page, see
- * docs/item-player/loading-strategies.md#one-mathjax-version-per-page. The
- * event name is repeated here because players do not depend on the element
- * packages.
- */
-import type { InstrumentationProvider } from "../instrumentation/types.js";
-export declare const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
-/**
- * Tracks each `pie-mathjax-version-conflict` event on `target` with the
- * provider `getProvider` returns when it fires, once per provider.
- */
-export declare function forwardMathjaxVersionConflicts(target: EventTarget, getProvider: () => InstrumentationProvider | undefined): void;

package/dist/loaders/mathjax-version-conflict.js

@@ -1,51 +0,0 @@
-/**
- * Forwards the MathJax version-conflict event to instrumentation.
- *
- * The MathJax 4 adapter that browser ESM elements render with dispatches
- * `pie-mathjax-version-conflict` on `window`, once per condition per page, when
- * MathJax 3 runs on the same page — an unsupported page, see
- * docs/item-player/loading-strategies.md#one-mathjax-version-per-page. The
- * event name is repeated here because players do not depend on the element
- * packages.
- */
-export const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
-// Every ESM backend on a page listens, and each player bundle carries its own
-// copy of this module, so the providers that tracked an event are kept on the
-// page.
-const TRACKED = Symbol.for("@pie-players/pie-players-shared/mathjax-version-conflict-tracked");
-function providersThatTracked(event) {
-    const registry = globalThis;
-    registry[TRACKED] ??= new WeakMap();
-    let providers = registry[TRACKED].get(event);
-    if (!providers) {
-        providers = new WeakSet();
-        registry[TRACKED].set(event, providers);
-    }
-    return providers;
-}
-/**
- * Tracks each `pie-mathjax-version-conflict` event on `target` with the
- * provider `getProvider` returns when it fires, once per provider.
- */
-export function forwardMathjaxVersionConflicts(target, getProvider) {
-    target.addEventListener(MATHJAX_VERSION_CONFLICT_EVENT, (event) => {
-        const provider = getProvider();
-        if (!provider)
-            return;
-        const tracked = providersThatTracked(event);
-        if (tracked.has(provider))
-            return;
-        tracked.add(provider);
-        const detail = event.detail;
-        const { condition, docsUrl } = (detail && typeof detail === "object" ? detail : {});
-        try {
-            provider.trackEvent(MATHJAX_VERSION_CONFLICT_EVENT, {
-                condition,
-                docsUrl,
-            });
-        }
-        catch {
-            // Swallow: instrumentation must never break rendering.
-        }
-    });
-}

package/dist/pie/stage-tracker.d.ts

@@ -1,50 +0,0 @@
-import { type Stage, type StageChangeDetail, type StageSourceCe, type StageStatus } from "./stages.js";
-/**
- * Stage tracker primitive (M6).
- *
- * One tracker per CE instance per cohort. `enter(stage, status?)` is the
- * only mutation; `reset()` rolls the cohort over (e.g. when
- * `(sectionId, attemptId)` changes).
- *
- * The tracker enforces the locked invariants from
- * `m6_ready_vocab_canonical_followup.plan.md` §3.1–§3.6:
- * - Monotonic ordering across `STAGES`. Backward transitions inside one
- *   cohort are rejected (dev) / warned-once (prod) so subscribers never
- *   see a stage regress without an intervening `reset()`.
- * - Per-CE applicability. The post-retro canonical list applies to
- *   every CE shape; the `applicableStages` indirection is kept so a
- *   future shape-specific stage can opt out without rewriting callers.
- *   Non-applicable stages auto-emit `status: "skipped"` when an
- *   applicable later stage is entered, so iteration order stays stable
- *   across CE shapes.
- * - One source for every emit. The injected `emit(detail)` function
- *   drives DOM events, engine subscribers, and coordinator subscribers
- *   from the same call site so no surface drifts.
- *
- * Failure semantics intentionally piggyback on the M3 framework-error
- * contract: `enter(stage, "failed")` records the position; the
- * framework error records the cause.
- */
-export type CreateStageTrackerOptions = {
-    sourceCe: string;
-    sourceCeShape: StageSourceCe;
-    runtimeId: string;
-    sectionId?: string;
-    attemptId?: string;
-    emit: (detail: StageChangeDetail) => void;
-    now?: () => string;
-    onUnexpectedTransition?: (info: {
-        from: Stage | null;
-        to: Stage;
-        reason: "backward" | "duplicate";
-    }) => void;
-};
-export type StageTracker = {
-    enter: (stage: Stage, status?: StageStatus) => void;
-    reset: (next?: {
-        sectionId?: string;
-        attemptId?: string;
-    }) => void;
-    getCurrent: () => Stage | null;
-};
-export declare function createStageTracker(opts: CreateStageTrackerOptions): StageTracker;

package/dist/pie/stage-tracker.js

@@ -1,105 +0,0 @@
-import { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
-let unexpectedTransitionWarned = false;
-function defaultUnexpectedTransitionLogger(info) {
-    if (unexpectedTransitionWarned)
-        return;
-    unexpectedTransitionWarned = true;
-    if (typeof console !== "undefined" && console.warn) {
-        console.warn(`[pie-stage-tracker] Unexpected ${info.reason} stage transition ` +
-            `from \`${info.from ?? "<none>"}\` to \`${info.to}\`. ` +
-            `Stage transitions are expected to be monotonic within a cohort; ` +
-            `call \`reset()\` when \`(sectionId, attemptId)\` changes.`);
-    }
-}
-export function createStageTracker(opts) {
-    const applicable = applicableStages(opts.sourceCeShape);
-    const applicableSet = new Set(applicable);
-    const now = opts.now ?? (() => new Date().toISOString());
-    const onUnexpected = opts.onUnexpectedTransition ?? defaultUnexpectedTransitionLogger;
-    let current = null;
-    let sectionId = opts.sectionId;
-    let attemptId = opts.attemptId;
-    const emitted = new Set();
-    function emitDetail(stage, status) {
-        opts.emit({
-            stage,
-            status,
-            runtimeId: opts.runtimeId,
-            sectionId,
-            attemptId,
-            timestamp: now(),
-            sourceCe: opts.sourceCe,
-        });
-    }
-    function fillSkippedBefore(stage) {
-        const targetIdx = stageOrdinal(stage);
-        const startIdx = current === null ? 0 : stageOrdinal(current) + 1;
-        for (let idx = startIdx; idx < targetIdx; idx += 1) {
-            const skipCandidate = STAGES[idx];
-            if (applicableSet.has(skipCandidate))
-                continue;
-            if (emitted.has(skipCandidate))
-                continue;
-            emitted.add(skipCandidate);
-            emitDetail(skipCandidate, "skipped");
-        }
-    }
-    function enter(stage, status = "entered") {
-        const nextOrdinal = stageOrdinal(stage);
-        const currentOrdinal = current === null ? -1 : stageOrdinal(current);
-        if (status === "entered") {
-            if (emitted.has(stage)) {
-                onUnexpected({ from: current, to: stage, reason: "duplicate" });
-                return;
-            }
-            if (nextOrdinal < currentOrdinal) {
-                onUnexpected({ from: current, to: stage, reason: "backward" });
-                return;
-            }
-            if (!applicableSet.has(stage)) {
-                // A non-applicable stage entered with `entered` is a programming
-                // error: the tracker auto-skips it when a later stage enters.
-                // Treat it as a `skipped` emission and continue.
-                if (emitted.has(stage))
-                    return;
-                emitted.add(stage);
-                emitDetail(stage, "skipped");
-                return;
-            }
-            fillSkippedBefore(stage);
-            emitted.add(stage);
-            current = stage;
-            emitDetail(stage, "entered");
-            return;
-        }
-        // `status === "failed"` records position; do not gate on monotonic
-        // ordering — failure can happen during any transition. Mark the stage
-        // as emitted so a subsequent `entered` for the same stage warns as a
-        // duplicate; downstream recovery should call `reset()` first.
-        if (status === "failed") {
-            fillSkippedBefore(stage);
-            emitted.add(stage);
-            current = stage;
-            emitDetail(stage, "failed");
-            return;
-        }
-        // `status === "skipped"` is reserved for the auto-fill path; explicit
-        // callers shouldn't pass it. Accept it idempotently for robustness.
-        if (emitted.has(stage))
-            return;
-        emitted.add(stage);
-        emitDetail(stage, "skipped");
-    }
-    function reset(next) {
-        current = null;
-        emitted.clear();
-        if (next) {
-            sectionId = next.sectionId;
-            attemptId = next.attemptId;
-        }
-    }
-    function getCurrent() {
-        return current;
-    }
-    return { enter, reset, getCurrent };
-}