@pie-players/pie-players-shared 1.0.0-beta.7 → 1.0.0-beta.9

package/dist/security/private-hosts.js

@@ -0,0 +1,85 @@
+/**
+ * Hostname classification for a URL a server fetches on someone else's behalf,
+ * such as an SSML `<audio src>` a TTS provider will request or an asset URL an
+ * upstream service returns. Every such check reads this module, so no two
+ * copies of it can drift apart.
+ *
+ * IP literals are classified by `ipaddr.js`, whose ranges follow the IANA IPv4
+ * and IPv6 Special-Purpose Address Registries (RFC 6890). A host is private
+ * unless it is a public unicast address or a name: loopback, private, link-local,
+ * unique-local, carrier-grade NAT, multicast, broadcast, documentation and
+ * reserved ranges, and the IPv6 forms that embed an IPv4 address (NAT64, 6to4,
+ * Teredo), all count. `ipaddr.js` also reads the numeric IPv4 forms (`2130706433`,
+ * `0x7f000001`, `0177.0.0.1`) and unmaps IPv4-mapped IPv6.
+ *
+ * Only the literal is checked. A public name that resolves to a private address
+ * passes; guarding that takes a check of the resolved address at connect time.
+ *
+ * @module
+ */
+import ipaddr from "ipaddr.js";
+/**
+ * Cloud instance-metadata hostnames. They hand out credentials. No registry
+ * lists them; each is the provider's documented name.
+ */
+const CLOUD_METADATA_HOSTNAMES = new Set([
+    "metadata.google.internal",
+    "metadata.azure.internal",
+    "metadata.packet.net",
+    "metadata.oci.oraclecloud.com",
+]);
+/** Cloud instance-metadata addresses: the link-local one most clouds use, and AWS's IPv6 one. */
+const CLOUD_METADATA_ADDRESSES = ["169.254.169.254", "fd00:ec2::254"].map((address) => ipaddr.parse(address));
+/** Lower-cased, without brackets or a trailing dot. */
+function normalizeHostname(hostname) {
+    return hostname
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "")
+        .toLowerCase();
+}
+/**
+ * The address `host` is a literal for, IPv4-mapped (`::ffff:a.b.c.d`) and
+ * IPv4-compatible (`::a.b.c.d`) IPv6 reduced to IPv4, or `null` for a name.
+ */
+function parseAddress(host) {
+    if (!ipaddr.isValid(host))
+        return null;
+    const address = ipaddr.process(host);
+    if (address.kind() !== "ipv6")
+        return address;
+    // `ipaddr.js` classifies deprecated IPv4-compatible addresses as unicast;
+    // read the IPv4 address in their low 32 bits instead.
+    const { parts } = address;
+    const isIpv4Compatible = parts.slice(0, 6).every((part) => part === 0) &&
+        (parts[6] !== 0 || parts[7] > 1);
+    return isIpv4Compatible
+        ? new ipaddr.IPv4([
+            parts[6] >> 8,
+            parts[6] & 0xff,
+            parts[7] >> 8,
+            parts[7] & 0xff,
+        ])
+        : address;
+}
+/** Whether `hostname` is a cloud instance-metadata endpoint. */
+export function isCloudMetadataHostname(hostname) {
+    const host = normalizeHostname(hostname);
+    if (CLOUD_METADATA_HOSTNAMES.has(host))
+        return true;
+    const address = parseAddress(host);
+    return (address !== null &&
+        CLOUD_METADATA_ADDRESSES.some((metadata) => metadata.kind() === address.kind() &&
+            metadata.toNormalizedString() === address.toNormalizedString()));
+}
+/**
+ * Whether `hostname` is anything other than a public unicast address or a
+ * public name: `localhost` and its subdomains (RFC 6761), or an IP literal in
+ * any special-purpose range.
+ */
+export function isPrivateHostname(hostname) {
+    const host = normalizeHostname(hostname);
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    const address = parseAddress(host);
+    return address !== null && address.range() !== "unicast";
+}

package/dist/timed-media/index.d.ts

@@ -5,7 +5,7 @@
  * Pure apart from one adapter factory that is inert until called, so the contract
  * is testable without a browser and an adapter can import it without pulling in a
  * player. Live cue state belongs to `SectionController` in
- * `@pie-players/pie-section-player`, which is where the equivalent formative state
+ * `@pie-players/pie-section-player`, which is where the equivalent Try state
  * lives — one rollup over one item set, in one package.
  *
  * Contract: `docs/prds/timed-media-section-contract.md`.

package/dist/timed-media/index.js

@@ -5,7 +5,7 @@
  * Pure apart from one adapter factory that is inert until called, so the contract
  * is testable without a browser and an adapter can import it without pulling in a
  * player. Live cue state belongs to `SectionController` in
