@pie-players/pie-section-player 0.2.13 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-section-player",
-	"version": "0.2.13",
+	"version": "0.3.0",
 	"type": "module",
 	"description": "Web component for rendering QTI 3.0 assessment sections with passages and items",
 	"license": "MIT",
@@ -49,21 +49,22 @@
 		"svelte": "^5.51.0"
 	},
 	"dependencies": {
-		"@pie-players/pie-assessment-toolkit": "0.2.10",
-		"@pie-players/pie-item-player": "0.1.1",
-		"@pie-players/pie-context": "0.1.2",
-		"@pie-players/pie-players-shared": "0.2.6",
-		"@pie-players/pie-toolbars": "0.1.1",
-		"@pie-players/pie-tool-answer-eliminator": "0.2.10",
-		"@pie-players/pie-tool-calculator": "0.1.10",
-		"@pie-players/pie-tool-theme": "0.1.10",
-		"@pie-players/pie-tool-graph": "0.1.10",
-		"@pie-players/pie-tool-line-reader": "0.1.10",
-		"@pie-players/pie-tool-periodic-table": "0.1.10",
-		"@pie-players/pie-tool-protractor": "0.1.10",
-		"@pie-players/pie-tool-ruler": "0.1.10",
-		"@pie-players/pie-tool-text-to-speech": "0.1.10",
-		"@pie-players/tts-client-server": "0.2.5",
+		"@pie-players/pie-assessment-toolkit": "0.3.0",
+		"@pie-players/pie-item-player": "0.3.0",
+		"@pie-players/pie-context": "0.3.0",
+		"@pie-players/pie-players-shared": "0.3.0",
+		"@pie-players/pie-toolbars": "0.3.0",
+		"@pie-players/pie-tool-answer-eliminator": "0.3.0",
+		"@pie-players/pie-tool-annotation-toolbar": "0.3.0",
+		"@pie-players/pie-tool-calculator": "0.3.0",
+		"@pie-players/pie-tool-theme": "0.3.0",
+		"@pie-players/pie-tool-graph": "0.3.0",
+		"@pie-players/pie-tool-line-reader": "0.3.0",
+		"@pie-players/pie-tool-periodic-table": "0.3.0",
+		"@pie-players/pie-tool-protractor": "0.3.0",
+		"@pie-players/pie-tool-ruler": "0.3.0",
+		"@pie-players/pie-tool-text-to-speech": "0.3.0",
+		"@pie-players/tts-client-server": "0.3.0",
 		"daisyui": "^5.5.18"
 	},
 	"devDependencies": {
@@ -83,7 +84,7 @@
 		"url": "https://github.com/pie-framework/pie-players/issues"
 	},
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=20.0.0"
 	},
 	"sideEffects": true
 }

package/src/components/ItemShellElement.svelte

@@ -13,8 +13,16 @@
 	}}
 />
 
+<script module lang="ts">
+	const crossShellSessionDedupe = new Map<
+		string,
+		{ fingerprint: string; timestamp: number }
+	>();
+</script>
+
 <script lang="ts">
 	import {
+		PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT,
 		PIE_ITEM_SESSION_CHANGED_EVENT,
 		PIE_REGISTER_EVENT,
 		PIE_UNREGISTER_EVENT,
@@ -23,11 +31,28 @@
 		dispatchCrossBoundaryEvent,
 		type AssessmentToolkitRegionScopeContext,
 		type AssessmentToolkitShellContext,
+		type InternalItemSessionChangedDetail,
 		type ItemSessionChangedDetail,
 		type RuntimeRegistrationDetail,
 	} from "@pie-players/pie-assessment-toolkit";
+	import { normalizeItemSessionChange } from "@pie-players/pie-players-shared";
 	import { ContextProvider, ContextRoot } from "@pie-players/pie-context";
 
