@pie-element/element-player 0.1.2-next.2 → 0.1.2-next.20261002100925

package/README.md

@@ -1,30 +1,6 @@
 # PIE Element Player
 
-Self-contained web components for rendering PIE elements, following the same architecture as `@pie-framework/pie-players`.
-
----
-
-## ⚠️ IMPORTANT: NOT FOR PUBLISHING
-
-**This package is currently marked as `private` and should NOT be published to npm.**
-
-### Build Issue
-
-The package has a dependency resolution issue that prevents it from building as a standalone library:
-
-- [element-loader.ts](src/lib/element-loader.ts) imports `$lib/element-imports` for local development mode
-- This import only exists in the element-demo app, not in this package
-- The import is marked as external in the build config as a workaround
-- For production use, this architecture needs to be refactored
-
-**Before publishing this package**, the following must be resolved:
-
-1. Refactor the element-loader to not depend on app-specific imports
-2. Either remove local development mode from the library OR provide a proper abstraction
-3. Ensure the build completes successfully without external dependencies on non-existent modules
-4. Remove the `"private": true` field from package.json
-
-**Issue tracked in**: Build fails with "Rollup failed to resolve import '$lib/element-imports'"
+Self-contained web components for rendering PIE elements, following the same architecture as the `@pie-players/*` players in [pie-players](https://github.com/pie-framework/pie-players).
 
 ---
 
@@ -107,7 +83,6 @@ For elements with import maps:
 
 - Loads elements via dynamic ESM imports: `import('@pie-element/hotspot')`
 - Handles session state and user interactions
-- Manages math rendering internally (MathJax)
 - Emits `session-changed` events
 - Works with both React and Svelte elements
 
@@ -116,23 +91,50 @@ For elements with import maps:
 - Loads print exports: `import('@pie-element/hotspot/print')`
 - Stateless (no session management)
 - Optimized for print layouts
-- Manages math rendering internally (MathJax)
 - Role-based rendering (student/instructor)
 
 **All views:**
 
 - Use import maps for module resolution
 - Self-contained (no external setup needed)
-- Handle math rendering automatically
 - Support for both React and Svelte elements
 
+### Math rendering
+
+The player typesets math through `window['@pie-lib/math-rendering'].renderMath`, read on every render. A renderer the host installs there before the player mounts, such as the legacy MathJax 3 one, is used and no MathJax 4 loads. Without one, the player installs a MathJax 4 renderer from `@pie-element/shared-math-rendering-mathjax`, which elements and later players on the page share.
+
+### Events
+
+The player dispatches each event from `<pie-element-player>`, bubbling and composed. A bubble-phase listener on the player, on an ancestor or on `document` hears each event once, with `event.target` the player; a listener outside a shadow root that contains the player sees that root's host instead. The element's own `session-changed` stops at the element, and the player dispatches its copy in its place. A capture-phase listener on the player or above it also hears every `session-changed` the element dispatches, ahead of the player's copy, and should ignore events whose `event.composedPath()[0]` is not the player. That equals `event.target` when no shadow root lies between listener and player. A closed shadow root hides the player from both, so listen in the bubble phase there.
+
+| Event | When | `detail` |
+|---|---|---|
+| `session-changed` | delivery: the learner changes the session, or the element re-reports a session the player set (below) | the element's detail, with `session` the new session |
+| `model-changed` | author: the author edits the model | the whole model |
+| `load-complete` | the element is mounted | `strategy`, `view`, `tagName` |
+| `load-cancelled` | a newer load supersedes this one, or the load fails with an abort error (below) | `reason`, `strategy`, `view` |
+| `player-error` | the load fails | `error`, `strategy`, `view`, `retry` |
+| `build-state` | the load changes stage | `loading`, `error`, `stage`, and `strategy`, `view`, `retry` where known |
+| `bundle-retry-status` | IIFE: a bundle build is polled; any strategy: the load fails with an abort error | the retry state |
+| `bundle-meta` | IIFE: the bundle loads | the bundle's metadata |
+| `controller-load` | a load completes, except a `preloaded` one that finds its tag defined (below) | `status`, `source`, `packageName`, `strategy`, `view`, `message` |
+| `controller-changed` | IIFE delivery: the bundle's controller loads | the controller |
+
+`session-changed` also fires with no learner action. Once the element has a model, the player sets `session` on it, and sets it again whenever the host assigns a different session. A report the element dispatches while that setter runs is dropped; one it dispatches after the setter returns is forwarded.
+
+An abort error is a load error whose message contains `aborted`, whatever the strategy. The player then emits `bundle-retry-status` with state `cancelled`, `build-state` with stage `cancelled` and `load-cancelled`, in place of `player-error`.
+
+`controller-load` reports `status` `loaded` in delivery view, where any other status fails the load. Author view can also report `missing` or `failed`, and print view reports `not-required` unless an IIFE bundle carries a controller.
+
+A player removed from the document mid-load emits nothing more from that load, and re-attaching it starts a new one; a synchronous move keeps the load.
+
 ## Testing Elements Locally
 
 Use the existing demo commands to test elements:
 
 ```bash
-# Start demo server for Svelte elements
-bun cli dev:demo hotspot
+# Start the element demo, then open http://localhost:5222/hotspot/deliver
+bun cli dev:demo
 ```
 
 **Prerequisites:**
@@ -153,5 +155,5 @@ bun run build
 
 # Run element demo
 cd ../..
-bun cli dev:demo hotspot
+bun cli dev:demo
 ```

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  */
 import './app.css';
 import './players/index.js';
-export type { ElementPlayerProps, PieController, Tab } from './lib/types.js';
+export type { ElementPlayerProps, PieController } from './lib/types.js';
 export type { ElementPlayerStrategy, ElementPlayerView } from './lib/player-strategy.js';
 export type { RuntimeSupportCheck, RuntimeSupportStrategy, RuntimeSupportView, PieElementRuntimeSupport, } from './lib/runtime-support.js';
 export { normalizeRuntimeSupportCheck } from './lib/runtime-support.js';

package/dist/lib/element-loader.d.ts

@@ -4,7 +4,7 @@
  * Dynamically loads PIE elements from CDN and registers them as custom elements.
  * Based on the ESM loader pattern from pie-players.
  */
-import type { PieElementRuntimeSupport } from './runtime-support';
+import type { PieElementRuntimeSupport } from './runtime-support.js';
 export type ElementModuleKind = 'delivery' | 'author' | 'print' | 'controller' | 'runtime-support';
 export interface ElementModuleResolveRequest {
     packagePath: string;

package/dist/lib/math-rendering-types.d.ts

@@ -1,7 +1 @@
 export type MathRenderer = (element: HTMLElement) => void | Promise<void>;
-export interface MathRenderingAPI {
-    renderMath: MathRenderer;
-    wrapMath?: (latex: string) => string;
-    unWrapMath?: (wrapped: string) => string;
-    mmlToLatex?: (mathml: string) => string;
-}

package/dist/lib/types.d.ts

@@ -18,9 +18,3 @@ export interface PieController {
     outcome?: (model: any, session: any, env: any) => Promise<any>;
     createCorrectResponseSession?: (model: any, env: any) => Promise<any>;
 }
-export interface Tab {
-    id: string;
-    label: string;
-    description?: string;
-    disabled?: boolean;
-}

package/dist/lib/unified-player-loader.d.ts

@@ -1,7 +1,7 @@
-import { type ElementModuleResolver } from './element-loader';
-import { type IifeBundleRetryConfig, type IifeBundleRetryStatus, type IifeBundleLoadError, type LocalBundleMeta } from './iife-bundle-loader';
-import { type ElementPlayerStrategy, type ElementPlayerView } from './player-strategy';
-import { type PieElementRuntimeSupport, type RuntimeSupportCheck } from './runtime-support';
+import { type ElementModuleResolver } from './element-loader.js';
+import { type IifeBundleRetryConfig, type IifeBundleRetryStatus, type IifeBundleLoadError, type LocalBundleMeta } from './iife-bundle-loader.js';
+import { type ElementPlayerStrategy, type ElementPlayerView } from './player-strategy.js';
+import { type PieElementRuntimeSupport, type RuntimeSupportCheck } from './runtime-support.js';
 export interface UnifiedPlayerLoadRequest {
     strategy: string | null | undefined;
     view: string | null | undefined;

package/dist/math-mathjax-Y_CMClAV.js

@@ -0,0 +1,179 @@
+//#region ../shared/math-rendering-mathjax/dist/index.js
+var e = "https://github.com/pie-framework/pie-players/blob/develop/docs/item-player/loading-strategies.md#one-mathjax-version-per-page", t = Symbol.for("@pie-element/shared-math-rendering-mathjax/unsupported-page");
+function n(n, r) {
+	if (typeof window > "u") return;
+	let i = globalThis;
+	i[t] ??= {
+		logged: !1,
+		conditions: []
+	};
+	let a = i[t];
+	if (a.conditions.includes(n)) return;
+	a.conditions.push(n);
+	let o = `[math-rendering] Unsupported page (${n}): ${r}. PIE supports one MathJax major version per page; with MathJax 3 and 4 on one page, math rendering is best effort and may break. See ${e}`;
+	a.logged || (a.logged = !0, console.error(o)), window.dispatchEvent(new CustomEvent("pie-mathjax-version-conflict", { detail: {
+		condition: n,
+		message: o,
+		docsUrl: e
+	} }));
+}
+function r() {
+	let e = window.MathJax?.version;
+	return typeof e == "string" && e.startsWith("3.") ? e : void 0;
+}
+var i = "https://cdn.jsdelivr.net/npm/mathjax@4.1.3/tex-mml-chtml.js", a = {
+	parallelogram: "\\lower.2em{\\Huge\\unicode{x25B1}}",
+	overarc: "\\overparen",
+	napprox: "\\not\\approx",
+	longdiv: "\\enclose{longdiv}",
+	abs: ["\\left|#1\\right|", 1]
+}, o = "[math-rendering] using $ is not advisable, please use $$..$$ or \\(...\\)", s = /\\\(|\\\[|\$\$|\\\$|\\begin\{|\\(?:eq)?ref\{/, c = /\\\(|\\\[|\$|\\begin\{|\\(?:eq)?ref\{/, l = /\\embed\{newLine\}\[\]/g, u = [
+	["$$", "$$"],
+	["$", "$"],
+	["\\[", "\\]"],
+	["\\(", "\\)"]
+], d = Symbol.for("@pie-element/shared-math-rendering-mathjax/loading"), f = "PIE-MJX-CHTML-styles", p = "MJX-CHTML-styles", m = [p, "MJX-SVG-styles"], h = 201;
+function g(e) {
+	let t = [...e.matches("mjx-container") ? [e] : [], ...e.querySelectorAll("mjx-container")];
+	for (let e of t) for (let t of [e, ...e.querySelectorAll("[data-latex],[data-latex-item]")]) t.removeAttribute("data-latex"), t.removeAttribute("data-latex-item");
+}
+function _() {
+	return window.MathJax;
+}
+function v(e) {
+	for (let [t, n] of u) if (e.startsWith(t) && e.endsWith(n)) return e.substring(t.length, e.length - n.length);
+	return e;
+}
+function y(e) {
+	return v(e.includes("\\displaystyle") ? e.replace("\\displaystyle", "").trim() : e);
+}
+var b = "mathjax_ignore", x = "mathjax_process";
+function S(e, t) {
+	let n = e.closest(`.${b}, .${x}`);
+	return n !== null && t.contains(n) && !n.classList.contains(x);
+}
+function C(e) {
+	for (let t of e.querySelectorAll("[data-latex]")) {
+		if (t.dataset.mathHandled || t.closest("mjx-container") || S(t, e)) continue;
+		let n = t.textContent;
+		n && (t.textContent = `\\(${y(n)}\\)`.replace(l, "\\newline "), t.dataset.mathHandled = "true");
+	}
+}
+function w(e, t) {
+	for (let t of e.querySelectorAll("math")) if (!t.closest("mjx-assistive-mml")) return !0;
+	return (t ? c : s).test(e.textContent ?? "");
+}
+function T(e) {
+	return new Promise((t, n) => {
+		let { useSingleDollar: r = !1, accessibility: s = !0, loadFonts: c = !0, srcUrl: l } = e, u = {
+			loader: {
+				load: s ? ["a11y/assistive-mml"] : [],
+				failed: (e) => n(e)
+			},
+			startup: {
+				typeset: !1,
+				ready: () => {
+					let e = _(), r = e?.startup, i = !!e?.version?.startsWith("4.");
+					i && E(e), r?.defaultReady?.(), i && D(r?.document), Promise.resolve(r?.promise).then(() => t(), n);
+				}
+			},
+			tex: { macros: { ...a } },
+			options: {
+				enableMenu: s,
+				menuOptions: { settings: {
+					assistiveMml: s,
+					enrich: !1,
+					inTabOrder: !1
+				} }
+			}
+		};
+		r && u.tex && (console.warn(o), u.tex.inlineMath = [["$", "$"], ["\\(", "\\)"]], u.tex.processEscapes = !0), c || (u.chtml = { fontURL: "" }), window.MathJax = u;
+		let d = document.createElement("script");
+		d.src = l || i, d.async = !0, d.onerror = () => n(/* @__PURE__ */ Error("Failed to load MathJax")), document.head.appendChild(d);
+	});
+}
+function E(e) {
+	let t = e?._?.output?.chtml_ts?.CHTML;
+	t && (t.STYLESHEETID = f);
+}
+function D(e) {
+	if (!e) return;
+	let t = /* @__PURE__ */ new WeakSet(), n = (e) => {
+		let n = e.typesetRoot;
+		!n || t.has(n) || (g(n), t.add(n));
+	};
+	e.addRenderAction?.("pie-strip-latex", h, (e) => {
+		for (let t of e.math ?? []) n(t);
+		return !1;
+	}, (e) => {
+		let t = e.typesetRoot;
+		return t && g(t), !1;
+	});
+	let r = e.outputJax?.chtmlStyles;
+	r?.id === p && (r.id = f), A();
+}
+function O(e) {
+	return e instanceof HTMLStyleElement && m.includes(e.id);
+}
+function k(e) {
+	n("foreign-output-stylesheet", `another MathJax added <style id="${e.id}"> to <head>`);
+}
+function A() {
+	let e = document.head, t = [...e.children].find(O);
+	if (t) {
+		k(t);
+		return;
+	}
+	let n = new MutationObserver((e) => {
+		for (let t of e) {
+			let e = [...t.addedNodes].find(O);
+			if (e) {
+				k(e), n.disconnect();
+				return;
+			}
+		}
+	});
+	n.observe(e, { childList: !0 });
+}
+function j(e) {
+	return new Promise((t, n) => {
+		let r = e.startup ?? {};
+		e.startup = r;
+		let i = r.ready;
+		r.ready = () => {
+			let e = _()?.startup;
+			i ? i.call(r) : e?.defaultReady?.(), Promise.resolve(e?.promise).then(() => t(), n);
+		};
+	});
+}
+function M(e) {
+	let t = _();
+	return t ? t.version ? t.startup?.promise ? Promise.resolve(t.startup.promise).then(() => void 0) : Promise.resolve() : j(t) : T(e);
+}
+function N(e) {
+	return M(e).then(() => {
+		typeof _()?.typesetPromise != "function" && console.warn("[mathjax-renderer] MathJax on this page has no typesetPromise; math stays untypeset.");
+	});
+}
+function P(e) {
+	let t = globalThis, n = t[d];
+	return n || (n = N(e), t[d] = n), n;
+}
+function F(e = {}) {
+	let t = e.useSingleDollar ?? !1;
+	return async (i) => {
+		if (typeof window > "u") return;
+		let a = r();
+		a && n("mathjax-3-global", `window.MathJax is MathJax ${a}`), C(i);
+		let o = P(e);
+		if (!w(i, t)) {
+			o.catch(() => {});
+			return;
+		}
+		await o;
+		let s = _();
+		await s?.startup?.promise, typeof s?.typesetPromise == "function" && (await s.typesetPromise([i]), g(i));
+	};
+}
+//#endregion
+export { F as t };