@pie-players/pie-assessment-toolkit 0.3.63 → 0.3.64

package/dist/components/chunks/{ItemToolBar-84nv78dy.js → ItemToolBar-7rq2gj8b.js}

@@ -1,4 +1,4 @@
-import{B as bJ,C as H0,D as S0,E as pJ,F as L0,G as I0,H as _J,I as d,J as EJ,M as vJ,O as gJ,Q as $J,S as mj,T as hj,b as G0,c as SJ,d as IJ,e as N,f as a,g as w0,ga as mJ,h as P0,i as CJ,j as $0,k as K0,l as Gj,m as Y0,n as Q0,o as j,q as Pj,r as yJ,s as M0,t as U0,u as F,w as D0,x as Mj,y as e0,z as jj}from"./ItemToolBar-843902tp.js";function vj(v){return typeof v.href==="string"}function wJ(v){if(!v||typeof v!=="object"||Array.isArray(v))return!1;let q=v;if(typeof q.id!=="string"||q.id.trim().length===0)return!1;if(typeof q.label!=="string"||q.label.trim().length===0)return!1;if(q.ariaLabel!==void 0&&typeof q.ariaLabel!=="string")return!1;if(q.icon!==void 0&&typeof q.icon!=="string")return!1;if(q.tooltip!==void 0&&typeof q.tooltip!=="string")return!1;if(q.active!==void 0&&typeof q.active!=="boolean")return!1;if(q.disabled!==void 0&&typeof q.disabled!=="boolean")return!1;let s=typeof q.href==="string",m0=typeof q.onClick==="function";if(s===m0)return!1;if(s)return!0;return m0}function gj(v){return typeof v==="string"&&v.trimStart().startsWith("<svg")}function $j(v){return typeof v==="string"&&v.trimStart().startsWith("http")}import{sanitizeSvgIcon as Yj}from"@pie-players/pie-players-shared/security";import{approximateZoomFromWidths as qZ,computeZoomCompensation as FZ,ICON_BUTTON_ZOOM_OPTIONS as HJ}from"@pie-players/pie-players-shared/ui/zoom-compensation";import{createFocusTrap as kZ,FOCUSABLE_SELECTOR as xJ,isProgrammaticFocusTarget as BJ}from"@pie-players/pie-players-shared";import"@pie-players/pie-players-shared/nds-icon-button";var RZ=(v,q)=>{if(customElements.get(v))return;try{customElements.define(v,q)}catch(s){if(!(s instanceof DOMException&&s.name==="NotSupportedError"||s&&typeof s==="object"&&s.name==="NotSupportedError")||!customElements.get(v))throw s}},Oj=M0('<span class="item-toolbar__element-host svelte-rnx3ie"></span>'),WZ=M0('<span class="item-toolbar__nds-button-zoom svelte-rnx3ie"><nds-icon-button></nds-icon-button></span>',2),Nj=M0('<span aria-hidden="true"></span>'),AJ=M0('<img class="item-toolbar__icon-image svelte-rnx3ie" alt=""/>'),fJ=M0('<i aria-hidden="true"></i>'),zZ=M0("<a><!></a>"),wZ=M0('<button type="button"><!></button>'),TJ=M0('<span class="item-toolbar__controls-host svelte-rnx3ie"></span>'),HZ=M0("<div></div>"),xZ=M0('<div><div class="item-toolbar__tools-row svelte-rnx3ie"><!> <!> <!></div> <!></div>'),BZ={hash:"svelte-rnx3ie",code:`.item-toolbar.svelte-rnx3ie {display:flex;flex-direction:column;align-items:flex-end;gap:0;--pie-toolbar-tools-row-height: 2rem;--pie-tts-controls-row-height: 2.875rem;}.item-toolbar__tools-row.svelte-rnx3ie {display:flex;align-items:center;justify-content:flex-end;flex-wrap:nowrap;
+import{B as bJ,C as H0,D as S0,E as pJ,F as L0,G as I0,H as _J,I as d,J as EJ,M as vJ,O as gJ,Q as $J,S as mj,T as hj,b as G0,c as SJ,d as IJ,e as N,f as a,g as w0,h as P0,i as CJ,j as $0,ja as mJ,k as K0,l as Gj,m as Y0,n as Q0,o as j,q as Pj,r as yJ,s as M0,t as U0,u as F,w as D0,x as Mj,y as e0,z as jj}from"./ItemToolBar-3cppre9r.js";function vj(v){return typeof v.href==="string"}function wJ(v){if(!v||typeof v!=="object"||Array.isArray(v))return!1;let q=v;if(typeof q.id!=="string"||q.id.trim().length===0)return!1;if(typeof q.label!=="string"||q.label.trim().length===0)return!1;if(q.ariaLabel!==void 0&&typeof q.ariaLabel!=="string")return!1;if(q.icon!==void 0&&typeof q.icon!=="string")return!1;if(q.tooltip!==void 0&&typeof q.tooltip!=="string")return!1;if(q.active!==void 0&&typeof q.active!=="boolean")return!1;if(q.disabled!==void 0&&typeof q.disabled!=="boolean")return!1;let s=typeof q.href==="string",m0=typeof q.onClick==="function";if(s===m0)return!1;if(s)return!0;return m0}function gj(v){return typeof v==="string"&&v.trimStart().startsWith("<svg")}function $j(v){return typeof v==="string"&&v.trimStart().startsWith("http")}import{sanitizeSvgIcon as Yj}from"@pie-players/pie-players-shared/security";import{approximateZoomFromWidths as qZ,computeZoomCompensation as FZ,ICON_BUTTON_ZOOM_OPTIONS as HJ}from"@pie-players/pie-players-shared/ui/zoom-compensation";import{createFocusTrap as kZ,FOCUSABLE_SELECTOR as xJ,isProgrammaticFocusTarget as BJ}from"@pie-players/pie-players-shared";import"@pie-players/pie-players-shared/nds-icon-button";var RZ=(v,q)=>{if(customElements.get(v))return;try{customElements.define(v,q)}catch(s){if(!(s instanceof DOMException&&s.name==="NotSupportedError"||s&&typeof s==="object"&&s.name==="NotSupportedError")||!customElements.get(v))throw s}},Oj=M0('<span class="item-toolbar__element-host svelte-rnx3ie"></span>'),WZ=M0('<span class="item-toolbar__nds-button-zoom svelte-rnx3ie"><nds-icon-button></nds-icon-button></span>',2),Nj=M0('<span aria-hidden="true"></span>'),AJ=M0('<img class="item-toolbar__icon-image svelte-rnx3ie" alt=""/>'),fJ=M0('<i aria-hidden="true"></i>'),zZ=M0("<a><!></a>"),wZ=M0('<button type="button"><!></button>'),TJ=M0('<span class="item-toolbar__controls-host svelte-rnx3ie"></span>'),HZ=M0("<div></div>"),xZ=M0('<div><div class="item-toolbar__tools-row svelte-rnx3ie"><!> <!> <!></div> <!></div>'),BZ={hash:"svelte-rnx3ie",code:`.item-toolbar.svelte-rnx3ie {display:flex;flex-direction:column;align-items:flex-end;gap:0;--pie-toolbar-tools-row-height: 2rem;--pie-tts-controls-row-height: 2.875rem;}.item-toolbar__tools-row.svelte-rnx3ie {display:flex;align-items:center;justify-content:flex-end;flex-wrap:nowrap;
 		/* Cap the gap between toolbar items (e.g. TTS play ↔ calculator) at its
 		   200%-zoom size with the same factor the buttons use, so the spacing
 		   doesn't keep growing past 200% while the buttons themselves freeze. */gap:calc(0.5rem * var(--pie-toolbar-zoom-comp, 1));min-height:var(--pie-toolbar-tools-row-height);}.item-toolbar__controls-row.svelte-rnx3ie {display:flex;align-items:center;justify-content:flex-end;width:100%;min-height:0;height:auto;}.item-toolbar__controls-row--reserve.svelte-rnx3ie {min-height:var(--pie-tts-controls-row-height);height:var(--pie-tts-controls-row-height);}.item-toolbar__controls-row--active.svelte-rnx3ie {min-height:var(--pie-tts-controls-row-height);height:var(--pie-tts-controls-row-height);}.item-toolbar__controls-row--align-start.svelte-rnx3ie {justify-content:flex-start;}.item-toolbar__controls-host.svelte-rnx3ie {display:inline-flex;align-items:center;justify-content:flex-end;width:100%;}.item-toolbar--top.svelte-rnx3ie,

package/dist/index.d.ts

@@ -10,11 +10,12 @@ export type { AssessmentToolkitHostRuntimeContext, AssessmentToolkitRegionScopeC
 export type { TTSHighlightContext, TTSHighlightTargetResolver, TTSHighlightTargetResolverProvider, TTSHighlightTargetResolverRuntime, } from "./services/tts/highlight-target-resolver.js";
 export { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "./context/assessment-toolkit-context.js";
 export { connectAssessmentToolkitHostRuntimeContext, connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "./context/runtime-context-consumer.js";
+export { catalogOwnerContextFor, collectCatalogRegistrations, collectEntityCatalogRegistrations, type CatalogOwnerIdentity, type CatalogRegistration, type CatalogSourceEntity, } from "./runtime/catalog-registration.js";
 export { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, PIE_REGISTER_EVENT, PIE_UNREGISTER_EVENT, type InternalContentLoadedDetail, type InternalItemSessionChangedDetail, type InternalItemPlayerErrorDetail, type ItemSessionChangedDetail, type RuntimeRegistrationDetail, type RuntimeRegistrationKind, } from "./runtime/registration-events.js";
 export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createCrossBoundaryEvent, dispatchCrossBoundaryEvent, isContextValueDefined, } from "./runtime/tool-host-contract.js";
 export type { AccessibilityCatalogResolverApi, ElementToolStateStoreApi, HighlightCoordinatorApi, I18nServiceApi, ThemeProviderApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi, ToolState, } from "./services/interfaces.js";
-export type { CatalogLookupContext, CatalogLookupOptions, CatalogOwnerContext, CatalogOwnerKind, CatalogStatistics, CatalogType, ResolvedCatalog, } from "./services/AccessibilityCatalogResolver.js";
-export { AccessibilityCatalogResolver } from "./services/AccessibilityCatalogResolver.js";
+export type { CatalogCardForm, CatalogChangeEvent, CatalogChangeListener, CatalogChangeReason, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerContext, CatalogOwnerKind, CatalogStatistics, CatalogType, ResolvedCatalog, } from "./services/AccessibilityCatalogResolver.js";
+export { AccessibilityCatalogResolver, catalogCardForm, isKnownCatalogType, KNOWN_CATALOG_TYPES, } from "./services/AccessibilityCatalogResolver.js";
 export { ContextVariableStore } from "./services/ContextVariableStore.js";
 export { ElementToolStateStore } from "./services/ElementToolStateStore.js";
 export type { Annotation } from "./services/HighlightCoordinator.js";
@@ -30,10 +31,14 @@ export { extractTextContent, hasChoiceInteraction, hasMathContent, hasReadableTe
 export { DEFAULT_TOOL_PLACEMENT, DEFAULT_TOOL_ORDER, createPackagedToolRegistry, PACKAGED_TOOL_PLACEMENT, registerPackagedTools, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./services/createDefaultToolRegistry.js";
 export type { CreateToolsConfigArgs } from "./services/create-tools-config.js";
 export { createToolsConfig } from "./services/create-tools-config.js";
-export { DEFAULT_PERSONAL_NEEDS_PROFILE, createDefaultPersonalNeedsProfile, } from "./services/defaultPersonalNeedsProfile.js";
+export { ACCOMMODATION_ONLY_SUPPORT_IDS, DEFAULT_PERSONAL_NEEDS_PROFILE, createDefaultPersonalNeedsProfile, } from "./services/defaultPersonalNeedsProfile.js";
 export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverrides, ToolTagMap, } from "./tools/tool-tag-map.js";
 export { createToolElement, DEFAULT_TOOL_TAG_MAP, resolveToolTag, toToolIdFromTag, } from "./tools/tool-tag-map.js";
 export { ALL_STANDARD_ACCESS_FEATURES, EXAMPLE_PNP_CONFIGURATIONS, getFeatureCategory, getFeaturesInCategory, isStandardAccessFeature, QTI_STANDARD_ACCESS_FEATURES, } from "./services/pnp-standard-features.js";
+export type { SignLanguageMedia } from "./services/sign-language-cards.js";
+export { AMERICAN_SIGN_LANGUAGE, applyMediaFragment, describeSignLanguage, isSignLanguageCard, matchesRequestedSignLanguage, resolveSignLanguageMedia, SIGN_LANGUAGE_CATALOG_TYPE, } from "./services/sign-language-cards.js";
+export type { SpokenAudioMedia } from "./services/spoken-audio-cards.js";
+export { resolveSpokenAudioMedia, SPOKEN_CATALOG_TYPE, } from "./services/spoken-audio-cards.js";
 export type { ExtractionResult } from "./services/SSMLExtractor.js";
 export { SSMLExtractor } from "./services/SSMLExtractor.js";
 export type { FontSize, ThemeConfig } from "./services/ThemeProvider.js";

package/dist/index.js

@@ -8,9 +8,10 @@
  */
 export { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "./context/assessment-toolkit-context.js";
 export { connectAssessmentToolkitHostRuntimeContext, connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "./context/runtime-context-consumer.js";
+export { catalogOwnerContextFor, collectCatalogRegistrations, collectEntityCatalogRegistrations, } from "./runtime/catalog-registration.js";
 export { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_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 } from "./services/AccessibilityCatalogResolver.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";
 // Element Tool State Store (Element-level ephemeral tool state)
@@ -22,10 +23,12 @@ export { ToolRegistry } from "./services/ToolRegistry.js";
 export { extractTextContent, hasChoiceInteraction, hasMathContent, hasReadableText, isAssessmentContext, isElementContext, isItemContext, isPassageContext, isRubricContext, isSectionContext, } from "./services/tool-context.js";
 export { DEFAULT_TOOL_PLACEMENT, DEFAULT_TOOL_ORDER, createPackagedToolRegistry, PACKAGED_TOOL_PLACEMENT, registerPackagedTools, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./services/createDefaultToolRegistry.js";
 export { createToolsConfig } from "./services/create-tools-config.js";
-export { DEFAULT_PERSONAL_NEEDS_PROFILE, createDefaultPersonalNeedsProfile, } from "./services/defaultPersonalNeedsProfile.js";
+export { ACCOMMODATION_ONLY_SUPPORT_IDS, DEFAULT_PERSONAL_NEEDS_PROFILE, createDefaultPersonalNeedsProfile, } from "./services/defaultPersonalNeedsProfile.js";
 export { createToolElement, DEFAULT_TOOL_TAG_MAP, 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";
+export { AMERICAN_SIGN_LANGUAGE, applyMediaFragment, describeSignLanguage, isSignLanguageCard, matchesRequestedSignLanguage, resolveSignLanguageMedia, SIGN_LANGUAGE_CATALOG_TYPE, } from "./services/sign-language-cards.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

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

@@ -21,6 +21,7 @@ import type { CanonicalToolsConfig, ToolPlacementLevel } from "../../services/to
 import type { ToolRegistry } from "../../services/ToolRegistry.js";
 import type { ToolPolicyDecision, ToolPolicyDecisionRequest } 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;
@@ -88,6 +89,26 @@ export declare class ToolPolicyEngine {
      * cached `ToolPolicyDecision` rather than re-call `decide(...)`.
      */
     decide(request: ToolPolicyDecisionRequest): ToolPolicyDecision;
+    /**
+     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * precedence, independent of toolbar placement.
+     *
+     * For capabilities that render as their own surface rather than a toolbar
+     * button — a signed alternate's region, for example — `decide(...)` cannot
+     * answer the question, because such a capability is deliberately absent from
+     * `tools.placement` and would read as "removed by policy" when nothing of
+     * the sort happened. See {@link FeaturePolicyDecision}.
+     *
+     * `pnpEnforcement` is deliberately **not** consulted here. That flag governs
+     * whether PNP/profile policy *refines* an otherwise-visible tool set; a
+     * feature with no placement has no unrefined baseline to fall back to, so
+     * skipping the PNP read would make the capability permanently unavailable
+     * rather than merely unrefined. Auto-mode already flips enforcement on
+     * whenever profile material exists, so this only diverges for a host that
+     * explicitly forces `"off"` while supplying a profile that grants the
+     * feature — and there, honouring the profile is the safer failure.
+     */
+    decideFeature(featureId: string): FeaturePolicyDecision;
     /**
      * Convenience wrapper for hosts that just want the visible tool
      * IDs. Equivalent to `decide(...).visibleTools.map(e => e.toolId)`.

package/dist/policy/core/ToolPolicyEngine.js

@@ -17,6 +17,7 @@
  * `ToolkitCoordinator`. PR 3 switches `<pie-item-toolbar>` over.
  */
 import { normalizeToolsConfig } from "../../services/tools-config-normalizer.js";
+import { interpretFeatureResult } from "./feature-decision.js";
 import { composeDecision } from "./compose-decision.js";
 import { resolveDefaultPnpEnforcement } from "./pnp-policy-inputs.js";
 import { PnpPolicySource } from "../sources/PnpPolicySource.js";
@@ -85,6 +86,32 @@ export class ToolPolicyEngine {
             contextId: requestContextId,
         });
     }
+    /**
+     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * precedence, independent of toolbar placement.
+     *
+     * For capabilities that render as their own surface rather than a toolbar
+     * button — a signed alternate's region, for example — `decide(...)` cannot
+     * answer the question, because such a capability is deliberately absent from
+     * `tools.placement` and would read as "removed by policy" when nothing of
+     * the sort happened. See {@link FeaturePolicyDecision}.
+     *
+     * `pnpEnforcement` is deliberately **not** consulted here. That flag governs
+     * whether PNP/profile policy *refines* an otherwise-visible tool set; a
+     * feature with no placement has no unrefined baseline to fall back to, so
+     * skipping the PNP read would make the capability permanently unavailable
+     * rather than merely unrefined. Auto-mode already flips enforcement on
+     * whenever profile material exists, so this only diverges for a host that
+     * explicitly forces `"off"` while supplying a profile that grants the
+     * feature — and there, honouring the profile is the safer failure.
+     */
+    decideFeature(featureId) {
+        this.assertNotDisposed();
+        return interpretFeatureResult(featureId, this.pnpPolicySource.resolveFeature(featureId, {
+            assessment: this.assessment ?? undefined,
+            currentItemRef: this.currentItemRef ?? undefined,
+        }));
+    }
     /**
      * Convenience wrapper for hosts that just want the visible tool
      * IDs. Equivalent to `decide(...).visibleTools.map(e => e.toolId)`.

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

@@ -0,0 +1,57 @@
+/**
+ * Feature policy decisions — eligibility for policy-addressable capabilities
+ * that are not toolbar tools.
+ *
+ * "Tool" in this codebase means *policy-addressable capability*, not "gadget on
+ * a toolbar" (see `docs/tools-and-accomodations/architecture.md`). Most such
+ * capabilities render as toolbar surfaces, so the engine's main answer is a
+ * placement-scoped `ToolPolicyDecision`. Some do not: a signed alternate renders
+ * as its own region and is never placed on a toolbar, so asking
+ * `decide({ level: "item", ... })` about it would answer the wrong question —
+ * it would be absent because it is not in `tools.placement.item`, not because
+ * policy said no.
+ *
+ * A feature decision answers only the eligibility half: *did policy grant this
+ * feature id?* Whether the capability has anything to show is a separate,
+ * independent check owned by its renderer — for signing, whether a matching
+ * catalog card exists. Both are required; neither implies the other.
+ */
+import type { PnpPolicyResult } from "../sources/PnpPolicySource.js";
+import type { PnpPolicySourceRule } from "./policy-source-tag.js";
+import type { ToolPolicyResolutionDecision, ToolPolicySourceType } from "./provenance.js";
+export interface FeaturePolicyDecision {
+    /** The PNP/AfA support id that was evaluated (e.g. `"signLanguage"`). */
+    featureId: string;
+    /**
+     * `true` only when policy explicitly granted the feature at one of the six
+     * precedence levels. A feature nobody configured is **not** available —
+     * accommodations require a documented need, so silence means no.
+     */
+    granted: boolean;
+    action: ToolPolicyResolutionDecision["action"];
+    /** Which precedence rule produced the verdict. */
+    rule: PnpPolicySourceRule;
+    precedence: 1 | 2 | 3 | 4 | 5 | 6;
+    sourceType: ToolPolicySourceType;
+    /** Human-readable explanation, suitable for a policy debugger. */
+    reason: string;
+    /**
+     * `true` when the grant is a mandate (item or district `requiredTools`)
+     * rather than a student-profile support.
+     */
+    required: boolean;
+    /**
+     * Feature parameters resolved from item `toolParameters` then assessment
+     * `toolConfigs`, keyed by the feature id. The seam a later configurable
+     * presentation would hang on; no vocabulary is defined yet.
+     */
+    parameters?: unknown;
+}
+/**
+ * Interpret a single-feature `PnpPolicySource.resolveFeature(...)` result.
+ *
+ * `resolveFeature` evaluates exactly one support id, so the result carries
+ * exactly one decision and at most one flags entry — no mapped-tool-id
+ * bookkeeping is needed to read it back out.
+ */
+export declare function interpretFeatureResult(featureId: string, result: PnpPolicyResult): FeaturePolicyDecision;

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

@@ -0,0 +1,40 @@
+/**
+ * Feature policy decisions — eligibility for policy-addressable capabilities
+ * that are not toolbar tools.
+ *
+ * "Tool" in this codebase means *policy-addressable capability*, not "gadget on
+ * a toolbar" (see `docs/tools-and-accomodations/architecture.md`). Most such
+ * capabilities render as toolbar surfaces, so the engine's main answer is a
+ * placement-scoped `ToolPolicyDecision`. Some do not: a signed alternate renders
+ * as its own region and is never placed on a toolbar, so asking
+ * `decide({ level: "item", ... })` about it would answer the wrong question —
+ * it would be absent because it is not in `tools.placement.item`, not because
+ * policy said no.
+ *
+ * A feature decision answers only the eligibility half: *did policy grant this
+ * feature id?* Whether the capability has anything to show is a separate,
+ * independent check owned by its renderer — for signing, whether a matching
+ * catalog card exists. Both are required; neither implies the other.
+ */
+/**
+ * Interpret a single-feature `PnpPolicySource.resolveFeature(...)` result.
+ *
+ * `resolveFeature` evaluates exactly one support id, so the result carries
+ * exactly one decision and at most one flags entry — no mapped-tool-id
+ * bookkeeping is needed to read it back out.
+ */
+export function interpretFeatureResult(featureId, result) {
+    const decision = result.decisions[0];
+    const flags = Array.from(result.perToolFlags.values())[0];
+    return {
+        featureId,
+        granted: decision?.action === "enable",
+        action: decision?.action ?? "skip",
+        rule: decision?.rule ?? "pnp-support",
+        precedence: decision?.precedence ?? 6,
+        sourceType: decision?.sourceType ?? "system",
+        reason: decision?.reason ?? `Feature "${featureId}" not configured`,
+        required: Boolean(flags?.required),
+        parameters: flags?.settings,
+    };
+}

package/dist/policy/engine.d.ts

@@ -21,6 +21,7 @@
  */
 export { ToolPolicyEngine, type PnpEnforcementMode, type ResolvedEngineInputs, type ToolPolicyChangeEvent, type ToolPolicyChangeListener, type ToolPolicyEngineArgs, type ToolPolicyEngineInputs, } from "./core/ToolPolicyEngine.js";
 export { TOOL_POLICY_ENGINE_KEY, type ToolPolicyEngineContext, } from "./core/engine-context.js";
+export type { FeaturePolicyDecision } from "./core/feature-decision.js";
 export type { RequiredToolBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, } from "./core/decision-types.js";
 export type { PolicySource, PolicySourceDecisionContext, PolicySourceProvenanceEntry, PolicySourceResult, } from "./core/PolicySource.js";
 export type { PolicySourceTag, PnpPolicySourceRule, PnpPolicySourceTag, CustomPolicySourceTag, } from "./core/policy-source-tag.js";

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

@@ -88,6 +88,28 @@ export declare class PnpPolicySource {
     private readonly toolRegistry;
     constructor(toolRegistry: ToolRegistry);
     apply(args: PnpPolicyApplyArgs): PnpPolicyResult;
+    /**
+     * Evaluate exactly one PNP support id through the same six-level
+     * precedence `apply(...)` uses.
+     *
+     * This exists for **policy-addressable capabilities that are not toolbar
+     * tools** — a signed alternate rendered as its own region, for example.
+     * `apply(...)` only evaluates support ids that appear somewhere in the
+     * bound policy inputs, and it keys its result maps by *mapped tool id*, so
+     * a caller asking about one feature would have to re-derive that mapping
+     * and could collide with another support id that maps to the same tool.
+     * Evaluating one id in isolation avoids both problems: the returned result
+     * carries exactly one decision, and `decisions[0].action` is the verdict.
+     *
+     * Reusing `resolveSupport(...)` rather than re-walking the precedence rules
+     * is the point — a second copy of the six levels would drift.
+     */
+    resolveFeature(featureId: string, args: PnpPolicyApplyArgs): PnpPolicyResult;
+    /**
+     * Build the rule-evaluation context and the empty result (with its
+     * configuration-source attribution) from the bound policy inputs.
+     */
+    private prepare;
     private resolveSupport;
     /**
      * Map a QTI / PNP support id (e.g. `"calculator-basic"`) to the

package/dist/policy/sources/PnpPolicySource.js

@@ -14,6 +14,46 @@ export class PnpPolicySource {
         this.toolRegistry = toolRegistry;
     }
     apply(args) {
+        const { ctx, result } = this.prepare(args);
+        const { pnp, districtPolicy, itemSettings } = ctx;
+        const allSupports = new Set();
+        pnp?.supports?.forEach((s) => allSupports.add(s));
+        pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
+        districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
+        districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
+        itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
+        itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
+        for (const supportId of allSupports) {
+            this.resolveSupport(supportId, ctx, result);
+        }
+        return result;
+    }
+    /**
+     * Evaluate exactly one PNP support id through the same six-level
+     * precedence `apply(...)` uses.
+     *
+     * This exists for **policy-addressable capabilities that are not toolbar
+     * tools** — a signed alternate rendered as its own region, for example.
+     * `apply(...)` only evaluates support ids that appear somewhere in the
+     * bound policy inputs, and it keys its result maps by *mapped tool id*, so
+     * a caller asking about one feature would have to re-derive that mapping
+     * and could collide with another support id that maps to the same tool.
+     * Evaluating one id in isolation avoids both problems: the returned result
+     * carries exactly one decision, and `decisions[0].action` is the verdict.
+     *
+     * Reusing `resolveSupport(...)` rather than re-walking the precedence rules
+     * is the point — a second copy of the six levels would drift.
+     */
+    resolveFeature(featureId, args) {
+        const { ctx, result } = this.prepare(args);
+        this.resolveSupport(featureId, ctx, result);
+        return result;
+    }
+    /**
+     * Build the rule-evaluation context and the empty result (with its
+     * configuration-source attribution) from the bound policy inputs.
+     */
+    prepare(args) {
         const { assessment, currentItemRef } = args;
         const pnp = assessment?.personalNeedsProfile;
         const settings = assessment?.settings;
@@ -46,13 +86,6 @@ export class PnpPolicySource {
                 config: itemSettings,
             };
         }
-        const allSupports = new Set();
-        pnp?.supports?.forEach((s) => allSupports.add(s));
-        pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
-        settings?.districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
-        settings?.districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
-        itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
-        itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
         const ctx = {
             pnp,
             districtPolicy: settings?.districtPolicy,
@@ -60,10 +93,7 @@ export class PnpPolicySource {
             itemSettings,
             toolConfigs: settings?.toolConfigs,
         };
-        for (const supportId of allSupports) {
-            this.resolveSupport(supportId, ctx, result);
-        }
-        return result;
+        return { ctx, result };
     }
     resolveSupport(supportId, ctx, out) {
         // 1. District block (absolute veto)

package/dist/runtime/catalog-registration.d.ts

@@ -1,6 +1,19 @@
+/**
+ * Where accessibility catalogs live on a rendered entity, and which owner scope
+ * each one belongs to.
+ *
+ * Catalogs are placed dynamically: a shell registers what its entity carries
+ * when it mounts, and readers (TTS, the item card's media region) resolve by
+ * identifier within an owner scope. Both sides therefore have to agree on two
+ * facts — the three places catalogs can hang off an entity, and the owner
+ * context each one is filed under. This module is the only place either is
+ * decided, so a reader cannot look up a scope registration never wrote.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
 import type { AccessibilityCatalog } from "@pie-players/pie-players-shared/types";
 import type { CatalogOwnerContext } from "../services/AccessibilityCatalogResolver.js";
-import type { RuntimeRegistrationDetail } from "./registration-events.js";
+import type { RuntimeRegistrationDetail, RuntimeRegistrationKind } from "./registration-events.js";
 export interface CatalogRegistrationRuntimeContext {
     assessmentId?: string;
     sectionId?: string;
@@ -9,4 +22,46 @@ export interface CatalogRegistration {
     context: CatalogOwnerContext;
     catalogs: AccessibilityCatalog[];
 }
+/** The entity shape catalogs hang off: an item, or a passage. */
+export interface CatalogSourceEntity {
+    accessibilityCatalogs?: AccessibilityCatalog[];
+    config?: {
+        extractedCatalogs?: AccessibilityCatalog[];
+        models?: Array<{
+            id?: string;
+            accessibilityCatalogs?: AccessibilityCatalog[];
+        }>;
+    };
+}
+/** Who is rendering the entity — everything owner scoping is derived from. */
+export interface CatalogOwnerIdentity {
+    kind: RuntimeRegistrationKind;
+    /** The rendered instance id. */
+    itemId: string;
+    canonicalItemId?: string;
+    assessmentId?: string;
+    sectionId?: string;
+}
+/**
+ * The owner context an entity's catalogs are registered under, and therefore the
+ * one a reader must look them up with.
+ *
+ * Exported because readers construct the lookup context themselves: the
+ * resolver matches contexts field by field, so a reader that hand-assembled its
+ * own would silently resolve nothing the day either side gained a field.
+ */
+export declare function catalogOwnerContextFor(owner: CatalogOwnerIdentity): CatalogOwnerContext;
+/**
+ * Every catalog an entity carries, paired with the owner scope it belongs in.
+ *
+ * Three places carry catalogs, and the distinction matters to resolution rather
+ * than only to bookkeeping: entity-level `accessibilityCatalogs` and
+ * extractor-generated `config.extractedCatalogs` are filed against the entity,
+ * while a model's own catalogs are filed against that model, so two models on
+ * one item can use the same catalog identifier without colliding.
+ *
+ * Passages have no models, so the walk stops after the entity-level pair.
+ */
+export declare function collectEntityCatalogRegistrations(entity: CatalogSourceEntity | null | undefined, owner: CatalogOwnerIdentity): CatalogRegistration[];
+/** Adapter for the runtime registration event a shell dispatches on mount. */
 export declare function collectCatalogRegistrations(detail: RuntimeRegistrationDetail, runtime?: CatalogRegistrationRuntimeContext): CatalogRegistration[];

package/dist/runtime/catalog-registration.js

@@ -1,53 +1,86 @@
+/**
+ * Where accessibility catalogs live on a rendered entity, and which owner scope
+ * each one belongs to.
+ *
+ * Catalogs are placed dynamically: a shell registers what its entity carries
+ * when it mounts, and readers (TTS, the item card's media region) resolve by
+ * identifier within an owner scope. Both sides therefore have to agree on two
+ * facts — the three places catalogs can hang off an entity, and the owner
+ * context each one is filed under. This module is the only place either is
+ * decided, so a reader cannot look up a scope registration never wrote.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
 const hasCatalogs = (catalogs) => Array.isArray(catalogs) && catalogs.length > 0;
-export function collectCatalogRegistrations(detail, runtime = {}) {
-    const entity = detail.item;
-    if (!entity)
-        return [];
-    const registrations = [];
-    if (detail.kind === "passage") {
-        const context = {
+/**
+ * The owner context an entity's catalogs are registered under, and therefore the
+ * one a reader must look them up with.
+ *
+ * Exported because readers construct the lookup context themselves: the
+ * resolver matches contexts field by field, so a reader that hand-assembled its
+ * own would silently resolve nothing the day either side gained a field.
+ */
+export function catalogOwnerContextFor(owner) {
+    if (owner.kind === "passage") {
+        return {
             ownerKind: "passage",
-            assessmentId: runtime.assessmentId,
-            sectionId: runtime.sectionId,
-            passageId: detail.canonicalItemId || detail.itemId,
+            assessmentId: owner.assessmentId,
+            sectionId: owner.sectionId,
+            passageId: owner.canonicalItemId || owner.itemId,
         };
-        if (hasCatalogs(entity.accessibilityCatalogs)) {
-            registrations.push({ context, catalogs: entity.accessibilityCatalogs });
-        }
-        if (hasCatalogs(entity.config?.extractedCatalogs)) {
-            registrations.push({
-                context,
-                catalogs: entity.config.extractedCatalogs,
-            });
-        }
-        return registrations;
     }
-    const itemContext = {
+    return {
         ownerKind: "itemModel",
-        assessmentId: runtime.assessmentId,
-        sectionId: runtime.sectionId,
-        itemId: detail.itemId,
-        canonicalItemId: detail.canonicalItemId || detail.itemId,
+        assessmentId: owner.assessmentId,
+        sectionId: owner.sectionId,
+        itemId: owner.itemId,
+        canonicalItemId: owner.canonicalItemId || owner.itemId,
     };
+}
+/**
+ * Every catalog an entity carries, paired with the owner scope it belongs in.
+ *
+ * Three places carry catalogs, and the distinction matters to resolution rather
+ * than only to bookkeeping: entity-level `accessibilityCatalogs` and
+ * extractor-generated `config.extractedCatalogs` are filed against the entity,
+ * while a model's own catalogs are filed against that model, so two models on
+ * one item can use the same catalog identifier without colliding.
+ *
+ * Passages have no models, so the walk stops after the entity-level pair.
+ */
+export function collectEntityCatalogRegistrations(entity, owner) {
+    if (!entity)
+        return [];
+    const context = catalogOwnerContextFor(owner);
+    const registrations = [];
     if (hasCatalogs(entity.accessibilityCatalogs)) {
-        registrations.push({
-            context: itemContext,
-            catalogs: entity.accessibilityCatalogs,
-        });
+        registrations.push({ context, catalogs: entity.accessibilityCatalogs });
     }
     if (hasCatalogs(entity.config?.extractedCatalogs)) {
         registrations.push({
-            context: itemContext,
+            context,
             catalogs: entity.config.extractedCatalogs,
         });
     }
+    if (owner.kind === "passage")
+        return registrations;
     for (const model of entity.config?.models ?? []) {
         if (!hasCatalogs(model.accessibilityCatalogs))
             continue;
         registrations.push({
-            context: { ...itemContext, modelId: model.id },
+            context: { ...context, modelId: model.id },
             catalogs: model.accessibilityCatalogs,
         });
     }
     return registrations;
 }
+/** Adapter for the runtime registration event a shell dispatches on mount. */
+export function collectCatalogRegistrations(detail, runtime = {}) {
+    return collectEntityCatalogRegistrations(detail.item, {
+        kind: detail.kind,
+        itemId: detail.itemId,
+        canonicalItemId: detail.canonicalItemId,
+        assessmentId: runtime.assessmentId,
+        sectionId: runtime.sectionId,
+    });
+}