@pie-players/pie-assessment-toolkit 0.3.29 → 0.3.31

package/dist/runtime/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/runtime/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,YAAY,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAWrF,OAAO,EACN,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,GAC3B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACN,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,4BAA4B,GACjC,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACN,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC1B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACN,0BAA0B,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GAChC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACN,2BAA2B,EAC3B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,GACxB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACN,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC3B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,YAAY,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAE7E,OAAO,EACN,SAAS,EACT,YAAY,EACZ,UAAU,EACV,KAAK,SAAS,GACd,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EACX,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACtB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACX,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EACN,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,gCAAgC,EAChC,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACN,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/runtime/internal.js

@@ -0,0 +1,46 @@
+/**
+ * Section runtime engine — **internal** entry point (M7 — Variant C).
+ *
+ * Re-exports the layered core + adapter surface for advanced hosts that
+ * want to construct or inspect engines directly, and for the engine's
+ * own tests / benchmarks.
+ *
+ * **Stability posture.** This module is **not** part of the stable
+ * public API. Symbols here are subject to change between minor versions
+ * with only a changeset note. Hosts that need long-term stability
+ * should depend on the facade (`SectionRuntimeEngine` exported from
+ * `./runtime/engine`) instead.
+ *
+ * The split is intentional:
+ *   - `./runtime/engine` (PR 3) — narrow, stable facade for common
+ *     host wiring.
+ *   - `./runtime/internal` — wide, evolving surface for the kernel,
+ *     adapter tests, and any host that wants to reach past the facade.
+ *
+ * The `runtime/engine` and `runtime/internal` package `exports` map
+ * entries are added in PR 3 alongside the facade refactor.
+ */
+export { SectionEngineAdapter } from "./adapter/SectionEngineAdapter.js";
+// `FrameworkErrorBus` is the package-internal multi-subscriber bus the
+// engine adapter consumes via the `FrameworkErrorReporter` write port.
+// It is re-exported here (alongside the read/write ports) so advanced
+// hosts that construct an engine instance directly — including the M7
+// PR 5 section-player kernel — can wire a bus without reaching into a
+// deep relative path. The class itself remains "package-internal" in
+// posture (the doc comment on the class explains why); this export is
+// a deliberate, advanced-host escape hatch on the evolving
+// `runtime/internal` surface, never on the stable facade.
+export { FrameworkErrorBus, } from "../services/framework-error-bus.js";
+export { createCoordinatorBridge, } from "./adapter/coordinator-bridge.js";
+export { createDomEventBridge, } from "./adapter/dom-event-bridge.js";
+export { createFrameworkErrorBridge, } from "./adapter/framework-error-bridge.js";
+export { createInstrumentationBridge, } from "./adapter/instrumentation-bridge.js";
+export { createSubscriberFanout, } from "./adapter/subscriber-fanout.js";
+export { SectionEngineCore } from "./core/SectionEngineCore.js";
+export { cohortKey, cohortsEqual, makeCohort, } from "./core/cohort.js";
+export { createInitialEngineState } from "./core/engine-state.js";
+export { phaseToStage } from "./core/engine-stage-derivation.js";
+export { DEFAULT_ASSESSMENT_ID, DEFAULT_ENV, DEFAULT_ISOLATION, DEFAULT_LAZY_INIT, DEFAULT_PLAYER_TYPE, resolveOnFrameworkError, resolveRuntime, resolveSectionEngineRuntimeState, resolveToolsConfig, } from "./core/engine-resolver.js";
+export { createReadinessDetail, resolveReadinessPhase, } from "./core/engine-readiness.js";
+export { transition } from "./core/engine-transition.js";
+//# sourceMappingURL=internal.js.map

package/dist/runtime/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/runtime/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAGzE,uEAAuE;AACvE,uEAAuE;AACvE,sEAAsE;AACtE,sEAAsE;AACtE,sEAAsE;AACtE,qEAAqE;AACrE,sEAAsE;AACtE,2DAA2D;AAC3D,0DAA0D;AAC1D,OAAO,EACN,iBAAiB,GAIjB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACN,uBAAuB,GAKvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACN,oBAAoB,GAGpB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACN,0BAA0B,GAG1B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACN,2BAA2B,GAI3B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACN,sBAAsB,GAGtB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACN,SAAS,EACT,YAAY,EACZ,UAAU,GAEV,MAAM,kBAAkB,CAAC;AAa1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EACN,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,gCAAgC,EAChC,kBAAkB,GAQlB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACN,qBAAqB,EACrB,qBAAqB,GACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/runtime/runtime-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stable runtime-instance id generator.
+ *
+ * Produces a per-runtime id used to scope DOM attribute names and
+ * telemetry tags. Single export by design — not a "guards" module.
+ */
+export declare function createRuntimeId(prefix?: string): string;
+//# sourceMappingURL=runtime-id.d.ts.map

