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

package/dist/runtime/adapter/SectionEngineAdapter.js

@@ -1,61 +1,33 @@
 /**
- * Section runtime engine adapter (M7 — Variant C, layered).
+ * Section runtime engine adapter.
  *
  * The adapter is the single I/O seam between the pure FSM core
- * (`SectionEngineCore`) and the rest of the world (DOM, coordinator,
- * framework-error bus, host subscribers, instrumentation). It does
- * exactly two jobs:
+ * (`SectionEngineCore`) and the rest of the world (the DOM and host
+ * subscribers). It does exactly two jobs:
  *
- *   1. Translate **host inputs** (from kernels, the toolkit CE, or
- *      direct facade callers) into `SectionEngineInput`s and forward
- *      them to the core via `core.dispatch(input)`.
+ *   1. Forward host-constructed `SectionEngineInput`s to the core via
+ *      `core.dispatch(input)`.
  *
- *   2. Subscribe to the core's output stream and **route each output**
- *      through the bridges in a deterministic order so the public DOM
- *      surface, framework-error bus, instrumentation hook, and host
- *      subscribers all see exactly the same fan-out with
- *      byte-identical detail shapes.
+ *   2. Subscribe to the core's output stream and route each batch, in
+ *      order, to the DOM-event bridge (`pie-stage-change`,
+ *      `pie-loading-complete`) and then to the subscriber fan-out (one
+ *      batch per `core.dispatch`).
  *
- * Output routing is a single exhaustive `switch` (`assertNever` on
- * the default branch) so adding a new `SectionEngineOutput` kind in
- * `engine-output.ts` is a compile error here until the adapter knows
- * what to do with it.
+ * Output routing is a single exhaustive `switch`, so a new
+ * `SectionEngineOutput` kind is a compile error here until the adapter
+ * routes it.
  *
- * **Routing order per output:**
- *   - canonical DOM event (`pie-stage-change`, `pie-loading-complete`,
- *     `framework-error`)
- *   - framework-error bus (single fan-out for in-process subscribers)
- *   - instrumentation hook
- *   - public subscriber fan-out (batched, runs once per
- *     `core.dispatch`)
- *
- * The `readiness-change` / `interaction-ready` / `ready`
- * DOM events and their event bridge were removed in the
- * broad architecture review compat sweep; the corresponding output
- * kinds are gone from `engine-output.ts`.
- *
- * **Layering constraint.** The adapter is plain TS. It must not
- * import `svelte` — the M7 implementation plan and
- * `scripts/check-engine-core-purity.mjs` enforce the core's purity;
- * the adapter follows the same constraint by convention so it stays
- * usable from non-Svelte hosts (Node tests, Storybook, or future
- * non-Svelte consumers). `bun run check:custom-elements:dist`
- * already blocks `.svelte` imports in published `dist`; adding a
- * Svelte dependency here would also leak through that gate.
+ * **Layering constraint.** The adapter is plain TS and must not import
+ * `svelte`; `scripts/check-engine-core-purity.mjs` enforces it, so the
+ * adapter stays usable from non-Svelte hosts and Node tests.
  */
 import { SectionEngineCore } from "../core/SectionEngineCore.js";
-import { createCoordinatorBridge, } from "./coordinator-bridge.js";
 import { createDomEventBridge, } from "./dom-event-bridge.js";
