@pie-element/element-player 0.1.1 → 0.1.2-next.1

package/README.md

@@ -32,9 +32,36 @@ The package has a dependency resolution issue that prevents it from building as
 
 The element player is a **standalone web component bundle** (`pie-element-player.js`) that can be dropped into any HTML page with a simple `<script>` tag. It loads PIE elements via dynamic ESM imports.
 
+## Recommendation
+
+Use the player as a **Node package dependency** in modern applications.
+
+- Recommended: install/import via package manager and bundle with your app.
+- Secondary/fallback: dynamic script/import-map loading for environments that cannot bundle.
+
+Positioning note:
+
+- In normal production integrations, use the standard production player stacks from the upstream PIE projects (`../pie-elements` and `../pie-players`).
+- Treat `@pie-element/element-player` as a flexible element-level host for development, testing, and composable/advanced embedding scenarios.
+
+Why this is preferred:
+
+- Better build-time optimization and dependency deduplication
+- More reliable versioning through lockfiles
+- Better TypeScript/IDE support and compile-time validation
+- Fewer runtime resolution issues (CDN/import-map/config drift)
+
 ## Usage
 
-### ESM Player
+### Recommended: Node package integration
+
+```ts
+import '@pie-element/element-player/players';
+```
+
+Then render the host component and set `model`/`session` via properties in your framework/runtime.
+
+### Dynamic loading fallback (supported)
 
 For elements with import maps:
 
@@ -45,10 +72,11 @@ For elements with import maps:
   <title>PIE Element Demo</title>
 </head>
 <body>
-  <pie-esm-element-player
+  <pie-element-player
     id="player"
     element-name="hotspot"
-  ></pie-esm-element-player>
+    view="delivery"
+  ></pie-element-player>
 
   <!-- Import map for module resolution -->
   <script type="importmap">
@@ -60,7 +88,7 @@ For elements with import maps:
   </script>
 
   <!-- Load the player bundle -->
-  <script type="module" src="/packages/shared/element-player/dist/pie-element-player.js"></script>
+  <script type="module" src="/packages/element-player/dist/pie-element-player.js"></script>
 
   <script type="module">
     const player = document.getElementById('player');
@@ -73,9 +101,9 @@ For elements with import maps:
 
 ## Architecture
 
-### ESM Players
+### Unified Player
 
-**Interactive Player (`<pie-esm-element-player>`):**
+**Delivery view (`<pie-element-player view="delivery">`):**
 
 - Loads elements via dynamic ESM imports: `import('@pie-element/hotspot')`
 - Handles session state and user interactions
@@ -83,7 +111,7 @@ For elements with import maps:
 - Emits `session-changed` events
 - Works with both React and Svelte elements
 
-**Print Player (`<pie-esm-print-player>`):**
+**Print view (`<pie-element-player view="print">`):**
 
 - Loads print exports: `import('@pie-element/hotspot/print')`
 - Stateless (no session management)
@@ -91,7 +119,7 @@ For elements with import maps:
 - Manages math rendering internally (MathJax)
 - Role-based rendering (student/instructor)
 
-**Both players:**
+**All views:**
 
 - Use import maps for module resolution
 - Self-contained (no external setup needed)
@@ -120,10 +148,10 @@ To test changes to player components:
 
 ```bash
 # Build element-player
-cd packages/shared/element-player
+cd packages/element-player
 bun run build
 
 # Run element demo
-cd ../../../
+cd ../..
 bun cli dev:demo hotspot
 ```

package/dist/index.d.ts

@@ -5,11 +5,15 @@
  * Handles element loading, math rendering, and session management internally.
  *
  * Usage:
- *   <pie-esm-element-player element-name="hotspot"></pie-esm-element-player>
- *   <pie-esm-print-player element-name="hotspot" role="student"></pie-esm-print-player>
+ *   <pie-element-player element-name="hotspot" view="delivery"></pie-element-player>
+ *   <pie-element-player element-name="hotspot" view="print" role="student"></pie-element-player>
  */
 import './app.css';
