@pie-players/pie-players-shared 0.3.69 → 0.3.71

package/dist/pie/initialization.js

@@ -5,84 +5,33 @@
  * This is the core of the PIE player system.
  */
 import { BUILDER_BUNDLE_URL } from "../config/profile.js";
+import { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG } from "../loader-config.js";
 import { mergeObjectsIgnoringNullUndefined } from "../object/index.js";
-import { wrapModelRichContent } from "../security/wrap-model-rich-content.js";
 import { editorPostFix } from "../types/index.js";
+import { initializePieElement } from "./initialize-element.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { initializeMathRendering } from "./math-rendering.js";
 import { pieRegistry } from "./registry.js";
-import { findPieController } from "./scoring.js";
 import { defineCustomElementSafely } from "./custom-element-define.js";
 import { validateCustomElementTag } from "./tag-names.js";
 import { BundleType, isCustomElementConstructor, isPieAvailable, Status, } from "./types.js";
 import { updatePieElement } from "./updates.js";
-import { findOrAddSession, getPackageWithoutVersion, getPieElementBundlesUrl, } from "./utils.js";
+import { getPackageWithoutVersion, getPieElementBundlesUrl, } from "./utils.js";
 // Create module-level logger (respects global debug flag - pass function for dynamic checking)
 const logger = createPieLogger("pie-initialization", () => isGlobalDebugEnabled());
+/**
+ * Deadline for `loadPieModule`'s bundle `<script>` load when the caller
+ * sets no `loadTimeoutMs`. Shared with the `ElementLoader` primitive's
+ * `DEFAULT_LOAD_TIMEOUT_MS` so a bundle gets the same budget whichever
+ * path a host loads it through.
+ */
+const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
 // Default options for loading PIE elements
 const defaultOptions = {
     buildServiceBase: BUILDER_BUNDLE_URL,
     bundleType: BundleType.player, // Default to player.js (no controllers, server-processed models)
     env: { mode: "gather", role: "student" },
 };
