@pie-players/pie-players-shared 0.3.73 → 0.3.75

package/dist/loaders/preloaded-registration.js

@@ -0,0 +1,141 @@
+/**
+ * Registration for the `preloaded` strategy: the host's bundler resolves the
+ * element packages, and the players load nothing.
+ *
+ * Each element is defined under the versioned tag `toPackageVersionedTag`
+ * derives from its base tag and the registered version, recorded in
+ * `window.PIE_REGISTRY`, and recorded by package in
+ * `window.PIE_PRELOADED_ELEMENTS`. The item player and the section player
+ * rewrite every authored spec of a registered package to that version
+ * (`alignPreloadedElementVersions`), derive the versioned tags from the result,
+ * define the ones content names under another base tag
+ * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
+ *
+ * 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
+ * each tag it renders without one.
+ *
+ * Bundled by the host, the elements' copies of the MathJax adapter find no npm
+ * root in their module URLs, so the registration also takes where they load
+ * MathJax's fonts and speech from (`options.math`): a root, or each file's URL.
+ */
+import { defineCustomElementSafely } from "../pie/custom-element-define.js";
+import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
+import { writeRegistryEntry } from "../pie/registry.js";
+import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
+import { parsePackageName } from "../pie/utils.js";
+import { toPackageVersionedTag } from "../pie/versioned-tag.js";
+import { isExactSemver } from "./element-package-policy.js";
+import { pickElementClass } from "./esm-adapter.js";
+/**
+ * Register host-bundled elements for the `preloaded` strategy.
+ *
+ * Synchronous: every tag is in `customElements` when the call returns.
+ * Idempotent: a tag that is already defined keeps its definition and its
+ * registry entry, which only gains a controller it lacked. Every entry is
+ * validated before any is registered. A package registers at one version per
+ * page, because the players align every authored version of a package to the
+ * registered one. `options.math` replaces the page's math asset options it
+ * sets, and keeps the others.
+ */
+export function registerPreloadedElements(elements, options = {}) {
+    if (typeof window === "undefined" || typeof customElements === "undefined") {
+        throw new Error("[registerPreloadedElements] requires a browser with customElements");
+    }
+    const preloaded = preloadedPackageSpecs();
+    const resolved = elements.map(resolveElement);
+    assertOneVersionPerPackage(resolved, preloaded);
+    const mathError = options.math === undefined ? undefined : mathAssetOptionsError(options.math);
+    if (mathError) {
+        throw new Error(`[registerPreloadedElements] options.math: ${mathError}`);
+    }
+    if (options.math)
+        setMathAssetOptions(options.math);
+    for (const { packageName, spec, tagName, elementClass, controller } of resolved) {
+        defineCustomElementSafely(tagName, class extends elementClass {
+        }, `preloaded element tag for ${packageName}`);
+        writeRegistryEntry({
+            package: spec,
+            status: Status.loaded,
+            tagName,
+            element: elementClass,
+            ...(controller ? { controller } : {}),
+            bundleType: controller ? BundleType.clientPlayer : BundleType.player,
+        });
+        preloaded[packageName] = spec;
+    }
+}
+function resolveElement(element, index) {
+    const at = `[registerPreloadedElements] entry ${index}`;
+    if (!element || typeof element !== "object") {
+        throw new Error(`${at}: expected { tag, package, version, element }`);
+    }
+    const { package: packageName, version, tag } = element;
+    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 (typeof tag !== "string" || !tag) {
+        throw new Error(`${at} (${packageName}): tag must be the base tag to register, got ${JSON.stringify(tag)}`);
+    }
+    const candidate = typeof element.element === "function"
+        ? element.element
+        : pickElementClass(element.element, "delivery");
+    if (!isCustomElementConstructor(candidate)) {
+        throw new Error(`${at} (${packageName}): element must be the ./browser/delivery module or its default export`);
+    }
+    let controller;
+    if (element.controller !== undefined) {
+        controller = resolveController(element.controller);
+        if (!controller) {
+            throw new Error(`${at} (${packageName}): controller must be the ./browser/controller module or its default export`);
+        }
+    }
+    const spec = `${packageName}@${version}`;
+    return {
+        packageName,
+        spec,
+        tagName: toPackageVersionedTag(tag, spec),
+        elementClass: candidate,
+        controller,
+    };
+}
+function resolveController(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const module = value;
+    const candidate = (typeof module.model === "function" ? module : module.default);
+    return candidate && typeof candidate.model === "function"
+        ? candidate
+        : undefined;
+}
+function assertOneVersionPerPackage(resolved, preloaded) {
+    const specs = new Map(Object.entries(preloaded));
+    for (const { packageName, spec } of resolved) {
+        const existing = specs.get(packageName);
+        if (existing !== undefined && existing !== spec) {
+            throw new Error(`[registerPreloadedElements] ${packageName} is registered as ${existing}; ` +
+                `${spec} cannot also be registered, because the players align every ` +
+                "authored version of a package to the registered one");
+        }
+        specs.set(packageName, spec);
+    }
+}
+function isBarePackageName(value) {
+    if (typeof value !== "string" || !value)
+        return false;
+    try {
+        return parsePackageName(value).name === value;
+    }
+    catch {
+        return false;
+    }
+}
+function preloadedPackageSpecs() {
+    const host = window;
+    host.PIE_PRELOADED_ELEMENTS ??= {};
+    return host.PIE_PRELOADED_ELEMENTS;
+}

