@pie-players/pie-players-shared 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/i18n/provider.js

@@ -9,7 +9,7 @@
  *
  * @module @pie-players/pie-players-shared/i18n/provider
  */
-import { findBestLanguageMatch, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+import { canonicalLanguageTag, findBestLanguageMatch, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
 import enUS from "./messages/en-US.js";
 /** The locale every fallback chain terminates at. */
 export const DEFAULT_LOCALE = "en-US";
@@ -118,7 +118,8 @@ export class SimpleI18n {
     config;
     constructor(config = {}) {
         this.config = { ...config };
-        this.fallbackLocale = toLanguageTag(config.fallbackLocale) || DEFAULT_LOCALE;
+        this.fallbackLocale =
+            toLanguageTag(config.fallbackLocale) || DEFAULT_LOCALE;
         this.catalogs = new Map([[DEFAULT_LOCALE, enUS]]);
         this.customMessages = { ...(config.customMessages ?? {}) };
         this.loading = new Map();
@@ -190,7 +191,7 @@ export class SimpleI18n {
             this.config.onMissingKey?.(key, this.locale);
             return key;
         }
-        return interpolate(message, values);
+        return interpolate(message, values, this.locale);
     }
     /**
      * Translate a plural group.
@@ -207,7 +208,7 @@ export class SimpleI18n {
         }
         const category = this.selectPluralCategory(options.count);
         const form = group[category] ?? group.other;
-        return interpolate(form, options);
+        return interpolate(form, options, this.locale);
     }
     getDirection() {
         return localeDirection(this.locale);
@@ -389,12 +390,41 @@ function readPath(source, key) {
     }
     return current;
 }
-function interpolate(text, values) {
+/**
+ * Substitute `{name}` placeholders.
+ *
+ * A finite numeric value renders through `Intl.NumberFormat` for the active
+ * locale, so digits and grouping follow CLDR locale defaults: `ar` renders
+ * Arabic-Indic digits, `fr` groups with narrow no-break spaces, `en-US` with
+ * commas. Catalog text that spells digits out is untouched.
+ */
+const numberFormats = new Map();
+function formatNumber(value, locale) {
+    let formatter = numberFormats.get(locale);
+    if (!formatter) {
+        try {
+            formatter = new Intl.NumberFormat(locale);
+        }
+        catch {
+            formatter = new Intl.NumberFormat(DEFAULT_LOCALE);
+        }
+        numberFormats.set(locale, formatter);
+    }
+    return formatter.format(value);
+}
+function interpolate(text, values, locale) {
     if (!values)
         return text;
     return text.replace(/\{(\w+)\}/g, (match, name) => {
         const value = values[name];
-        return value === undefined || value === null ? match : String(value);
+        if (value === undefined || value === null)
+            return match;
+        if (locale !== undefined &&
+            typeof value === "number" &&
+            Number.isFinite(value)) {
+            return formatNumber(value, locale);
+        }
+        return String(value);
     });
 }
 function deepMerge(target, source) {
@@ -428,41 +458,51 @@ export function getDefaultI18n() {
         defaultProvider = new SimpleI18n();
     return defaultProvider;
 }
-/**
- * Resolve a component's interface-locale provider from a published context.
- *
- * Returns a **fresh** object on every call. A
- * provider is mutable: `setLocale` swaps its catalog in place, so its identity is
- * unchanged before and after a locale load. A reactive `$derived` reading the
- * provider directly therefore never invalidates, and a label rendered while the
- * catalog was still loading stays English forever — the exact silent failure
- * `composition-context.md` records for a context published without a change
- * signal, and it is silent here too because English is a plausible answer.
- *
- * Deriving this instead gives the component a value whose identity tracks the
- * context republish, so the strings built from it re-render. Call it inside
- * `$derived`, never once at setup:
- *
- * ```ts
- * const interfaceI18n = $derived(resolveInterfaceI18n(runtimeContext));
- * ```
- *
- * A context with no provider — no publisher at all — resolves to the English-only
- * default rather than nothing, which is the graceful default the pull pattern
- * requires.
- */
 export function resolveInterfaceI18n(source) {
     const provider = source?.i18n ?? getDefaultI18n();
     // A thin facade rather than the provider itself: cheap to allocate (a handful
     // of times per session, once per republish) and it carries no state of its own,
-    // so it cannot drift from the provider it delegates to.
+    // so it cannot drift from the provider it delegates to. The locale formatters
+    // are part of the promised surface, so a provider that does not implement
+    // them falls through to `Intl` at the locale the provider resolves — the same
+    // thing the bundled provider does, and the same graceful default every other
+    // optional member here applies.
     return {
-        getLocale: () => provider.getLocale(),
+        // Canonical, because components read this for `lang` attributes; the
+        // provider's own `getLocale()` keeps the tag as resolved for lookups.
+        getLocale: () => {
+            const locale = provider.getLocale();
+            return canonicalLanguageTag(locale) ?? locale;
+        },
         setLocale: (locale) => provider.setLocale(locale),
         t: (key, values) => provider.t(key, values),
         plural: (key, options) => provider.plural?.(key, options) ?? provider.t(key, options),
         getDirection: () => provider.getDirection?.() ?? "ltr",
         hasKey: (key) => provider.hasKey?.(key) ?? false,
         subscribe: (listener) => provider.subscribe?.(listener) ?? (() => { }),
+        formatNumber: (value, options) => provider.formatNumber?.(value, options) ??
+            new Intl.NumberFormat(provider.getLocale(), options).format(value),
+        formatDate: (value, options) => provider.formatDate?.(value, options) ??
+            new Intl.DateTimeFormat(provider.getLocale(), options).format(value),
     };
 }
+/**
+ * Stamp the interface locale's `lang` and `dir` on a chrome element.
+ *
+ * The imperative form of the `lang={…} dir={…}` pair a template puts on its
+ * root, for the elements a template cannot reach: a shadow host whose chrome
+ * is slotted light DOM, a shell built with `document.createElement`, a vanilla
+ * element stamping itself. Call it from whatever already re-runs on a locale
+ * change and on a catalog load: `getLocale()` moves only once the requested
+ * catalog is resident, so a stamp taken at setup alone names the locale that
+ * rendered before the load.
+ */
+export function stampInterfaceLocale(target, provider) {
+    // `lang` takes the canonical form: a provider honours an unshipped tag as
+    // the host spelled it, and `NL-nl` is a valid request but not a valid
+    // attribute value. Every `lang` this repository writes goes through the
+    // same rule, so chrome and content stamps match in shape.
+    const locale = provider.getLocale();
+    target.setAttribute("lang", canonicalLanguageTag(locale) ?? locale);
+    target.setAttribute("dir", provider.getDirection?.() ?? "ltr");
+}

package/dist/i18n/pseudo.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pseudo-localization: a transform over the English catalog that keeps every key,
+ * plural category and `{placeholder}` intact while making each string accented,
+ * bracketed and padded roughly 40% longer.
+ *
+ * What it is for: the gates check parity, not rendered geometry. A pseudo-locale
+ * makes truncation, clipped labels, strings glued together in code and text that
+ * was never catalog text visible in any demo or e2e run, before a translator or a
+ * reviewer sees a real one. It is the industry's `qps-ploc` (Windows) and
+ * `en-XA`/`ar-XB` (Android) practice; PIE uses the Android tags, registered
+ * through `customMessages`, never shipped as catalogs.
+ */
+import type { MessageCatalog } from "./types.js";
+/** Expanded Latin pseudo-locale: text grows ~40% and carries accents and brackets. */
+export declare const PSEUDO_LOCALE_EXPANDED = "en-XA";
+/**
+ * Right-to-left pseudo-locale: the same transformed English under an `ar` primary
+ * subtag, so `localeDirection` resolves RTL and chrome lays out mirrored without a
+ * word of Arabic on screen.
+ */
+export declare const PSEUDO_LOCALE_RTL = "ar-XB";
+export interface PseudoLocalizeOptions {
+    /** Extra length as a fraction of the original, on top of what accents add. Default 0.4. */
+    expansion?: number;
+    /** Wrap every string in `[` and `]` so concatenated fragments stand out. Default true. */
+    brackets?: boolean;
+    /** Map Latin letters to accented look-alikes. Default true. */
+    accents?: boolean;
+}
+/**
+ * Produce the pseudo-localized twin of a catalog: same keys, same plural
+ * categories, same placeholder sets, longer accented bracketed strings.
+ */
+export declare function pseudoLocalize(catalog: MessageCatalog, options?: PseudoLocalizeOptions): MessageCatalog;

package/dist/i18n/pseudo.js

@@ -0,0 +1,106 @@
+/** Expanded Latin pseudo-locale: text grows ~40% and carries accents and brackets. */
+export const PSEUDO_LOCALE_EXPANDED = "en-XA";
+/**
+ * Right-to-left pseudo-locale: the same transformed English under an `ar` primary
+ * subtag, so `localeDirection` resolves RTL and chrome lays out mirrored without a
+ * word of Arabic on screen.
+ */
+export const PSEUDO_LOCALE_RTL = "ar-XB";
+const ACCENTS = {
+    a: "á",
+    A: "Á",
+    b: "ƀ",
+    B: "Ƀ",
+    c: "ç",
+    C: "Ç",
+    d: "ð",
+    D: "Ð",
+    e: "é",
+    E: "É",
+    f: "ƒ",
+    F: "Ƒ",
+    g: "ğ",
+    G: "Ğ",
+    h: "ĥ",
+    H: "Ĥ",
+    i: "í",
+    I: "Í",
+    j: "ĵ",
+    J: "Ĵ",
+    k: "ķ",
+    K: "Ķ",
+    l: "ĺ",
+    L: "Ĺ",
+    m: "ḿ",
+    M: "Ḿ",
+    n: "ñ",
+    N: "Ñ",
+    o: "ó",
+    O: "Ó",
+    p: "þ",
+    P: "Þ",
+    q: "ǫ",
+    Q: "Ǫ",
+    r: "ŕ",
+    R: "Ŕ",
+    s: "š",
+    S: "Š",
+    t: "ŧ",
+    T: "Ŧ",
+    u: "ú",
+    U: "Ú",
+    v: "ṽ",
+    V: "Ṽ",
+    w: "ŵ",
+    W: "Ŵ",
+    x: "ẋ",
+    X: "Ẋ",
+    y: "ý",
+    Y: "Ý",
+    z: "ž",
+    Z: "Ž",
+};
+const PLACEHOLDER = /(\{\w+\})/g;
+function pseudoText(text, { expansion, accents, brackets }) {
+    const segments = text.split(PLACEHOLDER);
+    const transformed = segments.map((segment, index) => {
+        // A capturing split leaves each placeholder at an odd index, verbatim.
+        if (index % 2 === 1 || segment === "")
+            return segment;
+        let out = segment;
+        if (accents) {
+            out = out.replace(/[a-zA-Z]/g, (letter) => ACCENTS[letter] ?? letter);
+        }
+        if (expansion <= 0)
+            return out;
+        const padding = Math.max(1, Math.ceil(segment.length * expansion));
+        return `${out} ${"~".repeat(padding)}`;
+    });
+    const joined = transformed.join("");
+    return brackets ? `[${joined}]` : joined;
+}
+/**
+ * Produce the pseudo-localized twin of a catalog: same keys, same plural
+ * categories, same placeholder sets, longer accented bracketed strings.
+ */
+export function pseudoLocalize(catalog, options) {
+    const settings = {
+        expansion: options?.expansion ?? 0.4,
+        brackets: options?.brackets ?? true,
+        accents: options?.accents ?? true,
+    };
+    const result = {};
+    for (const [key, node] of Object.entries(catalog)) {
+        result[key] = pseudoNode(node, settings);
+    }
+    return result;
+}
+function pseudoNode(node, settings) {
+    if (typeof node === "string")
+        return pseudoText(node, settings);
+    const branch = {};
+    for (const [key, child] of Object.entries(node)) {
+        branch[key] = pseudoNode(child, settings);
+    }
+    return branch;
+}

package/dist/loaders/esm-adapter.d.ts

@@ -85,4 +85,14 @@ export declare function resolveEsmAssetRoot(options: {
     cdnBaseUrl: string;
     cdnProvider?: EsmCdnProviderOption;
 }): string | undefined;
+/**
+ * URL of a raw npm package file, `file` being `<package>@<version>/<path>`, on
+ * the ESM CDN a player's `loaderOptions` name, so a page asset the players add,
+ * such as a stylesheet, comes from where the elements do. Reads untyped options
+ * as a toolkit runtime context carries them; jsDelivr when they set no base.
+ */
+export declare function resolveEsmPackageFileUrl(loaderOptions: {
+    esmCdnUrl?: unknown;
+    esmCdnProvider?: unknown;
+} | null | undefined, file: string): string;
 export declare function pickElementClass(module: any, view: string): unknown;

package/dist/loaders/esm-adapter.js

@@ -19,6 +19,7 @@ import { writeRegistryEntry } from "../pie/registry.js";
 import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
+import { DEFAULT_ESM_CDN_URL } from "./defaults.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { isExactSemver } from "./element-package-policy.js";
 import { invalidPackageSpecMessage, isScopedPackageSpec, } from "./element-package-spec.js";
@@ -141,8 +142,11 @@ export function createEsmBackend(config) {
                 : undefined;
             const imports = withoutMappedSpecifiers({ ...importMapResult.imports, ...runtimePlan?.imports }, context.doc);
             let injectedMap;
+            let map;
             if (Object.keys(imports).length > 0) {
-                const json = JSON.stringify({ imports }, null, 2);
+                const scopes = withoutMappedScopes(jsDelivrRootPathScopes(cdnProvider, cdnBaseUrl, context.doc), context.doc);
+                map = scopes ? { imports, scopes } : { imports };
+                const json = JSON.stringify(map, null, 2);
                 // URL resolution maps the shared dependencies and the editor
                 // runtime, so it needs import maps too.
                 assertImportMapSupported();
@@ -162,8 +166,8 @@ export function createEsmBackend(config) {
                     importMappedPackageVersions.set(parsePackageName(pkg).name, pkg);
                 }
             }
-            if (injectedMap) {
-                await applyImportMap(imports, injectedMap, context.doc);
+            if (injectedMap && map) {
+                await applyImportMap(map, injectedMap, context.doc);
             }
         }
         await Promise.all(Object.entries(loadable).map(async ([tag, packageVersion]) => {
@@ -339,13 +343,13 @@ export function createEsmBackend(config) {
      * document that already uses it, and otherwise the browser has either
      * applied it or rejected it.
      */
-    async function applyImportMap(imports, script, doc) {
+    async function applyImportMap(map, script, doc) {
         let state = "applied";
         try {
             if (script.type === SHIM_IMPORT_MAP_TYPE) {
-                (await importShim(doc)).addImportMap({ imports });
+                (await importShim(doc)).addImportMap(map);
             }
-            else if (await importMapRejected(imports)) {
+            else if (await importMapRejected(map.imports)) {
                 state = "rejected";
                 await importShim(doc);
             }
@@ -384,7 +388,7 @@ export function createEsmBackend(config) {
      */
     function importShim(doc) {
         importShimRequest ??= importShimLoader().then((shim) => {
-            shim.addImportMap({ imports: documentImports(doc) });
+            shim.addImportMap(documentImportMap(doc));
             return shim;
         }, (err) => {
             importShimRequest = undefined;
@@ -661,6 +665,24 @@ export function resolveEsmAssetRoot(options) {
         ? packageJsonUrl.slice(0, -suffix.length) || undefined
         : undefined;
 }
+/**
+ * URL of a raw npm package file, `file` being `<package>@<version>/<path>`, on
+ * the ESM CDN a player's `loaderOptions` name, so a page asset the players add,
+ * such as a stylesheet, comes from where the elements do. Reads untyped options
+ * as a toolkit runtime context carries them; jsDelivr when they set no base.
+ */
+export function resolveEsmPackageFileUrl(loaderOptions, file) {
+    const configured = loaderOptions?.esmCdnUrl;
+    const cdnBaseUrl = (typeof configured === "string" && configured.trim()
+        ? configured.trim()
+        : DEFAULT_ESM_CDN_URL).replace(/\/+$/, "");
+    const provider = loaderOptions?.esmCdnProvider;
+    const cdnProvider = typeof provider === "string" || isEsmCdnProvider(provider)
+        ? provider
+        : undefined;
+    const root = resolveEsmAssetRoot({ cdnBaseUrl, cdnProvider }) ?? cdnBaseUrl;
+    return `${root}/${file.replace(/^\/+/, "")}`;
+}
 function resolveCdnProvider(provider, cdnBaseUrl) {
     if (isEsmCdnProvider(provider))
         return provider;
@@ -681,7 +703,7 @@ function isEsmCdnProvider(value) {
         typeof candidate.sharedDependencyUrl === "function");
 }
 function createJsDelivrProvider(cdnBaseUrl, name = "jsdelivr") {
-    return {
+    const provider = {
         name,
         packageJsonUrl: (packageVersion) => `${cdnBaseUrl}/${packageVersion}/package.json`,
         browserViewUrl: (packageVersion, view) => `${cdnBaseUrl}/${packageVersion}/dist/browser/${view}/index.js`,
@@ -692,7 +714,31 @@ function createJsDelivrProvider(cdnBaseUrl, name = "jsdelivr") {
             return `${cdnBaseUrl}/${dependencyName}@${version}${suffix}`;
         },
     };
+    jsDelivrShapedProviders.add(provider);
+    return provider;
 }
+/**
+ * jsDelivr's `+esm` builds import their dependencies by root path
+ * (`/npm/react@18.3.1/+esm`), which resolves against the origin that served
+ * them. A base mounted anywhere but `/npm` gets a scope mapping those paths
+ * back under it, so they load from the configured CDN and resolve to the URLs
+ * the shared-dependency entries map, keeping one React on the page.
+ */
+function jsDelivrRootPathScopes(cdnProvider, cdnBaseUrl, doc) {
+    if (!jsDelivrShapedProviders.has(cdnProvider))
+        return undefined;
+    let base;
+    try {
+        base = new URL(`${cdnBaseUrl}/`, doc.baseURI || undefined);
+    }
+    catch {
+        return undefined;
+    }
+    const root = new URL("/npm/", base).href;
+    return root === base.href ? undefined : { [base.href]: { [root]: base.href } };
+}
+/** Providers built by {@link createJsDelivrProvider}, whatever their name. */
+const jsDelivrShapedProviders = new WeakSet();
 function createEsmShProvider(cdnBaseUrl) {
     const esmBaseUrl = cdnBaseUrl.replace(/\/+$/, "");
     const rawBaseUrl = toRawEsmShBaseUrl(esmBaseUrl);
@@ -1050,23 +1096,50 @@ async function importMapsSettled(doc) {
  * for a specifier as it does in the browser.
  */
 function documentImports(doc) {
+    return documentImportMap(doc).imports;
+}
+/** {@link documentImports}, with the scopes the maps define. */
+function documentImportMap(doc) {
     const imports = Object.create(null);
+    const scopes = Object.create(null);
     for (const script of importMapScripts(doc)) {
         try {
-            const mapped = JSON.parse(script.textContent || "{}")?.imports;
-            if (!mapped || typeof mapped !== "object")
+            const map = JSON.parse(script.textContent || "{}");
+            addFirstRules(imports, map?.imports);
+            if (!map?.scopes || typeof map.scopes !== "object")
                 continue;
-            for (const [specifier, url] of Object.entries(mapped)) {
-                if (typeof url === "string" && !(specifier in imports)) {
-                    imports[specifier] = url;
-                }
+            for (const [scope, rules] of Object.entries(map.scopes)) {
+                scopes[scope] ??= Object.create(null);
+                addFirstRules(scopes[scope], rules);
             }
         }
         catch {
             // The browser rejects a map it cannot parse, so it maps nothing.
         }
     }
-    return imports;
+    return { imports, scopes };
+}
+function addFirstRules(target, rules) {
+    if (!rules || typeof rules !== "object")
+        return;
+    for (const [specifier, url] of Object.entries(rules)) {
+        if (typeof url === "string" && !(specifier in target)) {
+            target[specifier] = url;
+        }
+    }
+}
+/** {@link withoutMappedSpecifiers} for scope rules; `undefined` when none remain. */
+function withoutMappedScopes(scopes, doc) {
+    if (!scopes)
+        return undefined;
+    const mapped = documentImportMap(doc).scopes;
+    const remaining = {};
+    for (const [scope, rules] of Object.entries(scopes)) {
+        const kept = Object.entries(rules).filter(([specifier]) => !(specifier in (mapped[scope] ?? {})));
+        if (kept.length > 0)
+            remaining[scope] = Object.fromEntries(kept);
+    }
+    return Object.keys(remaining).length > 0 ? remaining : undefined;
 }
 /**
  * es-module-shims in shim mode: it resolves through the import maps this

package/dist/loaders/index.d.ts

@@ -38,7 +38,7 @@ export { isScopedPackageSpec } from "./element-package-spec.js";
 export type { BackendContext, BackendOption, ElementLoaderBackend, ElementTag, EnsureRegisteredOptions, EsmBackendConfig, IifeBackendConfig, RegistrationFailureReason, } from "./element-loader.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
 export type { BuiltInEsmCdnProviderName, EsmBackend, EsmCdnProvider, EsmCdnProviderName, EsmCdnProviderOption, ViewConfig, } from "./esm-adapter.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmPackageFileUrl, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
 export type { IifeBackend, IifeBundleRetryStatus, } from "./iife-adapter.js";
 export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";
 export { DEFAULT_BUNDLE_HOST, DEFAULT_ESM_CDN_URL } from "./defaults.js";

package/dist/loaders/index.js

@@ -34,7 +34,7 @@ export { aggregateElements } from "./ElementLoader.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
 export { isScopedPackageSpec } from "./element-package-spec.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmPackageFileUrl, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
 export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";
 export { DEFAULT_BUNDLE_HOST, DEFAULT_ESM_CDN_URL } from "./defaults.js";
 export { createIifeBackend } from "./iife-adapter.js";

package/dist/loaders/preloaded-registration.d.ts

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -29,13 +34,20 @@ export interface PreloadedElement {
     /**
      * Base tag to register, e.g. `pie-element-multiple-choice`. Content can
      * author another base tag for the package, which the players define from
-     * this registration.
+     * this registration. Defaults to the package name without its `@`, with
+     * `-` for `/`.
+     */
+    tag?: string;
+    /**
+     * npm package name, e.g. `@pie-element/multiple-choice`. Defaults to the
+     * name in the modules' `piePackage`.
+     */
+    package?: string;
+    /**
+     * The installed version, exact, e.g. `13.4.4`. Defaults to the version in
+     * the modules' `piePackage`.
      */
-    tag: string;
-    /** npm package name, e.g. `@pie-element/multiple-choice`. */
-    package: string;
-    /** The installed version, exact, e.g. `13.4.4`. */
-    version: string;
+    version?: string;
     /** The package's `./browser/delivery` module, or its default export. */
     element: CustomElementConstructor | {
         readonly default: CustomElementConstructor;

package/dist/loaders/preloaded-registration.js

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -23,6 +28,7 @@
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
 import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
 import { writeRegistryEntry } from "../pie/registry.js";
+import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
 import { toPackageVersionedTag } from "../pie/versioned-tag.js";
@@ -69,15 +75,24 @@ export function registerPreloadedElements(elements, options = {}) {
 function resolveElement(element, index) {
     const at = `[registerPreloadedElements] entry ${index}`;
     if (!element || typeof element !== "object") {
-        throw new Error(`${at}: expected { tag, package, version, element }`);
+        throw new Error(`${at}: expected { element, controller?, tag?, package?, version? }`);
+    }
+    const identity = moduleIdentity(element, at);
+    if (!identity && element.package === undefined && element.version === undefined) {
+        throw new Error(`${at}: package and version are required for modules that export no piePackage`);
     }
-    const { package: packageName, version, tag } = element;
+    const packageName = element.package ?? identity?.name;
+    const version = element.version ?? identity?.version;
     if (!isBarePackageName(packageName)) {
         throw new Error(`${at}: package must be a bare package name, got ${JSON.stringify(packageName)}`);
     }
     if (typeof version !== "string" || !isExactSemver(version)) {
         throw new Error(`${at} (${packageName}): version must be the installed version, exact, such as 1.2.3; got ${JSON.stringify(version)}`);
     }
+    if (identity && (identity.name !== packageName || identity.version !== version)) {
+        throw new Error(`${at}: the modules were built from ${identity.name}@${identity.version}, not ${packageName}@${version}`);
+    }
+    const tag = element.tag ?? packageName.replace(/^@/, "").replace("/", "-");
     if (typeof tag !== "string" || !tag) {
         throw new Error(`${at} (${packageName}): tag must be the base tag to register, got ${JSON.stringify(tag)}`);
     }
@@ -95,13 +110,33 @@ function resolveElement(element, index) {
         }
     }
     const spec = `${packageName}@${version}`;
-    return {
-        packageName,
-        spec,
-        tagName: toPackageVersionedTag(tag, spec),
-        elementClass: candidate,
-        controller,
-    };
+    const tagName = validateCustomElementTag(toPackageVersionedTag(tag, spec), element.tag === undefined
+        ? `${at} (${packageName}) tag derived from the package name; give tag`
+        : `${at} (${packageName}) tag`);
+    return { packageName, spec, tagName, elementClass: candidate, controller };
+}
+/** The `piePackage` of the entry's modules, which agree when both export one. */
+function moduleIdentity(element, at) {
+    const fromElement = readPackageIdentity(element.element, `${at}: element`);
+    const fromController = readPackageIdentity(element.controller, `${at}: controller`);
+    if (fromElement &&
+        fromController &&
+        (fromElement.name !== fromController.name ||
+            fromElement.version !== fromController.version)) {
+        throw new Error(`${at}: the element module is ${fromElement.name}@${fromElement.version}, ` +
+            `but the controller module is ${fromController.name}@${fromController.version}`);
+    }
+    return fromElement ?? fromController;
+}
+function readPackageIdentity(module, at) {
+    if (!module || typeof module !== "object" || !("piePackage" in module)) {
+        return undefined;
+    }
+    const identity = module.piePackage;
+    if (typeof identity?.name !== "string" || typeof identity.version !== "string") {
+        throw new Error(`${at} module's piePackage must be { name, version }`);
+    }
+    return { name: identity.name, version: identity.version };
 }
 function resolveController(value) {
     if (!value || typeof value !== "object")

package/dist/pie/index.d.ts

@@ -15,6 +15,7 @@ export type { PieElementContext, PieElementContextSource, } from "./element-obse
 export { createAuthoringAssetEventManager, initializeAuthoringConfigures, resolveConfigureConfiguration, validateAuthoringModels, } from "./authoring.js";
 export type { AuthoringMediaHandlers, AuthoringValidationResult, InitializedConfigureModel, } from "./authoring.js";
 export { initializeMathRendering, setMathRenderer, } from "./math-rendering.js";
+export type { MathRenderingOptions } from "./math-rendering.js";
 export { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
 export type { AttachInstrumentationEventBridgeArgs } from "./instrumentation-event-bridge.js";
 export { resolveInstrumentationProvider } from "./instrumentation-provider-resolution.js";