@pie-players/pie-assessment-toolkit 0.3.67 → 0.3.69

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

@@ -0,0 +1,610 @@
+/**
+ * Headless host for capabilities that render into a renderer's surfaces.
+ *
+ * The interface deliberately exposes only current input, a two-boolean snapshot,
+ * and teardown. Discovery, policy/catalog invalidation, content resolution, lazy
+ * loading, DOM reconciliation, error isolation, and registry observation stay
+ * inside this module. Svelte callers are geometry adapters over this seam.
+ *
+ * It lives here rather than in `section-player`, where it was written, because a
+ * second renderer now opens a surface: the annotation toolbar hosts the
+ * capabilities that act on a text selection. Two copies of mount/reconcile/
+ * registry-observation would drift, and the drift would be invisible until one
+ * renderer stopped honouring the grant-AND-content rule. Nothing about the module
+ * was section-shaped — it already imported only from this package — so the move
+ * is a relocation, not a rewrite. The one thing that *was* section-shaped is the
+ * name it reported errors under, which is now {@link ToolSurfaceHostOptions.hostLabel}.
+ */
+import { isHostDeniedFeature } from "../policy/core/feature-decision.js";
+import { toFrameworkErrorModel } from "../services/framework-error.js";
+import { resolveContentCapabilities } from "./content-capability-resolution.js";
+const SECTION_POLICY_LEVELS = ["section", "item", "passage"];
+function stableSerializableJson(value) {
+    const seen = new Set();
+    function normalize(current, path) {
+        if (current === null ||
+            typeof current === "string" ||
+            typeof current === "boolean") {
+            return current;
+        }
+        if (typeof current === "number") {
+            return Number.isFinite(current) ? current : null;
+        }
+        if (typeof current === "undefined") {
+            return undefined;
+        }
+        if (typeof current === "function" || typeof current === "symbol") {
+            throw new TypeError(`${path} is not JSON-serializable`);
+        }
+        if (typeof current === "bigint") {
+            throw new TypeError(`${path} is not JSON-serializable`);
+        }
+        if (typeof current !== "object") {
+            throw new TypeError(`${path} is not JSON-serializable`);
+        }
+        if (seen.has(current)) {
+            throw new TypeError(`${path} contains a cycle`);
+        }
+        seen.add(current);
+        try {
+            if (Array.isArray(current)) {
+                return current.map((entry, index) => normalize(entry, `${path}[${index}]`) ?? null);
+            }
+            const prototype = Object.getPrototypeOf(current);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new TypeError(`${path} must contain only plain objects and arrays`);
+            }
+            const record = current;
+            const normalized = {};
+            for (const key of Object.keys(record).sort()) {
+                const entry = normalize(record[key], `${path}.${key}`);
+                if (entry !== undefined)
+                    normalized[key] = entry;
+            }
+            return normalized;
+        }
+        finally {
+            seen.delete(current);
+        }
+    }
+    const serialized = JSON.stringify(normalize(value, "content"));
+    if (serialized === undefined) {
+        throw new TypeError("content is not JSON-serializable");
+    }
+    return serialized;
+}
+function scopeEquals(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === "section" && right.kind === "section") {
+        return (left.assessmentId === right.assessmentId &&
+            left.sectionId === right.sectionId);
+    }
+    if (left.kind === "content" && right.kind === "content") {
+        const leftOwner = left.ownerContext;
+        const rightOwner = right.ownerContext;
+        return (leftOwner.ownerKind === rightOwner.ownerKind &&
+            leftOwner.assessmentId === rightOwner.assessmentId &&
+            leftOwner.sectionId === rightOwner.sectionId &&
+            leftOwner.canonicalItemId === rightOwner.canonicalItemId &&
+            leftOwner.itemId === rightOwner.itemId &&
+            leftOwner.passageId === rightOwner.passageId &&
+            leftOwner.modelId === rightOwner.modelId);
+    }
+    return false;
+}
+function inputEquals(left, right) {
+    return (left.anchor === right.anchor &&
+        left.surface === right.surface &&
+        left.registry === right.registry &&
+        left.services.toolkitCoordinator === right.services.toolkitCoordinator &&
+        left.services.ttsService === right.services.ttsService &&
+        left.services.catalogResolver === right.services.catalogResolver &&
+        scopeEquals(left.scope, right.scope));
+}
+function subscriptionInputsEqual(left, right) {
+    return (left.registry === right.registry &&
+        left.services.toolkitCoordinator === right.services.toolkitCoordinator &&
+        left.services.catalogResolver === right.services.catalogResolver &&
+        scopeEquals(left.scope, right.scope));
+}
+function contextSignature(context) {
+    try {
+        return stableSerializableJson({
+            toolId: context.toolId,
+            featureId: context.featureId,
+            surface: context.surface,
+            parameters: context.parameters ?? null,
+            content: context.content ?? null,
+        });
+    }
+    catch {
+        // Parameters are host/provider data and are not required to be serializable.
+        // Fall back to syncing them on each invalidation instead of rejecting the tool.
+        return null;
+    }
+}
+function sameContext(mountedEntry, nextEntry) {
+    if (mountedEntry.contextSignature === null ||
+        nextEntry.contextSignature === null ||
+        mountedEntry.contextSignature !== nextEntry.contextSignature) {
+        return false;
+    }
+    return (mountedEntry.context.services.toolkitCoordinator ===
+        nextEntry.context.services.toolkitCoordinator &&
+        mountedEntry.context.services.ttsService ===
+            nextEntry.context.services.ttsService &&
+        mountedEntry.context.services.catalogResolver ===
+            nextEntry.context.services.catalogResolver);
+}
+/** Create one lifecycle owner for one host surface anchor. */
+export function createToolSurfaceHost(onSnapshot, options) {
+    const { hostLabel } = options;
+    let input = null;
+    let destroyed = false;
+    let snapshot = { mountable: false, occupied: false };
+    let unsubscribeRegistry = null;
+    let unsubscribePolicy = null;
+    let unsubscribeCatalogs = null;
+    let catalogOwnerView = null;
+    const mounted = new Map();
+    const loadedRegistrations = new Map();
+    const pendingLoads = new Map();
+    const reportedWarnings = new Set();
+    function publish(next) {
+        if (next.mountable === snapshot.mountable &&
+            next.occupied === snapshot.occupied) {
+            return;
+        }
+        snapshot = next;
+        onSnapshot({ ...next });
+    }
+    function report(toolId, phase, message, cause) {
+        const current = input;
+        const key = `${current?.surface ?? "unknown"}\u0000${toolId}\u0000${phase}\u0000${message}`;
+        if (reportedWarnings.has(key))
+            return;
+        reportedWarnings.add(key);
+        const model = toFrameworkErrorModel({
+            kind: "tool-surface",
+            severity: "warning",
+            source: `${hostLabel}/tool-surface-host`,
+            message,
+            details: [
+                `surface=${current?.surface ?? "unknown"}`,
+                `toolId=${toolId}`,
+                `phase=${phase}`,
+            ],
+            recoverable: true,
+            cause,
+        });
+        const coordinator = current?.services.toolkitCoordinator;
+        if (typeof coordinator?.reportFrameworkError === "function") {
+            try {
+                coordinator.reportFrameworkError(model);
+                return;
+            }
+            catch (error) {
+                console.warn(`[${hostLabel}] tool surface warning reporter failed:`, error);
+            }
+        }
+        if (current?.anchor && typeof CustomEvent === "function") {
+            current.anchor.dispatchEvent(new CustomEvent("framework-error", {
+                detail: model,
+                bubbles: true,
+                composed: true,
+            }));
+            return;
+        }
+        console.warn(`[${hostLabel}] ${message}`, cause);
+    }
+    function unmount(toolId) {
+        const entry = mounted.get(toolId);
+        if (!entry)
+            return;
+        mounted.delete(toolId);
+        try {
+            entry.destroy?.();
+        }
+        catch (error) {
+            report(toolId, "destroy", `Tool "${toolId}" failed while leaving the "${input?.surface ?? "unknown"}" surface.`, error);
+        }
+        finally {
+            try {
+                entry.element.remove();
+            }
+            catch (error) {
+                // A custom element can override `remove`; use its parent as a fallback so
+                // one broken teardown hook cannot strand the node or abort reconciliation.
+                try {
+                    entry.element.parentNode?.removeChild(entry.element);
+                }
+                catch {
+                    // The warning below remains observable even if the DOM itself rejects
+                    // both removal paths.
+                }
+                report(toolId, "destroy", `Tool "${toolId}" failed DOM removal from the "${input?.surface ?? "unknown"}" surface.`, error);
+            }
+        }
+    }
+    function unmountAll() {
+        for (const toolId of [...mounted.keys()])
+            unmount(toolId);
+    }
+    function contentEligibility(current, registration, catalogs) {
+        if (current.scope.kind !== "content")
+            return null;
+        const coordinator = current.services.toolkitCoordinator;
+        const [resolved] = resolveContentCapabilities({
+            registrations: [registration],
+            catalogs,
+            // One decision per feature id, in the rule's three states. The scan across
+            // a capability's support ids, the gate-only probe of its tool id, and
+            // denial's precedence over both a grant and `resolvesWithoutGrant` live in
+            // the rule, so this host and print cannot answer differently. All this
+            // adapter owns is reading a `FeaturePolicyDecision`: `granted` is not
+            // enough on its own, because a host gate and an unconfigured feature are
+            // both `granted: false` and only one of them may be reopened by content.
+            policyFor: (featureId) => {
+                const decision = coordinator?.decideFeaturePolicy?.(featureId);
+                if (isHostDeniedFeature(decision))
+                    return { outcome: "denied" };
+                if (decision?.granted === true) {
+                    return {
+                        outcome: "granted",
+                        featureId,
+                        parameters: decision.parameters,
+                    };
+                }
+                return { outcome: "silent" };
+            },
+            onError: (failed, phase, error) => {
+                report(failed.toolId, "resolve", phase === "policy"
+                    ? `Tool "${failed.toolId}" failed policy resolution for the "${current.surface}" surface.`
+                    : `Tool "${failed.toolId}" failed authored-content resolution for the "${current.surface}" surface.`, error);
+            },
+        });
+        if (!resolved)
+            return null;
+        // Serializability is this host's requirement rather than the rule's: it
+        // re-resolves on every policy and catalog signal and compares the answer
+        // structurally, so content it cannot compare would report a change on every
+        // invalidation. Print resolves once and does not care.
+        if (resolved.content !== null) {
+            try {
+                stableSerializableJson(resolved.content);
+            }
+            catch (error) {
+                report(registration.toolId, "resolve", `Tool "${registration.toolId}" failed authored-content resolution for the "${current.surface}" surface.`, error);
+                return null;
+            }
+        }
+        const context = {
+            toolId: registration.toolId,
+            featureId: resolved.featureId,
+            surface: current.surface,
+            parameters: resolved.parameters,
+            content: resolved.content,
+            services: current.services,
+        };
+        return {
+            registration,
+            context,
+            contextSignature: contextSignature(context),
+        };
+    }
+    function sectionEligibility(current, registration) {
+        if (current.scope.kind !== "section")
+            return null;
+        if (registration.requiresAuthoredContent) {
+            report(registration.toolId, "resolve", `Tool "${registration.toolId}" declares authored content that the section-scoped "${current.surface}" surface cannot resolve.`);
+            return null;
+        }
+        const coordinator = current.services.toolkitCoordinator;
+        if (!coordinator)
+            return null;
+        const supportIds = registration.pnpSupportIds?.length
+            ? registration.pnpSupportIds
+            : [registration.toolId];
+        let featureId = "";
+        let parameters;
+        try {
+            if (registration.activation === "region") {
+                for (const supportId of supportIds) {
+                    const decision = coordinator.decideFeaturePolicy?.(supportId);
+                    if (decision?.granted !== true)
+                        continue;
+                    featureId = supportId;
+                    parameters = decision.parameters;
+                    break;
+                }
+                if (!featureId)
+                    return null;
+            }
+            else {
+                const scopeId = current.scope.sectionId || "*";
+                for (const level of SECTION_POLICY_LEVELS) {
+                    const decision = coordinator.decideToolPolicy({
+                        level,
+                        scope: {
+                            level,
+                            scopeId,
+                            assessmentId: current.scope.assessmentId,
+                            sectionId: current.scope.sectionId || undefined,
+                        },
+                    });
+                    const entry = decision.visibleTools.find((candidate) => candidate.toolId === registration.toolId);
+                    if (!entry)
+                        continue;
+                    featureId = supportIds[0] ?? registration.toolId;
+                    parameters = entry.settings;
+                    break;
+                }
+                if (!featureId)
+                    return null;
+            }
+        }
+        catch (error) {
+            report(registration.toolId, "resolve", `Tool "${registration.toolId}" failed policy resolution for the "${current.surface}" surface.`, error);
+            return null;
+        }
+        const context = {
+            toolId: registration.toolId,
+            featureId,
+            surface: current.surface,
+            parameters,
+            services: current.services,
+        };
+        return {
+            registration,
+            context,
+            contextSignature: contextSignature(context),
+        };
+    }
+    function resolveEligible(current) {
+        const registry = current.registry;
+        if (!registry || !current.surface)
+            return [];
+        let registrations;
+        try {
+            registrations = registry.getToolsBySurface(current.surface);
+        }
+        catch (error) {
+            report("registry", "resolve", `The tool registry failed discovery for the "${current.surface}" surface.`, error);
+            return [];
+        }
+        let catalogs = null;
+        if (current.scope.kind === "content" &&
+            catalogOwnerView &&
+            registrations.some((registration) => registration.requiresAuthoredContent)) {
+            try {
+                catalogs = catalogOwnerView.snapshot();
+            }
+            catch (error) {
+                report("catalog-owner", "resolve", `Catalog owner resolution failed for the "${current.surface}" surface; catalog-dependent capabilities were omitted.`, error);
+            }
+        }
+        return registrations.flatMap((registration) => {
+            const eligible = current.scope.kind === "content"
+                ? contentEligibility(current, registration, catalogs)
+                : sectionEligibility(current, registration);
+            return eligible ? [eligible] : [];
+        });
+    }
+    function ensureLoaded(current, entry) {
+        const registry = current.registry;
+        if (!registry)
+            return false;
+        const toolId = entry.registration.toolId;
+        if (loadedRegistrations.get(toolId) === entry.registration)
+            return true;
+        const existing = pendingLoads.get(toolId);
+        if (existing?.registry === registry &&
+            existing.registration === entry.registration) {
+            return false;
+        }
+        const promise = registry.ensureToolModuleLoaded(toolId);
+        const pending = { registry, registration: entry.registration };
+        pendingLoads.set(toolId, pending);
+        void promise
+            .then(() => {
+            if (pendingLoads.get(toolId) === pending)
+                pendingLoads.delete(toolId);
+            if (destroyed || input?.registry !== registry)
+                return;
+            if (registry.get(toolId) !== entry.registration)
+                return;
+            loadedRegistrations.set(toolId, entry.registration);
+            reconcile();
+        })
+            .catch((error) => {
+            if (pendingLoads.get(toolId) === pending)
+                pendingLoads.delete(toolId);
+            if (destroyed || input?.registry !== registry)
+                return;
+            if (registry.get(toolId) !== entry.registration)
+                return;
+            report(toolId, "load", `Tool "${toolId}" failed to load for the "${current.surface}" surface.`, error);
+        });
+        return false;
+    }
+    function mount(current, entry) {
+        const registry = current.registry;
+        const anchor = current.anchor;
+        if (!registry || !anchor)
+            return;
+        const toolId = entry.registration.toolId;
+        let rendered = null;
+        try {
+            rendered = registry.renderForSurface(toolId, entry.context);
+            if (!rendered?.element)
+                return;
+            if (rendered.ariaLabel) {
+                rendered.element.setAttribute("aria-label", rendered.ariaLabel);
+            }
+            anchor.appendChild(rendered.element);
+            mounted.set(toolId, {
+                registration: entry.registration,
+                element: rendered.element,
+                sync: rendered.sync,
+                destroy: rendered.destroy,
+                context: entry.context,
+                contextSignature: entry.contextSignature,
+            });
+        }
+        catch (error) {
+            if (rendered?.element.parentNode === anchor) {
+                try {
+                    anchor.removeChild(rendered.element);
+                }
+                catch {
+                    // Reporting the render failure is still preferable to escaping and
+                    // blocking the player when the capability returned an invalid node.
+                }
+            }
+            report(toolId, "render", `Tool "${toolId}" failed to render into the "${current.surface}" surface.`, error);
+            return;
+        }
+    }
+    function reconcile() {
+        if (destroyed || !input)
+            return;
+        const current = input;
+        const eligible = resolveEligible(current);
+        const wanted = new Map(eligible.map((entry) => [entry.registration.toolId, entry]));
+        for (const [toolId, mountedEntry] of [...mounted]) {
+            const next = wanted.get(toolId);
+            if (!current.anchor ||
+                !next ||
+                next.registration !== mountedEntry.registration) {
+                unmount(toolId);
+            }
+        }
+        if (current.anchor && current.registry) {
+            for (const entry of eligible) {
+                const toolId = entry.registration.toolId;
+                const existing = mounted.get(toolId);
+                if (existing) {
+                    if (sameContext(existing, entry))
+                        continue;
+                    try {
+                        existing.sync?.(entry.context);
+                        existing.context = entry.context;
+                        existing.contextSignature = entry.contextSignature;
+                    }
+                    catch (error) {
+                        report(toolId, "sync", `Tool "${toolId}" failed to synchronize in the "${current.surface}" surface.`, error);
+                    }
+                    continue;
+                }
+                if (ensureLoaded(current, entry))
+                    mount(current, entry);
+            }
+            // Re-appending existing nodes is identity-preserving and keeps registry
+            // order even when lazy modules resolve in a different order.
+            for (const entry of eligible) {
+                const mountedEntry = mounted.get(entry.registration.toolId);
+                if (!mountedEntry)
+                    continue;
+                try {
+                    current.anchor.appendChild(mountedEntry.element);
+                }
+                catch (error) {
+                    report(entry.registration.toolId, "sync", `Tool "${entry.registration.toolId}" failed DOM reconciliation in the "${current.surface}" surface.`, error);
+                }
+            }
+        }
+        publish({
+            mountable: eligible.length > 0,
+            occupied: Boolean(current.anchor && mounted.size > 0),
+        });
+    }
+    function invalidate() {
+        if (destroyed)
+            return;
+        reportedWarnings.clear();
+        reconcile();
+    }
+    function handleRegistryChange(event) {
+        if (event.kind === "module-loaders") {
+            for (const toolId of event.toolIds)
+                loadedRegistrations.delete(toolId);
+        }
+        if (event.kind === "component-overrides") {
+            unmountAll();
+        }
+        invalidate();
+    }
+    function detachSubscriptions() {
+        for (const unsubscribe of [
+            unsubscribeRegistry,
+            unsubscribePolicy,
+            unsubscribeCatalogs,
+        ]) {
+            try {
+                unsubscribe?.();
+            }
+            catch {
+                // The dependency may already have been disposed.
+            }
+        }
+        unsubscribeRegistry = null;
+        unsubscribePolicy = null;
+        unsubscribeCatalogs = null;
+        catalogOwnerView = null;
+    }
+    function bindSubscriptions(current) {
+        detachSubscriptions();
+        unsubscribeRegistry =
+            typeof current.registry?.onRegistryChange === "function"
+                ? current.registry.onRegistryChange(handleRegistryChange)
+                : null;
+        const coordinator = current.services.toolkitCoordinator;
+        if (coordinator) {
+            unsubscribePolicy =
+                typeof coordinator.onPolicyChange === "function"
+                    ? coordinator.onPolicyChange(invalidate)
+                    : null;
+        }
+        if (current.scope.kind === "content" && current.services.catalogResolver) {
+            catalogOwnerView = current.services.catalogResolver.forOwner(current.scope.ownerContext);
+            unsubscribeCatalogs = catalogOwnerView.onChange(invalidate);
+        }
+    }
+    return {
+        update(nextInput) {
+            if (destroyed)
+                return;
+            const previous = input;
+            let changed = true;
+            try {
+                changed = previous ? !inputEquals(previous, nextInput) : true;
+            }
+            catch {
+                // Owner contexts are expected to be plain serializable records. Treat an
+                // invalid one as changed so it cannot freeze the lifecycle.
+                changed = true;
+            }
+            const subscriptionsChanged = previous
+                ? !subscriptionInputsEqual(previous, nextInput)
+                : true;
+            input = nextInput;
+            if (subscriptionsChanged)
+                bindSubscriptions(nextInput);
+            if (!changed)
+                return;
+            reportedWarnings.clear();
+            reconcile();
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            detachSubscriptions();
+            unmountAll();
+            destroyed = true;
+            input = null;
+            pendingLoads.clear();
+            loadedRegistrations.clear();
+        },
+    };
+}