package/dist/runtime/runtime-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-id.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAY,GAAG,MAAM,CAE1D"}

package/dist/runtime/runtime-id.js

@@ -0,0 +1,10 @@
+/**
+ * Stable runtime-instance id generator.
+ *
+ * Produces a per-runtime id used to scope DOM attribute names and
+ * telemetry tags. Single export by design — not a "guards" module.
+ */
+export function createRuntimeId(prefix = "runtime") {
+    return `${prefix}-${Math.random().toString(16).slice(2)}-${Date.now()}`;
+}
+//# sourceMappingURL=runtime-id.js.map

package/dist/runtime/runtime-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-id.js","sourceRoot":"","sources":["../../src/runtime/runtime-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAM,GAAG,SAAS;IACjD,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AACzE,CAAC"}

package/dist/runtime/section-runtime-engine-host-context.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Cross-Custom-Element context for the section runtime engine (M7 PR 6).
+ *
+ * The toolkit CE renders inside its own Shadow DOM, so Svelte's native
+ * `setContext`/`getContext` (used by `engine-context.ts`) cannot bridge
+ * the kernel-provided engine reference to the toolkit's component tree.
+ * This module exposes a `@pie-players/pie-context` based context that
+ * does cross the CE boundary via DOM events:
+ *
+ *   - The kernel (`SectionPlayerLayoutKernel.svelte`) installs a
+ *     `ContextProvider` for `sectionRuntimeEngineHostContext` on its
+ *     `host` (the layout CE). The provider value carries the engine
+ *     reference owned by that kernel mount.
+ *   - The toolkit CE installs a `ContextConsumer` on its own host. When
+ *     wrapped by a section player layout, the consumer resolves to the
+ *     kernel's engine and the toolkit treats it as the active engine
+ *     for legacy controller-side calls (`register`, `handleContent*`,
+ *     `initialize`, etc.) and for FSM input dispatch (e.g.
+ *     `framework-error`). When standalone, no upstream provider
+ *     responds and the toolkit keeps using its locally-constructed
+ *     engine.
+ *
+ * The two engine-context surfaces (`SECTION_RUNTIME_ENGINE_KEY` and
+ * this one) are deliberately distinct:
+ *   - `SECTION_RUNTIME_ENGINE_KEY` (Svelte context) stays scoped to a
+ *     single component tree (kernel + descendants in the same shadow
+ *     root) and is the right hook for in-tree consumers.
+ *   - `sectionRuntimeEngineHostContext` (DOM-event context) is the
+ *     bridge for cross-CE consumers and only carries data that is
+ *     safe to share across CE boundaries (a stable engine reference).
+ *
+ * **Stability.** This export is part of the stable runtime/engine
+ * surface; the symbol identity and value shape are part of the
+ * cross-CE contract. Renaming or replacing the symbol is a major
+ * breaking change. Adding optional fields to the value shape is
+ * allowed; required fields are not.
+ */
+import type { SectionRuntimeEngine } from "./SectionRuntimeEngine.js";
+/**
+ * Value shape published by the kernel and consumed by the wrapped
+ * toolkit CE. Carries only the engine reference today; if more
+ * cross-CE shared runtime state is needed later, fields can be added
+ * here additively.
+ */
+export interface SectionRuntimeEngineHostContextValue {
+    engine: SectionRuntimeEngine;
+}
+/**
+ * `pie-context` context key for the cross-CE engine bridge. Uses a
+ * `Symbol.for(...)` registry key so providers and consumers in
+ * separately-bundled CEs see the same identity.
+ */
+export declare const sectionRuntimeEngineHostContext: {
+    __context__: SectionRuntimeEngineHostContextValue;
+};
+export type SectionRuntimeEngineHostContextListener = (value: SectionRuntimeEngineHostContextValue) => void;
+/**
+ * Connect a DOM host to the cross-CE engine context with the same
+ * provider-retry semantics used elsewhere in the toolkit (initial
+ * synchronous request + `context-provider` re-request + 50 ms polling
+ * fallback up to 200 attempts ≈ 10 s).
+ *
+ * The retry mirrors the existing
+ * `connectAssessmentToolkitHostRuntimeContext` infrastructure so the
+ * timing characteristics of cross-CE handshakes stay consistent across
+ * the toolkit's contexts.
+ *
+ * Returns a cleanup function that disconnects the consumer and clears
+ * the retry interval. Standalone toolkits naturally exhaust the retry
+ * window without ever resolving and continue using their local
+ * engine — that is by design and is not an error.
+ */
+export declare function connectSectionRuntimeEngineHostContext(host: HTMLElement, onValue: SectionRuntimeEngineHostContextListener): () => void;
+//# sourceMappingURL=section-runtime-engine-host-context.d.ts.map

