@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/runtime/policy-input-forwarding.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which policy inputs `<pie-assessment-toolkit>` forwards to the coordinator it
+ * owns.
+ *
+ * The toolkit forwards an input when its own value for it changes. A host
+ * driving the owned coordinator directly — an embedded toolkit's host binds its
+ * assessment from `runtime-ready` or `toolkit-ready` — keeps that binding until
+ * the toolkit's own value changes, so an unrelated re-run of the forwarding
+ * effect (a `tools` change, a coordinator rebuild trigger) cannot reset it. A
+ * coordinator not forwarded to yet is newly built and holds no inputs, so it
+ * receives only the inputs that are set.
+ */
+import type { AssessmentEntity } from "@pie-players/pie-players-shared/types";
+import type { PnpEnforcementMode } from "../policy/core/ToolPolicyEngine.js";
+export interface ForwardedPolicyInputs {
+    pnpEnforcement: PnpEnforcementMode | null;
+    assessment: AssessmentEntity | null;
+}
+/**
+ * The inputs to forward, in apply order: the enforcement override first, so
+ * binding the assessment never resolves auto-mode against a stale override.
+ * `previous` is what was last forwarded to the same coordinator, or `null` for
+ * a coordinator not forwarded to yet.
+ */
+export declare function policyInputsToForward(previous: ForwardedPolicyInputs | null, next: ForwardedPolicyInputs): Array<keyof ForwardedPolicyInputs>;

package/dist/runtime/policy-input-forwarding.js

@@ -0,0 +1,25 @@
+/**
+ * Which policy inputs `<pie-assessment-toolkit>` forwards to the coordinator it
+ * owns.
+ *
+ * The toolkit forwards an input when its own value for it changes. A host
+ * driving the owned coordinator directly — an embedded toolkit's host binds its
+ * assessment from `runtime-ready` or `toolkit-ready` — keeps that binding until
+ * the toolkit's own value changes, so an unrelated re-run of the forwarding
+ * effect (a `tools` change, a coordinator rebuild trigger) cannot reset it. A
+ * coordinator not forwarded to yet is newly built and holds no inputs, so it
+ * receives only the inputs that are set.
+ */
+/**
+ * The inputs to forward, in apply order: the enforcement override first, so
+ * binding the assessment never resolves auto-mode against a stale override.
+ * `previous` is what was last forwarded to the same coordinator, or `null` for
+ * a coordinator not forwarded to yet.
+ */
+export function policyInputsToForward(previous, next) {
+    const order = [
+        "pnpEnforcement",
+        "assessment",
+    ];
+    return order.filter((key) => previous ? !Object.is(previous[key], next[key]) : next[key] !== null);
+}

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

@@ -1,3 +1,5 @@
+import type { SessionCommitReason } from "@pie-players/pie-players-shared/pie";
+import type { ItemSettings } from "@pie-players/pie-players-shared/types";
 import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
 export declare const PIE_REGISTER_EVENT = "pie-register";
 export declare const PIE_UNREGISTER_EVENT = "pie-unregister";
