@pie-players/pie-assessment-toolkit 0.3.68 → 0.3.70

package/dist/services/HighlightCoordinator.js

@@ -900,20 +900,17 @@ export class HighlightCoordinator {
         this.applyAdaptiveTTSStyle();
     }
     /**
-     * Cleanup - remove all highlights
+     * Cleanup this coordinator's highlights and observer.
+     *
+     * The stylesheet is process-global and shared by every live coordinator, so
+     * removing it here would break a replacement or sibling coordinator. Keep the
+     * single bounded style element installed for the lifetime of the document.
      */
     destroy() {
         if (!this.supported)
             return;
         this.clearTTS();
         this.clearAnnotations();
-        // Remove style element
-        if (typeof document !== "undefined") {
-            const styleEl = document.getElementById("pie-highlight-styles");
-            if (styleEl) {
-                styleEl.remove();
-            }
-        }
         this.themeObserver?.disconnect();
         this.themeObserver = null;
     }

package/dist/services/ToolRegistry.d.ts

@@ -116,6 +116,20 @@ export interface ResolvedToolContext {
 export interface ToolRenderElement {
     element: HTMLElement | null;
     mount: "before-buttons" | "after-buttons" | "controls-row";
+    /**
+     * Which box the element is appended to. `mount` places it among the toolbar's
+     * own regions; this chooses the box it is positioned against.
+     *
+     * `"toolbar"` (the default) leaves it in the toolbar, whose element is the
+     * containing block for anything absolutely positioned inside it.
+     * `"content-boundary"` appends it to the nearest element the host marked with
+     * `data-pie-tool-overlay-boundary` — the content a tool was placed on. An
+     * element that draws its own surface over that content and computes its own
+     * coordinates needs the content's box as its frame, and the toolbar's box is a
+     * header-sized one. When the host declares no boundary the element stays in
+     * the toolbar.
+     */
+    container?: "toolbar" | "content-boundary";
     layoutHints?: {
         controlsRow?: {
             reserveSpace?: boolean;
@@ -483,6 +497,26 @@ export interface ToolRegistration {
      * @returns true if tool should be visible, false to hide
      */
     isVisibleInContext?(context: ToolContext): boolean;
+    /**
+     * Whether this tool can act on this content at all — a capability question,
+     * not a relevance heuristic. Answering `false` withdraws the tool even where
+     * a PNP grant would otherwise keep it, which {@link
+     * ToolRegistration.isVisibleInContext} deliberately cannot do.
+     *
+     * The two gates answer different questions, and most tools declare only the
+     * first. A calculator is *applicable* to every item — a learner granted one
+     * keeps it on an item that does not look mathematical — while its relevance
+     * is a guess about usefulness. An answer eliminator on an item with no choice
+     * interaction has nothing to strike through, so no grant can make it work.
+     *
+     * Declare this only where the tool's own controls provably do nothing:
+     * withdrawing a granted accommodation on a false negative is the more
+     * expensive failure. Omitting it means "applicable".
+     *
+     * @param context - The item or element context the tool would act on
+     * @returns false to withdraw the tool from this context
+     */
+    isApplicableToContent?(context: ToolContext): boolean;
     /**
      * Toolbar render contract. Required for `toolbar-toggle` and
      * `selection-gateway`; a region capability renders through
@@ -625,6 +659,20 @@ export declare class ToolRegistry {
      * @returns Array of visible tool registrations
      */
     filterVisibleInContext(allowedToolIds: string[], context: ToolContext): ToolRegistration[];
+    /**
+     * Whether a tool can act on any of the contexts it would be placed against.
+     * Unlike the relevance pass this is a veto: a `false` here removes the tool
+     * from a toolbar even when a grant protects it, so a tool answers `false`
+     * only where its controls provably do nothing.
+     *
+     * A tool that declares no applicability gate is applicable. So is one
+     * evaluated against no contexts — content that has not resolved yet cannot
+     * establish that a tool is useless.
+     *
+     * @param toolId - Tool to ask
+     * @param contexts - Every context the tool could act on at this placement
+     */
+    isApplicableToAnyContext(toolId: string, contexts: readonly ToolContext[]): boolean;
     /**
      * Get tool metadata for building UIs
      * Useful for building PNP configuration interfaces

package/dist/services/ToolRegistry.js

@@ -164,6 +164,10 @@ function assertToolRegistrationShape(registration) {
         typeof registration.isVisibleInContext !== "function") {
         throw new Error(`Invalid tool registration "${registration.toolId}": "isVisibleInContext" must be a function when present.`);
     }
+    if (registration.isApplicableToContent !== undefined &&
+        typeof registration.isApplicableToContent !== "function") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "isApplicableToContent" must be a function when present.`);
+    }
     if (registration.requiresAuthoredContent !== undefined) {
         if (typeof registration.requiresAuthoredContent !== "object" ||
             registration.requiresAuthoredContent === null ||
@@ -442,6 +446,36 @@ export class ToolRegistry {
         }
         return visible;
     }
+    /**
+     * Whether a tool can act on any of the contexts it would be placed against.
+     * Unlike the relevance pass this is a veto: a `false` here removes the tool
+     * from a toolbar even when a grant protects it, so a tool answers `false`
+     * only where its controls provably do nothing.
+     *
+     * A tool that declares no applicability gate is applicable. So is one
+     * evaluated against no contexts — content that has not resolved yet cannot
+     * establish that a tool is useless.
+     *
+     * @param toolId - Tool to ask
+     * @param contexts - Every context the tool could act on at this placement
+     */
+    isApplicableToAnyContext(toolId, contexts) {
+        const tool = this.get(toolId);
+        if (!tool?.isApplicableToContent)
+            return true;
+        if (contexts.length === 0)
+            return true;
+        return contexts.some((context) => {
+            try {
+                return tool.isApplicableToContent?.(context) ?? true;
+            }
+            catch (error) {
+                console.error(`Error evaluating applicability for tool '${toolId}':`, error);
+                // A gate that throws has not established that the tool is useless.
+                return true;
+            }
+        });
+    }
     /**
      * Get tool metadata for building UIs
      * Useful for building PNP configuration interfaces

package/dist/services/ToolkitCoordinator.d.ts

@@ -323,7 +323,8 @@ export declare class ToolkitCoordinator {
     private readonly toolRequests;
     private readonly sectionControllers;
     private readonly sectionControllerKeys;
-    private readonly sectionControllerInitPromises;
+    private readonly sectionControllerInitEntries;
+    private readonly sectionControllerDisposePromises;
     private readonly sectionPersistenceStrategies;
     private readonly sectionControllerLifecycleListeners;
     /**
@@ -356,14 +357,10 @@ export declare class ToolkitCoordinator {
     private readonly telemetryListeners;
     private readonly frameworkErrorBus;
     private readonly ownsFrameworkErrorBus;
+    private frameworkErrorHookUnsubscribe;
+    private disposePromise;
     /**
-     * Unified Tool Policy Engine. Owned by the coordinator and lives
-     * for the lifetime of the coordinator instance — there is no
-     * explicit teardown path today; the engine and its listener set
-     * are reclaimed by GC when the coordinator becomes unreachable.
-     * Subscribers attached via {@link onPolicyChange} must therefore
-     * detach via the unsubscribe function the engine returns; do not
-     * rely on a `disposed` event being emitted on coordinator teardown.
+     * Unified Tool Policy Engine. Owned by the coordinator and disposed with it.
      *
      * Hosts read decisions via {@link decideToolPolicy} or subscribe
      * to changes via {@link onPolicyChange}.
@@ -409,6 +406,7 @@ export declare class ToolkitCoordinator {
     private reportedUnboundFeaturePolicy;
     private static resolveConfig;
     constructor(config: ToolkitCoordinatorConfig);
+    private assertNotDisposed;
     /**
      * Subscribe the canonical `onFrameworkError` hook adapter to the
      * framework-error bus.
@@ -572,6 +570,10 @@ export declare class ToolkitCoordinator {
     private resolveExistingSectionController;
     private createSectionControllerContext;
     private initializeNewSectionController;
+    private createSectionControllerRetirementError;
+    private retireUnpublishedSectionControllerIfNeeded;
+    private cleanupUnpublishedSectionController;
+    private retirePublishedSectionControllerIfNeeded;
     private finalizeSectionControllerReady;
     private handleSectionControllerInitError;
     disposeSectionController(args: {
@@ -580,8 +582,18 @@ export declare class ToolkitCoordinator {
         persistBeforeDispose?: boolean;
         clearPersistence?: boolean;
     }): Promise<void>;
+    private trackSectionControllerDisposal;
+    private disposeSectionControllerEntry;
     private runSectionControllerDisposePipeline;
     private finalizeSectionControllerDispose;
+    /**
+     * Release every resource whose lifetime is owned by this coordinator.
+     * Borrowed constructor inputs, including a host framework-error bus and tool
+     * registry, remain owned by their caller.
+     */
+    dispose(): Promise<void>;
+    private disposeOwnedResources;
+    private waitForAdmittedInitialization;
     /**
      * Initialize TTS service with provider
      */
@@ -681,11 +693,9 @@ export declare class ToolkitCoordinator {
      * that want the new visible tool set should call
      * {@link decideToolPolicy} with their level / scope.
      *
-     * Note: the engine itself can also emit `reason: "disposed"`, but
-     * the coordinator does not dispose its engine on teardown today,
-     * so subscribers attached via this method will not observe that
-     * reason. Detach via the returned unsubscribe function instead of
-     * relying on a `disposed` event.
+     * The owned engine emits `reason: "disposed"` during coordinator teardown.
+     * Callers should still detach through the returned unsubscribe function when
+     * their own lifetime ends before the coordinator's.
      */
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
     /**