@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

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, 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;
+}
+/**
+ * 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;

package/dist/runtime/shell-scope.js

@@ -0,0 +1,194 @@
+import { ContextProvider, } from "@pie-players/pie-context";
+import { assessmentToolkitRegionScopeContext, assessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
+import { catalogSourceSignature, } from "../services/catalog-owner.js";
+import { PIE_INTERNAL_CONTENT_LOADED_EVENT } from "./registration-events.js";
+import { createShellRegistrationDispatcher, shellEventTarget, } from "./shell-registration.js";
+import { connectHostRuntimeContext, dispatchCrossBoundaryEvent, } from "./tool-host-contract.js";
+/**
+ * The newest events kept until a runtime answers; an older one is dropped. A
+ * scope in plain mode sends only load and error events, a section shell its
+ * session events too.
+ */
+const MAX_HELD_SHELL_EVENTS = 50;
+function provide(host, context, value) {
+    const provider = new ContextProvider(host, { context, initialValue: value });
+    provider.connect();
+    return { provider, value };
+}
+function republish(provided, value, same) {
+    if (same(provided.value, value))
+        return;
+    provided.value = value;
+    provided.provider.setValue(value);
+}
+const sameItem = (a, b, kind) => {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.id !== b.id)
+        return false;
+    const catalogs = catalogSourceSignature(a, kind);
+    return (catalogs !== null &&
+        catalogs === catalogSourceSignature(b, kind));
+};
+const sameShellContext = (a, b) => a.kind === b.kind &&
+    a.itemId === b.itemId &&
+    a.canonicalItemId === b.canonicalItemId &&
+    a.contentKind === b.contentKind &&
+    a.regionPolicy === b.regionPolicy &&
+    a.scopeElement === b.scopeElement &&
+    sameItem(a.item, b.item, a.kind);
+const sameRegionScope = (a, b) => a.scopeElement === b.scopeElement &&
+    a.ttsHighlightTargetResolver === b.ttsHighlightTargetResolver;
+const setAttributeIfChanged = (host, name, value) => {
+    if (host.getAttribute(name) !== value)
+        host.setAttribute(name, value);
+};
+/**
+ * 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 function createShellScope() {
+    const registration = createShellRegistrationDispatcher();
+    const contextVersion = Date.now();
+    let host = null;
+    let shell = null;
+    let region = null;
+    let stopFindingRuntime = null;
+    let runtime = null;
+    let identity = null;
+    let held = [];
+    let loaded = null;
+    const syncRegistration = () => {
+        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 && !runtimeDeparted(host, runtime)) {
+            dispatchCrossBoundaryEvent(shellEventTarget(host, runtime), type, {
+                ...detail,
+                runtimeId: runtime.runtimeId,
+            });
+            return;
+        }
+        held.push({ type, detail });
+        if (held.length > MAX_HELD_SHELL_EVENTS)
+            held.shift();
+    }
+    // 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) {
+        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);
+        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])
+            provided?.provider.disconnect();
+        stopFindingRuntime?.();
+        stopFindingRuntime = null;
+        runtime = null;
+        held = [];
+        loaded = null;
+        identity = null;
+        shell = null;
+        region = null;
+        host = null;
+    }
+    function publish(state) {
+        if (!state) {
+            registration.sync(null);
+            disconnect();
+            return;
+        }
+        if (state.host !== host)
+            disconnect();
+        host = state.host;
+        const canonicalItemId = state.canonicalItemId || state.itemId;
+        const regionPolicy = state.regionPolicy || "default";
+        const scopeElement = state.scopeElement || state.host;
+        const shellValue = {
+            kind: state.kind,
+            itemId: state.itemId,
+            canonicalItemId,
+            contentKind: state.contentKind,
+            regionPolicy,
+            scopeElement,
+            item: state.item ?? null,
+            contextVersion,
+        };
+        if (shell)
+            republish(shell, shellValue, sameShellContext);
+        else
+            shell = provide(host, assessmentToolkitShellContext, shellValue);
+        const regionValue = {
+            scopeElement,
+            ttsHighlightTargetResolver: state.ttsHighlightTargetResolver ?? null,
+        };
+        if (region)
+            republish(region, regionValue, sameRegionScope);
+        else
+            region = provide(host, assessmentToolkitRegionScopeContext, regionValue);
+        setAttributeIfChanged(host, "data-item-id", state.itemId);
+        setAttributeIfChanged(host, "data-canonical-item-id", canonicalItemId);
+        setAttributeIfChanged(host, "data-pie-shell-root", state.kind);
+        setAttributeIfChanged(host, "data-region-policy", regionPolicy);
+        const previousIdentity = identity;
+        identity = state.itemId
+            ? {
+                kind: state.kind,
+                host,
+                itemId: state.itemId,
+                canonicalItemId,
+                contentKind: state.contentKind,
+                item: state.item ?? null,
+                settings: state.settings ?? null,
+            }
+            : null;
+        if (previousIdentity &&
+            (previousIdentity.itemId !== identity?.itemId ||
+                previousIdentity.canonicalItemId !== identity?.canonicalItemId)) {
+            loaded = null;
+        }
+        // Answers at once when the runtime is already there.
+        stopFindingRuntime ??= connectHostRuntimeContext(host, onRuntime);
+        syncRegistration();
+    }
+    return { publish, retire: registration.retire, disconnect, send };
+}

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

@@ -1,29 +1,27 @@
-import type { UnknownContext } from "@pie-players/pie-context";
-import { type RegionScopeContextListener, type RuntimeContextListener, type ShellContextListener } from "../context/runtime-context-consumer.js";
+import { type AssessmentToolkitHostRuntimeContext, type AssessmentToolkitRegionScopeContext, type AssessmentToolkitRuntimeContext, type AssessmentToolkitShellContext } from "../context/assessment-toolkit-context.js";
 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.
  */
 export declare function dispatchCrossBoundaryEvent<T>(target: EventTarget, name: string, detail: T, init?: Partial<BaseEventInit>): boolean;
 /**
  * Shared runtime-context connection contract for tools and shells.
- * Uses retry + provider announcements so late providers are tolerated.
+ * A provider that connects after the tool answers it through the document's
+ * context root.
  */
