@pie-players/pie-players-shared 0.3.29 → 0.3.31

package/dist/pie/stage-tracker.d.ts

@@ -0,0 +1,51 @@
+import { type Stage, type StageChangeDetail, type StageSourceCe, type StageStatus } from "./stages.js";
+/**
+ * Stage tracker primitive (M6).
+ *
+ * One tracker per CE instance per cohort. `enter(stage, status?)` is the
+ * only mutation; `reset()` rolls the cohort over (e.g. when
+ * `(sectionId, attemptId)` changes).
+ *
+ * The tracker enforces the locked invariants from
+ * `m6_ready_vocab_canonical_followup.plan.md` §3.1–§3.6:
+ * - Monotonic ordering across `STAGES`. Backward transitions inside one
+ *   cohort are rejected (dev) / warned-once (prod) so subscribers never
+ *   see a stage regress without an intervening `reset()`.
+ * - Per-CE applicability. The post-retro canonical list applies to
+ *   every CE shape; the `applicableStages` indirection is kept so a
+ *   future shape-specific stage can opt out without rewriting callers.
+ *   Non-applicable stages auto-emit `status: "skipped"` when an
+ *   applicable later stage is entered, so iteration order stays stable
+ *   across CE shapes.
+ * - One source for every emit. The injected `emit(detail)` function
+ *   drives DOM events, engine subscribers, and coordinator subscribers
+ *   from the same call site so no surface drifts.
+ *
+ * Failure semantics intentionally piggyback on the M3 framework-error
+ * contract: `enter(stage, "failed")` records the position; the
+ * framework error records the cause.
+ */
+export type CreateStageTrackerOptions = {
+    sourceCe: string;
+    sourceCeShape: StageSourceCe;
+    runtimeId: string;
+    sectionId?: string;
+    attemptId?: string;
+    emit: (detail: StageChangeDetail) => void;
+    now?: () => string;
+    onUnexpectedTransition?: (info: {
+        from: Stage | null;
+        to: Stage;
+        reason: "backward" | "duplicate";
+    }) => void;
+};
+export type StageTracker = {
+    enter: (stage: Stage, status?: StageStatus) => void;
+    reset: (next?: {
+        sectionId?: string;
+        attemptId?: string;
+    }) => void;
+    getCurrent: () => Stage | null;
+};
+export declare function createStageTracker(opts: CreateStageTrackerOptions): StageTracker;
+//# sourceMappingURL=stage-tracker.d.ts.map

package/dist/pie/stage-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-tracker.d.ts","sourceRoot":"","sources":["../../src/pie/stage-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,KAAK,EACV,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,MAAM,yBAAyB,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC/B,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;QACnB,EAAE,EAAE,KAAK,CAAC;QACV,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;KACjC,KAAK,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;IACpD,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACnE,UAAU,EAAE,MAAM,KAAK,GAAG,IAAI,CAAC;CAC/B,CAAC;AAqBF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,YAAY,CAkGhF"}

package/dist/pie/stage-tracker.js

