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

package/dist/runtime/composition-emit-scheduler.js

@@ -0,0 +1,154 @@
+/**
+ * Composition emit scheduler (PIE-885).
+ *
+ * `PieAssessmentToolkit.svelte` publishes the section composition to the
+ * players through exactly one path — the `composition-changed` event — and
+ * coalesces bursts of updates behind a one-shot latch so several changes
+ * within one frame produce a single emit.
+ *
+ * That latch used to be cleared only by a `requestAnimationFrame` callback,
+ * and the frame branch was chosen whenever `window.requestAnimationFrame`
+ * merely *existed* rather than when it was known to fire. In a document that
+ * never paints the callback never ran, the latch never cleared, and no
+ * `composition-changed` was ever dispatched: the section controller held a
+ * correct view model while the player kept its initial empty composition, so
+ * every `pie-section-player` route rendered no content at all. The permanent
+ * failure was in contexts with no compositor — headless browsers, hidden or
+ * offscreen tabs, agent and CI automation harnesses. A background tab only
+ * rendered late, because its pending frame becomes due on refocus.
+ *
+ * So the frame is raced against a deadline timer instead of trusted. Whichever
+ * arrives first releases the latch and flushes, and a non-painting document
+ * degrades to a slower render rather than a permanent blank. Svelte's own
+ * `tick()` races the same two primitives for the same reason.
+ *
+ * This scheduler owns the latch and both handles, which is what makes "the
+ * latch cannot stay set after a scheduled frame is cancelled or superseded"
+ * structural rather than a discipline every call site has to keep: releasing
+ * the latch and releasing the handles is one operation in one place.
+ *
+ * Deliberately stateless across cycles. A cycle the timer wins does not switch
+ * the scheduler into a timer-preferring mode: that trades the deadline cost for
+ * a mode which never returns to frame alignment once a single frame is missed,
+ * and a slower render is the accepted outcome.
+ *
+ * NOT a public surface: internal to the toolkit and not exported from
+ * `runtime/engine.ts`. It exists as its own module so the race can be pinned in
+ * a unit test without mounting the toolkit CE — same rationale as
+ * `runtime/stage-emit-gate.ts`.
+ */
+/**
+ * How long to wait for a frame before the timer takes over.
+ *
+ * Six frames at 60fps, so on any normally painting document the frame still
+ * wins and emits stay paint-aligned. Chrome clamps timers in hidden tabs to
+ * ≥1s and can clamp harder under intensive throttling; that makes a hidden tab
+ * bounded-slow instead of blank, which is the point.
+ */
+export const DEFAULT_FRAME_DEADLINE_MS = 100;
+function pickFunction(override, ambient) {
+    if (typeof override === "function")
+        return override;
+    if (override === null)
+        return null;
+    return typeof ambient === "function" ? ambient : null;
+}
+export function createCompositionEmitScheduler(timing = {}) {
+    const frameDeadlineMs = timing.frameDeadlineMs ?? DEFAULT_FRAME_DEADLINE_MS;
+    let pending = false;
+    let pendingFlush = null;
+    let frameHandle = null;
+    let timerHandle = null;
+    // Kept from the arming call so a cancel is paired with the primitive that
+    // actually armed the handle.
+    let cancelFrame = null;
+    let clearTimer = null;
+    function release() {
+        pending = false;
+        if (frameHandle !== null) {
+            cancelFrame?.(frameHandle);
+            frameHandle = null;
+        }
+        if (timerHandle !== null) {
+            clearTimer?.(timerHandle);
+            timerHandle = null;
+        }
+        cancelFrame = null;
+        clearTimer = null;
+    }
+    /**
+     * Resolve one cycle. `firedFrom` names the side that arrived so its own
+     * handle is dropped rather than handed back to a cancel that has nothing
+     * left to cancel.
+     *
+     * The latch is released before the flush callback runs, so a re-entrant
+     * `schedule()` from inside the flush arms a fresh cycle instead of being
+     * swallowed. The pre-fix code cleared its latch first for the same reason.
+     */
+    function resolve(firedFrom) {
+        if (!pending)
+            return;
+        if (firedFrom === "frame")
+            frameHandle = null;
+        if (firedFrom === "timer")
+            timerHandle = null;
+        const flushNow = pendingFlush;
+        pendingFlush = null;
+        release();
+        flushNow?.();
+    }
+    function schedule(flush) {
+        pendingFlush = flush;
+        if (pending)
+            return;
+        pending = true;
+        const ambient = globalThis;
+        const requestFrame = pickFunction(timing.requestFrame, ambient.requestAnimationFrame);
+        cancelFrame = pickFunction(timing.cancelFrame, ambient.cancelAnimationFrame);
+        const setTimer = pickFunction(timing.setTimer, ambient.setTimeout);
+        clearTimer = pickFunction(timing.clearTimer, ambient.clearTimeout);
+        if (requestFrame) {
+            const handle = requestFrame(() => resolve("frame"));
+            // A primitive that calls back synchronously has already flushed and
+            // released; arming anything else would leave a stray handle behind.
+            if (!pending)
+                return;
+            frameHandle = handle;
+            // The frame is not trusted to arrive. Without a timer alongside it, a
+            // document that never paints leaves the latch set forever.
+            if (setTimer) {
+                const deadlineHandle = setTimer(() => resolve("timer"), frameDeadlineMs);
+                if (pending)
+                    timerHandle = deadlineHandle;
+            }
+            return;
+        }
+        // No frame primitive at all (SSR, non-DOM test environments). Preserve
+        // the microtask timing those hosts already had.
+        const queueMicrotaskFn = pickFunction(timing.queueMicrotaskFn, ambient.queueMicrotask);
+        if (queueMicrotaskFn) {
+            queueMicrotaskFn(() => resolve("microtask"));
+            return;
+        }
+        if (setTimer) {
+            const deadlineHandle = setTimer(() => resolve("timer"), 0);
+            if (pending)
+                timerHandle = deadlineHandle;
+            return;
+        }
+        // Nothing to defer with. A synchronous flush is strictly better than
+        // dropping the composition on the floor.
+        resolve("microtask");
+    }
+    function cancel() {
+        if (!pending)
+            return;
+        pendingFlush = null;
+        release();
+    }
+    return {
+        schedule,
+        cancel,
+        isPending: () => pending,
+    };
+}