package/dist/runtime/section-runtime-engine-host-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-runtime-engine-host-context.d.ts","sourceRoot":"","sources":["../../src/runtime/section-runtime-engine-host-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,oCAAoC;IACpD,MAAM,EAAE,oBAAoB,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,+BAA+B;;CAG1C,CAAC;AAEH,MAAM,MAAM,uCAAuC,GAAG,CACrD,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAC;AAMV;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sCAAsC,CACrD,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,uCAAuC,GAC9C,MAAM,IAAI,CAuCZ"}

package/dist/runtime/section-runtime-engine-host-context.js

@@ -0,0 +1,96 @@
+/**
+ * Cross-Custom-Element context for the section runtime engine (M7 PR 6).
+ *
+ * The toolkit CE renders inside its own Shadow DOM, so Svelte's native
+ * `setContext`/`getContext` (used by `engine-context.ts`) cannot bridge
+ * the kernel-provided engine reference to the toolkit's component tree.
+ * This module exposes a `@pie-players/pie-context` based context that
+ * does cross the CE boundary via DOM events:
+ *
+ *   - The kernel (`SectionPlayerLayoutKernel.svelte`) installs a
+ *     `ContextProvider` for `sectionRuntimeEngineHostContext` on its
+ *     `host` (the layout CE). The provider value carries the engine
+ *     reference owned by that kernel mount.
+ *   - The toolkit CE installs a `ContextConsumer` on its own host. When
+ *     wrapped by a section player layout, the consumer resolves to the
+ *     kernel's engine and the toolkit treats it as the active engine
+ *     for legacy controller-side calls (`register`, `handleContent*`,
+ *     `initialize`, etc.) and for FSM input dispatch (e.g.
+ *     `framework-error`). When standalone, no upstream provider
+ *     responds and the toolkit keeps using its locally-constructed
+ *     engine.
+ *
+ * The two engine-context surfaces (`SECTION_RUNTIME_ENGINE_KEY` and
+ * this one) are deliberately distinct:
+ *   - `SECTION_RUNTIME_ENGINE_KEY` (Svelte context) stays scoped to a
+ *     single component tree (kernel + descendants in the same shadow
+ *     root) and is the right hook for in-tree consumers.
+ *   - `sectionRuntimeEngineHostContext` (DOM-event context) is the
+ *     bridge for cross-CE consumers and only carries data that is
+ *     safe to share across CE boundaries (a stable engine reference).
+ *
+ * **Stability.** This export is part of the stable runtime/engine
+ * surface; the symbol identity and value shape are part of the
+ * cross-CE contract. Renaming or replacing the symbol is a major
+ * breaking change. Adding optional fields to the value shape is
+ * allowed; required fields are not.
+ */
+import { ContextConsumer, createContext, } from "@pie-players/pie-context";
+/**
+ * `pie-context` context key for the cross-CE engine bridge. Uses a
+ * `Symbol.for(...)` registry key so providers and consumers in
+ * separately-bundled CEs see the same identity.
+ */
+export const sectionRuntimeEngineHostContext = createContext(Symbol.for("pie.sectionRuntimeEngineHostContext"));
+/**
+ * Connect a DOM host to the cross-CE engine context with the same
+ * provider-retry semantics used elsewhere in the toolkit (initial
+ * synchronous request + `context-provider` re-request + 50 ms polling
+ * fallback up to 200 attempts ≈ 10 s).
+ *
+ * The retry mirrors the existing
+ * `connectAssessmentToolkitHostRuntimeContext` infrastructure so the
+ * timing characteristics of cross-CE handshakes stay consistent across
+ * the toolkit's contexts.
+ *
+ * Returns a cleanup function that disconnects the consumer and clears
+ * the retry interval. Standalone toolkits naturally exhaust the retry
+ * window without ever resolving and continue using their local
+ * engine — that is by design and is not an error.
+ */
+export function connectSectionRuntimeEngineHostContext(host, onValue) {
+    let hasValue = false;
+    const consumer = new ContextConsumer(host, {
+        context: sectionRuntimeEngineHostContext,
+        subscribe: true,
+        onValue: (value) => {
+            hasValue = true;
+            onValue(value);
+        },
+    });
+    consumer.connect();
+    const onContextProvider = (event) => {
+        if (event.context !==
+            sectionRuntimeEngineHostContext) {
+            return;
+        }
+        consumer.requestValue();
+    };
+    host.addEventListener("context-provider", onContextProvider);
+    let attempts = 0;
+    const maxAttempts = 200;
+    const retryTimer = globalThis.setInterval(() => {
+        if (hasValue || attempts >= maxAttempts) {
+            globalThis.clearInterval(retryTimer);
+            return;
+        }
+        attempts += 1;
+        consumer.requestValue();
+    }, 50);
+    return () => {
+        globalThis.clearInterval(retryTimer);
+        host.removeEventListener("context-provider", onContextProvider);
+        consumer.disconnect();
+    };
+}
+//# sourceMappingURL=section-runtime-engine-host-context.js.map