- * `@pie-players/pie-section-player`, which is where the equivalent formative state
+ * `@pie-players/pie-section-player`, which is where the equivalent Try state
  * lives — one rollup over one item set, in one package.
  *
  * Contract: `docs/prds/timed-media-section-contract.md`.

package/dist/timed-media/policy.d.ts

@@ -28,9 +28,9 @@ export declare function normalizeTimedMediaSectionData(args: {
     itemIdentifiers: readonly string[];
     resolveStimulusRenderableId: (stimulusRef: string) => string | undefined;
     /**
-     * The Try budget each item's resolved formative policy leaves, so a gate on
+     * The Try budget each item's resolved item session control policy leaves, so a gate on
      * correctness can be refused where it would strand the learner. Supplied by the
-     * caller because formative policy resolution is that contract's, not this one's.
+     * caller because item session control policy resolution is that contract's, not this one's.
      */
     resolveItemTryBudget: (itemIdentifier: string) => TimedMediaItemTryBudget;
 }): TimedMediaValidationResult;

package/dist/timed-media/policy.js

@@ -240,7 +240,7 @@ export function normalizeTimedMediaSectionData(args) {
                 // A correctness gate is only passable while the learner still has a Try
                 // to spend. Over an item with a finite budget the gate becomes
                 // unpassable the moment the budget runs out, and over an item that does
-                // not deliver formatively there is never a Try at all — in both cases
+                // not enable item session control there is never a Try at all — in both cases
                 // nothing the learner can do releases playback, and no host action
                 // releases it either, because a forced reveal is not a correct answer.
                 // Refused here rather than released at runtime: releasing would deliver
@@ -250,7 +250,7 @@ export function normalizeTimedMediaSectionData(args) {
                 if (unpassable.length > 0) {
                     errors.push({
                         code: "gate-requires-unlimited-tries",
-                        message: `Gate cue "${identifier}" releases on correctness, so every item it names needs formative delivery with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
+                        message: `Gate cue "${identifier}" releases on correctness, so every item it names needs item session control with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
                         cueIdentifier: identifier,
                     });
                     continue;

package/dist/timed-media/session.d.ts

@@ -1,7 +1,7 @@
 /**
  * Persistence for the timed-media slice.
  *
- * Same posture as the formative slice: an unreadable slice is rejected whole and
+ * Same posture as the Try slice: an unreadable slice is rejected whole and
  * delivery starts from clean cue state, while item sessions in the same snapshot
  * are normalized separately and survive. A version bump here must never cost a
  * learner their responses.

package/dist/timed-media/session.js

@@ -1,7 +1,7 @@
 /**
  * Persistence for the timed-media slice.
  *
- * Same posture as the formative slice: an unreadable slice is rejected whole and
+ * Same posture as the Try slice: an unreadable slice is rejected whole and
  * delivery starts from clean cue state, while item sessions in the same snapshot
  * are normalized separately and survive. A version bump here must never cost a
  * learner their responses.

package/dist/timed-media/types.d.ts

@@ -9,7 +9,7 @@
  * See `docs/prds/timed-media-section-contract.md` for the ratified contract and
  * `docs/architecture/timed-media-section.md` for the layer-ownership record.
  */
-import type { FormativeCorrectness } from "../formative/types.js";
+import type { TryCorrectness } from "../item-session-control/types.js";
 import type { MediaFragmentRange } from "../types/index.js";
 /**
  * What a cue does to the items it names.
@@ -23,15 +23,15 @@ export type TimedMediaCueActivation = "reveal" | "gate" | "metadata";
 /**
  * The condition over delivery state that releases a gate.
  *
- * Named from the shipped formative vocabulary rather than defined here, which is
- * the whole reason formative delivery sequenced first — see
+ * Named from the shipped Try vocabulary rather than defined here, which is
+ * the whole reason item session control sequenced first — see
  * `docs/adr/0001-formative-delivery-before-timed-media.md`. `"responded"` is the
  * response-only case, and it reads item completion rather than Try state so a
- * gate works in a section that does not deliver formatively at all.
+ * gate works in a section that does not enable item session control at all.
  */
 export type TimedMediaGateCondition = "responded" | "correct" | "partial-or-better";
 /**
- * What a gate does when the item cannot be auto-scored — `FormativeCorrectness`
+ * What a gate does when the item cannot be auto-scored — `TryCorrectness`
  * of `"unknown"`, which is the honest state of an item holding a rubric element
  * rather than a defect to design around.
  *
@@ -131,13 +131,13 @@ export interface ResolvedTimedMediaSectionData {
     scoringPolicy?: TimedMediaScoringPolicy;
 }
 /**
- * What a gated item's resolved formative policy leaves the learner.
+ * What a gated item's resolved item session control policy leaves the learner.
  *
  * Read by validation, not by the reduction: a gate on correctness over an item
  * with a finite Try budget is a dead end, and so is one over an item that does not
- * deliver formatively at all — no Try means no correctness, ever.
+ * enable item session control at all — no Try means no correctness, ever.
  */
-export type TimedMediaItemTryBudget = "unlimited" | "finite" | "not-formative";
+export type TimedMediaItemTryBudget = "unlimited" | "finite" | "none";
 export interface TimedMediaValidationError {
     /** Machine-readable, so a host can branch without parsing prose. */
     code: "missing-stimulus-ref" | "unresolved-stimulus-ref"
@@ -219,7 +219,7 @@ export interface MediaTimeSource {
 /**
  * The persisted slice, carried on `SectionControllerSessionState.timedMedia`.
  *
- * One shape live and persisted, unlike formative's split between a per-item
+ * One shape live and persisted, unlike the Try state's split between a per-item
  * reducer state and a slice: timed-media state is section-scoped, so there is
  * nothing to key.
  */
@@ -241,14 +241,14 @@ export interface TimedMediaSectionSessionSlice {
 }
 /**
  * Delivery state a gate condition reads, supplied by the caller so this module
- * stays pure and depends on neither the controller nor the formative module's
+ * stays pure and depends on neither the controller nor the item session control module's
  * live state.
  */
 export interface TimedMediaDeliveryState {
     /** Item completion by canonical id: the `"responded"` condition's signal. */
     respondedByItemId: Record<string, boolean>;
     /** Last Try correctness by canonical id; absent means no Try yet. */
-    correctnessByItemId: Record<string, FormativeCorrectness | undefined>;
+    correctnessByItemId: Record<string, TryCorrectness | undefined>;
     /** Whether every item in the section reports completion. */
     itemsComplete: boolean;
 }

package/dist/tools/term-lookup.d.ts

@@ -13,6 +13,7 @@
  * corpus behind one is licensed per programme, so a host supplies either an endpoint
  * or a resolver of its own.
  */
+import type { TextDirection } from "../i18n/types.js";
 /** What a host's term service is asked for. */
 export interface TermLookupRequest {
     /** The term, already normalised by {@link normalizeTerm}. */
@@ -187,3 +188,17 @@ export declare function termPanelStatusMessage<TItem>(state: TermPanelState<TIte
     countLabel: (count: number) => string;
     emptyLabel: (term: string) => string;
 }): string;
+/**
+ * `lang` and `dir` for a lookup's results: the language the lookup asked in.
+ *
+ * Results are in the corpus's language, which is neither the panel's interface
+ * locale nor necessarily the content the term came from: a Spanish gloss for an
+ * English passage. Stamped on the results, an Arabic definition in an English panel
+ * reads and lays out as Arabic, and the panel's language never reaches the content.
+ * With no language named the corpus's is unknown, so the stamp is `lang=""` and
+ * `dir="auto"`, the one undeclared content gets.
+ */
+export declare function termResultLanguage(language: string | undefined): {
+    lang: string;
+    dir: TextDirection | "auto";
+};

package/dist/tools/term-lookup.js

@@ -13,6 +13,8 @@
  * corpus behind one is licensed per programme, so a host supplies either an endpoint
  * or a resolver of its own.
  */
+import { toLanguageTag } from "../i18n/language-tags.js";
+import { localeDirection } from "../i18n/provider.js";
 /** Longest term worth sending. Past this it is prose, not a headword. */
 export const MAX_LOOKUP_TERM_LENGTH = 80;
 /** Words a term may span. Generous enough for `carbon dioxide` and `mother in law`. */
@@ -282,3 +284,17 @@ export function termPanelStatusMessage(state, labels) {
         return labels.emptyLabel(state.term);
     return "";
 }
+/**
+ * `lang` and `dir` for a lookup's results: the language the lookup asked in.
+ *
+ * Results are in the corpus's language, which is neither the panel's interface
+ * locale nor necessarily the content the term came from: a Spanish gloss for an
+ * English passage. Stamped on the results, an Arabic definition in an English panel
+ * reads and lays out as Arabic, and the panel's language never reaches the content.
+ * With no language named the corpus's is unknown, so the stamp is `lang=""` and
+ * `dir="auto"`, the one undeclared content gets.
+ */
+export function termResultLanguage(language) {
+    const tag = toLanguageTag(language);
+    return tag ? { lang: tag, dir: localeDirection(tag) } : { lang: "", dir: "auto" };
+}

package/dist/types/index.d.ts

@@ -8,12 +8,12 @@
  * 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 { ItemSessionControlPolicy, TrySectionSlice } from "../item-session-control/types.js";
 import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
-import type { AdaptationLink, LanguagePolicy } from "./interchange.js";
-export type { FormativeDeliveryPolicy, FormativeItemPolicy };
+import type { AdaptationLink, CurriculumStandard, LanguagePolicy, SkillLevel } from "./interchange.js";
+export type { ItemSessionControlPolicy };
 export type { TimedMediaSectionData };
-export type { AdaptationLink, ContentSubstitution, LanguagePolicy, ServedContentIdentity, } from "./interchange.js";
+export type { AdaptationLink, ContentSubstitution, CurriculumStandard, LanguagePolicy, ServedContentIdentity, SkillLevel, } from "./interchange.js";
 export interface BaseEntity {
     id?: string;
     createdAt?: Date;
@@ -76,6 +76,13 @@ export interface PassageEntity extends VersionEntity, ConfigContainerEntity {
     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;
 }
@@ -96,6 +103,13 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity {
     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;
@@ -161,13 +175,13 @@ export interface AssessmentItemRef extends BaseEntity {
     /** Item-level settings for tool requirements and customization */
     settings?: ItemSettings;
     /**
-     * Formative delivery override for this item. Every field overrides the
-     * section's `formative` policy independently, which is the order QTI 3 uses
+     * Item session control override for this item. Every field overrides the
+     * section's `itemSessionControl` policy independently, which is the order QTI 3 uses
      * for `qti-item-session-control` on an item ref versus its section.
      *
-     * See `docs/prds/formative-delivery-contract.md`.
+     * See `docs/prds/item-session-control-contract.md`.
      */
-    formative?: FormativeItemPolicy;
+    itemSessionControl?: ItemSessionControlPolicy;
 }
 export interface AssessmentSection extends BaseEntity {
     id?: string;
@@ -194,15 +208,15 @@ export interface AssessmentSection extends BaseEntity {
     assessmentItemRefs?: AssessmentItemRef[];
     rubricBlocks?: RubricBlock[];
     /**
-     * Formative delivery policy for this section: how many Tries a learner gets
+     * Item session control policy for this section: how many Tries a learner gets
      * on each item, when feedback is revealed, and whether the behavior is on at
      * all. Absent or `enabled: false` delivers exactly as a section without this
      * field — no control, no state, no env override.
      *
-     * Individual items override it through `AssessmentItemRef.formative`. See
-     * `docs/prds/formative-delivery-contract.md`.
+     * Individual items override it through `AssessmentItemRef.itemSessionControl`. See
+     * `docs/prds/item-session-control-contract.md`.
      */
-    formative?: FormativeDeliveryPolicy;
+    itemSessionControl?: ItemSessionControlPolicy;
     /**
      * The section flavor. Absent for every section authored so far, and the only
      * value is `"timed-media"`, which pairs with `timedMedia` below.
@@ -244,19 +258,19 @@ export interface SectionControllerSessionState {
     visitedItemIdentifiers?: string[];
     itemSessions: Record<string, unknown>;
     /**
-     * Formative delivery state — Try counts and reveal state per item.
+     * Try state — Try counts and reveal state per item.
      *
      * Optional, and its absence is indistinguishable from a snapshot saved
-     * before formative delivery existed, which is what keeps existing persisted
+     * before item session control existed, which is what keeps existing persisted
      * sessions valid. A slice with an unrecognized `version` is rejected whole
-     * and formative state starts clean; `itemSessions` in the same snapshot is
-     * unaffected, so a formative version bump never costs a learner responses.
+     * and Try state starts clean; `itemSessions` in the same snapshot is
+     * unaffected, so a Try slice version bump never costs a learner responses.
      */
-    formative?: FormativeSectionSlice;
+    tries?: TrySectionSlice;
     /**
      * Timed-media delivery state — media progress, cue visits and completions.
      *
-     * Same posture as `formative`: optional, absence indistinguishable from a
+     * Same posture as `tries`: optional, absence indistinguishable from a
      * pre-timed-media snapshot, and an unrecognized `version` rejected whole so
      * cue progress restarts while item sessions in the same snapshot are applied
      * untouched.

package/dist/types/interchange.d.ts

@@ -1,7 +1,9 @@
 /**
- * Language-variant interchange types (PIE-1393). Backends and authoring tools
- * exchange them; no player reads `AdaptationLink` or `LanguagePolicy`.
+ * 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`.
@@ -40,8 +42,13 @@ export interface LanguagePolicy {
      */
     staleness: "serve" | "require-current";
 }
-/** Why the served content differs from what was requested. */
-export type ContentSubstitution = "fallback" | "stale";
+/**
+ * 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;
@@ -52,3 +59,58 @@ export interface ServedContentIdentity {
     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/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();
+}