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

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. */
@@ -92,6 +92,23 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     configuration?: any;
     highlights?: Record<string, string[]>;
 }
+/**
+ * `baseId` and `version` are optional on an entity a section references. They
+ * identify a stored version, which a host building a section from an item
+ * config does not have, and no player reads either.
+ */
+type WithOptionalVersion<T extends VersionEntity> = Omit<T, "baseId" | "version"> & Partial<Pick<VersionEntity, "baseId" | "version">>;
+/**
+ * A passage as a section's item references it. `name` is optional on the same
+ * ground: the section player reads it only as a fallback for a missing `id`.
+ */
+export type ReferencedPassageEntity = Omit<WithOptionalVersion<PassageEntity>, "name"> & {
+    name?: string;
+};
+/** An item as `AssessmentItemRef.item` references it. */
+export type ReferencedItemEntity = Omit<WithOptionalVersion<ItemEntity>, "passage"> & {
+    passage?: string | ReferencedPassageEntity | null;
+};
 /**
  * Metadata specifically for interpretation by clients, typically containing
  * options that are relevant for the user interface. This is not indexed for search.
@@ -146,7 +163,7 @@ export interface AssessmentItemRef extends SearchMetaDataEntity {
      * Resolved item entity with PIE config.
      * This is populated by the client before passing to the player.
      */
-    item?: ItemEntity;
+    item?: ReferencedItemEntity;
     /** Item-level settings for tool requirements and customization */
     settings?: ItemSettings;
     /**
@@ -182,14 +199,6 @@ export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDat
      */
     assessmentItemRefs?: AssessmentItemRef[];
     rubricBlocks?: RubricBlock[];
-    /**
-     * QTI 3.0: Personal Needs Profile (PNP 3.0) for section-scoped delivery.
-     *
-     * Section players read this (falling back to `settings.personalNeedsProfile`,
-     * then to the computed default profile) to drive PNP policy when a section is
-     * delivered without an enclosing assessment.
-     */
-    personalNeedsProfile?: PersonalNeedsProfile;
     /**
      * Formative delivery policy for this section: how many Tries a learner gets
      * on each item, when feedback is revealed, and whether the behavior is on at
@@ -232,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;
@@ -362,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.
  */