package/dist/runtime/section-runtime-engine-host-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-runtime-engine-host-context.js","sourceRoot":"","sources":["../../src/runtime/section-runtime-engine-host-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACN,eAAe,EACf,aAAa,GAEb,MAAM,0BAA0B,CAAC;AAalC;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAC3C,aAAa,CACZ,MAAM,CAAC,GAAG,CAAC,qCAAqC,CAAC,CACjD,CAAC;AAUH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sCAAsC,CACrD,IAAiB,EACjB,OAAgD;IAEhD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,IAAI,EAAE;QAC1C,OAAO,EAAE,+BAA+B;QACxC,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAClB,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC;KACD,CAAC,CAAC;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC;IAEnB,MAAM,iBAAiB,GAAG,CAAC,KAA+B,EAAE,EAAE;QAC7D,IACC,KAAK,CAAC,OAAO;YACZ,+BAA6D,EAC7D,CAAC;YACF,OAAO;QACR,CAAC;QACD,QAAQ,CAAC,YAAY,EAAE,CAAC;IACzB,CAAC,CAAC;IACF,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;IAE7D,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,WAAW,GAAG,GAAG,CAAC;IACxB,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,EAAE;QAC9C,IAAI,QAAQ,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;YACzC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YACrC,OAAO;QACR,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;QACd,QAAQ,CAAC,YAAY,EAAE,CAAC;IACzB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,GAAG,EAAE;QACX,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;QAChE,QAAQ,CAAC,UAAU,EAAE,CAAC;IACvB,CAAC,CAAC;AACH,CAAC"}

