feat(qti3): add delivery context parity foundations

Add resolved QTI 3 delivery context, item session lifecycle, timing evidence, and clean-room coverage so certification and accessibility gates can run against the restored workspace dependencies.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chillenious

apps/demo/src/lib/package-processor.ts

@@ -11,7 +11,14 @@ import {
 	tryResolveImagePath
 } from '@pie-qti/ims-cp-browser';
 import type { VirtualPackage } from '@pie-qti/ims-cp-browser';
-import { extractQtiItemMetadata, type QtiItemMetadata } from '@pie-qti/ims-cp-core';
+import {
+	createResolvedItemDeliveryContext,
+	extractAssessmentStimulusRefs,
+	extractQtiItemMetadata,
+	type AssessmentStimulusRef,
+	type QtiItemMetadata,
+	type ResolvedItemDeliveryContext
+} from '@pie-qti/ims-cp-core';
 import { createLogger } from '@pie-qti/logger/browser';
 
 // Storage key for the current package ID
@@ -364,63 +371,14 @@ function resolveMediaReferencesInXml(xml: string, pkg: PackageStructure, itemHre
 	return new XMLSerializer().serializeToString(doc);
 }
 
-/**
- * Stimulus reference extracted from a QTI item's qti-assessment-stimulus-ref element.
- */
-export interface StimulusRef {
-	identifier: string;
-	href: string;
-	title?: string;
-}
+export type StimulusRef = AssessmentStimulusRef;
 
 /**
  * Extract qti-assessment-stimulus-ref elements from QTI 3.0 item XML.
  * Returns an array of stimulus references found in the item.
  */
 export function extractStimulusRefsFromItemXml(xml: string): StimulusRef[] {
-	const pattern = /<qti-assessment-stimulus-ref([^>]+)>/gi;
-	const refs: StimulusRef[] = [];
-	let match: RegExpExecArray | null;
-	while ((match = pattern.exec(xml)) !== null) {
-		const attrs = match[1];
-		const identifier = attrs.match(/\bidentifier="([^"]+)"/i)?.[1];
-		const href = attrs.match(/\bhref="([^"]+)"/i)?.[1];
-		const title = attrs.match(/\btitle="([^"]+)"/i)?.[1];
-		if (identifier && href) {
-			refs.push({ identifier, href, title });
-		}
-	}
-	return refs;
-}
-
-/**
- * Extract inner HTML of the <qti-stimulus-body> element from a QTI 3.0 stimulus XML file.
- */
-function extractStimulusBodyHtml(stimulusXml: string): string {
-	const match = stimulusXml.match(/<qti-stimulus-body[^>]*>([\s\S]*?)<\/qti-stimulus-body>/i);
-	return match ? match[1].trim() : '';
-}
-
-/**
- * Resolve a path relative to a base file href within the package.
- * e.g. href="Items/Item-1/item.xml", relativePath="../../Passages/file.xml"
- * returns "Passages/file.xml"
- */
-function resolveRelativePath(baseHref: string, relativePath: string): string {
-	// Build a base by stripping the filename from the item href
-	const baseDir = baseHref.includes('/') ? baseHref.substring(0, baseHref.lastIndexOf('/') + 1) : '';
-	// Combine and resolve ../ sequences
-	const combined = baseDir + relativePath;
-	const parts = combined.split('/');
-	const resolved: string[] = [];
-	for (const part of parts) {
-		if (part === '..') {
-			resolved.pop();
-		} else if (part !== '.') {
-			resolved.push(part);
-		}
-	}
-	return resolved.join('/');
+	return extractAssessmentStimulusRefs(xml);
 }
 
 /**
@@ -438,32 +396,30 @@ export async function loadStimulusContent(
 	itemHref: string,
 	refs: StimulusRef[]
 ): Promise<Record<string, string>> {
-	const result: Record<string, string> = {};
-
-	for (const ref of refs) {
-		const stimulusPath = resolveRelativePath(itemHref, ref.href);
-		const stimulusXml = pkg._pkg.readText(stimulusPath);
-		if (!stimulusXml) {
-			logger.warn(`Stimulus file not found in package: ${stimulusPath}`);
-			continue;
-		}
-
-		// Extract the body HTML
-		let bodyHtml = extractStimulusBodyHtml(stimulusXml);
-		if (!bodyHtml) {
-			logger.warn(`No qti-stimulus-body found in stimulus: ${stimulusPath}`);
-			continue;
-		}
+	const itemXml = pkg._pkg.readText(itemHref) ?? '';
+	const deliveryContext = await loadItemDeliveryContext(pkg, itemHref, itemXml);
+	return Object.fromEntries(
+		refs
+			.map((ref) => [ref.identifier, deliveryContext.stimuli[ref.identifier]?.bodyHtml] as const)
+			.filter((entry): entry is readonly [string, string] => Boolean(entry[1]))
+	);
+}
 
-		// Resolve images in the stimulus body using the stimulus file path as base
-		try {
-			bodyHtml = await resolveImagesInXmlCore(bodyHtml, pkg._pkg, stimulusPath, { logger });
-		} catch (err) {
-			logger.warn(`Failed to resolve images in stimulus ${ref.identifier}:`, err);
-		}
+export async function loadItemDeliveryContext(
+	pkg: PackageStructure,
+	itemHref: string,
+	itemXml: string
+): Promise<ResolvedItemDeliveryContext> {
+	const context = createResolvedItemDeliveryContext({
+		itemXml,
+		itemHref,
+		readText: (path) => pkg._pkg.readText(path),
+		resolveAssetUrl: (path) => pkg._pkg.getDataUrl(path),
+	});
 
-		result[ref.identifier] = bodyHtml;
+	for (const message of context.validationMessages) {
+		logger.warn(message);
 	}
 
-	return result;
+	return context;
 }

apps/demo/src/routes/package-upload/[packageId]/item/[itemId]/+page.svelte

@@ -5,14 +5,15 @@
 	import { goto } from '$app/navigation';
 	import { base } from '$app/paths';
 	import { Player, normalizeHeuristicsConfig, shouldAutoPopulateFeedbackOutcome, type QtiHeuristicsConfig } from '@pie-qti/item-player';
+	import type { ResolvedItemDeliveryContext } from '@pie-qti/ims-cp-core';
 	import type { InteractionResponseValue } from '@pie-qti/item-player/web-components';
 	// @ts-expect-error - Svelte-check can't resolve workspace subpath exports, but runtime works correctly
 	import { ItemBody } from '@pie-qti/item-player/components';
 	import { registerDefaultComponents } from '@pie-qti/default-components';
 	import { typesetAction } from '@pie-qti/default-components/shared';
 	import { typesetMathInElement } from '@pie-qti/typeset-katex';
 	import type { SvelteI18nProvider } from '@pie-qti/i18n';
-	import { loadPackageDataAsync, getItemXml, resolveImagesInXml, extractStimulusRefsFromItemXml, loadStimulusContent, listFiles } from '$lib/package-processor';
+	import { loadPackageDataAsync, getItemXml, resolveImagesInXml, extractStimulusRefsFromItemXml, loadStimulusContent, loadItemDeliveryContext, listFiles } from '$lib/package-processor';
 	import type { PackageStructure } from '$lib/package-processor';
 	import { getSecurityConfig } from '$lib/player-config';
 	import XmlEditor from '$lib/components/XmlEditor.svelte';
@@ -56,6 +57,7 @@
 	let responses = $state<ItemResponseMap>({});
 	let outcomeValues = $state<Record<string, any>>({});
 	let stimulusContent = $state<Record<string, string>>({});
+	let deliveryContext = $state<ResolvedItemDeliveryContext | undefined>(undefined);
 	let diagnostics = $state<QtiCompatibilityReport | null>(null);
 
 	// Get i18n provider from context
@@ -78,6 +80,7 @@
 		responses = {};
 		outcomeValues = {};
 		stimulusContent = {};
+		deliveryContext = undefined;
 		diagnostics = null;
 
 		// Load item asynchronously
@@ -135,6 +138,7 @@
 				if (currentItem2?.href) {
 					const stimulusRefs = extractStimulusRefsFromItemXml(itemXml);
 					if (stimulusRefs.length > 0) {
+						deliveryContext = await loadItemDeliveryContext(packageData, currentItem2.href, itemXml);
 						stimulusContent = await loadStimulusContent(packageData, currentItem2.href, stimulusRefs);
 					}
 				}
@@ -145,6 +149,7 @@
 				player = new Player({
 					itemXml: itemXml,
 					role: 'candidate',
+					deliveryContext,
 					security: {
 						...getSecurityConfig(),
 						urlPolicy: {
@@ -330,6 +335,7 @@
 					typeset={typesetMathInElement}
 					onResponseChange={handleResponseChange}
 					{heuristicsConfig}
+					{deliveryContext}
 					{stimulusContent}
 				/>
 			</div>

bun.lock

@@ -1,7 +1,7 @@
 {
 	"$schema": "./public-coverage-matrix.schema.json",
 	"scope": "QTI 2.2 Advanced and QTI 3.0 Advanced DELIVERY public clean-room coverage",
-	"updated": "2026-05-04",
+	"updated": "2026-05-05",
 	"commands": [
 		{
 			"id": "item-clean-room",
@@ -26,6 +26,24 @@
 				"packages/assessment-player/tests/conformance-qti30-advanced.test.ts"
 			]
 		},
+		{
+			"id": "package-clean-room",
+			"description": "Clean-room IMS CP and QTI 3 shared content parsing coverage",
+			"cwd": ".",
+			"args": ["test", "packages/ims-cp-core/tests/qti3-shared-content.test.ts"]
+		},
+		{
+			"id": "item-runtime-clean-room",
+			"description": "Clean-room item runtime session, PNP, and catalog behavior coverage",
+			"cwd": ".",
+			"args": [
+				"test",
+				"packages/item-player/tests/core/item-session-lifecycle.test.ts",
+				"packages/item-player/tests/core/pnp.test.ts",
+				"packages/item-player/tests/core/delivery-context.test.ts",
+				"packages/item-player/tests/core/glossaryTriggers.test.ts"
+			]
+		},
 		{
 			"id": "mathml-clean-room",
 			"description": "MathML rendering coverage",
@@ -314,11 +332,11 @@
 			"level": "Advanced",
 			"feature": "I4 Shared Stimulus",
 			"officialPath": "qti3.0/Advanced/I4 Shared Stimulus/",
-			"publicTests": ["packages/item-player/src/extraction/extractors/conformance-qti3-advanced.test.ts", "apps/demo/tests/playwright/public-certification.pw.ts"],
+			"publicTests": ["packages/item-player/src/extraction/extractors/conformance-qti3-advanced.test.ts", "packages/ims-cp-core/tests/qti3-shared-content.test.ts", "packages/item-player/tests/core/delivery-context.test.ts", "apps/demo/tests/playwright/public-certification.pw.ts"],
 			"fixturePackages": [],
 			"e2eRequired": true,
-			"commandIds": ["item-clean-room", "browser-visible"],
-			"notes": "Covers stimulus reference preservation and browser-visible shared stimulus rendering."
+			"commandIds": ["item-clean-room", "package-clean-room", "item-runtime-clean-room", "browser-visible"],
+			"notes": "Covers stimulus reference preservation, structured qti-assessment-stimulus parsing, stylesheet/catalog extraction, and item-runtime consumption of resolved stimulus/catalog context. Scoped stylesheet/catalog and browser-visible shared stimulus rendering evidence is tracked in docs/certification/qti3-remaining-parity-evidence.md."
 		},
 		{
 			"id": "qti30-advanced-i17",
@@ -362,11 +380,11 @@
 			"level": "Advanced",
 			"feature": "A13 captions and A15 glossary",
 			"officialPath": "qti3.0/Advanced/A13captions_A15glossary/",
-			"publicTests": ["packages/item-player/src/extraction/extractors/conformance-qti3-advanced.test.ts", "apps/demo/tests/playwright/public-certification.pw.ts"],
+			"publicTests": ["packages/item-player/src/extraction/extractors/conformance-qti3-advanced.test.ts", "packages/item-player/tests/core/pnp.test.ts", "packages/item-player/tests/core/glossaryTriggers.test.ts", "apps/demo/tests/playwright/public-certification.pw.ts"],
 			"fixturePackages": [],
 			"e2eRequired": true,
-			"commandIds": ["item-clean-room", "browser-visible"],
-			"notes": "Covers caption track preservation, catalog references, and glossary lookup."
+			"commandIds": ["item-clean-room", "item-runtime-clean-room", "browser-visible"],
+			"notes": "Covers caption track preservation plus item-runtime PNP/catalog coverage for glossary, keyword translation, and illustrated glossary triggers. Browser-visible catalog affordances, access-for-all, dynamic rebinding, host-routed support, and manual AT evidence is tracked in docs/certification/qti3-remaining-parity-evidence.md."
 		},
 		{
 			"id": "qti30-advanced-s3-s4",
@@ -413,8 +431,8 @@
 			"publicTests": ["packages/assessment-player/tests/conformance-qti30-advanced.test.ts"],
 			"fixturePackages": [],
 			"e2eRequired": false,
-			"commandIds": ["assessment-clean-room"],
-			"notes": "Covers qti-item-session-control and max-attempts=0 as unlimited."
+			"commandIds": ["assessment-clean-room", "item-runtime-clean-room"],
+			"notes": "Covers qti-item-session-control, max-attempts=0 as unlimited, and individual/simultaneous item session behavior. Remaining item-ref/section/testPart precedence evidence is tracked in docs/certification/qti3-remaining-parity-evidence.md."
 		},
 		{
 			"id": "qti30-advanced-t12",
@@ -426,7 +444,7 @@
 			"fixturePackages": [],
 			"e2eRequired": true,
 			"commandIds": ["assessment-clean-room", "browser-visible"],
-			"notes": "Covers qti-assessment-section, qti-time-limits, allow-skipping, and qti-assessment-section-ref."
+			"notes": "Covers qti-assessment-section, qti-time-limits, allow-skipping, and qti-assessment-section-ref. Remaining item/section/test timing precedence, restoration, expiry, and accessible timer UI evidence is tracked in docs/certification/qti3-remaining-parity-evidence.md."
 		}
 	]
 }