@pie-players/pie-language-tags 0.0.0-stage → 1.0.0-beta.9

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

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @pie-players/pie-language-tags
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+BCP 47 language tag lookup and matching for the two PIE i18n engines: pie-players'
+`@pie-players/pie-players-shared/i18n`, which re-exports it as
+`@pie-players/pie-players-shared/i18n/language-tags`, and pie-elements-ng's
+`@pie-element/shared-i18n`. The package carries no locale data, touches no DOM and
+has no dependencies, so it imports in a browser, in Node.js and in a server bundle
+alike.
+
+```ts
+import {
+	canonicalLanguageTag,
+	findBestLanguageMatch,
+	findClosestLanguageMatch,
+	languageTagLookupSequence,
+	negotiateContentLanguage,
+	normalizeLanguageTag,
+	toLanguageTag,
+} from "@pie-players/pie-language-tags";
+
+languageTagLookupSequence("zh-Hans-CN"); // ["zh-hans-cn", "zh-hans", "zh"]
+findBestLanguageMatch("es_MX", ["en-US", "es"]); // "es"
+toLanguageTag("es_ES"); // "es-ES"
+```
+
+Lookup follows RFC 4647: a tag widens by dropping its last subtag, and a script
+subtag is never crossed, so `zh-TW` reaches `zh-Hant` but not a bare `zh`. Widening
+to a sibling (`es-MX` to `es-ES`, through `findClosestLanguageMatch`) reaches only a
+sibling with the same variant subtags. POSIX forms (`es_ES`, `es_ES.UTF-8`) read as
+their BCP 47 tag.
+
+## Conformance spec
+
+`@pie-players/pie-language-tags/i18n-conformance-fixtures.json` is the behaviour
+the two engines share: lookup sequence, catalog matching, direction, plural
+routing, interpolation and the fallback chain. Each repository runs it against its
+own engine, so a case one engine passes and the other fails is drift, and the fix
+goes to the engine.

package/dist/i18n-conformance-fixtures.json