-export { EsmElementPlayer, EsmPrintPlayer } from './players';
-import './players';
-export type { ElementPlayerProps, PieController, Tab } from './lib/types';
-//# sourceMappingURL=index.d.ts.map
+import './players/index.js';
+export type { ElementPlayerProps, PieController, Tab } 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';
+export { normalizeElementPlayerStrategy, normalizeElementPlayerView, resolveElementPlayerView, } from './lib/player-strategy.js';
+export { configureUnifiedPlayerResolver, type ControllerLoadDiagnostic, type RuntimeSupportDiagnostic, } from './lib/unified-player-loader.js';
+export { configureIifeBundleLoader, IifeBundleLoadError, type IifeBuildClient, type IifeRegistryClient, type IifeBundleLoaderAdapters, type IifeBundleRetryConfig, type IifeBundleRetryStatus, DEFAULT_IIFE_BUNDLE_RETRY_CONFIG, } from './lib/iife-bundle-loader.js';

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

@@ -4,6 +4,17 @@
  * 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';
+export type ElementModuleKind = 'delivery' | 'author' | 'print' | 'controller' | 'runtime-support';
+export interface ElementModuleResolveRequest {
+    packagePath: string;
+    packageName: string;
+    elementName: string;
+    kind: ElementModuleKind;
+    cdnUrl: string;
+}
+export type ElementModuleResolver = (request: ElementModuleResolveRequest) => Promise<unknown | null | undefined> | unknown | null | undefined;
+export declare function configureElementModuleResolver(resolver?: ElementModuleResolver): void;
 /**
  * Load and register a PIE element as a custom element
  *
@@ -23,4 +34,8 @@ export declare function loadElement(packagePath: string, tagName: string, cdnUrl
  * @returns Controller object with model/score/outcome methods
  */
 export declare function loadController(packageName: string, cdnUrl: string, debug?: boolean): Promise<any>;
-//# sourceMappingURL=element-loader.d.ts.map
+/**
+ * Load optional runtime support metadata module.
+ * Missing module should be handled by caller as an optional capability.
+ */
+export declare function loadRuntimeSupport(packageName: string, cdnUrl: string, debug?: boolean): Promise<PieElementRuntimeSupport>;

package/dist/lib/iife-bundle-loader.d.ts

@@ -0,0 +1,98 @@
+type IifeBundleTarget = 'player' | 'client-player' | 'editor';
+export interface IifeBundleRetryConfig {
+    retryDelayMs?: number;
+    timeoutMs?: number;
+}
+export interface IifeBundleRetryStatus {
+    state: 'retrying' | 'completed' | 'timeout' | 'cancelled';
+    stage: 'build-start' | 'build-status' | 'script-load';
+    attempt: number;
+    elapsedMs: number;
+    retryDelayMs?: number;
+    timeoutMs: number;
+    reason?: string;
+}
+export declare const DEFAULT_IIFE_BUNDLE_RETRY_CONFIG: {
+    readonly retryDelayMs: 3000;
+    readonly timeoutMs: 120000;
+};
+export interface LocalBundleMeta {
+    hash?: string;
+    duration?: number;
+    cached?: boolean;
+    source: 'local' | 'hosted';
+    url: string;
+}
+export interface IifePackageExports {
+    Element?: CustomElementConstructor;
+    Print?: CustomElementConstructor;
+    controller?: any;
+    Configure?: CustomElementConstructor;
+}
+export interface IifeBuildResult {
+    success: boolean;
+    bundles?: {
+        player?: string;
+        clientPlayer?: string;
+        editor?: string;
+    };
+    hash: string;
+    duration: number;
+    cached?: boolean;
+    errors?: string[];
+}
+export declare class IifeBundleLoadError extends Error {
+    code: 'BUILD_START_FAILED' | 'BUILD_STATUS_FAILED' | 'BUILD_RESULT_FAILED' | 'BUNDLE_URL_MISSING' | 'SCRIPT_LOAD_FAILED' | 'REGISTRY_INVALID' | 'PACKAGE_MISSING' | 'LOAD_ABORTED';
+    metadata?: Record<string, unknown>;
+    constructor(code: 'BUILD_START_FAILED' | 'BUILD_STATUS_FAILED' | 'BUILD_RESULT_FAILED' | 'BUNDLE_URL_MISSING' | 'SCRIPT_LOAD_FAILED' | 'REGISTRY_INVALID' | 'PACKAGE_MISSING' | 'LOAD_ABORTED', message: string, metadata?: Record<string, unknown>);
+}
+export interface IifeBuildClient {
+    startBuild(request: {
+        endpoint: string;
+        packageName: string;
+        version: string;
+        bundleTarget: IifeBundleTarget;
+        forceRebuild: boolean;
+        clearCache: boolean;
+    }): Promise<{
+        buildId: string;
+        hash?: string;
+    }>;
+    waitForBuildResult(request: {
+        endpoint: string;
+        buildId: string;
+        onProgress?: (event: {
+            stage: string;
+            message?: string;
+        }) => void;
+    }): Promise<IifeBuildResult>;
+}
+export interface IifeRegistryClient {
+    load(url: string): Promise<Record<string, IifePackageExports>>;
+}
+export interface IifeBundleLoaderAdapters {
+    buildClient?: IifeBuildClient;
+    registryClient?: IifeRegistryClient;
+}
+export declare function configureIifeBundleLoader(adapters?: IifeBundleLoaderAdapters): void;
+export declare function loadIifePackage(opts: {
+    packageName: string;
+    version: string;
+    endpoint?: string;
+    bundleHost?: string;
+    forceRebuild?: boolean;
+    clearCache?: boolean;
+    bundleTarget?: IifeBundleTarget;
+    iifeBundleRetry?: IifeBundleRetryConfig;
+    onProgress?: (event: {
+        stage: string;
+        message?: string;
+    }) => void;
+    onRetryStatus?: (status: IifeBundleRetryStatus) => void;
+    signal?: AbortSignal;
+    adapters?: IifeBundleLoaderAdapters;
+}): Promise<{
+    pkg: IifePackageExports;
+    meta: LocalBundleMeta;
+}>;
+export {};

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