-import { createFrameworkErrorBridge, } from "./framework-error-bridge.js";
-import { createInstrumentationBridge, } from "./instrumentation-bridge.js";
 import { createSubscriberFanout, } from "./subscriber-fanout.js";
 export class SectionEngineAdapter {
     core;
     domEventBridge;
-    frameworkErrorBridge;
-    instrumentationBridge;
     subscriberFanout;
-    coordinatorBridge;
     unsubscribeCore;
     disposed = false;
     constructor(options) {
@@ -66,19 +38,7 @@ export class SectionEngineAdapter {
             sourceCe: options.sourceCe,
             now: options.now,
         });
-        this.frameworkErrorBridge = createFrameworkErrorBridge({
-            bus: options.frameworkErrorBus,
-        });
-        this.instrumentationBridge = createInstrumentationBridge({
-            hook: options.instrumentationHook,
-        });
         this.subscriberFanout = createSubscriberFanout();
-        this.coordinatorBridge = options.coordinator
-            ? createCoordinatorBridge({
-                coordinator: options.coordinator,
-                dispatchCoreInput: (input) => this.dispatchInput(input),
-            })
-            : null;
         this.unsubscribeCore = this.core.subscribe((outputs) => {
             this.routeOutputs(outputs);
         });
@@ -114,35 +74,11 @@ export class SectionEngineAdapter {
         this.domEventBridge.setHost(host);
     }
     /**
-     * Update the instrumentation hook at runtime.
-     */
-    setInstrumentationHook(hook) {
-        this.instrumentationBridge.setHook(hook);
-    }
-    /**
-     * Resolve a section controller through the configured coordinator.
-     *
-     * Throws if the adapter was constructed without a coordinator.
-     * Standalone callers should manually feed
-     * `{ kind: "section-controller-resolved" }` after their own
-     * controller resolution path completes.
+     * Tear the adapter down. Safe to call more than once. Emits `disposed`
+     * for the active cohort, then detaches the core subscription and
+     * clears subscribers.
      */
-    resolveSectionController(args) {
-        if (!this.coordinatorBridge) {
-            throw new Error("[SectionEngineAdapter] resolveSectionController called without a coordinator.");
-        }
-        return this.coordinatorBridge.resolveSectionController(args);
-    }
-    /**
-     * Tear the adapter down. Safe to call more than once. Disposes the
-     * coordinator bridge (which in turn disposes the section
-     * controller for the current cohort), detaches the core
-     * subscription, and clears subscribers.
-     *
-     * Does **not** dispose the framework-error bus — its lifetime is
-     * owned by the toolkit CE / host.
-     */
-    async dispose() {
+    dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
@@ -151,9 +87,6 @@ export class SectionEngineAdapter {
         this.core.dispatch({ kind: "dispose" });
         this.unsubscribeCore();
         this.subscriberFanout.dispose();
-        if (this.coordinatorBridge) {
-            await this.coordinatorBridge.dispose();
-        }
     }
     routeOutputs(outputs) {
         for (const output of outputs) {
@@ -167,16 +100,10 @@ export class SectionEngineAdapter {
             case "loading-complete":
                 this.domEventBridge.dispatch(output);
                 break;
-            case "framework-error":
-                this.domEventBridge.dispatch(output);
-                this.frameworkErrorBridge.dispatch(output);
-                break;
             default: {
                 const exhaustive = output;
                 void exhaustive;
-                return;
             }
         }
-        this.instrumentationBridge.dispatch(output);
     }
 }

package/dist/runtime/adapter/dom-event-bridge.d.ts

@@ -1,36 +1,21 @@
 /**
- * DOM event bridge for the section runtime engine adapter (M7 — Variant
- * C, layered).
+ * DOM event bridge for the section runtime engine adapter.
  *
- * Translates canonical engine outputs (`stage-change`,
- * `loading-complete`, `framework-error`) into DOM `CustomEvent`
- * dispatches on the host element. Mirrors the kernel's existing
- * `dispatch("pie-stage-change", …)` / `dispatch("pie-loading-complete", …)`
- * / `dispatch("framework-error", …)` emit chain bit-for-bit so the M6
- * canonical event surface stays stable while the kernel migrates onto
- * the engine in PR 5.
+ * Translates engine outputs (`stage-change`, `loading-complete`) into
+ * `pie-stage-change` and `pie-loading-complete` on the host element. Both are
+ * dispatched with `CROSS_BOUNDARY_EVENT_INIT` (bubbling, composed), the init
+ * every other runtime event uses, so a listener above the layout element hears
+ * them as it hears `toolkit-ready` or `framework-error`.
  *
- * **Detail-shape contract.** The engine core emits structurally minimal
- * outputs (`{ stage, status, cohort }`, `{ cohort, itemCount,
- * loadedCount }`). The bridge enriches them with `runtimeId`,
- * `sourceCe`, and `timestamp` so the dispatched DOM event detail
- * matches the canonical
- * `packages/players-shared/src/pie/stages.ts#StageChangeDetail` and
- * `LoadingCompleteDetail` shapes verbatim. `runtimeId` and `sourceCe`
- * are supplied at adapter construction time (one per engine instance);
- * `timestamp` is captured per-emit via the injected `now()` clock so
- * tests can pin a deterministic value.
+ * **Detail-shape contract.** The core emits structurally minimal outputs
+ * (`{ stage, status, cohort }`, `{ cohort, itemCount }`). The bridge enriches
+ * them with `runtimeId`, `sourceCe` and `timestamp` so the dispatched detail
+ * matches `StageChangeDetail` and `LoadingCompleteDetail` in
+ * `packages/players-shared/src/pie/stages.ts`. `runtimeId` and `sourceCe` are
+ * fixed per engine; `timestamp` comes from the injected `now()` clock.
  *
- * **Why not import the stage tracker.** The tracker's monotonic /
- * skipped-fill enforcement now lives in the engine core's transition
- * function. The bridge is purely an output-to-DOM translator — it does
- * not gate emissions, does not re-order, does not de-duplicate. That
- * keeps the responsibility clean and matches the "outputs are already
- * ordered correctly by the core" contract from
- * `engine-transition.ts`.
- *
- * The bridge **must not** import `svelte`; per the M7 layering
- * constraint the adapter is plain TS.
+ * The bridge only translates: ordering and once-per-cohort gating belong to
+ * the transition function. It must not import `svelte`.
  */
 import type { SectionEngineOutput } from "../core/engine-output.js";
 export interface DomEventBridgeOptions {
@@ -41,7 +26,7 @@ export interface DomEventBridgeOptions {
     /**
      * Tag name of the host CE without the `--version-<encoded>` suffix.
      * Each layout CE that mounts the kernel passes its own canonical tag
-     * name; the toolkit CE passes its own.
+     * name.
      */
     sourceCe: string;
     /**

package/dist/runtime/adapter/dom-event-bridge.js

@@ -1,37 +1,23 @@
 /**
- * DOM event bridge for the section runtime engine adapter (M7 — Variant
- * C, layered).
+ * DOM event bridge for the section runtime engine adapter.
  *
- * Translates canonical engine outputs (`stage-change`,
- * `loading-complete`, `framework-error`) into DOM `CustomEvent`
- * dispatches on the host element. Mirrors the kernel's existing
- * `dispatch("pie-stage-change", …)` / `dispatch("pie-loading-complete", …)`
- * / `dispatch("framework-error", …)` emit chain bit-for-bit so the M6
- * canonical event surface stays stable while the kernel migrates onto
- * the engine in PR 5.
+ * Translates engine outputs (`stage-change`, `loading-complete`) into
+ * `pie-stage-change` and `pie-loading-complete` on the host element. Both are
+ * dispatched with `CROSS_BOUNDARY_EVENT_INIT` (bubbling, composed), the init
+ * every other runtime event uses, so a listener above the layout element hears
+ * them as it hears `toolkit-ready` or `framework-error`.
  *
- * **Detail-shape contract.** The engine core emits structurally minimal
- * outputs (`{ stage, status, cohort }`, `{ cohort, itemCount,
- * loadedCount }`). The bridge enriches them with `runtimeId`,
- * `sourceCe`, and `timestamp` so the dispatched DOM event detail
- * matches the canonical
- * `packages/players-shared/src/pie/stages.ts#StageChangeDetail` and
- * `LoadingCompleteDetail` shapes verbatim. `runtimeId` and `sourceCe`
- * are supplied at adapter construction time (one per engine instance);
- * `timestamp` is captured per-emit via the injected `now()` clock so
- * tests can pin a deterministic value.
+ * **Detail-shape contract.** The core emits structurally minimal outputs
+ * (`{ stage, status, cohort }`, `{ cohort, itemCount }`). The bridge enriches
+ * them with `runtimeId`, `sourceCe` and `timestamp` so the dispatched detail
+ * matches `StageChangeDetail` and `LoadingCompleteDetail` in
+ * `packages/players-shared/src/pie/stages.ts`. `runtimeId` and `sourceCe` are
+ * fixed per engine; `timestamp` comes from the injected `now()` clock.
  *
- * **Why not import the stage tracker.** The tracker's monotonic /
- * skipped-fill enforcement now lives in the engine core's transition
- * function. The bridge is purely an output-to-DOM translator — it does
- * not gate emissions, does not re-order, does not de-duplicate. That
- * keeps the responsibility clean and matches the "outputs are already
- * ordered correctly by the core" contract from
- * `engine-transition.ts`.
- *
- * The bridge **must not** import `svelte`; per the M7 layering
- * constraint the adapter is plain TS.
+ * The bridge only translates: ordering and once-per-cohort gating belong to
+ * the transition function. It must not import `svelte`.
  */
+import { dispatchCrossBoundaryEvent } from "../tool-host-contract.js";
 export function createDomEventBridge(options) {
     const { runtimeId, sourceCe } = options;
     let host = options.host;
@@ -46,7 +32,7 @@ export function createDomEventBridge(options) {
             timestamp: now(),
             sourceCe,
         };
-        host.dispatchEvent(new CustomEvent("pie-stage-change", { detail }));
+        dispatchCrossBoundaryEvent(host, "pie-stage-change", detail);
     }
     function dispatchLoadingComplete(output) {
         const detail = {
@@ -54,20 +40,10 @@ export function createDomEventBridge(options) {
             sectionId: output.cohort.sectionId,
             attemptId: output.cohort.attemptId ? output.cohort.attemptId : undefined,
             itemCount: output.itemCount,
-            loadedCount: output.loadedCount,
             timestamp: now(),
             sourceCe,
         };
-        host.dispatchEvent(new CustomEvent("pie-loading-complete", {
-            detail,
-        }));
-    }
-    function dispatchFrameworkError(output) {
-        // Mirror the kernel's existing surface — the `framework-error`
-        // DOM event detail is the framework-error model. The
-        // `framework-error-bridge` separately reports the same model
-        // into the bus so subscribers see one fan-out per error.
-        host.dispatchEvent(new CustomEvent("framework-error", { detail: output.error }));
+        dispatchCrossBoundaryEvent(host, "pie-loading-complete", detail);
     }
     function dispatch(output) {
         switch (output.kind) {
@@ -77,9 +53,6 @@ export function createDomEventBridge(options) {
             case "loading-complete":
                 dispatchLoadingComplete(output);
                 return;
-            case "framework-error":
-                dispatchFrameworkError(output);
-                return;
             default: {
                 const exhaustive = output;
                 void exhaustive;

package/dist/runtime/adapter/subscriber-fanout.d.ts

@@ -1,6 +1,5 @@
 /**
- * Subscriber fan-out for the section runtime engine adapter (M7 — Variant
- * C, layered).
+ * Subscriber fan-out for the section runtime engine adapter.
  *
  * The adapter exposes a single `subscribe(listener)` channel for hosts
  * that want a synchronous stream of `SectionEngineOutput[]` batches —

package/dist/runtime/adapter/subscriber-fanout.js

@@ -1,6 +1,5 @@
 /**
- * Subscriber fan-out for the section runtime engine adapter (M7 — Variant
- * C, layered).
+ * Subscriber fan-out for the section runtime engine adapter.
  *
  * The adapter exposes a single `subscribe(listener)` channel for hosts
  * that want a synchronous stream of `SectionEngineOutput[]` batches —

package/dist/runtime/catalog-context.d.ts

@@ -0,0 +1,19 @@
+import { type AssessmentToolkitShellContext } from "../context/assessment-toolkit-context.js";
+import type { CatalogLookupContext } from "../services/AccessibilityCatalogResolver.js";
+/** Where a shell's owner registered its catalogs, from the toolkit runtime context. */
+export interface CatalogRuntimeScope {
+    assessmentId?: string;
+    sectionId?: string;
+}
+/**
+ * The catalog lookup context for content in `shell`: the cards its owner
+ * registered, then the assessment's.
+ */
+export declare const catalogContextForShell: (shell: AssessmentToolkitShellContext, runtime?: CatalogRuntimeScope | null) => CatalogLookupContext;
+/**
+ * The catalog lookup context for the shell scope holding `node`, asked of that
+ * shell's context provider at the time of the call, or undefined outside every
+ * shell scope. For a tool that serves several shells and so has no shell
+ * context of its own, such as the section-wide annotation toolbar.
+ */
+export declare const catalogContextHolding: (node: Node, runtime?: CatalogRuntimeScope | null) => CatalogLookupContext | undefined;

package/dist/runtime/catalog-context.js

@@ -0,0 +1,28 @@
+import { requestContext } from "@pie-players/pie-context";
+import { assessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
+import { catalogOwnerContextFor } from "../services/catalog-owner.js";
+import { composedParentElement } from "../services/tts/flat-tree.js";
+/**
+ * The catalog lookup context for content in `shell`: the cards its owner
+ * registered, then the assessment's.
+ */
+export const catalogContextForShell = (shell, runtime) => catalogOwnerContextFor({
+    kind: shell.kind,
+    assessmentId: runtime?.assessmentId,
+    sectionId: runtime?.sectionId,
+    itemId: shell.itemId,
+    canonicalItemId: shell.canonicalItemId || shell.itemId,
+});
+/**
+ * The catalog lookup context for the shell scope holding `node`, asked of that
+ * shell's context provider at the time of the call, or undefined outside every
+ * shell scope. For a tool that serves several shells and so has no shell
+ * context of its own, such as the section-wide annotation toolbar.
+ */
+export const catalogContextHolding = (node, runtime) => {
+    const element = node.nodeType === 1 ? node : composedParentElement(node);
+    const shell = element
+        ? requestContext(element, assessmentToolkitShellContext)
+        : undefined;
+    return shell ? catalogContextForShell(shell, runtime) : undefined;
+};

package/dist/runtime/composition-emit-scheduler.d.ts

@@ -1,23 +1,18 @@
 /**
- * Composition emit scheduler (PIE-885).
+ * Composition emit scheduler.
  *
  * `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
+ * The latch is released by a `requestAnimationFrame` callback raced against a
+ * deadline timer, because the existence of `window.requestAnimationFrame` does
+ * not mean it fires: in a document with no compositor (headless browsers,
+ * hidden or offscreen tabs, CI and agent harnesses) the callback never runs, so
+ * a frame-only latch would never clear and the player would keep its initial
+ * empty composition while the section controller held a correct view model. A
+ * background tab's pending frame only becomes due on refocus. 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.
@@ -34,8 +29,7 @@
  *
  * 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`.
+ * a unit test without mounting the toolkit CE.
  */
 /**
  * How long to wait for a frame before the timer takes over.

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

@@ -1,23 +1,18 @@
 /**
- * Composition emit scheduler (PIE-885).
+ * Composition emit scheduler.
  *
  * `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
+ * The latch is released by a `requestAnimationFrame` callback raced against a
+ * deadline timer, because the existence of `window.requestAnimationFrame` does
+ * not mean it fires: in a document with no compositor (headless browsers,
+ * hidden or offscreen tabs, CI and agent harnesses) the callback never runs, so
+ * a frame-only latch would never clear and the player would keep its initial
+ * empty composition while the section controller held a correct view model. A
+ * background tab's pending frame only becomes due on refocus. 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.
@@ -34,8 +29,7 @@
  *
  * 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`.
+ * a unit test without mounting the toolkit CE.
  */
 /**
  * How long to wait for a frame before the timer takes over.

package/dist/runtime/content-language.d.ts

@@ -0,0 +1,32 @@
+/** The content language when neither the markup nor the host names one. */
+export declare const DEFAULT_CONTENT_LANGUAGE = "en-US";
+/**
+ * The nearest non-empty `lang` attribute at or above `node`, climbing through
+ * shadow hosts, and ending after `boundary` when one is given.
+ */
+export declare const findLangAttribute: (node: Node | null | undefined, boundary?: Element | null) => string | undefined;
+export interface ContentLanguageOptions {
+    /**
+     * Where the `lang` climb ends, inclusive. Defaults to the nearest shell scope
+     * host above the target; with neither, markup names no language.
+     */
+    boundary?: Element | null;
+    /** The host's `content-language` input. */
+    contentLanguage?: string | null;
+}
+/**
+ * The language the content at `target` is named as being in: the nearest `lang`
+ * between it and its shell scope host, else the host's `content-language` input.
+ * Undefined when neither names one.
+ *
+ * The climb stops at the shell because the page's own `lang` above it is the
+ * interface language, which the toolkit's `locale` carries; content language is
+ * the content's. Resolved at speak time, since a reading target's markup can
+ * change between reads.
+ */
+export declare const findContentLanguage: (target: Node | null | undefined, options?: ContentLanguageOptions) => string | undefined;
+/**
+ * {@link findContentLanguage}, else `en-US`: the language text processing and
+ * catalog lookup read.
+ */
+export declare const resolveContentLanguage: (target: Node | null | undefined, options?: ContentLanguageOptions) => string;

package/dist/runtime/content-language.js

@@ -0,0 +1,46 @@
+import { composedParentElement } from "../services/tts/flat-tree.js";
+import { findShellScopeHost } from "./content-region.js";
+/** The content language when neither the markup nor the host names one. */
+export const DEFAULT_CONTENT_LANGUAGE = "en-US";
+/**
+ * The nearest non-empty `lang` attribute at or above `node`, climbing through
+ * shadow hosts, and ending after `boundary` when one is given.
+ */
+export const findLangAttribute = (node, boundary) => {
+    let current = !node
+        ? null
+        : node.nodeType === 1
+            ? node
+            : composedParentElement(node);
+    while (current) {
+        const lang = current.getAttribute("lang")?.trim();
+        if (lang)
+            return lang;
+        if (boundary && current === boundary)
+            return undefined;
+        current = composedParentElement(current);
+    }
+    return undefined;
+};
+/**
+ * The language the content at `target` is named as being in: the nearest `lang`
+ * between it and its shell scope host, else the host's `content-language` input.
+ * Undefined when neither names one.
+ *
+ * The climb stops at the shell because the page's own `lang` above it is the
+ * interface language, which the toolkit's `locale` carries; content language is
+ * the content's. Resolved at speak time, since a reading target's markup can
+ * change between reads.
+ */
+export const findContentLanguage = (target, options = {}) => {
+    const boundary = options.boundary !== undefined
+        ? options.boundary
+        : findShellScopeHost(target);
+    const fromMarkup = boundary ? findLangAttribute(target, boundary) : undefined;
+    return fromMarkup || options.contentLanguage?.trim() || undefined;
+};
+/**
+ * {@link findContentLanguage}, else `en-US`: the language text processing and
+ * catalog lookup read.
+ */
+export const resolveContentLanguage = (target, options = {}) => findContentLanguage(target, options) ?? DEFAULT_CONTENT_LANGUAGE;

package/dist/runtime/content-region.d.ts

@@ -0,0 +1,17 @@
+/** Marks the part of a shell scope that holds the content tools read and annotate. */
+export declare const CONTENT_REGION_SELECTOR = "[data-region='content']";
+/** Marks the host of a shell scope (`<pie-item-scope>`, `<pie-passage-shell>`). */
+export declare const SHELL_SCOPE_HOST_SELECTOR = "[data-pie-shell-root]";
+/**
+ * The content region of `scope` that tools read and annotate.
+ *
+ * With `target`, the region holding it: the nearest `data-region="content"`
+ * element from `target` up to `scope`, climbing through shadow hosts. Otherwise,
+ * or when `target` lies in none, `scope` itself when it is a content region,
+ * else its first content region, else `scope`, so a scope that marks no region
+ * is read whole. Resolved at each use, because a card renders its regions after
+ * its tools connect.
+ */
+export declare const resolveContentRegion: (scope: Element, target?: Node | null) => Element;
+/** The nearest shell scope host at or above `node`, climbing through shadow hosts. */
+export declare const findShellScopeHost: (node: Node | null | undefined) => Element | null;

package/dist/runtime/content-region.js

@@ -0,0 +1,29 @@
+import { composedClosest, flatQuerySelector, } from "../services/tts/flat-tree.js";
+/** Marks the part of a shell scope that holds the content tools read and annotate. */
+export const CONTENT_REGION_SELECTOR = "[data-region='content']";
+/** Marks the host of a shell scope (`<pie-item-scope>`, `<pie-passage-shell>`). */
+export const SHELL_SCOPE_HOST_SELECTOR = "[data-pie-shell-root]";
+/**
+ * The content region of `scope` that tools read and annotate.
+ *
+ * With `target`, the region holding it: the nearest `data-region="content"`
+ * element from `target` up to `scope`, climbing through shadow hosts. Otherwise,
+ * or when `target` lies in none, `scope` itself when it is a content region,
+ * else its first content region, else `scope`, so a scope that marks no region
+ * is read whole. Resolved at each use, because a card renders its regions after
+ * its tools connect.
+ */
+export const resolveContentRegion = (scope, target) => {
+    if (target) {
+        const holding = composedClosest(target, CONTENT_REGION_SELECTOR, scope);
+        if (holding)
+            return holding;
+    }
+    if (scope.matches?.(CONTENT_REGION_SELECTOR))
+        return scope;
+    return (scope.querySelector?.(CONTENT_REGION_SELECTOR) ??
+        flatQuerySelector(scope, CONTENT_REGION_SELECTOR) ??
+        scope);
+};
+/** The nearest shell scope host at or above `node`, climbing through shadow hosts. */
+export const findShellScopeHost = (node) => node ? composedClosest(node, SHELL_SCOPE_HOST_SELECTOR) : null;

package/dist/runtime/content-registration.d.ts

@@ -0,0 +1,13 @@
+import type { ToolkitCoordinatorApi } from "../services/interfaces.js";
+import type { RuntimeRegistrationDetail } from "./registration-events.js";
+/**
+ * What a content registration files with the coordinator: the content's
+ * accessibility catalogs, and an item's policy settings under its canonical
+ * id, the id its item-level toolbar scopes decisions by. Returns the cleanups
+ * that withdraw them, for the toolkit to run when the content unregisters or
+ * the coordinator changes.
+ */
+export declare function registerContentWithCoordinator(coordinator: Pick<ToolkitCoordinatorApi, "catalogResolver" | "registerItemSettings">, detail: RuntimeRegistrationDetail, owner: {
+    assessmentId: string;
+    sectionId: string;
+}): Array<() => void>;

package/dist/runtime/content-registration.js

@@ -0,0 +1,25 @@
+/**
+ * What a content registration files with the coordinator: the content's
+ * accessibility catalogs, and an item's policy settings under its canonical
+ * id, the id its item-level toolbar scopes decisions by. Returns the cleanups
+ * that withdraw them, for the toolkit to run when the content unregisters or
+ * the coordinator changes.
+ */
+export function registerContentWithCoordinator(coordinator, detail, owner) {
+    const cleanups = [
+        coordinator.catalogResolver.registerOwner({
+            owner: {
+                kind: detail.kind,
+                itemId: detail.itemId,
+                canonicalItemId: detail.canonicalItemId,
+                assessmentId: owner.assessmentId,
+                sectionId: owner.sectionId,
+            },
+            entity: detail.item,
+        }),
+    ];
+    if (detail.kind === "item" && detail.settings) {
+        cleanups.push(coordinator.registerItemSettings(detail.canonicalItemId || detail.itemId, detail.settings));
+    }
+    return cleanups;
+}