@@ -0,0 +1,270 @@
+{
+	"$comment": "Cross-repository conformance spec for the two PIE i18n engines: pie-players' players-shared/src/i18n and pie-elements-ng's @pie-element/shared-i18n, which share this package's language-tag code and keep their own providers. Both repositories read this one file from @pie-players/pie-language-tags and run it against their own engine. A case that only one engine passes is drift, and the fix goes to the engine, not the fixture. Locale tags are full where CLDR defaults differ by region: bare `ar` formats Latin digits and `ar-SA` Arabic-Indic, which is CLDR, not an engine.",
+	"lookupSequence": [
+		{ "tag": "nl-BE", "expected": ["nl-be", "nl"] },
+		{ "tag": "pt-BR", "expected": ["pt-br", "pt"] },
+		{ "tag": "zh-Hans-CN", "expected": ["zh-hans-cn", "zh-hans", "zh"] },
+		{ "tag": "sr-Latn-RS", "expected": ["sr-latn-rs", "sr-latn", "sr"] },
+		{ "tag": "es", "expected": ["es"] },
+		{ "tag": "und", "expected": ["und"] }
+	],
+	"catalogMatch": [
+		{
+			"locale": "zh-TW",
+			"available": ["en-US", "zh", "zh-Hant"],
+			"expected": "zh-Hant"
+		},
+		{ "locale": "zh-TW", "available": ["en-US", "zh"], "expected": "en-US" },
+		{ "locale": "zh-HK", "available": ["en-US", "zh"], "expected": "en-US" },
+		{
+			"locale": "zh-HK",
+			"available": ["en-US", "zh", "zh-TW"],
+			"expected": "zh-TW"
+		},
+		{ "locale": "zh-SG", "available": ["en-US", "zh"], "expected": "zh" },
+		{ "locale": "zh-CN", "available": ["en-US", "zh-TW"], "expected": "en-US" },
+		{ "locale": "zh", "available": ["en-US", "zh-TW"], "expected": "en-US" },
+		{
+			"locale": "sr-ME",
+			"available": ["en-US", "sr", "sr-Latn"],
+			"expected": "sr-Latn"
+		},
+		{ "locale": "sr-ME", "available": ["en-US", "sr"], "expected": "en-US" },
+		{ "locale": "sr-Cyrl-RS", "available": ["en-US", "sr"], "expected": "sr" },
+		{ "locale": "sr-Latn", "available": ["en-US", "sr"], "expected": "en-US" },
+		{
+			"locale": "sr-Latn",
+			"available": ["en-US", "sr-ME"],
+			"expected": "sr-ME"
+		},
+		{ "locale": "es-MX", "available": ["en-US", "es"], "expected": "es" },
+		{ "locale": "es_MX", "available": ["en-US", "es-ES"], "expected": "es-ES" },
+		{ "locale": "pt-BR", "available": ["en-US", "pt-PT"], "expected": "pt-PT" },
+		{
+			"locale": "de-CH-1996",
+			"available": ["en-US", "de-DE"],
+			"expected": "en-US"
+		},
+		{
+			"locale": "ca-ES-valencia",
+			"available": ["en-US", "ca-AD", "ca-AD-valencia"],
+			"expected": "ca-AD-valencia"
+		},
+		{
+			"locale": "en-AU",
+			"available": ["en-GB-x-gulf", "en-US"],
+			"expected": "en-US"
+		}
+	],
+	"direction": [
+		{ "tag": "ar-SA", "expected": "rtl" },
+		{ "tag": "he", "expected": "rtl" },
+		{ "tag": "fa", "expected": "rtl" },
+		{ "tag": "ur", "expected": "rtl" },
+		{ "tag": "en-US", "expected": "ltr" },
+		{ "tag": "nl-NL", "expected": "ltr" },
+		{ "tag": "zh-Hans-CN", "expected": "ltr" }
+	],
+	"plural": {
+		"catalogs": {
+			"en-US": { "items": { "one": "{count} o", "other": "{count} x" } },
+			"ar-SA": {
+				"items": {
+					"zero": "{count} z",
+					"one": "{count} o",
+					"two": "{count} t",
+					"few": "{count} f",
+					"many": "{count} m",
+					"other": "{count} x"
+				}
+			},
+			"pl-PL": {
+				"items": {
+					"one": "{count} o",
+					"few": "{count} f",
+					"many": "{count} m",
+					"other": "{count} x"
+				}
+			}
+		},
+		"cases": [
+			{ "locale": "en-US", "count": 1, "expected": "1 o" },
+			{ "locale": "en-US", "count": 0, "expected": "0 x" },
+			{ "locale": "en-US", "count": 1234.5, "expected": "1,234.5 x" },
+			{ "locale": "ar-SA", "count": 0, "expected": "٠ z" },
+			{ "locale": "ar-SA", "count": 1, "expected": "١ o" },
+			{ "locale": "ar-SA", "count": 2, "expected": "٢ t" },
+			{ "locale": "ar-SA", "count": 5, "expected": "٥ f" },
+			{ "locale": "ar-SA", "count": 11, "expected": "١١ m" },
+			{ "locale": "ar-SA", "count": 100, "expected": "١٠٠ x" },
+			{ "locale": "ar-SA", "count": 103, "expected": "١٠٣ f" },
+			{ "locale": "pl-PL", "count": 1, "expected": "1 o" },
+			{ "locale": "pl-PL", "count": 2, "expected": "2 f" },
+			{ "locale": "pl-PL", "count": 5, "expected": "5 m" },
+			{ "locale": "pl-PL", "count": 22, "expected": "22 f" },
+			{ "locale": "pl-PL", "count": 25, "expected": "25 m" },
+			{ "locale": "pl-PL", "count": 1.5, "expected": "1,5 x" }
+		]
+	},
+	"interpolation": [
+		{
+			"locale": "en-US",
+			"template": "Hello {name}",
+			"values": { "name": "Ana" },
+			"expected": "Hello Ana"
+		},
+		{
+			"locale": "en-US",
+			"template": "{name} and {name}",
+			"values": { "name": "A" },
+			"expected": "A and A"
+		},
+		{
+			"locale": "en-US",
+			"template": "Keep {missing} literal",
+			"values": {},
+			"expected": "Keep {missing} literal"
+		},
+		{
+			"locale": "de-DE",
+			"template": "{count} Punkte",
+			"values": { "count": 1234.5 },
+			"expected": "1.234,5 Punkte"
+		},
+		{
+			"locale": "ar-SA",
+			"template": "{count}",
+			"values": { "count": 5 },
+			"expected": "٥"
+		}
+	],
+	"fallbackChain": {
+		"locale": "es-ES",
+		"source": { "a": "A", "b": "B" },
+		"shipped": { "a": "Á" },
+		"hostMessages": { "a": "Ä" },
+		"expected": { "a": "Ä", "b": "B", "nope.key": "nope.key" }
+	},
+	"scenarios": [
+		{
+			"name": "a host plural override of one category leaves the others to the catalog",
+			"locale": "en-US",
+			"source": {
+				"max": { "one": "{count} answer", "other": "{count} answers" }
+			},
+			"shipped": {},
+			"hostMessages": { "en-US": { "max": { "one": "Just {count} answer" } } },
+			"expected": {
+				"locale": "en-US",
+				"direction": "ltr",
+				"t": { "max": "{count} answers" },
+				"plural": [
+					{ "key": "max", "count": 1, "expected": "Just 1 answer" },
+					{ "key": "max", "count": 2, "expected": "2 answers" }
+				]
+			}
+		},
+		{
+			"name": "a host plural override in a shipped locale falls through to that locale's catalog per category",
+			"locale": "es",
+			"source": {
+				"max": { "one": "{count} answer", "other": "{count} answers" }
+			},
+			"shipped": {
+				"es": {
+					"max": { "one": "{count} respuesta", "other": "{count} respuestas" }
+				}
+			},
+			"hostMessages": { "es": { "max": { "one": "Solo {count} respuesta" } } },
+			"expected": {
+				"locale": "es",
+				"direction": "ltr",
+				"t": { "max": "{count} respuestas" },
+				"plural": [
+					{ "key": "max", "count": 1, "expected": "Solo 1 respuesta" },
+					{ "key": "max", "count": 2, "expected": "2 respuestas" }
+				]
+			}
+		},
+		{
+			"name": "a locale's own other form wins over the fallback's category",
+			"locale": "es",
+			"source": {
+				"max": { "one": "{count} answer", "other": "{count} answers" }
+			},
+			"shipped": { "es": { "max": { "other": "{count} respuestas" } } },
+			"hostMessages": {},
+			"expected": {
+				"locale": "es",
+				"direction": "ltr",
+				"t": { "max": "{count} respuestas" },
+				"plural": [{ "key": "max", "count": 1, "expected": "1 respuestas" }]
+			}
+		},
+		{
+			"name": "a regional host override layers over the shipped parent catalog",
+			"locale": "es-MX",
+			"source": { "a": "A", "b": "B", "c": "C" },
+			"shipped": { "es": { "a": "Á", "b": "Bé" } },
+			"hostMessages": { "es-MX": { "a": "Ä" } },
+			"expected": {
+				"locale": "es",
+				"direction": "ltr",
+				"t": { "a": "Ä", "b": "Bé", "c": "C" },
+				"plural": []
+			}
+		},
+		{
+			"name": "a parent host override reaches a regional request",
+			"locale": "es-MX",
+			"source": { "a": "A", "b": "B" },
+			"shipped": { "es": { "a": "Á", "b": "Bé" } },
+			"hostMessages": { "es": { "a": "Ä" } },
+			"expected": {
+				"locale": "es",
+				"direction": "ltr",
+				"t": { "a": "Ä", "b": "Bé" },
+				"plural": []
+			}
+		},
+		{
+			"name": "host messages match the request whatever their tag's casing",
+			"locale": "es",
+			"source": { "a": "A", "b": "B" },
+			"shipped": { "es": { "a": "Á", "b": "Bé" } },
+			"hostMessages": { "ES": { "a": "Ä" } },
+			"expected": {
+				"locale": "es",
+				"direction": "ltr",
+				"t": { "a": "Ä", "b": "Bé" },
+				"plural": []
+			}
+		},
+		{
+			"name": "a locale nothing serves reports the fallback it is served in",
+			"locale": "he",
+			"source": { "a": "A" },
+			"shipped": { "es": { "a": "Á" } },
+			"hostMessages": {},
+			"expected": {
+				"locale": "en-US",
+				"direction": "ltr",
+				"t": { "a": "A" },
+				"plural": []
+			}
+		},
+		{
+			"name": "a locale served by host messages alone reports the host-message locale",
+			"locale": "he-IL",
+			"source": { "a": "A", "b": "B" },
+			"shipped": {},
+			"hostMessages": { "he": { "a": "א" } },
+			"expected": {
+				"locale": "he",
+				"direction": "rtl",
+				"t": { "a": "א", "b": "B" },
+				"plural": []
+			}
+		}
+	]
+}

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * BCP-47 language tag comparison, the one implementation both PIE i18n engines
+ * run: players-shared re-exports it as
+ * `@pie-players/pie-players-shared/i18n/language-tags`, and pie-elements-ng's
+ * `@pie-element/shared-i18n` imports it.
+ *
+ * Deliberately carries no locale data and no DOM access: this module is the one
+ * piece of language machinery that everything else needs, including the
+ * accessibility catalog resolver and TTS voice selection, neither of which wants
+ * a message catalog.
+ *
+ * Content producers do not agree on tag syntax. The Learnosity transform emits
+ * POSIX `es_ES`, QTI catalog cards carry BCP-47 `xml:lang`, and pie-elements-ng
+ * carried a hand-written POSIX-to-BCP-47 mapping table of its own. Comparing
+ * with `===`, as the catalog resolver did, means an `es_ES` card matches no
+ * request for `es-ES` and surfaces only through a no-language-constraint
+ * fallback — resolution by accident.
+ *
+ * @module @pie-players/pie-language-tags
+ */
+/**
+ * Canonicalize a language tag for comparison.
+ *
+ * Converts POSIX underscores to hyphens, strips a POSIX charset or modifier
+ * suffix (`es_ES.UTF-8`, `es_ES@euro`), and lowercases. Lowercasing rather than
+ * applying BCP-47 display casing is intentional — this output is a comparison
+ * key, not something to render. `toLanguageTag` is the form to render.
+ *
+ * Returns an empty string for nullish or blank input, which callers read as
+ * "this card declares no language".
+ */
+export declare function normalizeLanguageTag(tag: string | null | undefined): string;
+/**
+ * A tag in BCP-47 syntax with its authored casing kept: POSIX underscores become
+ * hyphens, so `es_ES` renders as `es-ES`. The form for a `lang` attribute or a
+ * platform locale API.
+ *
+ * Returns an empty string for nullish or blank input.
+ */
+export declare function toLanguageTag(tag: string | null | undefined): string;
+/**
+ * Whether two language tags denote the same locale, ignoring separator style and
+ * case. Two tags that both declare no language are not a match.
+ */
+export declare function languageTagsEqual(a: string | null | undefined, b: string | null | undefined): boolean;
+/**
+ * The RFC 4647 lookup sequence for a tag, most specific first.
+ *
+ * `es-MX` yields `["es-mx", "es"]`, so a request for Mexican Spanish reaches a
+ * card tagged plain `es` without also reaching one tagged `es-ES`. Truncation
+ * never stops on a singleton subtag (`x`, `u`), per RFC 4647 §3.4, and never
+ * produces a bare region or script.
+ */
+export declare function languageTagLookupSequence(tag: string | null | undefined): string[];
+/**
+ * The script a tag is written in, lowercased: explicit (`sr-Latn`), or the
+ * CLDR likely script (`zh-TW` maximizes to Hant, `sr` to Cyrl). `undefined`
+ * when the tag has no script data or the runtime has no `Intl.Locale`.
+ */
+export declare function languageTagScript(tag: string | null | undefined): string | undefined;
+/**
+ * Whether a catalog reached by widening serves a request in the same script.
+ * A tag without script data passes, so a runtime without `Intl.Locale`
+ * resolves as plain RFC 4647 lookup.
+ */
+export declare function languageTagScriptsMatch(requested: string | null | undefined, candidate: string | null | undefined): boolean;
+/**
+ * The script-aware lookup sequence: the RFC 4647 sequence with the language
+ * and likely script inserted before the bare language, so `zh-TW` yields
+ * `["zh-tw", "zh-hant", "zh"]`. A bare-language step serves the request only
+ * in the same script, which `findBestLanguageMatch` checks.
+ */
+export declare function languageTagScriptLookupSequence(tag: string | null | undefined): string[];
+/**
+ * Best available tag for a request, or `undefined` when nothing matches.
+ * Ranking is by the request's specificity rather than the candidates' order,
+ * so `es-MX` prefers an `es-MX` candidate over an `es` one however they were
+ * authored, and `zh-TW` reaches `zh-Hant`. A catalog shorter than the request
+ * serves it only in the same script: a bare `zh` catalog is Simplified, so
+ * `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`. 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;
+     * `"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
+ * first `requested` tag that has one, under `findClosestLanguageMatch`, or with
+ * `matching: "exact"` only an equal tag, so `es-MX` then passes an `es`
+ * variant by. With no match and `fallback` other than `"none"`, the fallback
+ * 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. 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;
+    fallback?: "default" | "none";
+    matching?: "closest" | "exact";
+    /** The family source's `available` entry. */
+    source?: string | null;
+}): ContentLanguageMatch | undefined;
+/**
+ * The canonical form of a usable language tag, or `undefined` for anything a
+ * language in use would not be: `es_MX` normalizes to `es-MX`, `NL-nl` to
+ * `nl-NL`, and `Spanish` or an empty string are not tags. One rule for every
+ * `lang` this repository writes — content and chrome alike — and the same rule
+ * the PIE elements apply to `model.language`, so every stamped attribute on a
+ * page carries the same shape.
+ */
+export declare function canonicalLanguageTag(language: string | null | undefined): string | undefined;