+	const PIE_INTERNAL_CONTENT_LOADED_EVENT = "pie-content-loaded";
+	const PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT = "pie-item-player-error";
+	type InternalContentLoadedDetail = {
+		itemId: string;
+		canonicalItemId?: string;
+		contentKind?: string;
+		detail?: unknown;
+	};
+	type InternalItemPlayerErrorDetail = {
+		itemId: string;
+		canonicalItemId?: string;
+		contentKind?: string;
+		error: unknown;
+	};
+
 	let {
 		itemId = "",
 		canonicalItemId = "",
@@ -100,13 +125,64 @@
 	function normalizeAndDispatchSession(event: Event): void {
 		if (!host || !itemId) return;
 		const detail = (event as CustomEvent).detail;
+		const internalPayload: InternalItemSessionChangedDetail = {
+			itemId,
+			session: detail,
+		};
+		// Internal runtime session wiring must always continue to keep item UI/state synchronized.
+		dispatchCrossBoundaryEvent(host, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, internalPayload);
+		// Keep public item stream response-focused; metadata-only belongs on canonical session-changed.
+		const normalized = normalizeItemSessionChange({
+			itemId,
+			sessionDetail: detail,
+		});
+		if (normalized.intent === "metadata-only" || !normalized.session) {
+			return;
+		}
 		const payload: ItemSessionChangedDetail = {
 			itemId,
 			canonicalItemId: canonicalItemId || itemId,
-			session: detail,
+			session: normalized.session,
 		};
 		dispatchCrossBoundaryEvent(host, PIE_ITEM_SESSION_CHANGED_EVENT, payload);
-		dispatchCrossBoundaryEvent(host, "item-session-changed", payload);
+	}
+
+	function dispatchLoaded(detail: unknown): void {
+		if (!host || !itemId) return;
+		const payload: InternalContentLoadedDetail = {
+			itemId,
+			canonicalItemId: canonicalItemId || itemId,
+			contentKind,
+			detail,
+		};
+		dispatchCrossBoundaryEvent(host, PIE_INTERNAL_CONTENT_LOADED_EVENT, payload);
+	}
+
+	function dispatchPlayerError(error: unknown): void {
+		if (!host || !itemId) return;
+		const payload: InternalItemPlayerErrorDetail = {
+			itemId,
+			canonicalItemId: canonicalItemId || itemId,
+			contentKind,
+			error,
+		};
+		dispatchCrossBoundaryEvent(host, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, payload);
+	}
+
+	function createSessionEventFingerprint(detail: unknown): string {
+		const semanticDetail =
+			detail && typeof detail === "object"
+				? { ...(detail as Record<string, unknown>) }
+				: detail;
+		if (semanticDetail && typeof semanticDetail === "object") {
+			delete (semanticDetail as Record<string, unknown>).timestamp;
+			delete (semanticDetail as Record<string, unknown>).sourceRuntimeId;
+		}
+		try {
+			return JSON.stringify(semanticDetail);
+		} catch {
+			return String(semanticDetail);
+		}
 	}
 
 	$effect(() => {
@@ -114,19 +190,50 @@
 		dispatchRegistration(PIE_REGISTER_EVENT);
 
 		const seenSessionEvents = new WeakSet<Event>();
+		let lastForwardedFingerprint = "";
+		const CROSS_SHELL_DEDUPE_WINDOW_MS = 500;
 		const onSessionChanged = (event: Event) => {
+			// Keep framework surface minimal: normalize these descendant events and do not
+			// leak raw item-player session events to external listeners.
+			event.stopPropagation();
 			// Some players emit `session-changed`, others emit `sessionchanged`.
-			// Guard against duplicate forwarding when both fire for the same original event.
+			// Guard against duplicate forwarding when both fire for the same payload.
 			if (seenSessionEvents.has(event)) return;
 			seenSessionEvents.add(event);
+			const fingerprint = createSessionEventFingerprint((event as CustomEvent).detail);
+			if (fingerprint === lastForwardedFingerprint) return;
+			const dedupeKey = itemId || canonicalItemId || "__unknown-item__";
+			const now = Date.now();
+			const lastCrossShell = crossShellSessionDedupe.get(dedupeKey);
+			if (
+				lastCrossShell &&
+				lastCrossShell.fingerprint === fingerprint &&
+				now - lastCrossShell.timestamp < CROSS_SHELL_DEDUPE_WINDOW_MS
+			) {
+				return;
+			}
+			crossShellSessionDedupe.set(dedupeKey, { fingerprint, timestamp: now });
+			lastForwardedFingerprint = fingerprint;
 			normalizeAndDispatchSession(event);
 		};
 		host.addEventListener("sessionchanged", onSessionChanged);
 		host.addEventListener("session-changed", onSessionChanged);
+		const onLoadComplete = (event: Event) => {
+			event.stopPropagation();
+			dispatchLoaded((event as CustomEvent).detail);
+		};
+		const onPlayerError = (event: Event) => {
+			event.stopPropagation();
+			dispatchPlayerError((event as CustomEvent).detail);
+		};
+		host.addEventListener("load-complete", onLoadComplete);
+		host.addEventListener("player-error", onPlayerError);
 
 		return () => {
 			host?.removeEventListener("sessionchanged", onSessionChanged);
 			host?.removeEventListener("session-changed", onSessionChanged);
+			host?.removeEventListener("load-complete", onLoadComplete);
+			host?.removeEventListener("player-error", onPlayerError);
 			dispatchRegistration(PIE_UNREGISTER_EVENT);
 		};
 	});

package/src/components/PassageShellElement.svelte

@@ -26,6 +26,21 @@
 	} from "@pie-players/pie-assessment-toolkit";
 	import { ContextProvider, ContextRoot } from "@pie-players/pie-context";
 
