@pie-players/pie-players-shared 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/types/index.d.ts

@@ -10,8 +10,10 @@
  */
 import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
 import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
+import type { AdaptationLink, CurriculumStandard, LanguagePolicy, SkillLevel } from "./interchange.js";
 export type { FormativeDeliveryPolicy, FormativeItemPolicy };
 export type { TimedMediaSectionData };
+export type { AdaptationLink, ContentSubstitution, CurriculumStandard, LanguagePolicy, ServedContentIdentity, SkillLevel, } from "./interchange.js";
 export interface BaseEntity {
     id?: string;
     createdAt?: Date;
@@ -32,12 +34,6 @@ export interface VersionEntity extends BaseEntity {
     signature?: string;
     version: SemVer;
 }
-export interface SearchMetaData {
-    [key: string]: any;
-}
-export interface SearchMetaDataEntity extends BaseEntity {
-    searchMetaData?: SearchMetaData;
-}
 export interface ConfigElements {
     [key: string]: string;
 }
@@ -69,16 +65,36 @@ export interface ConfigEntity {
 export interface ConfigContainerEntity extends BaseEntity {
     config: ConfigEntity;
 }
-export interface PassageEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
+export interface PassageEntity extends VersionEntity, ConfigContainerEntity {
     name: string;
+    /**
+     * BCP 47 tag of the content's language (QTI `xml:lang`). The players render
+     * and score it under this language; absent, the section's `env.locale` holds.
+     */
+    language?: string;
+    /** The source a translated version was adapted from. No player reads it. */
+    isAdaptationOf?: AdaptationLink;
     /** QTI/APIP-style accessibility catalogs owned by this passage content. */
     accessibilityCatalogs?: AccessibilityCatalog[];
+    /**
+     * Standards and skills the content is aligned to. Absent means no data; `[]`
+     * means the writer states that none applies. No player reads it.
+     */
+    curriculumStandards?: CurriculumStandard[];
+    /** DOK and Bloom's classifications, on the same terms. No player reads it. */
+    skillLevels?: SkillLevel[];
     retired?: boolean;
     published?: boolean;
-    highlights?: Record<string, string[]>;
 }
-export interface ItemEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
+export interface ItemEntity extends VersionEntity, ConfigContainerEntity {
     name?: string;
+    /**
+     * BCP 47 tag of the content's language (QTI `xml:lang`). The players render
+     * and score it under this language; absent, the section's `env.locale` holds.
+     */
+    language?: string;
+    /** The source a translated version was adapted from. No player reads it. */
+    isAdaptationOf?: AdaptationLink;
     /**
      * `null` as well as absent, because importers write it: JSON has no
      * `undefined`, so an item transformed from another format carries an
@@ -87,10 +103,16 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     passage?: string | PassageEntity | null;
     /** QTI/APIP-style accessibility catalogs owned by the item root. */
     accessibilityCatalogs?: AccessibilityCatalog[];
+    /**
+     * Standards and skills the content is aligned to. Absent means no data; `[]`
+     * means the writer states that none applies. No player reads it.
+     */
+    curriculumStandards?: CurriculumStandard[];
+    /** DOK and Bloom's classifications, on the same terms. No player reads it. */
+    skillLevels?: SkillLevel[];
     retired?: boolean;
     published?: boolean;
     configuration?: any;
-    highlights?: Record<string, string[]>;
 }
 /**
  * `baseId` and `version` are optional on an entity a section references. They
@@ -109,20 +131,6 @@ export type ReferencedPassageEntity = Omit<WithOptionalVersion<PassageEntity>, "
 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.
- */
-export interface SettingsMetaData {
-    [key: string]: any;
-}
-/**
- * Objects that contain metadata in the settings property, which is NOT indexed for search
- * but typically only relevant for particular client cases.
- */
-export interface SettingsMetaDataEntity {
-    settings?: SettingsMetaData;
-}
 export type RubricBlockView = "author" | "candidate" | "proctor" | "scorer" | "testConstructor" | "tutor";
 export interface RubricBlock {
     identifier?: string;
@@ -150,7 +158,7 @@ export interface RubricBlock {
  * References an item within a section. The item property contains the resolved
  * ItemEntity with its PIE config.
  */
-export interface AssessmentItemRef extends SearchMetaDataEntity {
+export interface AssessmentItemRef extends BaseEntity {
     id?: string;
     identifier: string;
     title?: string;
@@ -175,7 +183,7 @@ export interface AssessmentItemRef extends SearchMetaDataEntity {
      */
     formative?: FormativeItemPolicy;
 }
-export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDataEntity {
+export interface AssessmentSection extends BaseEntity {
     id?: string;
     identifier: string;
     title?: string;
@@ -484,7 +492,7 @@ export interface PersonalNeedsProfile {
      */
     toolParameters?: ToolParameters;
 }
-export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
+export interface AssessmentEntity extends BaseEntity {
     name?: string;
     title?: string;
     identifier?: string;
@@ -499,6 +507,11 @@ export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
     accessibilityCatalogs?: AccessibilityCatalog[];
     /** QTI 3.0: Personal Needs Profile (PNP 3.0) */
     personalNeedsProfile?: PersonalNeedsProfile;
+    /**
+     * The languages the assessment is offered in, read by a backend that
+     * resolves language variants. No player reads it.
+     */
+    languagePolicy?: LanguagePolicy;
     /**
      * QTI 3.0: testParts structure (authoritative for QTI format).
      */
@@ -548,6 +561,13 @@ export interface ToolParameterMap {
     signLanguage: {
         signLang?: string;
     };
+    /**
+     * `language` is the BCP 47 content language the learner reads items in. A
+     * host passes it to delivery as `requestedLanguages`.
+     */
+    itemTranslation: {
+        language?: string;
+    };
     /**
      * `rate` multiplies every playback speed, 1 being the provider's normal
      * speed; `pitch` runs 0–2 with 1 normal; `volume` runs 0–1.

package/dist/types/interchange.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Interchange types: backends and authoring tools exchange them, and no player
+ * reads them. Their tier is listed on the content-model page.
+ *
+ * Language variants (PIE-1393): no player reads `AdaptationLink` or
+ * `LanguagePolicy`.
+ * A language variant is its own item or passage version that declares
+ * `language` and, when it is a translation, `isAdaptationOf`. Its family is
+ * `isAdaptationOf.baseId ?? baseId`.
+ */
+import type { SemVer } from "./index.js";
+/** The source a translated item or passage was adapted from. */
+export interface AdaptationLink {
+    baseId: string;
+    /** The source version translated. Absent when provenance is unknown. */
+    version?: SemVer;
+}
+/**
+ * The languages an assessment offers and what a backend serves when a family
+ * has no variant in the requested language.
+ */
+export interface LanguagePolicy {
+    /** BCP 47 tags the assessment may be served in. */
+    languages: string[];
+    /**
+     * `"default"` serves an item whose family lacks the requested language in
+     * the closest match for the platform default, `en-US` (so `en` or `en-GB`),
+     * then its content that declares no language, then its source. Fallback is
+     * per item; items sharing a passage fall back together. `"none"` fails the
+     * load.
+     */
+    fallback: "default" | "none";
+    /**
+     * `"closest"`, the default, serves the nearest variant in the requested
+     * language, so `es-MX` reaches `es` or `es-ES`; `"exact"` serves only an
+     * equal tag and leaves anything else to `fallback`.
+     */
+    matching?: "closest" | "exact";
+    /**
+     * `"serve"` serves a variant whose source has a newer release and records
+     * it as stale; `"require-current"` treats that variant as missing.
+     */
+    staleness: "serve" | "require-current";
+}
+/**
+ * Why the served content differs from what was requested: `"fallback"`, not
+ * in a requested language; `"variety"`, in another variety of a requested
+ * language, such as `es-ES` for `es-MX`; `"stale"`, a translation of an older
+ * source release.
+ */
+export type ContentSubstitution = "fallback" | "stale" | "variety";
+/** The content version a backend served, and the language it served it in. */
+export interface ServedContentIdentity {
+    baseId: string;
+    version?: SemVer;
+    /** The family key, when the served version belongs to a variant family. */
+    family?: string;
+    /** BCP 47 tag of the served content. */
+    servedLanguage?: string;
+    substitution?: ContentSubstitution;
+}
+/**
+ * One curriculum standard, skill or competency the content is aligned to
+ * (PIE-1381). QTI 3 Curriculum Standards Metadata (CSM 1.1), one entry per
+ * `labelledGUID`. Content records direct links only; a framework provider
+ * resolves parents, crosswalks and successors on read.
+ */
+export interface CurriculumStandard {
+    /**
+     * CSM `curriculumStandardsMetadata@providerId`: who issued `guid`, from the
+     * provider-id registry on the content-model page, or a host value. Absent
+     * means `"AB"` (Academic Benchmarks).
+     */
+    providerId?: string;
+    /**
+     * CSM `labelledGUID/GUID`, as the provider issued it. Stored with its case
+     * and compared case-insensitively.
+     */
+    guid: string;
+    /** CSM `labelledGUID/caseItemURI`, for a CASE framework item. */
+    caseItemURI?: string;
+    /** CSM `labelledGUID/label`: a display code. Never a key. */
+    label?: string;
+    /** LOM classification purpose. Absent means `"educational objective"`. */
+    purpose?: "educational objective" | "prerequisite" | (string & {});
+    /** The record's main standard for this provider. At most one per `providerId`. */
+    primary?: boolean;
+    /** How the link was made. */
+    provenance?: "authored" | "derived" | "imported";
+    /**
+     * For a derived link: the link it was generated from. An absent
+     * `providerId` means `"AB"`.
+     */
+    derivedFrom?: {
+        providerId?: string;
+        guid: string;
+    };
+}
+/**
+ * A cognitive-complexity classification of the content (PIE-1381). LOM
+ * classification purpose "skill level".
+ */
+export interface SkillLevel {
+    /**
+     * LOM `taxonPath/source`: `"webb-dok"`, `"blooms-revised"`,
+     * `"blooms-original"`, or a host taxonomy.
+     */
+    source: string;
+    /**
+     * LOM `taxon/id`: `"1"` to `"4"` for `webb-dok`; `"remember"` to `"create"`
+     * for `blooms-revised`.
+     */
+    id: string;
+    /** PIE extension: the author's justification. */
+    rationale?: string;
+}

package/dist/types/interchange.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/focus-trap.js

@@ -1,4 +1,5 @@
 import { collectFocusable } from "./first-focusable.js";
+import { isComposingKeyEvent } from "./ime.js";
 /**
  * Shadow-aware: a trapped panel almost always hosts a custom element rendering into
  * `shadow: "open"`, and a flat `querySelectorAll` would collect only the panel's own
@@ -44,7 +45,8 @@ export function createFocusTrap(container, options = {}) {
     const wrap = options.wrap ?? true;
     const onKeydown = (event) => {
         if (event.key === "Escape") {
-            if (!options.onEscape)
+            // An Escape that cancels an IME composition belongs to the IME.
+            if (!options.onEscape || isComposingKeyEvent(event))
                 return;
             // Claimed, so a page-wide Escape listener does not also act on it.
             event.preventDefault();

package/dist/ui/fontawesome.d.ts

@@ -0,0 +1,51 @@
+/**
+ * FontAwesome for `<nds-icon-button>`, which renders its glyph as
+ * `<i class="fa-light fa-${name}">` and ships no font of its own.
+ *
+ * FontAwesome comes from the host page when it links any FA stylesheet.
+ * Otherwise `ensureFontAwesome` adds FA Free from the ESM CDN the item player's
+ * `loaderOptions` name, jsDelivr by default. Pro is never fetched from here:
+ * ui.renaissance.com serves its font files to Renaissance origins only, so a
+ * host that licenses it links it itself, as section-demos does through its dev
+ * proxy.
+ *
+ * `fa-light` is a weight only Pro carries. Free has no `.fa-light` rule and its
+ * Regular font lacks most toolbar glyphs, so without Pro `applyNdsGlyphVariant`
+ * renders every glyph in Solid, the one Free weight that has them all.
+ *
+ * Roboto comes from the vendored button: its connectedCallback links
+ * ui.renaissance.com's Roboto unless the page links a stylesheet whose URL
+ * contains `Roboto`.
+ */
+export type NdsGlyphVariant = "fa-light" | "fa-regular" | "fa-solid";
+/**
+ * Adds FA Free to `<head>` unless the page already links a FontAwesome
+ * stylesheet. Appending Free after a host's Pro would override Pro's
+ * `.fa-regular` / `.fa-solid` font-family rules page-wide.
+ *
+ * A stylesheet that fails to load stays in `<head>` marked
+ * `data-pie-load-failed`: no later call requests it again, and no shadow root
+ * copies it.
+ */
+export declare function ensureFontAwesome(loaderOptions: {
+    esmCdnUrl?: unknown;
+    esmCdnProvider?: unknown;
+} | null | undefined): void;
+/**
+ * Copies the page's FontAwesome `<link>`s into the shadow root `node` renders
+ * in, since `<head>` stylesheets do not cross a shadow boundary. Does nothing
+ * when `node` is in the document tree, and runs once per shadow root.
+ *
+ * A stylesheet still loading is copied once it loads, so the copy comes from
+ * the cache; one that fails is not copied, since every copy would request it
+ * again. Chromium gives a link a `sheet` even when its load fails, so a failed
+ * one is known by its mark.
+ */
+export declare function installFontAwesomeInShadow(node: Node): void;
+/**
+ * Renders the `fa-light` glyphs inside `button` in `preferred` when the page
+ * links Pro, and in Solid otherwise. Re-applies whenever Lit renders or
+ * rewrites the icon's class; the class edit removes `fa-light`, so the
+ * callback it triggers is a no-op. Returns the observer's disconnect.
+ */
+export declare function applyNdsGlyphVariant(button: HTMLElement, preferred: NdsGlyphVariant): () => void;

package/dist/ui/fontawesome.js

@@ -0,0 +1,122 @@
+/**
+ * FontAwesome for `<nds-icon-button>`, which renders its glyph as
+ * `<i class="fa-light fa-${name}">` and ships no font of its own.
+ *
+ * FontAwesome comes from the host page when it links any FA stylesheet.
+ * Otherwise `ensureFontAwesome` adds FA Free from the ESM CDN the item player's
+ * `loaderOptions` name, jsDelivr by default. Pro is never fetched from here:
+ * ui.renaissance.com serves its font files to Renaissance origins only, so a
+ * host that licenses it links it itself, as section-demos does through its dev
+ * proxy.
+ *
+ * `fa-light` is a weight only Pro carries. Free has no `.fa-light` rule and its
+ * Regular font lacks most toolbar glyphs, so without Pro `applyNdsGlyphVariant`
+ * renders every glyph in Solid, the one Free weight that has them all.
+ *
+ * Roboto comes from the vendored button: its connectedCallback links
+ * ui.renaissance.com's Roboto unless the page links a stylesheet whose URL
+ * contains `Roboto`.
+ */
+import { resolveEsmPackageFileUrl } from "../loaders/esm-adapter.js";
+/** The one FA Free build the players add; `<package>@<version>/<path>`. */
+const FONTAWESOME_FREE_FILE = "@fortawesome/fontawesome-free@6.5.2/css/all.min.css";
+// Matches any FA stylesheet the host page links: `fontawesome.min.css`,
+// `font-awesome.css`, a `/_fa-pro/` proxy, `fontawesome-free@…`.
+const FA_HREF_PATTERN = /font.?awesome|fa-?pro/i;
+const FA_FREE_HREF_PATTERN = /fontawesome-free/i;
+const documentStylesheetLinks = () => Array.from(document.querySelectorAll('link[rel="stylesheet"][href]'));
+const documentFontAwesomeLinks = () => documentStylesheetLinks().filter((link) => FA_HREF_PATTERN.test(link.href));
+/** Whether the page links a FontAwesome build other than Free. */
+const pageLinksFontAwesomePro = () => documentFontAwesomeLinks().some((link) => !FA_FREE_HREF_PATTERN.test(link.href));
+/**
+ * Adds FA Free to `<head>` unless the page already links a FontAwesome
+ * stylesheet. Appending Free after a host's Pro would override Pro's
+ * `.fa-regular` / `.fa-solid` font-family rules page-wide.
+ *
+ * A stylesheet that fails to load stays in `<head>` marked
+ * `data-pie-load-failed`: no later call requests it again, and no shadow root
+ * copies it.
+ */
+export function ensureFontAwesome(loaderOptions) {
+    if (typeof document === "undefined")
+        return;
+    if (documentFontAwesomeLinks().length > 0)
+        return;
+    const href = resolveEsmPackageFileUrl(loaderOptions, FONTAWESOME_FREE_FILE);
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    link.addEventListener("error", () => {
+        link.dataset.pieLoadFailed = "";
+    }, { once: true });
+    document.head.appendChild(link);
+}
+const mirroredShadowRoots = new WeakSet();
+/**
+ * Copies the page's FontAwesome `<link>`s into the shadow root `node` renders
+ * in, since `<head>` stylesheets do not cross a shadow boundary. Does nothing
+ * when `node` is in the document tree, and runs once per shadow root.
+ *
+ * A stylesheet still loading is copied once it loads, so the copy comes from
+ * the cache; one that fails is not copied, since every copy would request it
+ * again. Chromium gives a link a `sheet` even when its load fails, so a failed
+ * one is known by its mark.
+ */
+export function installFontAwesomeInShadow(node) {
+    const shadow = node.getRootNode();
+    if (!(shadow instanceof ShadowRoot) || mirroredShadowRoots.has(shadow)) {
+        return;
+    }
+    mirroredShadowRoots.add(shadow);
+    const appendLink = (href) => {
+        const present = Array.from(shadow.querySelectorAll('link[rel="stylesheet"]')).some((link) => link.href === href);
+        if (!href || present)
+            return;
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = href;
+        shadow.appendChild(link);
+    };
+    for (const link of documentFontAwesomeLinks()) {
+        if ("pieLoadFailed" in link.dataset)
+            continue;
+        if (link.sheet) {
+            appendLink(link.href);
+            continue;
+        }
+        const settle = (event) => {
+            link.removeEventListener("load", settle);
+            link.removeEventListener("error", settle);
+            if (event.type === "load")
+                appendLink(link.href);
+        };
+        link.addEventListener("load", settle);
+        link.addEventListener("error", settle);
+    }
+}
+/**
+ * Renders the `fa-light` glyphs inside `button` in `preferred` when the page
+ * links Pro, and in Solid otherwise. Re-applies whenever Lit renders or
+ * rewrites the icon's class; the class edit removes `fa-light`, so the
+ * callback it triggers is a no-op. Returns the observer's disconnect.
+ */
+export function applyNdsGlyphVariant(button, preferred) {
+    const variant = pageLinksFontAwesomePro() ? preferred : "fa-solid";
+    if (variant === "fa-light")
+        return () => { };
+    const apply = () => {
+        for (const icon of button.querySelectorAll("i.fa-light")) {
+            icon.classList.remove("fa-light");
+            icon.classList.add(variant);
+        }
+    };
+    apply();
+    const observer = new MutationObserver(apply);
+    observer.observe(button, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["class"],
+    });
+    return () => observer.disconnect();
+}

package/dist/ui/ime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a keydown belongs to an IME composition, so it must not act as a
+ * shortcut. Safari reports `isComposing` false on the Enter that commits a
+ * composition and marks it only with `keyCode` 229.
+ */
+export declare function isComposingKeyEvent(event: Pick<KeyboardEvent, "isComposing" | "keyCode">): boolean;

package/dist/ui/ime.js

@@ -0,0 +1,10 @@
+/** The legacy `keyCode` a browser reports for a keydown the IME consumes. */
+const IME_PROCESS_KEY_CODE = 229;
+/**
+ * Whether a keydown belongs to an IME composition, so it must not act as a
+ * shortcut. Safari reports `isComposing` false on the Enter that commits a
+ * composition and marks it only with `keyCode` 229.
+ */
+export function isComposingKeyEvent(event) {
+    return event.isComposing || event.keyCode === IME_PROCESS_KEY_CODE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.6",
+	"version": "1.0.0-beta.8",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -29,6 +29,10 @@
 			"types": "./dist/security/index.d.ts",
 			"import": "./dist/security/index.js"
 		},
+		"./security/private-hosts": {
+			"types": "./dist/security/private-hosts.d.ts",
+			"import": "./dist/security/private-hosts.js"
+		},
 		"./object": {
 			"types": "./dist/object/index.d.ts",
 			"import": "./dist/object/index.js"
@@ -97,6 +101,10 @@
 			"types": "./dist/ui/content-styles.d.ts",
 			"import": "./dist/ui/content-styles.js"
 		},
+		"./ui/fontawesome": {
+			"types": "./dist/ui/fontawesome.d.ts",
+			"import": "./dist/ui/fontawesome.js"
+		},
 		"./tools/term-lookup": {
 			"types": "./dist/tools/term-lookup.d.ts",
 			"import": "./dist/tools/term-lookup.js"
@@ -106,9 +114,10 @@
 		"dist"
 	],
 	"dependencies": {
-		"@pie-element/shared-utils": "0.1.4",
+		"@pie-element/shared-utils": "0.1.6",
 		"@pie-lib/math-rendering-module": "6.0.0",
 		"dompurify": "^3.4.17",
+		"ipaddr.js": "^2.5.0",
 		"semver": "^7.8.5"
 	},
 	"scripts": {
@@ -122,15 +131,15 @@
 		"scan-hardcoded": "bun run src/i18n/scripts/scan-hardcoded.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.15",
-		"@happy-dom/global-registrator": "^20.14.5",
-		"@pie-element/shared-math-rendering-mathjax": "0.1.7",
+		"@biomejs/biome": "^2.6.4",
+		"@happy-dom/global-registrator": "^21.0.4",
+		"@pie-element/shared-math-rendering-mathjax": "0.1.8",
 		"@playwright/test": "^1.64.1",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
-		"svelte": "^5.57.2",
+		"svelte": "^5.57.3",
 		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3"
 	},