@pie-players/pie-players-shared 0.3.75 → 1.0.0-beta.1

package/dist/pie/stages.d.ts

@@ -4,9 +4,10 @@
  * A cohort (one section and attempt) moves through `composed`,
  * `engine-ready`, `interactive` and `disposed`, in that order. The section
  * runtime engine in `@pie-players/pie-assessment-toolkit` is the only emitter;
- * it dispatches the event on the layout element. `pie-loading-complete`
- * reports that every item loaded and is not a stage. `readiness.mode =
- * "strict"` only delays `interactive`.
+ * it dispatches the event on the layout element. `pie-loading-complete` is
+ * not a stage; it fires once per cohort when the section controller is ready
+ * and the element pre-warm has resolved. `readiness.mode = "strict"` only
+ * delays `interactive`.
  *
  * `status` is `entered`, or `failed` for the stage a non-recoverable
  * framework error stopped the chain at, with `skipped` for each later stage

package/dist/pie/stages.js

@@ -4,9 +4,10 @@
  * A cohort (one section and attempt) moves through `composed`,
  * `engine-ready`, `interactive` and `disposed`, in that order. The section
  * runtime engine in `@pie-players/pie-assessment-toolkit` is the only emitter;
- * it dispatches the event on the layout element. `pie-loading-complete`
- * reports that every item loaded and is not a stage. `readiness.mode =
- * "strict"` only delays `interactive`.
+ * it dispatches the event on the layout element. `pie-loading-complete` is
+ * not a stage; it fires once per cohort when the section controller is ready
+ * and the element pre-warm has resolved. `readiness.mode = "strict"` only
+ * delays `interactive`.
  *
  * `status` is `entered`, or `failed` for the stage a non-recoverable
  * framework error stopped the chain at, with `skipped` for each later stage

package/dist/pie/updates.js

@@ -8,7 +8,6 @@ import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { findPieController } from "./scoring.js";
 import { defaultPieElementOptions } from "./types.js";
 import { findOrAddSession } from "./utils.js";
