@pie-players/pie-assessment-toolkit 0.3.72 → 0.3.74

package/dist/services/ToolkitCoordinator.js

@@ -14,7 +14,7 @@
  * Part of PIE Assessment Toolkit.
  */
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
-import { normalizeAndValidateToolsConfig, normalizeToolConfigStrictness, } from "./tool-config-validation.js";
+import { collectToolConfigDiagnostics, normalizeToolConfigStrictness, reportToolConfigDiagnostics, } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
 import { ElementToolStateStore } from "./ElementToolStateStore.js";
 import { frameworkErrorFromCoordinatorContext, } from "./framework-error.js";
@@ -25,7 +25,7 @@ import { TTSService } from "./TTSService.js";
 import { BrowserTTSProvider } from "./tts/browser-provider.js";
 import { buildRuntimeTTSConfig, resolveTTSBackend, resolveTTSRuntimeSettings, } from "./tts-runtime-config.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
-import { ToolRegistry } from "./ToolRegistry.js";
+import { resolveToolProviderId, ToolRegistry } from "./ToolRegistry.js";
 import { ToolRequestRegistry } from "./tool-request.js";
 import { ToolPolicyEngine, } from "../policy/engine.js";
 import { resolveDefaultPnpEnforcement } from "../policy/internal.js";
