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

package/README.md

@@ -20,6 +20,7 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `@pie-players/pie-players-shared` | The root: the loader, PIE, security and object helpers, loader config, instrumentation providers, the item-player strategy helpers, the default bundle host URL (`BUILDER_BUNDLE_URL`), a subset of the shared types, and the UI helpers (attribute coercion, content styles, pointer gestures, overlay placement, focus trap, safe storage, scoped CSS) |
 | `/loader-config` | `LoaderConfig` and its defaults: instrumentation (`trackPageActions`, `instrumentationProvider`), resource retry, and IIFE bundle retry |
 | `/security` | The item-markup sanitizer (`sanitizeItemMarkup`, `createDefaultItemMarkupSanitizer`, `buildAuthoringAllowList`), external-stylesheet URL validation, the SVG icon and `style` attribute sanitizers, and the wrappers that put overwide images and tables in a scrollable region |
+| `/security/private-hosts` | `isPrivateHostname` and `isCloudMetadataHostname`, the host classification for a URL a server fetches on someone else's behalf. Node-safe: it loads none of the markup sanitizers |
 | `/object` | `mergeObjectsIgnoringNullUndefined`, `cloneDeep`, `isPlainRecord` |
 | `/types` | The shared types: item, passage, section and session entities, PIE models and controllers, accessibility catalogs, and the [media vocabulary](#media-validation) |
 | `/formative` | [Formative delivery](#formative-delivery) |
@@ -33,9 +34,10 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `/i18n/provider` | `SimpleI18n`, `getDefaultI18n` and `resolveInterfaceI18n`, with the English catalog only |
 | `/i18n/catalogs` | `BUNDLED_LOCALES` and lazy loaders for the bundled locales other than English |
 | `/i18n/language-tags` | BCP 47 language tag normalization and matching |
-| `/nds-icon-button` | `<nds-icon-button>`, an icon button vendored as a prebuilt bundle with Lit inlined; importing it registers the tag. The assessment toolkit and `@pie-players/pie-tool-tts-inline` render it |
+| `/nds-icon-button` | `<nds-icon-button>`, an icon button vendored as a prebuilt bundle with Lit inlined; importing it registers the tag. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` render it |
 | `/ui/attribute-coercion` | Boolean attribute coercion for custom elements |
 | `/ui/content-styles` | `installContentStyles`, `auditContentStyles` and the opt-out checks behind the item player's content styles |
+| `/ui/fontawesome` | The FontAwesome `<nds-icon-button>` glyphs need: the one FA Free pin, Pro detection, the `<head>` and shadow-root installs, and the glyph weight. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` use it |
 | `/tools/term-lookup` | Term normalization and the lookup session the dictionary tools share; the host supplies the endpoint or a resolver |
 
 ## Formative Delivery

package/dist/i18n/catalogs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lazy catalog loaders for every locale this repository ships.
+ * The bundled catalog loader: `en-US`, the one statically shipped catalog.
  *
  * Imported by players, never by tools. A tool resolves its provider from the
  * toolkit runtime context and needs only the interface plus the English
@@ -7,25 +7,32 @@
  * into a bundle that never calls `setLocale`, because every tool
  * `vite.config.ts` sets `external: []`.
  *
- * An explicit static map rather than a bundler macro: `tsc` emits these
- * `import()` calls verbatim, so `players-shared/dist` evaluates anywhere ESM
- * does — webpack, esbuild, Rollup, Node, or a browser loading the files
- * directly. `pie-qti` used `import.meta.glob` and shipped a `dist` that throws
- * under every one of those. Each bundler still sees the specifiers statically,
- * so each locale stays its own chunk. Adding a locale means adding one line here
- * alongside the file.
+ * `en-US` is the source of truth — the fallback for every missing key in every
+ * other locale — so the provider imports it statically and it is always
+ * resident. It is the only catalog this package ships: every other locale this
+ * repository ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), whose loaders a host composes after
+ * this one. The composed shape is that package's README's wiring example:
  *
- * `en-US` is absent: it is the fallback for every missing key in every other
- * locale, so the provider imports it statically and it is always resident.
+ * ```ts
+ * loadCatalog: (locale) =>
+ *   loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale));
+ * ```
+ *
+ * A request this function cannot serve rejects, and the provider treats that
+ * as "resolve through the fallback chain" rather than an error, so a host
+ * locale nothing ships still renders English.
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
 import type { BundledLocaleCode, MessageCatalog } from "./types.js";
 /**
- * Every locale tag this repository ships a catalog for, English included.
+ * Every locale tag this repository bundles a catalog for. `en-US` alone: the
+ * statically resident source of truth.
  *
  * The provider resolves a request against this list through RFC 4647 lookup and
- * primary-subtag widening, so `nl`, `nl_NL` and `nl-BE` all reach `nl-NL`.
+ * primary-subtag widening, so `en`, `en_US` and `en-GB`-without-a-catalog all
+ * land on `en-US` unless a composed loader serves the region.
  */
 export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
 /**
@@ -36,7 +43,7 @@ export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
  * or a pseudo-localization of the English catalog — asks for it by name like
  * any other locale.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * Rejects for a locale with no bundled catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */

package/dist/i18n/catalogs.js

@@ -1,5 +1,5 @@
 /**
- * Lazy catalog loaders for every locale this repository ships.
+ * The bundled catalog loader: `en-US`, the one statically shipped catalog.
  *
  * Imported by players, never by tools. A tool resolves its provider from the
  * toolkit runtime context and needs only the interface plus the English
@@ -7,30 +7,34 @@
  * into a bundle that never calls `setLocale`, because every tool
  * `vite.config.ts` sets `external: []`.
  *
- * An explicit static map rather than a bundler macro: `tsc` emits these
- * `import()` calls verbatim, so `players-shared/dist` evaluates anywhere ESM
- * does — webpack, esbuild, Rollup, Node, or a browser loading the files
- * directly. `pie-qti` used `import.meta.glob` and shipped a `dist` that throws
- * under every one of those. Each bundler still sees the specifiers statically,
- * so each locale stays its own chunk. Adding a locale means adding one line here
- * alongside the file.
+ * `en-US` is the source of truth — the fallback for every missing key in every
+ * other locale — so the provider imports it statically and it is always
+ * resident. It is the only catalog this package ships: every other locale this
+ * repository ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), whose loaders a host composes after
+ * this one. The composed shape is that package's README's wiring example:
  *
- * `en-US` is absent: it is the fallback for every missing key in every other
- * locale, so the provider imports it statically and it is always resident.
+ * ```ts
+ * loadCatalog: (locale) =>
+ *   loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale));
+ * ```
+ *
+ * A request this function cannot serve rejects, and the provider treats that
+ * as "resolve through the fallback chain" rather than an error, so a host
+ * locale nothing ships still renders English.
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
 import enUS from "./messages/en-US.js";
-const CATALOG_LOADERS = {
-    "nl-NL": () => import("./messages/nl-NL.js"),
-};
 /**
- * Every locale tag this repository ships a catalog for, English included.
+ * Every locale tag this repository bundles a catalog for. `en-US` alone: the
+ * statically resident source of truth.
  *
  * The provider resolves a request against this list through RFC 4647 lookup and
- * primary-subtag widening, so `nl`, `nl_NL` and `nl-BE` all reach `nl-NL`.
+ * primary-subtag widening, so `en`, `en_US` and `en-GB`-without-a-catalog all
+ * land on `en-US` unless a composed loader serves the region.
  */
-export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
+export const BUNDLED_LOCALES = ["en-US"];
 /**
  * Load one shipped catalog.
  *
@@ -39,7 +43,7 @@ export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
  * or a pseudo-localization of the English catalog — asks for it by name like
  * any other locale.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * Rejects for a locale with no bundled catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */
@@ -47,10 +51,5 @@ export async function loadBundledCatalog(locale) {
     if (locale === "en-US") {
         return enUS;
     }
-    const loader = CATALOG_LOADERS[locale];
-    if (!loader) {
-        throw new Error(`No bundled i18n catalog for locale: ${locale}`);
-    }
-    const module = await loader();
-    return module.default;
+    throw new Error(`No bundled i18n catalog for locale: ${locale}`);
 }

package/dist/i18n/language-tags.d.ts

@@ -78,19 +78,31 @@ export declare function languageTagScriptLookupSequence(tag: string | null | und
  * `zh-TW` passes it by.
  */
 export declare function findBestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
+/**
+ * A tag without its variant, extension and private-use subtags, casing kept:
+ * `en-GB-x-gulf` yields `en-GB`. The form for a speech engine, whose voices
+ * are keyed by language and region.
+ */
+export declare function languageTagWithoutVariants(tag: string | null | undefined): string;
 /**
  * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
- * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Both stay within
- * the request's script: `zh` never reaches `zh-TW`, and `sr-Latn` may reach
- * `sr-ME`. The rule that picks an interface catalog and a content variant alike.
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Widening stays
+ * within the request's script and keeps its variant subtags: `zh` never
+ * reaches `zh-TW`, `sr-Latn` may reach `sr-ME`, `en-GB` never reaches
+ * `en-GB-x-gulf`, and `en-US-x-gulf` may reach `en-GB-x-gulf`. Among several
+ * siblings the first in `available` wins. The rule that picks an interface
+ * catalog and a content variant alike.
  */
 export declare function findClosestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
 /** The content language a backend serves, and whether it is a substitute. */
 export interface ContentLanguageMatch {
     /** The `available` entry served, as authored; `null` for content that declares no language. */
     language: string | null;
-    /** `"fallback"` when the served content stands in for the request. */
-    substitution?: "fallback";
+    /**
+     * `"fallback"` when the served content stands in for the request;
+     * `"variety"` when it is another variety of the requested language.
+     */
+    substitution?: "fallback" | "variety";
 }
 /**
  * The language to serve content in: the closest `available` match for the
@@ -100,7 +112,12 @@ export interface ContentLanguageMatch {
  * chain serves the closest match for `defaultLanguage` (`en-US` reaches `en`),
  * then content that declares no language (a `null` entry), then `source`;
  * `matching` does not narrow it. `undefined` means nothing can be served. No
- * requested languages run the chain without a substitution.
+ * requested languages run the chain without a substitution. A closest match
+ * in another variety, `es-MX` served `es-ES`, records `"variety"`; a host
+ * that must not serve one sets `matching: "exact"` and lists the varieties it
+ * accepts. Candidates rank
+ * `source` first, then by tag, so the order of `available` never decides
+ * between two siblings.
  */
 export declare function negotiateContentLanguage(requested: readonly string[], available: readonly (string | null)[], options?: {
     defaultLanguage?: string;

package/dist/i18n/language-tags.js

@@ -149,11 +149,59 @@ export function findBestLanguageMatch(requested, available) {
     }
     return undefined;
 }
+/**
+ * A tag's subtags split at the end of its language, script and region:
+ * `en-GB-x-gulf` yields `[["en", "GB"], ["x", "gulf"]]`. The second part holds
+ * variants, extensions and private use, as authored.
+ */
+function splitVariantSubtags(tag) {
+    const subtags = toLanguageTag(tag).split(/[.@]/)[0].split("-");
+    let length = 1;
+    if (/^[a-z]{4}$/i.test(subtags[length] ?? ""))
+        length++;
+    if (/^([a-z]{2}|\d{3})$/i.test(subtags[length] ?? ""))
+        length++;
+    return [subtags.slice(0, length), subtags.slice(length)];
+}
+/** The variant, extension and private-use subtags as a comparison key. */
+function variantSubtagsKey(tag) {
+    return splitVariantSubtags(tag)[1].join("-").toLowerCase();
+}
+/**
+ * Whether `served` is another variety of `requested`: it names a different
+ * region, or different variant or private-use subtags. `es-MX` served `es-ES`
+ * or `en-GB-x-gulf` served `en-GB` is; `es-MX` served `es`, or `zh-TW` served
+ * `zh-Hant`, is not.
+ */
+function isOtherLanguageVariety(requested, served) {
+    const region = (tag) => {
+        const [base] = splitVariantSubtags(tag);
+        const last = base.length > 1 ? base[base.length - 1] : "";
+        return /^([a-z]{2}|\d{3})$/i.test(last) ? last.toLowerCase() : undefined;
+    };
+    const requestedRegion = region(requested);
+    const servedRegion = region(served);
+    return ((requestedRegion !== undefined &&
+        servedRegion !== undefined &&
+        requestedRegion !== servedRegion) ||
+        variantSubtagsKey(requested) !== variantSubtagsKey(served));
+}
+/**
+ * A tag without its variant, extension and private-use subtags, casing kept:
+ * `en-GB-x-gulf` yields `en-GB`. The form for a speech engine, whose voices
+ * are keyed by language and region.
+ */
+export function languageTagWithoutVariants(tag) {
+    return splitVariantSubtags(tag)[0].join("-");
+}
 /**
  * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
- * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Both stay within
- * the request's script: `zh` never reaches `zh-TW`, and `sr-Latn` may reach
- * `sr-ME`. The rule that picks an interface catalog and a content variant alike.
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Widening stays
+ * within the request's script and keeps its variant subtags: `zh` never
+ * reaches `zh-TW`, `sr-Latn` may reach `sr-ME`, `en-GB` never reaches
+ * `en-GB-x-gulf`, and `en-US-x-gulf` may reach `en-GB-x-gulf`. Among several
+ * siblings the first in `available` wins. The rule that picks an interface
+ * catalog and a content variant alike.
  */
 export function findClosestLanguageMatch(requested, available) {
     const best = findBestLanguageMatch(requested, available);
@@ -162,7 +210,9 @@ export function findClosestLanguageMatch(requested, available) {
     const language = normalizeLanguageTag(requested).split("-")[0];
     if (!language)
         return undefined;
+    const variants = variantSubtagsKey(requested);
     const sibling = available.find((candidate) => normalizeLanguageTag(candidate).split("-")[0] === language &&
+        variantSubtagsKey(candidate) === variants &&
         languageTagScriptsMatch(requested, candidate));
     return sibling ?? undefined;
 }
@@ -174,20 +224,35 @@ export function findClosestLanguageMatch(requested, available) {
  * chain serves the closest match for `defaultLanguage` (`en-US` reaches `en`),
  * then content that declares no language (a `null` entry), then `source`;
  * `matching` does not narrow it. `undefined` means nothing can be served. No
- * requested languages run the chain without a substitution.
+ * requested languages run the chain without a substitution. A closest match
+ * in another variety, `es-MX` served `es-ES`, records `"variety"`; a host
+ * that must not serve one sets `matching: "exact"` and lists the varieties it
+ * accepts. Candidates rank
+ * `source` first, then by tag, so the order of `available` never decides
+ * between two siblings.
  */
 export function negotiateContentLanguage(requested, available, options = {}) {
     const { defaultLanguage, fallback = "default", matching = "closest", source } = options;
+    const candidates = [...available].sort((a, b) => {
+        if ((a === source) !== (b === source))
+            return a === source ? -1 : 1;
+        const left = normalizeLanguageTag(a);
+        const right = normalizeLanguageTag(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
     for (const tag of requested) {
         const language = matching === "exact"
-            ? available.find((candidate) => languageTagsEqual(candidate, tag))
-            : findClosestLanguageMatch(tag, available);
-        if (language != null)
-            return { language };
+            ? candidates.find((candidate) => languageTagsEqual(candidate, tag))
+            : findClosestLanguageMatch(tag, candidates);
+        if (language != null) {
+            return isOtherLanguageVariety(tag, language)
+                ? { language, substitution: "variety" }
+                : { language };
+        }
     }
     if (requested.length > 0 && fallback === "none")
         return undefined;
-    let language = findClosestLanguageMatch(defaultLanguage, available);
+    let language = findClosestLanguageMatch(defaultLanguage, candidates);
     if (language === undefined && available.includes(null))
         language = null;
     if (language === undefined && source !== undefined && available.includes(source)) {

package/dist/i18n/messages/en-US.d.ts

@@ -301,6 +301,12 @@ declare const enUS: {
                 lanthanide: string;
                 actinide: string;
             };
+            /** Standard-state phase, keyed by the data file's lowercased `phase` value. */
+            phaseValue: {
+                solid: string;
+                liquid: string;
+                gas: string;
+            };
         };
         ruler: {
             name: string;
@@ -462,6 +468,17 @@ declare const enUS: {
             highlightPinkA11y: string;
             highlightBlueA11y: string;
             highlightGreenA11y: string;
+            selectionAvailableA11y: string;
+            highlightedYellowA11y: string;
+            highlightedPinkA11y: string;
+            highlightedBlueA11y: string;
+            highlightedGreenA11y: string;
+            underlinedA11y: string;
+            removedA11y: string;
+            clearedA11y: {
+                one: string;
+                other: string;
+            };
         };
         theme: {
             name: string;

package/dist/i18n/messages/en-US.js

@@ -306,6 +306,12 @@ const enUS = {
                 lanthanide: "Lanthanide",
                 actinide: "Actinide",
             },
+            /** Standard-state phase, keyed by the data file's lowercased `phase` value. */
+            phaseValue: {
+                solid: "Solid",
+                liquid: "Liquid",
+                gas: "Gas",
+            },
         },
         ruler: {
             name: "Ruler",
@@ -482,6 +488,19 @@ const enUS = {
             highlightPinkA11y: "Pink highlight",
             highlightBlueA11y: "Blue highlight",
             highlightGreenA11y: "Green highlight",
+            // Announced in the strip's live region. A colour is authored per phrase:
+            // a colour adjective agrees with its noun in some languages.
+            selectionAvailableA11y: "Annotation toolbar available for “{text}”. Press Shift+F10 for annotation tools.",
+            highlightedYellowA11y: "“{text}” highlighted in yellow",
+            highlightedPinkA11y: "“{text}” highlighted in pink",
+            highlightedBlueA11y: "“{text}” highlighted in blue",
+            highlightedGreenA11y: "“{text}” highlighted in green",
+            underlinedA11y: "“{text}” underlined",
+            removedA11y: "Removed annotation from “{text}”",
+            clearedA11y: {
+                one: "{count} annotation cleared",
+                other: "{count} annotations cleared",
+            },
         },
         theme: {
             name: "Theme",

package/dist/i18n/types.d.ts

@@ -16,8 +16,13 @@ import type enUS from "./messages/en-US.js";
  * syntax — the Learnosity transform emits POSIX `nl_NL`, QTI catalog cards carry
  * `xml:lang` — and the resolver normalizes both onto these, so this list is the
  * set of catalogs, not the set of accepted inputs.
+ *
+ * `en-US` is the only bundled catalog: the statically resident source of truth
+ * every other locale falls back through. Every other locale this repository
+ * ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), which a host composes into its loader.
  */
-export type BundledLocaleCode = "en-US" | "nl-NL";
+export type BundledLocaleCode = "en-US";
 /**
  * Any locale tag. A host may supply a locale we ship no catalog for and provide
  * its own messages through {@link I18nConfig.customMessages}, so this is

package/dist/security/private-hosts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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
+ */
+/** Whether `hostname` is a cloud instance-metadata endpoint. */
+export declare function isCloudMetadataHostname(hostname: string): boolean;
+/**
+ * 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 declare function isPrivateHostname(hostname: string): boolean;

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/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

@@ -10,10 +10,10 @@
  */
 import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
 import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
-import type { AdaptationLink, LanguagePolicy } from "./interchange.js";
+import type { AdaptationLink, CurriculumStandard, LanguagePolicy, SkillLevel } from "./interchange.js";
 export type { FormativeDeliveryPolicy, FormativeItemPolicy };
 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;