@pie-players/pie-assessment-toolkit 0.3.30 → 0.3.32

package/dist/components/PieAssessmentToolkit.custom-element.js

@@ -16,10 +16,12 @@ const __pieDefineSafely = (tagName, ctor) => {
 
 import 'svelte/internal/disclose-version';
 import * as $ from 'svelte/internal/client';
+import { untrack } from "svelte";
 import { ContextProvider, ContextRoot, requestContext } from "@pie-players/pie-context";
 
 import {
 	attachInstrumentationEventBridge,
+	createStageTracker,
 	resolveInstrumentationProvider,
 	TOOLKIT_INSTRUMENTATION_EVENT_MAP
 } from "@pie-players/pie-players-shared/pie";
@@ -34,7 +36,9 @@ import {
 import { connectAssessmentToolkitHostRuntimeContext } from "../context/runtime-context-consumer.js";
 import { ToolkitCoordinator } from "../services/ToolkitCoordinator.js";
 import { formatFrameworkErrorForConsole, frameworkErrorFromUnknown } from "../services/framework-error.js";
+import { FrameworkErrorBus } from "../services/framework-error-bus.js";
 import { normalizeAndValidateToolsConfig } from "../services/tool-config-validation.js";
+import { parseToolList } from "../services/tools-config-normalizer.js";
 
 import {
 	PIE_INTERNAL_CONTENT_LOADED_EVENT,
@@ -46,7 +50,9 @@ import {
 
 import { dispatchCrossBoundaryEvent } from "../runtime/tool-host-contract.js";
 import { SectionRuntimeEngine } from "../runtime/SectionRuntimeEngine.js";
-import { createRuntimeId } from "../runtime/runtime-event-guards.js";
+import { connectSectionRuntimeEngineHostContext } from "../runtime/section-runtime-engine-host-context.js";
+import { runStageEmitWithSuppression } from "../runtime/stage-emit-gate.js";
+import { createRuntimeId } from "../runtime/runtime-id.js";
 
 import {
 	createSessionEmitPolicyState,
@@ -68,6 +74,31 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 
 	const runtimeId = createRuntimeId("toolkit");
 	const sectionEngine = new SectionRuntimeEngine();
+
+	// M7 PR 6: when wrapped by a section-player layout, the kernel
+	// publishes its engine via the cross-CE
+	// `sectionRuntimeEngineHostContext`. We track the upstream
+	// reference so wrapped-mode-specific behavior (stage-emit
+	// suppression to avoid double-emit on layout CE; framework-error
+	// FSM input forwarding) can branch off it. `null` means
+	// standalone — no upstream provider responded — and the toolkit
+	// keeps its existing pre-PR-6 behavior. The reference is set once
+	// per cohort by the cross-CE consumer effect below; it never
+	// becomes a substitute for `sectionEngine` (the local engine
+	// remains the controller-side facade for `register`,
+	// `handleContent*`, `initialize`, etc.). PR 7+ will collapse the
+	// local controller-side surface onto the upstream engine.
+	let upstreamEngine = $.state(null);
+
+	// Per-CE-instance framework-error bus. Shared with the owned
+	// `ToolkitCoordinator` so coordinator-side failures (provider-init,
+	// tts-init, ...) flow through the same fan-out as CE-side failures
+	// (coordinator-init, runtime-init, runtime-dispose). The bus is the
+	// single source for the canonical `onFrameworkError` prop, the
+	// `framework-error` DOM event, the banner UI, and the
+	// `subscribeFrameworkErrors` API on the coordinator.
+	const frameworkErrorBus = new FrameworkErrorBus();
+
 	const DEFAULT_ENV = { mode: "gather", role: "student" };
 
 	const DEFAULT_ITEM_PLAYER_BY_TYPE = {
@@ -81,27 +112,46 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		section = $.prop($$props, 'section', 7, null),
 		sectionId = $.prop($$props, 'sectionId', 7, ""),
 		attemptId = $.prop($$props, 'attemptId', 7, ""),
-		view = $.prop($$props, 'view', 7, "candidate"),
 		env = $.prop($$props, 'env', 23, () => ({})),
 		lazyInit = $.prop($$props, 'lazyInit', 7, true),
 		toolConfigStrictness = $.prop($$props, 'toolConfigStrictness', 7, "error"),
 		tools = $.prop($$props, 'tools', 23, () => ({})),
+		enabledTools = $.prop($$props, 'enabledTools', 7, ""),
 		toolRegistry = $.prop($$props, 'toolRegistry', 7, null),
 		accessibility = $.prop($$props, 'accessibility', 23, () => ({})),
 		player = $.prop($$props, 'player', 7, null),
 		playerType = $.prop($$props, 'playerType', 7, ""),
 		coordinator = $.prop($$props, 'coordinator', 7, null),
 		createSectionController = $.prop($$props, 'createSectionController', 7, null),
-		frameworkErrorCallback = $.prop($$props, 'frameworkErrorHook', 7, null),
 		onFrameworkError = $.prop($$props, 'onFrameworkError', 7, null),
-		onframeworkerror = $.prop($$props, 'onframeworkerror', 7, null),
 		errorRenderer = $.prop($$props, 'errorRenderer', 7, null),
+		onStageChange = $.prop($$props, 'onStageChange', 7, null),
+		// M8 PR 2 — additive Tool Policy Engine inputs. See the
+		// `<svelte:options>` props block above for the rationale.
+		// `qtiEnforcement` accepts `"on"`, `"off"`, or `null` (auto —
+		// the coordinator infers the effective mode from QTI material
+		// on the bound `assessment` / `currentItemRef`). Embedded
+		// under `<pie-section-player-*>` the same override flows via
+		// `runtime.tools.qtiEnforcement`; the effect below falls back
+		// to `tools.qtiEnforcement` when the explicit prop is `null`
+		// so both entry points converge on the same coordinator call.
+		assessment = $.prop($$props, 'assessment', 7, null),
+		currentItemRef = $.prop($$props, 'currentItemRef', 7, null),
+		qtiEnforcement = $.prop($$props, 'qtiEnforcement', 7, null),
 		isolation = $.prop($$props, 'isolation', 7, "inherit");
 
 	let anchor = $.state(null);
 	let ownedCoordinator = $.state(null);
 	let inheritedRuntime = $.state(null);
-	let lastOwnership = $.state(null);
+
+	// `lastOwnership` is a self-comparison latch read and written only by
+	// the ownership-change `$effect` below. Keeping it as `$state` would
+	// make Svelte treat the same-effect read+write as a reactivity loop
+	// (effect_update_depth_exceeded). It does not feed any other reactive
+	// consumer, so a plain `let` is safer and matches the canonical Svelte
+	// 5 latch pattern from `.cursor/rules/svelte-subscription-safety.mdc`.
+	let lastOwnership = null;
+
 	let provider = null;
 	let contextRoot = null;
 	let hostRuntimeProvider = null;
@@ -112,8 +162,17 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 	let frameworkErrorModel = $.state(null);
 	let frameworkErrorTitle = $.state("Unable to initialize assessment toolkit.");
 	let frameworkErrorDetails = $.state($.proxy([]));
-	let deliveredFrameworkErrorKey = $.state("");
-	let lastOwnedBootstrapFailureKey = $.state("");
+
+	// Self-comparison latches for the framework-error redelivery `$effect`
+	// and the owned-coordinator bootstrap `$effect` below. Same rationale
+	// as `lastOwnership`: keeping these as `$state` made the owning
+	// effects read+write the same source in a single pass, tripping
+	// `effect_update_depth_exceeded`. Neither value is read by any other
+	// reactive consumer, so plain `let` removes the loop without dropping
+	// any subscriber.
+	let deliveredFrameworkErrorKey = "";
+
+	let lastOwnedBootstrapFailureKey = "";
 	let lastCompositionRevisionKey = $.state("");
 	let pendingCompositionModel = null;
 	let pendingCompositionEmit = false;
@@ -121,6 +180,79 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 	let pendingCrossBoundaryEvents = [];
 	const sessionEmitPolicyState = createSessionEmitPolicyState();
 
+	// M6 canonical stage tracker. Post-retro the toolkit applies the
+	// same four-stage canonical list (`composed`, `engine-ready`,
+	// `interactive`, `disposed`) as every layout CE; subscriber
+	// iteration order stays stable across `<pie-section-player-*>` and
+	// `<pie-assessment-toolkit>` CE shapes. Cohort changes
+	// (`(sectionId, attemptId)`) reset the tracker so the new cohort
+	// begins emitting from `composed`. Initial seed values are captured
+	// via `untrack` because the tracker explicitly absorbs subsequent
+	// cohort changes through `reset()`, not through prop reactivity at
+	// construction time.
+	const stageTracker = createStageTracker({
+		sourceCe: "pie-assessment-toolkit",
+		sourceCeShape: "toolkit",
+		runtimeId,
+		sectionId: untrack(() => sectionId() || undefined),
+		attemptId: untrack(() => attemptId() || undefined),
+		emit: (detail) => {
+			// M7 PR 6: route the toolkit's stage-emit through the
+			// extracted `runStageEmitWithSuppression` helper so the
+			// wrapped/standalone gating logic is testable in isolation
+			// (see `tests/runtime/stage-emit-gate.test.ts`). The
+			// thunks below preserve pre-PR-6 semantics:
+			//
+			//   - `isSuppressed`: when wrapped by a section-player
+			//     layout the kernel's engine emits the canonical
+			//     `pie-stage-change` chain on the layout CE host and
+			//     invokes the runtime-tier `onStageChange` callback
+			//     itself. Suppressing here prevents the toolkit CE
+			//     from also emitting (which would bubble through
+			//     `composed: true` to the layout CE host and produce a
+			//     duplicate emission for outside listeners). The
+			//     internal stage-tracker latch state advances before
+			//     `opts.emit` runs, so suppression only short-circuits
+			//     externally-visible side effects — the toolkit's own
+			//     readiness path (`waitUntilReady` / `engine-ready` /
+			//     `interactive`) stays correct in standalone mode and
+			//     degenerates into a series of suppressed emits in
+			//     wrapped mode without losing any latch transitions.
+			//
+			//     The reactive `upstreamEngine` is read inside the
+			//     thunk (i.e. at emit time, not at construction time)
+			//     and all callers of `stageTracker.enter(...)` are
+			//     themselves wrapped in `untrack(...)` (see effects
+			//     below), so the read does not feed back into any
+			//     tracked dependency graph.
+			//
+			//   - `getOnStageChange`: the prop is read on every emit
+			//     so reassignments (cohort change, host swap) always
+			//     reach the latest handler.
+			runStageEmitWithSuppression(
+				{
+					isSuppressed: () => $.get(upstreamEngine) !== null,
+					dispatchDomEvent: (d) => emit("pie-stage-change", d),
+					getOnStageChange: () => onStageChange()
+				},
+				detail
+			);
+		}
+	});
+
+	let lastStageCohortKey = $.state($.proxy(untrack(() => `${sectionId()}|${attemptId()}`)));
+	let composedStageEntered = $.state(false);
+	let engineReadyStageEntered = $.state(false);
+	let interactiveStageEntered = $.state(false);
+
+	// `sectionInitialized` is the second of two preconditions for the
+	// `interactive` stage emission. The toolkit's interactive entrance
+	// requires *both* `engine-ready` (coordinator bring-up settled) and
+	// `sectionInitialized` (section composition + controller hydrated)
+	// before it fires. A reactive effect below joins them so neither
+	// race ordering silently drops a stage.
+	let sectionInitialized = $.state(false);
+
 	function getHostElement() {
 		if (!$.get(anchor)) return null;
 
@@ -200,6 +332,20 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		}
 	}
 
+	/**
+	 * Build a `FrameworkErrorModel` and publish it on this CE's
+	 * framework-error bus.
+	 *
+	 * All delivery side-effects (banner UI, `framework-error` DOM event,
+	 * hook delivery, console logging) live in the bus subscriber
+	 * registered below — keeping this helper a thin publish-side wrapper
+	 * that CE-internal callers can use.
+	 *
+	 * Coordinator-side failures (provider-init, tts-init, ...) reach the
+	 * same subscriber by way of the shared bus (passed into the owned
+	 * coordinator via `buildOwnedCoordinator`), so consumers see one
+	 * canonical fan-out per error.
+	 */
 	function reportFrameworkError(args) {
 		const model = frameworkErrorFromUnknown({
 			kind: args.kind,
@@ -208,49 +354,69 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			recoverable: args.recoverable
 		});
 
-		console.error(formatFrameworkErrorForConsole(model), model.cause);
+		frameworkErrorBus.reportFrameworkError(model);
 
-		const rendered = applyErrorRenderer(model);
+		return model;
+	}
 
-		$.set(frameworkErrorModel, model, true);
-		$.set(frameworkErrorTitle, rendered.title, true);
-		$.set(frameworkErrorDetails, rendered.details, true);
-		emit("framework-error", model);
-		emit("runtime-error", { runtimeId, error: args.error, frameworkError: model });
+	/**
+	 * Whether this CE should surface the bootstrap banner for `kind`.
+	 *
+	 * The banner is the visible "we could not start the toolkit" surface
+	 * and is intentionally narrower than the canonical contract: it only
+	 * fires for fatal CE-bootstrap kinds (`coordinator-init`,
+	 * `runtime-init`, `tool-config`). Coordinator-internal failures
+	 * (provider-init, tts-init, ...) still flow through the canonical
+	 * hook + DOM event but do not replace the toolkit content with an
+	 * error card — they are degradations, not bootstrap failures.
+	 */
+	function isBootstrapKind(kind) {
+		return kind === "coordinator-init" || kind === "runtime-init" || kind === "tool-config";
+	}
 
-		const frameworkErrorHook = frameworkErrorCallback() ?? onFrameworkError() ?? onframeworkerror();
+	function deliverFrameworkErrorHook(model) {
+		if (!onFrameworkError()) return;
 
-		if (frameworkErrorHook) {
-			try {
-				frameworkErrorHook(model);
-				$.set(deliveredFrameworkErrorKey, `${model.kind}|${model.source}|${model.message}`);
-			} catch(hookError) {
-				console.error(`[pie-framework:runtime-init:pie-assessment-toolkit] framework error hook failed`, hookError);
-			}
+		try {
+			onFrameworkError()(model);
+			deliveredFrameworkErrorKey = `${model.kind}|${model.source}|${model.message}`;
+		} catch(hookError) {
+			console.error(`[pie-framework:${model.kind}:${model.source}] framework error hook failed`, hookError);
 		}
-
-		return model;
 	}
 
 	$.user_effect(() => {
-		if (!$.get(frameworkErrorModel)) {
-			return;
-		}
+		const detach = frameworkErrorBus.subscribeFrameworkErrors((model) => {
+			console.error(formatFrameworkErrorForConsole(model), model.cause);
 
-		const frameworkErrorKey = `${$.get(frameworkErrorModel).kind}|${$.get(frameworkErrorModel).source}|${$.get(frameworkErrorModel).message}`;
+			if (isBootstrapKind(model.kind)) {
+				const rendered = applyErrorRenderer(model);
 
-		if ($.get(deliveredFrameworkErrorKey) === frameworkErrorKey) return;
+				$.set(frameworkErrorModel, model, true);
+				$.set(frameworkErrorTitle, rendered.title, true);
+				$.set(frameworkErrorDetails, rendered.details, true);
+			}
 
-		const frameworkErrorHook = frameworkErrorCallback() ?? onFrameworkError() ?? onframeworkerror();
+			emit("framework-error", model);
+			deliverFrameworkErrorHook(model);
+		});
 
-		if (!frameworkErrorHook) return;
+		return () => {
+			detach();
+		};
+	});
 
-		try {
-			frameworkErrorHook($.get(frameworkErrorModel));
-			$.set(deliveredFrameworkErrorKey, frameworkErrorKey);
-		} catch(hookError) {
-			console.error(`[pie-framework:runtime-init:pie-assessment-toolkit] framework error hook failed`, hookError);
-		}
+	$.user_effect(() => {
+		if (!$.get(frameworkErrorModel)) return;
+
+		const frameworkErrorKey = `${$.get(frameworkErrorModel).kind}|${$.get(frameworkErrorModel).source}|${$.get(frameworkErrorModel).message}`;
+
+		if (deliveredFrameworkErrorKey === frameworkErrorKey) return;
+
+		// Hook prop became available after the framework-error model was
+		// already produced (e.g. host wired it asynchronously). Re-deliver
+		// once for the current model so late-binding hosts see the error.
+		deliverFrameworkErrorHook($.get(frameworkErrorModel));
 	});
 
 	function hashString(input) {
@@ -392,8 +558,41 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		throw new Error("pie-assessment-toolkit requires createSectionController when no coordinator hook provides one");
 	}
 
+	/**
+	 * Merge the `enabled-tools` shorthand into a `tools.placement.section`
+	 * list, leaving the `tools` object form authoritative when both are
+	 * provided. Mirrors `resolveToolsConfig` in the section-player layer
+	 * so direct toolkit hosts get the same easy-tier behavior.
+	 *
+	 * Precedence (highest first):
+	 *   1. Explicit `tools.placement.section` array on the `tools` prop
+	 *   2. `enabled-tools` shorthand attribute / `enabledTools` prop
+	 *
+	 * Section-player CEs already merge before passing `tools` here, so for
+	 * the embedded path this helper is a no-op in practice; it only fires
+	 * when a host mounts `<pie-assessment-toolkit>` directly.
+	 */
+	function buildEffectiveToolsInput() {
+		const baseTools = tools() || {};
+		const sectionShorthand = parseToolList(enabledTools());
+
+		if (sectionShorthand.length === 0) return baseTools;
+
+		const placement = baseTools.placement || {};
+		const explicitSectionPlacement = Array.isArray(placement.section) ? placement.section : null;
+
+		if (explicitSectionPlacement && explicitSectionPlacement.length > 0) {
+			return baseTools;
+		}
+
+		return {
+			...baseTools,
+			placement: { ...placement, section: sectionShorthand }
+		};
+	}
+
 	function validateToolsConfigForBootstrap() {
-		return normalizeAndValidateToolsConfig(tools(), {
+		return normalizeAndValidateToolsConfig(buildEffectiveToolsInput(), {
 			strictness: toolConfigStrictness(),
 			source: "pie-assessment-toolkit.bootstrap",
 			toolRegistry: toolRegistry()
@@ -404,7 +603,7 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		let toolsSignature = "";
 
 		try {
-			toolsSignature = JSON.stringify(tools() || {});
+			toolsSignature = JSON.stringify(buildEffectiveToolsInput());
 		} catch {
 			toolsSignature = "[unserializable-tools]";
 		}
@@ -416,6 +615,39 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		].join("|");
 	}
 
+	// Coerce the public `qti-enforcement` CE attribute (string or null)
+	// into the engine's `QtiEnforcementMode | null` contract. Anything
+	// outside the canonical "on" / "off" set — typos like "ON",
+	// missing-attribute artifacts like "" or "null" strings — collapses
+	// to `null` (auto-mode) instead of silently degrading inside the
+	// engine. This is the single canonical entry point for the prop;
+	// keep all `setQtiEnforcement(...)` calls in this file routed
+	// through it.
+	function coerceQtiEnforcement(value) {
+		return value === "on" || value === "off" ? value : null;
+	}
+
+	// Resolve the effective override that flows into the coordinator.
+	// The explicit `qti-enforcement` attribute (standalone path) wins
+	// over `tools.qtiEnforcement` (embedded path via
+	// `runtime.tools.qtiEnforcement`); both fall back to `null`
+	// (auto-mode) so the coordinator's
+	// {@link resolveDefaultQtiEnforcement} helper runs on the bound
+	// assessment / item ref.
+	function resolveQtiEnforcementInput(explicit, toolsConfig) {
+		const explicitMode = coerceQtiEnforcement(explicit);
+
+		if (explicitMode) return explicitMode;
+
+		if (toolsConfig && typeof toolsConfig === "object") {
+			const candidate = toolsConfig.qtiEnforcement;
+
+			return coerceQtiEnforcement(typeof candidate === "string" ? candidate : null);
+		}
+
+		return null;
+	}
+
 	function buildOwnedCoordinator(validatedTools) {
 		const fallbackAssessmentId = assessmentId() || section()?.identifier || `assessment-${Math.random().toString(16).slice(2)}`;
 
@@ -426,7 +658,8 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			deferToolConfigValidation: true,
 			tools: validatedTools,
 			toolRegistry: toolRegistry(),
-			accessibility: accessibility()
+			accessibility: accessibility(),
+			frameworkErrorBus
 		});
 	}
 
@@ -438,52 +671,69 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		return coordinator() || $.get(ownedCoordinator);
 	});
 
+	// Owned-coordinator bootstrap. The effect must re-run when ownership
+	// inputs (`host`, `coordinator`, `isolation`, `inheritedRuntime`)
+	// change so the toolkit can swap between owned, passed-in, and
+	// inherited coordinators. It must *not* re-run on its own writes to
+	// `ownedCoordinator` / `lastOwnedBootstrapFailureKey` /
+	// `frameworkError*` / `runtimeError` — those self-mutations were the
+	// observed source of the `effect_update_depth_exceeded` warnings in
+	// the assessment-player smoke flow. We therefore explicitly track
+	// only the ownership inputs and run the bootstrap body inside
+	// `untrack`, matching `.cursor/rules/svelte-subscription-safety.mdc`.
 	$.user_effect(() => {
-		if (!$.get(host)) return;
+		void $.get(host);
+		void coordinator();
+		void isolation();
+		void $.get(inheritedRuntime);
 
-		if (coordinator()) {
-			if ($.get(ownedCoordinator)) {
-				$.set(ownedCoordinator, null);
-			}
+		untrack(() => {
+			if (!$.get(host)) return;
 
-			return;
-		}
+			if (coordinator()) {
+				if ($.get(ownedCoordinator)) {
+					$.set(ownedCoordinator, null);
+				}
 
-		if (isolation() !== "force" && $.get(inheritedRuntime)?.coordinator) {
-			if ($.get(ownedCoordinator)) {
-				$.set(ownedCoordinator, null);
+				return;
 			}
 
-			return;
-		}
-
-		if (!$.get(ownedCoordinator)) {
-			const failureKey = getOwnedBootstrapFailureKey();
+			if (isolation() !== "force" && $.get(inheritedRuntime)?.coordinator) {
+				if ($.get(ownedCoordinator)) {
+					$.set(ownedCoordinator, null);
+				}
 
-			if ($.get(lastOwnedBootstrapFailureKey) === failureKey) {
 				return;
 			}
 
-			try {
-				const validatedTools = validateToolsConfigForBootstrap();
-
-				$.set(ownedCoordinator, buildOwnedCoordinator(validatedTools), true);
-				$.set(lastOwnedBootstrapFailureKey, "");
-				$.set(frameworkErrorModel, null);
-				$.set(frameworkErrorTitle, "Unable to initialize assessment toolkit.");
-				$.set(frameworkErrorDetails, [], true);
-			} catch(error) {
-				$.set(runtimeError, error, true);
-				$.set(ownedCoordinator, null);
-				$.set(lastOwnedBootstrapFailureKey, failureKey, true);
+			if (!$.get(ownedCoordinator)) {
+				const failureKey = getOwnedBootstrapFailureKey();
 
-				reportFrameworkError({
-					kind: "coordinator-init",
-					source: "pie-assessment-toolkit",
-					error
-				});
+				if (lastOwnedBootstrapFailureKey === failureKey) {
+					return;
+				}
+
+				try {
+					const validatedTools = validateToolsConfigForBootstrap();
+
+					$.set(ownedCoordinator, buildOwnedCoordinator(validatedTools), true);
+					lastOwnedBootstrapFailureKey = "";
+					$.set(frameworkErrorModel, null);
+					$.set(frameworkErrorTitle, "Unable to initialize assessment toolkit.");
+					$.set(frameworkErrorDetails, [], true);
+				} catch(error) {
+					$.set(runtimeError, error, true);
+					$.set(ownedCoordinator, null);
+					lastOwnedBootstrapFailureKey = failureKey;
+
+					reportFrameworkError({
+						kind: "coordinator-init",
+						source: "pie-assessment-toolkit",
+						error
+					});
+				}
 			}
-		}
+		});
 	});
 
 	const effectiveAssessmentId = $.derived(() => assessmentId() || $.get(effectiveCoordinator)?.assessmentId || "");
@@ -626,12 +876,33 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		});
 	});
 
+	// M7 PR 6: cross-CE engine bridge consumer. When the toolkit CE
+	// renders inside a section-player layout, the kernel publishes its
+	// `SectionRuntimeEngine` via `sectionRuntimeEngineHostContext` on
+	// the layout CE host. The consumer's `context-request` bubbles up
+	// across the toolkit's shadow boundary, the kernel's provider
+	// answers, and we record the upstream reference. When standalone,
+	// no provider responds within the consumer's retry window and
+	// `upstreamEngine` stays `null` — that is the standalone path's
+	// contract. `isolation === "force"` does not opt out of this
+	// bridge: it is a runtime-engine seam, not a coordinator-isolation
+	// seam, and `force` still wants the canonical engine path.
+	$.user_effect(() => {
+		if (!$.get(host)) return;
+
+		return connectSectionRuntimeEngineHostContext($.get(host), (value) => {
+			if (value.engine === $.get(upstreamEngine)) return;
+
+			$.set(upstreamEngine, value.engine, true);
+		});
+	});
+
 	$.user_effect(() => {
 		const parentRuntimeId = isolation() !== "force" && $.get(inheritedRuntime) ? $.get(inheritedRuntime).runtimeId : null;
 		const ownership = parentRuntimeId ? "inherited" : "owned";
 
-		if (ownership !== $.get(lastOwnership)) {
-			$.set(lastOwnership, ownership, true);
+		if (ownership !== lastOwnership) {
+			lastOwnership = ownership;
 			emit(ownership === "inherited" ? "runtime-inherited" : "runtime-owned", { runtimeId, parentRuntimeId });
 		}
 	});
@@ -723,6 +994,62 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		});
 	});
 
+	// M8 — push Tool Policy Engine inputs (`assessment`,
+	// `currentItemRef`, `qtiEnforcement`) into the toolkit-owned
+	// coordinator whenever they change. The coordinator's
+	// `updateAssessment` / `updateCurrentItemRef` / `setQtiEnforcement`
+	// forwards land on `ToolPolicyEngine.updateInputs`, which value-
+	// diffs each key with `Object.is` and only emits an `inputs` event
+	// on real changes — so re-running this effect on coordinator swap
+	// is safe and self-idempotent. We touch the reactive props
+	// explicitly and then run the side effect inside `untrack(...)`
+	// per `.cursor/rules/svelte-subscription-safety.mdc`.
+	//
+	// `qtiEnforcement` resolves through {@link resolveQtiEnforcementInput}
+	// so the embedded path (`<pie-section-player-*>` setting
+	// `runtime.tools.qtiEnforcement`) and the standalone path (the
+	// explicit `qti-enforcement` attribute on `<pie-assessment-toolkit>`)
+	// converge on a single coordinator call. The explicit prop wins
+	// over `tools.qtiEnforcement` so a host can pin a stricter mode
+	// without rewriting the runtime overlay.
+	//
+	// CRITICAL: only push when the toolkit *owns* the coordinator
+	// (i.e. `effectiveCoordinator === ownedCoordinator`). When the
+	// host passes a coordinator via the `coordinator` prop or shares
+	// one through `assessmentToolkitHostRuntimeContext`, that
+	// coordinator's policy inputs are the host's contract — overwriting
+	// them with our prop defaults would silently null out a host's
+	// pre-bound `AssessmentEntity`, etc. Hosts that share a coordinator
+	// drive policy inputs directly via `coord.updateAssessment(...)`.
+	$.user_effect(() => {
+		void assessment();
+		void currentItemRef();
+		void qtiEnforcement();
+		void tools();
+
+		const coord = $.get(effectiveCoordinator);
+
+		if (!coord) return;
+
+		// Host-owned coordinators are off-limits for this effect.
+		if (coord !== $.get(ownedCoordinator)) return;
+
+		untrack(() => {
+			// Apply order matters: `setQtiEnforcement` lands the override
+			// (or clears it) FIRST so `updateAssessment(...)`'s
+			// auto-promote path sees the final override and doesn't
+			// briefly resolve to "on" (when binding an assessment with
+			// `qtiEnforcement="off"`) or "off" (when clearing an
+			// assessment with `qtiEnforcement="on"`). Without this
+			// ordering we would emit a transient wrong-state policy
+			// event between the calls.
+			coord.setQtiEnforcement(resolveQtiEnforcementInput(qtiEnforcement(), tools()));
+
+			coord.updateAssessment(assessment());
+			coord.updateCurrentItemRef(currentItemRef());
+		});
+	});
+
 	$.user_effect(() => {
 		if (!$.get(effectiveCoordinator)) return;
 
@@ -730,7 +1057,11 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			if (!isInstrumentationProvider($.get(instrumentationProvider))) return;
 			if (!$.get(instrumentationProvider).isReady()) return;
 
-			const instrumentationEventName = eventName.startsWith("pie-") ? eventName : `pie-toolkit-${eventName}`;
+			// Telemetry event names are prefixed at the emit site in
+			// `ToolkitCoordinator.emitTelemetry`. See the JSDoc on that
+			// method for the namespace convention. No fallback here.
+			const instrumentationEventName = eventName;
+
 			const timestamp = new Date().toISOString();
 
 			const attributes = {
@@ -792,7 +1123,35 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			});
 
 			emit("section-ready", { sectionId: $.get(effectiveSectionId) });
+
+			// Mark section initialization complete. The reactive
+			// effect below joins this with `engineReadyStageEntered`
+			// so `interactive` only fires once the canonical
+			// predecessor is in. Direct emit here would race with
+			// `waitUntilReady()` and silently auto-skip
+			// `engine-ready` on fast hydration paths.
+			untrack(() => {
+				$.set(sectionInitialized, true);
+			});
 		}).catch((error) => {
+			untrack(() => {
+				// If `engine-ready` has not latched yet, mark it
+				// explicitly skipped so subscribers see a monotonic
+				// chain (`composed → engine-ready:skipped →
+				// interactive:failed`) instead of `engine-ready`
+				// silently disappearing from the canonical stream.
+				// `waitUntilReady()` is still in flight at this
+				// point; `engineReadyStageEntered` guards its
+				// resolver so a late success cannot regress past
+				// the recorded skip.
+				if (!$.get(engineReadyStageEntered)) {
+					$.set(engineReadyStageEntered, true);
+					stageTracker.enter("engine-ready", "skipped");
+				}
+
+				stageTracker.enter("interactive", "failed");
+			});
+
 			$.set(runtimeError, error, true);
 			sectionEngine.reportSectionError({ source: "section-runtime", error, timestamp: Date.now() });
 
@@ -955,6 +1314,122 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 		await sectionEngine.hydrate();
 	}
 
+	// Stage: `disposed` — wired on CE unmount. The four-stage retro
+	// dropped `attached` (it had no consumers); the toolkit no longer
+	// emits anything on mount and starts the canonical chain at
+	// `composed` once the section composition lands. `disposed` still
+	// fires on CE teardown so subscribers see a monotonic close-out.
+	$.user_effect(() => {
+		return () => {
+			untrack(() => {
+				if (stageTracker.getCurrent() !== null) {
+					stageTracker.enter("disposed");
+				}
+			});
+		};
+	});
+
+	// Cohort change handler: when `(sectionId, attemptId)` changes, emit
+	// `disposed` for the outgoing cohort and reset the tracker so the
+	// new cohort begins emitting from `composed` against the same DOM
+	// element. The boolean stage flags must reset in lockstep.
+	$.user_effect(() => {
+		const nextKey = `${sectionId()}|${attemptId()}`;
+
+		untrack(() => {
+			if (nextKey === $.get(lastStageCohortKey)) return;
+
+			if (stageTracker.getCurrent() !== null) {
+				stageTracker.enter("disposed");
+			}
+
+			stageTracker.reset({
+				sectionId: sectionId() || undefined,
+				attemptId: attemptId() || undefined
+			});
+
+			$.set(lastStageCohortKey, nextKey);
+			$.set(composedStageEntered, false);
+			$.set(engineReadyStageEntered, false);
+			$.set(interactiveStageEntered, false);
+			$.set(sectionInitialized, false);
+		});
+	});
+
+	// `interactive` fires once both canonical predecessors land:
+	// `engine-ready` (coordinator bring-up settled) and
+	// `sectionInitialized` (section composition + controller hydrated).
+	// Joining here prevents the race that would otherwise silently
+	// auto-skip `engine-ready` when the section initializer wins.
+	$.user_effect(() => {
+		const ready = $.get(engineReadyStageEntered) && $.get(sectionInitialized);
+
+		untrack(() => {
+			if (!ready) return;
+			if ($.get(interactiveStageEntered)) return;
+
+			$.set(interactiveStageEntered, true);
+			stageTracker.enter("interactive");
+		});
+	});
+
+	// Canonical M6 stage progression for the toolkit CE (post-retro:
+	// 4 stages). The tracker is idempotent and rejects backward
+	// transitions; gating with `composedStageEntered` keeps the emit
+	// order monotonic across asynchronous sources.
+	$.user_effect(() => {
+		const composed = $.get(compositionVersion) > 0 || $.get(compositionModel) !== null;
+
+		untrack(() => {
+			if (!$.get(composedStageEntered) && composed) {
+				$.set(composedStageEntered, true);
+				stageTracker.enter("composed");
+			}
+		});
+	});
+
+	// `engine-ready` resolves once `effectiveCoordinator.waitUntilReady()`
+	// settles — that promise covers state load, TTS bring-up, and provider
+	// initialization. Failures still flow through the framework-error bus;
+	// here we record the position with `failed` so subscribers see a
+	// monotonic stage chain even when the coordinator throws during
+	// readiness. Gated on `composedStageEntered` so the engine-ready
+	// emission cannot precede `composed` even if the coordinator
+	// resolves before composition lands (rare but possible during
+	// fast-hydration paths).
+	$.user_effect(() => {
+		if (!$.get(effectiveCoordinator)) return;
+		if (!$.get(composedStageEntered)) return;
+		if ($.get(engineReadyStageEntered)) return;
+
+		const coord = $.get(effectiveCoordinator);
+		let cancelled = false;
+
+		void coord.waitUntilReady().then(() => {
+			if (cancelled) return;
+
+			untrack(() => {
+				if ($.get(engineReadyStageEntered)) return;
+
+				$.set(engineReadyStageEntered, true);
+				stageTracker.enter("engine-ready");
+			});
+		}).catch(() => {
+			if (cancelled) return;
+
+			untrack(() => {
+				if ($.get(engineReadyStageEntered)) return;
+
+				$.set(engineReadyStageEntered, true);
+				stageTracker.enter("engine-ready", "failed");
+			});
+		});
+
+		return () => {
+			cancelled = true;
+		};
+	});
+
 	$.user_effect(() => {
 		return () => {
 			if (compositionEmitRaf !== null && typeof window !== "undefined") {
@@ -973,6 +1448,8 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 					error,
 					recoverable: true
 				});
+			}).finally(() => {
+				frameworkErrorBus.dispose();
 			});
 		};
 	});