package/dist/runtime/stage-emit-gate.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Stage-emit suppression gate (M7 PR 6).
+ *
+ * `PieAssessmentToolkit.svelte` builds a `createStageTracker(...)` whose
+ * `emit` callback dispatches the toolkit CE's `pie-stage-change` DOM
+ * event and invokes the runtime-tier `onStageChange` callback. PR 6
+ * introduces the wrapped/standalone branch:
+ *
+ *   - **Standalone** (no upstream `SectionRuntimeEngine` provider on
+ *     the layout CE host): emit + `onStageChange` fire as before.
+ *   - **Wrapped** (kernel publishes its engine via
+ *     `sectionRuntimeEngineHostContext` and the toolkit consumer
+ *     resolves it): emit + `onStageChange` are suppressed on the
+ *     toolkit CE, because the kernel's engine already emits the
+ *     canonical `pie-stage-change` chain on the layout CE host and
+ *     invokes the runtime-tier callback. Without suppression the
+ *     toolkit CE would also dispatch its own event, which bubbles
+ *     through `composed: true` to the layout CE host and produces a
+ *     duplicate emission for outside listeners.
+ *
+ * The internal `stageTracker` latch state advances **before** this
+ * helper is reached (the latch is updated inside
+ * `createStageTracker.enter` prior to `opts.emit(...)`), so suppression
+ * here only short-circuits the externally-visible side effects. The
+ * toolkit's own readiness path (`waitUntilReady` / `engine-ready` /
+ * `interactive`) keeps working in standalone mode and degenerates into
+ * a series of suppressed emits in wrapped mode without losing any
+ * latch transitions.
+ *
+ * Splitting this helper out of the inline `emit:` closure in
+ * `PieAssessmentToolkit.svelte` lets us pin the suppression branch in a
+ * unit test without mounting the toolkit CE — see
+ * `tests/runtime/stage-emit-gate.test.ts`. The closure in the toolkit
+ * passes thunks for `isSuppressed` and `getOnStageChange` so the live
+ * Svelte reactive variables (`upstreamEngine`, `onStageChange`) are
+ * read at emit time, not captured at construction time. This keeps the
+ * pre-PR-6 behavior of always reading the latest `onStageChange` prop
+ * value (cohort change, host swap, etc.) intact.
+ *
+ * NOT a public surface: this helper is internal to the toolkit and is
+ * not exported from `runtime/engine.ts`. It only exists to make the
+ * gate testable.
+ */
+import type { StageChangeDetail } from "@pie-players/pie-players-shared/pie";
+export type StageOnChangeHandler = (detail: StageChangeDetail) => void;
+export interface StageEmitGateContext {
+    /**
+     * Reads the current suppression flag. Implemented as a thunk so
+     * the reactive Svelte `$state(upstreamEngine)` is read at emit
+     * time. Return `true` to suppress; `false` to fire.
+     */
+    isSuppressed: () => boolean;
+    /**
+     * Dispatches the `pie-stage-change` DOM event on the toolkit's
+     * CE host. In `PieAssessmentToolkit.svelte` this is the
+     * Svelte-generated `emit("pie-stage-change", detail)` helper.
+     */
+    dispatchDomEvent: (detail: StageChangeDetail) => void;
+    /**
+     * Reads the current `onStageChange` runtime-tier callback. Thunk
+     * so the latest reassigned handler is invoked, not whichever
+     * handler was current at construction time.
+     */
+    getOnStageChange: () => StageOnChangeHandler | null | undefined;
+    /**
+     * Optional logger for handler errors. Defaults to `console.error`
+     * with the same prefix the toolkit used pre-PR-6 so test output
+     * matches production logs.
+     */
+    logHandlerError?: (error: unknown) => void;
+}
+/**
+ * Run the toolkit's stage emit pipeline with the suppression gate
+ * applied.
+ *
+ *   - When `isSuppressed()` returns `true`, the helper returns
+ *     immediately with neither side effect.
+ *   - Otherwise it dispatches the `pie-stage-change` DOM event first,
+ *     then invokes `onStageChange(detail)` (preserving the
+ *     "DOM-event-then-callback" ordering pre-PR-6 consumers depend
+ *     on).
+ *   - A throwing `onStageChange` handler does not interrupt the DOM
+ *     event (already fired) and does not propagate up to
+ *     `stageTracker.enter` (latch state already advanced); the error
+ *     is logged and swallowed, matching pre-PR-6 behavior.
+ *
+ * Returns `true` if the emit pipeline ran (i.e. it was not
+ * suppressed); `false` if it was suppressed. Tests use the return
+ * value to assert the gate's decision in isolation from the side
+ * effects.
+ */
+export declare function runStageEmitWithSuppression(context: StageEmitGateContext, detail: StageChangeDetail): boolean;
+//# sourceMappingURL=stage-emit-gate.d.ts.map

package/dist/runtime/stage-emit-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-emit-gate.d.ts","sourceRoot":"","sources":["../../src/runtime/stage-emit-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEvE,MAAM,WAAW,oBAAoB;IACpC;;;;OAIG;IACH,YAAY,EAAE,MAAM,OAAO,CAAC;IAE5B;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAEtD;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,oBAAoB,GAAG,IAAI,GAAG,SAAS,CAAC;IAEhE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,iBAAiB,GACvB,OAAO,CAcT"}