+	const PIE_INTERNAL_CONTENT_LOADED_EVENT = "pie-content-loaded";
+	const PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT = "pie-item-player-error";
+	type InternalContentLoadedDetail = {
+		itemId: string;
+		canonicalItemId?: string;
+		contentKind?: string;
+		detail?: unknown;
+	};
+	type InternalItemPlayerErrorDetail = {
+		itemId: string;
+		canonicalItemId?: string;
+		contentKind?: string;
+		error: unknown;
+	};
+
 	let {
 		itemId = "",
 		canonicalItemId = "",
@@ -95,11 +110,45 @@
 		dispatchCrossBoundaryEvent(host, eventName, detail);
 	}
 
+	function dispatchLoaded(detail: unknown): void {
+		if (!host || !itemId) return;
+		const payload: InternalContentLoadedDetail = {
+			itemId,
+			canonicalItemId: canonicalItemId || itemId,
+			contentKind,
+			detail,
+		};
+		dispatchCrossBoundaryEvent(host, PIE_INTERNAL_CONTENT_LOADED_EVENT, payload);
+	}
+
+	function dispatchPlayerError(error: unknown): void {
+		if (!host || !itemId) return;
+		const payload: InternalItemPlayerErrorDetail = {
+			itemId,
+			canonicalItemId: canonicalItemId || itemId,
+			contentKind,
+			error,
+		};
+		dispatchCrossBoundaryEvent(host, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, payload);
+	}
+
 	$effect(() => {
 		if (!host) return;
 		dispatchRegistration(PIE_REGISTER_EVENT);
+		const onLoadComplete = (event: Event) => {
+			event.stopPropagation();
+			dispatchLoaded((event as CustomEvent).detail);
+		};
+		const onPlayerError = (event: Event) => {
+			event.stopPropagation();
+			dispatchPlayerError((event as CustomEvent).detail);
+		};
+		host.addEventListener("load-complete", onLoadComplete);
+		host.addEventListener("player-error", onPlayerError);
 
 		return () => {
+			host?.removeEventListener("load-complete", onLoadComplete);
+			host?.removeEventListener("player-error", onPlayerError);
 			dispatchRegistration(PIE_UNREGISTER_EVENT);
 		};
 	});

package/src/components/PieSectionPlayerBaseElement.svelte

@@ -23,9 +23,14 @@
 
 <script lang="ts">
 	import "@pie-players/pie-assessment-toolkit/components/pie-assessment-toolkit-element";
+	import "@pie-players/pie-tool-annotation-toolbar";
 	import {
 		createDefaultPersonalNeedsProfile,
 	} from "@pie-players/pie-assessment-toolkit";