@@ -0,0 +1,7 @@
+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/player-strategy.d.ts

@@ -0,0 +1,9 @@
+export type ElementPlayerStrategy = 'esm' | 'iife' | 'preloaded';
+export type ElementPlayerView = 'delivery' | 'author' | 'print';
+export interface ResolveElementPlayerViewInput {
+    mode?: string | null;
+    view?: ElementPlayerView | null;
+}
+export declare function normalizeElementPlayerStrategy(value: string | null | undefined, fallback?: ElementPlayerStrategy): ElementPlayerStrategy;
+export declare function normalizeElementPlayerView(value: string | null | undefined, fallback?: ElementPlayerView): ElementPlayerView;
+export declare function resolveElementPlayerView(input: ResolveElementPlayerViewInput, fallback?: ElementPlayerView): ElementPlayerView;

package/dist/lib/runtime-support.d.ts

@@ -0,0 +1,12 @@
+export type RuntimeSupportCheck = 'off' | 'on';
+export type RuntimeSupportStrategy = 'esm' | 'iife';
+export type RuntimeSupportView = 'delivery' | 'author' | 'print';
+export interface PieElementRuntimeSupport {
+    schemaVersion: number;
+    packageName?: string;
+    version?: string;
+    supports?: Partial<Record<RuntimeSupportStrategy, Partial<Record<RuntimeSupportView, boolean>>>>;
+}
+export declare function normalizeRuntimeSupportCheck(value: string | null | undefined, fallback?: RuntimeSupportCheck): RuntimeSupportCheck;
+export declare function isRuntimeSupportEnabled(mode: RuntimeSupportCheck): boolean;
+export declare function isStrategySupportedForView(runtimeSupport: PieElementRuntimeSupport, strategy: RuntimeSupportStrategy, view: RuntimeSupportView): boolean;

package/dist/lib/types.d.ts

