@pie-players/pie-assessment-toolkit 0.2.9 → 0.2.10

package/src/components/PieAssessmentToolkit.svelte

@@ -61,10 +61,14 @@
 
 	const runtimeId = createRuntimeId("toolkit");
 	const sectionEngine = new SectionRuntimeEngine();
+const DEFAULT_ENV = {
+	mode: "gather",
+	role: "student",
+} as const;
 	const DEFAULT_ITEM_PLAYER_BY_TYPE: Record<ItemPlayerType, string> = {
-		iife: "pie-iife-player",
-		esm: "pie-esm-player",
-		fixed: "pie-fixed-player",
+		iife: "pie-item-player",
+		esm: "pie-item-player",
+	preloaded: "pie-item-player",
 		custom: "",
 	};
 
@@ -98,7 +102,10 @@
 	let compositionVersion = $state(0);
 	let compositionModel = $state<unknown>(null);
 	let runtimeError = $state<unknown>(null);
-	let lastCompositionSignature = $state<string>("");
+	let lastCompositionRevisionKey = $state("");
+	let pendingCompositionModel: unknown = null;
+	let pendingCompositionEmit = false;
+	let compositionEmitRaf: number | null = null;
 
 	function getHostElement(): HTMLElement | null {
 		if (!anchor) return null;
@@ -115,8 +122,59 @@
 		dispatchCrossBoundaryEvent(host, name, detail);
 	}
 
+	function hashString(input: string): string {
+		let hash = 5381;
+		for (let index = 0; index < input.length; index += 1) {
+			hash = ((hash << 5) + hash) ^ input.charCodeAt(index);
+		}
+		return (hash >>> 0).toString(36);
+	}
+
+	function getCompositionRevisionKey(model: unknown): string {
+		const typed = (model || {}) as Record<string, unknown>;
+		const sectionId =
+			((typed.section as Record<string, unknown> | undefined)?.identifier as string) ||
+			(typed.sectionId as string) ||
+			"";
+		const currentItemIndex =
+			typeof typed.currentItemIndex === "number" ? typed.currentItemIndex : -1;
+		const renderables = Array.isArray(typed.renderables) ? typed.renderables : [];
+		const renderableSignature = renderables
+			.map((entry, index) => {
+				const row = (entry || {}) as Record<string, unknown>;
+				const entity = (row.entity || {}) as Record<string, unknown>;
+				const entityId =
+					(typeof entity.id === "string" && entity.id) || `renderable-${index}`;
+				const entityVersion =
+					(typeof entity.version === "string" && entity.version) ||
+					(typeof entity.version === "number" ? String(entity.version) : "") ||
+					(typeof (entity.config as Record<string, unknown> | undefined)?.version === "string"
+						? ((entity.config as Record<string, unknown>).version as string)
+						: "");
+				return `${entityId}:${entityVersion}`;
+			})
+			.join("|");
+		const sessionsByItem = (typed.itemSessionsByItemId || {}) as Record<string, unknown>;
+		const itemSessionSignature = Object.keys(sessionsByItem)
+			.sort((left, right) => left.localeCompare(right))
+			.map((itemId) => {
+				const session = sessionsByItem[itemId] as Record<string, unknown> | undefined;
+				const sessionId = (typeof session?.id === "string" && session.id) || "";
+				const dataPayload = Array.isArray(session?.data) ? session.data : [];
+				let payloadSignature = "";
+				try {
+					payloadSignature = hashString(JSON.stringify(dataPayload));
+				} catch {
+					payloadSignature = String(dataPayload.length);
+				}
+				return `${itemId}:${sessionId}:${payloadSignature}`;
+			})
+			.join("|");
+		return `${sectionId}|${currentItemIndex}|${renderableSignature}|${itemSessionSignature}`;
+	}
+
 	function isKnownPlayerType(value: unknown): value is ItemPlayerType {
-		return value === "iife" || value === "esm" || value === "fixed" || value === "custom";
+		return value === "iife" || value === "esm" || value === "preloaded" || value === "custom";
 	}
 
 	function normalizeItemPlayerConfig(
@@ -150,6 +208,26 @@
 		};
 	}
 