+	import {
+		normalizeToolsConfig,
+		resolveToolsForLevel,
+	} from "@pie-players/pie-assessment-toolkit";
 	import { createEventDispatcher } from "svelte";
 	import { SectionController } from "../controllers/SectionController.js";
 	import type { SectionCompositionModel } from "../controllers/types.js";
@@ -57,6 +62,7 @@
 	} = $props();
 
 	let toolkitElement = $state<any>(null);
+	let activeToolkitCoordinator = $state<any>(null);
 	let lastCompositionVersion = $state(-1);
 	type BaseSectionPlayerEvents = {
 		"composition-changed": { composition: SectionCompositionModel };
@@ -124,9 +130,40 @@
 		eventName: Exclude<keyof BaseSectionPlayerEvents, "composition-changed">,
 	): void {
 		const detail = (event as CustomEvent).detail as Record<string, unknown>;
+		if (eventName === "toolkit-ready" && detail?.coordinator) {
+			activeToolkitCoordinator = detail.coordinator;
+		}
 		emit(eventName, detail || ({} as Record<string, unknown>));
 	}
 
+	const normalizedToolsConfig = $derived.by(() =>
+		normalizeToolsConfig((effectiveTools || {}) as any),
+	);
+	const annotationToolbarPlacementEnabled = $derived.by(() => {
+		const levels: Array<"section" | "item" | "passage"> = [
+			"section",
+			"item",
+			"passage",
+		];
+		return levels.some((level) =>
+			resolveToolsForLevel(normalizedToolsConfig as any, level).includes(
+				"annotationToolbar",
+			),
+		);
+	});
+	const annotationToolbarProviderEnabled = $derived.by(() =>
+		activeToolkitCoordinator?.isToolEnabled?.("annotationToolbar") ??
+		((normalizedToolsConfig as any)?.providers?.annotationToolbar?.enabled !==
+			false),
+	);
+	const shouldRenderAnnotationToolbar = $derived(
+		Boolean(
+			activeToolkitCoordinator &&
+				annotationToolbarPlacementEnabled &&
+				annotationToolbarProviderEnabled,
+		),
+	);
+
 	$effect(() => {
 		if (!toolkitElement) return;
 		toolkitElement.createSectionController =
@@ -157,6 +194,13 @@
 	onruntime-owned={(event: Event) => handleToolkitEvent(event, "runtime-owned")}
 	onruntime-inherited={(event: Event) => handleToolkitEvent(event, "runtime-inherited")}
 >
+	{#if shouldRenderAnnotationToolbar}
+		<pie-tool-annotation-toolbar
+			enabled={true}
+			ttsService={activeToolkitCoordinator.ttsService}
+			highlightCoordinator={activeToolkitCoordinator.highlightCoordinator}
+		></pie-tool-annotation-toolbar>
+	{/if}
 	<slot></slot>
 </pie-assessment-toolkit>
 

package/src/components/PieSectionPlayerSplitPaneElement.svelte

@@ -19,7 +19,7 @@
 			isolation: { attribute: "isolation", type: "String" },
 			env: { type: "Object", reflect: false },
 			iifeBundleHost: { attribute: "iife-bundle-host", type: "String" },
-			showToolbar: { attribute: "show-toolbar", type: "Boolean" },
+			showToolbar: { attribute: "show-toolbar", type: "String" },
 			toolbarPosition: { attribute: "toolbar-position", type: "String" },
 			enabledTools: { attribute: "enabled-tools", type: "String" },
 			itemToolbarTools: { attribute: "item-toolbar-tools", type: "String" },
@@ -29,6 +29,7 @@
 />
 
 <script lang="ts">
+	import { onMount } from "svelte";
 	import "./section-player-base-element.js";
 	import * as SectionItemCardModule from "./shared/SectionItemCard.svelte";
 	import * as SectionPassageCardModule from "./shared/SectionPassageCard.svelte";
@@ -91,13 +92,36 @@
 		isolation,
 		env,
 		iifeBundleHost,
-		showToolbar = true,
+		showToolbar = "true" as boolean | string | null | undefined,
 		toolbarPosition = "right",
 		enabledTools = "",
 		itemToolbarTools = "",
 		passageToolbarTools = "",
 	} = $props();
 
+	function resolveToolbarVisibility(value: boolean | string | null | undefined): boolean {
+		if (typeof value === "boolean") {
+			return value;
+		}
+		if (value === null || value === undefined) {
+			return true;
+		}
+		const normalizedValue = String(value).trim().toLowerCase();
+		if (normalizedValue === "") {
+			return true;
+		}
+		if (["false", "0", "off", "no"].includes(normalizedValue)) {
+			return false;
+		}
+		if (["true", "1", "on", "yes"].includes(normalizedValue)) {
+			return true;
+		}
+		return Boolean(normalizedValue);
+	}
+
+	const MANAGED_OUTER_SCROLL_CLASS = "pie-outer-scrollbars-managed";
+	const ACTIVE_OUTER_SCROLL_CLASS = "pie-outer-scrolling";
+
 	let compositionModel = $state<SectionCompositionModel>(EMPTY_COMPOSITION);
 	let leftPanelWidth = $state(50);
 	let isDragging = $state(false);
@@ -109,7 +133,9 @@
 	const passages = $derived(compositionModel.passages || []);
 	const items = $derived(compositionModel.items || []);
 	const hasPassages = $derived(passages.length > 0);
-	const shouldRenderToolbar = $derived(showToolbar && toolbarPosition !== "none");
+	const shouldRenderToolbar = $derived(
+		resolveToolbarVisibility(showToolbar) && toolbarPosition !== "none",
+	);
 	const toolbarBeforeContent = $derived(
 		toolbarPosition === "top" || toolbarPosition === "left",
 	);
@@ -237,6 +263,39 @@
 		});
 	});
 