@@ -81,9 +81,13 @@ const SECTION_SCOPED_EVENT_TYPES = [
  *
  * @example
  * ```typescript
+ * // createPackagedToolRegistry is exported by @pie-players/pie-default-tool-loaders
+ * const toolRegistry = createPackagedToolRegistry();
+ *
  * // Create coordinator with configuration
  * const coordinator = new ToolkitCoordinator({
  *   assessmentId: 'demo-three-questions',
+ *   toolRegistry,
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
@@ -96,7 +100,7 @@ const SECTION_SCOPED_EVENT_TYPES = [
  * });
  *
  * // Pass to section player
- * player.toolkitCoordinator = coordinator;
+ * player.runtime = { ...(player.runtime ?? {}), coordinator };
  *
  * // Access services directly
  * const ttsService = coordinator.ttsService;
@@ -127,6 +131,14 @@ export class ToolkitCoordinator {
     coordinatorReadyNotified = false;
     providerInitPromises = new Map();
     toolRegistry;
+    /** Whether the host passed `toolRegistry`, which then always stands. */
+    toolRegistrySupplied;
+    /**
+     * Whether the registry is final: supplied at construction, or adopted from
+     * the toolkit this coordinator is bound to. Until then the empty placeholder
+     * reports no missing registry, since the toolkit will supply one.
+     */
+    toolRegistrySettled;
     toolContextResolvers = new Map();
     toolContextResolverChangeListeners = new Set();
     toolRequests = new ToolRequestRegistry();
@@ -213,22 +225,40 @@ export class ToolkitCoordinator {
      * lifetime for no new information.
      */
     reportedUnboundFeaturePolicy = false;
-    static resolveConfig(config) {
+    /**
+     * Whether {@link _initializeTTS} has already reported a non-browser backend
+     * falling back to browser speech because no `tts` provider is registered.
+     * Once per coordinator: a text-to-speech config change re-runs
+     * initialization, and the missing provider is the same gap each time.
+     */
+    reportedMissingTTSProvider = false;
+    /**
+     * The backend of a fallback {@link reportMissingTTSProvider} held back while
+     * the registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    heldMissingTTSProviderBackend = null;
+    /**
+     * Whether {@link validateToolsConfig} has already reported validating with
+     * no registry (`tools.registryUnavailable`). Once per coordinator: every
+     * {@link updateToolConfig} and {@link updateToolsPlacement} re-validates, and
+     * the missing registry is the same gap each time.
+     */
+    reportedRegistryUnavailable = false;
+    resolveConfig(config) {
         const strictness = normalizeToolConfigStrictness(config.toolConfigStrictness);
-        // An empty registry when the host supplies none. This package no longer
-        // holds the packaged capability set, so there is nothing to fall back to —
-        // a host that wants stock tools passes a registry from
-        // `@pie-players/pie-default-tool-loaders`. Tool-id validation is skipped
-        // against an empty registry (with a diagnostic saying so) rather than
+        // An empty placeholder when the host supplies none, replaced by the bound
+        // toolkit's registry in `adoptToolRegistry`. This package does not hold the
+        // packaged capability set, and importing it would be a dependency cycle.
+        // Tool-id validation is skipped against an empty registry rather than
         // rejecting every configured id.
         const toolRegistry = config.toolRegistry ?? new ToolRegistry();
         const normalized = config.deferToolConfigValidation === true
             ? normalizeToolsConfig(config.tools)
-            : normalizeAndValidateToolsConfig(config.tools, {
+            : this.validateToolsConfig(config.tools, {
                 strictness,
                 source: "ToolkitCoordinator.init",
                 toolRegistry,
-            }).config;
+            });
         const defaultProviders = {
             textToSpeech: {
                 enabled: true,
@@ -256,11 +286,29 @@ export class ToolkitCoordinator {
             },
         };
     }
+    /**
+     * `normalizeAndValidateToolsConfig`, except that `tools.registryUnavailable`
+     * is reported once per coordinator, whichever call validates.
+     */
+    validateToolsConfig(tools, options) {
+        const { config, diagnostics } = collectToolConfigDiagnostics(tools, options.toolRegistry);
+        const unreported = this.reportedRegistryUnavailable || !this.toolRegistrySettled
+            ? diagnostics.filter((entry) => entry.code !== "tools.registryUnavailable")
+            : diagnostics;
+        reportToolConfigDiagnostics(unreported, options);
+        if (options.strictness !== "off" &&
+            unreported.some((entry) => entry.code === "tools.registryUnavailable")) {
+            this.reportedRegistryUnavailable = true;
+        }
+        return config;
+    }
     constructor(config) {
         if (!config.assessmentId) {
             throw new Error("ToolkitCoordinator requires assessmentId in config");
         }
-        const resolvedConfig = ToolkitCoordinator.resolveConfig(config);
+        this.toolRegistrySupplied = config.toolRegistry != null;
+        this.toolRegistrySettled = this.toolRegistrySupplied;
+        const resolvedConfig = this.resolveConfig(config);
         this.assessmentId = resolvedConfig.assessmentId;
         this.config = resolvedConfig;
         this.toolRegistry = resolvedConfig.toolRegistry ?? new ToolRegistry();
@@ -286,6 +334,9 @@ export class ToolkitCoordinator {
         this._registerToolProviders();
         // Initialize TTS service based on config
         this.ttsService = new TTSService();
+        // Selection read-aloud speaks through this service without the inline TTS
+        // tool ever having run, so it cannot rely on that tool to attach highlights.
+        this.ttsService.setHighlightCoordinator(this.highlightCoordinator);
         this.setupStatePersistenceHooks();
         // M8 PR 2 — construct the unified ToolPolicyEngine seeded with
         // the validated tools config. PNP/profile inputs (`assessment`,
@@ -527,6 +578,72 @@ export class ToolkitCoordinator {
         });
         return this.stateLoadPromise;
     }
+    reportMissingTTSProvider(backend) {
+        // The toolkit this coordinator binds to may still supply the provider.
+        if (!this.toolRegistrySettled) {
+            this.heldMissingTTSProviderBackend = backend;
+            return;
+        }
+        if (this.reportedMissingTTSProvider)
+            return;
+        this.reportedMissingTTSProvider = true;
+        console.warn(`[ToolkitCoordinator] Text-to-speech is configured for the "${backend}" backend but falls back to browser speech: no "tts" tool provider is registered. A coordinator registers tool providers only from its \`toolRegistry\`, or from its toolkit's when constructed without one, so supply one that carries the text-to-speech registration — for the packaged capability set, \`createPackagedToolRegistry()\` from "@pie-players/pie-default-tool-loaders". Reported once per coordinator.`);
+    }
+    /**
+     * Take the registry of the toolkit this coordinator is bound to, when the host
+     * constructed it without one: the config is validated against it, its
+     * providers register, and text-to-speech re-initializes through it if it
+     * already started. The toolkit elements call this on binding. A registry
+     * passed at construction stands, and the first call wins; `null` records a
+     * toolkit without one, which reports the registry as missing.
+     *
+     * @returns Whether `registry` was adopted.
+     */
+    adoptToolRegistry(registry) {
+        if (this.disposePromise !== null || this.toolRegistrySettled)
+            return false;
+        this.toolRegistrySettled = true;
+        const heldBackend = this.heldMissingTTSProviderBackend;
+        this.heldMissingTTSProviderBackend = null;
+        const strictness = this.config.toolConfigStrictness ?? "error";
+        const source = "ToolkitCoordinator.adoptToolRegistry";
+        if (!registry) {
+            this.validateToolsConfig(this.config.tools, {
+                strictness,
+                source,
+                toolRegistry: this.toolRegistry,
+            });
+            if (heldBackend)
+                this.reportMissingTTSProvider(heldBackend);
+            return false;
+        }
+        this.toolRegistry = registry;
+        this.config.toolRegistry = registry;
+        try {
+            // Warn at most: the config was accepted at construction, and a binding
+            // toolkit has no caller to throw to.
+            this.config.tools = this.validateToolsConfig(this.config.tools, {
+                strictness: strictness === "off" ? "off" : "warn",
+                source,
+                toolRegistry: registry,
+            });
+        }
+        catch (err) {
+            console.warn("[ToolkitCoordinator] Tool config does not validate against the adopted tool registry:", err);
+        }
+        this.policyEngine.replaceToolRegistry(registry, this.config.tools);
+        const ttsStarted = this.ttsInitialized ||
+            this.ttsInitPromise !== undefined ||
+            this.ttsReconfigurePromise !== undefined;
+        for (const tool of this.getProviderDescriptorTools()) {
+            if (ttsStarted && tool.toolId === "textToSpeech")
+                continue;
+            void this.registerProviderFromTool(tool);
+        }
+        if (ttsStarted)
+            this.scheduleTTSReconfigure();
+        return true;
+    }
     /**
      * Register tool providers in the registry
      */