-export declare function connectToolRuntimeContext(host: HTMLElement, onValue: RuntimeContextListener): () => void;
+export declare function connectToolRuntimeContext(host: HTMLElement, onValue: (value: AssessmentToolkitRuntimeContext) => void): () => void;
 /**
  * Shared shell-context connection contract for tools needing item/passage scope.
  */
-export declare function connectToolShellContext(host: HTMLElement, onValue: ShellContextListener): () => void;
+export declare function connectToolShellContext(host: HTMLElement, onValue: (value: AssessmentToolkitShellContext) => void): () => void;
 /**
  * Shared region-scope context contract for tools targeting content subregions.
  */
-export declare function connectToolRegionScopeContext(host: HTMLElement, onValue: RegionScopeContextListener): () => void;
+export declare function connectToolRegionScopeContext(host: HTMLElement, onValue: (value: AssessmentToolkitRegionScopeContext) => void): () => void;
+/** Connects a shell or toolkit element to the host runtime context above it. */
+export declare function connectHostRuntimeContext(host: HTMLElement, onValue: (value: AssessmentToolkitHostRuntimeContext) => void): () => void;
 /** A tool's registration with the coordinator in its runtime context. */
 export interface ToolCoordinatorRegistration {
     /**
@@ -42,8 +40,4 @@ export interface ToolCoordinatorRegistration {
     release(): void;
 }
 export declare function createToolCoordinatorRegistration(name: string, layer: ZIndexLayer): ToolCoordinatorRegistration;
-/**
- * Guard utility: narrows unknown context payloads when needed by callers.
- */
-export declare function isContextValueDefined<T extends UnknownContext>(value: unknown): value is T["__context__"];
 export {};

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

@@ -1,4 +1,5 @@
-import { connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "../context/runtime-context-consumer.js";
+import { connectContextWithRetry } from "@pie-players/pie-context";
+import { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
 const CROSS_BOUNDARY_EVENT_INIT = {
     bubbles: true,
     composed: true,
@@ -7,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,
@@ -22,22 +23,27 @@ export function dispatchCrossBoundaryEvent(target, name, detail, init = {}) {
 }
 /**
  * Shared runtime-context connection contract for tools and shells.
- * Uses retry + provider announcements so late providers are tolerated.
+ * A provider that connects after the tool answers it through the document's
+ * context root.
  */
 export function connectToolRuntimeContext(host, onValue) {
-    return connectAssessmentToolkitRuntimeContext(host, onValue);
+    return connectContextWithRetry(host, assessmentToolkitRuntimeContext, onValue);
 }
 /**
  * Shared shell-context connection contract for tools needing item/passage scope.
  */
 export function connectToolShellContext(host, onValue) {
-    return connectAssessmentToolkitShellContext(host, onValue);
+    return connectContextWithRetry(host, assessmentToolkitShellContext, onValue);
 }
 /**
  * Shared region-scope context contract for tools targeting content subregions.
  */
 export function connectToolRegionScopeContext(host, onValue) {
-    return connectAssessmentToolkitRegionScopeContext(host, onValue);
+    return connectContextWithRetry(host, assessmentToolkitRegionScopeContext, onValue);
+}
+/** Connects a shell or toolkit element to the host runtime context above it. */
+export function connectHostRuntimeContext(host, onValue) {
+    return connectContextWithRetry(host, assessmentToolkitHostRuntimeContext, onValue);
 }
 export function createToolCoordinatorRegistration(name, layer) {
     let registered = null;
@@ -60,9 +66,3 @@ export function createToolCoordinatorRegistration(name, layer) {
         release,
     };
 }
-/**
- * Guard utility: narrows unknown context payloads when needed by callers.
- */
-export function isContextValueDefined(value) {
-    return value !== null && value !== undefined;
-}

package/dist/runtime/unclaimed-registration-watch.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A toolkit stops every registration it claims, so one that reaches the
+ * document went unclaimed: its item's catalogs are not filed and it does not
+ * count toward its section's loading. Installed from a toolkit's host at
+ * connect, once per document across every copy of the toolkit.
+ */
+export declare function watchForUnclaimedRegistrations(doc: Document | null | undefined): void;