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

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/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.1",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",