package/dist/runtime/stage-emit-gate.js

@@ -0,0 +1,83 @@
+/**
+ * Stage-emit suppression gate (M7 PR 6).
+ *
+ * `PieAssessmentToolkit.svelte` builds a `createStageTracker(...)` whose
+ * `emit` callback dispatches the toolkit CE's `pie-stage-change` DOM
+ * event and invokes the runtime-tier `onStageChange` callback. PR 6
+ * introduces the wrapped/standalone branch:
+ *
+ *   - **Standalone** (no upstream `SectionRuntimeEngine` provider on
+ *     the layout CE host): emit + `onStageChange` fire as before.
+ *   - **Wrapped** (kernel publishes its engine via
+ *     `sectionRuntimeEngineHostContext` and the toolkit consumer
+ *     resolves it): emit + `onStageChange` are suppressed on the
+ *     toolkit CE, because the kernel's engine already emits the
+ *     canonical `pie-stage-change` chain on the layout CE host and
+ *     invokes the runtime-tier callback. Without suppression the
+ *     toolkit CE would also dispatch its own event, which bubbles
+ *     through `composed: true` to the layout CE host and produces a
+ *     duplicate emission for outside listeners.
+ *
+ * The internal `stageTracker` latch state advances **before** this
+ * helper is reached (the latch is updated inside
+ * `createStageTracker.enter` prior to `opts.emit(...)`), so suppression
+ * here only short-circuits the externally-visible side effects. The
+ * toolkit's own readiness path (`waitUntilReady` / `engine-ready` /
+ * `interactive`) keeps working in standalone mode and degenerates into
+ * a series of suppressed emits in wrapped mode without losing any
+ * latch transitions.
+ *
+ * Splitting this helper out of the inline `emit:` closure in
+ * `PieAssessmentToolkit.svelte` lets us pin the suppression branch in a
+ * unit test without mounting the toolkit CE — see
+ * `tests/runtime/stage-emit-gate.test.ts`. The closure in the toolkit
+ * passes thunks for `isSuppressed` and `getOnStageChange` so the live
+ * Svelte reactive variables (`upstreamEngine`, `onStageChange`) are
+ * read at emit time, not captured at construction time. This keeps the
+ * pre-PR-6 behavior of always reading the latest `onStageChange` prop
+ * value (cohort change, host swap, etc.) intact.
+ *
+ * NOT a public surface: this helper is internal to the toolkit and is
+ * not exported from `runtime/engine.ts`. It only exists to make the
+ * gate testable.
+ */
+const defaultLogHandlerError = (error) => {
+    console.error("[pie-assessment-toolkit] onStageChange handler threw", error);
+};
+/**
+ * Run the toolkit's stage emit pipeline with the suppression gate
+ * applied.
+ *
+ *   - When `isSuppressed()` returns `true`, the helper returns
+ *     immediately with neither side effect.
+ *   - Otherwise it dispatches the `pie-stage-change` DOM event first,
+ *     then invokes `onStageChange(detail)` (preserving the
+ *     "DOM-event-then-callback" ordering pre-PR-6 consumers depend
+ *     on).
+ *   - A throwing `onStageChange` handler does not interrupt the DOM
+ *     event (already fired) and does not propagate up to
+ *     `stageTracker.enter` (latch state already advanced); the error
+ *     is logged and swallowed, matching pre-PR-6 behavior.
+ *
+ * Returns `true` if the emit pipeline ran (i.e. it was not
+ * suppressed); `false` if it was suppressed. Tests use the return
+ * value to assert the gate's decision in isolation from the side
+ * effects.
+ */
+export function runStageEmitWithSuppression(context, detail) {
+    if (context.isSuppressed()) {
+        return false;
+    }
+    context.dispatchDomEvent(detail);
+    const handler = context.getOnStageChange();
+    if (handler) {
+        try {
+            handler(detail);
+        }
+        catch (error) {
+            (context.logHandlerError ?? defaultLogHandlerError)(error);
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=stage-emit-gate.js.map

package/dist/runtime/stage-emit-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-emit-gate.js","sourceRoot":"","sources":["../../src/runtime/stage-emit-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAoCH,MAAM,sBAAsB,GAAG,CAAC,KAAc,EAAQ,EAAE;IACvD,OAAO,CAAC,KAAK,CAAC,sDAAsD,EAAE,KAAK,CAAC,CAAC;AAC9E,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,2BAA2B,CAC1C,OAA6B,EAC7B,MAAyB;IAEzB,IAAI,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAC3C,IAAI,OAAO,EAAE,CAAC;QACb,IAAI,CAAC;YACJ,OAAO,CAAC,MAAM,CAAC,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,CAAC,OAAO,CAAC,eAAe,IAAI,sBAAsB,CAAC,CAAC,KAAK,CAAC,CAAC;QAC5D,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/services/SSMLExtractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SSMLExtractor.d.ts","sourceRoot":"","sources":["../../src/services/SSMLExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACX,oBAAoB,EACpB,YAAY,EAEZ,MAAM,uCAAuC,CAAC;AAU/C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,aAAa,EAAE,YAAY,CAAC;CAC5B;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,cAAc,CAAK;IAE3B;;;;;OAKG;IACH,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IA6D7D;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAmGzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGb"}
+{"version":3,"file":"SSMLExtractor.d.ts","sourceRoot":"","sources":["../../src/services/SSMLExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACX,oBAAoB,EACpB,YAAY,EAEZ,MAAM,uCAAuC,CAAC;AAU/C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,aAAa,EAAE,YAAY,CAAC;CAC5B;AAgMD;;;;GAIG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,cAAc,CAAK;IAE3B;;;;;OAKG;IACH,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IA6D7D;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAuGzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGb"}

package/dist/services/SSMLExtractor.js

@@ -16,6 +16,189 @@
  *
  * Part of PIE Assessment Toolkit.
  */
+/**
+ * Allow-listed SSML elements (from the SSML 1.1 spec subset we forward to
+ * TTS providers). Anything outside this list is unwrapped during
+ * sanitization so we never leak author-supplied scripts, iframes, or
+ * arbitrary HTML into the TTS pipeline.
+ */
+const SSML_ALLOWED_TAGS = new Set([
+    "speak",
+    "break",
+    "prosody",
+    "emphasis",
+    "say-as",
+    "sub",
+    "mark",
+    "phoneme",
+    "lang",
+    "p",
+    "s",
+    "voice",
+    "audio",
+    "lexicon",
+]);
+/**
+ * Allow-listed attributes across SSML elements. Attribute allow-listing is
+ * global (not per-tag) because the union is small and consistent across
+ * providers.
+ */
+/**
+ * Tags whose content must be dropped entirely (rather than unwrapped to
+ * preserve phrasing text). These are dangerous containers whose text
+ * payload could be re-interpreted downstream.
+ */
+const SSML_DROP_FULLY_TAGS = new Set([
+    "script",
+    "style",
+    "iframe",
+    "object",
+    "embed",
+    "foreignobject",
+    "noscript",
+    "template",
+]);
+const SSML_ALLOWED_ATTRS = new Set([
+    "alphabet",
+    "ph",
+    "time",
+    "strength",
+    "rate",
+    "pitch",
+    "volume",
+    "name",
+    "interpret-as",
+    "format",
+    "detail",
+    "language",
+    "xml:lang",
+    "lang",
+    "gender",
+    "src",
+]);
+/**
+ * Hosts that must never appear inside an SSML `<audio src>` because they
+ * would cause the server-side TTS provider to fetch a private / metadata
+ * endpoint on behalf of the request. Mirrors the SchoolCity provider's
+ * defense-in-depth check; the SSML-side block is cheap and belt-and-braces.
+ */
+const SSML_PRIVATE_AUDIO_HOSTS = [
+    /^localhost$/i,
+    /^127(?:\.\d{1,3}){3}$/,
+    /^0(?:\.\d{1,3}){3}$/,
+    /^10(?:\.\d{1,3}){3}$/,
+    /^192\.168(?:\.\d{1,3}){2}$/,
+    /^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/,
+    /^169\.254(?:\.\d{1,3}){2}$/,
+    /^::1$/,
+    /^fe80:/i,
+    /^fc00:/i,
+    /^fd[0-9a-f]{2}:/i,
+    /^metadata\.google\.internal$/i,
+    /^metadata\.azure\.internal$/i,
+    /^metadata\.packet\.net$/i,
+];
+function isSafeSsmlAudioSrc(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return false;
+    }
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "");
+    return !SSML_PRIVATE_AUDIO_HOSTS.some((pattern) => pattern.test(hostname));
+}
+/**
+ * Sanitize an SSML subtree in place: remove disallowed attributes and
+ * replace disallowed elements with their text content (so phrasing order
+ * is preserved but no scripts / iframes / unknown tags survive).
+ */
+function sanitizeSsmlElement(element) {
+    // Walk children snapshot first because we may replace nodes as we go.
+    const children = Array.from(element.children);
+    for (const child of children) {
+        const tagName = child.tagName.toLowerCase();
+        if (SSML_DROP_FULLY_TAGS.has(tagName)) {
+            child.remove();
+            continue;
+        }
+        sanitizeSsmlElement(child);
+        if (!SSML_ALLOWED_TAGS.has(tagName)) {
+            const textNode = element.ownerDocument.createTextNode(child.textContent ?? "");
+            child.replaceWith(textNode);
+        }
+    }
+    // Strip disallowed attributes on the surviving node.
+    const attrNames = Array.from(element.attributes).map((attr) => attr.name);
+    for (const attrName of attrNames) {
+        if (!SSML_ALLOWED_ATTRS.has(attrName.toLowerCase())) {
+            element.removeAttribute(attrName);
+        }
+    }
+    // Belt-and-braces: even though `src` is allow-listed, SSML `<audio>`
+    // sends its URL to a server-side TTS provider that will dereference
+    // it. Refuse non-http(s) schemes and private / cloud-metadata hosts
+    // at the SSML boundary so we never forward an SSRF primitive.
+    if (element.tagName.toLowerCase() === "audio") {
+        const src = element.getAttribute("src");
+        if (src !== null && !isSafeSsmlAudioSrc(src)) {
+            element.removeAttribute("src");
+        }
+    }
+}
+/**
+ * Serialize a sanitized `<speak>` element back to a minimal SSML string.
+ * Uses a manual walker instead of `outerHTML` so that any namespace
+ * quirks (e.g. `xmlns` attributes added by the HTML parser) are
+ * normalised and disallowed descendants cannot reappear through quirks
+ * in the serializer.
+ */
+function serializeSsmlElement(element) {
+    const tagName = element.tagName.toLowerCase();
+    const attrs = Array.from(element.attributes)
+        .filter((attr) => SSML_ALLOWED_ATTRS.has(attr.name.toLowerCase()))
+        .map((attr) => ` ${attr.name}="${escapeXmlAttr(attr.value)}"`)
+        .join("");
+    const childPieces = [];
+    for (const node of Array.from(element.childNodes)) {
+        if (node.nodeType === 3 /* text */) {
+            childPieces.push(escapeXmlText(node.nodeValue ?? ""));
+        }
+        else if (node.nodeType === 1 /* element */) {
+            const childElement = node;
+            const childTag = childElement.tagName.toLowerCase();
+            if (SSML_DROP_FULLY_TAGS.has(childTag)) {
+                continue;
+            }
+            if (SSML_ALLOWED_TAGS.has(childTag)) {
+                childPieces.push(serializeSsmlElement(childElement));
+            }
+            else {
+                childPieces.push(escapeXmlText(childElement.textContent ?? ""));
+            }
+        }
+    }
+    return `<${tagName}${attrs}>${childPieces.join("")}</${tagName}>`;
+}
+function escapeXmlText(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function escapeXmlAttr(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
 /**
  * SSMLExtractor Service
  *
@@ -107,8 +290,12 @@ export class SSMLExtractor {
                 try {
                     // Generate unique catalog ID
                     const catalogId = this.generateCatalogId(idPrefix);
-                    // Extract SSML content
-                    const ssmlContent = speakEl.outerHTML;
+                    // Sanitize before serializing so the SSML forwarded to the TTS
+                    // provider only contains spec-allowed tags/attributes. This
+                    // closes an author-content -> TTS-server pipeline that would
+                    // otherwise accept arbitrary HTML.
+                    sanitizeSsmlElement(speakEl);
+                    const ssmlContent = serializeSsmlElement(speakEl);
                     // Extract language (check both xml:lang and lang attributes)
                     const language = speakEl.getAttribute("xml:lang") ||
                         speakEl.getAttribute("lang") ||