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

package/dist/instrumentation/providers/CompositeInstrumentationProvider.js

@@ -1,3 +1,4 @@
+import { settleAll } from "../../promise/index.js";
 export class CompositeInstrumentationProvider {
     providerId = "composite";
     providerName = "Composite Provider";
@@ -7,7 +8,7 @@ export class CompositeInstrumentationProvider {
         this.providers = providers.filter(Boolean);
     }
     async initialize(config) {
-        const results = await Promise.allSettled(this.providers.map((provider) => provider.initialize(config)));
+        const results = await settleAll(this.providers.map((provider) => provider.initialize(config)));
         this.initialized = true;
         if (config?.debug) {
             for (const [index, result] of results.entries()) {

package/dist/loaders/element-package-spec.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shape check for the package specs an item config names in `elements`.
+ *
+ * Loaders that build CDN URLs from a spec run it through
+ * `isScopedPackageSpec` first: item configs are authored content, and a
+ * version such as `1.0.0/../../../gh/owner/repo@main` would otherwise
+ * resolve to a path outside the package.
+ */
+/**
+ * A scoped npm package name with an optional semver version or dist-tag, as
+ * item configs store it: `@pie-element/rubric`, `@pie-element/rubric@latest`,
+ * `@pie-element/rubric@8.0.0-hotfix.2`.
+ */
+export declare function isScopedPackageSpec(spec: unknown): spec is string;
+/** Why a loader refused `spec`, for its failure reason. */
+export declare function invalidPackageSpecMessage(spec: unknown): string;

package/dist/loaders/element-package-spec.js

@@ -0,0 +1,30 @@
+/**
+ * Shape check for the package specs an item config names in `elements`.
+ *
+ * Loaders that build CDN URLs from a spec run it through
+ * `isScopedPackageSpec` first: item configs are authored content, and a
+ * version such as `1.0.0/../../../gh/owner/repo@main` would otherwise
+ * resolve to a path outside the package.
+ */
+const SEMVER_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const DIST_TAG = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const SCOPED_PACKAGE_NAME = /^@[a-z0-9~-][a-z0-9._~-]*\/[a-z0-9~-][a-z0-9._~-]*$/;
+/**
+ * A scoped npm package name with an optional semver version or dist-tag, as
+ * item configs store it: `@pie-element/rubric`, `@pie-element/rubric@latest`,
+ * `@pie-element/rubric@8.0.0-hotfix.2`.
+ */
+export function isScopedPackageSpec(spec) {
+    if (typeof spec !== "string")
+        return false;
+    const versionAt = spec.indexOf("@", 1);
+    if (versionAt === -1)
+        return SCOPED_PACKAGE_NAME.test(spec);
+    const version = spec.slice(versionAt + 1);
+    return (SCOPED_PACKAGE_NAME.test(spec.slice(0, versionAt)) &&
+        (SEMVER_VERSION.test(version) || DIST_TAG.test(version)));
+}
+/** Why a loader refused `spec`, for its failure reason. */
+export function invalidPackageSpecMessage(spec) {
+    return `Invalid element package spec ${JSON.stringify(String(spec))}: expected a scoped npm package name with an optional semver version or dist-tag`;
+}

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

@@ -67,7 +67,8 @@ export declare function createEsmBackend(config: EsmBackendConfig): EsmBackend;
 export declare function mapEsmViewElements(elements: ElementMap, view?: string, viewConfig?: ViewConfig): ElementMap;
 /**
  * URL of a package's `./runtime-support` module on the ESM CDN the players load
- * elements from, or `undefined` when a custom provider names no package root.
+ * elements from, or `undefined` when a custom provider names no package root or
+ * `packageVersion` is not a scoped package spec.
  */
 export declare function resolveEsmRuntimeSupportUrl(packageVersion: string, options: {
     cdnBaseUrl: string;

package/dist/loaders/esm-adapter.js

@@ -21,6 +21,7 @@ import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js
 import { parsePackageName } from "../pie/utils.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { isExactSemver } from "./element-package-policy.js";
+import { invalidPackageSpecMessage, isScopedPackageSpec, } from "./element-package-spec.js";
 import { forwardMathjaxEvents } from "./mathjax-events.js";
 import { isPlainRecord } from "../object/index.js";
 export const BUILT_IN_VIEWS = {
@@ -80,12 +81,30 @@ export function createEsmBackend(config) {
     async function load(elements, context) {
         if (!elements || Object.keys(elements).length === 0)
             return;
+        // Refused before any URL is built from the spec; the other elements load.
+        const reasons = new Map();
+        const loadable = {};
+        for (const [tag, pkg] of Object.entries(elements)) {
+            if (isScopedPackageSpec(pkg)) {
+                loadable[tag] = pkg;
+            }
+            else {
+                reasons.set(tag, {
+                    kind: "backend-rejected",
+                    tag,
+                    cause: invalidPackageSpecMessage(pkg),
+                });
+            }
+        }
+        if (Object.keys(loadable).length === 0) {
+            throw new AdapterFailure(reasons);
+        }
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
         }
         forwardMathjaxEventsOf(context.doc);
         const newEntries = {};
-        for (const [tag, pkg] of Object.entries(elements)) {
+        for (const [tag, pkg] of Object.entries(loadable)) {
             const packageName = parsePackageName(pkg).name;
             if (moduleResolution === "import-map") {
                 const existingVersion = importMappedPackageVersions.get(packageName);
@@ -147,8 +166,7 @@ export function createEsmBackend(config) {
                 await applyImportMap(imports, injectedMap, context.doc);
             }
         }
-        const reasons = new Map();
-        await Promise.all(Object.entries(elements).map(async ([tag, packageVersion]) => {
+        await Promise.all(Object.entries(loadable).map(async ([tag, packageVersion]) => {
             const packageName = parsePackageName(packageVersion).name;
             let actualTag;
             try {
@@ -609,9 +627,12 @@ async function fetchPackageMetadata(packageJsonUrl) {
 const RUNTIME_SUPPORT_PATH = "dist/runtime-support.js";
 /**
  * URL of a package's `./runtime-support` module on the ESM CDN the players load
- * elements from, or `undefined` when a custom provider names no package root.
+ * elements from, or `undefined` when a custom provider names no package root or
+ * `packageVersion` is not a scoped package spec.
  */
 export function resolveEsmRuntimeSupportUrl(packageVersion, options) {
+    if (!isScopedPackageSpec(packageVersion))
+        return undefined;
     const cdnBaseUrl = options.cdnBaseUrl.replace(/\/+$/, "");
     const provider = resolveCdnProvider(options.cdnProvider, cdnBaseUrl);
     if (typeof provider.runtimeSupportUrl === "function") {

package/dist/loaders/index.d.ts

@@ -34,6 +34,7 @@ export type { ElementMap } from "./ElementLoader.js";
 export { aggregateElements } from "./ElementLoader.js";
 export type { ElementPackagePolicy } from "./element-package-policy.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
+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";

package/dist/loaders/index.js

@@ -32,6 +32,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 { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";

package/dist/pie/index.d.ts

@@ -41,6 +41,7 @@ export { BundleType, defaultPieElementOptions, isCustomElementConstructor, isPie
 export { attemptCustomElementDefine, defineCustomElementSafely, type AttemptCustomElementDefineOptions, type SafeDefineAttempt, type SafeDefineOutcome, type SafeDefineResult, type SafeDefineStatus, } from "./custom-element-define.js";
 export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX, } from "./tag-names.js";
 export type { PieViewMode } from "./tag-names.js";
+export { runtimeElementTags } from "./versioned-tag.js";
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";
 export type { ElementOverrides } from "./overrides.js";
 export { addOrUpdateOverrideInUrl, applyElementOverrides, applyElementVersionOverridesPreserveTags, extractPackageInfo, formatElementOverrideParam, parseElementOverridesFromCurrentUrl, parseElementOverridesFromUrl, } from "./overrides.js";

package/dist/pie/index.js

@@ -44,6 +44,7 @@ isPieAvailable, isPieRegistryAvailable, Status, } from "./types.js";
 // Tag naming helpers
 export { attemptCustomElementDefine, defineCustomElementSafely, } from "./custom-element-define.js";
 export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX, } from "./tag-names.js";
+export { runtimeElementTags } from "./versioned-tag.js";
 // Updates
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";
 export { addOrUpdateOverrideInUrl, applyElementOverrides, applyElementVersionOverridesPreserveTags, extractPackageInfo, formatElementOverrideParam, parseElementOverridesFromCurrentUrl, parseElementOverridesFromUrl, } from "./overrides.js";

package/dist/pie/versioned-tag.d.ts

@@ -17,3 +17,13 @@ export declare function parseVersionedTagName(tagName: string): {
 export declare function toPackageVersionedTag(tagName: string, packageSpec: string, options?: {
     preserveUnversionedTag?: boolean;
 }): string;
+/**
+ * The tags a player can define an authored element under, most specific first:
+ * the versioned tag for its package spec, aligned to the page's preloaded
+ * registration, then the authored tag, which an unversioned spec keeps. With no
+ * spec the authored tag is the only candidate.
+ *
+ * For code that looks an element's class up by tag without rendering it, such as
+ * reading what the class declares before the element is in the DOM.
+ */
+export declare function runtimeElementTags(tagName: string, packageSpec?: string): string[];

package/dist/pie/versioned-tag.js

@@ -1,3 +1,4 @@
+import { alignPreloadedElementVersions } from "../loaders/preloaded-alignment.js";
 import { parsePackageName } from "./utils.js";
 const VERSION_DELIMITER = "--version-";
 const TAG_VERSION_PATTERN = "[0-9A-Za-z-]+";
@@ -45,3 +46,29 @@ export function toPackageVersionedTag(tagName, packageSpec, options = {}) {
     // package versions at runtime, which requires updating the cloned runtime tag.
     return `${baseName}${VERSION_DELIMITER}${targetEncodedVersion}`;
 }
+/**
+ * The tags a player can define an authored element under, most specific first:
+ * the versioned tag for its package spec, aligned to the page's preloaded
+ * registration, then the authored tag, which an unversioned spec keeps. With no
+ * spec the authored tag is the only candidate.
+ *
+ * For code that looks an element's class up by tag without rendering it, such as
+ * reading what the class declares before the element is in the DOM.
+ */
+export function runtimeElementTags(tagName, packageSpec) {
+    if (!packageSpec)
+        return [tagName];
+    let versioned;
+    try {
+        const { elements } = alignPreloadedElementVersions({
+            elements: { [tagName]: packageSpec },
+        });
+        versioned = toPackageVersionedTag(tagName, elements[tagName], {
+            preserveUnversionedTag: true,
+        });
+    }
+    catch {
+        return [tagName];
+    }
+    return versioned === tagName ? [tagName] : [versioned, tagName];
+}

package/dist/promise/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Waits for every value to settle and resolves with each outcome in input
+ * order, as the `allSettled` static does. Built on `Promise.all` and `then` alone:
+ * a host page can replace the global `Promise` with an implementation that
+ * predates `allSettled` (zone.js 0.9.1 does), so published code calls no
+ * `Promise` static beyond `all`, `race`, `resolve` and `reject`.
+ * `bun run check:bundle-safety` enforces that on every built bundle.
+ * @param values The promises or plain values to settle.
+ */
+export declare const settleAll: <T>(values: Iterable<T | PromiseLike<T>>) => Promise<PromiseSettledResult<Awaited<T>>[]>;

package/dist/promise/index.js

@@ -0,0 +1,16 @@
+/**
+ * Waits for every value to settle and resolves with each outcome in input
+ * order, as the `allSettled` static does. Built on `Promise.all` and `then` alone:
+ * a host page can replace the global `Promise` with an implementation that
+ * predates `allSettled` (zone.js 0.9.1 does), so published code calls no
+ * `Promise` static beyond `all`, `race`, `resolve` and `reject`.
+ * `bun run check:bundle-safety` enforces that on every built bundle.
+ * @param values The promises or plain values to settle.
+ */
+export const settleAll = (values) => Promise.all(Array.from(values, (value) => Promise.resolve(value).then((result) => ({
+    status: "fulfilled",
+    value: result,
+}), (reason) => ({
+    status: "rejected",
+    reason,
+}))));

package/dist/types/index.d.ts

@@ -464,9 +464,25 @@ export interface AccessibilityCatalog {
     identifier: string;
     cards: CatalogCard[];
 }
+/**
+ * A learner's personal needs profile, in tool ids. An AfA PNP 3.0 record maps to
+ * it through the AfA adapter the packaged tool set exports.
+ */
 export interface PersonalNeedsProfile {
+    /** Tools the learner may turn on. */
     supports: string[];
+    /** Tools withheld from the learner; a prohibition outranks a support. */
     prohibitedSupports?: string[];
+    /**
+     * Tools granted as `supports` grants them and turned on when the learner's
+     * toolbar first shows them. A block withdraws them as it withdraws a support.
+     */
+    activateAtInit?: string[];
+    /**
+     * Parameters by tool id, the lowest layer: the assessment's and an item's
+     * `toolParameters` override them key by key.
+     */
+    toolParameters?: ToolParameters;
 }
 export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
     name?: string;
@@ -509,8 +525,9 @@ export interface AssessmentSettings {
         toolOverrides?: Record<string, boolean>;
     };
     /**
-     * Parameters by tool id, handed to the tool wherever policy shows it; an
-     * item's `toolParameters` entry wins on that item's own toolbar. Provider
+     * Parameters by tool id, handed to the tool wherever policy shows it. They
+     * override the profile's `toolParameters` key by key, and an item's
+     * `toolParameters` override them on that item's own toolbar. Provider
      * configuration belongs in the toolkit's `tools.providers`.
      */
     toolParameters?: ToolParameters;
@@ -531,6 +548,15 @@ export interface ToolParameterMap {
     signLanguage: {
         signLang?: string;
     };
+    /**
+     * `rate` multiplies every playback speed, 1 being the provider's normal
+     * speed; `pitch` runs 0–2 with 1 normal; `volume` runs 0–1.
+     */
+    textToSpeech: {
+        rate?: number;
+        pitch?: number;
+        volume?: number;
+    };
 }
 /** The parameter shape of tool `K`: its {@link ToolParameterMap} entry, else open. */
 export type ToolParametersFor<K extends string> = K extends keyof ToolParameterMap ? ToolParameterMap[K] : Record<string, unknown>;
@@ -547,7 +573,7 @@ export type ToolParameters = {
 export interface ItemSettings {
     requiredTools?: string[];
     restrictedTools?: string[];
-    /** Parameters by tool id; outranks the assessment's `toolParameters` entry. */
+    /** Parameters by tool id; override the assessment's key by key. */
     toolParameters?: ToolParameters;
 }
 export type PlayerMode = "gather" | "view" | "evaluate" | "author";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.0",
+	"version": "1.0.0-beta.2",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -33,6 +33,10 @@
 			"types": "./dist/object/index.d.ts",
 			"import": "./dist/object/index.js"
 		},
+		"./promise": {
+			"types": "./dist/promise/index.d.ts",
+			"import": "./dist/promise/index.js"
+		},
 		"./types": {
 			"types": "./dist/types/index.d.ts",
 			"import": "./dist/types/index.js"
@@ -121,12 +125,12 @@
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
 		"@pie-element/shared-math-rendering-mathjax": "0.1.4",
-		"@playwright/test": "^1.63.0",
+		"@playwright/test": "^1.64.0",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",
 		"esbuild": "^0.28.2",
 		"glob": "^13.0.0",
-		"svelte": "^5.57.1",
+		"svelte": "^5.57.2",
 		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3"
 	},