+	onMount(() => {
+		let scrollTimeout: ReturnType<typeof setTimeout> | null = null;
+		const html = document.documentElement;
+		const body = document.body;
+
+		html.classList.add(MANAGED_OUTER_SCROLL_CLASS);
+		body.classList.add(MANAGED_OUTER_SCROLL_CLASS);
+
+		const showOuterScrollbars = () => {
+			html.classList.add(ACTIVE_OUTER_SCROLL_CLASS);
+			body.classList.add(ACTIVE_OUTER_SCROLL_CLASS);
+			if (scrollTimeout) {
+				clearTimeout(scrollTimeout);
+			}
+			scrollTimeout = setTimeout(() => {
+				html.classList.remove(ACTIVE_OUTER_SCROLL_CLASS);
+				body.classList.remove(ACTIVE_OUTER_SCROLL_CLASS);
+			}, 900);
+		};
+
+		window.addEventListener("scroll", showOuterScrollbars, { passive: true });
+		return () => {
+			window.removeEventListener("scroll", showOuterScrollbars);
+			html.classList.remove(ACTIVE_OUTER_SCROLL_CLASS);
+			body.classList.remove(ACTIVE_OUTER_SCROLL_CLASS);
+			html.classList.remove(MANAGED_OUTER_SCROLL_CLASS);
+			body.classList.remove(MANAGED_OUTER_SCROLL_CLASS);
+			if (scrollTimeout) {
+				clearTimeout(scrollTimeout);
+			}
+		};
+	});
+
 </script>
 
 <pie-section-player-base
@@ -258,7 +317,7 @@
 		{/if}
 
 		<div
-			class={`pie-section-player-layout-body ${toolbarInline ? "pie-section-player-layout-body--inline" : ""}`}
+			class={`pie-section-player-layout-body ${shouldRenderToolbar && toolbarInline ? "pie-section-player-layout-body--inline" : ""}`}
 		>
 			<div
 				class={`pie-section-player-split-content ${!hasPassages ? "pie-section-player-split-content--no-passages" : ""}`}
@@ -555,6 +614,47 @@
 		padding: 1rem;
 	}
 
