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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIE Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,13 +2,12 @@
 
 Shared runtime utilities for the `@pie-players/*` player suite: the element
 loader, PIE config and session helpers, markup security, i18n, and the
-formative, timed-media and media contracts. For framework code and host
+item session control, timed-media and media contracts. For framework code and host
 integrations that need the helpers the player packages use.
 
 ## Public Exports
 
 ```ts
-import { safeLocalStorageGet } from "@pie-players/pie-players-shared";
 import { makeUniqueTags } from "@pie-players/pie-players-shared/pie";
 import { normalizeItemPlayerStrategy } from "@pie-players/pie-players-shared";
 ```
@@ -17,12 +16,13 @@ The subpaths below are the package's `exports`; nothing else is importable.
 
 | Subpath | Contents |
 | --- | --- |
-| `@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) |
+| `@pie-players/pie-players-shared` | The root: the loader, PIE and security 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 the tools share (focus trap and focusable lookup, IME composition, overlay containment and placement, pointer drag and gestures, scoped CSS). Attribute coercion, content styles and the object helpers are on their own subpaths only |
 | `/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) |
+| `/item-session-control` | [Item session control](#item-session-control) |
 | `/timed-media` | [Timed media](#timed-media) |
 | `/media` | [Media validation](#media-validation) |
 | `/pie` | PIE runtime utilities: config helpers, bundle initialization, `ItemController` and the item session contract, session commit and snapshots, authoring helpers, math renderer setup, instrumentation event maps ([PIE utilities](src/pie/README.md)) |
@@ -32,15 +32,16 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `/i18n/types` | The i18n contract, types only |
 | `/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 |
+| `/i18n/language-tags` | BCP 47 language tag normalization and matching, re-exported from `@pie-players/pie-language-tags` |
+| `/nds-icon-button` | `<pie-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 `<pie-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
+## Item Session Control
 
-`@pie-players/pie-players-shared/formative` holds the policy resolution, outcome
+`@pie-players/pie-players-shared/item-session-control` holds the policy resolution, outcome
 aggregation, Try-state reducer, item view, and mastery rollup that
 `pie-section-player` drives. It is pure (no DOM, no timers, no element
 registry), so it is testable without a browser and importable by an adapter that
@@ -48,18 +49,18 @@ has no player.
 
 ```ts
 import {
-  aggregateFormativeOutcome,
-  resolveFormativePolicy,
-  resolveFormativeItemView,
-  rollupFormativeMastery,
-} from "@pie-players/pie-players-shared/formative";
+  aggregateTryOutcome,
+  resolveItemSessionControl,
+  resolveItemTryView,
+  rollupMastery,
+} from "@pie-players/pie-players-shared/item-session-control";
 ```
 
-The authored half, `FormativeDeliveryPolicy` on `AssessmentSection` and
-`FormativeItemPolicy` on `AssessmentItemRef`, is re-exported from the package
+The authored half, `ItemSessionControlPolicy` on `AssessmentSection` and
+`AssessmentItemRef`, is re-exported from the package
 root and from `/types`, beside the section types it annotates.
 
-The contract is [`docs/prds/formative-delivery-contract.md`](../../docs/prds/formative-delivery-contract.md),
+The contract is [`docs/prds/item-session-control-contract.md`](../../docs/prds/item-session-control-contract.md),
 including the QTI 3 mapping and why PIE says **Try** rather than "attempt".
 
 ## Timed Media
@@ -92,7 +93,7 @@ re-exported from the package root and from `/types`, beside the section types it
 annotates.
 
 The contract is [`docs/prds/timed-media-section-contract.md`](../../docs/prds/timed-media-section-contract.md),
-including why cue gate conditions name the formative vocabulary and why an
+including why cue gate conditions name the Try vocabulary and why an
 unenforceable policy degrades to advisory rather than failing closed.
 
 ## Media Validation

package/dist/THIRD-PARTY-LICENSES.txt

@@ -0,0 +1,51 @@
+Third-party software included in this package's bundles, with the licence each is used under.
+
+========================================================================
+
+es-module-shims 2.8.4
+License: MIT
+
+MIT License
+-----------
+
+Copyright (C) 2018-2021 Guy Bedford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+========================================================================
+
+lit (pre-bundled in the vendored NDS icon button)
+License: BSD-3-Clause
+
+BSD 3-Clause License
+
+Copyright (c) 2017 Google LLC. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/components/vendor/nds/README.md

@@ -1,7 +1,8 @@
 # Vendored: `nds-icon-button`
 
 Pre-built bundle of the Renaissance Next Design System (NDS)
-`<nds-icon-button>` custom element. This is the **single source of truth** for
+`nds-icon-button` component, registered here as `<pie-nds-icon-button>`. This is
+the **single source of truth** for
 the button across `@pie-players/*`; consumers import it via the package export
 `@pie-players/pie-players-shared/nds-icon-button` rather than vendoring their
 own copy.
@@ -12,6 +13,7 @@ Known consumers:
   header (chevrons, zoom, close).
 - `@pie-players/pie-tool-tts-inline` — the Text-to-Speech play/pause trigger
   and the "more" overflow control.
+- `@pie-players/pie-section-player` — the items pane's scroll hint.
 
 It ships as a pre-built single-file bundle (Lit inlined) so consumers get the
 button without taking a runtime dependency on Lit or the rest of NDS: the Lit
@@ -27,6 +29,17 @@ lands, so it never leaks into a consumer's own dependency set.
 | Last sync commit | `1c728d3` |
 | Bundler | Vite 7 in lib mode, ES output, single-file (Lit inlined) |
 
+## Licence
+
+The inlined Lit runtime is BSD-3-Clause, Copyright Google LLC. Its `@license`
+comments sit in `nds-icon-button.js` and must survive every refresh, since the
+licence requires the notice to travel with a redistributed copy.
+
+The NDS component code is Renaissance's own. The bundle carries no NDS licence
+header and the repository records no separate terms, so it ships inside
+`@pie-players/pie-players-shared` under that package's MIT licence (`LICENSE`).
+Renaissance owns that call; record any different terms here.
+
 ## Why a vendored bundle, not an npm dep
 
 NDS is not currently published to a registry the `@pie-players/*` chain can
@@ -35,10 +48,22 @@ would force a `lit` dependency plus a chunk of foundations CSS onto every
 downstream consumer on lockstep release. A pre-built single-file bundle
 sidesteps both: zero new package deps, the bundle inlines what it needs.
 
+## Registered tag
+
+The bundle registers `pie-nds-icon-button`, under PIE's prefix. A host page that
+also loads NDS registers upstream's own `nds-icon-button`, often unguarded and
+at a different version; sharing that name would leave whichever copy defines
+second either skipped (PIE's guarded define) or throwing (the host's). Two
+sites are patched: the `Pt("…")` decorator argument at the class registration,
+and the `nds-icon-button { display: inline-block; }` element selector at the top
+of `render()`'s inline `<style>`. The BEM class names (`.nds-icon-button`,
+`.nds-icon-button__icon`, modifiers) stay upstream's, and so do the export path
+and file names.
+
 ## Idempotent registration (built-in define guard)
 
-A host page can load more than one `nds-icon-button` consumer (e.g. the toolkit
-and the inline TTS tool), and each would otherwise register `nds-icon-button` a
+A host page can load more than one `pie-nds-icon-button` consumer (e.g. the
+toolkit and the inline TTS tool), and each would otherwise register the tag a
 second time and throw `NotSupportedError`. To make registration idempotent
 regardless of load order, the Lit `@customElement` decorator helper (`Pt`) in
 this bundle is patched to guard the define:
@@ -55,6 +80,18 @@ Re-apply this guard after any refresh from upstream. Because the guard still
 contains the literal `customElements.define(` token, this file is allow-listed
 in `scripts/check-ce-define-safety.mjs` (which would otherwise flag it).
 
+## One registration per page
+
+The tag is registered at most once per page, by whichever consumer reaches it
+first, and that copy serves every consumer. Consumers load the bundle with a
+dynamic `import()` the first time an NDS control is about to render, which is
+only when the host sets `ndsIcons: true`; a page that never opts in neither
+fetches the bundle nor takes the `pie-nds-icon-button` tag. A second copy of the
+bundle at a different version loads without error and is skipped by the define
+guard, so the first copy to register decides the markup and styles every
+consumer sees. A host that loads its own NDS registers upstream's
+`nds-icon-button`, a different tag, and is unaffected.
+
 ## How this is built and shipped
 
 `players-shared` builds with `tsc`, which does not emit static `.js`/`.d.ts`
@@ -69,6 +106,7 @@ Consuming bundlers treat this module per their own externals config:
 - `tool-tts-inline` (Vite lib build) externalizes `players-shared` and its
   subpaths, so its published output imports
   `@pie-players/pie-players-shared/nds-icon-button` from the host.
+- `section-player` externalizes the same specifier for the scroll hint.
 - `assessment-toolkit` builds its CE artifacts with every dependency and peer
   dependency, plus each one's subpaths, as esbuild externals, so this module
   stays a bare external import in those artifacts — resolved by the
@@ -107,8 +145,8 @@ When a newer `nds-icon-button` is needed:
    ```
 
    Then: `bunx vite build --config vite.self-contained.config.js`.
-4. Copy the output over this file, re-apply the define guard above, and update
-   the `Last sync commit` row.
+4. Copy the output over this file, re-apply the define guard and the two tag
+   renames above, and update the `Last sync commit` row.
 5. Rebuild the consumers (`assessment-toolkit`, `tool-tts-inline`) and verify
    the calculator shell and the TTS trigger still mount and register.
 

package/dist/components/vendor/nds/nds-icon-button.d.ts

@@ -1,8 +1,8 @@
 /**
- * Type surface for the vendored `<nds-icon-button>` bundle.
+ * Type surface for the vendored NDS icon button bundle.
  *
  * Consumers import this module for its side effect (it registers the
- * `nds-icon-button` custom element on evaluation). The named export is
+ * `pie-nds-icon-button` custom element on evaluation). The named export is
  * provided only so tooling can reference the constructor; the tag is what
  * consumers actually use, via markup or `document.createElement`.
  */

package/dist/components/vendor/nds/nds-icon-button.js

@@ -602,7 +602,7 @@ let p = class extends C {
   render() {
     return yt`
       <style>
-        nds-icon-button {
+        pie-nds-icon-button {
           display: inline-block;
         }
 
@@ -819,7 +819,7 @@ b([
   _()
 ], p.prototype, "shape", 1);
 p = b([
-  Pt("nds-icon-button")
+  Pt("pie-nds-icon-button")
 ], p);
 export {
   p as NdsIconButton

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,31 +7,43 @@
  * 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[];
 /**
  * Load one shipped catalog.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * `en-US` comes back without a load: it is statically resident, and a host
+ * composing this loader into a provider — the generated tier's README pattern,
+ * or a pseudo-localization of the English catalog — asks for it by name like
+ * any other locale.
+ *
+ * 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,41 +7,49 @@
  * 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
  */
-const CATALOG_LOADERS = {
-    "nl-NL": () => import("./messages/nl-NL.js"),
-};
+import enUS from "./messages/en-US.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.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * `en-US` comes back without a load: it is statically resident, and a host
+ * composing this loader into a provider — the generated tier's README pattern,
+ * or a pseudo-localization of the English catalog — asks for it by name like
+ * any other locale.
+ *
+ * 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.
  */
 export async function loadBundledCatalog(locale) {
-    const loader = CATALOG_LOADERS[locale];
-    if (!loader) {
-        throw new Error(`No bundled i18n catalog for locale: ${locale}`);
+    if (locale === "en-US") {
+        return enUS;
     }
-    const module = await loader();
-    return module.default;
+    throw new Error(`No bundled i18n catalog for locale: ${locale}`);
 }

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

@@ -0,0 +1,77 @@
+/**
+ * Content language on the delivery channel.
+ *
+ * Content language names the language the item's content is written in — a
+ * fact about the content, on a separate channel from the interface locale a
+ * player publishes to the elements inside it. It reaches the player in
+ * `env.locale`, the same channel `env.mode` travels: a delivery fact the
+ * container knows and content cannot. Authoring hosts emit it; a host that
+ * emits nothing leaves the content unstamped, and nothing is invented — there
+ * is no default language for content that names none.
+ *
+ * The player reflects the resolved language onto its content subtree's root as
+ * `lang` and `dir`, so a screen reader takes the content's voice rules and RTL
+ * content lays out right to left, independent of the chrome's locale.
+ *
+ * Content that declares nothing falls back to a default the container names:
+ * a section's `runtime.contentLanguage`, or {@link UNDECLARED_CONTENT_LANGUAGE}
+ * once the host sets an interface locale, which stamps `lang=""` and
+ * `dir="auto"` so the content takes neither the interface's language nor its
+ * direction. With neither, undeclared content inherits its context, which keeps
+ * hosts that set no interface locale rendering as they always have.
+ */
+import type { TextDirection } from "./types.js";
+/**
+ * The content-language default for content that declares no language under a
+ * host-set interface locale: `lang=""` names the language unknown and
+ * `dir="auto"` takes direction from the content's first strong character.
+ */
+export declare const UNDECLARED_CONTENT_LANGUAGE = "auto";
+/**
+ * The default a player stamps on content whose `env` declares no language: the
+ * host's content language, else {@link UNDECLARED_CONTENT_LANGUAGE} when the
+ * host set an interface locale, else `undefined`, which leaves undeclared
+ * content inheriting its context. Inputs are read defensively, since both
+ * arrive from attributes.
+ */
+export declare function defaultContentLanguage(options: {
+    contentLanguage?: unknown;
+    interfaceLocale?: unknown;
+}): string | undefined;
+/** `lang` and `dir` for declared content, or `null` when nothing is declared. */
+export interface ContentLanguageAttributes {
+    lang: string;
+    dir: TextDirection;
+}
+/**
+ * `lang` and `dir` for the content an `env` describes, or `null` when it
+ * declares no usable language. Reads `env.locale` defensively — `env` is
+ * pass-through and load-bearing, so anything may arrive — and never invents a
+ * default: undeclared content stays unstamped and inherits whatever its
+ * context genuinely provides.
+ */
+export declare function contentLanguageAttributes(env: unknown): ContentLanguageAttributes | null;
+/**
+ * Stamps the content language onto `target`: `contentLanguageAttributes(env)`,
+ * else `fallback` — a tag, or {@link UNDECLARED_CONTENT_LANGUAGE} for
+ * `lang=""` and `dir="auto"` — else neither attribute, so a model set can drop
+ * the language a previous one declared. A fallback that is not a usable tag
+ * counts as absent. No-op without a target.
+ */
+export declare function stampContentLanguage(target: Element | null | undefined, env: unknown, fallback?: string | null): void;
+/**
+ * The direction of the first letter in `root`'s text, skipping `script`,
+ * `style` and `template`, or `null` when it has none. Letters only, which is
+ * where the bidi algorithm's strong characters overwhelmingly sit.
+ */
+export declare function firstStrongDirection(root: Node): TextDirection | null;
+/**
+ * The mismatch between undeclared content's script and the direction a
+ * fallback stamped on `root`, or `null` when there is none to report: the env
+ * declares a language, `root` carries no stamped direction or `dir="auto"`, or
+ * the content has no letters.
+ */
+export declare function undeclaredDirectionMismatch(root: Element, env: unknown): {
+    stamped: TextDirection;
+    script: TextDirection;
+} | null;

package/dist/i18n/content-language.js

@@ -0,0 +1,129 @@
+/**
+ * Content language on the delivery channel.
+ *
+ * Content language names the language the item's content is written in — a
+ * fact about the content, on a separate channel from the interface locale a
+ * player publishes to the elements inside it. It reaches the player in
+ * `env.locale`, the same channel `env.mode` travels: a delivery fact the
+ * container knows and content cannot. Authoring hosts emit it; a host that
+ * emits nothing leaves the content unstamped, and nothing is invented — there
+ * is no default language for content that names none.
+ *
+ * The player reflects the resolved language onto its content subtree's root as
+ * `lang` and `dir`, so a screen reader takes the content's voice rules and RTL
+ * content lays out right to left, independent of the chrome's locale.
+ *
+ * Content that declares nothing falls back to a default the container names:
+ * a section's `runtime.contentLanguage`, or {@link UNDECLARED_CONTENT_LANGUAGE}
+ * once the host sets an interface locale, which stamps `lang=""` and
+ * `dir="auto"` so the content takes neither the interface's language nor its
+ * direction. With neither, undeclared content inherits its context, which keeps
+ * hosts that set no interface locale rendering as they always have.
+ */
+import { canonicalLanguageTag } from "./language-tags.js";
+import { localeDirection } from "./provider.js";
+/**
+ * The content-language default for content that declares no language under a
+ * host-set interface locale: `lang=""` names the language unknown and
+ * `dir="auto"` takes direction from the content's first strong character.
+ */
+export const UNDECLARED_CONTENT_LANGUAGE = "auto";
+/**
+ * The default a player stamps on content whose `env` declares no language: the
+ * host's content language, else {@link UNDECLARED_CONTENT_LANGUAGE} when the
+ * host set an interface locale, else `undefined`, which leaves undeclared
+ * content inheriting its context. Inputs are read defensively, since both
+ * arrive from attributes.
+ */
+export function defaultContentLanguage(options) {
+    const named = typeof options.contentLanguage === "string"
+        ? options.contentLanguage.trim()
+        : "";
+    if (named)
+        return named;
+    const requested = typeof options.interfaceLocale === "string"
+        ? options.interfaceLocale.trim()
+        : "";
+    return requested ? UNDECLARED_CONTENT_LANGUAGE : undefined;
+}
+/**
+ * `lang` and `dir` for the content an `env` describes, or `null` when it
+ * declares no usable language. Reads `env.locale` defensively — `env` is
+ * pass-through and load-bearing, so anything may arrive — and never invents a
+ * default: undeclared content stays unstamped and inherits whatever its
+ * context genuinely provides.
+ */
+export function contentLanguageAttributes(env) {
+    const locale = env?.locale;
+    if (typeof locale !== "string")
+        return null;
+    const lang = canonicalLanguageTag(locale);
+    if (!lang)
+        return null;
+    return { lang, dir: localeDirection(lang) };
+}
+/**
+ * Stamps the content language onto `target`: `contentLanguageAttributes(env)`,
+ * else `fallback` — a tag, or {@link UNDECLARED_CONTENT_LANGUAGE} for
+ * `lang=""` and `dir="auto"` — else neither attribute, so a model set can drop
+ * the language a previous one declared. A fallback that is not a usable tag
+ * counts as absent. No-op without a target.
+ */
+export function stampContentLanguage(target, env, fallback) {
+    if (!target)
+        return;
+    const attributes = contentLanguageAttributes(env) ??
+        (fallback === UNDECLARED_CONTENT_LANGUAGE
+            ? { lang: "", dir: "auto" }
+            : contentLanguageAttributes({ locale: fallback }));
+    if (attributes) {
+        target.setAttribute("lang", attributes.lang);
+        target.setAttribute("dir", attributes.dir);
+    }
+    else {
+        target.removeAttribute("lang");
+        target.removeAttribute("dir");
+    }
+}
+/** Scripts written right to left, for {@link firstStrongDirection}. */
+const RTL_LETTER = /[\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}\p{Script=Adlam}\p{Script=Hanifi_Rohingya}\p{Script=Mandaic}\p{Script=Samaritan}]/u;
+const LETTER = /\p{L}/u;
+/**
+ * The direction of the first letter in `root`'s text, skipping `script`,
+ * `style` and `template`, or `null` when it has none. Letters only, which is
+ * where the bidi algorithm's strong characters overwhelmingly sit.
+ */
+export function firstStrongDirection(root) {
+    const doc = root.ownerDocument ?? root;
+    const walker = doc.createTreeWalker(root, 4 /* NodeFilter.SHOW_TEXT */, {
+        acceptNode: (node) => node.parentElement?.closest("script, style, template")
+            ? 2 /* NodeFilter.FILTER_REJECT */
+            : 1 /* NodeFilter.FILTER_ACCEPT */,
+    });
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        for (const char of node.nodeValue ?? "") {
+            if (RTL_LETTER.test(char))
+                return "rtl";
+            if (LETTER.test(char))
+                return "ltr";
+        }
+    }
+    return null;
+}
+/**
+ * The mismatch between undeclared content's script and the direction a
+ * fallback stamped on `root`, or `null` when there is none to report: the env
+ * declares a language, `root` carries no stamped direction or `dir="auto"`, or
+ * the content has no letters.
+ */
+export function undeclaredDirectionMismatch(root, env) {
+    if (contentLanguageAttributes(env))
+        return null;
+    const stamped = root.getAttribute("dir");
+    if (stamped !== "ltr" && stamped !== "rtl")
+        return null;
+    const script = firstStrongDirection(root);
+    if (!script)
+        return null;
+    return script === stamped ? null : { stamped, script };
+}