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

package/dist/services/interfaces.d.ts

@@ -8,48 +8,28 @@
  * Part of PIE Assessment Toolkit.
  */
 import type { I18nServiceApi } from "@pie-players/pie-players-shared/i18n";
-import type { AccessibilityCatalog } from "@pie-players/pie-players-shared/types";
-import type { AccessibilityCatalogResolver, CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerRegistration, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
+import type { AccessibilityCatalog, SectionControllerSessionState } from "@pie-players/pie-players-shared/types";
+import type { CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerRegistration, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
 import type { CatalogOwnerContext } from "./catalog-owner.js";
 import type { FrameworkErrorListener } from "./framework-error-bus.js";
 import type { FrameworkErrorModel } from "./framework-error.js";
-import type { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
-import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks, ToolkitInitStatus, TTSToolConfig } from "./ToolkitCoordinator.js";
-import type { ThemeConfig } from "./ThemeProvider.js";
+import type { ToolFailurePhase } from "./tool-failure.js";
+import type { Annotation, HighlightColor } from "./HighlightCoordinator.js";
+import type { SerializedRange } from "./RangeSerializer.js";
+import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks } from "./ToolkitCoordinator.js";
+import type { ElementIdComponents } from "./ElementToolStateStore.js";
 import type { ZIndexLayer } from "./ToolCoordinator.js";
-import type { PlaybackState, TTSConfig } from "./TTSService.js";
+import type { PlaybackState } from "./TTSService.js";
 import type { TTSHighlightTargetResolverProvider } from "./tts/highlight-target-resolver.js";
-import type { ToolPlacementConfig, ToolPlacementLevel, ToolProviderConfig } from "./tools-config-normalizer.js";
+import type { TextToSpeechToolProviderConfig, ToolPlacementConfig, ToolProviderConfig } from "./tools-config-normalizer.js";
+import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { ToolProviderRegistry } from "./tool-providers/ToolProviderRegistry.js";
-import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest } from "../policy/engine.js";
-import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
-import type { ITTSProvider, TTSProviderCapabilities } from "@pie-players/pie-tts";
-import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
+import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolScope } from "../policy/engine.js";
+import type { AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { TTSConfig } from "@pie-players/pie-tts";
+import type { ResolvedToolContext, ToolContextResolverContext, ToolRegistry } from "./ToolRegistry.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
 export type { I18nServiceApi };
-/**
- * Theme provider interface
- *
- * Applies consistent accessibility theming across items and tools.
- */
-export interface ThemeProviderApi {
-    /**
-     * Apply theme configuration
-     */
-    applyTheme(config: ThemeConfig): void;
-    /**
-     * Get current theme configuration
-     */
-    getCurrentTheme(): Required<ThemeConfig>;
-    /**
-     * Reset to default theme
-     */
-    reset(): void;
-    /**
-     * Clean up and remove theme styles
-     */
-    destroy(): void;
-}
 /**
  * Highlight coordinator interface
  *
@@ -57,13 +37,11 @@ export interface ThemeProviderApi {
  */
 export interface HighlightCoordinatorApi {
     /**
-     * Highlight a text range
-     */
-    highlightRange(range: Range, type: HighlightType, color: HighlightColor): void;
-    /**
-     * Highlight a word for TTS (temporary)
+     * Highlight the word being read (temporary): one range per tree the word
+     * spans, all painted, so a word split across inline elements highlights
+     * whole.
      */
-    highlightTTSWord(textNode: Text, startOffset: number, endOffset: number): void;
+    highlightTTSWord(ranges: Range[]): void;
     /**
      * Highlight a single element as the active TTS word (temporary).
      *
@@ -73,40 +51,64 @@ export interface HighlightCoordinatorApi {
      * (e.g. `<mjx-mi><mjx-c/></mjx-mi>`) and whole-expression fallbacks. Painting
      * the element itself is what lets a resolved math token highlight as a token
      * rather than escalating to the full `<math>` / `<mjx-container>`.
-     *
-     * Optional so lightweight coordinator mocks can omit it.
      */
-    highlightTTSWordElement?(element: Element): void;
+    highlightTTSWordElement(element: Element): void;
     /**
      * Highlight sentence(s) for TTS (background layer)
      */
     highlightTTSSentence(ranges: Range[]): void;
     /**
      * Highlight sentence/block element targets for TTS (background layer).
-     *
-     * Optional so lightweight coordinator mocks can omit it.
      */
-    highlightTTSSentenceElements?(elements: Element[]): void;
+    highlightTTSSentenceElements(elements: Element[]): void;
     /**
      * Clear all TTS highlights (word and sentence)
      */
     clearTTS(): void;
     /**
-     * Clear highlights of a specific type
+     * Clear the TTS word highlight, keeping the sentence highlight
      */
-    clearHighlights(type: HighlightType): void;
+    clearTTSWord(): void;
     /**
-     * Clear all highlights
+     * Record a learner annotation over a range.
+     *
+     * @returns Annotation id for later lookup or removal
      */
-    clearAll(): void;
+    addAnnotation(range: Range, color?: HighlightColor): string;
     /**
-     * Check if highlighting is supported in current environment
+     * Remove one annotation
      */
-    isSupported(): boolean;
+    removeAnnotation(id: string): void;
     /**
-     * Update TTS highlight style dynamically
+     * Remove all annotations
      */
-    updateTTSHighlightStyle(color: string, opacity: number): void;
+    clearAnnotations(): void;
+    /**
+     * All recorded annotations
+     */
+    getAnnotations(): Annotation[];
+    /**
+     * One annotation by id
+     */
+    getAnnotation(id: string): Annotation | null;
+    /**
+     * Serialize annotations relative to `root` for persistence
+     */
+    exportAnnotations(root?: Element): Array<SerializedRange & {
+        id: string;
+        color: HighlightColor;
+        timestamp: number;
+    }>;
+    /**
+     * Restore annotations serialized by `exportAnnotations` against the same root
+     *
+     * @returns Number of annotations restored
+     */
+    importAnnotations(data: Array<SerializedRange & {
+        id?: string;
+        color: HighlightColor;
+        timestamp?: number;
+    }>, root?: Element): number;
 }
 /**
  * Tool state interface
@@ -118,6 +120,11 @@ export interface ToolState {
     element: HTMLElement | null;
     layer: ZIndexLayer;
 }
+/** Narrows tool-state queries to the instances of one tool. */
+export interface ToolStateFilter {
+    /** Base tool id, such as `calculator`, matching every scoped instance of it. */
+    baseId?: string;
+}
 /**
  * Tool coordinator interface
  *
@@ -167,14 +174,44 @@ export interface ToolCoordinatorApi {
      */
     getToolState(id: string): ToolState | undefined;
     /**
-     * Get all visible tools
+     * Every visible tool, or with `{ baseId }` every visible instance of one
+     * tool, so a host need not parse scoped ids.
      */
-    getVisibleTools(): ToolState[];
+    getVisibleTools(filter?: ToolStateFilter): ToolState[];
+    /**
+     * Hide every visible tool, or every instance of one tool with `{ baseId }`.
+     */
+    hideAllTools(filter?: ToolStateFilter): void;
     /**
      * Subscribe to tool state changes
      */
     subscribe(listener: () => void): () => void;
 }
