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

package/src/components/PieAssessmentToolkit.svelte

@@ -0,0 +1,517 @@
+<svelte:options
+	customElement={{
+		tag: "pie-assessment-toolkit",
+		shadow: "open",
+		props: {
+			assessmentId: { attribute: "assessment-id", type: "String" },
+			section: { attribute: "section", type: "Object" },
+			sectionId: { attribute: "section-id", type: "String" },
+			attemptId: { attribute: "attempt-id", type: "String" },
+			view: { attribute: "view", type: "String" },
+			env: { attribute: "env", type: "Object" },
+			lazyInit: { attribute: "lazy-init", type: "Boolean" },
+			tools: { attribute: "tools", type: "Object" },
+			accessibility: { attribute: "accessibility", type: "Object" },
+			player: { attribute: "player", type: "Object" },
+			playerType: { attribute: "player-type", type: "String" },
+			coordinator: { type: "Object", reflect: false },
+			createSectionController: { type: "Object", reflect: false },
+			isolation: { attribute: "isolation", type: "String" },
+		},
+	}}
+/>
+
+<script lang="ts">
+	import {
+		ContextProvider,
+		ContextRoot,
+		requestContext,
+	} from "@pie-players/pie-context";
+	import {
+		assessmentToolkitHostRuntimeContext,
+		assessmentToolkitRuntimeContext,
+		type AssessmentToolkitHostRuntimeContext,
+		type AssessmentToolkitRuntimeContext,
+		type ItemPlayerConfig,
+		type ItemPlayerType,
+	} from "../context/assessment-toolkit-context.js";
+	import { connectAssessmentToolkitHostRuntimeContext } from "../context/runtime-context-consumer.js";
+	import { ToolkitCoordinator } from "../services/ToolkitCoordinator.js";
+	import {
+		PIE_ITEM_SESSION_CHANGED_EVENT,
+		PIE_REGISTER_EVENT,
+		PIE_UNREGISTER_EVENT,
+		type ItemSessionChangedDetail,
+		type RuntimeRegistrationDetail,
+	} from "../runtime/registration-events.js";
+	import { dispatchCrossBoundaryEvent } from "../runtime/tool-host-contract.js";
+	import { SectionRuntimeEngine } from "../runtime/SectionRuntimeEngine.js";
+	import {
+		createRuntimeId,
+		shouldHandleBySourceRuntime,
+	} from "../runtime/runtime-event-guards.js";
+
+	type SessionChangedLike = {
+		eventDetail?: unknown;
+	};
+
+	type HostItemPlayerInput = Partial<
+		Pick<ItemPlayerConfig, "type" | "tagName" | "version" | "source">
+	> | null;
+
+	const runtimeId = createRuntimeId("toolkit");
+	const sectionEngine = new SectionRuntimeEngine();
+	const DEFAULT_ITEM_PLAYER_BY_TYPE: Record<ItemPlayerType, string> = {
+		iife: "pie-iife-player",
+		esm: "pie-esm-player",
+		fixed: "pie-fixed-player",
+		custom: "",
+	};
+
+	let {
+		assessmentId = "",
+		section = null,
+		sectionId = "",
+		attemptId = "",
+		view = "candidate",
+		env = {},
+		lazyInit = true,
+		tools = {},
+		accessibility = {},
+		player = null as HostItemPlayerInput,
+		playerType = "" as ItemPlayerType | "",
+		coordinator = null as ToolkitCoordinator | null,
+		createSectionController = null as null | (() => unknown),
+		isolation = "inherit",
+	} = $props();
+
+	let anchor = $state<HTMLDivElement | null>(null);
+	let ownedCoordinator = $state<ToolkitCoordinator | null>(null);
+	let inheritedRuntime = $state<AssessmentToolkitHostRuntimeContext | null>(null);
+	let lastOwnership = $state<"owned" | "inherited" | null>(null);
+	let provider: ContextProvider<typeof assessmentToolkitRuntimeContext> | null = null;
+	let contextRoot: ContextRoot | null = null;
+	let hostRuntimeProvider: ContextProvider<
+		typeof assessmentToolkitHostRuntimeContext
+	> | null = null;
+	let hostRuntimeRoot: ContextRoot | null = null;
+	let compositionVersion = $state(0);
+	let compositionModel = $state<unknown>(null);
+	let runtimeError = $state<unknown>(null);
+	let lastCompositionSignature = $state<string>("");
+
+	function getHostElement(): HTMLElement | null {
+		if (!anchor) return null;
+		const rootNode = anchor.getRootNode();
+		if (rootNode && "host" in rootNode) {
+			return (rootNode as ShadowRoot).host as HTMLElement;
+		}
+		return anchor.parentElement as HTMLElement | null;
+	}
+	const host = $derived.by(() => getHostElement());
+
+	function emit(name: string, detail: unknown): void {
+		if (!host) return;
+		dispatchCrossBoundaryEvent(host, name, detail);
+	}
+
+	function isKnownPlayerType(value: unknown): value is ItemPlayerType {
+		return value === "iife" || value === "esm" || value === "fixed" || value === "custom";
+	}
+
+	function normalizeItemPlayerConfig(
+		hostPlayer: HostItemPlayerInput,
+		hostPlayerType: ItemPlayerType | "",
+	): ItemPlayerConfig {
+		const typeFromConfig = hostPlayer?.type;
+		const rawType = isKnownPlayerType(typeFromConfig)
+			? typeFromConfig
+			: isKnownPlayerType(hostPlayerType)
+				? hostPlayerType
+				: hostPlayer?.tagName
+					? "custom"
+					: "iife";
+		const requestedTagName = hostPlayer?.tagName?.trim();
+		if (rawType === "custom" && !requestedTagName) {
+			return {
+				type: "iife",
+				tagName: DEFAULT_ITEM_PLAYER_BY_TYPE.iife,
+				version: undefined,
+				source: undefined,
+				isDefault: true,
+			};
+		}
+		return {
+			type: rawType,
+			tagName: requestedTagName || DEFAULT_ITEM_PLAYER_BY_TYPE[rawType],
+			version: hostPlayer?.version,
+			source: hostPlayer?.source,
+			isDefault: !hostPlayer && !hostPlayerType,
+		};
+	}
+
+	async function createDefaultSectionController() {
+		if (createSectionController) {
+			return createSectionController() as any;
+		}
+		throw new Error(
+			"pie-assessment-toolkit requires createSectionController when no coordinator hook provides one",
+		);
+	}
+
+	function buildOwnedCoordinator(): ToolkitCoordinator {
+		const fallbackAssessmentId =
+			assessmentId ||
+			(section as any)?.identifier ||
+			`assessment-${Math.random().toString(16).slice(2)}`;
+		return new ToolkitCoordinator({
+			assessmentId: fallbackAssessmentId,
+			lazyInit,
+			tools: tools as any,
+			accessibility: accessibility as any,
+		});
+	}
+
+	const effectiveCoordinator = $derived.by(() => {
+		if (isolation !== "force" && inheritedRuntime?.coordinator) {
+			return inheritedRuntime.coordinator as ToolkitCoordinator;
+		}
+		return coordinator || ownedCoordinator;
+	});
+
+	$effect(() => {
+		if (coordinator) {
+			if (ownedCoordinator) {
+				ownedCoordinator = null;
+			}
+			return;
+		}
+		if (isolation !== "force" && inheritedRuntime?.coordinator) {
+			if (ownedCoordinator) {
+				ownedCoordinator = null;
+			}
+			return;
+		}
+		if (!ownedCoordinator) {
+			ownedCoordinator = buildOwnedCoordinator();
+		}
+	});
+
+	const effectiveAssessmentId = $derived(
+		assessmentId || effectiveCoordinator?.assessmentId || "",
+	);
+	const effectiveSectionId = $derived(
+		sectionId || (section as any)?.identifier || `section-${effectiveAssessmentId || "default"}`,
+	);
+	const effectiveItemPlayer = $derived.by(() =>
+		normalizeItemPlayerConfig(player, playerType),
+	);
+	const runtimeContextValue = $derived.by((): AssessmentToolkitRuntimeContext | null => {
+		if (!effectiveCoordinator) return null;
+		const services = effectiveCoordinator.getServiceBundle();
+		return {
+			toolkitCoordinator: effectiveCoordinator,
+			toolCoordinator: effectiveCoordinator.toolCoordinator,
+			ttsService: services.ttsService,
+			highlightCoordinator: services.highlightCoordinator,
+			catalogResolver: services.catalogResolver,
+			elementToolStateStore: services.elementToolStateStore,
+			assessmentId: effectiveAssessmentId,
+			sectionId: effectiveSectionId,
+			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,
+				});
+			},
+		};
+	});
+	const hostRuntimeContextValue = $derived.by(
+		(): AssessmentToolkitHostRuntimeContext | null => {
+			if (!effectiveCoordinator) return null;
+			return {
+				runtimeId,
+				coordinator: effectiveCoordinator,
+			};
+		},
+	);
+
+	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) {
+			return;
+		}
+		lastCompositionSignature = signature;
+		compositionVersion += 1;
+		compositionModel = nextModel;
+		emit("composition-changed", {
+			composition: compositionModel,
+			version: compositionVersion,
+		});
+	}
+
+	function isLocalToCurrentRuntime(eventTarget: EventTarget | null): boolean {
+		if (!(eventTarget instanceof HTMLElement)) return false;
+		const sourceRuntime = requestContext(
+			eventTarget,
+			assessmentToolkitHostRuntimeContext,
+		);
+		return sourceRuntime?.runtimeId === runtimeId;
+	}
+
+	$effect(() => {
+		if (!host) return;
+		if (isolation === "force") {
+			inheritedRuntime = null;
+			return;
+		}
+		return connectAssessmentToolkitHostRuntimeContext(host, (value) => {
+			if (value.runtimeId === runtimeId) {
+				return;
+			}
+			inheritedRuntime = value;
+		});
+	});
+
+	$effect(() => {
+		const parentRuntimeId =
+			isolation !== "force" && inheritedRuntime ? inheritedRuntime.runtimeId : null;
+		const ownership: "owned" | "inherited" = parentRuntimeId ? "inherited" : "owned";
+		if (ownership !== lastOwnership) {
+			lastOwnership = ownership;
+			emit(ownership === "inherited" ? "runtime-inherited" : "runtime-owned", {
+				runtimeId,
+				parentRuntimeId,
+			});
+		}
+	});
+
+	$effect(() => {
+		if (!host || !hostRuntimeContextValue) return;
+		hostRuntimeProvider = new ContextProvider(host, {
+			context: assessmentToolkitHostRuntimeContext,
+			initialValue: hostRuntimeContextValue,
+		});
+		hostRuntimeProvider.connect();
+		hostRuntimeRoot = new ContextRoot(host);
+		hostRuntimeRoot.attach();
+
+		return () => {
+			hostRuntimeRoot?.detach();
+			hostRuntimeRoot = null;
+			hostRuntimeProvider?.disconnect();
+			hostRuntimeProvider = null;
+		};
+	});
+
+	$effect(() => {
+		if (!hostRuntimeContextValue) return;
+		hostRuntimeProvider?.setValue(hostRuntimeContextValue);
+	});
+
+	$effect(() => {
+		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 || ""));
+	});
+
+	$effect(() => {
+		if (!host || !runtimeContextValue) return;
+		provider = new ContextProvider(host, {
+			context: assessmentToolkitRuntimeContext,
+			initialValue: runtimeContextValue,
+		});
+		provider.connect();
+		contextRoot = new ContextRoot(host);
+		contextRoot.attach();
+
+		return () => {
+			contextRoot?.detach();
+			contextRoot = null;
+			provider?.disconnect();
+			provider = null;
+		};
+	});
+
+	$effect(() => {
+		if (runtimeContextValue) {
+			provider?.setValue(runtimeContextValue);
+		}
+	});
+
+	$effect(() => {
+		if (!section || !effectiveCoordinator) return;
+		let cancelled = false;
+
+		void sectionEngine
+			.initialize({
+				coordinator: effectiveCoordinator,
+				section,
+				sectionId: effectiveSectionId,
+				assessmentId: effectiveAssessmentId,
+				attemptId: attemptId || undefined,
+				view,
+				createDefaultController: createDefaultSectionController,
+				onCompositionChanged: (nextComposition) => {
+					if (cancelled) return;
+					compositionModel = nextComposition;
+					emitCompositionChanged();
+				},
+			})
+			.then(() => {
+				if (cancelled) return;
+				emit("toolkit-ready", {
+					runtimeId,
+					assessmentId: effectiveAssessmentId,
+					sectionId: effectiveSectionId,
+					itemPlayer: effectiveItemPlayer,
+				});
+				emit("section-ready", {
+					sectionId: effectiveSectionId,
+				});
+			})
+			.catch((error) => {
+				runtimeError = error;
+				emit("runtime-error", {
+					runtimeId,
+					error,
+				});
+			});
+
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	$effect(() => {
+		if (!host) return;
+		const localHost = host;
+
+		const onRegister = (event: Event) => {
+			if (!isLocalToCurrentRuntime(event.target)) return;
+			const detail = (event as CustomEvent<RuntimeRegistrationDetail>).detail;
+			if (!detail?.element || !detail?.itemId) return;
+			const changed = sectionEngine.register(detail);
+			if (changed) emitCompositionChanged();
+		};
+
+		const onUnregister = (event: Event) => {
+			if (!isLocalToCurrentRuntime(event.target)) return;
+			const detail = (event as CustomEvent<RuntimeRegistrationDetail>).detail;
+			const changed = detail?.element
+				? sectionEngine.unregister(detail.element)
+				: false;
+			if (changed) emitCompositionChanged();
+		};
+
+		const onItemSessionChanged = (event: Event) => {
+			if (!isLocalToCurrentRuntime(event.target)) return;
+			const detail = (event as CustomEvent<ItemSessionChangedDetail>).detail;
+			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>),
+				itemId: detail.itemId,
+				canonicalItemId: detail.canonicalItemId || detail.itemId,
+				sourceRuntimeId: runtimeId,
+			});
+		};
+
+		localHost.addEventListener(PIE_REGISTER_EVENT, onRegister);
+		localHost.addEventListener(PIE_UNREGISTER_EVENT, onUnregister);
+		localHost.addEventListener(PIE_ITEM_SESSION_CHANGED_EVENT, onItemSessionChanged);
+		return () => {
+			localHost.removeEventListener(PIE_REGISTER_EVENT, onRegister);
+			localHost.removeEventListener(PIE_UNREGISTER_EVENT, onUnregister);
+			localHost.removeEventListener(PIE_ITEM_SESSION_CHANGED_EVENT, onItemSessionChanged);
+		};
+	});
+
+	export async function waitUntilReady(): Promise<void> {
+		if (!effectiveCoordinator) {
+			throw new Error("Coordinator not initialized");
+		}
+		await effectiveCoordinator.waitUntilReady();
+	}
+
+	export function getServiceBundle() {
+		if (!effectiveCoordinator) {
+			throw new Error("Coordinator not initialized");
+		}
+		return effectiveCoordinator.getServiceBundle();
+	}
+
+	export function setHooks(hooks: Record<string, unknown>): void {
+		if (!effectiveCoordinator) {
+			throw new Error("Coordinator not initialized");
+		}
+		effectiveCoordinator.setHooks(hooks as any);
+	}
+
+	export function navigateToItem(index: number): unknown {
+		return sectionEngine.navigateToItem(index);
+	}
+
+	export function getCompositionModel(): unknown {
+		return sectionEngine.getCompositionModel();
+	}
+
+	export function getItemPlayerConfig(): ItemPlayerConfig {
+		return effectiveItemPlayer;
+	}
+
+	export async function persist(): Promise<void> {
+		await sectionEngine.persist();
+	}
+
+	export async function hydrate(): Promise<void> {
+		await sectionEngine.hydrate();
+	}
+
+	$effect(() => {
+		return () => {
+			void sectionEngine.dispose().catch((error) => {
+				runtimeError = error;
+			});
+		};
+	});
+</script>
+
+<div bind:this={anchor} class="pie-assessment-toolkit-anchor" aria-hidden="true"></div>
+<slot></slot>
+
+<style>
+	.pie-assessment-toolkit-anchor {
+		display: none;
+	}
+</style>