package/dist/media/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Validation primitives shared by every catalog card whose payload references
+ * media.
+ *
+ * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
+ * audio form: both card types take authored, wire-facing URLs and hand them to a
+ * media element in the learner's browser, so both need the same scheme
+ * allow-list and the same "treat as absent, never as partially valid" posture.
+ * Two copies of a URL allow-list is one copy that gets a fix and one that does
+ * not.
+ *
+ * Lives here, behind its own subpath, so a PIE element can validate authored
+ * media without importing the assessment toolkit, whose root entry declares
+ * side effects and brings the TTS and calculator packages with it. The toolkit
+ * root re-exports every name. Nothing here runs at import time.
+ */
+import type { MediaFragmentRange, MediaSource } from "../types/index.js";
+/**
+ * The only `MediaAssetRef.version` this build renders.
+ *
+ * `media-asset-contract.md` requires unknown-version rejection for runtime
+ * rendering: bumping to `2` obliges every consumer to accept both for as long as
+ * any producer emits `1`, so a card claiming a version this build does not
+ * implement must not be rendered on a guess at which fields still mean what they
+ * did.
+ */
+export declare const SUPPORTED_MEDIA_ASSET_VERSION = 1;
+/**
+ * Whether a media reference claims a version this build cannot render.
+ *
+ * An absent `version` is accepted rather than rejected — the same posture the
+ * rest of this module takes toward absent fields, and the one `media.kind` and
+ * `matchesRequestedSignLanguage` already take: only a positive claim of
+ * something else is refused. Producers predate the field, and treating its
+ * absence as a rejection would drop cards that are otherwise wholly valid.
+ */
+export declare function isUnsupportedMediaAssetVersion(version: unknown): boolean;
+export declare function isSafeMediaSrc(raw: unknown): raw is string;
+export declare function normalizeMediaSources(raw: unknown): MediaSource[];
+export declare function normalizeMediaFragment(raw: unknown): MediaFragmentRange | undefined;
+export declare function trimmedOrUndefined(value: unknown): string | undefined;
+/**
+ * Hold a media element to one fragment's range, and return the disposer.
+ *
+ * The `#t=` URI `applyMediaFragment` writes is a hint browsers honour at neither
+ * bound reliably, so every consumer that means "play only this slice" enforces it
+ * here instead of reimplementing the pair. Both shipped consumers do —
+ * `SignLanguageMediaRegion` pausing at the end, `TTSService.playRecordedAudio`
+ * ending the clip so the chunk sequence advances — which is why the end action is
+ * the caller's and only the arithmetic is shared.
+ *
+ * The start seek is forward only: a browser that did honour the URI has already
+ * positioned past the start, and seeking back would replay audio the learner has
+ * heard. `onReachedEnd` may fire more than once and must tolerate it; polling
+ * stops while the element is paused, so an element left sitting past its end bound
+ * goes quiet rather than being told repeatedly.
+ */
+export declare function enforceMediaFragment(element: HTMLMediaElement, fragment: MediaFragmentRange | undefined, onReachedEnd: () => void): () => void;
+/**
+ * Apply a fragment range to a source URL as a Media Fragments URI, so one
+ * recording can serve several content nodes.
+ *
+ * The URI is a hint only: browsers honour both bounds inconsistently, so the
+ * caller enforces the range itself with `enforceMediaFragment` — seek forward
+ * to the start once metadata is available, and stop at the end.
+ * `SignLanguageMediaRegion` and `TTSService.playRecordedAudio` are the two
+ * shipped consumers that do so.
+ */
+export declare function applyMediaFragment(src: string, fragment?: MediaFragmentRange): string;