-// Create module-level logger (respects global debug flag - pass function for dynamic checking)
 const logger = createPieLogger("pie-updates", () => isGlobalDebugEnabled());
 const describeControllerShape = (controller) => {
     if (!controller)
@@ -67,8 +66,10 @@ const trackRemoval = (element) => {
     return () => wasConnected && !element.isConnected;
 };
 /**
- * Helper function to apply controller to element
- * Extracted to eliminate duplication and ensure consistent controller invocation
+ * Runs the controller's `model()` and assigns the result to the element, with
+ * the authored model's `id` and `element` as defaults, together with the
+ * session the controller may have written to. Assigns nothing once the element
+ * was removed.
  */
 const applyControllerToElement = async (element, model, elementSession, controller, env, logPrefix, wasRemoved, onElementSessionUpdate) => {
     logger.debug(`${logPrefix} Using controller, env:`, env);
@@ -118,7 +119,7 @@ const applyControllerToElement = async (element, model, elementSession, controll
     }
     catch (err) {
         logger.error(`${logPrefix} ❌ Controller error:`, err);
-        throw err; // Re-throw - controller errors are fatal
+        throw err; // The caller reports it and falls back to the authored model.
     }
 };
 const resolveAndValidateUpdateOptions = (opts) => {

package/dist/pie/utils.d.ts

@@ -60,8 +60,6 @@ export declare const getPackageWithoutVersion: (packages: string) => string;
 /**
  * Find or add a session entry for a given element
  *
- * TODO: kinda gnarly, copied from player project
- *
  * @param data - Session data array
  * @param id - Model/element ID
  * @param element - Element tag name (optional)

package/dist/pie/utils.js

@@ -103,8 +103,6 @@ export const getPackageWithoutVersion = (packages) => packages
 /**
  * Find or add a session entry for a given element
  *
- * TODO: kinda gnarly, copied from player project
- *
  * @param data - Session data array
  * @param id - Model/element ID
  * @param element - Element tag name (optional)

package/dist/pie/versioned-tag.d.ts

@@ -17,3 +17,13 @@ export declare function parseVersionedTagName(tagName: string): {
 export declare function toPackageVersionedTag(tagName: string, packageSpec: string, options?: {
     preserveUnversionedTag?: boolean;
 }): string;
+/**
+ * The tags a player can define an authored element under, most specific first:
+ * the versioned tag for its package spec, aligned to the page's preloaded
+ * registration, then the authored tag, which an unversioned spec keeps. With no
+ * spec the authored tag is the only candidate.
+ *
+ * For code that looks an element's class up by tag without rendering it, such as
+ * reading what the class declares before the element is in the DOM.
+ */
+export declare function runtimeElementTags(tagName: string, packageSpec?: string): string[];

package/dist/pie/versioned-tag.js

@@ -1,3 +1,4 @@
+import { alignPreloadedElementVersions } from "../loaders/preloaded-alignment.js";
 import { parsePackageName } from "./utils.js";
 const VERSION_DELIMITER = "--version-";
 const TAG_VERSION_PATTERN = "[0-9A-Za-z-]+";
@@ -45,3 +46,29 @@ export function toPackageVersionedTag(tagName, packageSpec, options = {}) {
     // package versions at runtime, which requires updating the cloned runtime tag.
     return `${baseName}${VERSION_DELIMITER}${targetEncodedVersion}`;
 }
+/**
+ * The tags a player can define an authored element under, most specific first:
+ * the versioned tag for its package spec, aligned to the page's preloaded
+ * registration, then the authored tag, which an unversioned spec keeps. With no
+ * spec the authored tag is the only candidate.
+ *
+ * For code that looks an element's class up by tag without rendering it, such as
+ * reading what the class declares before the element is in the DOM.
+ */
+export function runtimeElementTags(tagName, packageSpec) {
+    if (!packageSpec)
+        return [tagName];
+    let versioned;
+    try {
+        const { elements } = alignPreloadedElementVersions({
+            elements: { [tagName]: packageSpec },
+        });
+        versioned = toPackageVersionedTag(tagName, elements[tagName], {
+            preserveUnversionedTag: true,
+        });
+    }
+    catch {
+        return [tagName];
+    }
+    return versioned === tagName ? [tagName] : [versioned, tagName];
+}

package/dist/security/sanitize-item-markup.d.ts

@@ -31,8 +31,8 @@ export interface SanitizeItemMarkupOptions {
  * Sanitize raw item/passage markup before it is injected into the DOM.
  *
  * - Strips `<script>`, event-handler attributes, unknown protocols and
- *   a standard set of dangerous tags (`iframe`, `object`, `embed`, `base`,
- *   `form`, `meta`, `link`).
+ *   the other tags in `SANITIZER_FORBIDDEN_TAGS` (`iframe`, `object`, `embed`,
+ *   `base`, `form`, `meta`, `link`, `style`, `foreignObject`).
  * - Preserves PIE custom elements (`pie-*`) and any extra tags listed in
  *   `allowedCustomElements`.
  * - Marks elements that carry an authored color, as `markAuthoredColors`
@@ -46,8 +46,8 @@ export interface SanitizeItemMarkupOptions {
 export declare function sanitizeItemMarkup(markup: string, options?: SanitizeItemMarkupOptions): string;
 /**
  * Build the default `ItemMarkupSanitizer` used by the players. The returned
- * function is stable for a given set of allowed custom elements so callers
- * can safely use reference equality when deciding whether to re-sanitize.
+ * function captures the options once; each call returns a new function, so a
+ * caller that compares sanitizers by identity keeps the one it built.
  */
 export declare function createDefaultItemMarkupSanitizer(options?: SanitizeItemMarkupOptions): ItemMarkupSanitizer;
 /**

package/dist/security/sanitize-item-markup.js

@@ -102,8 +102,8 @@ function resolvePurifier() {
  * Sanitize raw item/passage markup before it is injected into the DOM.
  *
  * - Strips `<script>`, event-handler attributes, unknown protocols and
- *   a standard set of dangerous tags (`iframe`, `object`, `embed`, `base`,
- *   `form`, `meta`, `link`).
+ *   the other tags in `SANITIZER_FORBIDDEN_TAGS` (`iframe`, `object`, `embed`,
+ *   `base`, `form`, `meta`, `link`, `style`, `foreignObject`).
  * - Preserves PIE custom elements (`pie-*`) and any extra tags listed in
  *   `allowedCustomElements`.
  * - Marks elements that carry an authored color, as `markAuthoredColors`
@@ -167,8 +167,8 @@ export function sanitizeItemMarkup(markup, options = {}) {
 }
 /**
  * Build the default `ItemMarkupSanitizer` used by the players. The returned
- * function is stable for a given set of allowed custom elements so callers
- * can safely use reference equality when deciding whether to re-sanitize.
+ * function captures the options once; each call returns a new function, so a
+ * caller that compares sanitizers by identity keeps the one it built.
  */
 export function createDefaultItemMarkupSanitizer(options = {}) {
     const { allowedCustomElements, wrapOverwideContent } = options;

package/dist/security/sanitize-svg-icon.js

@@ -51,8 +51,8 @@ export function sanitizeSvgIcon(icon) {
     });
     const str = typeof result === "string" ? result : String(result ?? "");
     if (stringCache.size >= STRING_CACHE_MAX) {
-        // Naive LRU: clear oldest half when the cache fills up. Tool icons are
-        // a small fixed set per assessment so this is rarely hit.
+        // Evict the oldest-inserted half when full; a hit does not refresh an entry.
+        // Tool icons are a small fixed set per assessment, so this rarely runs.
         const keys = [...stringCache.keys()];
         for (let i = 0; i < keys.length / 2; i += 1) {
             stringCache.delete(keys[i]);

package/dist/security/wrap-overwide-images.d.ts

@@ -24,7 +24,7 @@
  *   they never appeared in the authored markup string.
  *
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the table
- * wrapper: only the four values below and the accessible name differ.
+ * wrapper: only the spec below differs.
  */
 import { type WrapOverwideOptions } from "./wrap-overwide.js";
 export type WrapOverwideImagesInElementOptions = WrapOverwideOptions;

package/dist/security/wrap-overwide-images.js

@@ -24,7 +24,7 @@
  *   they never appeared in the authored markup string.
  *
  * The wrapping itself lives in `./wrap-overwide.js`, shared with the table
- * wrapper: only the four values below and the accessible name differ.
+ * wrapper: only the spec below differs.
  */
 import { isOverwideWrapMutation, wrapOverwideInElement, wrapOverwideMarkup, } from "./wrap-overwide.js";
 function buildAriaLabel(image) {

package/dist/timed-media/media-element-source.js

@@ -116,6 +116,5 @@ export function createMediaElementTimeSource(element, options = {}) {
 export function findMediaElement(root) {
     if (!root)
         return null;
-    const found = root.querySelector("video, audio");
-    return found ?? null;
+    return root.querySelector("video, audio");
 }

package/dist/types/index.d.ts

@@ -1,11 +1,12 @@
 /**
- * This contains copies of the data types we use in PIEOneer. These types, unlike
- * the ones in the datastore package, should not have any dependencies, and might in some
- * cases be more shallow than their originals. The main reason for these is that they should
- * be able to be used in front-end code (as well as the PIEOneer backend code).
+ * The PIE content and assessment model the players share: item, passage and
+ * section configs, the QTI-aligned assessment structure, session snapshots,
+ * accessibility catalogs and media references, `Env`, the element controller
+ * contract and authoring asset events.
  *
- * INCLUDING REFERENCES TO THE DATASTORE PACKAGE INSTEAD WILL MAKE PIEONEER THROW 500
- * EVERYWHERE WITHOUT ANY FURTHER EXPLANATION
+ * The `*Entity` shapes mirror content-store records and may be shallower than
+ * them. The module depends on nothing beyond this package's own type modules,
+ * so front-end and server code can both import it.
  */
 import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
 import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
@@ -55,10 +56,12 @@ export interface ConfigEntity {
     markup: string;
     elements: ConfigElements;
     models: PieModel[];
+    /** Configure settings for authoring mode. */
     configuration?: Record<string, any>;
     /**
      * QTI 3.0: Extracted accessibility catalogs from embedded SSML.
-     * Automatically generated by SSMLExtractor when <speak> tags are found in content.
+     * Written by SSMLExtractor when a host's preprocessing runs it over content
+     * holding <speak> tags; the players register what this carries.
      */
     extractedCatalogs?: AccessibilityCatalog[];
     [key: string]: any;
@@ -77,12 +80,9 @@ export interface PassageEntity extends VersionEntity, ConfigContainerEntity, Sea
 export interface ItemEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
     name?: string;
     /**
-     * `null` as well as absent, because importers write it. JSON has no
-     * `undefined`, so an item transformed from another format carries an explicit
-     * `passage: null` for "no passage" — the runtime has always tested for
-     * null, so it expected it while the type denied it. Excluding null
-     * only meant a host feeding real importer output through a typed path had to
-     * cast it away.
+     * `null` as well as absent, because importers write it: JSON has no
+     * `undefined`, so an item transformed from another format carries an
+     * explicit `passage: null` for "no passage", and the runtime tests for it.
      */
     passage?: string | PassageEntity | null;
     /** QTI/APIP-style accessibility catalogs owned by the item root. */
@@ -241,11 +241,9 @@ export interface TestPart {
  * The host-facing persistence snapshot for one section, returned by
  * `SectionControllerHandle.getSession()` and accepted by `applySession()`.
  *
- * Canonical here rather than in a player or the toolkit: the toolkit is
- * complementary to a player rather than an alternative to one and sits beneath
- * both entry paths, so a shape both need belongs alongside `AssessmentSection`.
- * The delivery slices it carries are defined in this package too, which is what
- * previously forced them to reference this shape in prose instead of types.
+ * Canonical here, beside `AssessmentSection`: both entry paths need it, and the
+ * toolkit complements a player and sits beneath both of them. The delivery
+ * slices it carries live in this package too, so they reference it as a type.
  */
 export interface SectionControllerSessionState {
     currentItemIndex?: number;
@@ -371,7 +369,7 @@ export interface MediaFragmentRange {
  * inside `qti-card-entry` — multiple sources, MIME types, poster, and an
  * optional time range.
  *
- * Note there is no `kind` discriminant: the card's `catalog` field is QTI's
+ * It carries no `kind` discriminant: the card's `catalog` field is QTI's
  * `qti-card@support` and is the only discriminator. Restating it here would
  * create a second source of truth that can disagree with the first.
  */
@@ -382,15 +380,12 @@ export interface SignLanguageCardPayload {
      * signed alternate is LSM, not ASL, so this must never be inferred from the
      * item or assessment content language.
      *
-     * Optional, and redundant when it equals the card's `language`. The card's
-     * `language` is QTI's `xml:lang` on the card entry and is the only field
-     * catalog resolution selects on — it decides *which* card is returned, before
-     * anything knows the card is a signing card. This one is read after
-     * resolution, to name the language in the region's accessible label and to
-     * refuse a card in a sign language the learner did not ask for. Author it only
-     * where the two genuinely differ, which is a card tagged with the item's
-     * content language (`language: "en-US"`, `signLang: "ase"`) so that resolution
-     * reaches it by the default-language rung.
+     * Optional: when absent, the card's `language` stands in, so author it only
+     * where the two differ. The sign-language tool reads every signing card in
+     * the owner's scope and selects on this value: a card in the requested sign
+     * language wins, a card naming no language is the fallback, and a card in
+     * another sign language is never shown. It also names the language in the
+     * region's accessible label.
      */
     signLang?: string;
     media: MediaAssetRef;
@@ -401,8 +396,7 @@ export interface SignLanguageCardPayload {
  *
  * QTI 3 treats recorded audio and synthesized speech as the *same* support:
  * both are `spoken`, and a card holds recorded audio through `qti-file-href`
- * plus a MIME type. So this is not a new accommodation, it is the other form the
- * existing one can take.
+ * plus a MIME type. A recording is the other form that accommodation takes.
  *
  * A node commonly carries both this and a `content` card in the same language —
  * APIP's pattern, which QTI's migration guidance keeps, because the script is
@@ -435,15 +429,13 @@ export type CatalogCardPayload = SignLanguageCardPayload | SpokenAudioCardPayloa
  * one of `content` or `payload`.
  *
  * One generic `payload` slot, not a field per accommodation. This is the shape
- * `pie-elements-ng` (PIE-879) and the `pie-api-aws` Learnosity importer
- * (PIE-881) restate structurally; all three read the same authored JSON and none
- * of them takes a package dependency on the others, so keeping the declarations
- * identical is the only thing holding interop together. It briefly was not:
- * those two producers wrote the signing payload under `signLanguage`, this
- * repo tolerated that as an input alias, and the alias was folded in on the
- * resolution path but not the enumeration path — so an imported card rendered
- * its signing video and simultaneously reported that the item had no signed
- * alternate. Both producers now emit `payload` and the alias is gone.
+ * `pie-elements-ng` and the PIE API service's Learnosity importer restate
+ * structurally; all three read the same authored JSON and none of them takes a
+ * package dependency on the others, so keeping the declarations identical is
+ * the only thing holding interop together; a `signLanguage` input alias, folded
+ * in on the resolution path but not the enumeration path, once had an imported
+ * card render its signing video while reporting no signed alternate. Both
+ * producers now emit `payload`.
  */
 export interface CatalogCard {
     catalog: string;
@@ -472,9 +464,25 @@ export interface AccessibilityCatalog {
     identifier: string;
     cards: CatalogCard[];
 }
+/**
+ * A learner's personal needs profile, in tool ids. An AfA PNP 3.0 record maps to
+ * it through the AfA adapter the packaged tool set exports.
+ */
 export interface PersonalNeedsProfile {
+    /** Tools the learner may turn on. */
     supports: string[];
+    /** Tools withheld from the learner; a prohibition outranks a support. */
     prohibitedSupports?: string[];
+    /**
+     * Tools granted as `supports` grants them and turned on when the learner's
+     * toolbar first shows them. A block withdraws them as it withdraws a support.
+     */
+    activateAtInit?: string[];
+    /**
+     * Parameters by tool id, the lowest layer: the assessment's and an item's
+     * `toolParameters` override them key by key.
+     */
+    toolParameters?: ToolParameters;
 }
 export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
     name?: string;
@@ -517,18 +525,46 @@ export interface AssessmentSettings {
         toolOverrides?: Record<string, boolean>;
     };
     /**
-     * Parameters by tool id, handed to a tool a grant or requirement admits;
-     * an item's `toolParameters` entry wins. Provider configuration belongs in
-     * the toolkit's `tools.providers`.
+     * Parameters by tool id, handed to the tool wherever policy shows it. They
+     * override the profile's `toolParameters` key by key, and an item's
+     * `toolParameters` override them on that item's own toolbar. Provider
+     * configuration belongs in the toolkit's `tools.providers`.
+     */
+    toolParameters?: ToolParameters;
+}
+/**
+ * Parameter shapes by tool id. A tool outside the stock set may add its own by
+ * declaration merging, with a type literal as the value.
+ *
+ * The values come from authored content, so a tool still checks what it reads.
+ */
+export interface ToolParameterMap {
+    calculator: {
+        type?: "basic" | "scientific" | "graphing";
+    };
+    answerEliminator: {
+        strategy?: "strikethrough" | "mask";
+    };
+    signLanguage: {
+        signLang?: string;
+    };
+    /**
+     * `rate` multiplies every playback speed, 1 being the provider's normal
+     * speed; `pitch` runs 0–2 with 1 normal; `volume` runs 0–1.
      */
-    toolConfigs?: {
-        calculator?: AssessmentCalculatorConfig;
-        [toolId: string]: Record<string, unknown> | undefined;
+    textToSpeech: {
+        rate?: number;
+        pitch?: number;
+        volume?: number;
     };
 }
-/** Calculator parameters in assessment settings. */
-export type AssessmentCalculatorConfig = {
-    type?: "basic" | "scientific" | "graphing";
+/** The parameter shape of tool `K`: its {@link ToolParameterMap} entry, else open. */
+export type ToolParametersFor<K extends string> = K extends keyof ToolParameterMap ? ToolParameterMap[K] : Record<string, unknown>;
+/** Parameters by tool id: typed for the ids {@link ToolParameterMap} names. */
+export type ToolParameters = {
+    [K in keyof ToolParameterMap]?: ToolParameterMap[K];
+} & {
+    [toolId: string]: Record<string, unknown> | undefined;
 };
 /**
  * Item-level settings for tool requirements.
@@ -537,8 +573,8 @@ export type AssessmentCalculatorConfig = {
 export interface ItemSettings {
     requiredTools?: string[];
     restrictedTools?: string[];
-    /** Parameters by tool id; outranks the assessment's `toolConfigs` entry. */
-    toolParameters?: Record<string, Record<string, unknown>>;
+    /** Parameters by tool id; override the assessment's key by key. */
+    toolParameters?: ToolParameters;
 }
 export type PlayerMode = "gather" | "view" | "evaluate" | "author";
 export type PlayerRole = "student" | "instructor";
@@ -636,8 +672,8 @@ export interface AdvancedItemConfig {
 }
 export type ItemConfig = PieContent | AdvancedItemConfig;
 /**
- * During the loading of elements from PIE bundles, we do a trick where we make
- * editor components available as web components by appending this to the element name.
+ * Appended to an element's tag name to register the bundle's editor component
+ * as a custom element of its own when PIE bundles load.
  */
 export declare const editorPostFix = "-pie-editor--";
 export type ModelUpdatedDetail = {

package/dist/types/index.js

@@ -1,6 +1,6 @@
 /**
- * During the loading of elements from PIE bundles, we do a trick where we make
- * editor components available as web components by appending this to the element name.
+ * Appended to an element's tag name to register the bundle's editor component
+ * as a custom element of its own when PIE bundles load.
  */
 export const editorPostFix = "-pie-editor--";
 export class ModelUpdatedEvent extends CustomEvent {

package/dist/ui/attribute-coercion.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Reads a boolean-like prop or attribute value. Nullish or blank reads as
+ * `defaultValue`; `false`, `0`, `off` and `no` (any case) read as false; any
+ * other value reads as true.
+ */
 export declare function coerceBooleanLike(value: boolean | string | null | undefined, defaultValue?: boolean): boolean;
 /**
  * Reads a boolean attribute value: present is true and absent is false, as in

package/dist/ui/attribute-coercion.js

@@ -1,3 +1,8 @@
+/**
+ * Reads a boolean-like prop or attribute value. Nullish or blank reads as
+ * `defaultValue`; `false`, `0`, `off` and `no` (any case) read as false; any
+ * other value reads as true.
+ */
 export function coerceBooleanLike(value, defaultValue = false) {
     if (typeof value === "boolean") {
         return value;
@@ -12,10 +17,7 @@ export function coerceBooleanLike(value, defaultValue = false) {
     if (["false", "0", "off", "no"].includes(normalizedValue)) {
         return false;
     }
-    if (["true", "1", "on", "yes"].includes(normalizedValue)) {
-        return true;
-    }
-    return Boolean(normalizedValue);
+    return true;
 }
 /**
  * Reads a boolean attribute value: present is true and absent is false, as in

package/dist/ui/content-styles.d.ts

@@ -9,11 +9,9 @@
  * light DOM, so those rules have to exist as a document-level stylesheet —
  * there is no shadow root to scope them to.
  *
- * Hosts used to be required to import that stylesheet themselves. Nothing
- * enforced it and nothing failed loudly when they didn't: the item rendered,
- * the passage was simply unstyled, and it surfaced as a visual bug reported by
- * hand days later. Players install the stylesheet themselves instead, which
- * keeps the host contract at "import the player".
+ * Players install that stylesheet themselves, which keeps the host contract at
+ * "import the player"; a host-side import was unenforced and failed silently,
+ * as an unstyled passage.
  *
  * The CSS text is passed in rather than imported here: this package builds with
  * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages
@@ -58,11 +56,9 @@ export declare function contentStylesPresent(): boolean;
  * hand — first in the entry, before app CSS — so an app rule and a content rule
  * of equal specificity resolve in the host's favour, exactly as before.
  *
- * A cascade layer looks tempting here and is the wrong tool: unlayered author
- * declarations beat *all* layered ones regardless of specificity, so a host
- * reset as broad as `p { margin: 0 }` would silently outrank
- * `.numbered-paragraph { margin-left: 36px }`. That trades a visible missing
- * stylesheet for a subtler override bug, so ordinary specificity wins instead.
+ * A cascade layer would invert that: unlayered author declarations beat *all*
+ * layered ones regardless of specificity, so a host reset as broad as
+ * `p { margin: 0 }` would outrank `.numbered-paragraph { margin-left: 36px }`.
  *
  * @param cssText Contents of `@pie-players/pie-theme/components.css`.
  * @param source Package installing the styles, for diagnostics.

package/dist/ui/content-styles.js

@@ -9,11 +9,9 @@
  * light DOM, so those rules have to exist as a document-level stylesheet —
  * there is no shadow root to scope them to.
  *
- * Hosts used to be required to import that stylesheet themselves. Nothing
- * enforced it and nothing failed loudly when they didn't: the item rendered,
- * the passage was simply unstyled, and it surfaced as a visual bug reported by
- * hand days later. Players install the stylesheet themselves instead, which
- * keeps the host contract at "import the player".
+ * Players install that stylesheet themselves, which keeps the host contract at
+ * "import the player"; a host-side import was unenforced and failed silently,
+ * as an unstyled passage.
  *
  * The CSS text is passed in rather than imported here: this package builds with
  * plain `tsc`, so it cannot inline a stylesheet. Bundler-built player packages
@@ -48,9 +46,8 @@ const declaresContentStylesSentinel = (rule) => {
     // Grouping rules hold no declarations of their own, so the sentinel sits one
     // or more levels down. A host that confines its copy — `@scope
     // (.item-content) { … }`, `@layer pie-content { … }` — presents exactly one
-    // top-level rule with an empty `.style`, and a top-level-only scan reads that
-    // as "no copy here". That made both detection paths blind to the one host
-    // configuration this module most needs to recognise.
+    // top-level rule with an empty `.style`, which a top-level-only scan reads
+    // as "no copy here".
     const nested = rule.cssRules;
     if (!nested)
         return false;
@@ -115,11 +112,9 @@ export function contentStylesPresent() {
  * hand — first in the entry, before app CSS — so an app rule and a content rule
  * of equal specificity resolve in the host's favour, exactly as before.
  *
- * A cascade layer looks tempting here and is the wrong tool: unlayered author
- * declarations beat *all* layered ones regardless of specificity, so a host
- * reset as broad as `p { margin: 0 }` would silently outrank
- * `.numbered-paragraph { margin-left: 36px }`. That trades a visible missing
- * stylesheet for a subtler override bug, so ordinary specificity wins instead.
+ * A cascade layer would invert that: unlayered author declarations beat *all*
+ * layered ones regardless of specificity, so a host reset as broad as
+ * `p { margin: 0 }` would outrank `.numbered-paragraph { margin-left: 36px }`.
  *
  * @param cssText Contents of `@pie-players/pie-theme/components.css`.
  * @param source Package installing the styles, for diagnostics.

package/dist/ui/first-focusable.d.ts

@@ -1,6 +1,5 @@
 /**
  * Selector for elements that are commonly keyboard-focusable in assessment UI.
- * Kept in sync with `focus-trap.ts` for consistent tab-order surfaces.
  */
 export declare const FOCUSABLE_SELECTOR: string;
 /**

package/dist/ui/first-focusable.js

@@ -1,6 +1,5 @@
 /**
  * Selector for elements that are commonly keyboard-focusable in assessment UI.
- * Kept in sync with `focus-trap.ts` for consistent tab-order surfaces.
  */
 export const FOCUSABLE_SELECTOR = [
     "a[href]",

package/dist/ui/focus-trap.js

@@ -57,9 +57,8 @@ export function createFocusTrap(container, options = {}) {
             container.focus?.();
             return;
         }
-        const current = getDeepActiveElement(container.getRootNode() instanceof ShadowRoot
-            ? container.getRootNode()
-            : document);
+        const rootNode = container.getRootNode();
+        const current = getDeepActiveElement(rootNode instanceof ShadowRoot ? rootNode : document);
         const currentIndex = focusable.indexOf(current || focusable[0]);
         if (event.shiftKey) {
             if (currentIndex <= 0) {