package/src/components/ToolButton.svelte

@@ -3,17 +3,17 @@
 	 * ToolButton
 	 *
 	 * Generic button component for rendering tool buttons in toolbars.
-	 * Uses ToolButtonDefinition from ToolRegistry for consistent tool button rendering.
+	 * Uses ToolToolbarButtonDefinition from ToolRegistry for consistent rendering.
 	 */
 
-	import type { ToolButtonDefinition } from "../services/ToolRegistry";
+	import type { ToolToolbarButtonDefinition } from "../services/ToolRegistry.js";
 
 	// Props
 	let {
 		button,
 		class: className = "",
 	}: {
-		button: ToolButtonDefinition;
+		button: ToolToolbarButtonDefinition;
 		class?: string;
 	} = $props();
 
@@ -69,10 +69,10 @@
 		align-items: center;
 		gap: 0.5rem;
 		padding: 0.5rem 1rem;
-		background: var(--tool-button-bg, #ffffff);
-		border: 1px solid var(--tool-button-border, #d1d5db);
+		background: var(--pie-button-bg, #ffffff);
+		border: 1px solid var(--pie-button-border, #d1d5db);
 		border-radius: 0.375rem;
-		color: var(--tool-button-color, #374151);
+		color: var(--pie-button-color, #374151);
 		font-size: 0.875rem;
 		font-weight: 500;
 		cursor: pointer;
@@ -81,18 +81,18 @@
 	}
 
 	.tool-button:hover:not(:disabled) {
-		background: var(--tool-button-hover-bg, #f9fafb);
-		border-color: var(--tool-button-hover-border, #9ca3af);
-		color: var(--tool-button-hover-color, #111827);
+		background: var(--pie-button-hover-bg, #f9fafb);
+		border-color: var(--pie-button-hover-border, #9ca3af);
+		color: var(--pie-button-hover-color, #111827);
 	}
 
 	.tool-button:active:not(:disabled) {
-		background: var(--tool-button-active-bg, #f3f4f6);
+		background: var(--pie-button-active-bg, #f3f4f6);
 		transform: translateY(1px);
 	}
 
 	.tool-button:focus-visible {
-		outline: 2px solid var(--tool-button-focus-outline, #3b82f6);
+		outline: 2px solid var(--pie-button-focus-outline, #3b82f6);
 		outline-offset: 2px;
 	}
 

package/src/components/ToolButtonGroup.svelte

@@ -8,8 +8,12 @@
 	 * - Pass 2: Filters by tool relevance using ToolRegistry
 	 */
 
-	import type { ToolRegistry } from "../services/ToolRegistry";
-	import type { ToolContext } from "../services/tool-context";
+	import type {
+		ToolRegistry,
+		ToolToolbarButtonDefinition,
+		ToolbarContext,
+	} from "../services/ToolRegistry.js";
+	import type { ToolContext } from "../services/tool-context.js";
 	import ToolButton from "./ToolButton.svelte";
 
 	// Props
@@ -17,6 +21,7 @@
 		toolRegistry,
 		allowedToolIds,
 		context,
+		toolbarContext,
 		onToolClick,
 		orientation = "horizontal",
 		compact = false,
@@ -28,6 +33,8 @@
 		allowedToolIds: string[];
 		/** Context for visibility evaluation (Pass 2) */
 		context: ToolContext;
+		/** Context used for toolbar rendering contract */
+		toolbarContext: ToolbarContext;
 		/** Callback when tool button is clicked */
 		onToolClick?: (toolId: string) => void;
 		/** Layout orientation */
@@ -44,17 +51,26 @@
 		toolRegistry.filterVisibleInContext(allowedToolIds, context),
 	);
 
-	// Create button definitions for visible tools
-	const buttons = $derived(
-		visibleTools.map((tool) =>
-			tool.createButton(context, {
+	// Create button definitions for visible tools using the toolbar contract
+	const buttons = $derived.by((): ToolToolbarButtonDefinition[] => {
+		const rendered = visibleTools
+			.map((tool) => toolRegistry.renderForToolbar(tool.toolId, context, toolbarContext))
+			.filter((tool): tool is NonNullable<typeof tool> => Boolean(tool));
+
+		return rendered
+			.map((tool) => tool.button)
+			.filter((button): button is ToolToolbarButtonDefinition => Boolean(button))
+			.map((button) => ({
+				...button,
 				onClick: () => {
-					onToolClick?.(tool.toolId);
+					button.onClick();
+					onToolClick?.(button.toolId);
 				},
-				className: compact ? "tool-button--compact" : "",
-			}),
-		),
-	);
+				className: compact
+					? `${button.className ? `${button.className} ` : ""}tool-button--compact`
+					: button.className,
+			}));
+	});
 
 	// Derive container classes
 	const containerClasses = $derived(

package/src/tools/README.md

@@ -139,10 +139,10 @@ src/lib/tags/tool-{name}/
 {#if visible}
   <div 
     bind:this={containerEl}
-    class="my-tool"
+    class="pie-tool-my-tool"
     on:mousedown={() => toolCoordinator.bringToFront(toolId)}
   >
-    <div class="tool-header">
+    <div class="pie-tool-my-tool__header">
       <span>My Tool</span>
       <button on:click={handleClose}>×</button>
     </div>
@@ -152,7 +152,7 @@ src/lib/tags/tool-{name}/
 {/if}
 
 <style>
-  .my-tool {
+  .pie-tool-my-tool {
     position: fixed;
     /* Tool-specific styles */
   }
@@ -257,6 +257,7 @@ Tools that require external API integration:
 6. **Make tools draggable** for better UX
 7. **Add close buttons** to all tools
 8. **Use consistent styling** (header, body, controls)
+9. **Use namespaced classes** (`pie-tool-{name}` and `pie-tool-{name}__*`)
 
 ## Architectural Enhancement Services
 
@@ -317,7 +318,7 @@ const roster: RosterToolConfiguration = {
   rosterId: 'roster-456',
   toolAllowances: {
     calculator: '1', // allowed
-    dictionary: '0', // blocked
+    lineReader: '0', // blocked
   },
 };
 
@@ -329,7 +330,7 @@ const item: ItemToolConfig = {
 
 // Resolve final tools
 const resolved = accommodationResolver.resolveToolsForItem(student, roster, item);
-// Returns: [calculator, highlighter, protractor] (graphing-calculator blocked, dictionary blocked)
+// Returns: [calculator, highlighter, protractor] (graphing-calculator blocked, lineReader blocked)
 
 // Check specific tool
 const result = accommodationResolver.isToolAllowed('calculator', student, roster, item);