package/dist/media/index.js

@@ -0,0 +1,194 @@
+/**
+ * Validation primitives shared by every catalog card whose payload references
+ * media.
+ *
+ * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
+ * audio form: both card types take authored, wire-facing URLs and hand them to a
+ * media element in the learner's browser, so both need the same scheme
+ * allow-list and the same "treat as absent, never as partially valid" posture.
+ * Two copies of a URL allow-list is one copy that gets a fix and one that does
+ * not.
+ *
+ * Lives here, behind its own subpath, so a PIE element can validate authored
+ * media without importing the assessment toolkit, whose root entry declares
+ * side effects and brings the TTS and calculator packages with it. The toolkit
+ * root re-exports every name. Nothing here runs at import time.
+ */
+/**
+ * Media source URLs are handed to a media element in the learner's browser. Only
+ * schemes such an element can actually fetch are allowed; anything else is
+ * dropped so an authored `javascript:` / `file:` URL cannot ride into the DOM.
+ * Relative and protocol-relative URLs are allowed — host content is commonly
+ * served from the same origin as the player.
+ */
+const DISALLOWED_SRC_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const ALLOWED_SRC_SCHEMES = new Set(["http:", "https:", "data:", "blob:"]);
+/**
+ * The only `MediaAssetRef.version` this build renders.
+ *
+ * `media-asset-contract.md` requires unknown-version rejection for runtime
+ * rendering: bumping to `2` obliges every consumer to accept both for as long as
+ * any producer emits `1`, so a card claiming a version this build does not
+ * implement must not be rendered on a guess at which fields still mean what they
+ * did.
+ */
+export const SUPPORTED_MEDIA_ASSET_VERSION = 1;
+/**
+ * Whether a media reference claims a version this build cannot render.
+ *
+ * An absent `version` is accepted rather than rejected — the same posture the
+ * rest of this module takes toward absent fields, and the one `media.kind` and
+ * `matchesRequestedSignLanguage` already take: only a positive claim of
+ * something else is refused. Producers predate the field, and treating its
+ * absence as a rejection would drop cards that are otherwise wholly valid.
+ */
+export function isUnsupportedMediaAssetVersion(version) {
+    return version !== undefined && version !== SUPPORTED_MEDIA_ASSET_VERSION;
+}
+export function isSafeMediaSrc(raw) {
+    if (typeof raw !== "string")
+        return false;
+    const src = raw.trim();
+    if (!src)
+        return false;
+    // Relative ("/video.mp4", "video.mp4") and protocol-relative ("//cdn/x.mp4")
+    // forms carry no scheme to check and inherit the document's.
+    if (src.startsWith("//") || !DISALLOWED_SRC_SCHEME.test(src))
+        return true;
+    const scheme = src.slice(0, src.indexOf(":") + 1).toLowerCase();
+    return ALLOWED_SRC_SCHEMES.has(scheme);
+}
+export function normalizeMediaSources(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const sources = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const candidate = entry;
+        if (!isSafeMediaSrc(candidate.src))
+            continue;
+        const source = { src: candidate.src.trim() };
+        if (typeof candidate.type === "string" && candidate.type.trim()) {
+            source.type = candidate.type.trim();
+        }
+        if (Number.isFinite(candidate.width))
+            source.width = candidate.width;
+        if (Number.isFinite(candidate.height))
+            source.height = candidate.height;
+        // Deduplicated by `src`, because the signing region renders `<source>`
+        // elements in an `{#each}` keyed on exactly that: an authored card listing
+        // one URL twice — the same file under two MIME types is the plausible way —
+        // would otherwise throw Svelte's duplicate-key error and take the whole
+        // region down rather than degrade. The first entry wins, so authored order
+        // still decides which encoding the browser is offered first.
+        if (sources.some((existing) => existing.src === source.src))
+            continue;
+        sources.push(source);
+    }
+    return sources;
+}
+export function normalizeMediaFragment(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const candidate = raw;
+    const start = Number(candidate.startSeconds);
+    if (!Number.isFinite(start) || start < 0)
+        return undefined;
+    const end = Number(candidate.endSeconds);
+    // An end at or before the start would produce a zero/negative slice; treat
+    // it as "no end" rather than a range that can never play.
+    if (!Number.isFinite(end) || end <= start)
+        return { startSeconds: start };
+    return { startSeconds: start, endSeconds: end };
+}
+export function trimmedOrUndefined(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+/**
+ * How often the end bound is re-checked while a slice is playing. `timeupdate`
+ * alone fires about four times a second, which is loose enough to leak a sliver
+ * of the next node's recording.
+ */
+const END_CHECK_INTERVAL_MS = 100;
+/** `HTMLMediaElement.HAVE_METADATA`, which not every DOM implementation exposes. */
+const HAVE_METADATA = 1;
+/**
+ * Hold a media element to one fragment's range, and return the disposer.
+ *
+ * The `#t=` URI `applyMediaFragment` writes is a hint browsers honour at neither
+ * bound reliably, so every consumer that means "play only this slice" enforces it
+ * here instead of reimplementing the pair. Both shipped consumers do —
+ * `SignLanguageMediaRegion` pausing at the end, `TTSService.playRecordedAudio`
+ * ending the clip so the chunk sequence advances — which is why the end action is
+ * the caller's and only the arithmetic is shared.
+ *
+ * The start seek is forward only: a browser that did honour the URI has already
+ * positioned past the start, and seeking back would replay audio the learner has
+ * heard. `onReachedEnd` may fire more than once and must tolerate it; polling
+ * stops while the element is paused, so an element left sitting past its end bound
+ * goes quiet rather than being told repeatedly.
+ */
+export function enforceMediaFragment(element, fragment, onReachedEnd) {
+    if (!fragment)
+        return () => { };
+    const { startSeconds, endSeconds } = fragment;
+    let seekToStart;
+    if (startSeconds > 0) {
+        seekToStart = () => {
+            if (element.currentTime < startSeconds) {
+                element.currentTime = startSeconds;
+            }
+        };
+        // Seeking before metadata is available only sets the default start
+        // position, so wait for it unless it already landed.
+        if (element.readyState >= HAVE_METADATA)
+            seekToStart();
+        else
+            element.addEventListener("loadedmetadata", seekToStart);
+    }
+    let checkEnd;
+    let endPoll;
+    if (endSeconds !== undefined) {
+        checkEnd = () => {
+            if (element.currentTime >= endSeconds)
+                onReachedEnd();
+        };
+        element.addEventListener("timeupdate", checkEnd);
+        endPoll = setInterval(() => {
+            if (!element.paused)
+                checkEnd?.();
+        }, END_CHECK_INTERVAL_MS);
+    }
+    return () => {
+        if (seekToStart)
+            element.removeEventListener("loadedmetadata", seekToStart);
+        if (checkEnd)
+            element.removeEventListener("timeupdate", checkEnd);
+        if (endPoll !== undefined)
+            clearInterval(endPoll);
+    };
+}
+/**
+ * Apply a fragment range to a source URL as a Media Fragments URI, so one
+ * recording can serve several content nodes.
+ *
+ * The URI is a hint only: browsers honour both bounds inconsistently, so the
+ * caller enforces the range itself with `enforceMediaFragment` — seek forward
+ * to the start once metadata is available, and stop at the end.
+ * `SignLanguageMediaRegion` and `TTSService.playRecordedAudio` are the two
+ * shipped consumers that do so.
+ */
+export function applyMediaFragment(src, fragment) {
+    if (!fragment)
+        return src;
+    // Never stack a second fragment onto a URL that already carries one — the
+    // authored value wins.
+    if (src.includes("#"))
+        return src;
+    const end = fragment.endSeconds !== undefined ? `,${fragment.endSeconds}` : "";
+    return `${src}#t=${fragment.startSeconds}${end}`;
+}

package/dist/pie/authoring.d.ts

@@ -10,7 +10,7 @@ export type InitializedConfigureModel = {
 export type AuthoringValidationResult = {
     hasErrors: boolean;
     validatedModels: Array<PieModel & {
-        validation?: unknown;
+        errors?: unknown;
     }>;
 };
 export type AuthoringMediaHandlers = {

package/dist/pie/authoring.js

@@ -105,14 +105,16 @@ export function initializeAuthoringConfigures(config, configuration = {}, option
 function resolveValidationController(configureElement) {
     return findPieController(configureElement.localName);
 }
-function hasValidationErrors(validation) {
-    if (!validation || typeof validation !== "object")
+// A controller's `validate` returns a field → message map. ebsr returns one map
+// per part, so an empty ebsr result is `{ partA: {}, partB: {} }`.
+function hasValidationErrors(errors) {
+    if (!isRecord(errors))
         return false;
-    const validationRecord = validation;
-    if (validationRecord.hasErrors === true)
-        return true;
-    const errors = validationRecord.errors;
-    return Array.isArray(errors) && errors.length > 0;
+    if (isRecord(errors.partA) && isRecord(errors.partB)) {
+        return (Object.keys(errors.partA).length > 0 ||
+            Object.keys(errors.partB).length > 0);
+    }
+    return Object.keys(errors).length > 0;
 }
 export async function validateAuthoringModels(config, configuration = {}, options = {}) {
     const container = options.container ?? document;
@@ -129,20 +131,25 @@ export async function validateAuthoringModels(config, configuration = {}, option
                 continue;
             const controller = resolveValidationController(element);
             const elementConfiguration = resolveConfigureConfiguration(configuration, elementTag, String(packageSpec));
-            const validation = typeof controller?.validate === "function"
-                ? await controller.validate(model, elementConfiguration)
-                : undefined;
-            validatedModels.push({
-                ...model,
-                ...(isRecord(validation) ? validation : {}),
-                id: model.id,
-                element: model.element,
-                validation,
-            });
+            if (typeof controller?.validate !== "function") {
+                validatedModels.push(model);
+                continue;
+            }
+            const errors = await controller.validate(model, elementConfiguration);
+            const validatedModel = { ...model, errors };
+            validatedModels.push(validatedModel);
+            // Configure elements render inline messages from `model.errors`. Skip an
+            // unchanged set: some configure elements emit `model.updated` when their
+            // model is assigned, and a host validating on every update would loop.
+            const configureElement = element;
+            if (JSON.stringify(configureElement.model?.errors) !==
+                JSON.stringify(errors)) {
+                configureElement.model = validatedModel;
+            }
         }
     }
     return {
-        hasErrors: validatedModels.some((model) => hasValidationErrors(model.validation)),
+        hasErrors: validatedModels.some((model) => hasValidationErrors(model.errors)),
         validatedModels,
     };
 }

package/dist/pie/element-announcements.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Which delivery-element `session-changed` announcements a renderer forwards.
+ *
+ * Every update pass hands each element its session again, and an element that
+ * announces from its `session` setter announces on every pass, with its own
+ * unchanged `complete`. Forwarded, those echoes follow every learner response
+ * and let the last element to announce set the item's completion for a host.
+ */
+/**
+ * JSON with object keys in sorted order, so a session entry rebuilt with its
+ * keys in another order signs the same. An object met a second time is written
+ * as `"[Circular]"`. `null` when the value cannot be serialized.
+ */
+export declare function sessionSignature(value: unknown): string | null;
+export interface ElementAnnouncement {
+    /** The element that dispatched. */
+    element: EventTarget | null;
+    /** `complete` from the event detail. */
+    complete: unknown;
+    /** The session the element holds. */
+    session: unknown;
+    /** A commit at a teardown, navigation or page-hidden seam. */
+    commit: boolean;
+}
+/**
+ * Admits an announcement when it is the element's first, or when its `complete`
+ * or the element's session differs from the last announcement admitted from
+ * that element. A commit is always admitted. Keyed by the element instance:
+ * `component` repeats across two elements of one type.
+ */
+export declare function createElementAnnouncementFilter(): (announcement: ElementAnnouncement) => boolean;
+/**
+ * Whether an element holds a session other than its entry of the item's
+ * session, by identity and by content. Before the renderer's update pass, that
+ * is the placeholder its first initialization pass handed it, and a `complete`
+ * it announces describes the placeholder. An element with no readable session
+ * holds none.
+ */
+export declare function holdsPlaceholderSession(held: unknown, entry: unknown): boolean;

package/dist/pie/element-announcements.js

@@ -0,0 +1,67 @@
+/**
+ * Which delivery-element `session-changed` announcements a renderer forwards.
+ *
+ * Every update pass hands each element its session again, and an element that
+ * announces from its `session` setter announces on every pass, with its own
+ * unchanged `complete`. Forwarded, those echoes follow every learner response
+ * and let the last element to announce set the item's completion for a host.
+ */
+/**
+ * JSON with object keys in sorted order, so a session entry rebuilt with its
+ * keys in another order signs the same. An object met a second time is written
+ * as `"[Circular]"`. `null` when the value cannot be serialized.
+ */
+export function sessionSignature(value) {
+    try {
+        const seen = new WeakSet();
+        const json = JSON.stringify(value, (_key, nested) => {
+            if (!nested || typeof nested !== "object" || Array.isArray(nested)) {
+                return nested;
+            }
+            if (seen.has(nested))
+                return "[Circular]";
+            seen.add(nested);
+            const record = nested;
+            const sorted = {};
+            for (const key of Object.keys(record).sort())
+                sorted[key] = record[key];
+            return sorted;
+        });
+        return json ?? "undefined";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Admits an announcement when it is the element's first, or when its `complete`
+ * or the element's session differs from the last announcement admitted from
+ * that element. A commit is always admitted. Keyed by the element instance:
+ * `component` repeats across two elements of one type.
+ */
+export function createElementAnnouncementFilter() {
+    const admitted = new WeakMap();
+    return ({ element, complete, session, commit }) => {
+        if (!element || typeof element !== "object")
+            return true;
+        const signature = sessionSignature({ complete, session });
+        if (signature === null)
+            return true;
+        if (!commit && admitted.get(element) === signature)
+            return false;
+        admitted.set(element, signature);
+        return true;
+    };
+}
+/**
+ * Whether an element holds a session other than its entry of the item's
+ * session, by identity and by content. Before the renderer's update pass, that
+ * is the placeholder its first initialization pass handed it, and a `complete`
+ * it announces describes the placeholder. An element with no readable session
+ * holds none.
+ */
+export function holdsPlaceholderSession(held, entry) {
+    if (held === undefined || held === entry)
+        return false;
+    return sessionSignature(held) !== sessionSignature(entry);
+}

package/dist/pie/element-observer.d.ts

@@ -20,7 +20,7 @@
  * recently registered, silently never bound.
  */
 import type { ConfigEntity, Env } from "../types/index.js";
-import type { EventListenersMap } from "./types.js";
+import type { BundleType, EventListenersMap } from "./types.js";
 /**
  * What one registration binds a PIE element with.
  */
@@ -29,6 +29,8 @@ export interface PieElementContext {
     session: any[];
     env?: Env;
     eventListeners?: EventListenersMap;
+    /** The delivering player's bundle type, see `findPieController`. */
+    bundleType?: BundleType;
 }
 /**
  * Reads the context to bind with.

package/dist/pie/element-observer.js

@@ -46,6 +46,7 @@ const bindElement = (element, contexts) => {
             session: context.session,
             env: context.env,
             eventListeners: context.eventListeners?.[tagName],
+            bundleType: context.bundleType,
         });
         if (bound)
             return;

package/dist/pie/elements-rendered.d.ts

@@ -0,0 +1,25 @@
+/**
+ * When the PIE elements of a player have rendered.
+ *
+ * An element renders after its model and session are assigned, in a task of
+ * its own: legacy React elements debounce the render and commit through the
+ * React scheduler, so the commit lands tens of milliseconds after the
+ * assignment. No event marks it in both element generations — `model-set` is
+ * dispatched by about half of them, some before rendering — so this reads the
+ * DOM.
+ *
+ * An element has rendered once it holds content, and so has every custom
+ * element defined below it: an `ebsr` paints its parts, which then render
+ * themselves. Some elements render nothing, a rubric for a student among them,
+ * so an element still empty when the subtree has had no mutation for
+ * `quietMs` counts as rendered. A render slower than that window, with no
+ * mutation before it, is missed rather than waited for.
+ */
+import type { ConfigEntity } from "../types/index.js";
+/** Longer than the 50ms render debounce legacy elements use, plus a scheduler task. */
+export declare const ELEMENT_RENDER_QUIET_MS = 200;
+/**
+ * Resolves once every element of `configs` in `root` has rendered, or when
+ * `signal` aborts. Never rejects.
+ */
+export declare function elementsRendered(root: Element, configs: ConfigEntity[], signal: AbortSignal, quietMs?: number): Promise<void>;