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

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,

package/dist/services/AccessibilityCatalogResolver.d.ts

@@ -55,25 +55,17 @@ export type CatalogType = "spoken" | "sign-language" | "transcript" | "braille"
 /**
  * The catalog types PIE names, plus the rule for the ones it does not.
  *
- * The type above stays open on purpose: QTI treats the support vocabulary as
- * extensible, and closing it here would reject content PIE has no reason to
- * reject and could not usefully validate anyway, since catalogs arrive as
- * authored JSON rather than through this type. Keeping it open cost something
- * though — the named literals were documentation only, so a card written
- * `"spokn"` was a perfectly valid `CatalogType` that no reader would ever ask
- * for, and it failed by being invisible rather than by failing. That is what
- * `isKnownCatalogType` and the warnings below are for: the openness stays, the
- * silence does not.
+ * `CatalogType` stays open because QTI treats the support vocabulary as
+ * extensible, and catalogs arrive as authored JSON this type never validates.
+ * The trade: a card written `"spokn"` is a valid `CatalogType` no reader asks
+ * for, so `isKnownCatalogType` and the warnings below report it.
  */
 export declare const KNOWN_CATALOG_TYPES: ReadonlySet<string>;
 export declare function isKnownCatalogType(type: string): boolean;
 /**
- * Which of a card's two content slots it fills.
- *
- * Not a new field on the card and not a second discriminant: the card already
- * says which form it is by carrying `content` or `payload`, and the
- * exactly-one-of invariant is what makes that unambiguous. This names the
- * distinction so a lookup can ask for one.
+ * Which of a card's two content slots it fills. The card says so by carrying
+ * `content` or `payload`, and the exactly-one-of invariant makes that
+ * unambiguous; this type names the distinction so a lookup can ask for one.
  */
 export type CatalogCardForm = "content" | "payload";
 export declare const catalogCardForm: (card: CatalogCard) => CatalogCardForm;
@@ -93,17 +85,15 @@ export interface CatalogLookupOptions {
      * Preferred content form, when one catalog type legitimately has both on the
      * same node.
      *
-     * The case this exists for is a `spoken` node carrying both a reading script
-     * and a recording of it — which is APIP's authoring pattern and what QTI 3's
-     * migration guidance tells you to keep, the script doubling as the source the
-     * audio was generated from and as the fallback when it cannot play. Before
-     * this, both resolution rungs took the first card matching type and language,
-     * so whichever of the two was written second in the array was unreachable and
-     * nothing said so.
+     * The case is a `spoken` node carrying both a reading script and a recording
+     * of it, which is APIP's authoring pattern and what QTI 3's migration
+     * guidance keeps: the script is the source the audio was generated from and
+     * the fallback when it cannot play. Without a form, a lookup returns the
+     * first card matching type and language.
      *
      * A preference, not a filter: if the requested form is not present, the other
-     * one is still returned. Callers that cannot use a form must check what they
-     * got, exactly as they already must for a card of a type they did not expect.
+     * one is still returned. Callers that cannot use a form check what they got,
+     * as they do for a card of a type they did not expect.
      */
     form?: CatalogCardForm;
 }