@@ -373,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;
@@ -392,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
@@ -426,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;
@@ -466,15 +467,7 @@ export interface AccessibilityCatalog {
 export interface PersonalNeedsProfile {
     supports: string[];
     prohibitedSupports?: string[];
-    activateAtInit?: string[];
 }
-/**
- * QTI 3.0: Reference to a shared stimulus (passage).
- * Maps to qti-assessment-stimulus-ref element.
- *
- * NOTE: Not currently used. We embed PassageEntity directly in RubricBlock instead.
- * Kept for potential future use if we need to support external stimulus references.
- */
 export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
     name?: string;
     title?: string;
@@ -494,117 +487,59 @@ export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
      * QTI 3.0: testParts structure (authoritative for QTI format).
      */
     testParts?: TestPart[];
-    /** QTI 3.0: Stimulus material references (Phase 3 - placeholder) */
-    stimulusRefs?: any[];
 }
 /**
- * Enhanced settings structure for assessment configuration.
- * Provides structured fields for district policies, test administration,
- * tool configurations, and theme settings while remaining extensible.
+ * Assessment settings the tool policy reads: district policy, test
+ * administration and per-tool parameters.
  */
 export interface AssessmentSettings {
     /** District/organization policies */
     districtPolicy?: {
         blockedTools?: string[];
         requiredTools?: string[];
-        policies?: Record<string, any>;
     };
     /** Test administration configuration */
     testAdministration?: {
-        mode?: "practice" | "test" | "benchmark";
-        toolOverrides?: Record<string, boolean>;
-        startDate?: string;
-        endDate?: string;
-    };
-    /** Tool-specific provider configurations */
-    toolConfigs?: {
-        calculator?: AssessmentCalculatorConfig;
         /**
-         * Text-to-speech configuration.
-         *
-         * Standard parameters (voice, rate, pitch) are portable across providers
-         * and follow W3C Web Speech API specifications.
-         *
-         * Provider-specific extensions should be placed in providerOptions.
-         *
-         * @see https://w3c.github.io/speech-api/
+         * Per-session override by tool id. `false` withdraws the tool and
+         * outranks every policy level except a district block. `true` grants it
+         * below a district block, an item's `restrictedTools` and the profile's
+         * `prohibitedSupports`, and above requirements and profile supports.
          */
-        textToSpeech?: {
-            /**
-             * TTS provider
-             *
-             * @standard "browser" uses W3C Web Speech API
-             * @extension "polly" and "custom" are provider-specific
-             */
-            provider?: "browser" | "polly" | "custom";
-            /**
-             * Voice identifier (provider-specific names)
-             *
-             * @standard W3C Web Speech API (concept)
-             * @example "Joanna" (Polly), "en-US-Standard-A" (Google), browser voices
-             */
-            voice?: string;
-            /**
-             * Speech rate (speed multiplier)
-             *
-             * @standard W3C Web Speech API
-             * @range 0.25 to 4.0
-             * @default 1.0
-             */
-            rate?: number;
-            /**
-             * Pitch adjustment
-             *
-             * @standard W3C Web Speech API
-             * @range 0 to 2 (as multiplier)
-             * @default 1.0
-             */
-            pitch?: number;
-            /**
-             * Speech Rule Engine options for generated MathML speech.
-             *
-             * `style` is passed to SRE directly; ClearSpeak combines multiple
-             * preferences with ":" (for example,
-             * "ImpliedTimes_MoreImpliedTimes:Paren_Silent").
-             *
-             * Mirrors assessment-toolkit's SREMathSpeechOptions without importing
-             * toolkit service types into the shared content contract package.
-             */
-            mathSpeech?: {
-                domain?: string;
-                style?: string;
-                engineOptions?: Record<string, unknown>;
-            };
-            /**
-             * Provider-specific options (extensions)
-             *
-             * @extension Not portable across providers
-             * @example For AWS Polly: { engine: "neural", region: "us-east-1" }
-             * @example For Google Cloud: { audioEncoding: "MP3", effectsProfileId: ["headphone-class-device"] }
-             */
-            providerOptions?: Record<string, any>;
-        };
-        [toolId: string]: any;
-    };
-    /** Theme configuration (not in PNP) */
-    themeConfig?: {
-        scheme?: "default" | "high-contrast" | "dark";
-        fontSize?: number;
-        fontFamily?: string;
-        lineHeight?: number;
-        reducedMotion?: boolean;
+        toolOverrides?: Record<string, boolean>;
     };
-    /** Product-specific extensions */
-    [key: string]: any;
+    /**
+     * 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`.
+     */
+    toolParameters?: ToolParameters;
 }
 /**
- * Calculator options exposed through assessment settings.
- * The engine is implicit (Desmos).
+ * 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 AssessmentCalculatorConfig {
-    type?: "basic" | "scientific" | "graphing";
-    [key: string]: any;
+export interface ToolParameterMap {
+    calculator: {
+        type?: "basic" | "scientific" | "graphing";
+    };
+    answerEliminator: {
+        strategy?: "strikethrough" | "mask";
+    };
+    signLanguage: {
+        signLang?: string;
+    };
 }
+/** 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.
  * Used in AssessmentItemRef.settings to specify item-specific tool needs.
@@ -612,8 +547,8 @@ export interface AssessmentCalculatorConfig {
 export interface ItemSettings {
     requiredTools?: string[];
     restrictedTools?: string[];
-    toolParameters?: Record<string, any>;
-    [key: string]: any;
+    /** Parameters by tool id; outranks the assessment's `toolParameters` entry. */
+    toolParameters?: ToolParameters;
 }
 export type PlayerMode = "gather" | "view" | "evaluate" | "author";
 export type PlayerRole = "student" | "instructor";
@@ -711,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.