@@ -14,13 +16,25 @@ export interface RuntimeRegistrationDetail {
     canonicalItemId?: string;
     contentKind?: string;
     item?: unknown;
+    /**
+     * An item's policy settings, which govern decisions scoped to the item; see
+     * `ToolkitCoordinatorApi.registerItemSettings`.
+     */
+    settings?: ItemSettings;
     element: HTMLElement;
+    /**
+     * The runtime the shell found through `assessmentToolkitHostRuntimeContext`.
+     * A toolkit claims an event carrying it only when the id is its own.
+     */
+    runtimeId?: string;
 }
 export interface ItemSessionChangedDetail {
     itemId: string;
     canonicalItemId?: string;
     session: unknown;
     sourceRuntimeId?: string;
+    /** Set when the change is a commit at a teardown, navigation or page-hidden seam. */
+    sessionCommitReason?: SessionCommitReason;
 }
 export interface InternalItemSessionChangedDetail {
     itemId: string;

package/dist/runtime/runtime-event-claim.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether the toolkit running as `runtimeId` claims a shell's event. A shell
+ * scope puts the id of the runtime that answered it in `detail.runtimeId`, and
+ * only that runtime claims the event. An event without one, from a shell that
+ * dispatches on its own, is claimed when `isLocalTarget` resolves its target
+ * to this runtime.
+ */
+export declare function isRuntimeEventClaimed(event: Event, runtimeId: string, isLocalTarget: (target: EventTarget | null) => boolean): boolean;

package/dist/runtime/runtime-event-claim.js

@@ -0,0 +1,15 @@
+/**
+ * Whether the toolkit running as `runtimeId` claims a shell's event. A shell
+ * scope puts the id of the runtime that answered it in `detail.runtimeId`, and
+ * only that runtime claims the event. An event without one, from a shell that
+ * dispatches on its own, is claimed when `isLocalTarget` resolves its target
+ * to this runtime.
+ */
+export function isRuntimeEventClaimed(event, runtimeId, isLocalTarget) {
+    const addressedTo = event
+        .detail?.runtimeId;
+    if (typeof addressedTo === "string" && addressedTo !== "") {
+        return addressedTo === runtimeId;
+    }
+    return isLocalTarget(event.target);
+}

package/dist/runtime/shell-event-bridge.d.ts

@@ -0,0 +1,45 @@
+import type { ShellContextKind } from "../context/assessment-toolkit-context.js";
+/**
+ * `section`: the shell is its content's only channel to the section. The
+ * player's `session-changed`, `load-complete` and `player-error` stop at the
+ * shell and travel on as the runtime's internal events, with an item's
+ * response changes also announced as `item-session-changed`.
+ *
+ * `plain`: the host owns the player and listens to it, so the player's events
+ * pass through untouched. The runtime still hears that the content loaded or
+ * failed, which a section bound later replays; sessions stay with the host.
+ */
+export type ShellEventBridgeMode = "section" | "plain";
+export interface ShellEventBridgeIdentity {
+    itemId: string;
+    canonicalItemId?: string;
+    contentKind?: string;
+}
+export interface ShellEventBridgeOptions {
+    /** The shell element, where the player's events arrive and leave from. */
+    host: HTMLElement;
+    kind: ShellContextKind;
+    /** Read as each event arrives, so a prop change needs no rebinding. */
+    identity: () => ShellEventBridgeIdentity;
+    /** Read as each event arrives. */
+    mode: () => ShellEventBridgeMode;
+    /** Sends an event addressed to the shell's runtime. */
+    send: (type: string, detail: object) => void;
+}
+export interface ShellEventBridge {
+    /**
+     * Gives an item's pending session one last chance to reach the section, then
+     * stops listening. The commit runs while the player is still inside the
+     * shell, so its `session-changed` arrives at the bridge before it is unbound.
+     * The shell has usually left the document by then; `send` delivers the
+     * forwarded session on the runtime's element.
+     */
+    disconnect: () => void;
+}
+/**
+ * A shell's translation of its player's events into the runtime's, shared by
+ * `<pie-item-scope>` and `<pie-passage-shell>`. The dedupe
+ * state lives as long as the bridge, so a prop change does not forget what was
+ * forwarded.
+ */
+export declare function createShellEventBridge(options: ShellEventBridgeOptions): ShellEventBridge;

package/dist/runtime/shell-event-bridge.js

@@ -0,0 +1,127 @@
+import { commitPendingSessions, createPieLogger, normalizeItemSessionChange, } from "@pie-players/pie-players-shared";
+import { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, } from "./registration-events.js";
+import { dispatchCrossBoundaryEvent } from "./tool-host-contract.js";
+/**
+ * Elements repeat themselves, a `complete` echo most often, so a session event
+ * is forwarded only when it differs from the last one, apart from when and
+ * through which runtime it was stamped.
+ */
+function sessionEventFingerprint(detail) {
+    const semanticDetail = detail && typeof detail === "object"
+        ? { ...detail }
+        : detail;
+    if (semanticDetail && typeof semanticDetail === "object") {
+        delete semanticDetail.timestamp;
+        delete semanticDetail.sourceRuntimeId;
+    }
+    try {
+        return JSON.stringify(semanticDetail);
+    }
+    catch {
+        return String(semanticDetail);
+    }
+}
+const isCommit = (detail) => Boolean(detail &&
+    typeof detail === "object" &&
+    detail.sessionCommitReason);
+/**
+ * A shell's translation of its player's events into the runtime's, shared by
+ * `<pie-item-scope>` and `<pie-passage-shell>`. The dedupe
+ * state lives as long as the bridge, so a prop change does not forget what was
+ * forwarded.
+ */
+export function createShellEventBridge(options) {
+    const { host, kind, identity, mode, send } = options;
+    const logger = createPieLogger(host.localName || "pie-shell", () => false);
+    let lastForwardedFingerprint = "";
+    const forwardSession = (detail) => {
+        const { itemId, canonicalItemId } = identity();
+        if (!itemId)
+            return;
+        const internal = {
+            itemId,
+            session: detail,
+        };
+        // The runtime keeps item state in step from every change; the public
+        // stream carries responses only.
+        send(PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, internal);
+        const normalized = normalizeItemSessionChange({
+            itemId,
+            sessionDetail: detail,
+        });
+        if (normalized.intent === "metadata-only" || !normalized.session)
+            return;
+        const payload = {
+            itemId,
+            canonicalItemId: canonicalItemId || itemId,
+            session: normalized.session,
+            ...(normalized.sessionCommitReason
+                ? { sessionCommitReason: normalized.sessionCommitReason }
+                : {}),
+        };
+        dispatchCrossBoundaryEvent(host, PIE_ITEM_SESSION_CHANGED_EVENT, payload);
+    };
+    const onSessionChanged = (event) => {
+        if (mode() !== "section")
+            return;
+        event.stopPropagation();
+        // A passage carries no response: a passage id on the section's session
+        // stream names no item a host has.
+        if (kind !== "item")
+            return;
+        const detail = event.detail;
+        const fingerprint = sessionEventFingerprint(detail);
+        // A commit is the response's last chance to reach the section.
+        if (!isCommit(detail) && fingerprint === lastForwardedFingerprint)
+            return;
+        lastForwardedFingerprint = fingerprint;
+        forwardSession(detail);
+    };
+    const onLoadComplete = (event) => {
+        if (mode() === "section")
+            event.stopPropagation();
+        const { itemId, canonicalItemId, contentKind } = identity();
+        if (!itemId)
+            return;
+        const detail = {
+            itemId,
+            canonicalItemId: canonicalItemId || itemId,
+            contentKind,
+            detail: event.detail,
+        };
+        send(PIE_INTERNAL_CONTENT_LOADED_EVENT, detail);
+    };
+    const onPlayerError = (event) => {
+        if (mode() === "section")
+            event.stopPropagation();
+        const { itemId, canonicalItemId, contentKind } = identity();
+        if (!itemId)
+            return;
+        const detail = {
+            itemId,
+            canonicalItemId: canonicalItemId || itemId,
+            contentKind,
+            error: event.detail,
+        };
+        send(PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, detail);
+    };
+    host.addEventListener("session-changed", onSessionChanged);
+    host.addEventListener("load-complete", onLoadComplete);
+    host.addEventListener("player-error", onPlayerError);
+    return {
+        disconnect: () => {
+            // An escape from the commit must not strand the listeners it needed, so
+            // the unbinding runs either way. A plain player commits its own.
+            try {
+                if (kind === "item" && mode() === "section") {
+                    commitPendingSessions(host, { reason: "teardown", logger });
+                }
+            }
+            finally {
+                host.removeEventListener("session-changed", onSessionChanged);
+                host.removeEventListener("load-complete", onLoadComplete);
+                host.removeEventListener("player-error", onPlayerError);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,73 @@
+import type { ItemSettings } from "@pie-players/pie-players-shared/types";
+/**
+ * Registration dispatch for the shells, through their shell scope.
+ *
+ * Registration is a statement of fact to the runtime, and the runtime takes it
+ * literally: a `pie-register` makes the toolkit unregister and re-register the
+ * content's accessibility catalogs, re-run `sectionBinding.register`, and
+ * re-notify the section controller.
+ *
+ * A shell's effects re-run whenever its props are re-applied, which happens on
+ * every update of its parent card's template. Dispatching from such an effect
+ * (with `pie-unregister` in its cleanup) announces a teardown and rebuild of
+ * state that has not moved, leaves the content without catalogs between the
+ * two, and closes a feedback loop: a reader that re-renders on a catalog change
+ * re-applies the shell's props, which re-registers, which changes catalogs
+ * again, until Svelte abandons the update at its depth limit with the DOM
+ * half-applied — while the elements are all present, so assertions about the
+ * rendered output still pass.
+ *
+ * So the dispatcher keeps the last identity it announced and says nothing when
+ * the next one matches.
+ */
+export type ShellRegistrationIdentity = {
+    kind: "item" | "passage";
+    host: HTMLElement;
+    itemId: string;
+    canonicalItemId: string;
+    contentKind: string;
+    item: unknown;
+    /** The item's policy settings, compared structurally like its catalogs. */
+    settings: ItemSettings | null;
+};
+/**
+ * The runtime a registration is addressed to: its id, and the element it
+ * listens on, which a shell whose host has left the document dispatches on.
+ */
+export type ShellRuntimeAddress = {
+    runtimeId: string;
+    eventTarget: EventTarget;
+};
+/**
+ * Where a shell's event to `runtime` goes: from the shell host while it is in
+ * the document, so the event bubbles through the tree like any other, and on
+ * the runtime's own element once it is not.
+ */
+export declare function shellEventTarget(host: HTMLElement, runtime: ShellRuntimeAddress | undefined): EventTarget;
+export type ShellRegistrationDispatcher = {
+    /**
+     * Announce `identity` if it says anything new, and retire the live
+     * registration when there is nothing left to describe — a shell without a host
+     * or an id no longer stands for content, and leaving its registration behind
+     * would strand it in the runtime.
+     *
+     * Never dispatches `pie-unregister` before a re-register to the same
+     * runtime: both registration paths in the toolkit are keyed by element and
+     * replace what is there, so the unregister only ever created the gap. A
+     * registration moving to a different runtime is retired first, addressed
+     * to the runtime that holds it.
+     */
+    sync: (identity: ShellRegistrationIdentity | null, runtime?: ShellRuntimeAddress) => void;
+    /**
+     * Retire the live registration, replaying the identity and runtime it was
+     * made under rather than whatever the props say now — by the time a
+     * registration is retired the props may already describe its replacement,
+     * and unregistering under the new identity would leave the old one live.
+     * A host already out of the document retires on the runtime's element.
+     *
+     * Belongs in a teardown that runs on teardown only. Attaching it to an effect
+     * that re-runs on prop changes is what made the churn.
+     */
+    retire: () => void;
+};
+export declare function createShellRegistrationDispatcher(): ShellRegistrationDispatcher;

package/dist/runtime/shell-registration.js

@@ -0,0 +1,95 @@
+import { catalogSourceSignature, } from "../services/catalog-owner.js";
+import { structurallyEqual } from "../utils/structural-equality.js";
+import { PIE_REGISTER_EVENT, PIE_UNREGISTER_EVENT, } from "./registration-events.js";
+import { dispatchCrossBoundaryEvent } from "./tool-host-contract.js";
+/**
+ * Everything a registration says except the item's catalogs.
+ */
+function sameOwner(a, b) {
+    return (a.kind === b.kind &&
+        a.host === b.host &&
+        a.itemId === b.itemId &&
+        a.canonicalItemId === b.canonicalItemId &&
+        a.contentKind === b.contentKind &&
+        structurallyEqual(a.settings, b.settings));
+}
+/**
+ * The item's part of a registration is its catalogs, which is all the runtime
+ * reads from it. Object identity is no guide: the toolkit and the layout kernel
+ * hold the composition in deep reactive state, so every republish, each answer
+ * included, hands a shell a new proxy of unchanged content.
+ */
+function catalogsOf(identity) {
+    return catalogSourceSignature(identity.item, identity.kind);
+}
+/**
+ * Where a shell's event to `runtime` goes: from the shell host while it is in
+ * the document, so the event bubbles through the tree like any other, and on
+ * the runtime's own element once it is not.
+ */
+export function shellEventTarget(host, runtime) {
+    return host.isConnected || !runtime ? host : runtime.eventTarget;
+}
+function dispatch(eventName, identity, runtime) {
+    const detail = {
+        kind: identity.kind,
+        itemId: identity.itemId,
+        canonicalItemId: identity.canonicalItemId,
+        contentKind: identity.contentKind,
+        item: identity.item,
+        ...(identity.settings ? { settings: identity.settings } : {}),
+        element: identity.host,
+        ...(runtime ? { runtimeId: runtime.runtimeId } : {}),
+    };
+    dispatchCrossBoundaryEvent(shellEventTarget(identity.host, runtime), eventName, detail);
+}
+export function createShellRegistrationDispatcher() {
+    /**
+     * What the runtime was last told, and the catalogs it was told about.
+     * Deliberately not reactive: it is read to decide whether to dispatch, and
+     * making it reactive would put that decision inside the graph it exists to
+     * keep quiet.
+     */
+    let dispatched = null;
+    let dispatchedCatalogs = null;
+    let dispatchedRuntime;
+    function retire() {
+        const previous = dispatched;
+        if (!previous)
+            return;
+        const previousRuntime = dispatchedRuntime;
+        dispatched = null;
+        dispatchedCatalogs = null;
+        dispatchedRuntime = undefined;
+        dispatch(PIE_UNREGISTER_EVENT, previous, previousRuntime);
+    }
+    function sync(identity, runtime) {
+        if (!identity) {
+            retire();
+            return;
+        }
+        if (dispatched && dispatchedRuntime?.runtimeId !== runtime?.runtimeId) {
+            retire();
+        }
+        if (dispatched && sameOwner(dispatched, identity)) {
+            // A re-render re-applies the object last seen, so identity settles most
+            // runs without serializing anything.
+            if (dispatched.item === identity.item)
+                return;
+            const catalogs = catalogsOf(identity);
+            if (catalogs !== null && catalogs === dispatchedCatalogs) {
+                dispatched = identity;
+                return;
+            }
+            dispatched = identity;
+            dispatchedCatalogs = catalogs;
+            dispatch(PIE_REGISTER_EVENT, identity, runtime);
+            return;
+        }
+        dispatched = identity;
+        dispatchedCatalogs = catalogsOf(identity);
+        dispatchedRuntime = runtime;
+        dispatch(PIE_REGISTER_EVENT, identity, runtime);
+    }
+    return { sync, retire };
+}

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

@@ -0,0 +1,68 @@
+import { type ShellContextKind } from "../context/assessment-toolkit-context.js";
+import type { ItemSettings } from "@pie-players/pie-players-shared/types";
+import type { TTSHighlightTargetResolver } from "../services/tts/highlight-target-resolver.js";
+/** What a shell says about the content it holds. */
+export interface ShellScopeState {
+    /** The shell element: it provides the contexts and dispatches the registration. */
+    host: HTMLElement;
+    kind: ShellContextKind;
+    itemId: string;
+    canonicalItemId?: string;
+    contentKind: string;
+    regionPolicy?: string;
+    /** The region the shell's tools act on; the shell itself when unset. */
+    scopeElement?: HTMLElement | null;
+    ttsHighlightTargetResolver?: TTSHighlightTargetResolver | null;
+    item?: unknown;
+    /** An item's policy settings, registered with the runtime alongside it. */
+    settings?: ItemSettings | null;
+}
+export interface ShellScope {
+    /**
+     * Publishes `state`, or withdraws the scope when there is none. A state that
+     * says nothing new publishes nothing.
+     */
+    publish: (state: ShellScopeState | null) => void;
+    /**
+     * Retires the runtime registration under the identity it was made with.
+     * Teardown only, after anything that still has to reach the runtime.
+     */
+    retire: () => void;
+    /** Stops providing the contexts, and drops the events `send` holds. */
+    disconnect: () => void;
+    /**
+     * Dispatches `type` from the shell host with the id of the runtime that
+     * 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.
+     */
+    send: (type: string, detail: object) => void;
+}
+/**
+ * A shell's publication of its content: the identity, as the shell context the
+ * tools inside it read, the region they act on, as the region scope, and the
+ * content itself, registered with the runtime, which files its accessibility
+ * catalogs under it. The section player's item and passage shells and
+ * `<pie-item-scope>` all publish through this, so a tool resolves its target
+ * and its catalogs the same way inside any of them.
+ *
+ * Content republished unchanged arrives as a new object, the composition being
+ * deep reactive state, so items compare by id and catalogs, the measure the
+ * registration applies.
+ *
+ * The registration waits for the runtime the shell sits in to answer through
+ * `assessmentToolkitHostRuntimeContext`, and carries that runtime's id, which
+ * the runtime claims it by. A shell mounted before its toolkit, which a host
+ * composing the elements itself can do, would otherwise register with no one
+ * listening, and nothing replays a registration. The document's context root
+ * replays the request instead, once the toolkit's provider connects. A
+ * different runtime answering later, a nearer toolkit taking over, moves the
+ * registration: the old runtime is told to unregister by its id, and the new
+ * one gets the registration and the content's last load, which only the old
+ * one heard.
+ */
+export declare function createShellScope(): ShellScope;