@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/index.js

@@ -6,55 +6,30 @@
  *
  * @packageDocumentation
  */
-export { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "./context/assessment-toolkit-context.js";
-export { connectAssessmentToolkitHostRuntimeContext, connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "./context/runtime-context-consumer.js";
 export { catalogOwnerContextFor, } from "./services/catalog-owner.js";
-export { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_FORMATIVE_ACTION_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, PIE_REGISTER_EVENT, PIE_UNREGISTER_EVENT, } from "./runtime/registration-events.js";
-export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createCrossBoundaryEvent, dispatchCrossBoundaryEvent, isContextValueDefined, } from "./runtime/tool-host-contract.js";
-export { AccessibilityCatalogResolver, catalogCardForm, isKnownCatalogType, KNOWN_CATALOG_TYPES, } from "./services/AccessibilityCatalogResolver.js";
-// Context Variable Store (QTI 3.0 Context Declarations)
-export { ContextVariableStore } from "./services/ContextVariableStore.js";
+export { PIE_INTERNAL_FORMATIVE_ACTION_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, } from "./runtime/registration-events.js";
+export { createShellScope, } from "./runtime/shell-scope.js";
+// A shell's translation of its player's events into the runtime's, shared by the
+// section player's passage shell and `<pie-item-scope>`.
+export { createShellEventBridge, } from "./runtime/shell-event-bridge.js";
+export { connectToolRuntimeContext, dispatchCrossBoundaryEvent, } from "./runtime/tool-host-contract.js";
+export { AccessibilityCatalogResolver } from "./services/AccessibilityCatalogResolver.js";
 // Element Tool State Store (Element-level ephemeral tool state)
 export { ElementToolStateStore } from "./services/ElementToolStateStore.js";
 export { HighlightColor, HighlightCoordinator, HighlightType, } from "./services/HighlightCoordinator.js";
-export { RangeSerializer } from "./services/RangeSerializer.js";
-export { I18nService } from "./services/I18nService.js";
 export { ToolRegistry } from "./services/ToolRegistry.js";
-export { DEFAULT_TOOL_REQUEST_LEVEL } from "./services/tool-request.js";
-export { extractTextContent, hasChoiceInteraction, hasMathContent, hasReadableText, isAssessmentContext, isElementContext, isItemContext, isPassageContext, isRubricContext, isSectionContext, } from "./services/tool-context.js";
-export { DEFAULT_TOOL_PLACEMENT } from "./services/createDefaultToolRegistry.js";
+export { hasReadableText } from "./services/tool-context.js";
 export { createToolsConfig } from "./services/create-tools-config.js";
-export { createEmptyPersonalNeedsProfile } from "./services/defaultPersonalNeedsProfile.js";
-export { createToolElement, resolveToolTag, toToolIdFromTag, } from "./tools/tool-tag-map.js";
-// QTI 3.0 Standard Access Features
-export { ALL_STANDARD_ACCESS_FEATURES, EXAMPLE_PNP_CONFIGURATIONS, getFeatureCategory, getFeaturesInCategory, isStandardAccessFeature, QTI_STANDARD_ACCESS_FEATURES, } from "./services/pnp-standard-features.js";
-// Media-bearing catalog cards: the generic half, shared by every card form that
-// references a recording rather than carrying text. `applyMediaFragment` reached
-// the public surface through `sign-language-cards.js` until signing moved to
-// `@pie-players/pie-tool-sign-language`; it is exported from its own module now,
-// alongside the validators a capability package needs to read a media payload.
-export { applyMediaFragment, enforceMediaFragment, isSafeMediaSrc, isUnsupportedMediaAssetVersion, normalizeMediaFragment, normalizeMediaSources, SUPPORTED_MEDIA_ASSET_VERSION, trimmedOrUndefined, } from "./services/catalog-media.js";
-export { resolveSpokenAudioMedia, SPOKEN_CATALOG_TYPE, } from "./services/spoken-audio-cards.js";
 export { SSMLExtractor } from "./services/SSMLExtractor.js";
-export { ThemeProvider } from "./services/ThemeProvider.js";
 // Tool Coordinator
 export { ToolCoordinator, ZIndexLayer } from "./services/ToolCoordinator.js";
 export { ToolkitCoordinator } from "./services/ToolkitCoordinator.js";
-export { formatFrameworkErrorForConsole, frameworkErrorFromToolConfigDiagnostics, frameworkErrorFromUnknown, toFrameworkErrorModel, } from "./services/framework-error.js";
-export { isExternalIconUrl, isInlineSvgIcon, isToolbarLinkItem, isValidToolbarItemShape, } from "./services/toolbar-items.js";
-export { normalizeToolsConfig, normalizeToolAlias, normalizeToolList, parseToolList, } from "./services/tools-config-normalizer.js";
-export { isHostDeniedFeature } from "./policy/core/feature-decision.js";
-export { frameworkErrorFromToolConfigValidation, normalizeAndValidateToolsConfig, } from "./services/tool-config-validation.js";
-export { createScopedToolId, parseScopedToolId, toOverlayToolId, } from "./services/tool-instance-id.js";
+export { frameworkErrorFromUnknown, toFrameworkErrorModel, } from "./services/framework-error.js";
+export { createScopedToolId } from "./services/tool-instance-id.js";
 export { PlaybackState, TTSService } from "./services/TTSService.js";
-export { PIE_TTS_CONTROL_HANDOFF_EVENT, } from "./services/tts-control-events.js";
-export { bindTtsAudioHandoff, pauseTtsForMediaAudio, } from "./services/audio-handoff.js";
 export { BrowserTTSProvider } from "./services/tts/browser-provider.js";
-export { DEFAULT_TTS_SPEED_OPTIONS, formatTTSSpeedOptionsAsText, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, normalizeTTSSpeedOptionConfigs, normalizeTTSSpeedOptions, parseTTSSpeedOptionsFromText, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSRuntimeSettings, } from "./services/tts-runtime-config.js";
-export { createFetchItemLoader, createLoadItem, ItemLoadError, } from "./item-loader.js";
-export { createMemoryStorage, createTestAttemptSessionIdentifier, createNewTestAttemptSession, getBrowserLocalStorage, getOrCreateAnonymousDeviceId, getTestAttemptSessionStorageKey, loadTestAttemptSession, saveTestAttemptSession, setCurrentPosition, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
-export { createNewAssessmentSession, getAssessmentSessionStorageKey, loadAssessmentSession, saveAssessmentSession, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
-export { buildActivitySessionItemUpdate, buildActivitySessionPatchFromTestAttemptSession, mapActivityToTestAttemptSession, toItemSessionsRecord, } from "./attempt/adapters/activity-to-test-attempt-session.js";
+export { createNewTestAttemptSession, setCurrentPosition, toItemSessionsRecord, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
+export { createNewAssessmentSession, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
 // Section Player - Use @pie-players/pie-section-player web component
 // ============================================================================
 // Shared Components

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

@@ -57,7 +57,7 @@ export interface PolicySourceResult {
     decisions?: PolicySourceProvenanceEntry[];
 }
 export interface PolicySource {
-    /** Stable identifier — used for `custom.${id}` source tags. */
+    /** Stable identifier, recorded as `customSourceId` on the decisions and diagnostics it causes. */
     readonly id: string;
     refine(context: PolicySourceDecisionContext): PolicySourceResult;
 }

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

@@ -3,43 +3,40 @@
  * `docs/tools-and-accomodations/architecture.md`.
  *
  * Wraps `composeDecision(...)` with engine-instance state:
- *   - bound inputs (`tools`, `assessment`, `currentItemRef`, ...)
+ *   - bound inputs (`tools`, `assessment`, `pnpEnforcement`) and the
+ *     settings of the mounted items
  *   - registered custom `PolicySource`s
  *   - `onPolicyChange` subscriber bus
  *   - `dispose()` clean-up
  *
  * The class has no DOM dependency and no Svelte runes. It is safe to
  * instantiate inside a worker, in a Node test, or inside a CE
- * connectedCallback. The Svelte context glue (`TOOL_POLICY_ENGINE_KEY`)
- * lives in `engine-context.ts`.
- *
- * PR 1 ships the engine *without callers*. PR 2 wires it into
- * `ToolkitCoordinator`. PR 3 switches `<pie-item-toolbar>` over.
+ * connectedCallback. `ToolkitCoordinator` owns the instance, and
+ * `<pie-item-toolbar>` reads its decisions through the coordinator.
  */
-import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
+import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
 import type { CanonicalToolsConfig, ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
 import type { ToolRegistry } from "../../services/ToolRegistry.js";
-import type { ToolPolicyDecision, ToolPolicyDecisionRequest } from "./decision-types.js";
+import type { ToolPolicyDecision, ToolPolicyDecisionRequest, ToolScope } from "./decision-types.js";
 import type { PolicySource } from "./PolicySource.js";
 import type { FeaturePolicyDecision } from "./feature-decision.js";
 export type PnpEnforcementMode = "on" | "off";
 export interface ToolPolicyEngineInputs {
     tools?: CanonicalToolsConfig | null;
     assessment?: AssessmentEntity | null;
-    currentItemRef?: AssessmentItemRef | null;
     /**
-     * Explicit PNP/profile override. When omitted (or `undefined`), the engine
-     * defaults to {@link resolveDefaultPnpEnforcement} over the bound
-     * `assessment` and `currentItemRef`: `"on"` if they carry any
-     * PNP/profile policy material (PNP, district policy, test
-     * administration, item-level required/restricted/parameters),
+     * Explicit PNP/profile override; `null` or omitted is auto-mode. Auto-mode
+     * resolves per decision through {@link resolveDefaultPnpEnforcement}: `"on"`
+     * when the bound `assessment` carries PNP/profile policy material (PNP,
+     * district policy, test administration), and for a decision scoped to an item
+     * also when that item's settings carry required/restricted/parameters;
      * `"off"` otherwise. `tests/policy/pnp-default-on.test.ts` locks the rule.
      *
      * Hosts that want to force a mode pass `"on"` or `"off"`
      * explicitly. Embedded under `<pie-section-player-*>` the preferred
      * override flows through `runtime.tools.pnpEnforcement`.
      */
-    pnpEnforcement?: PnpEnforcementMode;
+    pnpEnforcement?: PnpEnforcementMode | null;
 }
 export interface ToolPolicyEngineArgs {
     toolRegistry: ToolRegistry;
@@ -49,28 +46,41 @@ export interface ToolPolicyEngineArgs {
     contextId?: string;
 }
 export interface ToolPolicyChangeEvent {
-    /** What changed in this update. */
-    reason: "inputs" | "policy-source-added" | "policy-source-removed" | "pnp-enforcement" | "disposed";
+    /**
+     * What changed in this update. `"item-settings"` is a mounted item's
+     * settings changing: it can change which tools that item's own toolbar
+     * shows, and nothing else a toolbar renders.
+     */
+    reason: "inputs" | "item-settings" | "policy-source-added" | "policy-source-removed" | "pnp-enforcement" | "disposed";
     /** Snapshot of the engine's inputs after the change. */
     inputs: Readonly<ResolvedEngineInputs>;
 }
 export interface ResolvedEngineInputs {
     tools: CanonicalToolsConfig;
     assessment: AssessmentEntity | null;
-    currentItemRef: AssessmentItemRef | null;
+    /**
+     * The mode a decision not scoped to an item applies. In auto-mode an
+     * item-scoped decision also turns on for its item's settings.
+     */
     pnpEnforcement: PnpEnforcementMode;
+    /** The host's override of auto-mode, or `null` in auto-mode. */
+    pnpEnforcementOverride: PnpEnforcementMode | null;
 }
 export type ToolPolicyChangeListener = (event: ToolPolicyChangeEvent) => void;
 export declare class ToolPolicyEngine {
-    private readonly toolRegistry;
+    private toolRegistry;
     private readonly contextId;
-    private readonly pnpPolicySource;
+    private pnpPolicySource;
     private readonly customSources;
     private readonly listeners;
     private tools;
     private assessment;
-    private currentItemRef;
-    private pnpEnforcement;
+    private pnpEnforcementOverride;
+    /**
+     * Mounted items' settings by canonical item id, newest registration last;
+     * see {@link registerItemSettings}.
+     */
+    private readonly itemSettings;
     private disposed;
     constructor(args: ToolPolicyEngineArgs);
     /**
@@ -87,10 +97,33 @@ export declare class ToolPolicyEngine {
      * values even though the policy decision itself is identical.
      * Hosts that want timestamp-stable provenance should reuse a
      * cached `ToolPolicyDecision` rather than re-call `decide(...)`.
+     *
+     * An item's registered settings apply to the item's own toolbar: a request
+     * at item level whose scope is the item. Every other request — a section,
+     * assessment or passage toolbar — is shared by the items it sits beside, so
+     * it leaves every item's settings out and reports each tool on its toolbar
+     * that one restricts or requires as `tool-policy.itemSettingNotApplied`.
      */
     decide(request: ToolPolicyDecisionRequest): ToolPolicyDecision;
     /**
-     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * Whether some surface is granted `featureId`: a decision with no item scope,
+     * or one scoped to a registered item. A provider serves every surface, so its
+     * failure denies the accommodation wherever one surface is granted it.
+     */
+    grantsFeatureAnywhere(featureId: string): boolean;
+    /**
+     * File a mounted item's settings under its canonical id. They govern the
+     * decisions scoped to that item: its own toolbar, and a feature its content
+     * asks about with the item's scope. See {@link decide}.
+     *
+     * The same item mounted twice registers twice; the newest registration
+     * applies, and its cleanup hands the item back to the one before. Emits an
+     * `"item-settings"` change whenever the settings that apply to the item
+     * change.
+     */
+    registerItemSettings(itemId: string, settings: ItemSettings): () => void;
+    /**
+     * Resolve eligibility for one PNP/AfA feature id through the eight-level
      * precedence, independent of toolbar placement.
      *
      * For capabilities that render as their own surface rather than a toolbar
@@ -111,8 +144,11 @@ export declare class ToolPolicyEngine {
      * The decision reports whether an assessment was bound, which is the engine's
      * to answer rather than the policy source's — see
      * {@link FeaturePolicyDecision.assessmentBound}.
+     *
+     * `scope` is the surface asking. An item's scope brings in the item's
+     * registered settings, as {@link decide} does for the item's toolbar.
      */
-    decideFeature(featureId: string): FeaturePolicyDecision;
+    decideFeature(featureId: string, scope?: ToolScope): FeaturePolicyDecision;
     /**
      * The host gates that hold for a feature id, or `null` when none fires.
      *
@@ -133,24 +169,39 @@ export declare class ToolPolicyEngine {
     /**
      * Apply a partial input update.
      *
-     * Each key is value-diffed via `Object.is` before storing, so callers
-     * may safely re-push the same reference (e.g. on Svelte effect
-     * re-runs caused by unrelated tracked reads): no-op patches do not
-     * fire `onPolicyChange` listeners. This contract is relied on by
-     * `PieAssessmentToolkit.svelte`'s prop-forwarding effect and by the
-     * coordinator's `decideToolPolicy()` tests.
+     * A key that did not change does not fire `onPolicyChange` listeners.
+     * `tools` is diffed with `Object.is`. `assessment` is diffed structurally,
+     * because hosts rebuild it from their own state on every render; the latest
+     * reference is stored either way.
      *
-     * `pnpEnforcement` is stored on its own field and always emits with
-     * a distinct `"pnp-enforcement"` reason when no other key changed,
-     * so PR 4's auto-on flip can target that reason without a separate
-     * event channel.
+     * `pnpEnforcement` sets the override, `null` or `undefined` returning to
+     * auto-mode, and emits with a distinct `"pnp-enforcement"` reason when no
+     * other key changed.
      */
     updateInputs(patch: Partial<ToolPolicyEngineInputs>): void;
+    /**
+     * Swap the registry PNP support ids resolve against, together with the tools
+     * config validated against it, and emit an `"inputs"` change. For a
+     * coordinator adopting its toolkit's registry.
+     */
+    replaceToolRegistry(toolRegistry: ToolRegistry, tools: CanonicalToolsConfig): void;
     registerPolicySource(source: PolicySource): () => void;
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
     getInputs(): Readonly<ResolvedEngineInputs>;
     dispose(): void;
     private snapshotInputs;
+    /** The override, else auto-mode over the assessment and `item`'s settings. */
+    private enforcementFor;
+    /** The settings that apply to `itemId`: its newest registration's. */
+    private itemSettingsFor;
+    private emitIfItemSettingsChanged;
+    /**
+     * The registered item an item scope names, by its canonical id. A scope
+     * of any other level names none.
+     */
+    private itemForScope;
+    /** The registered items whose settings their own toolbar enforces. */
+    private enforcedItems;
     private emit;
     private assertNotDisposed;
 }

package/dist/policy/core/ToolPolicyEngine.js

@@ -3,24 +3,23 @@
  * `docs/tools-and-accomodations/architecture.md`.
  *
  * Wraps `composeDecision(...)` with engine-instance state:
- *   - bound inputs (`tools`, `assessment`, `currentItemRef`, ...)
+ *   - bound inputs (`tools`, `assessment`, `pnpEnforcement`) and the
+ *     settings of the mounted items
  *   - registered custom `PolicySource`s
  *   - `onPolicyChange` subscriber bus
  *   - `dispose()` clean-up
  *
  * The class has no DOM dependency and no Svelte runes. It is safe to
  * instantiate inside a worker, in a Node test, or inside a CE
- * connectedCallback. The Svelte context glue (`TOOL_POLICY_ENGINE_KEY`)
- * lives in `engine-context.ts`.
- *
- * PR 1 ships the engine *without callers*. PR 2 wires it into
- * `ToolkitCoordinator`. PR 3 switches `<pie-item-toolbar>` over.
+ * connectedCallback. `ToolkitCoordinator` owns the instance, and
+ * `<pie-item-toolbar>` reads its decisions through the coordinator.
  */
 import { normalizeToolList, normalizeToolsConfig, } from "../../services/tools-config-normalizer.js";
 import { hostFeatureDenial, interpretFeatureResult, } from "./feature-decision.js";
 import { composeDecision } from "./compose-decision.js";
 import { resolveDefaultPnpEnforcement } from "./pnp-policy-inputs.js";
-import { PnpPolicySource } from "../sources/PnpPolicySource.js";
+import { structurallyEqual } from "../../utils/structural-equality.js";
+import { PnpPolicySource, } from "../sources/PnpPolicySource.js";
 const DEFAULT_TOOLS = normalizeToolsConfig({
     policy: { allowed: [], blocked: [] },
     placement: { section: [], item: [], passage: [] },
@@ -34,8 +33,12 @@ export class ToolPolicyEngine {
     listeners = new Set();
     tools;
     assessment;
-    currentItemRef;
-    pnpEnforcement;
+    pnpEnforcementOverride;
+    /**
+     * Mounted items' settings by canonical item id, newest registration last;
+     * see {@link registerItemSettings}.
+     */
+    itemSettings = new Map();
     disposed = false;
     constructor(args) {
         this.toolRegistry = args.toolRegistry;
@@ -45,13 +48,7 @@ export class ToolPolicyEngine {
         const inputs = args.inputs ?? {};
         this.tools = inputs.tools ?? DEFAULT_TOOLS;
         this.assessment = inputs.assessment ?? null;
-        this.currentItemRef = inputs.currentItemRef ?? null;
-        this.pnpEnforcement =
-            inputs.pnpEnforcement ??
-                resolveDefaultPnpEnforcement({
-                    assessment: this.assessment,
-                    currentItemRef: this.currentItemRef,
-                });
+        this.pnpEnforcementOverride = inputs.pnpEnforcement ?? null;
     }
     /**
      * Resolve the visible tool set for a given placement level and
@@ -67,27 +64,85 @@ export class ToolPolicyEngine {
      * values even though the policy decision itself is identical.
      * Hosts that want timestamp-stable provenance should reuse a
      * cached `ToolPolicyDecision` rather than re-call `decide(...)`.
+     *
+     * An item's registered settings apply to the item's own toolbar: a request
+     * at item level whose scope is the item. Every other request — a section,
+     * assessment or passage toolbar — is shared by the items it sits beside, so
+     * it leaves every item's settings out and reports each tool on its toolbar
+     * that one restricts or requires as `tool-policy.itemSettingNotApplied`.
      */
     decide(request) {
         this.assertNotDisposed();
         const requestContextId = request.scope.scopeId
             ? `${this.contextId}:${request.level}:${request.scope.scopeId}`
             : `${this.contextId}:${request.level}`;
+        const item = request.level === "item" ? this.itemForScope(request.scope) : undefined;
+        const shared = request.level !== "item" ||
+            request.scope.level === "section" ||
+            request.scope.level === "assessment";
         return composeDecision({
             request,
             tools: this.tools,
             pnpPolicy: {
                 source: this.pnpPolicySource,
                 assessment: this.assessment ?? undefined,
-                currentItemRef: this.currentItemRef ?? undefined,
-                enforcement: this.pnpEnforcement,
+                item,
+                enforcement: this.enforcementFor(item),
             },
+            unappliedItems: shared ? this.enforcedItems() : undefined,
             customSources: this.customSources,
             contextId: requestContextId,
         });
     }
     /**
-     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * Whether some surface is granted `featureId`: a decision with no item scope,
+     * or one scoped to a registered item. A provider serves every surface, so its
+     * failure denies the accommodation wherever one surface is granted it.
+     */
+    grantsFeatureAnywhere(featureId) {
+        if (this.decideFeature(featureId).granted)
+            return true;
+        for (const id of this.itemSettings.keys()) {
+            if (this.decideFeature(featureId, { level: "item", scopeId: id }).granted) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * File a mounted item's settings under its canonical id. They govern the
+     * decisions scoped to that item: its own toolbar, and a feature its content
+     * asks about with the item's scope. See {@link decide}.
+     *
+     * The same item mounted twice registers twice; the newest registration
+     * applies, and its cleanup hands the item back to the one before. Emits an
+     * `"item-settings"` change whenever the settings that apply to the item
+     * change.
+     */
+    registerItemSettings(itemId, settings) {
+        this.assertNotDisposed();
+        const entry = { settings };
+        const before = this.itemSettingsFor(itemId);
+        const entries = this.itemSettings.get(itemId) ?? [];
+        entries.push(entry);
+        this.itemSettings.set(itemId, entries);
+        this.emitIfItemSettingsChanged(itemId, before);
+        return () => {
+            if (this.disposed)
+                return;
+            const current = this.itemSettings.get(itemId);
+            const index = current?.indexOf(entry) ?? -1;
+            if (!current || index < 0)
+                return;
+            const previous = this.itemSettingsFor(itemId);
+            current.splice(index, 1);
+            if (current.length === 0)
+                this.itemSettings.delete(itemId);
+            this.emitIfItemSettingsChanged(itemId, previous);
+        };
+    }
+    /**
+     * Resolve eligibility for one PNP/AfA feature id through the eight-level
      * precedence, independent of toolbar placement.
      *
      * For capabilities that render as their own surface rather than a toolbar
@@ -108,15 +163,18 @@ export class ToolPolicyEngine {
      * The decision reports whether an assessment was bound, which is the engine's
      * to answer rather than the policy source's — see
      * {@link FeaturePolicyDecision.assessmentBound}.
+     *
+     * `scope` is the surface asking. An item's scope brings in the item's
+     * registered settings, as {@link decide} does for the item's toolbar.
      */
-    decideFeature(featureId) {
+    decideFeature(featureId, scope) {
         this.assertNotDisposed();
         const hostDenial = this.hostFeatureGate(featureId);
         if (hostDenial)
             return hostDenial;
         return interpretFeatureResult(featureId, this.pnpPolicySource.resolveFeature(featureId, {
             assessment: this.assessment ?? undefined,
-            currentItemRef: this.currentItemRef ?? undefined,
+            item: this.itemForScope(scope),
         }), 
         // `resolveFeature` takes the assessment as `undefined` either way, so the
         // source cannot tell an unbound host from one whose profile is silent.
@@ -159,17 +217,14 @@ export class ToolPolicyEngine {
     /**
      * Apply a partial input update.
      *
-     * Each key is value-diffed via `Object.is` before storing, so callers
-     * may safely re-push the same reference (e.g. on Svelte effect
-     * re-runs caused by unrelated tracked reads): no-op patches do not
-     * fire `onPolicyChange` listeners. This contract is relied on by
-     * `PieAssessmentToolkit.svelte`'s prop-forwarding effect and by the
-     * coordinator's `decideToolPolicy()` tests.
+     * A key that did not change does not fire `onPolicyChange` listeners.
+     * `tools` is diffed with `Object.is`. `assessment` is diffed structurally,
+     * because hosts rebuild it from their own state on every render; the latest
+     * reference is stored either way.
      *
-     * `pnpEnforcement` is stored on its own field and always emits with
-     * a distinct `"pnp-enforcement"` reason when no other key changed,
-     * so PR 4's auto-on flip can target that reason without a separate
-     * event channel.
+     * `pnpEnforcement` sets the override, `null` or `undefined` returning to
+     * auto-mode, and emits with a distinct `"pnp-enforcement"` reason when no
+     * other key changed.
      */
     updateInputs(patch) {
         this.assertNotDisposed();
@@ -184,21 +239,14 @@ export class ToolPolicyEngine {
         }
         if ("assessment" in patch) {
             const next = patch.assessment ?? null;
-            if (!Object.is(this.assessment, next)) {
-                this.assessment = next;
+            if (!structurallyEqual(this.assessment, next))
                 changed = true;
-            }
+            this.assessment = next;
         }
-        if ("currentItemRef" in patch) {
-            const next = patch.currentItemRef ?? null;
-            if (!Object.is(this.currentItemRef, next)) {
-                this.currentItemRef = next;
-                changed = true;
-            }
-        }
-        if ("pnpEnforcement" in patch && patch.pnpEnforcement) {
-            if (this.pnpEnforcement !== patch.pnpEnforcement) {
-                this.pnpEnforcement = patch.pnpEnforcement;
+        if ("pnpEnforcement" in patch) {
+            const next = patch.pnpEnforcement ?? null;
+            if (this.pnpEnforcementOverride !== next) {
+                this.pnpEnforcementOverride = next;
                 pnpChanged = true;
             }
         }
@@ -209,6 +257,18 @@ export class ToolPolicyEngine {
             });
         }
     }
+    /**
+     * Swap the registry PNP support ids resolve against, together with the tools
+     * config validated against it, and emit an `"inputs"` change. For a
+     * coordinator adopting its toolkit's registry.
+     */
+    replaceToolRegistry(toolRegistry, tools) {
+        this.assertNotDisposed();
+        this.toolRegistry = toolRegistry;
+        this.pnpPolicySource = new PnpPolicySource(toolRegistry);
+        this.tools = tools;
+        this.emit({ reason: "inputs", inputs: this.snapshotInputs() });
+    }
     registerPolicySource(source) {
         this.assertNotDisposed();
         this.customSources.push(source);
@@ -247,16 +307,58 @@ export class ToolPolicyEngine {
             inputs: this.snapshotInputs(),
         });
         this.listeners.clear();
+        this.itemSettings.clear();
         this.customSources.length = 0;
     }
     snapshotInputs() {
         return Object.freeze({
             tools: this.tools,
             assessment: this.assessment,
-            currentItemRef: this.currentItemRef,
-            pnpEnforcement: this.pnpEnforcement,
+            pnpEnforcement: this.enforcementFor(),
+            pnpEnforcementOverride: this.pnpEnforcementOverride,
         });
     }
+    /** The override, else auto-mode over the assessment and `item`'s settings. */
+    enforcementFor(item) {
+        return (this.pnpEnforcementOverride ??
+            resolveDefaultPnpEnforcement({
+                assessment: this.assessment,
+                itemSettings: item?.settings,
+            }));
+    }
+    /** The settings that apply to `itemId`: its newest registration's. */
+    itemSettingsFor(itemId) {
+        return this.itemSettings.get(itemId)?.at(-1)?.settings;
+    }
+    emitIfItemSettingsChanged(itemId, before) {
+        if (structurallyEqual(before, this.itemSettingsFor(itemId)))
+            return;
+        this.emit({ reason: "item-settings", inputs: this.snapshotInputs() });
+    }
+    /**
+     * The registered item an item scope names, by its canonical id. A scope
+     * of any other level names none.
+     */
+    itemForScope(scope) {
+        if (scope?.level !== "item")
+            return undefined;
+        const id = scope.canonicalItemId || scope.itemId || scope.scopeId;
+        const settings = id ? this.itemSettingsFor(id) : undefined;
+        return settings ? { id, settings } : undefined;
+    }
+    /** The registered items whose settings their own toolbar enforces. */
+    enforcedItems() {
+        const items = [];
+        for (const id of this.itemSettings.keys()) {
+            const settings = this.itemSettingsFor(id);
+            if (!settings)
+                continue;
+            const item = { id, settings };
+            if (this.enforcementFor(item) === "on")
+                items.push(item);
+        }
+        return items;
+    }
     emit(event) {
         for (const listener of Array.from(this.listeners)) {
             try {

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

@@ -11,27 +11,48 @@
  * The tests in
  * `tests/policy/compose-decision.test.ts` lock the orchestration in.
  */
-import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
-import { type CanonicalToolsConfig } from "../../services/tools-config-normalizer.js";
-import type { ToolPolicyDecision, ToolPolicyDecisionRequest } from "./decision-types.js";
+import type { AssessmentEntity } from "@pie-players/pie-players-shared/types";
+import { type CanonicalToolsConfig, type ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
+import type { OverrideBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic } from "./decision-types.js";
 import type { PolicySource } from "./PolicySource.js";
-import type { PnpPolicySource } from "../sources/PnpPolicySource.js";
+import { type PnpPolicySourceRule } from "./provenance.js";
+import type { PnpPolicyItem, PnpPolicySource } from "../sources/PnpPolicySource.js";
 export interface ComposeDecisionInputs {
     request: ToolPolicyDecisionRequest;
     tools: CanonicalToolsConfig;
     pnpPolicy: {
         source: PnpPolicySource | null;
         assessment?: AssessmentEntity;
-        currentItemRef?: AssessmentItemRef;
+        /** The item an item-scoped decision is for; see {@link PnpPolicyItem}. */
+        item?: PnpPolicyItem;
         /**
          * "on" applies the PNP/profile precedence rules; "off" skips step 5
-         * entirely. Defaults to "on" when an assessment is present
-         * and the source is non-null (see M8 design Q5).
+         * entirely. The engine resolves it from the enforcement override, or
+         * from whether the assessment or item carries PNP/profile material.
          */
         enforcement: "on" | "off";
     };
+    /**
+     * Mounted items whose settings this decision leaves out: set for a section-
+     * or assessment-level toolbar. A tool on that toolbar that one of them
+     * restricts or requires gets a `tool-policy.itemSettingNotApplied`
+     * diagnostic.
+     */
+    unappliedItems?: readonly PnpPolicyItem[];
     customSources: readonly PolicySource[];
     /** Stable identifier used as the provenance `contextId`. */
     contextId: string;
 }
 export declare function composeDecision(inputs: ComposeDecisionInputs): ToolPolicyDecision;
+/**
+ * A `tool-policy.overrideBlocked` diagnostic for a tool a `true` test
+ * administration override grants and `rule` withdraws. `level` is absent on a
+ * feature decision, which has no toolbar level.
+ */
+export declare function overrideBlockedDiagnostic(toolId: string, rule: OverrideBlockedDetails["rule"], level?: ToolPlacementLevel): ToolPolicyDiagnostic;
+/**
+ * A `tool-policy.unknownSupportId` diagnostic for an id the registry lacks,
+ * attributed to the highest-precedence rule naming it. `level` is absent on a
+ * feature decision, which has no toolbar level.
+ */
+export declare function unknownSupportIdDiagnostic(supportId: string, origins: readonly PnpPolicySourceRule[], level?: ToolPlacementLevel): ToolPolicyDiagnostic;