@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/index.js

@@ -6,58 +6,28 @@
  *
  * @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, catalogSourceSignature, } 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, createToolCoordinatorRegistration, 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 { catalogOwnerContextFor, } from "./services/catalog-owner.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 { 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/tool-config-defaults.js";
+export { hasReadableText, hasSpokenContent, } 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. Owned by
-// `@pie-players/pie-players-shared/media`, which an element can import without
-// this package; re-exported here for toolkit consumers.
-export { applyMediaFragment, enforceMediaFragment, isSafeMediaSrc, isUnsupportedMediaAssetVersion, normalizeMediaFragment, normalizeMediaSources, SUPPORTED_MEDIA_ASSET_VERSION, trimmedOrUndefined, } from "@pie-players/pie-players-shared/media";
-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 { 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";
+// Text-to-Speech Service
 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 { createNewTestAttemptSession, setCurrentPosition, toItemSessionsRecord, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
 export { createNewAssessmentSession, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
-export { buildActivitySessionItemUpdate, buildActivitySessionPatchFromTestAttemptSession, mapActivityToTestAttemptSession, toItemSessionsRecord, } from "./attempt/adapters/activity-to-test-attempt-session.js";
-// Section Player - Use @pie-players/pie-section-player web component
-// ============================================================================
-// Shared Components
-// ============================================================================
-// ItemToolBar custom element registration helper is exported via package.json exports field
-// Import using: import '@pie-players/pie-assessment-toolkit/components/item-toolbar-element';
-// PieAssessmentToolkit custom element registration helper is exported via package.json exports field

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

@@ -36,7 +36,7 @@ export interface PolicySourceProvenanceEntry {
      * Custom precedence value used for the decision log. Defaults to
      * `100 + sourceIndex` (engine-assigned) when `undefined`. Sources
      * MAY override only if they know what they are doing — overriding
-     * to a value `<= 6` lets the source masquerade as a PNP/profile rule and
+     * to a value `<= 8` lets the source masquerade as a PNP/profile rule and
      * is generally a bug.
      */
     precedence?: number;
@@ -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 { CanonicalToolsConfig, ToolPlacementLevel } from "../../services/tools-config-normalizer.js";
+import type { AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { CanonicalToolsConfig, PnpEnforcementMode, 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, ToolPolicyDiagnostic, ToolScope } from "./decision-types.js";
 import type { PolicySource } from "./PolicySource.js";
 import type { FeaturePolicyDecision } from "./feature-decision.js";
-export type PnpEnforcementMode = "on" | "off";
+export type { PnpEnforcementMode };
 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 require or restrict a tool;
      * `"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;
@@ -47,30 +44,65 @@ export interface ToolPolicyEngineArgs {
     customSources?: readonly PolicySource[];
     /** Stable context label used in provenance trails. Defaults to "tool-policy". */
     contextId?: string;
+    /**
+     * Whether the host may leave the assessment unbound without that being a
+     * misconfiguration; see {@link ResolvedEngineInputs.assessmentExpected}.
+     * Defaults to `false`.
+     */
+    assessmentOptional?: boolean;
 }
 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;
+    /**
+     * Whether an unbound assessment is a misconfiguration: always, unless the
+     * engine was built `assessmentOptional`, and then only while enforcement is
+     * overridden `"on"`.
+     */
+    assessmentExpected: boolean;
+    /**
+     * Conflicts in the inputs themselves, independent of any decision: a
+     * `tool-policy.unknownSupportId` for each id the assessment or a mounted
+     * item's settings name that no registered tool carries. Recomputed when the
+     * assessment, an item's settings or the registry's tools change.
+     */
+    diagnostics: readonly ToolPolicyDiagnostic[];
 }
 export type ToolPolicyChangeListener = (event: ToolPolicyChangeEvent) => void;
 export declare class ToolPolicyEngine {
     private toolRegistry;
+    private unsubscribeRegistry;
     private readonly contextId;
+    private readonly assessmentOptional;
     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 inputDiagnostics;
     private disposed;
     constructor(args: ToolPolicyEngineArgs);
     /**
@@ -87,10 +119,38 @@ 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.
+     *
+     * `enforced` counts only scopes whose `pnpEnforcement` is on, as a toolbar
+     * tool's decisions do; a feature with no placement leaves it unset.
+     */
+    grantsFeatureAnywhere(featureId: string, options?: {
+        enforced?: boolean;
+    }): 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 +171,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<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
     /**
      * The host gates that hold for a feature id, or `null` when none fires.
      *
@@ -133,17 +196,14 @@ 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;
     /**
@@ -157,6 +217,30 @@ export declare class ToolPolicyEngine {
     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;
+    /**
+     * Recompute {@link ResolvedEngineInputs.diagnostics} from the bound
+     * assessment, every mounted item's settings and the registry. Returns
+     * whether they changed.
+     */
+    private refreshInputDiagnostics;
+    /**
+     * Registering a tool into the bound registry, or removing one, can make a
+     * named id known or unknown, so it emits an `"inputs"` change when the input
+     * diagnostics move.
+     */
+    private watchRegistry;
+    /**
+     * 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;
 }