@@ -539,40 +656,52 @@ export class ToolkitCoordinator {
     getProviderDescriptorTools() {
         return this.toolRegistry.getAllTools().filter((tool) => !!tool.provider);
     }
+    /**
+     * Register the provider `tool`'s descriptor creates for the tool's current
+     * config, unless the tool is disabled or that provider id is registered. A
+     * descriptor that throws is reported the way a failed registration is.
+     */
     async registerProviderFromTool(tool) {
         const descriptor = tool.provider;
         if (!descriptor)
             return;
-        const toolConfig = this.getToolConfig(tool.toolId) || undefined;
-        if (toolConfig?.enabled === false)
-            return;
-        const providerId = descriptor.getProviderId?.(toolConfig) ??
-            toolConfig?.provider?.id ??
-            tool.toolId;
-        if (this.toolProviderRegistry.has(providerId))
+        let providerId = null;
+        let registration;
+        try {
+            const toolConfig = this.getToolConfig(tool.toolId) || undefined;
+            if (toolConfig?.enabled === false)
+                return;
+            providerId = resolveToolProviderId(tool, toolConfig);
+            if (!providerId || this.toolProviderRegistry.has(providerId))
+                return;
+            const provider = descriptor.createProvider(toolConfig);
+            const initConfig = descriptor.getInitConfig?.(toolConfig) ??
+                toolConfig?.provider?.init ??
+                {};
+            const initConfigWithTelemetry = this.addToolTelemetryReporter({
+                toolId: tool.toolId,
+                providerId,
+                initConfig,
+            });
+            const registryTelemetry = this.createToolTelemetryForwarder({
+                toolId: tool.toolId,
+                providerId,
+            });
+            const authFetcher = descriptor.getAuthFetcher?.(toolConfig) ??
+                toolConfig?.provider?.runtime?.authFetcher;
+            registration = {
+                provider,
+                config: initConfigWithTelemetry,
+                lazy: descriptor.lazy ?? true,
+                authFetcher,
+                onTelemetry: registryTelemetry,
+            };
+        }
+        catch (err) {
+            this.reportProviderRegisterFailure(err, providerId, tool.toolId);
             return;
-        const provider = descriptor.createProvider(toolConfig);
-        const initConfig = descriptor.getInitConfig?.(toolConfig) ??
-            toolConfig?.provider?.init ??
-            {};
-        const initConfigWithTelemetry = this.addToolTelemetryReporter({
-            toolId: tool.toolId,
-            providerId,
-            initConfig,
-        });
-        const registryTelemetry = this.createToolTelemetryForwarder({
-            toolId: tool.toolId,
-            providerId,
-        });
-        const authFetcher = descriptor.getAuthFetcher?.(toolConfig) ??
-            toolConfig?.provider?.runtime?.authFetcher;
-        await this.registerProvider(providerId, {
-            provider,
-            config: initConfigWithTelemetry,
-            lazy: descriptor.lazy ?? true,
-            authFetcher,
-            onTelemetry: registryTelemetry,
-        });
+        }
+        await this.registerProvider(providerId, registration);
     }
     createToolTelemetryForwarder(args) {
         return async (eventName, payload) => {
@@ -616,10 +745,22 @@ export class ToolkitCoordinator {
             });
         }
         catch (err) {
-            console.warn(`[ToolkitCoordinator] Failed to register provider "${providerId}":`, err);
-            this.handleError(err, { phase: "provider-register", providerId });
+            this.reportProviderRegisterFailure(err, providerId);
         }
     }