@@ -1022,15 +1499,6 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			$.flush();
 		},
 
-		get view() {
-			return view();
-		},
-
-		set view($$value) {
-			view($$value);
-			$.flush();
-		},
-
 		get env() {
 			return env();
 		},
@@ -1067,6 +1535,15 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			$.flush();
 		},
 
+		get enabledTools() {
+			return enabledTools();
+		},
+
+		set enabledTools($$value) {
+			enabledTools($$value);
+			$.flush();
+		},
+
 		get toolRegistry() {
 			return toolRegistry();
 		},
@@ -1121,39 +1598,57 @@ export default function PieAssessmentToolkit($$anchor, $$props) {
 			$.flush();
 		},
 
-		get frameworkErrorHook() {
-			return frameworkErrorCallback();
+		get onFrameworkError() {
+			return onFrameworkError();
+		},
+
+		set onFrameworkError($$value) {
+			onFrameworkError($$value);
+			$.flush();
+		},
+
+		get errorRenderer() {
+			return errorRenderer();
 		},
 
-		set frameworkErrorHook($$value) {
-			frameworkErrorCallback($$value);
+		set errorRenderer($$value) {
+			errorRenderer($$value);
 			$.flush();
 		},
 
-		get onFrameworkError() {
-			return onFrameworkError();
+		get onStageChange() {
+			return onStageChange();
 		},
 
-		set onFrameworkError($$value) {
-			onFrameworkError($$value);
+		set onStageChange($$value) {
+			onStageChange($$value);
 			$.flush();
 		},
 
-		get onframeworkerror() {
-			return onframeworkerror();
+		get assessment() {
+			return assessment();
 		},
 
-		set onframeworkerror($$value) {
-			onframeworkerror($$value);
+		set assessment($$value) {
+			assessment($$value);
 			$.flush();
 		},
 
-		get errorRenderer() {
-			return errorRenderer();
+		get currentItemRef() {
+			return currentItemRef();
 		},
 
-		set errorRenderer($$value) {
-			errorRenderer($$value);
+		set currentItemRef($$value) {
+			currentItemRef($$value);
+			$.flush();
+		},
+
+		get qtiEnforcement() {
+			return qtiEnforcement();
+		},
+
+		set qtiEnforcement($$value) {
+			qtiEnforcement($$value);
 			$.flush();
 		},
 
@@ -1230,22 +1725,24 @@ __pieDefineSafely('pie-assessment-toolkit', $.create_custom_element(
 		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' },
 		toolConfigStrictness: { attribute: 'tool-config-strictness', type: 'String' },
 		tools: { attribute: 'tools', type: 'Object' },
+		enabledTools: { attribute: 'enabled-tools', type: 'String' },
 		toolRegistry: { type: 'Object' },
-		accessibility: { attribute: 'accessibility', type: 'Object' },
+		accessibility: { type: 'Object' },
 		player: { attribute: 'player', type: 'Object' },
 		playerType: { attribute: 'player-type', type: 'String' },
 		coordinator: { type: 'Object' },
 		createSectionController: { type: 'Object' },
-		frameworkErrorHook: { type: 'Object' },
 		onFrameworkError: { type: 'Object' },
-		onframeworkerror: { type: 'Object' },
 		errorRenderer: { type: 'Object' },
-		isolation: { attribute: 'isolation', type: 'String' }
+		onStageChange: { type: 'Object' },
+		assessment: { type: 'Object' },
+		currentItemRef: { type: 'Object' },
+		qtiEnforcement: { attribute: 'qti-enforcement', type: 'String' },
+		isolation: { type: 'Object' }
 	},
 	['default'],
 	[