@@ -241,9 +231,11 @@ export declare class AccessibilityCatalogResolver {
      */
     hasCatalog(catalogId: string): boolean;
     /**
-     * Get alternative content for a catalog identifier
+     * Get alternative content for a catalog identifier.
      *
-     * Priority: Item-level catalogs take precedence over assessment-level
+     * With a `context`, the catalog registered for exactly that owner comes
+     * first, then the one compatible scoped catalog (several are ambiguous and
+     * resolve to null). Item-level catalogs come next, then assessment-level.
      */
     getAlternative(catalogId: string, options: CatalogLookupOptions): ResolvedCatalog | null;
     private resolveCard;
@@ -264,11 +256,9 @@ export declare class AccessibilityCatalogResolver {
      * Get all available alternatives for a catalog identifier
      *
      * Every card goes through `resolveCard`, the same projection `getAlternative`
-     * uses, so enumeration cannot describe a card differently from the resolution
-     * that renders it. It was hand-rolled here once and drifted immediately: the
-     * `signLanguage` alias was folded in on the resolution path only, so a card
-     * that arrived under the alias rendered correctly and was still reported as
-     * carrying no payload by anything asking what alternates exist.
+     * uses, so enumeration describes a card exactly as the resolution that
+     * renders it. A hand-rolled copy here drifted: the `signLanguage` alias was
+     * folded in on the resolution path only.
      */
     getAllAlternatives(catalogId: string): ResolvedCatalog[];
     /**

package/dist/services/AccessibilityCatalogResolver.js

@@ -4,15 +4,10 @@ import { sanitizeSsmlString } from "./SSMLExtractor.js";
 /**
  * The catalog types PIE names, plus the rule for the ones it does not.
  *
- * The type above stays open on purpose: QTI treats the support vocabulary as
- * extensible, and closing it here would reject content PIE has no reason to
- * reject and could not usefully validate anyway, since catalogs arrive as
- * authored JSON rather than through this type. Keeping it open cost something
- * though — the named literals were documentation only, so a card written
- * `"spokn"` was a perfectly valid `CatalogType` that no reader would ever ask
- * for, and it failed by being invisible rather than by failing. That is what
- * `isKnownCatalogType` and the warnings below are for: the openness stays, the
- * silence does not.
+ * `CatalogType` stays open because QTI treats the support vocabulary as
+ * extensible, and catalogs arrive as authored JSON this type never validates.
+ * The trade: a card written `"spokn"` is a valid `CatalogType` no reader asks
+ * for, so `isKnownCatalogType` and the warnings below report it.
  */
 export const KNOWN_CATALOG_TYPES = new Set([
     "spoken",
@@ -336,9 +331,11 @@ export class AccessibilityCatalogResolver {
             Array.from(this.scopedCatalogs.values()).some((owner) => owner.catalogs.has(catalogId)));
     }
     /**
-     * Get alternative content for a catalog identifier
+     * Get alternative content for a catalog identifier.
      *
-     * Priority: Item-level catalogs take precedence over assessment-level
+     * With a `context`, the catalog registered for exactly that owner comes
+     * first, then the one compatible scoped catalog (several are ambiguous and
+     * resolve to null). Item-level catalogs come next, then assessment-level.
      */
     getAlternative(catalogId, options) {
         // A typo on this side is as silent as one on a card: the lookup simply finds
@@ -513,10 +510,10 @@ export class AccessibilityCatalogResolver {
         }
         return false;
     }
-    // The single funnel every registration path runs through — the constructor and
-    // `addItemCatalogs` by way of `indexCatalogs`, and `registerCatalogs`
-    // directly — which is why the unknown-type report lives here rather than at
-    // each entry point.
+    // The single funnel every registration path runs through (the constructor and
+    // `addItemCatalogs` by way of `indexCatalogs`, `registerCatalogs` and
+    // `registerOwner` by way of `insertScopedCatalogs`), so the unknown-type
+    // report lives here.
     sanitizeCatalogs(catalogs) {
         return catalogs.map((catalog) => ({
             ...catalog,
@@ -541,11 +538,10 @@ export class AccessibilityCatalogResolver {
         // Language rungs, most specific first: the requested language, then the
         // default language, then any.
         //
-        // Each requested tag expands into its RFC 4647 lookup sequence, so `es-MX`
-        // tries `es-mx` and then `es` before falling through to the default. Matching
-        // was `===`, which made a POSIX `es_ES` card — what the Learnosity transform
-        // emits — unreachable for an `es-ES` request except through the final
-        // no-constraint rung, i.e. by accident.
+        // Each requested tag expands into its RFC 4647 lookup sequence over
+        // normalized tags, so `es-MX` tries `es-mx` and then `es` before falling
+        // through to the default, and a POSIX `es_ES` card (what the Learnosity
+        // transform emits) matches an `es-ES` request on its own rung.
         const languageRungs = [];
         const pushLookupRungs = (tag) => {
             for (const step of languageTagLookupSequence(tag)) {
@@ -563,18 +559,16 @@ export class AccessibilityCatalogResolver {
             const candidates = catalog.cards.filter((card) => card.catalog === type && matchesLanguage(card));
             if (candidates.length === 0)
                 continue;
-            // Form is preferred inside a language rung and never across them: a
-            // recording in the requested language beats a script in that language,
-            // but a script in the requested language beats a recording in another
-            // one. Getting this backwards would answer a Spanish lookup with English
-            // audio, which is worse than answering it with Spanish text.
+            // Language outranks form: form is preferred inside a language rung and
+            // never across them, so a Spanish lookup preferring a recording gets a
+            // Spanish recording first, then Spanish text, and never English audio
+            // ahead of either.
             if (form) {
                 const preferred = candidates.find((card) => catalogCardForm(card) === form);
                 if (preferred)
                     return preferred;
             }
-            // No preference expressed, or the preferred form is absent: first match,
-            // which is what every caller got before form preference existed.
+            // No preference, or the preferred form is absent: the first match.
             return candidates[0];
         }
         return null;
@@ -583,25 +577,20 @@ export class AccessibilityCatalogResolver {
      * Get all available alternatives for a catalog identifier
      *
      * Every card goes through `resolveCard`, the same projection `getAlternative`
-     * uses, so enumeration cannot describe a card differently from the resolution
-     * that renders it. It was hand-rolled here once and drifted immediately: the
-     * `signLanguage` alias was folded in on the resolution path only, so a card
-     * that arrived under the alias rendered correctly and was still reported as
-     * carrying no payload by anything asking what alternates exist.
+     * uses, so enumeration describes a card exactly as the resolution that
+     * renders it. A hand-rolled copy here drifted: the `signLanguage` alias was
+     * folded in on the resolution path only.
      */
     getAllAlternatives(catalogId) {
         const results = [];
-        // Type, language *and* form: one catalog identifier legitimately carries
-        // several cards of the same type in different languages, and also a script
-        // and a recording of the same type in the *same* language. Keying on type
-        // and language alone dropped the second of those on the floor, so anything
-        // asking what alternates exist under-reported them.
+        // Keyed on type, language and form: one catalog identifier can carry cards
+        // of one type in several languages, and a script and a recording of one
+        // type in the same language.
         const claimed = new Set();
         const add = (card, source) => {
             // The language part is normalized, so a POSIX `es_ES` card and a BCP-47
-            // `es-ES` card collapse to one entry here exactly as they now collapse on
-            // the resolution path. Keying on the raw string would report two
-            // alternates where resolution can only ever return one.
+            // `es-ES` card collapse to one entry, as on the resolution path, which
+            // only ever returns one of them.
             const key = `${card.catalog}|${normalizeLanguageTag(card.language)}|${catalogCardForm(card)}`;
             if (claimed.has(key))
                 return;
@@ -646,7 +635,6 @@ export class AccessibilityCatalogResolver {
     getStatistics() {
         const allTypes = new Set();
         const allLanguages = new Set();
-        // Collect from assessment catalogs
         for (const catalog of this.assessmentCatalogs.values()) {
             for (const card of catalog.cards) {
                 allTypes.add(card.catalog);
@@ -654,7 +642,6 @@ export class AccessibilityCatalogResolver {
                     allLanguages.add(card.language);
             }
         }
-        // Collect from item catalogs
         for (const catalog of this.itemCatalogs.values()) {
             for (const card of catalog.cards) {
                 allTypes.add(card.catalog);