+	function normalizeEnv(input: unknown): { mode: string; role: string } {
+		const envValue = ((input || {}) as Record<string, unknown>) || {};
+		const mode =
+			typeof envValue.mode === "string" && envValue.mode.trim()
+				? envValue.mode.trim()
+				: DEFAULT_ENV.mode;
+		const role =
+			typeof envValue.role === "string" && envValue.role.trim()
+				? envValue.role.trim()
+				: DEFAULT_ENV.role;
+		return { mode, role };
+	}
+
+	function resolveSectionViewFromEnv(input: unknown): string {
+		const resolvedEnv = normalizeEnv(input);
+		if (resolvedEnv.mode === "author") return "author";
+		if (resolvedEnv.role === "instructor") return "scorer";
+		return "candidate";
+	}
+
 	async function createDefaultSectionController() {
 		if (createSectionController) {
 			return createSectionController() as any;
@@ -203,6 +281,8 @@
 	const effectiveSectionId = $derived(
 		sectionId || (section as any)?.identifier || `section-${effectiveAssessmentId || "default"}`,
 	);
+	const effectiveEnv = $derived.by(() => normalizeEnv(env));
+	const effectiveSectionView = $derived.by(() => resolveSectionViewFromEnv(effectiveEnv));
 	const effectiveItemPlayer = $derived.by(() =>
 		normalizeItemPlayerConfig(player, playerType),
 	);
@@ -221,10 +301,10 @@
 			itemPlayer: effectiveItemPlayer,
 			reportSessionChanged: (itemId: string, detail: unknown) => {
 				const result = sectionEngine.handleItemSessionChanged(itemId, detail);
-				const normalized = (result as SessionChangedLike | null)?.eventDetail || detail;
-				emit("session-changed", {
-					...(normalized as Record<string, unknown>),
-					sourceRuntimeId: runtimeId,
+				emitNormalizedSessionChanged({
+					itemId,
+					result,
+					fallbackSession: detail,
 				});
 			},
 		};
@@ -239,35 +319,12 @@
 		},
 	);
 
-	function getCompositionSignature(model: unknown): string {
-		const typed = model as any;
-		const itemIds = Array.isArray(typed?.items)
-			? typed.items.map((item: any) => item?.id || "")
-			: [];
-		const passageIds = Array.isArray(typed?.passages)
-			? typed.passages.map((item: any) => item?.id || "")
-			: [];
-		const sessionByItem = typed?.itemSessionsByItemId
-			? Object.entries(typed.itemSessionsByItemId)
-					.sort(([left], [right]) => left.localeCompare(right))
-					.map(([itemId, session]) => [itemId, JSON.stringify(session ?? null)])
-			: [];
-		return JSON.stringify({
-			sectionId: typed?.section?.identifier || typed?.sectionId || "",
-			currentItemIndex: typed?.currentItemIndex ?? -1,
-			itemIds,
-			passageIds,
-			sessionByItem,
-		});
-	}
-
-	function emitCompositionChanged() {
-		const nextModel = sectionEngine.getCompositionModel();
-		const signature = getCompositionSignature(nextModel);
-		if (signature === lastCompositionSignature) {
+	function flushCompositionChanged(nextModel: unknown) {
+		const nextRevisionKey = getCompositionRevisionKey(nextModel);
+		if (nextRevisionKey === lastCompositionRevisionKey) {
 			return;
 		}
-		lastCompositionSignature = signature;
+		lastCompositionRevisionKey = nextRevisionKey;
 		compositionVersion += 1;
 		compositionModel = nextModel;
 		emit("composition-changed", {
@@ -276,6 +333,38 @@
 		});
 	}
 
+	function emitCompositionChanged(nextModel?: unknown) {
+		pendingCompositionModel = nextModel ?? sectionEngine.getCompositionModel();
+		if (pendingCompositionEmit) return;
+		pendingCompositionEmit = true;
+		const flush = () => {
+			pendingCompositionEmit = false;
+			compositionEmitRaf = null;
+			flushCompositionChanged(pendingCompositionModel);
+		};
+		if (typeof window !== "undefined" && typeof window.requestAnimationFrame === "function") {
+			compositionEmitRaf = window.requestAnimationFrame(flush);
+			return;
+		}
+		queueMicrotask(flush);
+	}
+
+	function emitNormalizedSessionChanged(args: {
+		itemId: string;
+		canonicalItemId?: string;
+		result: unknown;
+		fallbackSession: unknown;
+	}) {
+		const normalized =
+			(args.result as SessionChangedLike | null)?.eventDetail || args.fallbackSession;
+		emit("session-changed", {
+			...(normalized as Record<string, unknown>),
+			itemId: args.itemId,
+			canonicalItemId: args.canonicalItemId || args.itemId,
+			sourceRuntimeId: runtimeId,
+		});
+	}
+
 	function isLocalToCurrentRuntime(eventTarget: EventTarget | null): boolean {
 		if (!(eventTarget instanceof HTMLElement)) return false;
 		const sourceRuntime = requestContext(
@@ -339,8 +428,8 @@
 		if (!host) return;
 		host.setAttribute("data-item-player-type", effectiveItemPlayer.type);
 		host.setAttribute("data-item-player-tag", effectiveItemPlayer.tagName);
-		host.setAttribute("data-env-mode", String((env as any)?.mode || ""));
-		host.setAttribute("data-env-role", String((env as any)?.role || ""));
+		host.setAttribute("data-env-mode", String((effectiveEnv as any)?.mode || ""));
+		host.setAttribute("data-env-role", String((effectiveEnv as any)?.role || ""));
 	});
 
 	$effect(() => {
@@ -378,12 +467,11 @@
 				sectionId: effectiveSectionId,
 				assessmentId: effectiveAssessmentId,
 				attemptId: attemptId || undefined,
-				view,
+				view: effectiveSectionView,
 				createDefaultController: createDefaultSectionController,
 				onCompositionChanged: (nextComposition) => {
 					if (cancelled) return;
-					compositionModel = nextComposition;
-					emitCompositionChanged();
+					emitCompositionChanged(nextComposition);
 				},
 			})
 			.then(() => {
@@ -393,6 +481,7 @@
 					assessmentId: effectiveAssessmentId,
 					sectionId: effectiveSectionId,
 					itemPlayer: effectiveItemPlayer,
+					coordinator: effectiveCoordinator,
 				});
 				emit("section-ready", {
 					sectionId: effectiveSectionId,
@@ -438,12 +527,11 @@
 			if (!detail?.itemId) return;
 			if (!shouldHandleBySourceRuntime(detail.sourceRuntimeId, runtimeId)) return;
 			const result = sectionEngine.handleItemSessionChanged(detail.itemId, detail.session);
-			const normalized = (result as SessionChangedLike | null)?.eventDetail || detail.session;
-			emit("session-changed", {
-				...(normalized as Record<string, unknown>),
+			emitNormalizedSessionChanged({
 				itemId: detail.itemId,
-				canonicalItemId: detail.canonicalItemId || detail.itemId,
-				sourceRuntimeId: runtimeId,
+				canonicalItemId: detail.canonicalItemId,
+				result,
+				fallbackSession: detail.session,
 			});
 		};
 
@@ -500,6 +588,11 @@
 
 	$effect(() => {
 		return () => {
+			if (compositionEmitRaf !== null && typeof window !== "undefined") {
+				window.cancelAnimationFrame(compositionEmitRaf);
+				compositionEmitRaf = null;
+			}
+			pendingCompositionEmit = false;
 			void sectionEngine.dispose().catch((error) => {
 				runtimeError = error;
 			});

package/src/components/SectionToolBar.svelte

@@ -0,0 +1,58 @@
+<svelte:options
+	customElement={{
+		tag: "pie-section-toolbar",
+		shadow: "none",
+		props: {
+			enabledTools: { type: "String", attribute: "enabled-tools" },
+			position: { type: "String", attribute: "position" },
+			sectionId: { type: "String", attribute: "section-id" },
+			size: { type: "String", attribute: "size" },
+			language: { type: "String", attribute: "language" },
+			toolRegistry: { type: "Object", reflect: false },
+			pnpResolver: { type: "Object", reflect: false },
+			assessment: { type: "Object", reflect: false },
+			itemRef: { type: "Object", reflect: false },
+			item: { type: "Object", reflect: false },
+			hostButtons: { type: "Object", reflect: false },
+		},
+	}}
+/>
+
+<script lang="ts">
+	import "./item-toolbar-element.js";
+	import type { ToolRegistry } from "../services/ToolRegistry.js";
+	import type { PNPToolResolver } from "../services/PNPToolResolver.js";
+	import type { AssessmentEntity, AssessmentItemRef, ItemEntity } from "@pie-players/pie-players-shared/types";
+	import type { ToolbarItem } from "../services/toolbar-items.js";
+
+	let {
+		enabledTools = "",
+		position = "bottom",
+		sectionId = "",
+		size = "md" as "sm" | "md" | "lg",
+		language = "en-US",
+		toolRegistry = null as ToolRegistry | null,
+		pnpResolver = null as PNPToolResolver | null,
+		assessment = null as AssessmentEntity | null,
+		itemRef = null as AssessmentItemRef | null,
+		item = null as ItemEntity | null,
+		hostButtons = [] as ToolbarItem[],
+	} = $props();
+</script>
+
+<pie-item-toolbar
+	level="section"
+	scope-id={sectionId}
+	section-id={sectionId}
+	tools={enabledTools}
+	content-kind="section"
+	position={position}
+	{size}
+	{language}
+	{toolRegistry}
+	{pnpResolver}
+	{assessment}
+	{itemRef}
+	{item}
+	{hostButtons}
+></pie-item-toolbar>

package/dist/services/tts/provider-interface.d.ts

@@ -1,131 +0,0 @@
-/**
- * TTS Provider Interfaces
- *
- * Defines the contract for text-to-speech providers.
- * Providers are stateless factories that create configured TTS implementations.
- *
- * Part of PIE Assessment Toolkit.
- */
-import type { TTSConfig } from "../TTSService.js";
-/**
- * TTS Provider interface
- *
- * Providers are stateless factories that create TTS implementations.
- * They describe capabilities and create configured instances.
- */
-export interface ITTSProvider {
-    /**
-     * Unique identifier for this provider
-     */
-    readonly providerId: string;
-    /**
-     * Human-readable provider name
-     */
-    readonly providerName: string;
-    /**
-     * Provider version
-     */
-    readonly version: string;
-    /**
-     * Initialize and create a configured TTS implementation
-     */
-    initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
-    /**
-     * Check if a specific feature is supported
-     */
-    supportsFeature(feature: TTSFeature): boolean;
-    /**
-     * Get provider capabilities
-     */
-    getCapabilities(): TTSProviderCapabilities;
-    /**
-     * Clean up provider resources
-     */
-    destroy(): void;
-}
-/**
- * TTS Provider Implementation interface
- *
- * The actual TTS implementation that handles playback.
- * Created by ITTSProvider.initialize()
- */
-export interface ITTSProviderImplementation {
-    /**
-     * Speak text
-     */
-    speak(text: string): Promise<void>;
-    /**
-     * Pause playback
-     */
-    pause(): void;
-    /**
-     * Resume playback
-     */
-    resume(): void;
-    /**
-     * Stop playback
-     */
-    stop(): void;
-    /**
-     * Check if currently playing
-     */
-    isPlaying(): boolean;
-    /**
-     * Check if paused
-     */
-    isPaused(): boolean;
-    /**
-     * Update settings dynamically (optional)
-     * Allows changing rate, pitch, and voice without full reinitialization.
-     * Changes take effect on the next speak() call.
-     */
-    updateSettings?(settings: Partial<TTSConfig>): void | Promise<void>;
-    /**
-     * Word boundary callback (optional)
-     * Called during speech for word highlighting
-     * @param word - The word being spoken (may be empty for server providers)
-     * @param position - Character position in the text
-     * @param length - Optional word length (for server providers with speech marks)
-     */
-    onWordBoundary?: (word: string, position: number, length?: number) => void;
-}
-/**
- * TTS Provider capabilities
- *
- * Describes which features a provider supports
- */
-export interface TTSProviderCapabilities {
-    /**
-     * Supports pause/resume
-     */
-    supportsPause: boolean;
-    /**
-     * Supports resume after pause
-     */
-    supportsResume: boolean;
-    /**
-     * Supports word boundary events for highlighting
-     */
-    supportsWordBoundary: boolean;
-    /**
-     * Supports voice selection
-     */
-    supportsVoiceSelection: boolean;
-    /**
-     * Supports rate control (speed)
-     */
-    supportsRateControl: boolean;
-    /**
-     * Supports pitch control
-     */
-    supportsPitchControl: boolean;
-    /**
-     * Maximum text length (if limited)
-     */
-    maxTextLength?: number;
-}
-/**
- * TTS features for capability checking
- */
-export type TTSFeature = "pause" | "resume" | "wordBoundary" | "voiceSelection" | "rateControl" | "pitchControl";
-//# sourceMappingURL=provider-interface.d.ts.map

package/dist/services/tts/provider-interface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-interface.d.ts","sourceRoot":"","sources":["../../../src/services/tts/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEnE;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IAE9C;;OAEG;IACH,eAAe,IAAI,uBAAuB,CAAC;IAE3C;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC;IAEpB;;;;OAIG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3E;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,sBAAsB,EAAE,OAAO,CAAC;IAEhC;;OAEG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GACnB,OAAO,GACP,QAAQ,GACR,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,cAAc,CAAC"}

package/dist/services/tts/provider-interface.js

@@ -1,10 +0,0 @@
-/**
- * TTS Provider Interfaces
- *
- * Defines the contract for text-to-speech providers.
- * Providers are stateless factories that create configured TTS implementations.
- *
- * Part of PIE Assessment Toolkit.
- */
-export {};
-//# sourceMappingURL=provider-interface.js.map

package/dist/services/tts/provider-interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-interface.js","sourceRoot":"","sources":["../../../src/services/tts/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}