-/**
- * Helper function to initialize a PIE element
- */
-const initializePieElement = (element, options) => {
-    const { config, session, env, eventListeners } = options;
-    if (element.__pieInitialized) {
-        return;
-    }
-    const tagName = element.tagName.toLowerCase();
-    logger.debug(`[initializePieElement] Initializing ${tagName}#${element.id}`);
-    // Find model for this element
-    let model = config?.models?.find((m) => m.id === element.id);
-    if (!model) {
-        // Only warn if this element is from a client-player.js bundle (where models are expected)
-        // player.js bundles use server-processed models, so missing models are expected there
-        const registry = pieRegistry();
-        const registryEntry = registry[tagName];
-        if (registryEntry && registryEntry.bundleType === BundleType.clientPlayer) {
-            logger.warn(`[initializePieElement] Model not found for PIE element ${tagName}#${element.id} (client-player.js bundle)`);
-        }
-        return;
-    }
-    // Set session (with element property for updateSession callback)
-    const elementSession = findOrAddSession(session, model.id, model.element);
-    element.session = elementSession;
-    element.__pieInitialized = true;
-    logger.debug(`[initializePieElement] Session set for ${tagName}#${element.id}:`, elementSession);
-    // Set model - use controller if available (client-player.js), or use server-processed model (player.js)
-    const controller = findPieController(tagName);
-    if (!env) {
-        logger.error(`[initializePieElement] ❌ FATAL: No env provided for ${tagName}`);
-        throw new Error(`No env provided for ${tagName}. PIE elements require an env object with mode and role.`);
-    }
-    if (!controller) {
-        // No controller available - using server-processed model (player.js bundle)
-        logger.debug(`[initializePieElement] ℹ️ No controller for ${tagName}, using server-processed model`);
-        logger.debug(`[initializePieElement] Model already processed by server:`, {
-            id: model.id,
-            element: model.element,
-            hasCorrectResponse: "correctResponse" in model,
-            mode: env.mode,
-            role: env.role,
-        });
-        // Set model directly - server already processed it
-        element.model = wrapModelRichContent(model);
-    }
-    else {
-        // Controller available - run client-side processing (client-player.js bundle)
-        // Note: updatePieElementWithRef handles controller invocation
-        logger.debug(`[initializePieElement] Controller found for ${tagName}, will invoke model() function`);
-    }
-    // Add event listeners
-    if (eventListeners) {
-        Object.entries(eventListeners).forEach(([evt, fn]) => {
-            element.addEventListener(evt, fn);
-        });
-    }
-};
 const getEditorElementTagName = (elementTagName, pkg) => validateCustomElementTag(elementTagName + editorPostFix, `editor element tag for ${pkg}`);
 const updateRegisteredElement = (elementTagName, config, session, options, omitEnv = false) => {
     updatePieElement(elementTagName, {
@@ -98,7 +47,10 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
 /**
  * Shared element registration logic
  * Extracted from initializePiesFromLoadedBundle and loadPieModule to eliminate ~200 lines of duplication
- * Also fixes MutationObserver memory leak by storing latest config/session in window context
+ *
+ * Binds the elements already present in `options.container`. Elements that
+ * arrive later are bound by the container owner's observer — see
+ * `element-observer.ts`.
  *
  * `elementModule` may be `null`. In that case we cannot register *new*
  * tags (no element constructor source), but we can still update tags
@@ -111,11 +63,6 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
  */
 const registerPieElementsFromBundle = (elementModule, config, session, registry, options) => {
     const promises = [];
-    const isNodeWithinContainer = (node, container) => {
-        if (!container || container === document)
-            return true;
-        return node instanceof Node && container.contains(node);
-    };
     if (elementModule) {
         logger.debug("[registerPieElementsFromBundle] Available packages in bundle:", Object.keys(elementModule));
     }
@@ -123,15 +70,6 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
         logger.debug("[registerPieElementsFromBundle] No bundle module supplied; will only update tags already registered with customElements.");
     }
     logger.debug("[registerPieElementsFromBundle] config.elements:", config.elements);
-    // Store latest config/session in window so MutationObserver can access current values
-    if (typeof window !== "undefined") {
-        window._pieCurrentContext = {
-            config,
-            session,
-            env: options.env,
-            container: options.container,
-        };
-    }
     Object.entries(config.elements).forEach(([elName, pkg]) => {
         const elementTagName = validateCustomElementTag(elName, `element tag in config.elements for ${String(pkg)}`);
         logger.debug(`[registerPieElementsFromBundle] Processing element: ${elementTagName} -> ${pkg}`);
@@ -227,58 +165,6 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                 promises.push(customElements.whenDefined(elementTagName).then(() => {
                     logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
                 }));
-                // Setup MutationObserver that uses current context (only once)
-                if (!window._pieElementObserver) {
-                    window._pieElementObserver = new MutationObserver((mutations) => {
-                        // Use current context from window instead of stale closure
-                        const context = window._pieCurrentContext;
-                        if (!context) {
-                            logger.warn("[MutationObserver] No current context available");
-                            return;
-                        }
-                        mutations.forEach((mutation) => {
-                            if (mutation.type === "childList") {
-                                mutation.addedNodes.forEach((node) => {
-                                    if (node.nodeType === Node.ELEMENT_NODE) {
-                                        if (!isNodeWithinContainer(node, context.container)) {
-                                            return;
-                                        }
-                                        const tagName = node.tagName.toLowerCase();
-                                        if (registry[tagName]) {
-                                            initializePieElement(node, {
-                                                config: context.config,
-                                                session: context.session,
-                                                env: context.env,
-                                                eventListeners: options.eventListeners?.[tagName],
-                                            });
-                                        }
-                                        // Check children of added nodes
-                                        node
-                                            .querySelectorAll("*")
-                                            .forEach((childNode) => {
-                                            if (!isNodeWithinContainer(childNode, context.container)) {
-                                                return;
-                                            }
-                                            const childTagName = childNode.tagName.toLowerCase();
-                                            if (registry[childTagName]) {
-                                                initializePieElement(childNode, {
-                                                    config: context.config,
-                                                    session: context.session,
-                                                    env: context.env,
-                                                    eventListeners: options.eventListeners?.[childTagName],
-                                                });
-                                            }
-                                        });
-                                    }
-                                });
-                            }
-                        });
-                    });
-                    window._pieElementObserver.observe(document.body, {
-                        childList: true,
-                        subtree: true,
-                    });
-                }
                 // Handle editor elements if needed
                 if (options.bundleType === BundleType.editor) {
                     if (isCustomElementConstructor(elementData.Configure)) {
@@ -327,6 +213,10 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
  * (bundle not loaded by *anyone*) still surface — every unregistered tag
  * gets its own warning, and `updatePieElements` later reports any tag
  * that never resolves.
+ *
+ * Binds the elements present in `opts.container` now. Elements that arrive
+ * later are the container owner's concern: a player with a lifecycle calls
+ * `observePieElements` and releases it on teardown.
  */
 export const initializePiesFromLoadedBundle = (config, session, opts = {}) => {
     const registry = pieRegistry();
@@ -341,7 +231,14 @@ export const initializePiesFromLoadedBundle = (config, session, opts = {}) => {
     registerPieElementsFromBundle(null, config, session, registry, options);
 };
 /**
- * Load a PIE bundle from a URL and initialize elements
+ * Load a PIE bundle from a URL and initialize elements.
+ *
+ * Rejects — rather than hanging or throwing on the window — for every way
+ * the load can fail: the `error` event (404, blocked request, CSP refusal),
+ * the `loadTimeoutMs` deadline (a stalled request that never fires either
+ * event), a bundle whose script ran without populating `window.pie`, and a
+ * throw out of registration. Every rejection names the bundle URL and drops
+ * the injected `<script>`.
  */
 export const loadPieModule = async (config, session, opts = {}) => {
     if (!session) {
@@ -352,31 +249,84 @@ export const loadPieModule = async (config, session, opts = {}) => {
     const registry = pieRegistry();
     const options = mergeObjectsIgnoringNullUndefined(defaultOptions, opts);
     const url = opts.bundleUrl || getPieElementBundlesUrl(config, options);
+    const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
     const script = document.createElement("script");
     script.src = url;
     script.defer = true;
-    script.onerror = () => {
-        throw new Error(`failed to load script: ${url}`);
-    };
-    const loadPromise = new Promise((loadResolve) => {
-        script.addEventListener("load", () => {
-            logger.debug("[loadPieModule] Script loaded from:", url);
-            if (isPieAvailable(window)) {
+    let timer;
+    // Removing a `<script>` does not abort a request already in flight, so a
+    // late `load` can still fire after the deadline rejected. Each handler
+    // checks this so registration never runs for a load the caller has
+    // already been told failed.
+    let settled = false;
+    try {
+        await new Promise((resolve, reject) => {
+            const succeed = () => {
+                settled = true;
+                resolve();
+            };
+            const fail = (error) => {
+                settled = true;
+                reject(error);
+            };
+            script.addEventListener("load", () => {
+                if (settled)
+                    return;
+                logger.debug("[loadPieModule] Script loaded from:", url);
+                if (!isPieAvailable(window)) {
+                    // Deliberately a rejection, not a resolve. The script executed
+                    // and registered nothing, so the URL did not serve a PIE IIFE
+                    // bundle; resolving would report a successful load to a caller
+                    // that then waits on elements which never arrive.
+                    // `initializePiesFromLoadedBundle` tolerates the same missing
+                    // global because there the host's own loader owns registration.
+                    // Here this function owns it, so there is no other party to
+                    // wait for. Matches the IIFE `ElementLoader` adapter, which
+                    // fails with `cause: "window.pie.default missing after bundle
+                    // load"`.
+                    fail(new Error(`PIE bundle loaded but window.pie is absent; is ${url} a proper PIE IIFE module?`));
+                    return;
+                }
                 logger.debug("[loadPieModule] window.pie available");
                 const elementModule = window.pie.default;
-                // Use shared registration logic (returns array of promises)
-                const registrationPromises = registerPieElementsFromBundle(elementModule, config, session, registry, options);
-                // Wait for all element definitions to complete
-                Promise.all(registrationPromises).then(() => loadResolve());
-            }
-            else {
-                logger.error("[loadPieModule] pie var not found; is %s a proper PIE IIFE module?", url);
-                loadResolve();
+                try {
+                    // Use shared registration logic (returns array of promises)
+                    const registrationPromises = registerPieElementsFromBundle(elementModule, config, session, registry, options);
+                    // Wait for all element definitions to complete
+                    Promise.all(registrationPromises).then(succeed, fail);
+                }
+                catch (error) {
+                    // `registerPieElementsFromBundle` throws synchronously for a
+                    // package missing from the bundle and for a client-player
+                    // bundle with no controller. Inside a DOM event handler that
+                    // throw reaches the window instead of the caller.
+                    fail(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+            script.addEventListener("error", () => {
+                if (settled)
+                    return;
+                fail(new Error(`failed to load PIE bundle script: ${url}`));
+            });
+            if (loadTimeoutMs > 0) {
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    fail(new Error(`PIE bundle script load timed out after ${loadTimeoutMs}ms: ${url}`));
+                }, loadTimeoutMs);
             }
+            document.head.appendChild(script);
         });
-    });
-    document.head.appendChild(script);
-    await loadPromise;
+    }
+    catch (error) {
+        // Drop the injected node so a retry starts from a clean head.
+        script.remove();
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
     return { session };
 };
 /**

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

@@ -0,0 +1,23 @@
+/**
+ * Binding a single PIE element to its model and session.
+ *
+ * Split out of `initialization.ts` so the late-arrival observer in
+ * `element-observer.ts` can reuse it without importing the bundle loaders.
+ */
+import type { ConfigEntity, Env } from "../types/index.js";
+import type { EventListeners, PieElement } from "./types.js";
+/**
+ * Bind `element` to the model in `options.config` whose `id` matches it.
+ *
+ * Returns whether the element is bound: `true` once a model has been applied
+ * (including on a repeat call for an element that is already bound), `false`
+ * when the config carries no model for this `id`. A caller holding several
+ * configs — an item player registers its item config and its passage config
+ * separately — uses that to stop at the config the element belongs to.
+ */
+export declare const initializePieElement: (element: PieElement, options: {
+    config: ConfigEntity;
+    session: any[];
+    env?: Env;
+    eventListeners?: EventListeners;
+}) => boolean;

package/dist/pie/initialize-element.js

@@ -0,0 +1,78 @@
+/**
+ * Binding a single PIE element to its model and session.
+ *
+ * Split out of `initialization.ts` so the late-arrival observer in
+ * `element-observer.ts` can reuse it without importing the bundle loaders.
+ */
+import { wrapModelRichContent } from "../security/wrap-model-rich-content.js";
+import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
+import { pieRegistry } from "./registry.js";
+import { findPieController } from "./scoring.js";
+import { BundleType } from "./types.js";
+import { findOrAddSession } from "./utils.js";
+const logger = createPieLogger("pie-initialize-element", () => isGlobalDebugEnabled());
+/**
+ * Bind `element` to the model in `options.config` whose `id` matches it.
+ *
+ * Returns whether the element is bound: `true` once a model has been applied
+ * (including on a repeat call for an element that is already bound), `false`
+ * when the config carries no model for this `id`. A caller holding several
+ * configs — an item player registers its item config and its passage config
+ * separately — uses that to stop at the config the element belongs to.
+ */
+export const initializePieElement = (element, options) => {
+    const { config, session, env, eventListeners } = options;
+    if (element.__pieInitialized) {
+        return true;
+    }
+    const tagName = element.tagName.toLowerCase();
+    logger.debug(`[initializePieElement] Initializing ${tagName}#${element.id}`);
+    // Find model for this element
+    const model = config?.models?.find((m) => m.id === element.id);
+    if (!model) {
+        // Only warn if this element is from a client-player.js bundle (where models are expected)
+        // player.js bundles use server-processed models, so missing models are expected there
+        const registry = pieRegistry();
+        const registryEntry = registry[tagName];
+        if (registryEntry && registryEntry.bundleType === BundleType.clientPlayer) {
+            logger.warn(`[initializePieElement] Model not found for PIE element ${tagName}#${element.id} (client-player.js bundle)`);
+        }
+        return false;
+    }
+    // Set session (with element property for updateSession callback)
+    const elementSession = findOrAddSession(session, model.id, model.element);
+    element.session = elementSession;
+    element.__pieInitialized = true;
+    logger.debug(`[initializePieElement] Session set for ${tagName}#${element.id}:`, elementSession);
+    // Set model - use controller if available (client-player.js), or use server-processed model (player.js)
+    const controller = findPieController(tagName);
+    if (!env) {
+        logger.error(`[initializePieElement] ❌ FATAL: No env provided for ${tagName}`);
+        throw new Error(`No env provided for ${tagName}. PIE elements require an env object with mode and role.`);
+    }
+    if (!controller) {
+        // No controller available - using server-processed model (player.js bundle)
+        logger.debug(`[initializePieElement] ℹ️ No controller for ${tagName}, using server-processed model`);
+        logger.debug(`[initializePieElement] Model already processed by server:`, {
+            id: model.id,
+            element: model.element,
+            hasCorrectResponse: "correctResponse" in model,
+            mode: env.mode,
+            role: env.role,
+        });
+        // Set model directly - server already processed it
+        element.model = wrapModelRichContent(model);
+    }
+    else {
+        // Controller available - run client-side processing (client-player.js bundle)
+        // Note: updatePieElementWithRef handles controller invocation
+        logger.debug(`[initializePieElement] Controller found for ${tagName}, will invoke model() function`);
+    }
+    // Add event listeners
+    if (eventListeners) {
+        Object.entries(eventListeners).forEach(([evt, fn]) => {
+            element.addEventListener(evt, fn);
+        });
+    }
+    return true;
+};

package/dist/pie/instrumentation-event-map.d.ts

@@ -4,4 +4,5 @@ export type InstrumentationEventMapping = {
 };
 export declare const TOOLKIT_INSTRUMENTATION_EVENT_MAP: InstrumentationEventMapping[];
 export declare const SECTION_INSTRUMENTATION_EVENT_MAP: InstrumentationEventMapping[];
+export declare const ITEM_INSTRUMENTATION_EVENT_MAP: InstrumentationEventMapping[];
 export declare const ASSESSMENT_INSTRUMENTATION_EVENT_MAP: InstrumentationEventMapping[];

package/dist/pie/instrumentation-event-map.js

@@ -67,6 +67,24 @@ export const SECTION_INSTRUMENTATION_EVENT_MAP = [
         instrumentationEventName: "pie-section-element-preload-error",
     },
 ];
+export const ITEM_INSTRUMENTATION_EVENT_MAP = [
+    // Only the security signal is mapped, deliberately. The item player's other
+    // public events (`load-complete`, `player-error`, `model-updated`,
+    // `model-loaded`, `session-changed` and the `backend-*` family) stay off the
+    // bridge because `session-changed` carries the learner's responses, and
+    // forwarding response data to a host's telemetry provider by default is the
+    // host's decision to make rather than this package's default. A host that
+    // wants them can attach its own bridge with its own map.
+    //
+    // `correct-responses-populated` firing at all is the signal: population
+    // requires a controller with `createCorrectResponseSession` in the browser,
+    // which only a `client-player.js` bundle provides, and the attributes that
+    // request it (`add-correct-response`, `env`, `mode`) are all client-mutable.
+    {
+        sourceEventName: "correct-responses-populated",
+        instrumentationEventName: "pie-item-correct-responses-populated",
+    },
+];
 export const ASSESSMENT_INSTRUMENTATION_EVENT_MAP = [
     {
         sourceEventName: "assessment-controller-ready",

package/dist/pie/math-rendering.js

@@ -72,8 +72,12 @@ export async function initializeMathRendering(customRenderer) {
     initPromise = (async () => {
         try {
             const { _dll_pie_lib__math_rendering } = await import("@pie-lib/math-rendering-module/module");
-            setWindowRenderer(_dll_pie_lib__math_rendering);
-            logger.debug("Math rendering module initialized (both globals set)");
+            // A host may install its renderer while the default module is in flight.
+            // The explicit renderer remains authoritative when that happens.
+            if (!getWindowRenderer()) {
+                setWindowRenderer(_dll_pie_lib__math_rendering);
+                logger.debug("Math rendering module initialized (both globals set)");
+            }
         }
         catch (error) {
             logger.error("Failed to initialize math rendering:", error);

package/dist/pie/types.d.ts

@@ -123,6 +123,16 @@ export interface LoadPieElementsOptions {
     bundleUrl?: string;
     eventListeners?: EventListenersMap;
     container?: Element | Document;
+    /**
+     * Deadline in ms for `loadPieModule`'s bundle `<script>` load.
+     *
+     * A stalled request fires neither `load` nor `error`, so without a
+     * deadline the returned promise never settles. Named and defaulted to
+     * match `EnsureRegisteredOptions.loadTimeoutMs` on the `ElementLoader`
+     * primitive, so both bundle-loading paths give a host one budget to
+     * reason about. `0` or negative disables the deadline.
+     */
+    loadTimeoutMs?: number;
 }
 /**
  * Type guard: Check if object has window.pie

package/dist/pie/utils.d.ts

@@ -5,6 +5,33 @@
  */
 import type { ConfigEntity } from "../types/index.js";
 import type { LoadPieElementsOptions } from "./types.js";
+/**
+ * Percent-encode one element package spec for a build-service bundle path.
+ *
+ * `config.elements` is authored content, so a spec must not be able to
+ * restructure the URL. Escaping everything outside
+ * {@link BUNDLE_PATH_LITERAL_CHARS} is what stops it: `#` no longer truncates
+ * the path at a fragment, `?` no longer turns the remainder into a query
+ * string (which in `buildBundleUrl` also swallowed the real `?elements=`
+ * parameter), `\` is no longer normalized to `/` by the URL parser, `%` can
+ * no longer smuggle an escape the build service decodes back into a
+ * separator, and an in-spec `+` becomes `%2B` instead of a phantom package
+ * boundary.
+ *
+ * Both blanket encoders are wrong here, so do not "simplify" to either.
+ * `encodeURI` — what this replaced — leaves `/`, `?`, `#` and `%` alone.
+ * `encodeURIComponent` escapes `/` and `@`, which this route needs literal;
+ * it is correct for the `elements=` query value, which is why both encoders
+ * appear in `buildBundleUrl`.
+ */
+export declare const encodeElementPackageSpec: (spec: string) => string;
+/**
+ * Encode each element package spec and join them with the literal `+` the
+ * legacy IIFE bundle route uses as its package separator. Encoding the joined
+ * string instead would escape the separator. That same separator is why
+ * `element-package-policy` rejects semver build metadata.
+ */
+export declare const encodeElementPackageSpecs: (specs: Iterable<string>) => string;
 /**
  * Build URL for fetching PIE element bundles from build service
  */

package/dist/pie/utils.js

@@ -3,12 +3,67 @@
  *
  * URL building, package name parsing, and session utilities.
  */
+/**
+ * Characters an element package spec may carry into a bundle path unescaped.
+ *
+ * `@` and `/` are in the set because the build service route is
+ * `<host>/<spec>+<spec>.../<bundleType>`, and a scoped spec
+ * (`@pie-element/multiple-choice@9.9.1`) spans path segments inside it —
+ * escaping either yields a path the service does not match. The rest is the
+ * RFC 3986 unreserved set, which covers every npm package name and every
+ * semver version. The `u` flag makes a surrogate pair match as one code
+ * point, so an astral character encodes as a whole character.
+ */
+const BUNDLE_PATH_LITERAL_CHARS = /[^A-Za-z0-9\-._~@/]/gu;
+/** Path segments the URL parser resolves away before a request is sent. */
+const DOT_SEGMENTS = new Set([".", ".."]);
+/**
+ * Percent-encode one element package spec for a build-service bundle path.
+ *
+ * `config.elements` is authored content, so a spec must not be able to
+ * restructure the URL. Escaping everything outside
+ * {@link BUNDLE_PATH_LITERAL_CHARS} is what stops it: `#` no longer truncates
+ * the path at a fragment, `?` no longer turns the remainder into a query
+ * string (which in `buildBundleUrl` also swallowed the real `?elements=`
+ * parameter), `\` is no longer normalized to `/` by the URL parser, `%` can
+ * no longer smuggle an escape the build service decodes back into a
+ * separator, and an in-spec `+` becomes `%2B` instead of a phantom package
+ * boundary.
+ *
+ * Both blanket encoders are wrong here, so do not "simplify" to either.
+ * `encodeURI` — what this replaced — leaves `/`, `?`, `#` and `%` alone.
+ * `encodeURIComponent` escapes `/` and `@`, which this route needs literal;
+ * it is correct for the `elements=` query value, which is why both encoders
+ * appear in `buildBundleUrl`.
+ */
+export const encodeElementPackageSpec = (spec) => {
+    const escaped = spec.replace(BUNDLE_PATH_LITERAL_CHARS, (char) => encodeURIComponent(char));
+    const segments = escaped.split("/");
+    // A literal `/` next to a `.` or `..` segment is the one remaining way
+    // authored content rewrites the path: the URL parser resolves dot segments
+    // before the request is sent, so `@pie-element/../../x` would leave the
+    // bundles route. Percent-encoding the dots does not help — the parser
+    // recognizes `%2e` as a dot segment as well. Escaping every `/` in such a
+    // spec collapses it into one inert segment that 404s inside the route. No
+    // npm package name or subpath is `.` or `..`, so nothing legitimate takes
+    // this branch.
+    return segments.some((segment) => DOT_SEGMENTS.has(segment))
+        ? segments.join("%2F")
+        : escaped;
+};
+/**
+ * Encode each element package spec and join them with the literal `+` the
+ * legacy IIFE bundle route uses as its package separator. Encoding the joined
+ * string instead would escape the separator. That same separator is why
+ * `element-package-policy` rejects semver build metadata.
+ */
+export const encodeElementPackageSpecs = (specs) => Array.from(specs, encodeElementPackageSpec).join("+");
 /**
  * Build URL for fetching PIE element bundles from build service
  */
 export const getPieElementBundlesUrl = (config, opts) => {
     const elements = config.elements;
-    return `${opts.buildServiceBase}/${encodeURI(Object.values(elements).join("+"))}/${opts.bundleType}`;
+    return `${opts.buildServiceBase}/${encodeElementPackageSpecs(Object.values(elements))}/${opts.bundleType}`;
 };
 /**
  * Parse a package name string into its components

package/dist/security/index.d.ts

@@ -1,6 +1,7 @@
 export { buildAuthoringAllowList, createDefaultItemMarkupSanitizer, resetPurifierForTesting, sanitizeItemMarkup, type ItemMarkupSanitizer, type SanitizeItemMarkupOptions, } from "./sanitize-item-markup.js";
 export { parseAllowedStyleOrigins, validateExternalStyleUrl, type StyleUrlValidationError, type StyleUrlValidationOk, type StyleUrlValidationOptions, type StyleUrlValidationResult, } from "./validate-style-url.js";
 export { resetSvgSanitizerForTesting, sanitizeSvgIcon, } from "./sanitize-svg-icon.js";
-export { wrapOverwideImages, wrapOverwideImagesInElement, } from "./wrap-overwide-images.js";
+export { sanitizeStyleAttribute } from "./sanitize-style-attribute.js";
+export { isOverwideImageWrapMutation, wrapOverwideImages, wrapOverwideImagesInElement, } from "./wrap-overwide-images.js";
 export { wrapModelRichContent } from "./wrap-model-rich-content.js";
-export { wrapOverwideTables, wrapOverwideTablesInElement, } from "./wrap-overwide-tables.js";
+export { isOverwideTableWrapMutation, wrapOverwideTables, wrapOverwideTablesInElement, } from "./wrap-overwide-tables.js";

package/dist/security/index.js

@@ -1,6 +1,7 @@
 export { buildAuthoringAllowList, createDefaultItemMarkupSanitizer, resetPurifierForTesting, sanitizeItemMarkup, } from "./sanitize-item-markup.js";
 export { parseAllowedStyleOrigins, validateExternalStyleUrl, } from "./validate-style-url.js";
 export { resetSvgSanitizerForTesting, sanitizeSvgIcon, } from "./sanitize-svg-icon.js";
-export { wrapOverwideImages, wrapOverwideImagesInElement, } from "./wrap-overwide-images.js";
+export { sanitizeStyleAttribute } from "./sanitize-style-attribute.js";
+export { isOverwideImageWrapMutation, wrapOverwideImages, wrapOverwideImagesInElement, } from "./wrap-overwide-images.js";
 export { wrapModelRichContent } from "./wrap-model-rich-content.js";
-export { wrapOverwideTables, wrapOverwideTablesInElement, } from "./wrap-overwide-tables.js";
+export { isOverwideTableWrapMutation, wrapOverwideTables, wrapOverwideTablesInElement, } from "./wrap-overwide-tables.js";

package/dist/security/sanitize-forbidden-lists.js

@@ -13,6 +13,15 @@ export const SANITIZER_FORBIDDEN_TAGS = [
     "form",
     "meta",
     "link",
+    // A <style> element is a document-global stylesheet. The item player renders
+    // in light DOM (`shadow: "none"`), so a <style> in authored markup restyles
+    // host chrome outside the item. DOMPurify's defaults already drop a
+    // top-level HTML <style>; the SVG profile keeps one, whose rules apply
+    // document-wide all the same — verified in Chromium 2026-08-30, where
+    // `<svg><style>` passed this list and hid an element outside the player.
+    // `style` is in DOMPurify's default FORBID_CONTENTS, so the CSS text is
+    // dropped with the tag rather than surfacing as item text.
+    "style",
     // <foreignObject> inside an <svg> is a well-known escape hatch back into
     // HTML context.
     "foreignobject",

package/dist/security/sanitize-item-markup.js

@@ -9,6 +9,7 @@
  */
 import DOMPurify from "dompurify";
 import { SANITIZER_FORBIDDEN_ATTRS, SANITIZER_FORBIDDEN_TAGS, } from "./sanitize-forbidden-lists.js";
+import { installStyleAttributeHook } from "./sanitize-style-attribute.js";
 import { wrapOverwideImages } from "./wrap-overwide-images.js";
 import { wrapOverwideTables } from "./wrap-overwide-tables.js";
 // Attributes every PIE element / wrapper is allowed to carry.
@@ -53,6 +54,9 @@ function resolvePurifier() {
         typeof factory === "function"
             ? factory(window)
             : DOMPurify;
+    // `style` is URI-safe to DOMPurify, so nothing inside it is inspected
+    // without this. See sanitize-style-attribute.ts.
+    installStyleAttributeHook(purifierInstance);
     return purifierInstance;
 }
 /**