+	:global(html.pie-outer-scrollbars-managed),
+	:global(body.pie-outer-scrollbars-managed) {
+		scrollbar-width: auto;
+		scrollbar-color: transparent transparent;
+	}
+
+	:global(html.pie-outer-scrollbars-managed.pie-outer-scrolling),
+	:global(body.pie-outer-scrollbars-managed.pie-outer-scrolling) {
+		scrollbar-color: #c1c1c1 #f1f1f1;
+	}
+
+	:global(html.pie-outer-scrollbars-managed::-webkit-scrollbar),
+	:global(body.pie-outer-scrollbars-managed::-webkit-scrollbar) {
+		width: 0;
+		height: 0;
+		background: transparent;
+	}
+
+	:global(html.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar),
+	:global(body.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar) {
+		width: 8px;
+		height: 8px;
+	}
+
+	:global(html.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar-track),
+	:global(body.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar-track) {
+		background: #f1f1f1;
+		border-radius: 4px;
+	}
+
+	:global(html.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar-thumb),
+	:global(body.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar-thumb) {
+		background: #c1c1c1;
+		border-radius: 4px;
+	}
+
+	:global(html.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar-thumb:hover),
+	:global(body.pie-outer-scrollbars-managed.pie-outer-scrolling::-webkit-scrollbar-thumb:hover) {
+		background: #a1a1a1;
+	}
+
 	@media (max-width: 1100px) {
 		.pie-section-player-shell--left,
 		.pie-section-player-shell--right {

package/src/components/PieSectionPlayerVerticalElement.svelte

@@ -19,7 +19,7 @@
 			isolation: { attribute: "isolation", type: "String" },
 			env: { type: "Object", reflect: false },
 			iifeBundleHost: { attribute: "iife-bundle-host", type: "String" },
-			showToolbar: { attribute: "show-toolbar", type: "Boolean" },
+			showToolbar: { attribute: "show-toolbar", type: "String" },
 			toolbarPosition: { attribute: "toolbar-position", type: "String" },
 			enabledTools: { attribute: "enabled-tools", type: "String" },
 			itemToolbarTools: { attribute: "item-toolbar-tools", type: "String" },
@@ -89,13 +89,33 @@
 		isolation,
 		env,
 		iifeBundleHost,
-		showToolbar = true,
+		showToolbar = "true" as boolean | string | null | undefined,
 		toolbarPosition = "right",
 		enabledTools = "",
 		itemToolbarTools = "",
 		passageToolbarTools = "",
 	} = $props();
 
+	function resolveToolbarVisibility(value: boolean | string | null | undefined): boolean {
+		if (typeof value === "boolean") {
+			return value;
+		}
+		if (value === null || value === undefined) {
+			return true;
+		}
+		const normalizedValue = String(value).trim().toLowerCase();
+		if (normalizedValue === "") {
+			return true;
+		}
+		if (["false", "0", "off", "no"].includes(normalizedValue)) {
+			return false;
+		}
+		if (["true", "1", "on", "yes"].includes(normalizedValue)) {
+			return true;
+		}
+		return Boolean(normalizedValue);
+	}
+
 	let compositionModel = $state<SectionCompositionModel>(EMPTY_COMPOSITION);
 	let elementsLoaded = $state(false);
 	let lastPreloadSignature = $state("");
@@ -103,7 +123,9 @@
 
 	const passages = $derived(compositionModel.passages || []);
 	const items = $derived(compositionModel.items || []);
-	const shouldRenderToolbar = $derived(showToolbar && toolbarPosition !== "none");
+	const shouldRenderToolbar = $derived(
+		resolveToolbarVisibility(showToolbar) && toolbarPosition !== "none",
+	);
 	const toolbarBeforeContent = $derived(
 		toolbarPosition === "top" || toolbarPosition === "left",
 	);
@@ -205,7 +227,7 @@
 		{/if}
 
 		<div
-			class={`pie-section-player-layout-body ${toolbarInline ? "pie-section-player-layout-body--inline" : ""}`}
+			class={`pie-section-player-layout-body ${shouldRenderToolbar && toolbarInline ? "pie-section-player-layout-body--inline" : ""}`}
 		>
 			<div class="pie-section-player-vertical-content">
 				{#if !elementsLoaded}