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

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/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;
@@ -517,18 +509,36 @@ 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; an
+     * item's `toolParameters` entry wins on that item's own toolbar. Provider
+     * configuration belongs in the toolkit's `tools.providers`.
      */
-    toolConfigs?: {
-        calculator?: AssessmentCalculatorConfig;
-        [toolId: string]: Record<string, unknown> | undefined;
+    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;
     };
 }
-/** 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 +547,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; outranks the assessment's `toolParameters` entry. */
+    toolParameters?: ToolParameters;
 }
 export type PlayerMode = "gather" | "view" | "evaluate" | "author";
 export type PlayerRole = "student" | "instructor";
@@ -636,8 +646,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) {

package/dist/ui/scope-css.d.ts

@@ -4,37 +4,34 @@
  * external-style-urls="...">` or `itemConfig.resources.stylesheets[*].url`
  * styles that player's subtree instead of the whole host document.
  *
- * This replaces a single-regex implementation that prefixed every
- * selector-like fragment. That is correct for flat selector rules and wrong for
- * everything else: `@media screen { ... }` became
- * `.scope @media screen { ... }`, an invalid selector, so the browser dropped
- * the whole block and every rule inside it; `@font-face` and `@keyframes` were
- * corrupted the same way; and `:root` became `.scope :root`, which can never
- * match, because `:root` is `<html>` and is not a descendant of the player.
- * At-rules and `:root` custom properties therefore never applied at all.
+ * Walks the stylesheet brace-by-brace. Block at-rules that hold rules
+ * (`@media`, `@supports`, `@container`, `@layer`, `@scope`) keep their prelude
+ * and have their inner rules scoped, every other at-rule passes through, and a
+ * leading `:root`, `html` or `body` is replaced by the scope, since
+ * `.scope :root` can never match: `:root` is `<html>`, which is no descendant
+ * of the player. A regex prefixer fails on exactly these cases: it turned
+ * `@media screen { … }` into the invalid `.scope @media screen { … }`, which the
+ * browser drops with every rule inside, and corrupted `@font-face`,
+ * `@keyframes` and `:root` the same way.
  *
- * The QTI player's `scopeCssRules` (`pie-qti` -
- * `packages/item-player/src/components/utils/stylesheetRender.ts`) is not a
- * drop-in either. Its `:root` handling is the behaviour we want and is adopted
- * here, but it excludes `@` from its selector pattern rather than understanding
- * at-rules, so `@media` and `@supports` lose their condition and their inner
- * rules are hoisted and applied unconditionally — a mobile-only rule then
- * applies at every viewport width, which is a subtler failure than dropping it.
+ * The `:root` handling follows the QTI player's `scopeCssRules` (`pie-qti` -
+ * `packages/item-player/src/components/utils/stylesheetRender.ts`), which is no
+ * drop-in: it excludes `@` from its selector pattern without understanding
+ * at-rules, so `@media` and `@supports` lose their condition and their rules
+ * apply at every viewport width.
  *
- * So this walks the stylesheet brace-by-brace instead of pattern-matching it.
- * A real CSS parser would be the textbook answer and is deliberately not used:
- * `@pie-players/pie-item-player` ships with two workspace dependencies, this
- * runs in the delivery path, and scoping needs to know about rule boundaries
- * only — not about property grammar.
+ * No CSS parser: `@pie-players/pie-item-player` ships with two workspace
+ * dependencies, this runs in the delivery path, and scoping needs rule
+ * boundaries only.
  *
- * Known limits, all preserving existing behaviour rather than adding policy:
+ * Known limits:
  *
- * - `@import` is passed through untouched, exactly as the old regex left it. It
- *   pulls in an unscoped stylesheet, so it defeats scoping, but blocking it is
- *   a security policy decision and not this function's job. Callers gate
- *   stylesheet URLs with `validateExternalStyleUrl` before fetching.
+ * - `@import` is passed through untouched. It pulls in an unscoped stylesheet,
+ *   so it defeats scoping, but blocking it is a security policy decision and
+ *   not this function's job. Callers gate stylesheet URLs with
+ *   `validateExternalStyleUrl` before fetching.
  * - Declaration blocks are emitted verbatim, so `url(...)` references are left
- *   as authored and resolve against the stylesheet's own URL as before.
+ *   as authored and resolve against the stylesheet's own URL.
  * - A style rule's block is never rewritten, which is also what native CSS
  *   nesting needs: nested selectors are relative to a parent that has already
  *   been scoped.