@@ -4,6 +4,7 @@
 export interface ElementPlayerProps {
     elementName: string;
     cdnUrl?: string;
+    runtimeSupportCheck?: 'off' | 'on';
     model?: any;
     session?: any;
     mode?: 'gather' | 'view' | 'evaluate';
@@ -23,4 +24,3 @@ export interface Tab {
     description?: string;
     disabled?: boolean;
 }
-//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,51 @@
+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';
+export interface UnifiedPlayerLoadRequest {
+    strategy: string | null | undefined;
+    view: string | null | undefined;
+    elementName: string;
+    packageName: string;
+    elementVersion: string;
+    cdnUrl?: string;
+    iifeBundleEndpoint?: string;
+    iifeBundleHost?: string;
+    iifeBundleRetry?: IifeBundleRetryConfig;
+    onIifeBundleRetryStatus?: (status: IifeBundleRetryStatus) => void;
+    signal?: AbortSignal;
+    rebuildVersion?: number;
+    preloadedFallbackStrategy?: ElementPlayerStrategy;
+    runtimeSupportCheck?: RuntimeSupportCheck | string | null;
+}
+export interface ControllerLoadDiagnostic {
+    status: 'loaded' | 'missing' | 'failed' | 'not-required';
+    source: 'module' | 'bundle' | 'none';
+    packageName: string;
+    strategy: ElementPlayerStrategy;
+    view: ElementPlayerView;
+    message?: string;
+}
+export interface UnifiedPlayerLoadResult {
+    strategy: ElementPlayerStrategy;
+    requestedStrategy?: ElementPlayerStrategy;
+    view: ElementPlayerView;
+    tagName: string;
+    controller?: any;
+    bundleMeta?: LocalBundleMeta;
+    controllerDiagnostic?: ControllerLoadDiagnostic;
+    runtimeSupport?: PieElementRuntimeSupport;
+    runtimeSupportDiagnostic?: RuntimeSupportDiagnostic;
+    diagnostics?: {
+        iife?: IifeBundleLoadError;
+    };
+}
+export interface RuntimeSupportDiagnostic {
+    status: 'loaded' | 'missing' | 'failed' | 'skipped';
+    packageName: string;
+    strategy: ElementPlayerStrategy;
+    view: ElementPlayerView;
+    message?: string;
+}
+export declare function configureUnifiedPlayerResolver(resolver?: ElementModuleResolver): void;
+export declare function loadUnifiedPlayer(request: UnifiedPlayerLoadRequest): Promise<UnifiedPlayerLoadResult>;

package/dist/math-mathjax-YIPQGZlD.js

@@ -0,0 +1,59 @@
+//#region ../shared/math-rendering-mathjax/dist/index.js
+var e = null;
+function t(t) {
+	return typeof window > "u" || window.MathJax?.typesetPromise ? Promise.resolve() : e || (e = new Promise((e, n) => {
+		let { useSingleDollar: r = !1, accessibility: i = !0, loadFonts: a = !0, srcUrl: o } = t, s = {
+			loader: { load: i ? ["a11y/assistive-mml"] : [] },
+			tex: {
+				packages: [
+					"base",
+					"ams",
+					"autoload"
+				],
+				macros: {
+					parallelogram: "\\lower.2em{\\Huge\\unicode{x25B1}}",
+					overarc: "\\overparen",
+					napprox: "\\not\\approx",
+					longdiv: "\\enclose{longdiv}"
+				}
+			},
+			options: {
+				enableMenu: i,
+				enableExplorer: i,
+				enableAssistiveMml: i
+			},
+			startup: {
+				ready: () => {
+					window.MathJax?.startup.defaultReady && (window.MathJax.startup.defaultReady(), e());
+				},
+				defaultReady: () => {}
+			}
+		};
+		r && s.tex && (s.tex.inlineMath = [["$", "$"], ["\\(", "\\)"]], s.tex.processEscapes = !0), a || (s.chtml = { fontURL: "" }), window.MathJax = s;
+		let c = document.createElement("script");
+		c.src = o || "https://cdn.jsdelivr.net/npm/mathjax@4/tex-chtml.js", c.async = !0, c.onload = () => {
+			setTimeout(e, 100);
+		}, c.onerror = () => {
+			n(/* @__PURE__ */ Error("Failed to load MathJax"));
+		}, document.head.appendChild(c);
+	}), e);
+}
+function n() {
+	let e = window.MathJax?.startup?.document;
+	if (typeof e?.assistiveMml == "function") try {
+		e.assistiveMml().updateDocument?.();
+	} catch (e) {
+		console.warn("[mathjax-renderer] Failed to attach assistive MathML:", e);
+	}
+}
+function r(e = {}) {
+	return async (r) => {
+		if (await t(e), !window.MathJax?.typesetPromise) {
+			console.warn("[mathjax-renderer] MathJax not loaded or missing typesetPromise.");
+			return;
+		}
+		await window.MathJax.typesetPromise([r]), n();
+	};
+}
+//#endregion
+export { r as t };