@pie-players/pie-assessment-toolkit 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/policy/core/decision-types.d.ts

@@ -79,6 +79,11 @@ export interface ToolPolicyDecisionRequest {
  * `restrictedTools` or the profile's `prohibitedSupports` withdraws instead.
  * `details` is {@link OverrideBlockedDetails}.
  *
+ * `tool-policy.supportConflict` fires for each id a support in effect withdraws
+ * that something would otherwise have served, as the toolkit's `screenReader`
+ * withdraws `textToSpeech`. It replaces `tool-policy.overrideBlocked` for a `true`
+ * override the conflict withdraws. `details` is {@link SupportConflictDetails}.
+ *
  * The toolkit coordinator logs each diagnostic once per code, tool and item,
  * and hands the same ones to its `onPolicyDiagnostic` listeners.
  */
@@ -122,6 +127,20 @@ export interface OverrideBlockedDetails {
     /** The rule that withdrew the granted tool. */
     rule: "item-restriction" | "pnp-prohibited";
 }
+/**
+ * What would have served an id a support conflict withdraws: the placement
+ * that put the tool on this toolbar, the rule that would have granted it, or,
+ * for a feature an item player applies, the player's attribute or the item's
+ * authored setting it displaced.
+ */
+export type SupportConflictServedBy = "placement" | "attribute" | "authored" | Extract<PnpPolicySourceRule, "test-admin-override" | "item-requirement" | "district-requirement" | "pnp-activate-at-init" | "pnp-support">;
+/** Payload of a `tool-policy.supportConflict` diagnostic. */
+export interface SupportConflictDetails {
+    /** The support in effect that withholds the id. */
+    support: string;
+    /** What would otherwise have served the withheld id. */
+    servedBy: SupportConflictServedBy;
+}
 /** Payload of a `tool-policy.itemSettingNotApplied` diagnostic. */
 export interface ItemSettingNotAppliedDetails {
     /** Canonical id of the item whose setting names the tool. */
@@ -138,6 +157,7 @@ export interface ToolPolicyDiagnosticDetails {
     "tool-policy.unknownSupportId": UnknownSupportIdDetails;
     "tool-policy.itemSettingNotApplied": ItemSettingNotAppliedDetails;
     "tool-policy.overrideBlocked": OverrideBlockedDetails;
+    "tool-policy.supportConflict": SupportConflictDetails;
 }
 /** A policy diagnostic, its `details` typed by its `code`. */
 export type ToolPolicyDiagnostic = {

package/dist/policy/core/feature-decision.d.ts

@@ -77,9 +77,16 @@ export interface FeaturePolicyDecision<P = Record<string, unknown>> {
      * later ones winning. Set on a denial too; a host denial leaves it out.
      */
     parameters?: P;
+    /**
+     * The support in effect that withholds the feature, on a `support-conflict`
+     * verdict.
+     */
+    withheldBy?: string;
     /**
      * Conflicts found while deciding: a `tool-policy.overrideBlocked` for a
-     * granting override the decision withdrew. Empty on a host denial, which
+     * granting override the decision withdrew, and a
+     * `tool-policy.supportConflict` for a granting rule a support in effect
+     * displaced. Empty on a host denial, which
      * consults no policy source. An id no tool is registered under describes the
      * inputs, so it is reported on the engine inputs' `diagnostics`.
      */

package/dist/policy/core/feature-decision.js

@@ -20,7 +20,7 @@
  * "nothing was bound to ask against" are the same verdict for different
  * reasons, and only the second is a defect.
  */
-import { overrideBlockedDiagnostic } from "./compose-decision.js";
+import { overrideBlockedDiagnostic, supportConflictDiagnostic, } from "./compose-decision.js";
 /**
  * Reason text for a denial that had no assessment to decide against.
  *
@@ -79,6 +79,7 @@ export function interpretFeatureResult(featureId, result, context, parameters) {
     // The source logs "no rule fired" as a skip at the last level so the trail
     // stays ordered; the verdict names no rule for it.
     const fired = decision !== undefined && decision.action !== "skip";
+    const conflict = result.supportConflicts.get(featureId);
     return {
         featureId,
         granted,
@@ -95,7 +96,13 @@ export function interpretFeatureResult(featureId, result, context, parameters) {
             : unboundAssessmentReason(featureId),
         required: Boolean(flags?.required),
         parameters,
+        ...(fired && decision.rule === "support-conflict" && conflict
+            ? { withheldBy: conflict.support }
+            : {}),
         assessmentBound: context.assessmentBound,
-        diagnostics: Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
+        diagnostics: [
+            ...Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
+            ...Array.from(result.supportConflicts).flatMap(([toolId, { support, grant }]) => grant ? [supportConflictDiagnostic(toolId, support, grant)] : []),
+        ],
     };
 }

package/dist/policy/core/provenance.d.ts

@@ -8,7 +8,7 @@
  * provider veto, PNP/profile gates, and custom policy sources.
  */
 /** The PNP/profile precedence rules, highest first. */
-export type PnpPolicySourceRule = "district-block" | "test-admin-override" | "item-restriction" | "pnp-prohibited" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-activate-at-init";
+export type PnpPolicySourceRule = "district-block" | "test-admin-override" | "item-restriction" | "pnp-prohibited" | "support-conflict" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-activate-at-init";
 /**
  * Rule vocabulary for tool policy decisions. A decision's `rule` is the one
  * attribution channel: it names the step that enabled, blocked or advised on a

package/dist/policy/engine.d.ts

@@ -7,6 +7,7 @@
  */
 export { ToolPolicyEngine, type PnpEnforcementMode, type ResolvedEngineInputs, type ToolPolicyChangeEvent, type ToolPolicyChangeListener, type ToolPolicyEngineArgs, type ToolPolicyEngineInputs, } from "./core/ToolPolicyEngine.js";
 export { isHostDeniedFeature, type FeaturePolicyDecision, type FeaturePolicyRule, } from "./core/feature-decision.js";
-export type { ItemSettingNotAppliedDetails, OverrideBlockedDetails, PlacementMissingDetails, RequiredToolBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyDiagnosticDetails, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, UnknownSupportIdDetails, } from "./core/decision-types.js";
+export type { ItemSettingNotAppliedDetails, OverrideBlockedDetails, PlacementMissingDetails, RequiredToolBlockedDetails, SupportConflictDetails, SupportConflictServedBy, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyDiagnosticDetails, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, UnknownSupportIdDetails, } from "./core/decision-types.js";
 export type { PolicySource, PolicySourceDecisionContext, PolicySourceProvenanceEntry, PolicySourceResult, } from "./core/PolicySource.js";
+export type { SupportConflict } from "./sources/PnpPolicySource.js";
 export type { PnpPolicySourceRule, ToolPolicyDecisionRule, ToolPolicyFeatureTrail, ToolPolicyProvenance, ToolPolicyResolutionDecision, ToolPolicySourceType, } from "./core/provenance.js";

package/dist/policy/sources/PnpPolicySource.d.ts

@@ -10,7 +10,19 @@
 import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
 import type { ToolRegistry } from "../../services/ToolRegistry.js";
 import type { PnpPolicySourceRule, ToolPolicyResolutionDecision, ToolPolicySourceType } from "../core/provenance.js";
-import type { OverrideBlockedDetails } from "../core/decision-types.js";
+import type { OverrideBlockedDetails, SupportConflictServedBy } from "../core/decision-types.js";
+/**
+ * A support whose being in effect withholds other ids: they resolve blocked
+ * under `support-conflict` at precedence 4 while `support` resolves enabled.
+ * Every id a conflict names is recognized without a tool registration, so none
+ * raises `tool-policy.unknownSupportId`.
+ */
+export interface SupportConflict {
+    /** The support id that withholds. */
+    support: string;
+    /** The ids withheld while `support` is in effect. */
+    withholds: readonly string[];
+}
 /** Per-tool flags PNP/profile policy may attach to a surviving entry. */
 export interface PnpPolicyToolFlags {
     /** PNP/profile policy mandates this tool (item or district `requiredTools`). */
@@ -82,6 +94,14 @@ export interface PnpPolicyResult {
      * engine turns each into a `tool-policy.overrideBlocked` diagnostic.
      */
     blockedOverrides: Map<string, OverrideBlockedDetails["rule"]>;
+    /**
+     * Ids a support in effect withdrew under `support-conflict`, each with that
+     * support and the rule that would otherwise have granted the id, absent when
+     * none would have. The engine turns each into a
+     * `tool-policy.supportConflict` diagnostic when something would have served
+     * the id.
+     */
+    supportConflicts: Map<string, SupportConflictResolution>;
     /** Configuration sources the engine should attach to its provenance. */
     sources: {
         assessment?: {
@@ -101,10 +121,21 @@ export interface PnpPolicyResult {
         };
     };
 }
+/** A rule a support conflict can displace: one of levels 5 to 8. */
+export type SupportConflictGrant = Exclude<SupportConflictServedBy, "placement" | "attribute" | "authored">;
+/** One `support-conflict` withdrawal. */
+export interface SupportConflictResolution {
+    support: string;
+    grant?: SupportConflictGrant;
+}
 export declare class PnpPolicySource {
     readonly id = "pnp";
     private readonly toolRegistry;
-    constructor(toolRegistry: ToolRegistry);
+    private readonly supportConflicts;
+    /** Withheld id to the supports that withhold it, in declaration order. */
+    private readonly withheldBy;
+    private readonly registrylessIds;
+    constructor(toolRegistry: ToolRegistry, supportConflicts?: readonly SupportConflict[]);
     apply(args: PnpPolicyApplyArgs): PnpPolicyResult;
     /**
      * Evaluate exactly one PNP support id through the same eight-level
@@ -126,6 +157,17 @@ export declare class PnpPolicySource {
      * configuration-source attribution) from the bound policy inputs.
      */
     private prepare;
+    /**
+     * Whether `support` resolves enabled, conflicts aside: a support another
+     * conflict withholds still withholds, and two conflicts naming each other
+     * cannot recurse.
+     */
+    private supportInEffect;
+    /**
+     * `withConflict: false` resolves the id as if no support conflict applied,
+     * which names the grant a conflict displaces without a second copy of
+     * levels 5 to 8.
+     */
     private resolveSupport;
     /**
      * Ids the assessment or any of `items` names that no tool is registered

package/dist/policy/sources/PnpPolicySource.js

@@ -10,8 +10,22 @@
 export class PnpPolicySource {
     id = "pnp";
     toolRegistry;
-    constructor(toolRegistry) {
+    supportConflicts;
+    /** Withheld id to the supports that withhold it, in declaration order. */
+    withheldBy = new Map();
+    registrylessIds = new Set();
+    constructor(toolRegistry, supportConflicts = []) {
         this.toolRegistry = toolRegistry;
+        this.supportConflicts = supportConflicts;
+        for (const { support, withholds } of supportConflicts) {
+            this.registrylessIds.add(support);
+            for (const id of withholds) {
+                this.registrylessIds.add(id);
+                const supports = this.withheldBy.get(id) ?? [];
+                supports.push(support);
+                this.withheldBy.set(id, supports);
+            }
+        }
     }
     apply(args) {
         const { ctx, result } = this.prepare(args);
@@ -27,6 +41,12 @@ export class PnpPolicySource {
         }
         itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
         itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
+        // A conflict withdraws a placed tool that no policy input names.
+        for (const { support, withholds } of this.supportConflicts) {
+            if (this.supportInEffect(support, ctx)) {
+                withholds.forEach((s) => allSupports.add(s));
+            }
+        }
         for (const supportId of allSupports) {
             this.resolveSupport(supportId, ctx, result);
         }
@@ -60,14 +80,7 @@ export class PnpPolicySource {
         const pnp = assessment?.personalNeedsProfile;
         const settings = assessment?.settings;
         const itemSettings = item?.settings;
-        const result = {
-            blockedToolIds: new Set(),
-            mandates: new Map(),
-            perToolFlags: new Map(),
-            decisions: [],
-            blockedOverrides: new Map(),
-            sources: {},
-        };
+        const result = emptyResult();
         if (settings?.districtPolicy || settings?.testAdministration) {
             result.sources.assessment = {
                 id: assessment?.id || "unknown",
@@ -97,7 +110,22 @@ export class PnpPolicySource {
         };
         return { ctx, result };
     }
-    resolveSupport(supportId, ctx, out) {
+    /**
+     * Whether `support` resolves enabled, conflicts aside: a support another
+     * conflict withholds still withholds, and two conflicts naming each other
+     * cannot recurse.
+     */
+    supportInEffect(support, ctx) {
+        const scratch = emptyResult();
+        this.resolveSupport(support, ctx, scratch, false);
+        return scratch.decisions[0]?.action === "enable";
+    }
+    /**
+     * `withConflict: false` resolves the id as if no support conflict applied,
+     * which names the grant a conflict displaces without a second copy of
+     * levels 5 to 8.
+     */
+    resolveSupport(supportId, ctx, out, withConflict = true) {
         // 1. District block (absolute veto)
         if (ctx.districtPolicy?.blockedTools?.includes(supportId)) {
             out.blockedToolIds.add(supportId);
@@ -163,6 +191,35 @@ export class PnpPolicySource {
             });
             return;
         }
+        // 4. Support conflict. Ranks with the profile prohibition, below the
+        // blocks a person recorded.
+        const withholding = withConflict
+            ? this.withheldBy
+                .get(supportId)
+                ?.find((support) => this.supportInEffect(support, ctx))
+            : undefined;
+        if (withholding) {
+            const displaced = emptyResult();
+            this.resolveSupport(supportId, ctx, displaced, false);
+            const grant = displaced.decisions[0];
+            out.blockedToolIds.add(supportId);
+            out.supportConflicts.set(supportId, {
+                support: withholding,
+                ...(grant?.action === "enable"
+                    ? { grant: grant.rule }
+                    : {}),
+            });
+            out.decisions.push({
+                precedence: 4,
+                rule: "support-conflict",
+                featureId: supportId,
+                action: "block",
+                sourceType: "student",
+                reason: `"${supportId}" is withheld while the student's "${withholding}" support is in effect`,
+                value: { support: withholding },
+            });
+            return;
+        }
         const activateAtInit = ctx.pnp?.activateAtInit?.includes(supportId) === true;
         const mandate = ctx.itemSettings?.requiredTools?.includes(supportId)
             ? "item-requirement"
@@ -311,8 +368,9 @@ export class PnpPolicySource {
         ];
         for (const [rule, ids] of named) {
             for (const id of ids ?? []) {
-                if (this.toolRegistry.has(id))
+                if (this.toolRegistry.has(id) || this.registrylessIds.has(id)) {
                     continue;
+                }
                 const rules = unmapped.get(id) ?? [];
                 if (!rules.includes(rule))
                     rules.push(rule);
@@ -322,3 +380,14 @@ export class PnpPolicySource {
         return unmapped;
     }
 }
+function emptyResult() {
+    return {
+        blockedToolIds: new Set(),
+        mandates: new Map(),
+        perToolFlags: new Map(),
+        decisions: [],
+        blockedOverrides: new Map(),
+        supportConflicts: new Map(),
+        sources: {},
+    };
+}

package/dist/runtime/core/engine-resolver.d.ts

@@ -22,6 +22,7 @@
  * `toolConfigStrictness` beside `runtime`.
  */
 import type { LoaderConfig } from "@pie-players/pie-players-shared/loader-config";
+import type { I18nProvider } from "@pie-players/pie-players-shared/i18n";
 import type { LoadingCompleteDetail, StageChangeDetail } from "@pie-players/pie-players-shared/pie";
 import type { FrameworkErrorModel } from "../../services/framework-error.js";
 import type { ToolConfigStrictness } from "../../services/tool-config-validation.js";
@@ -71,6 +72,14 @@ export type RuntimeConfig = {
      * Unset reads as `en-US` wherever the markup names no language.
      */
     contentLanguage?: string;
+    /**
+     * The interface-locale provider the toolkit publishes on its runtime
+     * context, in place of the one it would construct: the catalogs it can
+     * serve, their loaders, and any host messages. `locale` on the element
+     * still names the locale; a provider given with none set keeps the locale
+     * its owner gave it.
+     */
+    i18n?: I18nProvider;
     onFrameworkError?: FrameworkErrorHandler;
     /** Called with each `pie-stage-change` detail. */
     onStageChange?: StageChangeHandler;
@@ -131,6 +140,14 @@ export declare function resolveRuntime(args: {
      * Unset reads as `en-US` wherever the markup names no language.
      */
     contentLanguage?: string;
+    /**
+     * The interface-locale provider the toolkit publishes on its runtime
+     * context, in place of the one it would construct: the catalogs it can
+     * serve, their loaders, and any host messages. `locale` on the element
+     * still names the locale; a provider given with none set keeps the locale
+     * its owner gave it.
+     */
+    i18n?: I18nProvider;
     onFrameworkError?: FrameworkErrorHandler;
     /** Called with each `pie-stage-change` detail. */
     onStageChange?: StageChangeHandler;

package/dist/runtime/item-feature-decisions.d.ts

@@ -0,0 +1,44 @@
+import { type ItemFeatureDecisions } from "@pie-players/pie-context";
+import type { ToolScope } from "../policy/core/decision-types.js";
+import type { ToolkitCoordinatorApi } from "../services/interfaces.js";
+/** The feature ids an item player applies to its item's models. */
+export declare const ITEM_PLAYER_FEATURE_IDS: readonly ["autoplayAudio"];
+type DecidingCoordinator = Pick<ToolkitCoordinatorApi, "decideFeaturePolicy" | "onPolicyChange" | "reportFeatureDecisionApplied">;
+/** The item a scope asks feature policy for. */
+export interface ItemFeatureScopeIdentity {
+    itemId: string;
+    canonicalItemId?: string;
+}
+/**
+ * The scope an item's feature decisions are asked with, which brings in the
+ * item's registered settings; the same scope an item's content surfaces ask
+ * with.
+ */
+export declare function itemFeatureScope(identity: ItemFeatureScopeIdentity): ToolScope;
+/**
+ * The decisions an item player applies, leaving out each id no rule names. No
+ * coordinator, or one predating feature decisions, decides nothing.
+ */
+export declare function resolveItemFeatureDecisions(coordinator: Pick<ToolkitCoordinatorApi, "decideFeaturePolicy"> | null, scope: ToolScope | null): ItemFeatureDecisions;
+export interface ItemFeatureDecisionsProvider {
+    /**
+     * The coordinator the scope's toolkit answered with; `null` until one has.
+     * The provider follows its policy changes, an item's settings registering
+     * among them.
+     */
+    setCoordinator(coordinator: DecidingCoordinator | null): void;
+    /** The scope's item; `null` while it has no item id. */
+    setItem(identity: ItemFeatureScopeIdentity | null): void;
+    disconnect(): void;
+}
+/**
+ * Answers `itemFeatureDecisionsContext` for the item player under `host`, and
+ * relays the player's `feature-decision-applied` to the coordinator.
+ *
+ * It answers with no decision until both a coordinator and an item are set, so
+ * an item player under a scope no toolkit has answered keeps its own setting.
+ * A value is republished only when a decision changed, since every new value
+ * remounts the item.
+ */
+export declare function provideItemFeatureDecisions(host: HTMLElement): ItemFeatureDecisionsProvider;
+export {};

package/dist/runtime/item-feature-decisions.js

@@ -0,0 +1,115 @@
+import { ContextProvider, FEATURE_DECISION_APPLIED_EVENT, itemFeatureDecisionsContext, } from "@pie-players/pie-context";
+/** The feature ids an item player applies to its item's models. */
+export const ITEM_PLAYER_FEATURE_IDS = ["autoplayAudio"];
+const NO_DECISIONS = Object.freeze({
+    features: Object.freeze({}),
+});
+/**
+ * The scope an item's feature decisions are asked with, which brings in the
+ * item's registered settings; the same scope an item's content surfaces ask
+ * with.
+ */
+export function itemFeatureScope(identity) {
+    const canonicalItemId = identity.canonicalItemId || identity.itemId;
+    return {
+        level: "item",
+        scopeId: canonicalItemId,
+        itemId: identity.itemId,
+        canonicalItemId,
+    };
+}
+/**
+ * The decisions an item player applies, leaving out each id no rule names. No
+ * coordinator, or one predating feature decisions, decides nothing.
+ */
+export function resolveItemFeatureDecisions(coordinator, scope) {
+    if (!scope || typeof coordinator?.decideFeaturePolicy !== "function") {
+        return NO_DECISIONS;
+    }
+    const features = {};
+    for (const featureId of ITEM_PLAYER_FEATURE_IDS) {
+        const decision = coordinator.decideFeaturePolicy(featureId, scope);
+        if (decision.rule === "none")
+            continue;
+        features[featureId] = { granted: decision.granted, rule: decision.rule };
+    }
+    return { features };
+}
+/**
+ * Answers `itemFeatureDecisionsContext` for the item player under `host`, and
+ * relays the player's `feature-decision-applied` to the coordinator.
+ *
+ * It answers with no decision until both a coordinator and an item are set, so
+ * an item player under a scope no toolkit has answered keeps its own setting.
+ * A value is republished only when a decision changed, since every new value
+ * remounts the item.
+ */
+export function provideItemFeatureDecisions(host) {
+    const provider = new ContextProvider(host, {
+        context: itemFeatureDecisionsContext,
+        initialValue: NO_DECISIONS,
+    });
+    provider.connect();
+    let signature = JSON.stringify(NO_DECISIONS.features);
+    let coordinator = null;
+    let scope = null;
+    let stopFollowingPolicy = null;
+    const refresh = () => {
+        const next = resolveItemFeatureDecisions(coordinator, scope);
+        const nextSignature = JSON.stringify(next.features);
+        if (nextSignature === signature)
+            return;
+        signature = nextSignature;
+        provider.setValue(next);
+    };
+    const stopFollowing = () => {
+        const stop = stopFollowingPolicy;
+        stopFollowingPolicy = null;
+        try {
+            stop?.();
+        }
+        catch {
+            // The coordinator may already have been disposed.
+        }
+    };
+    const onApplied = (event) => {
+        const detail = event.detail;
+        if (!detail || !scope)
+            return;
+        coordinator?.reportFeatureDecisionApplied?.(detail, scope);
+    };
+    host.addEventListener(FEATURE_DECISION_APPLIED_EVENT, onApplied);
+    return {
+        setCoordinator(next) {
+            if (next === coordinator)
+                return;
+            stopFollowing();
+            coordinator = next;
+            if (next && typeof next.onPolicyChange === "function") {
+                stopFollowingPolicy = next.onPolicyChange((event) => {
+                    if (event.reason === "disposed") {
+                        stopFollowing();
+                        coordinator = null;
+                    }
+                    refresh();
+                });
+            }
+            refresh();
+        },
+        setItem(identity) {
+            const next = identity?.itemId ? itemFeatureScope(identity) : null;
+            if (next?.scopeId === scope?.scopeId && next?.itemId === scope?.itemId) {
+                return;
+            }
+            scope = next;
+            refresh();
+        },
+        disconnect() {
+            host.removeEventListener(FEATURE_DECISION_APPLIED_EVENT, onApplied);
+            stopFollowing();
+            coordinator = null;
+            scope = null;
+            provider.disconnect();
+        },
+    };
+}

package/dist/services/ToolkitCoordinator.d.ts

@@ -22,6 +22,7 @@
  * - config-change application and TTS reconfiguration, last.
  */
 import type { AccessibilityCatalog, AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { FeatureDecisionAppliedDetail } from "@pie-players/pie-context";
 import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPolicyConfig, type TextToSpeechToolProviderConfig, type ToolProviderConfig, type ToolProvidersConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
 import { type ToolConfigStrictness } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
@@ -789,6 +790,14 @@ export declare class ToolkitCoordinator {
      * registered settings ({@link registerItemSettings}).
      */
     decideFeaturePolicy<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
+    /**
+     * Hear that an item player applied a feature decision to its item's models.
+     * A `support-conflict` hold that displaced the player's attribute or the
+     * item's authored setting raises `tool-policy.supportConflict`, as a
+     * conflict that displaced a granting rule already did when it was decided.
+     * Every other block was recorded by a person and raises nothing.
+     */
+    reportFeatureDecisionApplied(detail: FeatureDecisionAppliedDetail, scope: ToolScope): void;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound inputs change (`updateToolConfig`,

package/dist/services/ToolkitCoordinator.js

@@ -37,7 +37,9 @@ import { ToolProviderRegistry } from "./tool-providers/index.js";
 import { ToolRegistry } from "./ToolRegistry.js";
 import { ToolRequestRegistry } from "./tool-request.js";
 import { ToolPolicyEngine, } from "../policy/engine.js";
+import { supportConflictDiagnostic } from "../policy/core/compose-decision.js";
 import { resolveSectionSessionAssignment } from "./section-session-assignment.js";
+import { TOOLKIT_SUPPORT_CONFLICTS } from "./support-conflicts.js";
 class ToolkitCoordinatorDisposedError extends Error {
     constructor() {
         super("ToolkitCoordinator has been disposed.");
@@ -367,6 +369,7 @@ export class ToolkitCoordinator {
             toolRegistry: this.toolRegistry,
             contextId: `toolkit-coordinator:${this.assessmentId}`,
             assessmentOptional: this.config.assessmentOptional === true,
+            supportConflicts: TOOLKIT_SUPPORT_CONFLICTS,
             inputs: {
                 tools: this.config.tools,
                 assessment: null,
@@ -2157,6 +2160,26 @@ export class ToolkitCoordinator {
         }
         return decision;
     }
+    /**
+     * Hear that an item player applied a feature decision to its item's models.
+     * A `support-conflict` hold that displaced the player's attribute or the
+     * item's authored setting raises `tool-policy.supportConflict`, as a
+     * conflict that displaced a granting rule already did when it was decided.
+     * Every other block was recorded by a person and raises nothing.
+     */
+    reportFeatureDecisionApplied(detail, scope) {
+        if (detail.granted ||
+            detail.rule !== "support-conflict" ||
+            (detail.overrode !== "attribute" && detail.overrode !== "authored")) {
+            return;
+        }
+        const decision = this.policyEngine.decideFeature(detail.featureId, scope);
+        if (decision.rule !== "support-conflict" || !decision.withheldBy)
+            return;
+        this.warnPolicyDiagnostics([
+            supportConflictDiagnostic(detail.featureId, decision.withheldBy, detail.overrode),
+        ]);
+    }
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound inputs change (`updateToolConfig`,

package/dist/services/interfaces.d.ts

@@ -26,6 +26,7 @@ import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { ToolProviderRegistry } from "./tool-providers/ToolProviderRegistry.js";
 import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolScope } from "../policy/engine.js";
 import type { AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { FeatureDecisionAppliedDetail } from "@pie-players/pie-context";
 import type { TTSConfig } from "@pie-players/pie-tts";
 import type { ResolvedToolContext, ToolContextResolverContext, ToolRegistry } from "./ToolRegistry.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
@@ -615,6 +616,15 @@ export interface ToolkitCoordinatorApi {
      * assignable; call sites must feature-detect.
      */
     decideFeaturePolicy?<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
+    /**
+     * Hear that an item player applied a feature decision to its item's models,
+     * as `<pie-item-scope>` relays its `feature-decision-applied`. A
+     * `support-conflict` hold that displaced the player's attribute or the
+     * item's authored setting raises `tool-policy.supportConflict`.
+     *
+     * Optional, like {@link decideFeaturePolicy}; call sites must feature-detect.
+     */
+    reportFeatureDecisionApplied?(detail: FeatureDecisionAppliedDetail, scope: ToolScope): void;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound policy inputs change (`updateToolConfig`,

package/dist/services/support-conflicts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The support conflicts `ToolkitCoordinator` gives its policy engine. They name
+ * capabilities, so they live here, outside the capability-neutral policy core.
+ */
+import type { SupportConflict } from "../policy/engine.js";
+/**
+ * A student's screen reader speaks the page, so PIE's read-aloud and item audio
+ * that starts on its own would talk over it (ADR 0004).
+ */
+export declare const TOOLKIT_SUPPORT_CONFLICTS: readonly SupportConflict[];

package/dist/services/support-conflicts.js

@@ -0,0 +1,11 @@
+/**
+ * The support conflicts `ToolkitCoordinator` gives its policy engine. They name
+ * capabilities, so they live here, outside the capability-neutral policy core.
+ */
+/**
+ * A student's screen reader speaks the page, so PIE's read-aloud and item audio
+ * that starts on its own would talk over it (ADR 0004).
+ */
+export const TOOLKIT_SUPPORT_CONFLICTS = [
+    { support: "screenReader", withholds: ["textToSpeech", "autoplayAudio"] },
+];