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

package/dist/tools/content-capability-resolution.d.ts

@@ -3,7 +3,7 @@
  * profile.
  *
  * Two independent halves, and a capability is in play only when both answer yes:
- * policy granted one of its support ids, and its own `requiresAuthoredContent`
+ * policy granted its support id, and its own `requiresAuthoredContent`
  * found the resource in this entity's catalogs. Neither implies the other — a
  * learner with an accommodation still sees nothing on an item carrying no
  * resource, and an item carrying one shows nothing to a learner without the
@@ -30,11 +30,9 @@
  */
 import type { ToolRegistration } from "../services/ToolRegistry.js";
 import type { CatalogOwnerSnapshot } from "../services/AccessibilityCatalogResolver.js";
-/** What policy answered about one feature id. */
+/** What policy answered about one capability's support id. */
 export type ContentCapabilityPolicy = {
     outcome: "granted";
-    /** The support id that was granted — a capability may declare several. */
-    featureId: string;
     /** Feature parameters carried by the decision, if any. */
     parameters?: unknown;
 }
@@ -61,12 +59,12 @@ export type ContentCapabilityPhase = "policy" | "content";
 export interface ResolvedContentCapability {
     registration: ToolRegistration;
     /**
-     * The granted support id, or `""` when the capability resolved without a
-     * grant. Passed through to the render context unchanged, so a capability that
+     * Whether policy granted the capability; `false` when it resolved from content
+     * alone. Passed through to the render context unchanged, so a capability that
      * serves both an authored-presentation case and an accommodation can still
      * tell them apart at render time.
      */
-    featureId: string;
+    granted: boolean;
     parameters?: unknown;
     /** Whatever the capability's own `resolve` returned; never inspected here. */
     content: unknown;
@@ -81,7 +79,7 @@ export interface ResolveContentCapabilitiesArgs {
     /** The entity's cards, or `null` when no resolver is available. */
     catalogs: CatalogOwnerSnapshot | null;
     /**
-     * Policy's answer about one feature id, in three states.
+     * Policy's answer about one support id, which is a tool id, in three states.
      *
      * Granting requires a documented need, so an unconfigured feature is
      * `"silent"`, never granted. What the third state buys is the distinction
@@ -89,7 +87,7 @@ export interface ResolveContentCapabilitiesArgs {
      * something, and a capability allowed to answer from content alone must not
      * treat that as nobody having spoken.
      */
-    policyFor: (featureId: string) => ContentCapabilityPolicy;
+    policyFor: (supportId: string) => ContentCapabilityPolicy;
     /**
      * Report a capability that threw. It is dropped either way; this is how a
      * caller surfaces it as its own recoverable warning rather than letting one

package/dist/tools/content-capability-resolution.js

@@ -3,7 +3,7 @@
  * profile.
  *
  * Two independent halves, and a capability is in play only when both answer yes:
- * policy granted one of its support ids, and its own `requiresAuthoredContent`
+ * policy granted its support id, and its own `requiresAuthoredContent`
  * found the resource in this entity's catalogs. Neither implies the other — a
  * learner with an accommodation still sees nothing on an item carrying no
  * resource, and an item carrying one shows nothing to a learner without the
@@ -28,51 +28,15 @@
  * a capability interprets its own cards, and the resolution owns only the
  * two-halves rule and its one documented exception.
  */
-/** The support ids a capability answers to, defaulting to its own id. */
-const supportIdsOf = (registration) => registration.pnpSupportIds?.length
-    ? registration.pnpSupportIds
-    : [registration.toolId];
-/**
- * Everything policy has to say about one capability: a grant, an off switch, or
- * nothing.
- *
- * Denial is checked ahead of a grant on each id rather than after the scan,
- * because the two can only disagree when a host blocked one of a capability's ids
- * while a profile granted another, and there the off switch is the later, more
- * specific statement about this delivery.
- *
- * A host gate names *capabilities*, so the tool id is probed too when it is not
- * already a declared support id — otherwise a capability whose id differs from
- * its support ids would slip a host block. That probe is gate-only: a grant on
- * the tool id is ignored, or blocking would double as a second way to switch a
- * capability on.
- */
-function policyForCapability(registration, args) {
-    const supportIds = supportIdsOf(registration);
-    for (const supportId of supportIds) {
-        const answer = args.policyFor(supportId);
-        if (answer.outcome === "denied")
-            return { grant: null, denied: true };
-        if (answer.outcome === "granted")
-            return { grant: answer, denied: false };
-    }
-    if (supportIds.includes(registration.toolId)) {
-        return { grant: null, denied: false };
-    }
-    return {
-        grant: null,
-        denied: args.policyFor(registration.toolId).outcome === "denied",
-    };
-}
 function resolveOne(registration, args) {
     let grant = null;
     try {
-        const answer = policyForCapability(registration, args);
-        // Nothing reopens a host denial — not a grant it outranked, and not the
-        // content exception below.
-        if (answer.denied)
+        const answer = args.policyFor(registration.toolId);
+        // Nothing reopens a host denial, not even the content exception below.
+        if (answer.outcome === "denied")
             return null;
-        grant = answer.grant;
+        if (answer.outcome === "granted")
+            grant = answer;
     }
     catch (error) {
         args.onError?.(registration, "policy", error);
@@ -92,13 +56,12 @@ function resolveOne(registration, args) {
             return null;
         return {
             registration,
-            featureId: grant.featureId,
+            granted: true,
             parameters: grant.parameters,
             content: null,
         };
     }
     const context = {
-        featureId: grant?.featureId ?? "",
         parameters: grant?.parameters,
         catalogs: args.catalogs,
         granted: Boolean(grant),
@@ -117,7 +80,7 @@ function resolveOne(registration, args) {
         return null;
     return {
         registration,
-        featureId: context.featureId,
+        granted: context.granted,
         parameters: context.parameters,
         content,
     };

package/dist/tools/registration.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Tool registration — the stable entry for tool authors: writing and rendering a
+ * `ToolRegistration`, and the runtime contract a tool element is written against.
+ *
+ * A capability package writes a registration with it: the registration contract,
+ * the context predicates a tool answers `isVisibleInContext` with, scoped ids,
+ * element creation, the toolbar button and overlay helpers, the provider contract
+ * a descriptor creates, and the TTS provider with its config resolution. A
+ * renderer puts registrations on screen with it: `createToolSurfaceHost` mounts
+ * and reconciles surfaces, and `resolveContentCapabilities` asks the
+ * grant-and-content question without a coordinator. A tool element connects to
+ * the runtime with it: the runtime, shell and region-scope contexts, the services
+ * they carry, coordinator registration, the reading scope of the content it reads
+ * or annotates, and read-aloud coordination.
+ *
+ * The composition layer (`@pie-players/pie-default-tool-loaders`), the packaged
+ * tools and the section player's tool panels are written against it, so a host's
+ * own tool uses the mechanism ours use. Its values are complete, so a tool
+ * package never imports the root entry, which carries what hosts and players
+ * import. A name the root also carries appears here only where a package imports
+ * it from here.
+ */
+export type { HostedToolContext, HostedToolSize, ToolContentDependencyContext, ToolModuleLoader, ToolProviderDescriptor, ToolRegistration, ToolRenderElement, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolbarContext, } from "../services/ToolRegistry.js";
+export { ToolRegistry } from "../services/ToolRegistry.js";
+export { resolveToolRegistrationName } from "../services/ToolRegistry.js";
+export type { CatalogOwnerSnapshot } from "../services/AccessibilityCatalogResolver.js";
+export type { ToolSelectionAction, ToolSelectionContext, } from "../services/selection-action.js";
+export { resolveFallbackToolIcon } from "../services/tool-icons.js";
+export type { ContentCapabilityPhase, ContentCapabilityPolicy, ResolveContentCapabilitiesArgs, ResolvedContentCapability, } from "./content-capability-resolution.js";
+export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export type { ToolSurfaceHost, ToolSurfaceHostInput, ToolSurfaceHostOptions, ToolSurfaceHostSnapshot, ToolSurfaceScope, } from "./tool-surface-host.js";
+export { createToolSurfaceHost } from "./tool-surface-host.js";
+export type { ToolContext } from "../services/tool-context.js";
+export { hasChoiceInteraction, hasMathContent, hasReadableText, hasScienceContent, } from "../services/tool-context.js";
+export type { ParsedToolInstanceId } from "../services/tool-instance-id.js";
+export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";
+export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverrides, ToolTagMap, } from "./tool-tag-map.js";
+export { createToolElement, resolveToolTag } from "./tool-tag-map.js";
+export { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "./registrations/toolbar-registration-helpers.js";
+export type { HighlightCoordinatorApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi, } from "../services/interfaces.js";
+export type { AssessmentToolkitRegionScopeContext, AssessmentToolkitRuntimeContext, AssessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
+export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createToolCoordinatorRegistration, type ToolCoordinatorRegistration, } from "../runtime/tool-host-contract.js";
+export { ZIndexLayer } from "../services/ToolCoordinator.js";
+export { HighlightColor, HighlightCoordinator, } from "../services/HighlightCoordinator.js";
+export type { CatalogLookupContext } from "../services/AccessibilityCatalogResolver.js";
+export { catalogContextForShell, catalogContextHolding, type CatalogRuntimeScope, } from "../runtime/catalog-context.js";
+export { findShellScopeHost, resolveContentRegion, } from "../runtime/content-region.js";
+export { composedClosest, composedContains, flatTextContent, isShadowRootNode, retargetToTree, } from "../services/tts/flat-tree.js";
+export type { ToolPlacementLevel } from "../services/tools-config-normalizer.js";
+export type { CalculatorToolProviderConfig, TextToSpeechToolProviderConfig, ToolProviderConfig, } from "../services/tools-config-normalizer.js";
+export type { ToolProviderApi, ToolProviderCapabilities, } from "../services/tool-providers/ToolProviderApi.js";
+export { TTSToolProvider } from "../services/tool-providers/index.js";
+export type { NormalizedTTSSpeedOption, TTSLayoutMode, TTSSpeedOption, } from "../services/tts-runtime-config.js";
+export { buildRuntimeTTSConfig, formatTTSSpeedOptionsAsText, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, parseTTSSpeedOptionsFromText, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSRuntimeSettings, } from "../services/tts-runtime-config.js";
+export { PIE_TTS_CONTROL_HANDOFF_EVENT } from "../services/tts-control-events.js";
+export { bindTtsAudioHandoff, pauseTtsForMediaAudio, } from "../services/audio-handoff.js";
+export { isTTSStartFailure } from "../services/tts/start-failure.js";
+export { browserVoiceMatchesLanguage, findBrowserVoice, waitForBrowserVoices, } from "../services/tts/browser-provider.js";

package/dist/tools/registration.js

@@ -0,0 +1,54 @@
+/**
+ * Tool registration — the stable entry for tool authors: writing and rendering a
+ * `ToolRegistration`, and the runtime contract a tool element is written against.
+ *
+ * A capability package writes a registration with it: the registration contract,
+ * the context predicates a tool answers `isVisibleInContext` with, scoped ids,
+ * element creation, the toolbar button and overlay helpers, the provider contract
+ * a descriptor creates, and the TTS provider with its config resolution. A
+ * renderer puts registrations on screen with it: `createToolSurfaceHost` mounts
+ * and reconciles surfaces, and `resolveContentCapabilities` asks the
+ * grant-and-content question without a coordinator. A tool element connects to
+ * the runtime with it: the runtime, shell and region-scope contexts, the services
+ * they carry, coordinator registration, the reading scope of the content it reads
+ * or annotates, and read-aloud coordination.
+ *
+ * The composition layer (`@pie-players/pie-default-tool-loaders`), the packaged
+ * tools and the section player's tool panels are written against it, so a host's
+ * own tool uses the mechanism ours use. Its values are complete, so a tool
+ * package never imports the root entry, which carries what hosts and players
+ * import. A name the root also carries appears here only where a package imports
+ * it from here.
+ */
+export { ToolRegistry } from "../services/ToolRegistry.js";
+// A registration's own display name in the interface locale. A tool window's
+// title is the registration's name, so the shell needs the same `nameKey`-then-
+// `name` precedence the toolbar uses rather than the raw English field.
+export { resolveToolRegistrationName } from "../services/ToolRegistry.js";
+// So a gateway button and the toolbar button for the same tool draw one icon.
+export { resolveFallbackToolIcon } from "../services/tool-icons.js";
+export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export { createToolSurfaceHost } from "./tool-surface-host.js";
+export { hasChoiceInteraction, hasMathContent, hasReadableText, hasScienceContent, } from "../services/tool-context.js";
+export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";
+export { createToolElement, resolveToolTag } from "./tool-tag-map.js";
+// Toolbar button/overlay wiring shared by every toolbar-toggle registration.
+export { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "./registrations/toolbar-registration-helpers.js";
+export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createToolCoordinatorRegistration, } from "../runtime/tool-host-contract.js";
+export { ZIndexLayer } from "../services/ToolCoordinator.js";
+export { HighlightColor, HighlightCoordinator, } from "../services/HighlightCoordinator.js";
+export { catalogContextForShell, catalogContextHolding, } from "../runtime/catalog-context.js";
+export { findShellScopeHost, resolveContentRegion, } from "../runtime/content-region.js";
+export { composedClosest, composedContains, flatTextContent, isShadowRootNode, retargetToTree, } from "../services/tts/flat-tree.js";
+// The TTS provider stays here because it is written against the `pie-tts`
+// contract package, which the toolkit's own `TTSService` also depends on.
+export { TTSToolProvider } from "../services/tool-providers/index.js";
+export { buildRuntimeTTSConfig, formatTTSSpeedOptionsAsText, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, parseTTSSpeedOptionsFromText, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSRuntimeSettings, } from "../services/tts-runtime-config.js";
+// Read-aloud coordination for a tool that plays or controls speech: the control
+// handoff event between TTS surfaces, pausing speech while a media element plays,
+// recognising a start failure the TTS service reports, and choosing a browser
+// voice for a language once the browser has published its voices.
+export { PIE_TTS_CONTROL_HANDOFF_EVENT } from "../services/tts-control-events.js";
+export { bindTtsAudioHandoff, pauseTtsForMediaAudio, } from "../services/audio-handoff.js";
+export { isTTSStartFailure } from "../services/tts/start-failure.js";
+export { browserVoiceMatchesLanguage, findBrowserVoice, waitForBrowserVoices, } from "../services/tts/browser-provider.js";

package/dist/tools/registrations/toolbar-registration-helpers.js

@@ -3,12 +3,12 @@ export function createScopedVisibilityBinding(toolId, toolbarContext) {
     const fullToolId = createScopedToolId(toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
     return {
         fullToolId,
-        isActive: () => toolbarContext.isToolVisible(fullToolId),
+        isActive: () => toolbarContext.isToolVisible(toolId),
         subscribeActive: (callback) => {
             if (!toolbarContext.subscribeVisibility)
                 return () => { };
             return toolbarContext.subscribeVisibility(() => {
-                callback(toolbarContext.isToolVisible(fullToolId));
+                callback(toolbarContext.isToolVisible(toolId));
             });
         },
     };

package/dist/tools/tool-surface-host.d.ts

@@ -1,19 +1,15 @@
 /**
  * Headless host for capabilities that render into a renderer's surfaces.
  *
- * The interface deliberately exposes only current input, a two-boolean snapshot,
- * and teardown. Discovery, policy/catalog invalidation, content resolution, lazy
+ * The interface exposes only current input, a two-boolean snapshot, and
+ * teardown. Discovery, policy/catalog invalidation, content resolution, lazy
  * loading, DOM reconciliation, error isolation, and registry observation stay
  * inside this module. Svelte callers are geometry adapters over this seam.
  *
- * It lives here rather than in `section-player`, where it was written, because a
- * second renderer now opens a surface: the annotation toolbar hosts the
- * capabilities that act on a text selection. Two copies of mount/reconcile/
- * registry-observation would drift, and the drift would be invisible until one
- * renderer stopped honouring the grant-AND-content rule. Nothing about the module
- * was section-shaped — it already imported only from this package — so the move
- * is a relocation, not a rewrite. The one thing that *was* section-shaped is the
- * name it reported errors under, which is now {@link ToolSurfaceHostOptions.hostLabel}.
+ * Every renderer that opens a surface shares this one host, so each honours the
+ * grant-AND-content rule the same way: the section player's cards and the
+ * annotation toolbar's selection surface. Errors are reported under
+ * {@link ToolSurfaceHostOptions.hostLabel}.
  */
 import type { CatalogOwnerContext } from "../services/catalog-owner.js";
 import type { ToolRegistry, ToolSurfaceServices } from "../services/ToolRegistry.js";

package/dist/tools/tool-surface-host.js

@@ -1,23 +1,33 @@
 /**
  * Headless host for capabilities that render into a renderer's surfaces.
  *
- * The interface deliberately exposes only current input, a two-boolean snapshot,
- * and teardown. Discovery, policy/catalog invalidation, content resolution, lazy
+ * The interface exposes only current input, a two-boolean snapshot, and
+ * teardown. Discovery, policy/catalog invalidation, content resolution, lazy
  * loading, DOM reconciliation, error isolation, and registry observation stay
  * inside this module. Svelte callers are geometry adapters over this seam.
  *
- * It lives here rather than in `section-player`, where it was written, because a
- * second renderer now opens a surface: the annotation toolbar hosts the
- * capabilities that act on a text selection. Two copies of mount/reconcile/
- * registry-observation would drift, and the drift would be invisible until one
- * renderer stopped honouring the grant-AND-content rule. Nothing about the module
- * was section-shaped — it already imported only from this package — so the move
- * is a relocation, not a rewrite. The one thing that *was* section-shaped is the
- * name it reported errors under, which is now {@link ToolSurfaceHostOptions.hostLabel}.
+ * Every renderer that opens a surface shares this one host, so each honours the
+ * grant-AND-content rule the same way: the section player's cards and the
+ * annotation toolbar's selection surface. Errors are reported under
+ * {@link ToolSurfaceHostOptions.hostLabel}.
  */
 import { isHostDeniedFeature } from "../policy/core/feature-decision.js";
 import { toFrameworkErrorModel } from "../services/framework-error.js";
 import { resolveContentCapabilities } from "./content-capability-resolution.js";
+/**
+ * The scope an item's content asks feature policy with, which brings in the
+ * item's settings; other owners ask unscoped.
+ */
+function itemFeatureScope(owner) {
+    if (owner.ownerKind !== "itemModel")
+        return undefined;
+    return {
+        level: "item",
+        scopeId: owner.canonicalItemId || owner.itemId,
+        itemId: owner.itemId,
+        canonicalItemId: owner.canonicalItemId,
+    };
+}
 const SECTION_POLICY_LEVELS = ["section", "item", "passage"];
 function stableSerializableJson(value) {
     const seen = new Set();
@@ -112,7 +122,7 @@ function contextSignature(context) {
     try {
         return stableSerializableJson({
             toolId: context.toolId,
-            featureId: context.featureId,
+            granted: context.granted,
             surface: context.surface,
             parameters: context.parameters ?? null,
             content: context.content ?? null,
@@ -235,26 +245,22 @@ export function createToolSurfaceHost(onSnapshot, options) {
         if (current.scope.kind !== "content")
             return null;
         const coordinator = current.services.toolkitCoordinator;
+        const featureScope = itemFeatureScope(current.scope.ownerContext);
         const [resolved] = resolveContentCapabilities({
             registrations: [registration],
             catalogs,
-            // One decision per feature id, in the rule's three states. The scan across
-            // a capability's support ids, the gate-only probe of its tool id, and
-            // denial's precedence over both a grant and `resolvesWithoutGrant` live in
-            // the rule, so this host and print cannot answer differently. All this
-            // adapter owns is reading a `FeaturePolicyDecision`: `granted` is not
-            // enough on its own, because a host gate and an unconfigured feature are
-            // both `granted: false` and only one of them may be reopened by content.
-            policyFor: (featureId) => {
-                const decision = coordinator?.decideFeaturePolicy?.(featureId);
+            // One decision per support id, in the rule's three states. Denial's
+            // precedence over both a grant and `resolvesWithoutGrant` lives in the
+            // rule, so this host and print cannot answer differently. All this adapter
+            // owns is reading a `FeaturePolicyDecision`: `granted` is not enough on its
+            // own, because a host gate and an unconfigured feature are both
+            // `granted: false` and only one of them may be reopened by content.
+            policyFor: (supportId) => {
+                const decision = coordinator?.decideFeaturePolicy?.(supportId, featureScope);
                 if (isHostDeniedFeature(decision))
                     return { outcome: "denied" };
                 if (decision?.granted === true) {
-                    return {
-                        outcome: "granted",
-                        featureId,
-                        parameters: decision.parameters,
-                    };
+                    return { outcome: "granted", parameters: decision.parameters };
                 }
                 return { outcome: "silent" };
             },
@@ -281,7 +287,7 @@ export function createToolSurfaceHost(onSnapshot, options) {
         }
         const context = {
             toolId: registration.toolId,
-            featureId: resolved.featureId,
+            granted: resolved.granted,
             surface: current.surface,
             parameters: resolved.parameters,
             content: resolved.content,
@@ -303,26 +309,19 @@ export function createToolSurfaceHost(onSnapshot, options) {
         const coordinator = current.services.toolkitCoordinator;
         if (!coordinator)
             return null;
-        const supportIds = registration.pnpSupportIds?.length
-            ? registration.pnpSupportIds
-            : [registration.toolId];
-        let featureId = "";
+        let granted = false;
         let parameters;
         try {
             if (registration.activation === "region") {
-                for (const supportId of supportIds) {
-                    const decision = coordinator.decideFeaturePolicy?.(supportId);
-                    if (decision?.granted !== true)
-                        continue;
-                    featureId = supportId;
-                    parameters = decision.parameters;
-                    break;
-                }
-                if (!featureId)
+                const decision = coordinator.decideFeaturePolicy?.(registration.toolId);
+                if (decision?.granted !== true)
                     return null;
+                granted = true;
+                parameters = decision.parameters;
             }
             else {
                 const scopeId = current.scope.sectionId || "*";
+                let placed = false;
                 for (const level of SECTION_POLICY_LEVELS) {
                     const decision = coordinator.decideToolPolicy({
                         level,
@@ -336,11 +335,14 @@ export function createToolSurfaceHost(onSnapshot, options) {
                     const entry = decision.visibleTools.find((candidate) => candidate.toolId === registration.toolId);
                     if (!entry)
                         continue;
-                    featureId = supportIds[0] ?? registration.toolId;
+                    // Placement admits the tool; only a support, requirement or
+                    // test-administration override grants it.
+                    placed = true;
+                    granted = entry.required || entry.alwaysAvailable;
                     parameters = entry.settings;
                     break;
                 }
-                if (!featureId)
+                if (!placed)
                     return null;
             }
         }
@@ -350,7 +352,7 @@ export function createToolSurfaceHost(onSnapshot, options) {
         }
         const context = {
             toolId: registration.toolId,
-            featureId,
+            granted,
             surface: current.surface,
             parameters,
             services: current.services,

package/dist/tools/tool-tag-map.d.ts

@@ -10,26 +10,16 @@ export type ToolComponentFactory = (args: {
 export type ToolComponentFactoryMap = Record<string, ToolComponentFactory>;
 export interface ToolComponentOverrides {
     toolTagMap?: Partial<ToolTagMap>;
-    toolComponentFactory?: ToolComponentFactory;
     toolComponentFactories?: Partial<ToolComponentFactoryMap>;
 }
 /**
- * Resolve the element tag for a tool from the overrides in play.
- *
- * There is no built-in map to fall back to. One lived here, naming eleven
- * capabilities, and a core module holding that catalogue is why a host could not
- * add a twelfth without editing this package — the map was overridable, but the
- * default was core-resident. The packaged map is `PACKAGED_TOOL_TAG_MAP` in
- * `@pie-players/pie-default-tool-loaders`, installed onto a registry through
+ * Resolve the element tag for a tool from the overrides in play. Core holds no
+ * tag map; the packaged one is `PACKAGED_TOOL_TAG_MAP` in
+ * `@pie-players/pie-default-tool-loaders`, installed through
  * `ToolRegistry.setComponentOverrides`.
  *
- * An unmapped toolId falls through to itself, which is only a valid tag if the
- * host's tool id already looks like one. Every packaged id is a single camelCase
- * word, so in practice an unmapped packaged tool throws here rather than
- * rendering a bogus element — the failure names the missing mapping, because
- * "custom element names must include a hyphen" is a true statement about the
- * wrong thing.
+ * An unmapped toolId is its own tag when it contains a hyphen. Otherwise this
+ * throws an error naming the missing mapping.
  */
 export declare const resolveToolTag: (toolId: string, overrides?: ToolComponentOverrides) => string;
 export declare const createToolElement: (toolId: string, context: ToolContext, toolbarContext: ToolbarContext, overrides?: ToolComponentOverrides) => HTMLElement;
-export declare const toToolIdFromTag: (tagName: string, overrides?: ToolComponentOverrides) => string | undefined;

package/dist/tools/tool-tag-map.js

@@ -1,20 +1,12 @@
 import { validateCustomElementTag } from "@pie-players/pie-players-shared/pie/tag-names";
 /**
- * Resolve the element tag for a tool from the overrides in play.
- *
- * There is no built-in map to fall back to. One lived here, naming eleven
- * capabilities, and a core module holding that catalogue is why a host could not
- * add a twelfth without editing this package — the map was overridable, but the
- * default was core-resident. The packaged map is `PACKAGED_TOOL_TAG_MAP` in
- * `@pie-players/pie-default-tool-loaders`, installed onto a registry through
+ * Resolve the element tag for a tool from the overrides in play. Core holds no
+ * tag map; the packaged one is `PACKAGED_TOOL_TAG_MAP` in
+ * `@pie-players/pie-default-tool-loaders`, installed through
  * `ToolRegistry.setComponentOverrides`.
  *
- * An unmapped toolId falls through to itself, which is only a valid tag if the
- * host's tool id already looks like one. Every packaged id is a single camelCase
- * word, so in practice an unmapped packaged tool throws here rather than
- * rendering a bogus element — the failure names the missing mapping, because
- * "custom element names must include a hyphen" is a true statement about the
- * wrong thing.
+ * An unmapped toolId is its own tag when it contains a hyphen. Otherwise this
+ * throws an error naming the missing mapping.
  */
 export const resolveToolTag = (toolId, overrides) => {
     const mapped = overrides?.toolTagMap?.[toolId];
@@ -26,14 +18,8 @@ export const resolveToolTag = (toolId, overrides) => {
 const createDefaultToolElement = (tagName) => document.createElement(tagName);
 export const createToolElement = (toolId, context, toolbarContext, overrides) => {
     const tagName = resolveToolTag(toolId, overrides);
-    const factoryForTool = overrides?.toolComponentFactories?.[toolId];
-    const factory = factoryForTool ?? overrides?.toolComponentFactory;
+    const factory = overrides?.toolComponentFactories?.[toolId];
     return factory
         ? factory({ toolId, tagName, context, toolbarContext })
         : createDefaultToolElement(tagName);
 };
-export const toToolIdFromTag = (tagName, overrides) => {
-    const validTag = validateCustomElementTag(tagName, "tool component tag");
-    const map = overrides?.toolTagMap ?? {};
-    return Object.entries(map).find(([, tag]) => tag === validTag)?.[0];
-};

package/dist/utils/structural-equality.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Structural equality for plain data: host-supplied policy inputs and session
+ * payloads.
+ *
+ * Plain objects compare by own enumerable keys in any order, a key holding
+ * `undefined` matching an absent one, and arrays compare by position. Every
+ * other value compares with `Object.is`, so class instances, functions and
+ * maps are equal only to themselves. A pair already under comparison counts as
+ * equal, which keeps a cyclic value from recursing forever.
+ */
+export declare function structurallyEqual(a: unknown, b: unknown): boolean;

package/dist/utils/structural-equality.js

@@ -0,0 +1,47 @@
+/**
+ * Structural equality for plain data: host-supplied policy inputs and session
+ * payloads.
+ *
+ * Plain objects compare by own enumerable keys in any order, a key holding
+ * `undefined` matching an absent one, and arrays compare by position. Every
+ * other value compares with `Object.is`, so class instances, functions and
+ * maps are equal only to themselves. A pair already under comparison counts as
+ * equal, which keeps a cyclic value from recursing forever.
+ */
+export function structurallyEqual(a, b) {
+    return compare(a, b, new WeakMap());
+}
+function compare(a, b, inProgress) {
+    if (Object.is(a, b))
+        return true;
+    const aIsArray = Array.isArray(a);
+    if (aIsArray !== Array.isArray(b))
+        return false;
+    if (!aIsArray && (!isPlainObject(a) || !isPlainObject(b)))
+        return false;
+    const left = a;
+    const right = b;
+    if (aIsArray && a.length !== b.length) {
+        return false;
+    }
+    let partners = inProgress.get(left);
+    if (partners?.has(right))
+        return true;
+    if (!partners) {
+        partners = new Set();
+        inProgress.set(left, partners);
+    }
+    partners.add(right);
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    for (const key of keys) {
+        if (!compare(left[key], right[key], inProgress))
+            return false;
+    }
+    return true;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}