@@ -0,0 +1,106 @@
+import { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
+let unexpectedTransitionWarned = false;
+function defaultUnexpectedTransitionLogger(info) {
+    if (unexpectedTransitionWarned)
+        return;
+    unexpectedTransitionWarned = true;
+    if (typeof console !== "undefined" && console.warn) {
+        console.warn(`[pie-stage-tracker] Unexpected ${info.reason} stage transition ` +
+            `from \`${info.from ?? "<none>"}\` to \`${info.to}\`. ` +
+            `Stage transitions are expected to be monotonic within a cohort; ` +
+            `call \`reset()\` when \`(sectionId, attemptId)\` changes.`);
+    }
+}
+export function createStageTracker(opts) {
+    const applicable = applicableStages(opts.sourceCeShape);
+    const applicableSet = new Set(applicable);
+    const now = opts.now ?? (() => new Date().toISOString());
+    const onUnexpected = opts.onUnexpectedTransition ?? defaultUnexpectedTransitionLogger;
+    let current = null;
+    let sectionId = opts.sectionId;
+    let attemptId = opts.attemptId;
+    const emitted = new Set();
+    function emitDetail(stage, status) {
+        opts.emit({
+            stage,
+            status,
+            runtimeId: opts.runtimeId,
+            sectionId,
+            attemptId,
+            timestamp: now(),
+            sourceCe: opts.sourceCe,
+        });
+    }
+    function fillSkippedBefore(stage) {
+        const targetIdx = stageOrdinal(stage);
+        const startIdx = current === null ? 0 : stageOrdinal(current) + 1;
+        for (let idx = startIdx; idx < targetIdx; idx += 1) {
+            const skipCandidate = STAGES[idx];
+            if (applicableSet.has(skipCandidate))
+                continue;
+            if (emitted.has(skipCandidate))
+                continue;
+            emitted.add(skipCandidate);
+            emitDetail(skipCandidate, "skipped");
+        }
+    }
+    function enter(stage, status = "entered") {
+        const nextOrdinal = stageOrdinal(stage);
+        const currentOrdinal = current === null ? -1 : stageOrdinal(current);
+        if (status === "entered") {
+            if (emitted.has(stage)) {
+                onUnexpected({ from: current, to: stage, reason: "duplicate" });
+                return;
+            }
+            if (nextOrdinal < currentOrdinal) {
+                onUnexpected({ from: current, to: stage, reason: "backward" });
+                return;
+            }
+            if (!applicableSet.has(stage)) {
+                // A non-applicable stage entered with `entered` is a programming
+                // error: the tracker auto-skips it when a later stage enters.
+                // Treat it as a `skipped` emission and continue.
+                if (emitted.has(stage))
+                    return;
+                emitted.add(stage);
+                emitDetail(stage, "skipped");
+                return;
+            }
+            fillSkippedBefore(stage);
+            emitted.add(stage);
+            current = stage;
+            emitDetail(stage, "entered");
+            return;
+        }
+        // `status === "failed"` records position; do not gate on monotonic
+        // ordering — failure can happen during any transition. Mark the stage
+        // as emitted so a subsequent `entered` for the same stage warns as a
+        // duplicate; downstream recovery should call `reset()` first.
+        if (status === "failed") {
+            fillSkippedBefore(stage);
+            emitted.add(stage);
+            current = stage;
+            emitDetail(stage, "failed");
+            return;
+        }
+        // `status === "skipped"` is reserved for the auto-fill path; explicit
+        // callers shouldn't pass it. Accept it idempotently for robustness.
+        if (emitted.has(stage))
+            return;
+        emitted.add(stage);
+        emitDetail(stage, "skipped");
+    }
+    function reset(next) {
+        current = null;
+        emitted.clear();
+        if (next) {
+            sectionId = next.sectionId;
+            attemptId = next.attemptId;
+        }
+    }
+    function getCurrent() {
+        return current;
+    }
+    return { enter, reset, getCurrent };
+}
+//# sourceMappingURL=stage-tracker.js.map

package/dist/pie/stage-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-tracker.js","sourceRoot":"","sources":["../../src/pie/stage-tracker.ts"],"names":[],"mappings":"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"}

package/dist/pie/stages.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Canonical stage vocabulary (M6 of the Coherent Options Surface track).
+ *
+ * One monotonic stage list is the unified replacement for the previous
+ * drift of `toolkit-ready`, `section-ready`, `section-controller-ready`,
+ * `interaction-ready`, `readiness-change`, and `ready` — all of which
+ * have been removed. Hosts ask the same question — "is this CE at
+ * stage ≥ X?" — across every `<pie-section-player-*>` and
+ * `<pie-assessment-toolkit>` element.
+ *
+ * The four-stage canonical list (`composed`, `engine-ready`, `interactive`,
+ * `disposed`) was finalized after the M5/M6 cumulative review confirmed
+ * zero internal or external consumers for the original `attached`,
+ * `runtime-bound`, and `ui-rendered` stages. The retro keeps the same
+ * shape for both the toolkit CE and the layout CEs — every CE iterates
+ * through the same list so subscribers don't need to special-case shape.
+ *
+ * Locked decisions (see `m6_ready_vocab_canonical_followup.plan.md`):
+ * - **A1** Stage machine model with one canonical event family.
+ * - **B1** "All items loaded" is reclassified as `pie-loading-complete`,
+ *   not a stage. (The previous `ready` DOM event alias was removed in
+ *   the broad architecture review compat sweep.)
+ * - **C1** `readiness.mode = "strict"` only delays the `interactive`
+ *   transition; every earlier stage fires identically across modes.
+ * - **D1** One DOM event family `pie-stage-change` with the stage in the
+ *   payload, mirroring the M3 `framework-error` idiom.
+ *
+ * Failure semantics deliberately stay in the M3 framework-error contract —
+ * `status: "failed"` records the position; the framework error records the
+ * cause.
+ */
+export declare const STAGES: readonly ["composed", "engine-ready", "interactive", "disposed"];
+export type Stage = (typeof STAGES)[number];
+export type StageStatus = "entered" | "skipped" | "failed";
+/**
+ * Subset of the source CE shape used by stage subscribers. Both shapes
+ * apply every canonical stage post-retro — the distinction stays in the
+ * type so future shape-specific stages (e.g. layout-only `paginated`) can
+ * be added without churn at the call sites.
+ */
+export type StageSourceCe = "toolkit" | "layout";
+/**
+ * Stages that apply to a given CE shape. Post-retro the toolkit and the
+ * layout CEs share the same canonical list; `applicableStages` is kept as
+ * an indirection so the tracker, telemetry, and tests don't have to be
+ * rewritten when a future stage diverges between shapes.
+ */
+export declare function applicableStages(_sourceCe: StageSourceCe): readonly Stage[];
+/**
+ * Strict ordering index used by the tracker to detect monotonic
+ * violations. `disposed` is last; `composed` is first.
+ */
+export declare function stageOrdinal(stage: Stage): number;
+export type StageChangeDetail = {
+    stage: Stage;
+    status: StageStatus;
+    /** Matches the existing `runtimeId` carried by toolkit telemetry. */
+    runtimeId: string;
+    sectionId?: string;
+    attemptId?: string;
+    /** ISO-8601, monotonic across one cohort. */
+    timestamp: string;
+    /** Tag name minus the `--version-<encoded>` suffix. */
+    sourceCe: string;
+};
+export type LoadingCompleteDetail = {
+    runtimeId: string;
+    sectionId: string;
+    attemptId?: string;
+    itemCount: number;
+    loadedCount: number;
+    timestamp: string;
+    sourceCe: string;
+};
+//# sourceMappingURL=stages.d.ts.map

package/dist/pie/stages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.d.ts","sourceRoot":"","sources":["../../src/pie/stages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,eAAO,MAAM,MAAM,kEAKR,CAAC;AAEZ,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,KAAK,EAAE,CAE3E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAMjD;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/pie/stages.js

@@ -0,0 +1,58 @@
+/**
+ * Canonical stage vocabulary (M6 of the Coherent Options Surface track).
+ *
+ * One monotonic stage list is the unified replacement for the previous
+ * drift of `toolkit-ready`, `section-ready`, `section-controller-ready`,
+ * `interaction-ready`, `readiness-change`, and `ready` — all of which
+ * have been removed. Hosts ask the same question — "is this CE at
+ * stage ≥ X?" — across every `<pie-section-player-*>` and
+ * `<pie-assessment-toolkit>` element.
+ *
+ * The four-stage canonical list (`composed`, `engine-ready`, `interactive`,
+ * `disposed`) was finalized after the M5/M6 cumulative review confirmed
+ * zero internal or external consumers for the original `attached`,
+ * `runtime-bound`, and `ui-rendered` stages. The retro keeps the same
+ * shape for both the toolkit CE and the layout CEs — every CE iterates
+ * through the same list so subscribers don't need to special-case shape.
+ *
+ * Locked decisions (see `m6_ready_vocab_canonical_followup.plan.md`):
+ * - **A1** Stage machine model with one canonical event family.
+ * - **B1** "All items loaded" is reclassified as `pie-loading-complete`,
+ *   not a stage. (The previous `ready` DOM event alias was removed in
+ *   the broad architecture review compat sweep.)
+ * - **C1** `readiness.mode = "strict"` only delays the `interactive`
+ *   transition; every earlier stage fires identically across modes.
+ * - **D1** One DOM event family `pie-stage-change` with the stage in the
+ *   payload, mirroring the M3 `framework-error` idiom.
+ *
+ * Failure semantics deliberately stay in the M3 framework-error contract —
+ * `status: "failed"` records the position; the framework error records the
+ * cause.
+ */
+export const STAGES = Object.freeze([
+    "composed",
+    "engine-ready",
+    "interactive",
+    "disposed",
+]);
+/**
+ * Stages that apply to a given CE shape. Post-retro the toolkit and the
+ * layout CEs share the same canonical list; `applicableStages` is kept as
+ * an indirection so the tracker, telemetry, and tests don't have to be
+ * rewritten when a future stage diverges between shapes.
+ */
+export function applicableStages(_sourceCe) {
+    return STAGES;
+}
+/**
+ * Strict ordering index used by the tracker to detect monotonic
+ * violations. `disposed` is last; `composed` is first.
+ */
+export function stageOrdinal(stage) {
+    const idx = STAGES.indexOf(stage);
+    if (idx === -1) {
+        throw new Error(`Unknown stage \`${stage}\``);
+    }
+    return idx;
+}
+//# sourceMappingURL=stages.js.map

package/dist/pie/stages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.js","sourceRoot":"","sources":["../../src/pie/stages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,UAAU;IACV,cAAc;IACd,aAAa;IACb,UAAU;CACD,CAAC,CAAC;AAcZ;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAwB;IACxD,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/pie/updates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../../src/pie/updates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAA2B,MAAM,mBAAmB,CAAC;AAGpF,OAAO,KAAK,EAAc,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA+JtE;;GAEG;AACH,eAAO,MAAM,uBAAuB,GACnC,IAAI,OAAO,EACX,MAAM,uBAAuB,KAC3B,IAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,QAAQ,MAAM,EACd,MAAM,uBAAuB,KAC3B,IAiBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,KAAK,GAAG,EACR,YAAY,OAAO,GAAG,QAAQ,KAC5B,IAKF,CAAC"}
+{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../../src/pie/updates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAY,MAAM,mBAAmB,CAAC;AAGrE,OAAO,KAAK,EAAc,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAiPtE;;GAEG;AACH,eAAO,MAAM,uBAAuB,GACnC,IAAI,OAAO,EACX,MAAM,uBAAuB,KAC3B,IAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,QAAQ,MAAM,EACd,MAAM,uBAAuB,KAC3B,IAiBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,KAAK,GAAG,EACR,YAAY,OAAO,GAAG,QAAQ,KAC5B,IAKF,CAAC"}

package/dist/pie/updates.js

@@ -10,6 +10,50 @@ import { defaultPieElementOptions } from "./types.js";
 import { findOrAddSession } from "./utils.js";
 // Create module-level logger (respects global debug flag - pass function for dynamic checking)
 const logger = createPieLogger("pie-updates", () => isGlobalDebugEnabled());
+const describeControllerShape = (controller) => {
+    if (!controller)
+        return "missing";
+    if (typeof controller === "function")
+        return "function";
+    if (typeof controller !== "object")
+        return typeof controller;
+    const keys = Object.keys(controller);
+    const defaultValue = controller.default;
+    const defaultKeys = defaultValue && typeof defaultValue === "object"
+        ? Object.keys(defaultValue)
+        : [];
+    return defaultKeys.length > 0
+        ? `object(keys=[${keys.join(",")}],defaultKeys=[${defaultKeys.join(",")}])`
+        : `object(keys=[${keys.join(",")}])`;
+};
+const resolveControllerModelFunction = (controller) => {
+    if (!controller)
+        return null;
+    if (typeof controller === "function") {
+        return controller;
+    }
+    if (typeof controller !== "object")
+        return null;
+    const direct = controller.model;
+    if (typeof direct === "function") {
+        return (model, sessionData, env, updateSession) => direct.call(controller, model, sessionData, env, updateSession);
+    }
+    const fromDefault = controller.default;
+    if (fromDefault && typeof fromDefault === "object") {
+        const nested = fromDefault.model;
+        if (typeof nested === "function") {
+            return (model, sessionData, env, updateSession) => nested.call(fromDefault, model, sessionData, env, updateSession);
+        }
+    }
+    return null;
+};
+const emitControllerError = (pieElement, detail) => {
+    pieElement.dispatchEvent(new CustomEvent("pie-controller-error", {
+        detail,
+        bubbles: true,
+        composed: true,
+    }));
+};
 /**
  * Helper function to apply controller to element
  * Extracted to eliminate duplication and ensure consistent controller invocation
@@ -28,12 +72,19 @@ const applyControllerToElement = async (element, model, elementSession, controll
         return Promise.resolve();
     };
     try {
-        const controllerResult = await controller.model(model, elementSession, env, updateSession);
+        const modelFunction = resolveControllerModelFunction(controller);
+        if (!modelFunction) {
+            throw new Error(`Controller contract mismatch: expected a model() function but received ${describeControllerShape(controller)}`);
+        }
+        const controllerResult = await modelFunction(model, elementSession, env, updateSession);
         // Merge controller result with id and element (like server-side PieControllerExecutor does)
+        const controllerResultObject = controllerResult && typeof controllerResult === "object"
+            ? controllerResult
+            : {};
         const filteredModel = {
             id: model.id,
             element: model.element,
-            ...controllerResult,
+            ...controllerResultObject,
         };
         logger.debug(`${logPrefix} ✅ Controller filtered model:`, {
             id: filteredModel.id,
@@ -91,7 +142,19 @@ const updateSinglePieElement = (pieElement, controllerLookupTag, options, logCon
             hasCorrectResponse: "correctResponse" in model,
         });
         applyControllerToElement(pieElement, model, elementSession, controller, env, `${logContext}(${controllerLookupTag}#${pieElement.id})`).catch((err) => {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            const isContractError = errorMessage.includes("Controller contract mismatch");
             logger.error(`${logContext} Controller failed for ${controllerLookupTag}#${pieElement.id}:`, err);
+            emitControllerError(pieElement, {
+                code: isContractError
+                    ? "PIE_CONTROLLER_CONTRACT_ERROR"
+                    : "PIE_CONTROLLER_RUNTIME_ERROR",
+                message: `${controllerLookupTag} controller failed while applying model for ${pieElement.id}. ${errorMessage}`,
+                elementName: controllerLookupTag,
+                elementId: pieElement.id,
+                controllerShape: describeControllerShape(controller),
+                cause: errorMessage,
+            });
             // Fall back to raw model on controller error
             pieElement.model = model;
             pieElement.session = elementSession;

package/dist/pie/updates.js.map

@@ -1 +1 @@
-{"version":3,"file":"updates.js","sourceRoot":"","sources":["../../src/pie/updates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"updates.js","sourceRoot":"","sources":["../../src/pie/updates.ts"],"names":[],"mappings":"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"}

package/dist/pie/use-resource-monitor.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-resource-monitor.svelte.d.ts","sourceRoot":"","sources":["../../src/pie/use-resource-monitor.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAKxD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,cAAc,EAAE,MAAM,WAAW,GAAG,IAAI,EACxC,eAAe,EAAE,MAAM,YAAY,EACnC,eAAe,EAAE,MAAM,OAAO,EAC9B,aAAa,GAAE,MAAqB;IAkInC;;OAEG;;IAKH;;OAEG;;;;;;;;IAKH;;OAEG;;EAKJ"}
+{"version":3,"file":"use-resource-monitor.svelte.d.ts","sourceRoot":"","sources":["../../src/pie/use-resource-monitor.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAKxD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,cAAc,EAAE,MAAM,WAAW,GAAG,IAAI,EACxC,eAAe,EAAE,MAAM,YAAY,EACnC,eAAe,EAAE,MAAM,OAAO,EAC9B,aAAa,GAAE,MAAqB;IA+InC;;OAEG;;IAKH;;OAEG;;;;;;;;IAKH;;OAEG;;EAKJ"}

package/dist/pie/use-resource-monitor.svelte.js

@@ -22,7 +22,7 @@
  * </script>
  * ```
  */
-import { onDestroy } from "svelte";
+import { onDestroy, untrack } from "svelte";
 import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
 import { DEFAULT_LOADER_CONFIG } from "../loader-config.js";
 import { createPieLogger } from "./logger.js";
@@ -45,85 +45,98 @@ export function useResourceMonitor(getHostElement, getLoaderConfig, getDebugEnab
     let activeHostElement = $state(null);
     let monitorConfigKey = $state("");
     let activeProvider = $state(undefined);
-    // Initialize resource monitor when conditions are met
+    // Initialize resource monitor when conditions are met.
+    //
+    // The body of this effect both reads and writes the local `$state`
+    // latches (`monitor`, `isInitialized`, `activeHostElement`,
+    // `monitorConfigKey`, `activeProvider`) — those latches exist so the
+    // public `instance`/`isActive` getters stay reactive for downstream
+    // consumers, but the same-effect read+write would otherwise trip
+    // `effect_update_depth_exceeded` on every host/config/provider change
+    // (observed in the assessment-player smoke flow during instrumentation
+    // provider rebinding). Per `.cursor/rules/svelte-subscription-safety.mdc`,
+    // we explicitly track only the input getters and run the body inside
+    // `untrack(...)` so the self-mutations don't re-trigger the effect.
     $effect(() => {
-        const hostElement = getHostElement();
-        const loaderConfig = getLoaderConfig();
-        const debugEnabled = getDebugEnabled();
-        const resolvedTrackPageActions = loaderConfig?.trackPageActions ?? false;
-        const resolvedMaxRetries = loaderConfig?.maxResourceRetries ??
-            DEFAULT_LOADER_CONFIG.maxResourceRetries;
-        const resolvedRetryDelay = loaderConfig?.resourceRetryDelay ??
-            DEFAULT_LOADER_CONFIG.resourceRetryDelay;
-        const resolvedInstrumentationProvider = isInstrumentationProvider(loaderConfig?.instrumentationProvider)
-            ? loaderConfig?.instrumentationProvider
-            : undefined;
-        if (debugEnabled &&
-            loaderConfig?.instrumentationProvider &&
-            !resolvedInstrumentationProvider) {
-            logger.warn(`Ignoring invalid instrumentation provider for ${componentName}; expected InstrumentationProvider contract`);
-        }
-        const nextConfigKey = JSON.stringify({
-            trackPageActions: resolvedTrackPageActions,
-            maxRetries: resolvedMaxRetries,
-            retryDelay: resolvedRetryDelay,
-            debugEnabled,
-        });
-        const providerChanged = activeProvider !== resolvedInstrumentationProvider;
-        const hostChanged = activeHostElement !== hostElement;
-        const configChanged = monitorConfigKey !== nextConfigKey;
-        const shouldReinitialize = hostElement && isInitialized && (hostChanged || configChanged || providerChanged);
-        // Clean up existing monitor if host element becomes null
-        if (!hostElement && monitor) {
-            logger.debug(`Host element removed, stopping resource monitor for ${componentName}`);
-            monitor.stop();
-            monitor = null;
-            isInitialized = false;
-            activeHostElement = null;
-            activeProvider = undefined;
-            monitorConfigKey = "";
-            return;
-        }
-        if (shouldReinitialize && monitor) {
-            logger.debug(`Reinitializing resource monitor for ${componentName}`, {
-                hostChanged,
-                configChanged,
-                providerChanged,
-            });
-            monitor.stop();
-            monitor = null;
-            isInitialized = false;
-        }
-        // Initialize if we have a host element (retry logic works independently of trackPageActions)
-        if (hostElement && !isInitialized) {
-            logger.debug(`Initializing resource monitor for ${componentName}`, {
+        void getHostElement();
+        void getLoaderConfig();
+        void getDebugEnabled();
+        untrack(() => {
+            const hostElement = getHostElement();
+            const loaderConfig = getLoaderConfig();
+            const debugEnabled = getDebugEnabled();
+            const resolvedTrackPageActions = loaderConfig?.trackPageActions ?? false;
+            const resolvedMaxRetries = loaderConfig?.maxResourceRetries ??
+                DEFAULT_LOADER_CONFIG.maxResourceRetries;
+            const resolvedRetryDelay = loaderConfig?.resourceRetryDelay ??
+                DEFAULT_LOADER_CONFIG.resourceRetryDelay;
+            const resolvedInstrumentationProvider = isInstrumentationProvider(loaderConfig?.instrumentationProvider)
+                ? loaderConfig?.instrumentationProvider
+                : undefined;
+            if (debugEnabled &&
+                loaderConfig?.instrumentationProvider &&
+                !resolvedInstrumentationProvider) {
+                logger.warn(`Ignoring invalid instrumentation provider for ${componentName}; expected InstrumentationProvider contract`);
+            }
+            const nextConfigKey = JSON.stringify({
                 trackPageActions: resolvedTrackPageActions,
                 maxRetries: resolvedMaxRetries,
                 retryDelay: resolvedRetryDelay,
-                hasCustomProvider: !!resolvedInstrumentationProvider,
-                hasContainer: !!hostElement,
+                debugEnabled,
             });
-            // Create and start resource monitor with config from loaderConfig
-            monitor = new ResourceMonitor({
-                trackPageActions: resolvedTrackPageActions,
-                instrumentationProvider: resolvedInstrumentationProvider,
-                maxRetries: resolvedMaxRetries,
-                initialRetryDelay: resolvedRetryDelay,
-                maxRetryDelay: DEFAULT_MAX_RETRY_DELAY,
-                debug: debugEnabled,
-            });
-            monitor.start(hostElement);
-            isInitialized = true;
-            activeHostElement = hostElement;
-            activeProvider = resolvedInstrumentationProvider;
-            monitorConfigKey = nextConfigKey;
-            logger.info(`✅ Resource monitoring enabled for ${componentName}` +
-                (resolvedTrackPageActions
-                    ? resolvedInstrumentationProvider
-                        ? " (with custom instrumentation provider)"
-                        : " (with New Relic tracking)"
-                    : " (retry only)"));
-        }
+            const providerChanged = activeProvider !== resolvedInstrumentationProvider;
+            const hostChanged = activeHostElement !== hostElement;
+            const configChanged = monitorConfigKey !== nextConfigKey;
+            const shouldReinitialize = hostElement && isInitialized && (hostChanged || configChanged || providerChanged);
+            if (!hostElement && monitor) {
+                logger.debug(`Host element removed, stopping resource monitor for ${componentName}`);
+                monitor.stop();
+                monitor = null;
+                isInitialized = false;
+                activeHostElement = null;
+                activeProvider = undefined;
+                monitorConfigKey = "";
+                return;
+            }
+            if (shouldReinitialize && monitor) {
+                logger.debug(`Reinitializing resource monitor for ${componentName}`, {
+                    hostChanged,
+                    configChanged,
+                    providerChanged,
+                });
+                monitor.stop();
+                monitor = null;
+                isInitialized = false;
+            }
+            if (hostElement && !isInitialized) {
+                logger.debug(`Initializing resource monitor for ${componentName}`, {
+                    trackPageActions: resolvedTrackPageActions,
+                    maxRetries: resolvedMaxRetries,
+                    retryDelay: resolvedRetryDelay,
+                    hasCustomProvider: !!resolvedInstrumentationProvider,
+                    hasContainer: !!hostElement,
+                });
+                monitor = new ResourceMonitor({
+                    trackPageActions: resolvedTrackPageActions,
+                    instrumentationProvider: resolvedInstrumentationProvider,
+                    maxRetries: resolvedMaxRetries,
+                    initialRetryDelay: resolvedRetryDelay,
+                    maxRetryDelay: DEFAULT_MAX_RETRY_DELAY,
+                    debug: debugEnabled,
+                });
+                monitor.start(hostElement);
+                isInitialized = true;
+                activeHostElement = hostElement;
+                activeProvider = resolvedInstrumentationProvider;
+                monitorConfigKey = nextConfigKey;
+                logger.info(`✅ Resource monitoring enabled for ${componentName}` +
+                    (resolvedTrackPageActions
+                        ? resolvedInstrumentationProvider
+                            ? " (with custom instrumentation provider)"
+                            : " (with New Relic tracking)"
+                        : " (retry only)"));
+            }
+        });
     });
     // Cleanup on component destroy
     onDestroy(() => {