package/dist/index.js

@@ -0,0 +1,291 @@
+/**
+ * BCP-47 language tag comparison, the one implementation both PIE i18n engines
+ * run: players-shared re-exports it as
+ * `@pie-players/pie-players-shared/i18n/language-tags`, and pie-elements-ng's
+ * `@pie-element/shared-i18n` imports it.
+ *
+ * Deliberately carries no locale data and no DOM access: this module is the one
+ * piece of language machinery that everything else needs, including the
+ * accessibility catalog resolver and TTS voice selection, neither of which wants
+ * a message catalog.
+ *
+ * Content producers do not agree on tag syntax. The Learnosity transform emits
+ * POSIX `es_ES`, QTI catalog cards carry BCP-47 `xml:lang`, and pie-elements-ng
+ * carried a hand-written POSIX-to-BCP-47 mapping table of its own. Comparing
+ * with `===`, as the catalog resolver did, means an `es_ES` card matches no
+ * request for `es-ES` and surfaces only through a no-language-constraint
+ * fallback — resolution by accident.
+ *
+ * @module @pie-players/pie-language-tags
+ */
+/**
+ * Canonicalize a language tag for comparison.
+ *
+ * Converts POSIX underscores to hyphens, strips a POSIX charset or modifier
+ * suffix (`es_ES.UTF-8`, `es_ES@euro`), and lowercases. Lowercasing rather than
+ * applying BCP-47 display casing is intentional — this output is a comparison
+ * key, not something to render. `toLanguageTag` is the form to render.
+ *
+ * Returns an empty string for nullish or blank input, which callers read as
+ * "this card declares no language".
+ */
+export function normalizeLanguageTag(tag) {
+    if (!tag)
+        return "";
+    const separatorsUnified = tag.trim().replace(/_/g, "-");
+    const withoutPosixSuffix = separatorsUnified.split(/[.@]/)[0];
+    return withoutPosixSuffix.toLowerCase();
+}
+/**
+ * A tag in BCP-47 syntax with its authored casing kept: POSIX underscores become
+ * hyphens, so `es_ES` renders as `es-ES`. The form for a `lang` attribute or a
+ * platform locale API.
+ *
+ * Returns an empty string for nullish or blank input.
+ */
+export function toLanguageTag(tag) {
+    return tag ? tag.trim().replace(/_/g, "-") : "";
+}
+/**
+ * Whether two language tags denote the same locale, ignoring separator style and
+ * case. Two tags that both declare no language are not a match.
+ */
+export function languageTagsEqual(a, b) {
+    const left = normalizeLanguageTag(a);
+    if (!left)
+        return false;
+    return left === normalizeLanguageTag(b);
+}
+/**
+ * The RFC 4647 lookup sequence for a tag, most specific first.
+ *
+ * `es-MX` yields `["es-mx", "es"]`, so a request for Mexican Spanish reaches a
+ * card tagged plain `es` without also reaching one tagged `es-ES`. Truncation
+ * never stops on a singleton subtag (`x`, `u`), per RFC 4647 §3.4, and never
+ * produces a bare region or script.
+ */
+export function languageTagLookupSequence(tag) {
+    const normalized = normalizeLanguageTag(tag);
+    if (!normalized)
+        return [];
+    const subtags = normalized.split("-");
+    const sequence = [];
+    for (let length = subtags.length; length > 0; length--) {
+        const candidate = subtags.slice(0, length);
+        // A trailing singleton introduces an extension with nothing left in it.
+        if (candidate.length > 1 && candidate[candidate.length - 1].length === 1) {
+            continue;
+        }
+        sequence.push(candidate.join("-"));
+    }
+    return sequence;
+}
+/** `maximize()` runs on every resolution, for each candidate catalog. */
+const scripts = new Map();
+/**
+ * The script a tag is written in, lowercased: explicit (`sr-Latn`), or the
+ * CLDR likely script (`zh-TW` maximizes to Hant, `sr` to Cyrl). `undefined`
+ * when the tag has no script data or the runtime has no `Intl.Locale`.
+ */
+export function languageTagScript(tag) {
+    const normalized = normalizeLanguageTag(tag);
+    if (!normalized ||
+        typeof Intl === "undefined" ||
+        typeof Intl.Locale !== "function") {
+        return undefined;
+    }
+    if (scripts.has(normalized))
+        return scripts.get(normalized);
+    let script;
+    try {
+        script = new Intl.Locale(normalized).maximize().script?.toLowerCase();
+    }
+    catch {
+        // Not a tag `Intl.Locale` parses: no script data.
+    }
+    scripts.set(normalized, script);
+    return script;
+}
+/**
+ * Whether a catalog reached by widening serves a request in the same script.
+ * A tag without script data passes, so a runtime without `Intl.Locale`
+ * resolves as plain RFC 4647 lookup.
+ */
+export function languageTagScriptsMatch(requested, candidate) {
+    const requestedScript = languageTagScript(requested);
+    const candidateScript = languageTagScript(candidate);
+    return (!requestedScript || !candidateScript || requestedScript === candidateScript);
+}
+/**
+ * The script-aware lookup sequence: the RFC 4647 sequence with the language
+ * and likely script inserted before the bare language, so `zh-TW` yields
+ * `["zh-tw", "zh-hant", "zh"]`. A bare-language step serves the request only
+ * in the same script, which `findBestLanguageMatch` checks.
+ */
+export function languageTagScriptLookupSequence(tag) {
+    const sequence = languageTagLookupSequence(tag);
+    const script = languageTagScript(tag);
+    if (!script || sequence.length < 2)
+        return sequence;
+    const language = sequence[sequence.length - 1];
+    const withScript = `${language}-${script}`;
+    if (sequence.includes(withScript))
+        return sequence;
+    return [...sequence.slice(0, -1), withScript, language];
+}
+/**
+ * Best available tag for a request, or `undefined` when nothing matches.
+ * Ranking is by the request's specificity rather than the candidates' order,
+ * so `es-MX` prefers an `es-MX` candidate over an `es` one however they were
+ * authored, and `zh-TW` reaches `zh-Hant`. A catalog shorter than the request
+ * serves it only in the same script: a bare `zh` catalog is Simplified, so
+ * `zh-TW` passes it by.
+ */
+export function findBestLanguageMatch(requested, available) {
+    const exact = normalizeLanguageTag(requested);
+    for (const step of languageTagScriptLookupSequence(requested)) {
+        const hit = available.find((candidate) => normalizeLanguageTag(candidate) === step &&
+            (step === exact || languageTagScriptsMatch(requested, candidate)));
+        if (hit != null)
+            return hit;
+    }
+    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`. 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);
+    if (best !== undefined)
+        return best;
+    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;
+}
+/**
+ * The language to serve content in: the closest `available` match for the
+ * first `requested` tag that has one, under `findClosestLanguageMatch`, or with
+ * `matching: "exact"` only an equal tag, so `es-MX` then passes an `es`
+ * variant by. With no match and `fallback` other than `"none"`, the fallback
+ * 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. 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"
+            ? 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, candidates);
+    if (language === undefined && available.includes(null))
+        language = null;
+    if (language === undefined &&
+        source !== undefined &&
+        available.includes(source)) {
+        language = source;
+    }
+    if (language === undefined)
+        return undefined;
+    return requested.length > 0
+        ? { language, substitution: "fallback" }
+        : { language };
+}
+/**
+ * The canonical form of a usable language tag, or `undefined` for anything a
+ * language in use would not be: `es_MX` normalizes to `es-MX`, `NL-nl` to
+ * `nl-NL`, and `Spanish` or an empty string are not tags. One rule for every
+ * `lang` this repository writes — content and chrome alike — and the same rule
+ * the PIE elements apply to `model.language`, so every stamped attribute on a
+ * page carries the same shape.
+ */
+export function canonicalLanguageTag(language) {
+    const tag = toLanguageTag(language).split(/[.@]/)[0];
+    // `Intl` accepts any 5-8 letter primary subtag, `Spanish` included; a
+    // language in use has an ISO 639 code of two or three letters.
+    if (!/^[a-z]{2,3}(-|$)/i.test(tag))
+        return undefined;
+    try {
+        return Intl.getCanonicalLocales(tag)[0];
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
-  "name": "@pie-players/pie-language-tags",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@pie-players/pie-language-tags",
+	"version": "1.0.0-beta.9",
+	"type": "module",
+	"description": "BCP 47 language tag lookup and matching shared by the PIE i18n engines, with the conformance spec both engines run",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pie-framework/pie-players.git",
+		"directory": "packages/pie-language-tags"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./i18n-conformance-fixtures.json": "./dist/i18n-conformance-fixtures.json",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp i18n-conformance-fixtures.json dist/",
+		"dev": "tsc -p tsconfig.json --watch",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json",
+		"lint": "biome lint .",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.6.4",
+		"typescript": "^5.9.3"
+	},
+	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/pie-language-tags#readme",
+	"bugs": {
+		"url": "https://github.com/pie-framework/pie-players/issues"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"sideEffects": false
+}