+/** Options for {@link TtsServiceApi.speak}. */
+export interface SpeakOptions {
+    /**
+     * The spoken card of the content root, read in place of its content when the
+     * target holds the whole root.
+     */
+    catalogId?: string;
+    /** The owner whose registered cards apply; without it only assessment-level cards do. */
+    catalogContext?: CatalogLookupContext;
+    /** BCP 47 language of the content read. */
+    language?: string;
+    /**
+     * For a range target, the content root that scopes highlighting and the
+     * offsets of the selection. Defaults to the range's nearest element. An
+     * element target is its own root.
+     */
+    contentRoot?: Element | null;
+    /**
+     * Who starts the read. The run carries it until the next read starts, a
+     * seek's restart included, and {@link TtsServiceApi.getRunOwner} reports it.
+     */
+    ownerId?: string;
+    /** The rate the read starts at; it stays the service's rate afterwards. */
+    rate?: number;
+}
 /**
  * TTS service interface
  *
@@ -183,24 +220,13 @@ export interface ToolCoordinatorApi {
  */
 export interface TtsServiceApi {
     /**
-     * Initialize TTS with a provider
-     */
-    initialize(provider: ITTSProvider, config?: Partial<TTSConfig>): Promise<void>;
-    /**
-     * Speak text with optional catalog support
+     * Read `target` aloud: a range reads the text it selects, an element its
+     * content. A node with a spoken card that the target holds whole reads its
+     * card, and math reads as math speech. Content marked not-to-be-spoken is
+     * never read; when nothing speakable remains, nothing is spoken and playback
+     * already running continues.
      */
-    speak(text: string, options?: {
-        catalogId?: string;
-        catalogContext?: CatalogLookupContext;
-        language?: string;
-        contentElement?: Element;
-    }): Promise<void>;
-    /**
-     * Speak a text range
-     */
-    speakRange(range: Range, options?: {
-        contentRoot?: Element | null;
-    }): Promise<void>;
+    speak(target: Range | Element, options?: SpeakOptions): Promise<void>;
     /**
      * Pause playback
      */
@@ -210,16 +236,15 @@ export interface TtsServiceApi {
      */
     resume(): void;
     /**
-     * Stop playback
+     * Stop playback and release the run owner. A read that ends on its own
+     * keeps its owner.
      */
     stop(): void;
     /**
-     * Request active TTS controls to hand off/deactivate their UI state.
-     *
-     * This is an orchestration hint for TTS tool chrome and does not replace
-     * playback controls such as stop/pause/resume.
+     * Stop, release the provider and drop every listener and timer. A disposed
+     * service cannot speak.
      */
-    requestControlHandoff(): void;
+    dispose(): void;
     /**
      * Seek forward by sentence units
      */
@@ -228,40 +253,21 @@ export interface TtsServiceApi {
      * Seek backward by sentence units
      */
     seekBackward(units?: number): Promise<void>;
-    /**
-     * Check if currently playing
-     */
-    isPlaying(): boolean;
-    /**
-     * Check if paused
-     */
-    isPaused(): boolean;
     /**
      * Get current playback state
      */
     getState(): PlaybackState;
     /**
-     * Get currently speaking text
+     * The `ownerId` the latest read started with, or null when it named none,
+     * nothing has been read or {@link stop} released it. A new read announces
+     * itself through {@link onStateChange} with `loading`, and a stop that
+     * releases an owner announces `idle`, so a listener sees the owner change.
      */
-    getCurrentText(): string | null;
+    getRunOwner(): string | null;
     /**
-     * Whether a catalog holds spoken content this service could speak.
-     * Optional: a service without one resolves a selection to the nearest
-     * docked catalog id.
+     * Subscribe to state changes. Returns the function that unsubscribes.
      */
-    hasSpokenAlternate?(catalogId: string, language?: string): boolean;
-    /**
-     * Subscribe to state changes
-     */
-    onStateChange(id: string, callback: (state: PlaybackState) => void): void;
-    /**
-     * Unsubscribe from state changes
-     */
-    offStateChange(id: string, callback: (state: PlaybackState) => void): void;
-    /**
-     * Get capabilities of current provider
-     */
-    getCapabilities(): TTSProviderCapabilities | null;
+    onStateChange(callback: (state: PlaybackState) => void): () => void;
     /**
      * Update TTS settings dynamically (rate, pitch, voice)
      */
@@ -270,18 +276,10 @@ export interface TtsServiceApi {
      * Update playback speed and apply it to active planned playback.
      */
     setPlaybackRate(rate: number): Promise<void>;
-    /**
-     * Set highlight coordinator for word highlighting
-     */
-    setHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;
     /**
      * Set a late-bound provider for optional host TTS highlight target remapping.
      */
-    setHighlightTargetResolverProvider?(provider: TTSHighlightTargetResolverProvider | null): () => void;
-    /**
-     * Set accessibility catalog resolver for spoken content
-     */
-    setCatalogResolver(resolver: AccessibilityCatalogResolver): void;
+    setHighlightTargetResolverProvider(provider: TTSHighlightTargetResolverProvider | null): () => void;
 }
 /**
  * Accessibility catalog resolver interface
@@ -359,18 +357,15 @@ export interface AccessibilityCatalogResolverApi {
  */
 export interface ElementToolStateStoreApi {
     /**
-     * Generate a globally unique element ID from components
+     * Generate a globally unique element ID from its parts. `attemptId` is `""`
+     * when the host names no attempt; a tool keyed by item or section leaves
+     * `elementId`, and for a section `itemId`, as `""`.
      */
-    getGlobalElementId(assessmentId: string, sectionId: string, itemId: string, elementId: string): string;
+    getGlobalElementId(parts: ElementIdComponents): string;
     /**
      * Parse a global element ID into its components
      */
-    parseGlobalElementId(globalElementId: string): {
-        assessmentId: string;
-        sectionId: string;
-        itemId: string;
-        elementId: string;
-    } | null;
+    parseGlobalElementId(globalElementId: string): ElementIdComponents | null;
     /**
      * Set state for a specific tool on an element
      */
@@ -408,7 +403,7 @@ export interface ElementToolStateStoreApi {
      */
     clearTool(toolId: string): void;
     /**
-     * Clear all elements in a specific section
+     * Clear all elements in a specific section, across its attempts
      */
     clearSection(assessmentId: string, sectionId: string): void;
     /**
@@ -452,24 +447,16 @@ export interface ToolkitCoordinatorApi {
      */
     readonly toolProviderRegistry: ToolProviderRegistry;
     /**
-     * Get all services as a bundle
+     * Ensure the TTS service is initialized from the `textToSpeech` tool config.
      */
-    getServiceBundle(): {
-        ttsService: TtsServiceApi;
-        toolCoordinator: ToolCoordinatorApi;
-        highlightCoordinator: HighlightCoordinatorApi;
-        elementToolStateStore: ElementToolStateStoreApi;
-        catalogResolver: AccessibilityCatalogResolverApi;
-        toolProviderRegistry: ToolProviderRegistry;
-    };
+    ensureTTSReady(): Promise<void>;
     /**
-     * Ensure TTS service is initialized and ready.
+     * Ensure a tool's provider is initialized and ready. Providers register under
+     * their tool's id, so a tool passes its own base tool id. A tool starts its
+     * provider here, so that a failure meets the toolkit's tool failure policy:
+     * recoverable unless policy grants the tool.
      */
-    ensureTTSReady(config?: Record<string, unknown>): Promise<void>;
-    /**
-     * Ensure a provider is initialized and ready.
-     */
-    ensureProviderReady(providerId: string): Promise<unknown>;
+    ensureProviderReady(toolId: string): Promise<ToolProviderApi>;
     /**
      * Wait until coordinator initialization is complete.
      */
@@ -479,27 +466,19 @@ export interface ToolkitCoordinatorApi {
      */
     isReady(): boolean;
     /**
-     * Read current initialization status.
-     */
-    getInitStatus(): ToolkitInitStatus;
-    /**
-     * Check if a tool is enabled
+     * Subscribe to changes of {@link isReady}.
      */
-    isToolEnabled(toolId: string): boolean;
+    onReadyChange(listener: () => void): () => void;
     /**
      * Get tool configuration
      */
-    getToolConfig(toolId: "textToSpeech"): TTSToolConfig | null;
+    getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
      * Update tool configuration
      */
-    updateToolConfig(toolId: "textToSpeech", updates: Partial<TTSToolConfig>): void;
+    updateToolConfig(toolId: "textToSpeech", updates: Partial<TextToSpeechToolProviderConfig>): void;
     updateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;
-    /**
-     * Update the enabled tool list for one placement level.
-     */
-    updateToolPlacement(level: ToolPlacementLevel, toolIds: string[]): void;
     /**
      * Patch one or more placement levels in the canonical tools config.
      */
@@ -526,11 +505,12 @@ export interface ToolkitCoordinatorApi {
      * aggregate `section-loading-complete`, in the canonical order a
      * fresh subscriber would have observed.
      *
-     * Throws if no active section cohort exists; host code must call
-     * `getOrCreateSectionController(...)` at least once before
-     * subscribing. (`toolkit-ready` alone is not sufficient — it fires
-     * once toolkit state has loaded but before any section controller
-     * has been created.) The typical pattern is to subscribe once
+     * Throws until the first `getOrCreateSectionController(...)` call; a
+     * listener added while a section is starting binds when that section
+     * becomes active. `runtime-ready` alone is not sufficient: it fires once
+     * the coordinator is bound, before any section controller exists. A
+     * `<pie-assessment-toolkit>` holding a section emits `toolkit-ready`
+     * after its controller resolves. The typical pattern is to subscribe once
      * immediately after the first `getOrCreateSectionController(...)`
      * resolves; the subscription then follows the active cohort across
      * all subsequent navigation without further wiring.
@@ -559,12 +539,18 @@ export interface ToolkitCoordinatorApi {
     subscribeSectionLifecycleEvents(args: SectionScopedEventSubscriptionArgs): () => void;
     /**
      * Create or reuse a section controller with single-flight deduplication.
+     *
+     * `initialSession` is a host-supplied session. A new controller applies it in
+     * replace mode in place of `hydrate()`, before it is published; an existing
+     * one applies it unless it equals the current session, keeping recorded
+     * responses that a response-free item session would replace.
      */
     getOrCreateSectionController(args: {
         sectionId: string;
         attemptId?: string;
         input?: unknown;
         updateExisting?: boolean;
+        initialSession?: SectionControllerSessionState | null;
         createDefaultController: () => SectionControllerHandle | Promise<SectionControllerHandle>;
     }): Promise<SectionControllerHandle>;
     /**
@@ -599,6 +585,12 @@ export interface ToolkitCoordinatorApi {
      * Optional so structural host coordinators remain assignable.
      */
     reportFrameworkError?(model: FrameworkErrorModel): void;
+    /**
+     * Report that a tool failed in `phase`, under the tool failure policy
+     * {@link ToolFailurePhase} describes. Optional so structural host
+     * coordinators remain assignable; a reporter without it logs.
+     */
+    reportToolFailure?(toolId: string, phase: ToolFailurePhase, error: unknown): void;
     /**
      * Resolve the visible tool set for a given placement level + scope.
      * Returns the engine's full decision (visible tools, diagnostics,
@@ -607,24 +599,36 @@ export interface ToolkitCoordinatorApi {
      */
     decideToolPolicy(request: ToolPolicyDecisionRequest): ToolPolicyDecision;
     /**
-     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * 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 button (a signed
      * alternate's region, for example).
      *
+     * `scope` is the surface asking; an item's scope brings in that item's
+     * registered settings ({@link registerItemSettings}).
+     *
      * Optional so host-supplied coordinator stubs predating this method stay
      * assignable; call sites must feature-detect.
      */
-    decideFeaturePolicy?(featureId: string): FeaturePolicyDecision;
+    decideFeaturePolicy?<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound policy inputs change (`updateToolConfig`,
-     * `updateToolPlacement`, `updateAssessment`, `updateCurrentItemRef`,
-     * `setPnpEnforcement`) or a custom `PolicySource` is registered /
-     * removed. Listeners that need the new visible tool set should
-     * call `decideToolPolicy(...)` with their level / scope.
+     * `updateToolsPlacement`, `updateAssessment`, `setPnpEnforcement`), an
+     * item's settings are registered or withdrawn, or a custom `PolicySource`
+     * is registered / removed. Listeners that need the new visible tool set
+     * should call `decideToolPolicy(...)` with their level / scope.
      */
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
+    /**
+     * Subscribe to the policy diagnostics the coordinator reports: the ones it
+     * logs as console warnings, once per code, tool and item. A new listener is
+     * first handed every diagnostic already reported. A change to the bound
+     * policy inputs or to PNP enforcement clears the record, and so does a tool
+     * registration that makes a named support id known or unknown, so a conflict
+     * that survives the change is reported again once.
+     */
+    onPolicyDiagnostic(listener: (diagnostic: ToolPolicyDiagnostic) => void): () => void;
     /**
      * Subscribe to accessibility-catalog registrations and removals.
      *
@@ -645,30 +649,31 @@ export interface ToolkitCoordinatorApi {
     /**
      * Bind (or clear) the active assessment for PNP/profile policy decisions.
      *
-     * Under auto-mode (no host override via {@link setPnpEnforcement}),
-     * the engine flips to `pnpEnforcement: "on"` iff the assessment
-     * carries profile precedence material (`personalNeedsProfile`,
-     * `settings.districtPolicy`, `settings.testAdministration`) or the
-     * currently-bound item ref carries item-level profile inputs. A bare
-     * assessment record (just `id` / `name`) keeps `"off"`.
+     * Under auto-mode (no host override via {@link setPnpEnforcement}), a
+     * decision enforces PNP/profile policy iff the assessment carries profile
+     * precedence material (`personalNeedsProfile`, `settings.districtPolicy`,
+     * `settings.testAdministration`), or the decision is scoped to an item whose
+     * registered settings carry item-level policy inputs. A bare assessment
+     * record (just `id` / `name`) keeps `"off"`.
      *
      * The host override set via {@link setPnpEnforcement} is sticky
      * across assessment swaps.
      */
     updateAssessment(assessment: AssessmentEntity | null): void;
     /**
-     * Bind (or clear) the current item reference for policy decisions.
-     * Used by item-level profile gates (item `requiredTools` /
-     * `restrictedTools` / `toolParameters`). Item-level profile material
-     * also feeds the auto-mode helper — navigating to an item with
-     * profile settings can flip auto-mode to `"on"` even when the parent
-     * assessment carries no profile block of its own.
+     * File a mounted item's policy settings (`requiredTools`, `restrictedTools`,
+     * `toolParameters`) under its canonical id; the returned function withdraws
+     * them. They govern only decisions scoped to that item: its own item-level
+     * toolbar, and feature decisions asked with the item's scope. A section- or
+     * assessment-level toolbar ignores them, and reports each tool on it that
+     * they restrict or require as `tool-policy.itemSettingNotApplied`.
+     * `<pie-item-scope>` registers its `settings` property through this.
      */
-    updateCurrentItemRef(itemRef: AssessmentItemRef | null): void;
+    registerItemSettings(itemId: string, settings: ItemSettings): () => void;
     /**
      * Override the auto-mode PNP/profile enforcement decision. Pass `"on"` /
      * `"off"` to pin the mode, or `null` to clear the override and
-     * return to auto-mode (`"on"` iff the bound assessment / item ref
+     * return to auto-mode (`"on"` for a decision whose assessment or item
      * carries profile material, otherwise `"off"`).
      */
     setPnpEnforcement(mode: PnpEnforcementMode | null): void;
@@ -683,14 +688,6 @@ export interface ToolkitCoordinatorApi {
      * (the returned function detaches).
      */
     registerPolicySource(source: PolicySource): () => void;
-    /**
-     * Register a host-owned resolver for scoped tool render context.
-     */
-    registerToolContextResolver(toolId: string, resolver: ToolContextResolver): () => void;
-    /**
-     * Replace all host-owned render-context resolvers.
-     */
-    setToolContextResolvers(resolvers: ToolContextResolverMap | null | undefined): void;
     /**
      * Whether a host resolver is registered for this tool.
      */
@@ -703,6 +700,14 @@ export interface ToolkitCoordinatorApi {
      * Subscribe to resolver registration/removal changes.
      */
     onToolContextResolverChange(listener: () => void): () => void;
+    /**
+     * The registry this coordinator's providers and policy resolve against: the
+     * one it was built with or adopted, else the empty one it started with. A
+     * toolbar that is not handed a registry reads it here, again on each
+     * {@link onPolicyChange}, which an adoption fires. Optional for the same reason
+     * as the request seam below: a host-supplied coordinator may predate it.
+     */
+    getToolRegistry?(): ToolRegistry;
     /**
      * The tool-open request seam, optional as a group.
      *
@@ -724,7 +729,7 @@ export interface ToolkitCoordinatorApi {
      * Whether a request for this tool would reach a toolbar. A surface asks before
      * offering the affordance.
      */
-    canRequestTool?(toolId: string, level?: ToolOpenRequest["level"]): boolean;
+    canRequestTool?(toolId: string, level?: ToolOpenRequest["level"], scopeId?: string): boolean;
     /**
      * Subscribe to toolbar registration/removal, so a surface can re-evaluate the
      * actions it offers.

package/dist/services/section-controller-types.d.ts

@@ -27,14 +27,14 @@ export interface SectionSessionPersistenceConfig {
     context: SectionControllerContext;
     strategy: SectionSessionPersistenceStrategy;
 }
+/**
+ * applySession contract:
+ * - Preferred input is the output of getSession().
+ * - itemSessions may contain canonical attempt entries
+ *   ({ itemIdentifier, session, isCompleted }) or raw session payloads
+ *   ({ id, data, ... }); controller normalizes these before applying.
+ */
 export interface SectionControllerApplySessionOptions {
-    /**
-     * applySession contract:
-     * - Preferred input is the output of getSession().
-     * - itemSessions may contain canonical attempt entries
-     *   ({ itemIdentifier, session, isCompleted }) or raw session payloads
-     *   ({ id, data, ... }); controller normalizes these before applying.
-     */
     mode?: "replace" | "merge";
 }
 export interface SectionControllerLoadedRenderable {

package/dist/services/section-session-assignment.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A host-assigned section session, resolved against the session a live
+ * controller already holds.
+ *
+ * The rules are the ones `ItemController.setSession` applies to one item:
+ * - a value whose content equals the current session is a no-op, so echoing a
+ *   snapshot back into the `session` property applies nothing;
+ * - an item session with neither a response value nor a response field leaves
+ *   an item session that holds responses in place. The embedded item player
+ *   applies the same rule when the section hands the session down, so applying
+ *   it at section level keeps the controller and its item players from
+ *   diverging.
+ *
+ * A controller that holds no session yet takes the value as assigned.
+ */
+import type { SectionControllerSessionState } from "@pie-players/pie-players-shared/types";
+/**
+ * The session to apply in replace mode, or `null` when applying `next` would
+ * change nothing.
+ */
+export declare function resolveSectionSessionAssignment(current: SectionControllerSessionState | null | undefined, next: SectionControllerSessionState): SectionControllerSessionState | null;