package/dist/runtime/core/engine-resolver.d.ts

@@ -120,7 +120,7 @@ export declare function resolveRuntime(args: {
     createSectionController: unknown;
     isolation: string;
     env: Record<string, unknown>;
-    toolConfigStrictness: "off" | "error" | "warn";
+    toolConfigStrictness: "off" | "warn" | "error";
     onFrameworkError: FrameworkErrorHandler | undefined;
     onStageChange: StageChangeHandler | undefined;
     onLoadingComplete: LoadingCompleteHandler | undefined;

package/dist/services/ToolRegistry.d.ts

@@ -4,9 +4,11 @@
  * Central registry for all assessment tools. Manages tool metadata, visibility logic,
  * and button/instance creation. Supports dynamic registration and override by integrators.
  */
+import type { ItemEntity } from "@pie-players/pie-players-shared/types";
+import type { CatalogOwnerContext } 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";
@@ -14,7 +16,14 @@ export type ToolModuleLoader = () => Promise<unknown>;
 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 +157,135 @@ 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-media"` (the media region on an item
+ * or passage card) and `"section-overlay"` (the section-scoped singleton).
+ *
+ * `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;
+    catalogResolver: AccessibilityCatalogResolverApi | null;
+    /** Owner scope for catalog lookups, without `modelId`. */
+    ownerContext: CatalogOwnerContext;
+    /** The item in scope, when the host renders per item. */
+    item?: ItemEntity | null;
+}
+/**
+ * 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:
+ * `ownerContext` names an item model or a 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`, a function or a DOM node therefore compares equal
+     * to itself across a real change and the capability never hears about it; a
+     * cyclic value throws inside the host's own reconciliation.
+     */
+    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 +296,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 +331,14 @@ 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;
     /**
      * Optional provider registration metadata.
      * When present, ToolkitCoordinator can register provider(s) generically
@@ -196,12 +355,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
@@ -290,6 +468,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 +514,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 +556,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,30 @@ 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.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 +115,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.`);
     }
 }
@@ -251,6 +301,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 +360,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 +388,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,
         }));
     }
     /**
@@ -402,6 +487,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 +502,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 || {}),
+            },
+        });
+    }
 }

package/dist/services/ToolkitCoordinator.d.ts

@@ -29,7 +29,8 @@ import type { SREMathSpeechOptions } from "./tts/math-speech.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { TTSToolProviderConfig } from "./tool-providers/index.js";
-import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap, ToolRegistry } from "./ToolRegistry.js";
+import { ToolRegistry } from "./ToolRegistry.js";
+import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
 import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest } from "../policy/engine.js";
 import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
 export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";