+    /**
+     * A console warning and a `provider-register` framework error. `providerId`
+     * is null when resolving it is what failed; the warning names the tool then.
+     */
+    reportProviderRegisterFailure(err, providerId, toolId) {
+        console.warn(providerId
+            ? `[ToolkitCoordinator] Failed to register provider "${providerId}":`
+            : `[ToolkitCoordinator] Failed to register the provider of tool "${toolId}":`, err);
+        this.handleError(err, {
+            phase: "provider-register",
+            providerId: providerId ?? undefined,
+        });
+    }
     async ensureProviderReady(providerId) {
         this.assertNotDisposed();
         const existing = this.providerInitPromises.get(providerId);
@@ -1505,6 +1646,9 @@ export class ToolkitCoordinator {
                 console.warn("[ToolkitCoordinator] Failed to initialize TTS via registry, falling back to browser provider:", normalized);
             }
         }
+        else if (resolvedBackend !== "browser") {
+            this.reportMissingTTSProvider(resolvedBackend);
+        }
         // Fallback to browser provider
         const provider = new BrowserTTSProvider();
         try {
@@ -1688,8 +1832,7 @@ export class ToolkitCoordinator {
         };
     }
     getTTSConfigFromProviders() {
-        const providers = this.config.tools?.providers || {};
-        return providers.textToSpeech;
+        return this.config.tools?.providers?.textToSpeech;
     }
     assertCanonicalToolId(toolId) {
         if (typeof toolId !== "string" || toolId.trim().length === 0) {
@@ -1703,8 +1846,8 @@ export class ToolkitCoordinator {
         // host's every tool-config call into an exception — including the calls
         // this coordinator's own default-provider block provokes, which is how a
         // host that passes no registry ended up unable to read its own config.
-        // `normalizeAndValidateToolsConfig` already reports the missing registry
-        // once, as `tools.registryUnavailable`; a second report per call is noise.
+        // Validation reports the missing registry once per coordinator, as
+        // `tools.registryUnavailable`; a report per call would be noise.
         if (this.toolRegistry.getAllToolIds().length === 0)
             return;
         if (!this.toolRegistry.get(toolId)) {
@@ -1752,26 +1895,20 @@ export class ToolkitCoordinator {
         // Enabled by default unless explicitly set to false
         return toolConfig?.enabled !== false;
     }
-    /**
-     * Get tool configuration.
-     *
-     * @param toolId Tool identifier
-     * @returns Tool configuration or null if not configured
-     */
     getToolConfig(toolId) {
         this.assertCanonicalToolId(toolId);
-        return (this.config.tools?.providers?.[toolId] || null);
+        return this.config.tools?.providers?.[toolId] || null;
     }
     updateToolConfig(toolId, updates) {
         // Update config
         this.assertCanonicalToolId(toolId);
         const current = this.getToolConfig(toolId) || {};
         if (!this.config.tools) {
-            this.config.tools = normalizeAndValidateToolsConfig(undefined, {
+            this.config.tools = this.validateToolsConfig(undefined, {
                 strictness: this.config.toolConfigStrictness ?? "error",
                 source: "ToolkitCoordinator.updateToolConfig",
                 toolRegistry: this.toolRegistry,
-            }).config;
+            });
         }
         if (!this.config.tools.providers) {
             this.config.tools.providers = {};
@@ -1780,7 +1917,7 @@ export class ToolkitCoordinator {
             ...(this.config.tools.providers || {}),
             [toolId]: mergeToolConfigUpdate(toolId, current, updates),
         };
-        const validated = normalizeAndValidateToolsConfig({
+        this.config.tools = this.validateToolsConfig({
             ...this.config.tools,
             providers: nextProviders,
         }, {
@@ -1788,7 +1925,6 @@ export class ToolkitCoordinator {
             source: "ToolkitCoordinator.updateToolConfig",
             toolRegistry: this.toolRegistry,
         });
-        this.config.tools = validated.config;
         // M8 PR 2 — keep the policy engine's tools input in lockstep
         // with the validated coordinator config. The engine emits an
         // `inputs` change event so subscribers (e.g. PR 3 toolbars) can
@@ -1798,7 +1934,7 @@ export class ToolkitCoordinator {
         });
         void this.emitTelemetry("pie-toolkit-tool-config-updated", { toolId });
         // Apply configuration changes to services
-        this._applyToolConfigChange(toolId, updates);
+        this._applyToolConfigChange(toolId, current);
     }
     /**
      * Update the enabled tool list for one placement level.
@@ -1816,11 +1952,11 @@ export class ToolkitCoordinator {
      */
     updateToolsPlacement(partial) {
         if (!this.config.tools) {
-            this.config.tools = normalizeAndValidateToolsConfig(undefined, {
+            this.config.tools = this.validateToolsConfig(undefined, {
                 strictness: this.config.toolConfigStrictness ?? "error",
                 source: "ToolkitCoordinator.updateToolsPlacement",
                 toolRegistry: this.toolRegistry,
-            }).config;
+            });
         }
         const currentPlacement = this.config.tools?.placement ?? {
             section: [],
@@ -1832,7 +1968,7 @@ export class ToolkitCoordinator {
             item: [...(partial.item ?? currentPlacement.item ?? [])],
             passage: [...(partial.passage ?? currentPlacement.passage ?? [])],
         };
-        const validated = normalizeAndValidateToolsConfig({
+        const validated = this.validateToolsConfig({
             ...this.config.tools,
             placement: nextPlacement,
         }, {
@@ -1840,8 +1976,8 @@ export class ToolkitCoordinator {
             source: "ToolkitCoordinator.updateToolsPlacement",
             toolRegistry: this.toolRegistry,
         });
-        validated.config.placement = nextPlacement;
-        this.config.tools = validated.config;
+        validated.placement = nextPlacement;
+        this.config.tools = validated;
         this.policyEngine.updateInputs({
             tools: this.config.tools,
         });
@@ -1867,10 +2003,19 @@ export class ToolkitCoordinator {
      * capability it asks about, which is indistinguishable from a student who was
      * properly declined — so without this, forgetting {@link updateAssessment}
      * presents as an accommodation that silently never appears.
+     *
+     * A coordinator built with `assessmentOptional` reports only while PNP
+     * enforcement is explicitly `"on"`. Its toolkit binds whatever assessment the
+     * host gave, usually none, and a host that passes no profile and leaves
+     * enforcement unset or `"off"` has asked for no accommodation.
      */
     decideFeaturePolicy(featureId) {
         const decision = this.policyEngine.decideFeature(featureId);
-        if (!decision.assessmentBound && !this.reportedUnboundFeaturePolicy) {
+        const unboundIsMisconfigured = this.config.assessmentOptional !== true ||
+            this.pnpEnforcementOverride === "on";
+        if (!decision.assessmentBound &&
+            unboundIsMisconfigured &&
+            !this.reportedUnboundFeaturePolicy) {
             this.reportedUnboundFeaturePolicy = true;
             console.warn(`[ToolkitCoordinator] Feature policy was asked about "${featureId}" with no assessment bound, so every capability will be declined for want of a profile to read. Call updateAssessment(...) with the assessment (its personalNeedsProfile, settings.districtPolicy and settings.testAdministration are what policy reads) before relying on any accommodation. Reported once per coordinator.`);
         }
@@ -2109,37 +2254,80 @@ export class ToolkitCoordinator {
     }
     /**
      * Apply tool configuration changes to underlying services.
-     * Called after updateToolConfig().
+     * Called after updateToolConfig() with the tool's config before the update.
      */
-    _applyToolConfigChange(toolId, _updates) {
+    _applyToolConfigChange(toolId, previousConfig) {
         if (this.disposePromise !== null)
             return;
         // Apply configuration changes based on tool
         switch (toolId) {
-            case "textToSpeech": {
-                const reconfigurePromise = this._reconfigureTTSProvider();
-                this.ttsReconfigurePromise = reconfigurePromise;
-                void reconfigurePromise.finally(() => {
-                    if (this.ttsReconfigurePromise === reconfigurePromise) {
-                        this.ttsReconfigurePromise = undefined;
-                    }
-                });
-                void reconfigurePromise.then(async () => {
-                    if (this.disposePromise !== null)
-                        return;
-                    const ttsConfig = this.getTTSConfigFromProviders();
-                    if (!this.lazyInit && ttsConfig?.enabled !== false) {
-                        await this.ensureTTSReady(ttsConfig);
-                    }
-                });
+            case "textToSpeech":
+                this.scheduleTTSReconfigure();
                 break;
-            }
             case "answerEliminator":
                 // Future: Could notify answer eliminator tools of strategy change
                 break;
-            // Add cases for other tools as needed
+            default:
+                this._registerChangedToolProvider(toolId, previousConfig);
         }
     }
+    /**
+     * Register the provider a tool's updated config names, and unregister the
+     * one its previous config named when the provider id changed, as
+     * {@link _reconfigureTTSProvider} does for `tts`. Registration completes
+     * before this returns, so a check on the policy change the update dispatched
+     * finds the new provider.
+     */
+    _registerChangedToolProvider(toolId, previousConfig) {
+        const registration = this.getProviderDescriptorTools().find((tool) => tool.toolId === toolId);
+        if (!registration)
+            return;
+        void this.registerProviderFromTool(registration);
+        const resolveQuietly = (config) => {
+            try {
+                return resolveToolProviderId(registration, config);
+            }
+            catch {
+                return null;
+            }
+        };
+        const previousId = resolveQuietly(previousConfig);
+        const nextId = resolveQuietly(this.getToolConfig(toolId) || undefined);
+        if (!previousId ||
+            previousId === nextId ||
+            !this.toolProviderRegistry.has(previousId)) {
+            return;
+        }
+        void this.toolProviderRegistry.unregister(previousId).catch((err) => {
+            console.warn(`[ToolkitCoordinator] Failed to unregister provider "${previousId}":`, err);
+        });
+    }
+    /**
+     * Re-register the `tts` provider for the current config and registry, then
+     * re-initialize unless initialization is lazy. An initialization already
+     * running finishes first: it would otherwise mark its provider ready after
+     * the reset.
+     */
+    scheduleTTSReconfigure() {
+        const inFlight = this.ttsInitPromise;
+        const reconfigurePromise = inFlight
+            ? inFlight.catch(() => { }).then(() => this._reconfigureTTSProvider())
+            : this._reconfigureTTSProvider();
+        this.ttsReconfigurePromise = reconfigurePromise;
+        void reconfigurePromise.finally(() => {
+            if (this.ttsReconfigurePromise === reconfigurePromise) {
+                this.ttsReconfigurePromise = undefined;
+            }
+        });
+        void reconfigurePromise.then(async () => {
+            if (this.disposePromise !== null)
+                return;
+            const ttsConfig = this.getTTSConfigFromProviders();
+            if (!this.lazyInit && ttsConfig?.enabled !== false) {
+                await this.ensureTTSReady(ttsConfig);
+            }
+        });
+    }
     async _reconfigureTTSProvider() {
         this.ttsInitialized = false;
         this.ttsInitPromise = undefined;

package/dist/services/catalog-owner.d.ts

@@ -68,4 +68,15 @@ export declare function catalogOwnerContextFor(owner: CatalogOwnerIdentity): Cat
  * register the owner once through `AccessibilityCatalogResolver.registerOwner`.
  */
 export declare function collectOwnerCatalogRegistrations(entity: CatalogSourceEntity | null | undefined, owner: CatalogOwnerIdentity): CatalogOwnerRegistrationEntry[];
+/**
+ * The catalogs an owner registration of `entity` would file, as a string equal
+ * for any two entities that register the same catalogs. A shell holding new
+ * content under an unchanged identity compares it to decide whether the runtime
+ * has anything new to register. It is derived from the registration walk, so it
+ * cannot disagree with the registration about what counts as a catalog.
+ *
+ * `null` when the catalogs do not serialize: nothing can be concluded, and the
+ * caller registers again.
+ */
+export declare function catalogSourceSignature(entity: CatalogSourceEntity | null | undefined, kind: CatalogOwnerIdentity["kind"]): string | null;
 export {};

package/dist/services/catalog-owner.js

@@ -62,3 +62,28 @@ export function collectOwnerCatalogRegistrations(entity, owner) {
     }
     return registrations;
 }
+/**
+ * The catalogs an owner registration of `entity` would file, as a string equal
+ * for any two entities that register the same catalogs. A shell holding new
+ * content under an unchanged identity compares it to decide whether the runtime
+ * has anything new to register. It is derived from the registration walk, so it
+ * cannot disagree with the registration about what counts as a catalog.
+ *
+ * `null` when the catalogs do not serialize: nothing can be concluded, and the
+ * caller registers again.
+ */
+export function catalogSourceSignature(entity, kind) {
+    const registrations = collectOwnerCatalogRegistrations(entity, {
+        kind,
+        itemId: "",
+    });
+    try {
+        return JSON.stringify(registrations.map((registration) => [
+            registration.context.modelId ?? null,
+            registration.catalogs,
+        ]));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/create-tools-config.d.ts

@@ -1,8 +1,8 @@
-import type { CanonicalToolsConfig } from "./tools-config-normalizer.js";
+import type { ToolsConfigInput } from "./tools-config-normalizer.js";
 import type { ToolRegistry } from "./ToolRegistry.js";
 import { type ToolConfigStrictness, type ToolConfigValidationResult } from "./tool-config-validation.js";
 export interface CreateToolsConfigArgs {
-    tools?: Partial<CanonicalToolsConfig> | null;
+    tools?: ToolsConfigInput | null;
     toolRegistry?: ToolRegistry | null;
     strictness?: ToolConfigStrictness;
     source?: string;

package/dist/services/framework-error.d.ts

@@ -13,7 +13,14 @@ export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispo
  * key still resolves through the English fallback chain, so the player renders
  * — in the wrong language, which a host wants to know about.
  */
- | "i18n-locale-load" | "unknown";
+ | "i18n-locale-load"
+/**
+ * A section player could not register the elements its items need before
+ * mounting them: a renderable failed the config contract, an element bundle
+ * or module failed to load, or a `preloaded` page lacks a registration the
+ * content names. Not recoverable — the section's items stay unmounted.
+ */
+ | "element-preload" | "unknown";
 export type FrameworkErrorSeverity = "warning" | "error";
 export interface FrameworkErrorModel {
     kind: FrameworkErrorKind;