@pie-players/pie-players-shared 0.3.74 → 0.3.75

package/dist/pie/index.js

@@ -23,20 +23,17 @@ export { createAuthoringAssetEventManager, initializeAuthoringConfigures, resolv
 export { initializeMathRendering, setMathRenderer, } from "./math-rendering.js";
 export { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
 export { resolveInstrumentationProvider } from "./instrumentation-provider-resolution.js";
-// Canonical stage vocabulary (M6). Both `<pie-section-player-*>` and
-// `<pie-assessment-toolkit>` share this primitive so the
-// `pie-stage-change` event family stays coherent across CE shapes.
-export { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
-export { createStageTracker } from "./stage-tracker.js";
+// Stage vocabulary of the section player's `pie-stage-change` event.
+export { STAGES } from "./stages.js";
 export { ASSESSMENT_INSTRUMENTATION_EVENT_MAP, ITEM_INSTRUMENTATION_EVENT_MAP, SECTION_INSTRUMENTATION_EVENT_MAP, TOOLKIT_INSTRUMENTATION_EVENT_MAP, } from "./instrumentation-event-map.js";
 export { ItemController, normalizeItemSessionContainer, } from "./item-controller.js";
-export { ensureHostSessionEntries, hasLearnerResponse, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
+export { ensureHostSessionEntries, hasLearnerResponse, hasResponseField, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
 export { MemoryItemSessionStorage, SessionStorageItemSessionStorage, } from "./item-controller-storage.js";
 export { SESSION_COMMIT_METHOD, bindPageLifecycleCommit, commitPendingSessions, flushPendingSessionNotifications, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
 // Opt-in device-local snapshot of a committed session, offered back to the host
 // after a crash rather than applied.
 export { createSessionSnapshot, isSessionSnapshotEnabled, isSnapshotIdentitySpecific, sessionSnapshotKey, sessionStorageSnapshotStore, } from "./session-snapshot.js";
-export { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
+export { createPieLogger, isGlobalDebugEnabled, isTtsDebugEnabled, } from "./logger.js";
 // Registry
 export { pieRegistry } from "./registry.js";
 // Scoring

package/dist/pie/instrumentation-event-bridge.js

@@ -1,9 +1,31 @@
 import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 const logger = createPieLogger("instrumentation-event-bridge", () => isGlobalDebugEnabled());
+/**
+ * Telemetry attributes are data. A detail's live objects (a coordinator on
+ * `toolkit-ready`, an `Error` cause, a function) stay on the event for its
+ * listeners and are left out of the attributes; primitives, arrays and plain
+ * objects pass.
+ */
+function isAttributeValue(value) {
+    if (value === null)
+        return true;
+    const type = typeof value;
+    if (type === "function" || type === "symbol")
+        return false;
+    if (type !== "object" || Array.isArray(value))
+        return true;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
 function normalizeEventDetail(detail) {
     if (detail && typeof detail === "object") {
-        return detail;
+        const attributes = {};
+        for (const [key, value] of Object.entries(detail)) {
+            if (isAttributeValue(value))
+                attributes[key] = value;
+        }
+        return attributes;
     }
     if (typeof detail === "undefined") {
         return {};

package/dist/pie/instrumentation-event-map.js

@@ -1,15 +1,7 @@
 export const TOOLKIT_INSTRUMENTATION_EVENT_MAP = [
-    // M6 canonical readiness vocabulary. The four-stage canonical list
-    // (`composed`, `engine-ready`, `interactive`, `disposed`) is identical
-    // across the toolkit CE and the layout CEs — the M6 retro removed the
-    // `attached`, `runtime-bound`, and `ui-rendered` stages because they
-    // had zero internal or external consumers. Hosts listen for the
-    // DOM-prefixed name directly (`pie-stage-change`); the instrumentation
-    // bridge forwards the same name to telemetry.
-    {
-        sourceEventName: "pie-stage-change",
-        instrumentationEventName: "pie-toolkit-stage-change",
-    },
+    // The toolkit emits no stage events: the section player's runtime
+    // engine dispatches `pie-stage-change` on the layout element, above the
+    // toolkit, and the section map tracks it there.
     {
         sourceEventName: "runtime-owned",
         instrumentationEventName: "pie-toolkit-runtime-owned",
@@ -18,6 +10,10 @@ export const TOOLKIT_INSTRUMENTATION_EVENT_MAP = [
         sourceEventName: "runtime-inherited",
         instrumentationEventName: "pie-toolkit-runtime-inherited",
     },
+    {
+        sourceEventName: "runtime-ready",
+        instrumentationEventName: "pie-toolkit-runtime-ready",
+    },
     {
         sourceEventName: "toolkit-ready",
         instrumentationEventName: "pie-toolkit-ready",
@@ -32,13 +28,10 @@ export const TOOLKIT_INSTRUMENTATION_EVENT_MAP = [
     },
 ];
 export const SECTION_INSTRUMENTATION_EVENT_MAP = [
-    // M6 canonical readiness vocabulary. Hosts listen for the DOM-prefixed
-    // names directly (`pie-stage-change`, `pie-loading-complete`); the
-    // instrumentation bridge forwards the same names to telemetry. The
-    // readiness alias mappings (`readiness-change`, `interaction-ready`,
-    // `ready`) and the `section-controller-ready` mapping were removed
-    // alongside their DOM-event surfaces. `session-changed` stays off the
-    // bridge for the reason the item map gives below.
+    // The runtime engine dispatches `pie-stage-change` and
+    // `pie-loading-complete` on the layout element; `framework-error`
+    // bubbles to it from the player's toolkit. `session-changed` stays off
+    // the bridge for the reason the item map gives below.
     {
         sourceEventName: "pie-stage-change",
         instrumentationEventName: "pie-section-stage-change",

package/dist/pie/item-controller.js

@@ -45,7 +45,11 @@ export class ItemController {
     setSession(input, options = {}) {
         const next = normalizeSessionContainer(input, this.sessionId);
         const allowMetadataOverwrite = options.allowMetadataOverwrite ?? false;
+        // The guard keeps a response from metadata churn on the same session. A
+        // session with another id is a new attempt or item, and replaces it.
+        const sameSession = next.id === "" || this.session.id === "" || next.id === this.session.id;
         if (!allowMetadataOverwrite &&
+            sameSession &&
             hasResponseValue(this.session) &&
             !hasResponseValue(next) &&
             !hasResponseField(next)) {

package/dist/pie/logger.d.ts

@@ -61,3 +61,9 @@ declare global {
  * Check if debug mode is enabled globally
  */
 export declare function isGlobalDebugEnabled(): boolean;
+/**
+ * Read-aloud's debug flag: `PIE_TTS_DEBUG=1` in the environment, or
+ * `globalThis.__PIE_TTS_DEBUG__ = true` in a page. Every read-aloud logger is
+ * created with it, and reads it on each debug line.
+ */
+export declare function isTtsDebugEnabled(): boolean;

package/dist/pie/logger.js

@@ -42,3 +42,13 @@ export function createPieLogger(namespace, debugEnabledFn) {
 export function isGlobalDebugEnabled() {
     return typeof window !== "undefined" && window.PIE_DEBUG === true;
 }
+/**
+ * Read-aloud's debug flag: `PIE_TTS_DEBUG=1` in the environment, or
+ * `globalThis.__PIE_TTS_DEBUG__ = true` in a page. Every read-aloud logger is
+ * created with it, and reads it on each debug line.
+ */
+export function isTtsDebugEnabled() {
+    const scope = globalThis;
+    return (scope.process?.env?.PIE_TTS_DEBUG === "1" ||
+        scope.__PIE_TTS_DEBUG__ === true);
+}

package/dist/pie/math-assets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where the MathJax adapter's copies load MathJax's fonts, speech worker and,
+ * on its npm build, MathJax itself from, and whether math is in the tab order.
+ * Every copy of `@pie-element/shared-math-rendering-mathjax` reads these from
+ * the legacy renderer's page options as it starts MathJax, on its first render,
+ * so they are set before any element renders. See
+ * https://github.com/pie-framework/pie-elements-ng/blob/develop/docs/MATH-RENDERING.md#assets
+ */
+export interface MathAssetOptions {
+    /**
+     * An npm root: a URL under which `<package>@<version>/<path>` serves that
+     * file of the package, such as `https://cdn.jsdelivr.net/npm`. A relative URL
+     * resolves against the page.
+     */
+    assetRoot?: string | URL;
+    /**
+     * The directory of `speech-worker.js` and its `mathmaps/`, by default
+     * `mathjax@<version>/sre` under the asset root.
+     */
+    speechPath?: string | URL;
+    /**
+     * The URL of individual files by npm path, `<package>@<version>/<path>`: a
+     * listed file loads from its URL, the rest from the asset root. A bundle lists
+     * each file it ships as `new URL("./…", import.meta.url)`, which its host's
+     * bundler emits, and needs no root. Read by the adapter's browser build, for
+     * its fonts, speech worker and speech rules.
+     */
+    assetUrls?: Readonly<Record<string, string | URL>>;
+    /**
+     * The speech locales the MathJax menu lists, by id (`["en", "es"]`), or by id
+     * with the label it shows. Unset, it lists every locale SRE ships.
+     */
+    speechLocales?: readonly string[] | Readonly<Record<string, string>>;
+    /**
+     * Puts typeset math in the keyboard tab order, for the MathJax menu and its
+     * explorer. Off by default.
+     */
+    inTabOrder?: boolean;
+}
+/** Why `options` is not a `MathAssetOptions`, or `undefined` when it is. */
+export declare function mathAssetOptionsError(options: unknown): string | undefined;
+/**
+ * Writes `options` to the page options, keeping the ones it leaves unset and
+ * the files of `assetUrls` it does not list.
+ */
+export declare function setMathAssetOptions(options: MathAssetOptions): void;
+/** The asset root the page options set, if any. */
+export declare function pageMathAssetRoot(): string | undefined;

package/dist/pie/math-assets.js

@@ -0,0 +1,81 @@
+/**
+ * Where the MathJax adapter's copies load MathJax's fonts, speech worker and,
+ * on its npm build, MathJax itself from, and whether math is in the tab order.
+ * Every copy of `@pie-element/shared-math-rendering-mathjax` reads these from
+ * the legacy renderer's page options as it starts MathJax, on its first render,
+ * so they are set before any element renders. See
+ * https://github.com/pie-framework/pie-elements-ng/blob/develop/docs/MATH-RENDERING.md#assets
+ */
+/** The legacy renderer's page options, which the adapter reads as well. */
+const PAGE_OPTIONS_KEY = "@pie-lib/math-rendering@2";
+const isUrl = (value) => (typeof value === "string" && value !== "") || value instanceof URL;
+/** Why `options` is not a `MathAssetOptions`, or `undefined` when it is. */
+export function mathAssetOptionsError(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        return "must be an object";
+    }
+    const { assetRoot, speechPath, assetUrls, speechLocales, inTabOrder } = options;
+    if (assetRoot !== undefined && !isUrl(assetRoot)) {
+        return `assetRoot must be a URL, got ${JSON.stringify(assetRoot)}`;
+    }
+    if (speechPath !== undefined && !isUrl(speechPath)) {
+        return `speechPath must be a URL, got ${JSON.stringify(speechPath)}`;
+    }
+    if (assetUrls !== undefined &&
+        (!assetUrls ||
+            typeof assetUrls !== "object" ||
+            Array.isArray(assetUrls) ||
+            !Object.values(assetUrls).every(isUrl))) {
+        return "assetUrls must map npm paths to URLs";
+    }
+    if (speechLocales !== undefined) {
+        const listed = Array.isArray(speechLocales)
+            ? speechLocales
+            : speechLocales && typeof speechLocales === "object"
+                ? Object.values(speechLocales)
+                : null;
+        if (!listed || listed.some((entry) => typeof entry !== "string" || !entry)) {
+            return "speechLocales must be locale ids, or locale ids mapped to their labels";
+        }
+    }
+    if (inTabOrder !== undefined && typeof inTabOrder !== "boolean") {
+        return `inTabOrder must be a boolean, got ${JSON.stringify(inTabOrder)}`;
+    }
+    return undefined;
+}
+/**
+ * Writes `options` to the page options, keeping the ones it leaves unset and
+ * the files of `assetUrls` it does not list.
+ */
+export function setMathAssetOptions(options) {
+    if (typeof window === "undefined")
+        return;
+    const host = window;
+    const page = (host[PAGE_OPTIONS_KEY] ??= {});
+    const opts = (page.opts ??= {});
+    if (options.assetRoot !== undefined)
+        opts.assetRoot = String(options.assetRoot);
+    if (options.speechPath !== undefined)
+        opts.speechPath = String(options.speechPath);
+    if (options.assetUrls !== undefined) {
+        const listed = opts.assetUrls && typeof opts.assetUrls === "object" ? opts.assetUrls : {};
+        opts.assetUrls = {
+            ...listed,
+            ...Object.fromEntries(Object.entries(options.assetUrls).map(([path, url]) => [path, String(url)])),
+        };
+    }
+    if (options.speechLocales !== undefined) {
+        opts.speechLocales = Array.isArray(options.speechLocales)
+            ? [...options.speechLocales]
+            : { ...options.speechLocales };
+    }
+    if (options.inTabOrder !== undefined)
+        opts.inTabOrder = options.inTabOrder;
+}
+/** The asset root the page options set, if any. */
+export function pageMathAssetRoot() {
+    if (typeof window === "undefined")
+        return undefined;
+    const root = window[PAGE_OPTIONS_KEY]?.opts?.assetRoot;
+    return typeof root === "string" && root ? root : undefined;
+}

package/dist/pie/scoring.d.ts

@@ -20,14 +20,9 @@ export type ScorePieItemOptions = {
     container?: Pick<ParentNode, "querySelector">;
     env?: Partial<Env>;
     models?: PieModel[];
-    /**
-     * Existing callers keep the historical scorePieItem controller call shape.
-     * provideScore() opts into the item-player score result shape explicitly.
-     */
-    outcomeArguments?: "session-env" | "model-session-env";
     /**
      * Preserve one result slot per model, including undefined for missing element/controller.
-     * Existing scorePieItem callers keep the filtered result shape by default.
+     * Missing slots are filtered out by default.
      */
     includeMissingResults?: boolean;
     /** The scoring player's bundle type; `player.js` scores nothing locally. */

package/dist/pie/scoring.js

@@ -62,13 +62,9 @@ const findRenderedPieElement = (root, modelId) => {
     return (root.querySelector(`[id="${escapedId}"]`) ||
         root.querySelector(`[pie-id="${escapedId}"]`));
 };
-const invokeOutcome = async (controller, model, session, env, argumentShape) => {
-    if (argumentShape === "model-session-env") {
-        const outcome = controller.outcome;
-        return outcome.call(controller, model, session, env);
-    }
+const invokeOutcome = async (controller, model, session, env) => {
     const outcome = controller.outcome;
-    return outcome.call(controller, session, env);
+    return outcome.call(controller, model, session, env);
 };
 /**
  * Score a PIE item by calling outcome on all PIE elements
@@ -76,7 +72,6 @@ const invokeOutcome = async (controller, model, session, env, argumentShape) =>
 export async function scorePieItem(config, sessionData, options = {}) {
     const root = options.container ?? document;
     const models = options.models ?? config.models ?? [];
-    const outcomeArguments = options.outcomeArguments ?? "session-env";
     const scoringEnv = {
         ...options.env,
         mode: "evaluate",
@@ -91,7 +86,7 @@ export async function scorePieItem(config, sessionData, options = {}) {
             if (controller?.outcome) {
                 return {
                     ...session,
-                    ...(await invokeOutcome(controller, model, session, scoringEnv, outcomeArguments)),
+                    ...(await invokeOutcome(controller, model, session, scoringEnv)),
                 };
             }
             else {

package/dist/pie/session-commit.js

@@ -93,7 +93,7 @@ function assignedElementsOf(element) {
  * elements assigned to each `<slot>`.
  *
  * `querySelectorAll("*")` sees none of the last two, and both are load-bearing
- * here. The section player mounts each item inside `<pie-item-shell>`'s shadow
+ * here. The section player mounts each item inside `<pie-item-scope>`'s shadow
  * root, and projects its item pane through a slot on the assessment toolkit -
  * a walk that stops at `<slot>` finds every delivery element in a section
  * unreachable.

package/dist/pie/stages.d.ts

@@ -1,56 +1,20 @@
 /**
- * Canonical stage vocabulary (M6 of the Coherent Options Surface track).
+ * Stage vocabulary of the section player's `pie-stage-change` event.
  *
- * 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.
+ * A cohort (one section and attempt) moves through `composed`,
+ * `engine-ready`, `interactive` and `disposed`, in that order. The section
+ * runtime engine in `@pie-players/pie-assessment-toolkit` is the only emitter;
+ * it dispatches the event on the layout element. `pie-loading-complete`
+ * reports that every item loaded and is not a stage. `readiness.mode =
+ * "strict"` only delays `interactive`.
  *
- * 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.
+ * `status` is `entered`, or `failed` for the stage a non-recoverable
+ * framework error stopped the chain at, with `skipped` for each later stage
+ * up to `interactive`. The `framework-error` event carries 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;
@@ -68,7 +32,6 @@ export type LoadingCompleteDetail = {
     sectionId: string;
     attemptId?: string;
     itemCount: number;
-    loadedCount: number;
     timestamp: string;
     sourceCe: string;
 };

package/dist/pie/stages.js

@@ -1,33 +1,16 @@
 /**
- * Canonical stage vocabulary (M6 of the Coherent Options Surface track).
+ * Stage vocabulary of the section player's `pie-stage-change` event.
  *
- * 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.
+ * A cohort (one section and attempt) moves through `composed`,
+ * `engine-ready`, `interactive` and `disposed`, in that order. The section
+ * runtime engine in `@pie-players/pie-assessment-toolkit` is the only emitter;
+ * it dispatches the event on the layout element. `pie-loading-complete`
+ * reports that every item loaded and is not a stage. `readiness.mode =
+ * "strict"` only delays `interactive`.
  *
- * 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.
+ * `status` is `entered`, or `failed` for the stage a non-recoverable
+ * framework error stopped the chain at, with `skipped` for each later stage
+ * up to `interactive`. The `framework-error` event carries the cause.
  */
 export const STAGES = Object.freeze([
     "composed",
@@ -35,23 +18,3 @@ export const STAGES = Object.freeze([
     "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;
-}

package/dist/security/sanitize-item-markup.d.ts

@@ -35,6 +35,10 @@ export interface SanitizeItemMarkupOptions {
  *   `form`, `meta`, `link`).
  * - Preserves PIE custom elements (`pie-*`) and any extra tags listed in
  *   `allowedCustomElements`.
+ * - Marks elements that carry an authored color, as `markAuthoredColors`
+ *   in `@pie-element/shared-utils` describes, so a color scheme can override
+ *   it. A host that opts out with `trust-markup` or supplies its own
+ *   sanitizer gets no markers.
  * - During SSR (no `window`) returns an empty string so untrusted markup
  *   never reaches the prerender output; the live renderer will re-run the
  *   sanitizer on hydrate.

package/dist/security/sanitize-item-markup.js

@@ -7,6 +7,7 @@
  * or supply their own sanitizer function if they need a stricter / looser
  * allow-list.
  */
+import { markAuthoredColors } from "@pie-element/shared-utils";
 import DOMPurify from "dompurify";
 import { SANITIZER_FORBIDDEN_ATTRS, SANITIZER_FORBIDDEN_TAGS, } from "./sanitize-forbidden-lists.js";
 import { installStyleAttributeHook } from "./sanitize-style-attribute.js";
@@ -29,6 +30,40 @@ const BASE_ALLOWED_ATTRS = [
     "lang",
     "dir",
 ];
+// MathML authored content uses that DOMPurify drops: elementary math, which
+// `@pie-element/shared-math-rendering-mathjax` rewrites as a table before
+// MathJax reads it, and `semantics`, `annotation`, `mprescripts` and `none`.
+// `annotation-xml` stays out because it is an HTML integration point.
+const MATHML_TAGS = new Set([
+    "mstack",
+    "mlongdiv",
+    "msgroup",
+    "msrow",
+    "msline",
+    "mscarries",
+    "mscarry",
+    "semantics",
+    "annotation",
+    "mprescripts",
+    "none",
+]);
+const MATHML_ATTRS = [
+    "stackalign",
+    "charalign",
+    "charspacing",
+    "longdivstyle",
+    "position",
+    "shift",
+    "location",
+    "crossout",
+    "leftoverhang",
+    "rightoverhang",
+    "mslinethickness",
+    "linebreak",
+];
+// Prefixed MathML such as `<m:math>`, which the HTML parser reads as unknown
+// HTML elements and the math adapter re-creates as MathML.
+const PREFIXED_TAG = /^[a-z_][\w.-]*:[a-z][\w.-]*$/;
 const BASE_URI_SAFE_ATTRS = ["pie-id"];
 const FORBIDDEN_TAGS = SANITIZER_FORBIDDEN_TAGS;
 const FORBIDDEN_ATTRS = SANITIZER_FORBIDDEN_ATTRS;
@@ -57,6 +92,10 @@ function resolvePurifier() {
     // `style` is URI-safe to DOMPurify, so nothing inside it is inspected
     // without this. See sanitize-style-attribute.ts.
     installStyleAttributeHook(purifierInstance);
+    // After the style filter, so only declarations that survive it are marked.
+    // The markers are the contract a color scheme's CSS overrides authored
+    // colors through, shared with element model HTML. (PIE-1119)
+    purifierInstance.addHook?.("afterSanitizeAttributes", (node) => markAuthoredColors(node));
     return purifierInstance;
 }
 /**
@@ -67,6 +106,10 @@ function resolvePurifier() {
  *   `form`, `meta`, `link`).
  * - Preserves PIE custom elements (`pie-*`) and any extra tags listed in
  *   `allowedCustomElements`.
+ * - Marks elements that carry an authored color, as `markAuthoredColors`
+ *   in `@pie-element/shared-utils` describes, so a color scheme can override
+ *   it. A host that opts out with `trust-markup` or supplies its own
+ *   sanitizer gets no markers.
  * - During SSR (no `window`) returns an empty string so untrusted markup
  *   never reaches the prerender output; the live renderer will re-run the
  *   sanitizer on hydrate.
@@ -80,8 +123,11 @@ export function sanitizeItemMarkup(markup, options = {}) {
     const allowedCustomElements = (options.allowedCustomElements ?? []).map((name) => name.toLowerCase());
     const explicitCustomElementSet = new Set(allowedCustomElements);
     const result = purifier.sanitize(markup, {
-        ADD_TAGS: allowedCustomElements,
-        ADD_ATTR: BASE_ALLOWED_ATTRS,
+        // DOMPurify still removes a tag in FORBID_TAGS that this accepts.
+        ADD_TAGS: (tagName) => explicitCustomElementSet.has(tagName) ||
+            MATHML_TAGS.has(tagName) ||
+            PREFIXED_TAG.test(tagName),
+        ADD_ATTR: [...BASE_ALLOWED_ATTRS, ...MATHML_ATTRS],
         ADD_URI_SAFE_ATTR: BASE_URI_SAFE_ATTRS,
         FORBID_TAGS: FORBIDDEN_TAGS,
         FORBID_ATTR: FORBIDDEN_ATTRS,

package/dist/security/wrap-overwide-images.js

@@ -32,12 +32,31 @@ function buildAriaLabel(image) {
     const trimmed = alt ? alt.trim() : "";
     return trimmed ? `Scrollable image: ${trimmed}` : "Scrollable image";
 }
+/**
+ * A block-level image — an element's own `display: block`, a flex item — gets a
+ * block wrapper, so wrapping it adds no line box below it — a host reset of
+ * `img { display: block }` included. The live pass reads the computed display;
+ * markup parsed off-document has only the inline style, so the live pass reads
+ * a wrapper built there again.
+ */
+function imageLayoutClass(image) {
+    const view = image.ownerDocument?.defaultView;
+    const display = view
+        ? view.getComputedStyle(image).display
+        : image.style?.display;
+    const blockLevel = !!display &&
+        !display.startsWith("inline") &&
+        display !== "none" &&
+        display !== "contents";
+    return blockLevel ? "pie-image-scroll-block" : null;
+}
 const IMAGE_SPEC = {
     selector: "img",
     wrapperTag: "span",
     wrapperClass: "pie-image-scroll",
     markupProbe: /<img\b/i,
     buildAriaLabel,
+    layoutClass: imageLayoutClass,
 };
 /**
  * Wrap every unwrapped `<img>` descendant of `root` with the shared

package/dist/security/wrap-overwide.d.ts

@@ -32,6 +32,11 @@ export interface OverwideWrapSpec {
     markupProbe: RegExp;
     /** The wrapper's accessible name for one node. */
     buildAriaLabel: (node: Element) => string;
+    /**
+     * An extra wrapper class carrying the node's own layout, or `null` for none.
+     * Absent when every wrapper lays out alike.
+     */
+    layoutClass?: (node: Element) => string | null;
 }
 export interface WrapOverwideOptions {
     /**
@@ -45,6 +50,9 @@ export interface WrapOverwideOptions {
 /**
  * Wrap every unwrapped match under `root`. Returns the number newly wrapped so
  * callers can short-circuit when nothing changed. Idempotent.
+ *
+ * Under a connected `root`, a wrapper whose layout was never read live gains
+ * the layout class this pass would have given it.
  */
 export declare function wrapOverwideInElement(root: Element, spec: OverwideWrapSpec, options?: WrapOverwideOptions): number;
 /**