@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

package/dist/policy/sources/PnpPolicySource.js

@@ -19,6 +19,7 @@ export class PnpPolicySource {
         const allSupports = new Set();
         pnp?.supports?.forEach((s) => allSupports.add(s));
         pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
+        pnp?.activateAtInit?.forEach((s) => allSupports.add(s));
         districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
         districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
         for (const s of Object.keys(testAdmin?.toolOverrides ?? {})) {
@@ -42,8 +43,8 @@ export class PnpPolicySource {
      * feature: the returned result carries exactly one decision, and
      * `decisions[0].action` is the verdict.
      *
-     * Reusing `resolveSupport(...)` rather than re-walking the precedence rules
-     * is the point — a second copy of the eight levels would drift.
+     * It reuses `resolveSupport(...)` because a second copy of the eight levels
+     * would drift.
      */
     resolveFeature(featureId, args) {
         const { ctx, result } = this.prepare(args);
@@ -61,10 +62,9 @@ export class PnpPolicySource {
         const itemSettings = item?.settings;
         const result = {
             blockedToolIds: new Set(),
-            mandatedToolIds: new Set(),
+            mandates: new Map(),
             perToolFlags: new Map(),
             decisions: [],
-            unmappedSupportIds: this.unmappedIds(pnp, settings, itemSettings),
             blockedOverrides: new Map(),
             sources: {},
         };
@@ -94,7 +94,6 @@ export class PnpPolicySource {
             districtPolicy: settings?.districtPolicy,
             testAdmin: settings?.testAdministration,
             itemSettings,
-            toolConfigs: settings?.toolConfigs,
         };
         return { ctx, result };
     }
@@ -164,13 +163,21 @@ export class PnpPolicySource {
             });
             return;
         }
+        const activateAtInit = ctx.pnp?.activateAtInit?.includes(supportId) === true;
+        const mandate = ctx.itemSettings?.requiredTools?.includes(supportId)
+            ? "item-requirement"
+            : ctx.districtPolicy?.requiredTools?.includes(supportId)
+                ? "district-requirement"
+                : undefined;
         // 5. Test administration override `true`: grants the support for the
-        // session.
+        // session. A requirement naming it keeps its mandate.
         if (override === true) {
+            if (mandate)
+                out.mandates.set(supportId, mandate);
             out.perToolFlags.set(supportId, {
-                required: false,
+                required: mandate !== undefined,
                 alwaysAvailable: true,
-                settings: this.resolveToolSettings(supportId, ctx),
+                activateAtInit,
                 rule: "test-admin-override",
             });
             out.decisions.push({
@@ -185,12 +192,12 @@ export class PnpPolicySource {
             return;
         }
         // 6. Item requirement (forces enable)
-        if (ctx.itemSettings?.requiredTools?.includes(supportId)) {
-            out.mandatedToolIds.add(supportId);
+        if (mandate === "item-requirement") {
+            out.mandates.set(supportId, mandate);
             out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
-                settings: this.resolveToolSettings(supportId, ctx),
+                activateAtInit,
                 rule: "item-requirement",
             });
             out.decisions.push({
@@ -200,17 +207,17 @@ export class PnpPolicySource {
                 action: "enable",
                 sourceType: "item",
                 reason: `Item requires "${supportId}" for this question`,
-                value: ctx.itemSettings.requiredTools,
+                value: ctx.itemSettings?.requiredTools,
             });
             return;
         }
         // 7. District requirement
-        if (ctx.districtPolicy?.requiredTools?.includes(supportId)) {
-            out.mandatedToolIds.add(supportId);
+        if (mandate === "district-requirement") {
+            out.mandates.set(supportId, mandate);
             out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
-                settings: this.resolveToolSettings(supportId, ctx),
+                activateAtInit,
                 rule: "district-requirement",
             });
             out.decisions.push({
@@ -220,16 +227,35 @@ export class PnpPolicySource {
                 action: "enable",
                 sourceType: "assessment",
                 reason: `District policy requires "${supportId}" for all assessments`,
-                value: ctx.districtPolicy.requiredTools,
+                value: ctx.districtPolicy?.requiredTools,
+            });
+            return;
+        }
+        // 8. Profile supports (student needs). `activateAtInit` grants as
+        // `supports` does and names the tool to turn on at start.
+        if (activateAtInit) {
+            out.perToolFlags.set(supportId, {
+                required: false,
+                alwaysAvailable: true,
+                activateAtInit,
+                rule: "pnp-activate-at-init",
+            });
+            out.decisions.push({
+                precedence: 8,
+                rule: "pnp-activate-at-init",
+                featureId: supportId,
+                action: "enable",
+                sourceType: "student",
+                reason: `Student PNP profile turns on "${supportId}" at start`,
+                value: ctx.pnp?.activateAtInit,
             });
             return;
         }
-        // 8. Profile supports (student needs)
         if (ctx.pnp?.supports?.includes(supportId)) {
             out.perToolFlags.set(supportId, {
                 required: false,
                 alwaysAvailable: true,
-                settings: this.resolveToolSettings(supportId, ctx),
+                activateAtInit: false,
                 rule: "pnp-support",
             });
             out.decisions.push({
@@ -256,24 +282,31 @@ export class PnpPolicySource {
         });
     }
     /**
-     * The named ids no tool is registered under, with the rules naming each in
-     * precedence order. A support id is the id of the tool it grants, so an id
-     * missing from the registry matches nothing placed.
+     * Ids the assessment or any of `items` names that no tool is registered
+     * under, each with the rules whose lists name it, in precedence order. A
+     * support id is the id of the tool it grants, so an id missing from the
+     * registry matches nothing placed; the engine turns each into a
+     * `tool-policy.unknownSupportId` diagnostic. Empty when the registry is: an
+     * empty registry has nothing to check an id against, and
+     * `tool-config-validation` already reports it once.
      */
-    unmappedIds(pnp, settings, itemSettings) {
+    unknownSupportIds(assessment, items) {
         const unmapped = new Map();
         if (this.toolRegistry.getAllTools().length === 0)
             return unmapped;
+        const pnp = assessment?.personalNeedsProfile;
+        const settings = assessment?.settings;
         const named = [
             ["district-block", settings?.districtPolicy?.blockedTools],
             [
                 "test-admin-override",
                 Object.keys(settings?.testAdministration?.toolOverrides ?? {}),
             ],
-            ["item-restriction", itemSettings?.restrictedTools],
+            ["item-restriction", items.flatMap((item) => item.restrictedTools ?? [])],
             ["pnp-prohibited", pnp?.prohibitedSupports],
-            ["item-requirement", itemSettings?.requiredTools],
+            ["item-requirement", items.flatMap((item) => item.requiredTools ?? [])],
             ["district-requirement", settings?.districtPolicy?.requiredTools],
+            ["pnp-activate-at-init", pnp?.activateAtInit],
             ["pnp-support", pnp?.supports],
         ];
         for (const [rule, ids] of named) {
@@ -288,9 +321,4 @@ export class PnpPolicySource {
         }
         return unmapped;
     }
-    /** Tool parameters: the item's entry, else the assessment's. */
-    resolveToolSettings(supportId, ctx) {
-        return (ctx.itemSettings?.toolParameters?.[supportId] ??
-            ctx.toolConfigs?.[supportId]);
-    }
 }

package/dist/runtime/SectionControllerBinding.d.ts

@@ -25,7 +25,6 @@ import type { ToolkitCoordinator } from "../services/ToolkitCoordinator.js";
 import type { SectionControllerEvent, SectionControllerHandle, SectionControllerSessionState } from "../services/section-controller-types.js";
 import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
 import type { RuntimeRegistrationDetail } from "./registration-events.js";
-import { RuntimeRegistry } from "./RuntimeRegistry.js";
 /**
  * Structural view of the resolved section controller, widened with the
  * extra methods the toolkit's runtime CE calls directly. Optional so
@@ -273,7 +272,12 @@ export declare class SectionControllerBinding {
     requestMediaPauseForCompetingAudio(): boolean;
     persist(): Promise<void>;
     hydrate(): Promise<void>;
-    getRegistry(): RuntimeRegistry;
+    /**
+     * Releases the binding and disposes the controller of every section it
+     * bound, so a coordinator the host passes or an outer toolkit lends keeps
+     * none of this toolkit's sections, and a later mount of one restores it from
+     * its session. The coordinator itself stays with its owner.
+     */
     dispose(): Promise<void>;
 }
 export {};

package/dist/runtime/SectionControllerBinding.js

@@ -43,6 +43,11 @@ function readRenderableIds(model) {
     }
     return ids;
 }
+/** Whether `ids` holds the shell's runtime or canonical id. */
+function rendersShell(ids, shell) {
+    return (ids.has(shell.itemId) ||
+        (!!shell.canonicalItemId && ids.has(shell.canonicalItemId)));
+}
 export class SectionControllerBinding {
     registry = new RuntimeRegistry();
     controller = null;
@@ -213,10 +218,7 @@ export class SectionControllerBinding {
      */
     isSectionRenderable(args) {
         const ids = this.sectionRenderableIds;
-        if (!ids)
-            return true;
-        return (ids.has(args.itemId) ||
-            (!!args.canonicalItemId && ids.has(args.canonicalItemId)));
+        return !ids || rendersShell(ids, args);
     }
     getSectionKey(sectionId, attemptId) {
         return `${sectionId}\u0000${attemptId ?? ""}`;
@@ -236,10 +238,8 @@ export class SectionControllerBinding {
         for (const [key, section] of sections) {
             if (key === current || !section.renderableIds)
                 continue;
-            if (!section.renderableIds.has(args.itemId) &&
-                !(args.canonicalItemId && section.renderableIds.has(args.canonicalItemId))) {
+            if (!rendersShell(section.renderableIds, args))
                 continue;
-            }
             const owner = this.coordinator?.getSectionController({
                 sectionId: section.sectionId,
                 attemptId: section.attemptId,
@@ -427,18 +427,24 @@ export class SectionControllerBinding {
     async hydrate() {
         await this.controller?.hydrate?.();
     }
-    getRegistry() {
-        return this.registry;
-    }
+    /**
+     * Releases the binding and disposes the controller of every section it
+     * bound, so a coordinator the host passes or an outer toolkit lends keeps
+     * none of this toolkit's sections, and a later mount of one restores it from
+     * its session. The coordinator itself stays with its owner.
+     */
     async dispose() {
         this.activeInitToken += 1;
         this.unsubscribeController?.();
         this.unsubscribeController = null;
-        if (this.coordinator && this.sectionId) {
-            await this.coordinator.disposeSectionController({
-                sectionId: this.sectionId,
-                attemptId: this.attemptId,
-            });
+        const coordinator = this.coordinator;
+        if (coordinator) {
+            for (const section of this.boundSections.values()) {
+                await coordinator.disposeSectionController({
+                    sectionId: section.sectionId,
+                    attemptId: section.attemptId,
+                });
+            }
         }
         this.registry.clear();
         this.loadedRenderableKeys.clear();

package/dist/runtime/adapter/subscriber-fanout.d.ts

@@ -28,6 +28,5 @@ export interface SubscriberFanoutHandle {
     emit(outputs: readonly SectionEngineOutput[]): void;
     subscribe(listener: EngineOutputListener): () => void;
     dispose(): void;
-    getListenerCount(): number;
 }
 export declare function createSubscriberFanout(): SubscriberFanoutHandle;

package/dist/runtime/adapter/subscriber-fanout.js

@@ -51,8 +51,5 @@ export function createSubscriberFanout() {
     function dispose() {
         listeners.clear();
     }
-    function getListenerCount() {
-        return listeners.size;
-    }
-    return { emit, subscribe, dispose, getListenerCount };
+    return { emit, subscribe, dispose };
 }

package/dist/runtime/composition-emit-scheduler.d.ts

@@ -44,9 +44,9 @@ export declare const DEFAULT_FRAME_DEADLINE_MS = 100;
  * Timing primitives, injectable so tests can drive the race deterministically.
  *
  * An omitted primitive is resolved from `globalThis` at `schedule()` time
- * rather than captured at construction: the pre-fix code also checked per
- * emit, and a host can install a `requestAnimationFrame` shim after the
- * toolkit is constructed. An explicit `null` opts the primitive out.
+ * rather than captured at construction, because a host can install a
+ * `requestAnimationFrame` shim after the toolkit is constructed. An explicit
+ * `null` opts the primitive out.
  */
 export interface CompositionEmitSchedulerTiming {
     requestFrame?: ((callback: () => void) => number) | null;

package/dist/runtime/composition-emit-scheduler.js

@@ -77,7 +77,7 @@ export function createCompositionEmitScheduler(timing = {}) {
      *
      * The latch is released before the flush callback runs, so a re-entrant
      * `schedule()` from inside the flush arms a fresh cycle instead of being
-     * swallowed. The pre-fix code cleared its latch first for the same reason.
+     * swallowed.
      */
     function resolve(firedFrom) {
         if (!pending)

package/dist/runtime/content-region.d.ts

@@ -1,7 +1,3 @@
-/** Marks the part of a shell scope that holds the content tools read and annotate. */
-export declare const CONTENT_REGION_SELECTOR = "[data-region='content']";
-/** Marks the host of a shell scope (`<pie-item-scope>`, `<pie-passage-shell>`). */
-export declare const SHELL_SCOPE_HOST_SELECTOR = "[data-pie-shell-root]";
 /**
  * The content region of `scope` that tools read and annotate.
  *

package/dist/runtime/content-region.js

@@ -1,8 +1,8 @@
 import { composedClosest, flatQuerySelector, } from "../services/tts/flat-tree.js";
 /** Marks the part of a shell scope that holds the content tools read and annotate. */
-export const CONTENT_REGION_SELECTOR = "[data-region='content']";
+const CONTENT_REGION_SELECTOR = "[data-region='content']";
 /** Marks the host of a shell scope (`<pie-item-scope>`, `<pie-passage-shell>`). */
-export const SHELL_SCOPE_HOST_SELECTOR = "[data-pie-shell-root]";
+const SHELL_SCOPE_HOST_SELECTOR = "[data-pie-shell-root]";
 /**
  * The content region of `scope` that tools read and annotate.
  *

package/dist/runtime/core/SectionEngineCore.d.ts

@@ -45,7 +45,5 @@ export declare class SectionEngineCore {
      * construction time if you need every output from `idle` onward.
      */
     subscribe(listener: SectionEngineCoreListener): () => void;
-    /** Test-only: detach every listener. */
-    disposeListeners(): void;
     private fanOut;
 }

package/dist/runtime/core/SectionEngineCore.js

@@ -61,10 +61,6 @@ export class SectionEngineCore {
             this.listeners.delete(listener);
         };
     }
-    /** Test-only: detach every listener. */
-    disposeListeners() {
-        this.listeners.clear();
-    }
     fanOut(outputs) {
         const snapshot = Array.from(this.listeners);
         const frozen = Object.freeze(outputs.slice());

package/dist/runtime/core/cohort.d.ts

@@ -17,11 +17,6 @@ export interface CohortKey {
     /** Attempt identifier; empty string if the host did not provide one. */
     attemptId: string;
 }
-/**
- * Stable string form of the cohort tuple used as a key for the
- * `loadingCompleteEmittedForCohort` latch and equality checks.
- */
-export declare function cohortKey(cohort: CohortKey | null): string;
 /**
  * `true` iff the two cohorts have the same `(sectionId, attemptId)` pair.
  * Treats both inputs as identifying the cohort by value, never by

package/dist/runtime/core/cohort.js

@@ -11,15 +11,6 @@
  * layout-CE prop shape) but the engine carries it as the empty string
  * when absent so the cohort key is total.
  */
-/**
- * Stable string form of the cohort tuple used as a key for the
- * `loadingCompleteEmittedForCohort` latch and equality checks.
- */
-export function cohortKey(cohort) {
-    if (!cohort)
-        return "";
-    return `${cohort.sectionId}|${cohort.attemptId}`;
-}
 /**
  * `true` iff the two cohorts have the same `(sectionId, attemptId)` pair.
  * Treats both inputs as identifying the cohort by value, never by

package/dist/runtime/core/engine-output.d.ts

@@ -26,8 +26,9 @@ export type EngineOutputStageChange = {
 };
 /**
  * Canonical `pie-loading-complete`. One-shot per cohort, emitted when the
- * readiness signals satisfy `allLoadingComplete`, so every one of `itemCount`
- * items has loaded.
+ * readiness signals satisfy `allLoadingComplete`: section ready plus the host's
+ * loading signal, which the section player kernel raises once the element
+ * pre-warm resolves. `itemCount` is the composition's item count.
  */
 export type EngineOutputLoadingComplete = {
     kind: "loading-complete";

package/dist/runtime/core/engine-transition.js

@@ -111,8 +111,9 @@ function applyReadinessUpdate(state, args) {
         emitStageChange(outputs, phase, state.cohort);
     }
     // Canonical `loading-complete` emission. One-shot per cohort, gated
-    // on the readiness signals indicating every item has finished
-    // loading.
+    // on `allLoadingComplete`: section ready plus the host's loading signal,
+    // which the section player kernel raises once the element pre-warm
+    // resolves.
     if (detail.allLoadingComplete && state.cohort && !loadingCompleteEmitted) {
         loadingCompleteEmitted = true;
         outputs.push({

package/dist/runtime/registration-events.d.ts

@@ -71,16 +71,14 @@ export interface InternalFormativeActionDetail {
 /**
  * A Media Time Source becoming available or going away.
  *
- * The one seam through which a timed-media section reaches media, and
- * deliberately the *only* one: the stimulus card dispatches this with a native
- * `<video>` adapter, and a host wrapping a third-party player dispatches the same
- * event with its own port. One code path, two producers — which is what keeps
- * "a host can supply its own media element without shipping a PIE element" true
- * rather than aspirational.
+ * The only seam through which a timed-media section reaches media: the stimulus
+ * card dispatches it with a native `<video>` adapter, and a host wrapping a
+ * third-party player dispatches it with its own port. One code path with two
+ * producers is what lets a host supply its own media element without shipping a
+ * PIE element.
  *
- * `source` carries a live object, not serializable data. That is fine and
- * intended: this event never crosses a realm, exactly like the element reference
- * on `pie-register`.
+ * `source` is a live object. The event never crosses a realm, like the element
+ * reference on `pie-register`.
  */
 export interface InternalMediaTimeSourceDetail {
     /** The renderable that owns the media, for matching against `stimulusRef`. */
@@ -93,11 +91,10 @@ export interface InternalMediaTimeSourceDetail {
      * wiring its own player, and omitting the field reads as `"host"` because a
      * caller constructing this event by hand is one.
      *
-     * Load-bearing for precedence: the card re-runs its discovery whenever its
-     * content changes, so without this a host that supplied a third-party port would
-     * have it silently replaced by the native element mid-session — and the
-     * capabilities would flip back with it, which is exactly the "appears to enforce"
-     * failure this contract exists to prevent.
+     * Precedence depends on it: the card re-runs its discovery whenever its content
+     * changes, and without the field the native element would replace a host's
+     * third-party port mid-session, flipping the capabilities back with it, so a
+     * policy would read as enforced while it is not.
      */
     origin?: "native-adapter" | "host";
 }

package/dist/runtime/runtime-id.d.ts

@@ -2,6 +2,6 @@
  * Stable runtime-instance id generator.
  *
  * Produces a per-runtime id used to scope DOM attribute names and
- * telemetry tags. Single export by design — not a "guards" module.
+ * telemetry tags.
  */
 export declare function createRuntimeId(prefix?: string): string;

package/dist/runtime/runtime-id.js

@@ -2,7 +2,7 @@
  * Stable runtime-instance id generator.
  *
  * Produces a per-runtime id used to scope DOM attribute names and
- * telemetry tags. Single export by design — not a "guards" module.
+ * telemetry tags.
  */
 export function createRuntimeId(prefix = "runtime") {
     return `${prefix}-${Math.random().toString(16).slice(2)}-${Date.now()}`;

package/dist/runtime/shell-scope.d.ts

@@ -35,10 +35,10 @@ export interface ShellScope {
      * answered the scope in its detail, so that runtime claims it by id. Once
      * the host has left the document, as in a teardown, the event is dispatched
      * on the runtime's element instead, which the scope captured when the
-     * runtime answered. Events
-     * sent before a runtime has answered are held, the newest
-     * {@link MAX_HELD_SHELL_EVENTS}, and delivered in order once one does.
-     * `disconnect` and `publish(null)` drop them.
+     * runtime answered. Events sent before a runtime has answered, or while the
+     * runtime's element is out of the document and the host is in it, are held,
+     * the newest {@link MAX_HELD_SHELL_EVENTS}, and delivered in order to the
+     * runtime that answers next. `disconnect` and `publish(null)` drop them.
      */
     send: (type: string, detail: object) => void;
 }

package/dist/runtime/shell-scope.js

@@ -83,10 +83,14 @@ export function createShellScope() {
         if (runtime !== null)
             registration.sync(identity, runtime);
     };
+    // A runtime element that left the document while the shell stays in it no
+    // longer sits above the shell, so nothing would claim the shell's events.
+    const runtimeDeparted = (shellHost, address) => shellHost.isConnected &&
+        address.eventTarget.isConnected === false;
     function send(type, detail) {
         if (type === PIE_INTERNAL_CONTENT_LOADED_EVENT)
             loaded = detail;
-        if (host && runtime !== null) {
+        if (host && runtime !== null && !runtimeDeparted(host, runtime)) {
             dispatchCrossBoundaryEvent(shellEventTarget(host, runtime), type, {
                 ...detail,
                 runtimeId: runtime.runtimeId,
@@ -97,20 +101,22 @@ export function createShellScope() {
         if (held.length > MAX_HELD_SHELL_EVENTS)
             held.shift();
     }
-    // The subscription re-answers whenever the runtime republishes its context,
-    // so only a different id means anything here.
+    // The subscription re-answers whenever the runtime republishes its context:
+    // under the same id it only delivers what the scope held meanwhile.
     function onRuntime(value) {
-        if (value.runtimeId === runtime?.runtimeId)
-            return;
-        const moved = runtime !== null;
-        runtime = { runtimeId: value.runtimeId, eventTarget: value.eventTarget };
-        syncRegistration();
+        const moved = runtime !== null && value.runtimeId !== runtime.runtimeId;
+        if (value.runtimeId !== runtime?.runtimeId) {
+            runtime = { runtimeId: value.runtimeId, eventTarget: value.eventTarget };
+            syncRegistration();
+        }
         const pending = held;
         held = [];
         for (const event of pending)
             send(event.type, event.detail);
-        if (moved && loaded)
+        const replayed = pending.some((event) => event.type === PIE_INTERNAL_CONTENT_LOADED_EVENT);
+        if (moved && loaded && !replayed) {
             send(PIE_INTERNAL_CONTENT_LOADED_EVENT, loaded);
+        }
     }
     function disconnect() {
         for (const provided of [shell, region])

package/dist/runtime/tool-host-contract.d.ts

@@ -2,10 +2,6 @@ import { type AssessmentToolkitHostRuntimeContext, type AssessmentToolkitRegionS
 import type { ZIndexLayer } from "../services/ToolCoordinator.js";
 import type { ToolCoordinatorApi } from "../services/interfaces.js";
 type BaseEventInit = Pick<EventInit, "bubbles" | "composed" | "cancelable">;
-/**
- * Contract helper for all toolkit/tool events that must cross custom-element boundaries.
- */
-export declare function createCrossBoundaryEvent<T>(name: string, detail: T, init?: Partial<BaseEventInit>): CustomEvent<T>;
 /**
  * Dispatches a cross-boundary event with toolkit defaults.
  */

package/dist/runtime/tool-host-contract.js

@@ -8,7 +8,7 @@ const CROSS_BOUNDARY_EVENT_INIT = {
 /**
  * Contract helper for all toolkit/tool events that must cross custom-element boundaries.
  */
-export function createCrossBoundaryEvent(name, detail, init = {}) {
+function createCrossBoundaryEvent(name, detail, init = {}) {
     return new CustomEvent(name, {
         detail,
         ...CROSS_BOUNDARY_EVENT_INIT,