package/dist/tools/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool system type definitions
  */
-export type { CalculationHistoryEntry, Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorState, CalculatorType, DesmosCalculatorConfig, } from "@pie-players/pie-calculator";
+export type { CalculationHistoryEntry, Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorState, CalculatorType, } from "@pie-players/pie-calculator";
 export type ToolId = string;
 export interface ToolState {
     id: ToolId;
@@ -148,41 +148,6 @@ export interface ResolvedItemConfig {
 export interface ResolvedItemToolParameters extends ItemToolParameters {
     finalConfig: ToolConfig;
 }
-/**
- * Library configuration for external dependencies
- */
-export interface LibraryConfig {
-    id: string;
-    url: string;
-    fallbackUrls?: string[];
-    globalVar?: string;
-    dependencies?: string[];
-    integrity?: string;
-    crossorigin?: "anonymous" | "use-credentials";
-    timeout?: number;
-    async?: boolean;
-    defer?: boolean;
-    retry?: RetryConfig;
-}
-/**
- * Retry configuration for library loading
- */
-export interface RetryConfig {
-    maxAttempts: number;
-    delay: number;
-    backoffMultiplier?: number;
-}
-/**
- * Library loader statistics
- */
-export interface LoaderStats {
-    loaded: string[];
-    failed: string[];
-    pending: string[];
-    cacheHits: number;
-    cacheMisses: number;
-    totalLoadTime: number;
-}
 /**
  * Base interface that all tool components should implement
  */
@@ -274,36 +239,6 @@ export interface VariantResolver {
      */
     resolveVariant(itemConfig: ItemToolConfig, context: VariantContext): ResolvedItemConfig;
 }
-/**
- * Library Loader Service
- * Dynamically loads external libraries with retry and fallback support
- */
-export interface LibraryLoader {
-    /**
-     * Load a JavaScript library
-     */
-    loadScript(library: LibraryConfig): Promise<void>;
-    /**
-     * Load a stylesheet
-     */
-    loadStylesheet(url: string, targetRoot?: Document | ShadowRoot): Promise<void>;
-    /**
-     * Check if a library is already loaded
-     */
-    isLoaded(libraryId: string): boolean;
-    /**
-     * Preload multiple libraries in parallel
-     */
-    preload(libraries: LibraryConfig[]): Promise<void>;
-    /**
-     * Unload a library (remove script tag)
-     */
-    unload(libraryId: string): void;
-    /**
-     * Get loader statistics
-     */
-    getStats(): LoaderStats;
-}
 /**
  * PIE Response Component Interface
  * For tool-to-response integration (e.g., calculator inserting into text field)