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

package/dist/services/ToolRegistry.d.ts

@@ -4,17 +4,32 @@
  * Central registry for all assessment tools. Manages tool metadata, visibility logic,
  * and button/instance creation. Supports dynamic registration and override by integrators.
  */
+import type { CatalogOwnerSnapshot } from "./AccessibilityCatalogResolver.js";
 import type { ToolContext, ToolLevel } from "./tool-context.js";
 import type { ToolComponentOverrides } from "../tools/tool-tag-map.js";
-import type { ElementToolStateStoreApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi } from "./interfaces.js";
+import type { AccessibilityCatalogResolverApi, ElementToolStateStoreApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi } from "./interfaces.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { ToolProviderConfig as ToolRuntimeConfig } from "./tools-config-normalizer.js";
 import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
 export type ToolModuleLoader = () => Promise<unknown>;
+export type ToolRegistryChangeKind = "register" | "override" | "unregister" | "clear" | "component-overrides" | "module-loaders";
+/** A successful mutation to discoverable or rendering registry state. */
+export interface ToolRegistryChangeEvent {
+    kind: ToolRegistryChangeKind;
+    toolIds: readonly string[];
+}
+export type ToolRegistryChangeListener = (event: ToolRegistryChangeEvent) => void;
 export interface ToolToolbarButtonDefinition {
     toolId: string;
     label: string;
-    icon: string;
+    /**
+     * Optional to match what the renderers already do: `ToolButton.svelte` and
+     * `ItemToolBar.svelte` both guard on `button.icon`, and `ToolbarItem.icon` is
+     * already optional, so requiring it here claimed a guarantee nothing relied
+     * on. A registration that renders a button still has to declare an icon —
+     * `assertToolRegistrationShape` enforces that.
+     */
+    icon?: string;
     ariaLabel: string;
     tooltip?: string;
     onClick: () => void;
@@ -148,8 +163,147 @@ export interface ToolToolbarRenderResult {
     sync?: () => void;
     subscribeActive?: (callback: (active: boolean) => void) => () => void;
 }
-export type ToolActivation = "toolbar-toggle" | "selection-gateway";
+export type ToolActivation = "toolbar-toggle" | "selection-gateway" | "region";
 export type ToolSingletonScope = "section";
+/**
+ * Services a host hands a capability rendering into one of its surfaces.
+ *
+ * Deliberately the same three references a toolbar tool reaches through
+ * `ToolbarContext`, and no more: a capability that needs the coordinator can ask
+ * it for anything else. Passing the host's own component or state would make the
+ * registration depend on which renderer mounted it.
+ */
+export interface ToolSurfaceServices {
+    toolkitCoordinator: ToolkitCoordinatorApi | null;
+    ttsService: TtsServiceApi | null;
+    catalogResolver: AccessibilityCatalogResolverApi | null;
+}
+/**
+ * What a host tells a capability when asking it to fill a surface.
+ *
+ * `surface` is a host-defined slot name. Core defines none and validates only
+ * that a region capability claims at least one, so a host can open a new surface
+ * without a change here and a capability can declare which of a host's surfaces
+ * it fits. Section-player ships `"content-lead"` and `"content-media"` on item
+ * and passage cards, plus `"section-overlay"` at section scope.
+ *
+ * `content` carries whatever the capability's own `requiresAuthoredContent`
+ * resolved, so the host neither inspects nor names it — it hands back what the
+ * capability asked for.
+ */
+export interface ToolSurfaceRenderContext {
+    toolId: string;
+    /** The PNP/AfA support id policy granted for this render. */
+    featureId: string;
+    /** Host slot being filled. */
+    surface: string;
+    /** Feature parameters from the policy decision, if any. */
+    parameters?: unknown;
+    /** Resolved content dependency, when the capability declares one. */
+    content?: unknown;
+    services: ToolSurfaceServices;
+    componentOverrides?: ToolComponentOverrides;
+}
+/**
+ * What a host tells a capability when asking whether the content it needs is
+ * present.
+ */
+export interface ToolContentDependencyContext {
+    /** The PNP/AfA support id being resolved. */
+    featureId: string;
+    /** Feature parameters from the policy decision, if any. */
+    parameters?: unknown;
+    /**
+     * Owner-scoped catalog cards, or `null` when no resolver is available.
+     *
+     * The catalog module has already applied item/passage/model traversal and
+     * registration precedence. A capability interprets its own card type without
+     * reconstructing the owner scope or reading the raw entity.
+     */
+    catalogs: CatalogOwnerSnapshot | null;
+    /**
+     * Whether policy granted one of this capability's support ids.
+     *
+     * `false` reaches `resolve` only for a capability that declares
+     * {@link ToolRegistration.resolvesWithoutGrant}, and it is the signal that the
+     * capability must answer from the content alone. Everything else sees `true`,
+     * because the host asks about eligibility first and stops there.
+     */
+    granted: boolean;
+}
+/**
+ * A capability's declaration that it needs authored content to have anything to
+ * show, and the check that decides whether that content is present.
+ *
+ * This is the resource half of AfA's PNP/DRD pair. Signing needs an authored
+ * catalog card, braille a transcription, authored SSML a `<speak>` in that item.
+ * It is intrinsic to the capability, unlike eligibility tier, which is a property
+ * of the program.
+ *
+ * Two independent things follow from declaring it, and both used to be done by
+ * naming ids in core:
+ *
+ *   1. **Availability is grant AND content.** The host renders only when policy
+ *      granted the feature *and* `resolve` returned something. Neither half
+ *      implies the other and neither is a default, so a learner with the
+ *      accommodation still sees nothing on an item that carries no resource — no
+ *      dead affordance.
+ *   2. **It is not granted wholesale.** A host building a default grant list
+ *      filters on this declaration instead of on a compile-time array of ids it
+ *      cannot extend. `@pie-players/pie-default-tool-loaders` asserts its
+ *      universal preset holds no id belonging to a capability that declares one.
+ *
+ * `resolve` returns the resolved content, which the host hands straight back
+ * through `ToolSurfaceRenderContext.content` without inspecting it. That is what
+ * keeps the resolver and the host from knowing which accommodation they are
+ * resolving.
+ *
+ * Resolvable only on a surface the host renders per item or per passage. The
+ * owner snapshot represents an item/model or passage, never a section, because a DRD
+ * resource pairs with a piece of content and not with a container. A capability
+ * declaring one and claiming a section-scoped surface is declined there rather
+ * than mounted with no content. `resolve` is also synchronous — a capability whose
+ * resource has to be fetched resolves the reference here and fetches inside its
+ * own element, where it can show its own pending state.
+ */
+export interface ToolContentDependency {
+    /**
+     * The resolved content, or `null` when the item carries none.
+     *
+     * Must be JSON-serializable. A host re-resolves on every policy and catalog
+     * signal and compares the answer structurally to decide whether anything moved,
+     * because every resolution builds fresh objects and identity would report a
+     * change each time. A `Map`, function, DOM node, cyclic value, or other
+     * non-serializable result is rejected for that capability and reported as a
+     * recoverable surface warning instead of escaping into the player.
+     */
+    resolve(context: ToolContentDependencyContext): unknown | null;
+    /**
+     * Optional human-readable description of what has to be authored, for a
+     * policy debugger explaining why an otherwise-granted capability is absent.
+     */
+    description?: string;
+}
+export interface ToolSurfaceRenderResult {
+    /** Element for the host to mount into its surface. */
+    element: HTMLElement;
+    /** Accessible name for the surface, when the capability owns that wording. */
+    ariaLabel?: string;
+    /**
+     * Reapply props after policy, parameters or content change.
+     *
+     * Takes the current context rather than closing over the one captured at
+     * render: the whole point of reconciling by `toolId` instead of remounting is
+     * that a re-resolve reaches the mounted element, and a closure over the
+     * render-time context re-applies the values the host already had. A signed
+     * alternate re-resolved to a different recording — a live `signLang` change, or
+     * a catalog registering after first paint — would otherwise leave the learner
+     * watching the previous one with no error anywhere.
+     */
+    sync?: (context: ToolSurfaceRenderContext) => void;
+    /** Release listeners and media before the host unmounts the element. */
+    destroy?: () => void;
+}
 /**
  * Tool registration interface
  */
@@ -160,16 +314,31 @@ export interface ToolRegistration {
     name: string;
     /** Description of what the tool does */
     description: string;
-    /** Icon identifier or SVG string */
-    icon: string | ((context: ToolContext) => string);
+    /**
+     * Icon identifier or SVG string. Required for the activations that render a
+     * toolbar button; a region capability has no button, so it has no icon.
+     */
+    icon?: string | ((context: ToolContext) => string);
     /** Which levels this tool supports */
     supportedLevels: ToolLevel[];
     /**
      * Activation model for this tool.
      * - toolbar-toggle: rendered as a toolbar button (default)
      * - selection-gateway: rendered as a singleton selection-driven gateway
+     * - region: rendered into a host surface, with no toolbar button
      */
     activation?: ToolActivation;
+    /**
+     * Host surfaces this capability can fill. Required for `activation: "region"`
+     * and meaningful for any activation whose capability also has a non-toolbar
+     * surface — the annotation toolbar is both a toolbar button and a
+     * section-scoped singleton.
+     *
+     * Names are the host's, not core's. A host discovers what it can mount by
+     * asking {@link ToolRegistry.getToolsBySurface}, which is what keeps a
+     * renderer from naming a capability.
+     */
+    surfaces?: string[];
     /**
      * Optional singleton scope for activation models that mount exactly one instance.
      */
@@ -180,6 +349,30 @@ export interface ToolRegistration {
      * Example: ['calculator', 'basic-calculator', 'scientific-calculator']
      */
     pnpSupportIds?: string[];
+    /**
+     * Authored content this capability needs before it has anything to show.
+     *
+     * Declaring it makes availability "grant AND content", and excludes the
+     * capability from any wholesale default grant. See
+     * {@link ToolContentDependency}.
+     */
+    requiresAuthoredContent?: ToolContentDependency;
+    /**
+     * Ask this capability for its content even when policy granted nothing.
+     *
+     * Only meaningful together with {@link ToolRegistration.requiresAuthoredContent},
+     * and only correct for a capability whose authored content can declare itself
+     * *presentation* rather than an accommodation — content authored to be delivered
+     * that way to everyone, which no profile grants and none revokes. Such a
+     * capability must return `null` from `resolve` when its content is the
+     * accommodation kind and the grant is absent, and the `granted` flag on the
+     * context is how it tells the two apart.
+     *
+     * Without this, "no grant" ends the question before content is consulted, which
+     * is the right default: it is what keeps an accommodation off the item of a
+     * learner with no documented need.
+     */
+    resolvesWithoutGrant?: boolean;
     /**
      * Optional provider registration metadata.
      * When present, ToolkitCoordinator can register provider(s) generically
@@ -196,12 +389,31 @@ export interface ToolRegistration {
      * Pass 2: Tool decides if it's relevant in this context
      * Called ONLY if orchestrator has already allowed the tool (Pass 1)
      *
+     * Required for the toolbar activations, and meaningless for `activation:
+     * "region"`: a region capability has no toolbar presence to be relevant to, and
+     * the question it *would* answer — is there anything to show here — is
+     * `requiresAuthoredContent`. A registration that omits this is never returned
+     * by `getVisibleTools`.
+     *
      * @param context - Rich context about where tool is being evaluated
      * @returns true if tool should be visible, false to hide
      */
-    isVisibleInContext(context: ToolContext): boolean;
-    /** Required toolbar-first render contract. */
-    renderToolbar(context: ToolContext, toolbarContext: ToolbarContext): ToolToolbarRenderResult | null;
+    isVisibleInContext?(context: ToolContext): boolean;
+    /**
+     * Toolbar render contract. Required for `toolbar-toggle` and
+     * `selection-gateway`; a region capability renders through
+     * {@link ToolRegistration.renderSurface} instead.
+     */
+    renderToolbar?(context: ToolContext, toolbarContext: ToolbarContext): ToolToolbarRenderResult | null;
+    /**
+     * Render into one of the host surfaces this capability declares.
+     *
+     * Returning `null` means "nothing to show for this render" and is not an
+     * error — a capability may decline once the host has already granted and
+     * resolved content. The host mounts the returned element and calls `sync()`
+     * when policy, parameters or content move.
+     */
+    renderSurface?(context: ToolSurfaceRenderContext): ToolSurfaceRenderResult | null;
 }
 /**
  * Tool Registry
@@ -215,6 +427,13 @@ export declare class ToolRegistry {
     private moduleLoaders;
     private loadedToolModules;
     private moduleLoadPromises;
+    private changeListeners;
+    private emitChange;
+    /**
+     * Observe successful registry mutations. Delivery is synchronous, listener
+     * failures are isolated, and the returned unsubscribe is idempotent.
+     */
+    onRegistryChange(listener: ToolRegistryChangeListener): () => void;
     /**
      * Normalize a single tool alias to canonical toolId.
      */
@@ -290,6 +509,23 @@ export declare class ToolRegistry {
      * Resolve singleton scope for a tool when present.
      */
     getToolSingletonScope(toolId: string): ToolSingletonScope | null;
+    /**
+     * Registrations that can fill a named host surface.
+     *
+     * The discovery call a renderer makes instead of naming a capability. Order
+     * follows registration order, so a host mounting several capabilities into one
+     * surface gets a stable sequence without core deciding a precedence it has no
+     * basis for.
+     */
+    getToolsBySurface(surface: string): ToolRegistration[];
+    /**
+     * Support ids belonging to capabilities that need authored content.
+     *
+     * What a host filters a default grant list on, in place of the compile-time
+     * exclusion array this replaced: granting one of these wholesale grants an
+     * accommodation to learners with no documented need for it.
+     */
+    getContentDependentSupportIds(): string[];
     /**
      * Filter tool IDs by activation type.
      */
@@ -319,6 +555,9 @@ export declare class ToolRegistry {
         supportedLevels: ToolLevel[];
         activation: ToolActivation;
         singletonScope: ToolSingletonScope | null;
+        surfaces: string[];
+        requiresAuthoredContent: boolean;
+        contentDependencyDescription: string | null;
     }>;
     /**
      * Generate PNP support IDs from enabled tools
@@ -358,4 +597,16 @@ export declare class ToolRegistry {
      * Render a tool for toolbar use with component overrides attached.
      */
     renderForToolbar(toolId: string, context: ToolContext, toolbarContext: ToolbarContext): ToolToolbarRenderResult | null;
+    /**
+     * Render a capability into a host surface, with component overrides attached.
+     *
+     * The surface counterpart of {@link renderForToolbar}, and it exists for the
+     * same reason: the registry owns the component-override map, so a host calling
+     * `registration.renderSurface(...)` directly would resolve element tags against
+     * nothing and fail on every packaged capability. Overrides passed in the
+     * context still win, matching the toolbar path's precedence.
+     */
+    renderForSurface(toolId: string, context: Omit<ToolSurfaceRenderContext, "componentOverrides"> & {
+        componentOverrides?: ToolComponentOverrides;
+    }): ToolSurfaceRenderResult | null;
 }

package/dist/services/ToolRegistry.js

@@ -55,9 +55,15 @@ function assertToolRegistrationShape(registration) {
     assertNonEmptyString(registration.toolId, "toolId");
     assertNonEmptyString(registration.name, "name");
     assertNonEmptyString(registration.description, "description");
-    if (typeof registration.icon !== "string" &&
-        typeof registration.icon !== "function") {
-        throw new Error(`Invalid tool registration "${registration.toolId}": "icon" must be a string or function.`);
+    // A region capability renders into a host surface and has no toolbar button,
+    // so it needs neither an icon nor `renderToolbar`. Both stay required for the
+    // activations that do render a button, so no existing registration is relaxed.
+    const isRegion = registration.activation === "region";
+    if (!isRegion || registration.icon !== undefined) {
+        if (typeof registration.icon !== "string" &&
+            typeof registration.icon !== "function") {
+            throw new Error(`Invalid tool registration "${registration.toolId}": "icon" must be a string or function.`);
+        }
     }
     if (typeof registration.icon === "string") {
         assertIconStringIsSafe(registration.toolId, registration.icon, "icon");
@@ -72,9 +78,41 @@ function assertToolRegistrationShape(registration) {
     }
     if (registration.activation !== undefined &&
         registration.activation !== "toolbar-toggle" &&
-        registration.activation !== "selection-gateway") {
+        registration.activation !== "selection-gateway" &&
+        registration.activation !== "region") {
         throw new Error(`Invalid tool registration "${registration.toolId}": unsupported activation "${String(registration.activation)}".`);
     }
+    if (registration.surfaces !== undefined &&
+        (!Array.isArray(registration.surfaces) ||
+            registration.surfaces.some((surface) => typeof surface !== "string" || surface.trim().length === 0))) {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "surfaces" must be an array of non-empty strings.`);
+    }
+    if (isRegion && !registration.surfaces?.length) {
+        throw new Error(`Invalid tool registration "${registration.toolId}": region tools must declare at least one host surface in "surfaces".`);
+    }
+    if (isRegion && typeof registration.renderSurface !== "function") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": region tools must implement "renderSurface".`);
+    }
+    if (registration.resolvesWithoutGrant !== undefined &&
+        typeof registration.resolvesWithoutGrant !== "boolean") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "resolvesWithoutGrant" must be a boolean.`);
+    }
+    if (registration.resolvesWithoutGrant &&
+        !registration.requiresAuthoredContent) {
+        // The flag only decides whether content is consulted without a grant, so on a
+        // capability with no content dependency it reads as "granted to everyone" and
+        // does nothing at all.
+        throw new Error(`Invalid tool registration "${registration.toolId}": "resolvesWithoutGrant" requires "requiresAuthoredContent".`);
+    }
+    if (registration.renderSurface !== undefined &&
+        typeof registration.renderSurface !== "function") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "renderSurface" must be a function.`);
+    }
+    if (registration.renderSurface && !registration.surfaces?.length) {
+        // A surface renderer nothing can find is a registration that silently does
+        // not render, which is the failure mode this mechanism exists to remove.
+        throw new Error(`Invalid tool registration "${registration.toolId}": "renderSurface" requires at least one entry in "surfaces".`);
+    }
     if (registration.singletonScope !== undefined &&
         registration.singletonScope !== "section") {
         throw new Error(`Invalid tool registration "${registration.toolId}": unsupported singletonScope "${String(registration.singletonScope)}".`);
@@ -88,10 +126,33 @@ function assertToolRegistrationShape(registration) {
             registration.pnpSupportIds.some((pnpId) => typeof pnpId !== "string" || pnpId.trim().length === 0))) {
         throw new Error(`Invalid tool registration "${registration.toolId}": "pnpSupportIds" must be an array of non-empty strings.`);
     }
-    if (typeof registration.isVisibleInContext !== "function") {
+    if (registration.activation !== "region" &&
+        typeof registration.isVisibleInContext !== "function") {
         throw new Error(`Invalid tool registration "${registration.toolId}": "isVisibleInContext" must be a function.`);
     }
-    if (typeof registration.renderToolbar !== "function") {
+    if (registration.isVisibleInContext !== undefined &&
+        typeof registration.isVisibleInContext !== "function") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "isVisibleInContext" must be a function when present.`);
+    }
+    if (registration.requiresAuthoredContent !== undefined) {
+        if (typeof registration.requiresAuthoredContent !== "object" ||
+            registration.requiresAuthoredContent === null ||
+            typeof registration.requiresAuthoredContent.resolve !== "function") {
+            throw new Error(`Invalid tool registration "${registration.toolId}": "requiresAuthoredContent" must be an object with a "resolve" function.`);
+        }
+        if (!registration.pnpSupportIds?.length) {
+            // A content dependency's second job is keeping the capability out of a
+            // wholesale grant, and a host filters that by support id. Declaring one
+            // with no id to filter on would silently drop that guarantee.
+            throw new Error(`Invalid tool registration "${registration.toolId}": "requiresAuthoredContent" requires at least one entry in "pnpSupportIds", which is what a host filters a default grant list on.`);
+        }
+    }
+    if (registration.renderToolbar !== undefined) {
+        if (typeof registration.renderToolbar !== "function") {
+            throw new Error(`Invalid tool registration "${registration.toolId}": "renderToolbar" must be a function.`);
+        }
+    }
+    else if (!isRegion) {
         throw new Error(`Invalid tool registration "${registration.toolId}": "renderToolbar" must be a function.`);
     }
 }
@@ -107,6 +168,31 @@ export class ToolRegistry {
     moduleLoaders = new Map();
     loadedToolModules = new Set();
     moduleLoadPromises = new Map();
+    changeListeners = new Set();
+    emitChange(event) {
+        for (const listener of this.changeListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.warn("[ToolRegistry] change listener failed:", error);
+            }
+        }
+    }
+    /**
+     * Observe successful registry mutations. Delivery is synchronous, listener
+     * failures are isolated, and the returned unsubscribe is idempotent.
+     */
+    onRegistryChange(listener) {
+        this.changeListeners.add(listener);
+        let subscribed = true;
+        return () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            this.changeListeners.delete(listener);
+        };
+    }
     /**
      * Normalize a single tool alias to canonical toolId.
      */
@@ -140,6 +226,7 @@ export class ToolRegistry {
                 this.pnpIndex.get(pnpId).add(registration.toolId);
             }
         }
+        this.emitChange({ kind: "register", toolIds: [registration.toolId] });
     }
     /**
      * Override an existing tool registration
@@ -169,6 +256,7 @@ export class ToolRegistry {
                 this.pnpIndex.get(pnpId).add(registration.toolId);
             }
         }
+        this.emitChange({ kind: "override", toolIds: [registration.toolId] });
     }
     /**
      * Unregister a tool
@@ -186,6 +274,7 @@ export class ToolRegistry {
             }
         }
         this.tools.delete(toolId);
+        this.emitChange({ kind: "unregister", toolIds: [toolId] });
     }
     /**
      * Get a tool registration by ID
@@ -251,6 +340,37 @@ export class ToolRegistry {
     getToolSingletonScope(toolId) {
         return this.get(toolId)?.singletonScope || null;
     }
+    /**
+     * Registrations that can fill a named host surface.
+     *
+     * The discovery call a renderer makes instead of naming a capability. Order
+     * follows registration order, so a host mounting several capabilities into one
+     * surface gets a stable sequence without core deciding a precedence it has no
+     * basis for.
+     */
+    getToolsBySurface(surface) {
+        if (!surface)
+            return [];
+        return this.getAllTools().filter((tool) => typeof tool.renderSurface === "function" &&
+            tool.surfaces?.includes(surface));
+    }
+    /**
+     * Support ids belonging to capabilities that need authored content.
+     *
+     * What a host filters a default grant list on, in place of the compile-time
+     * exclusion array this replaced: granting one of these wholesale grants an
+     * accommodation to learners with no documented need for it.
+     */
+    getContentDependentSupportIds() {
+        const ids = new Set();
+        for (const tool of this.getAllTools()) {
+            if (!tool.requiresAuthoredContent)
+                continue;
+            for (const supportId of tool.pnpSupportIds || [])
+                ids.add(supportId);
+        }
+        return [...ids].sort();
+    }
     /**
      * Filter tool IDs by activation type.
      */
@@ -279,9 +399,10 @@ export class ToolRegistry {
             if (!tool.supportedLevels.includes(context.level)) {
                 continue;
             }
-            // Pass 2: Ask tool if it's relevant
+            // Pass 2: Ask tool if it's relevant. A region capability declares no
+            // answer and has no toolbar presence, so it is never visible here.
             try {
-                if (tool.isVisibleInContext(context)) {
+                if (tool.isVisibleInContext?.(context)) {
                     visible.push(tool);
                 }
             }
@@ -306,6 +427,9 @@ export class ToolRegistry {
             supportedLevels: tool.supportedLevels,
             activation: tool.activation || "toolbar-toggle",
             singletonScope: tool.singletonScope || null,
+            surfaces: tool.surfaces || [],
+            requiresAuthoredContent: Boolean(tool.requiresAuthoredContent),
+            contentDependencyDescription: tool.requiresAuthoredContent?.description ?? null,
         }));
     }
     /**
@@ -331,28 +455,43 @@ export class ToolRegistry {
      * Clear all registrations (useful for testing)
      */
     clear() {
+        const toolIds = this.getAllToolIds();
+        if (toolIds.length === 0)
+            return;
         this.tools.clear();
         this.pnpIndex.clear();
+        this.emitChange({ kind: "clear", toolIds });
     }
     /**
      * Configure global component overrides used by tool instance creation.
      */
     setComponentOverrides(overrides) {
+        if (this.componentOverrides === overrides)
+            return;
         this.componentOverrides = overrides;
+        this.emitChange({ kind: "component-overrides", toolIds: [] });
     }
     /**
      * Register lazy module loaders by toolId.
      * Toolbars call ensureToolModuleLoaded(toolId) before instance creation.
      */
     setToolModuleLoaders(loaders) {
-        for (const [toolId, loader] of Object.entries(loaders)) {
-            if (!loader)
-                continue;
+        const entries = Object.entries(loaders).filter((entry) => entry[1] !== undefined);
+        for (const [toolId, loader] of entries) {
             assertNonEmptyString(toolId, "tool module loader id");
             if (typeof loader !== "function") {
                 throw new Error(`Invalid tool module loader for "${toolId}": expected a function.`);
             }
+        }
+        const changedToolIds = [];
+        for (const [toolId, loader] of entries) {
+            if (this.moduleLoaders.get(toolId) === loader)
+                continue;
             this.moduleLoaders.set(toolId, loader);
+            changedToolIds.push(toolId);
+        }
+        if (changedToolIds.length > 0) {
+            this.emitChange({ kind: "module-loaders", toolIds: changedToolIds });
         }
     }
     /**
@@ -402,6 +541,12 @@ export class ToolRegistry {
         if (!tool) {
             throw new Error(`Tool '${toolId}' is not registered`);
         }
+        if (typeof tool.renderToolbar !== "function") {
+            // Naming the activation rather than "renderToolbar is not a function":
+            // the caller's mistake is asking a surface capability for a toolbar
+            // button, and it is fixed by placement config, not by the registration.
+            throw new Error(`Tool '${toolId}' has activation "${tool.activation || "toolbar-toggle"}" and renders into a host surface, not a toolbar. Remove it from toolbar placement.`);
+        }
         const mergedContext = {
             ...toolbarContext,
             componentOverrides: {
@@ -411,4 +556,29 @@ export class ToolRegistry {
         };
         return tool.renderToolbar(context, mergedContext);
     }
+    /**
+     * Render a capability into a host surface, with component overrides attached.
+     *
+     * The surface counterpart of {@link renderForToolbar}, and it exists for the
+     * same reason: the registry owns the component-override map, so a host calling
+     * `registration.renderSurface(...)` directly would resolve element tags against
+     * nothing and fail on every packaged capability. Overrides passed in the
+     * context still win, matching the toolbar path's precedence.
+     */
+    renderForSurface(toolId, context) {
+        const tool = this.get(toolId);
+        if (!tool) {
+            throw new Error(`Tool '${toolId}' is not registered`);
+        }
+        if (typeof tool.renderSurface !== "function") {
+            throw new Error(`Tool '${toolId}' does not render into a host surface. Surface capabilities declare "surfaces" and implement "renderSurface".`);
+        }
+        return tool.renderSurface({
+            ...context,
+            componentOverrides: {
+                ...(this.componentOverrides || {}),
+                ...(context.componentOverrides || {}),
+            },
+        });
+    }
 }