@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.0

package/README.md

@@ -1,8 +1,36 @@
 # PIE Assessment Toolkit
 
-**Independent, composable services** for coordinating tools, accommodations, and item players in assessment applications.
-
-This is not an opinionated framework or monolithic "player" - it's a toolkit that solves specific problems through centralized service management.
+The assessment toolkit coordinates the services around PIE item players: tool
+policy and placement, tool providers, accommodations, text-to-speech (TTS),
+highlighting and per-element tool state. It ships the `ToolkitCoordinator`, the
+services it owns and the `<pie-assessment-toolkit>` custom element. This README
+is for host integrators wiring the toolkit into a section player, an item player
+or their own shell, and for contributors working on toolkit core. The
+[tools and accommodations architecture](../../docs/tools-and-accomodations/architecture.md)
+sets out the design, and [Configuring Tools](../../docs/tools-and-accomodations/tool_provider_system.md)
+is the configuration guide.
+
+## Contents
+
+- [Install](#install)
+- [Capabilities](#capabilities)
+- [Architecture overview](#architecture-overview)
+- [Configuration: attributes and a constructed coordinator](#configuration-attributes-and-a-constructed-coordinator)
+- [Quick Start](#quick-start)
+- [Tool Configuration Model](#tool-configuration-model)
+- [Test Attempt Session](#test-attempt-session)
+- [ToolkitCoordinator API](#toolkitcoordinator-api)
+- [ElementToolStateStore API](#elementtoolstatestore-api)
+- [Service APIs](#service-apis)
+- [Integration with Section Player](#integration-with-section-player)
+- [Instrumentation and Observability](#instrumentation-and-observability)
+- [Section Runtime Engine (advanced)](#section-runtime-engine-advanced)
+- [Writing a capability package](#writing-a-capability-package)
+- [State separation](#state-separation)
+- [Examples](#examples)
+- [TypeScript Support](#typescript-support)
+- [Content trust boundary](#content-trust-boundary)
+- [Related Documentation](#related-documentation)
 
 ## Install
 
@@ -21,133 +49,36 @@ Server-backed TTS (`backend: "server"`) loads
 first use. If it fails to load, TTS initialization reports a `provider-init`
 framework error and falls back to browser speech.
 
-A `ToolkitCoordinator` registers tool providers only from its `toolRegistry`.
-Built without one, it adopts the registry of the toolkit it is bound to, such as
-the section player's, which then validates its config and registers its
-providers. A registry passed at construction is never replaced. Bound to a
-toolkit that has none, it registers no providers, skips tool-id and placement
-validation, and warns once (`tools.registryUnavailable`).
-
-## What's New: ToolkitCoordinator
-
-✨ **Centralized Service Management**: The new `ToolkitCoordinator` provides a single entry point for all toolkit services, simplifying initialization and configuration.
-
-**Before** (scattered services):
-```typescript
-// Create 5+ services independently
-const ttsService = new TTSService();
-const toolCoordinator = new ToolCoordinator();
-const highlightCoordinator = new HighlightCoordinator();
-const catalogResolver = new AccessibilityCatalogResolver([...]);
-// Missing: ElementToolStateStore
-
-await ttsService.initialize(new BrowserTTSProvider());
-ttsService.setCatalogResolver(catalogResolver);
-
-// Pass all services separately
-player.ttsService = ttsService;
-player.toolCoordinator = toolCoordinator;
-// ...
-```
-
-**After** (coordinator orchestrates):
-```typescript
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from '@pie-players/pie-default-tool-loaders';
-
-// Create one coordinator with configuration
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
-const toolkitCoordinator = new ToolkitCoordinator({
-  assessmentId: 'my-assessment',
-  toolRegistry,
-  tools: {
-    providers: {
-      textToSpeech: { enabled: true, backend: 'browser' },
-      // Desmos needs an application key; see "Simple Default" below.
-      calculator: { enabled: true }
-    },
-    placement: {
-      section: ['graph', 'periodicTable', 'protractor', 'lineReader', 'ruler'],
-      item: ['calculator', 'textToSpeech', 'answerEliminator'],
-      passage: ['textToSpeech']
-    }
-  }
-});
-
-// Pass single coordinator to section-player through runtime
-player.runtime = { ...(player.runtime ?? {}), coordinator: toolkitCoordinator };
-```
-
-## What Does It Solve?
-
-- **Centralized service management**: One coordinator owns all toolkit services
-- **Tool coordination**: z-index management, visibility state, element-level state
-- **Accommodation support**: IEP/504 tool configuration logic
-- **TTS + annotation coordination**: Prevent conflicts between highlights
-- **Event communication**: Standard contracts between components
-- **Accessibility theming**: Consistent high-contrast, font sizing
-- **State separation**: Ephemeral tool state separate from persistent session data
-
-## Instrumentation and Observability
-
-Toolkit instrumentation is provider-agnostic and additive. It uses the shared
-`InstrumentationProvider` contract from `@pie-players/pie-players-shared`.
-
-### Injection Path
-
-When toolkit is hosted by section/assessment player flows, the canonical
-provider path is the item-player loader config:
-
-- `runtime.player.loaderConfig.instrumentationProvider`
-
-### Semantics
-
-- With `trackPageActions: true`, missing/`undefined` providers use the default New Relic provider path.
-- `instrumentationProvider: null` explicitly disables instrumentation.
-- Invalid provider objects are ignored (optional debug warning), also no-op.
-- Existing `item-player` behavior remains the compatibility anchor.
-- Debug overlays can consume the same stream by composing providers with
-  `CompositeInstrumentationProvider` (for example New Relic + debug panel).
-- Toolkit telemetry forwarding uses the same provider path, so tool/backend
-  instrumentation is sent to production providers and is visible in debug panel
-  overlays.
-
-### Toolkit-Owned Canonical Event Stream
-
-- `pie-toolkit-runtime-owned`
-- `pie-toolkit-runtime-inherited`
-- `pie-toolkit-runtime-ready`
-- `pie-toolkit-ready`
-- `pie-toolkit-section-ready`
-- `pie-toolkit-framework-error`
-
-Toolkit tool/backend operational stream:
-
-- `pie-tool-init-start|success|error`
-- `pie-tool-backend-call-start|success|error`
-- `pie-tool-library-load-start|success|error`
+## Capabilities
 
-Ownership boundary: toolkit emits toolkit lifecycle semantics only. Section and
-assessment semantic streams stay in their own layers to avoid overlap. Bridge
-dedupe is a safety net, not a substitute for clear ownership.
+- **Centralized service management**: one coordinator owns the toolkit services
+  and hands them to the players
+- **Tool coordination**: z-index management, visibility state and per-element
+  tool state
+- **Accommodation support**: tool policy driven by the student's personal needs
+  profile (PNP), including tools an IEP (Individualized Education Program) or
+  Section 504 plan requires
+- **TTS and annotation coordination**: TTS reading highlights and student
+  annotations share one highlight layer without conflict
+- **Event communication**: typed events between players, toolkit and tools
+- **Accessibility theming**: high-contrast color schemes through the
+  color-scheme tool (`theme`)
+- **State separation**: tool state kept apart from PIE session data
 
-## Architecture Overview
+## Architecture overview
 
-See the [ToolkitCoordinator section in the architecture overview](../../docs/architecture/architecture.md#toolkitcoordinator-centralized-service-management) for the current design documentation.
+The [Assessment toolkit section of the architecture overview](../../docs/architecture/architecture.md#assessment-toolkit)
+places the toolkit among the players.
 
 ### Core Principles
 
-1. **Centralized Coordination**: ToolkitCoordinator orchestrates all services
+1. **Centralized Coordination**: ToolkitCoordinator owns the services, and players reach them through it
 2. **Composable Services**: Import only what you need (or use coordinator for convenience)
 3. **No Framework Lock-in**: Works with any JavaScript framework
-4. **Product Control**: Products control navigation, layout and backend. Session persistence defaults to `localStorage` at the section and assessment layers, stored per attempt id and inactive without one, and a product replaces either through its persistence hook (`createSectionSessionPersistence` on the coordinator, `createAssessmentSessionPersistence` on the assessment player)
+4. **Product Control**: Products control navigation, layout and backend. Session persistence defaults to `localStorage` at the section and assessment layers, stored per attempt id and inactive without one, and a product replaces either through its persistence hook (`hooks.createSectionSessionPersistence` on the coordinator, `createAssessmentSessionPersistence` on the assessment player)
 5. **Standard Contracts**: Well-defined event types for component communication
-6. **Element-Level Granularity**: Tool state tracked per PIE element, not per item
-7. **State Separation**: Tool state (ephemeral) separate from PIE session data (persistent)
+6. **Element-Level Granularity**: Tool state is tracked per PIE element
+7. **State Separation**: Tool state is stored apart from PIE session data and never scored
 
 ## Configuration: attributes and a constructed coordinator
 
@@ -170,20 +101,16 @@ than the element inputs builds the coordinator itself.
   ```
 
 - **A constructed `ToolkitCoordinator` (or a
-  `runtime` object on consumer CEs).** Use this for advanced cases: composed
+  `runtime` object on the player custom elements).** Use this for advanced cases: composed
   configuration, dynamic overrides, runtime mutation, fields without an
   attribute, or anything that benefits from being a single typed
   object passed by reference. Example:
 
   ```ts
-  import {
-    createPackagedToolRegistry,
-    DEFAULT_TOOL_MODULE_LOADERS,
-  } from "@pie-players/pie-default-tool-loaders";
+  import { ToolkitCoordinator } from "@pie-players/pie-assessment-toolkit";
+  import { createPackagedToolRegistry } from "@pie-players/pie-default-tool-loaders";
 
-  const toolRegistry = createPackagedToolRegistry({
-    toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-  });
+  const toolRegistry = createPackagedToolRegistry();
   const coordinator = new ToolkitCoordinator({
     assessmentId: "my-assessment",
     toolRegistry,
@@ -211,33 +138,36 @@ callbacks; attributes carry section identity, layout controls, `nds-icons`,
 `locale` and `tool-config-strictness`. Unset inputs take their documented
 defaults.
 
-`<pie-assessment-toolkit>` takes the same fields as its own properties,
-with `assessment-id`, `nds-icons`, `locale` and `tool-config-strictness` as
-attributes, and reads `pnpEnforcement` from `tools.pnpEnforcement`.
+`<pie-assessment-toolkit>` takes the same fields as its own properties. Its
+string and boolean attributes are `assessment-id`, `section-id`, `attempt-id`,
+`nds-icons`, `locale`, `content-language`, `lazy-init`,
+`tool-config-strictness`, `enabled-tools`, `player-type` and `isolation`;
+`section`, `env`, `tools` and `player` also accept JSON attributes. It reads
+`pnpEnforcement` from `tools.pnpEnforcement`.
 
 ### Canonical attribute set
 
 - Identity: `assessment-id` on the toolkit, `section-id`, `attempt-id`
-- Runtime config on section-player CEs: `runtime`
-- Toolkit-only object properties: `tools`, `tool-registry`, `coordinator`,
+- Runtime config on section-player custom elements: `runtime`
+- Toolkit-only object properties: `tools`, `toolRegistry`, `coordinator`,
   `accessibility`
 - Interface: `nds-icons`, `locale`
-- Diagnostics: `tool-config-strictness`, `debug`. Framework-error
+- Diagnostics: `tool-config-strictness`, and `debug` on the section-player layouts. Framework-error
   delivery is via the `onFrameworkError` callback (a toolkit property,
   `runtime.onFrameworkError` on a section player) and the
-  `framework-error` DOM event dispatched on the layout CE host.
+  `framework-error` DOM event dispatched on the layout element.
 
 Inputs outside the runtime config:
 
 - Identity (`section-id`, `attempt-id`, `section`): per-attempt host
   state, not configuration.
-- Layout-only shell knobs on the section-player layout CEs
+- Layout-only shell knobs on the section-player layout elements
   (`show-toolbar`, `toolbar-position`, `narrow-layout-breakpoint`,
-  `split-pane-collapse-strategy`): layout-CE rendering concerns.
+  `split-pane-collapse-strategy`): rendering concerns of the layout element.
 - Per-region toolbar tool placement: hosts populate
   `tools.placement.item` / `tools.placement.passage` (object form) or
   `runtime.tools.placement.{item,passage}` directly.
-- Runtime-only keys on the section-player layout CEs
+- Runtime-only keys on the section-player layout elements
   (`createSectionController`, `isolation`): accepted only via
   `runtime.<key>`. Section-player layouts forward both to the wrapped
   toolkit as properties. `<pie-assessment-toolkit>` keeps
@@ -245,42 +175,46 @@ Inputs outside the runtime config:
   attribute or a property. A `coordinator` passed to it wins over an
   outer toolkit's.
 
-### When to add an attribute
+### Adding an attribute (contributors)
 
-Add an attribute only if all of the following hold:
+A new input becomes an attribute only if all of the following hold:
 
 - It is a common case that hosts set without composing a `ToolkitCoordinator`
   / `runtime` object.
 - Its value is a primitive or small typed object that round-trips through
   HTML attributes (string, boolean-like, number; structured data passes via
   property assignment).
-- It exists on every CE that conceptually owns the same knob, or has a
+- It exists on every custom element that owns the same knob, or has a
   deliberate documented exclusion.
 
 Otherwise expose it through the configuration object only.
 
 ## Quick Start
 
+Three defaults decide whether tools show up at all:
+
+- Placement is empty by default. A tool appears only at the levels
+  `tools.placement` names, and a profile grant does not place a tool.
+- The section player renders its section toolbar only when `show-toolbar` is
+  `true`; the attribute defaults to `false`.
+- The default calculator, Desmos, needs an API key
+  ([Calculator providers](#calculator-providers)).
+
 ### Option 1: Use ToolkitCoordinator (Recommended)
 
 ```typescript
 import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from '@pie-players/pie-default-tool-loaders';
+import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
 // Create coordinator with configuration
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
+const toolRegistry = createPackagedToolRegistry();
 const coordinator = new ToolkitCoordinator({
   assessmentId: 'demo-assessment',
   toolRegistry,
   tools: {
     providers: {
       textToSpeech: { enabled: true, backend: 'browser' },
-      // Desmos needs an application key; see "Simple Default" below.
+      // Desmos needs an API key; see "Calculator providers" below.
       calculator: { enabled: true }
     },
     placement: {
@@ -306,7 +240,7 @@ const toolState = coordinator.elementToolStateStore.getAllState();
 
 ### Controller Event Subscriptions (Helper First)
 
-For host-side session/progress logic, prefer helper subscriptions over the generic filter API. Subscriptions follow the toolkit's *active section cohort* automatically — a single `subscribe*` call survives navigation between sections without re-wiring:
+For host-side session and progress logic, the helper subscriptions below are simpler than the generic filter API. A cohort is the `(sectionId, attemptId)` pair a section controller serves. Subscriptions follow the toolkit's active cohort, so a single `subscribe*` call survives navigation between sections without re-wiring:
 
 ```typescript
 const unsubscribeItem = coordinator.subscribeItemEvents({
@@ -327,7 +261,7 @@ unsubscribeItem?.();
 unsubscribeSection?.();
 ```
 
-Behavior pins (PIE-512 Phase D):
+Subscription behavior:
 
 - Subscribe **after** the first `getOrCreateSectionController(...)` resolves; calling subscribe before any cohort exists throws.
 - On every cohort transition (navigation, fresh `getOrCreateSectionController` for a new section), the listener is automatically migrated to the new controller and receives a snapshot replay (`content-loaded` × N then `section-loading-complete`) in the same order a fresh subscriber would have seen.
@@ -339,85 +273,12 @@ Use `subscribeSectionEvents(...)` when you need advanced/custom filtering mixes.
 
 To persist or snapshot an inactive section, use `coordinator.getSectionController({ sectionId, attemptId })` — that lookup is by id and is unaffected by the active-cohort behavior described above.
 
-#### Migrating from `<0.3.35` (BREAKING — pre-1.0)
-
-`0.3.35` is the first release where `subscribeSectionEvents` (and its two helper wrappers `subscribeItemEvents` / `subscribeSectionLifecycleEvents`) follows the toolkit's *active section cohort* automatically. The on-the-wire shape of the subscription args object changed.
-
-If your host code looked like this:
-
-```typescript
-const unsub = coordinator.subscribeItemEvents({
-  sectionId: 'section-1',
-  attemptId: 'attempt-1',
-  listener: handleEvent,
-});
-```
-
-Update it to drop `sectionId` / `attemptId`:
-
-```typescript
-const unsub = coordinator.subscribeItemEvents({
-  listener: handleEvent,
-});
-```
-
-What this means in practice for typed integrations:
-
-- **TypeScript breaking change.** `SectionEventSubscriptionArgs`, `SectionItemEventSubscriptionArgs`, and `SectionScopedEventSubscriptionArgs` no longer declare `sectionId?` / `attemptId?` properties. Any host that imports these arg types directly and passes those keys will fail to compile after upgrade. **Action required.**
-- **Runtime is tolerant.** The runtime silently ignores extra unknown properties, so an untyped or lightly-typed call site that still passes `sectionId` / `attemptId` continues to work without source changes. The args have **no effect** at runtime — the subscription always follows the active cohort.
-- **New precondition.** `subscribe*` throws until the first `getOrCreateSectionController(...)` call; a listener added while a section is starting binds when that section becomes active. Subscribe **after** the first `getOrCreateSectionController(...)` resolves. Subscribing on `toolkit-ready` alone is no longer sufficient — though in practice the section player emits `toolkit-ready` *after* its first `getOrCreateSectionController(...)` resolves, so a `toolkit-ready` anchor is safe in section-player hosts.
-- **Cohort migration is automatic.** If your wrapper previously re-subscribed on every navigation to keep listeners alive across sections, that wiring is no longer needed (and should be removed). A single subscribe call after the first controller-resolve is now enough — the listener migrates automatically and is replayed the new cohort's snapshot on every transition.
-- **Watch for double-replay if you re-subscribe on every `toolkit-ready`.** Hosts that detached and re-subscribed on every `toolkit-ready` event (the correct pre-Phase D pattern, since each subscription was pinned to a `sectionId`) will now observe **two snapshot replays per navigation**: one delivered automatically when Phase D migrates the existing listener to the new active cohort, and a second when the manual re-subscribe attaches a fresh listener that replays again. Listener handlers that are not strictly idempotent will fire twice — analytics `pageAction`s, non-Set counters, side-effecting hydration. The fix is a one-line guard (`if (this.controllerUnsubscribe) return;`) so the subscribe runs only on the first `toolkit-ready`.
-- **For intentionally-pinned subscriptions to inactive sections** (e.g. a host UI that wants to keep watching section A while the user views section B), the helper API does not support that pattern by design. Use `coordinator.getSectionController({ sectionId, attemptId })` and subscribe directly on the controller handle (`controller.subscribe?.(...)`) — that binding is pinned to one controller instance and does not migrate.
-
-If your local types were hand-rolled structural copies of the public arg types (e.g. an Angular wrapper duplicating the shape rather than importing the package types), `sectionId` / `attemptId` keys will compile but are dead code at runtime — recommend dropping them as part of the upgrade.
-
-#### Pre-Phase D vs Phase D wrapper pattern
-
-```typescript
-// BEFORE (pre-Phase D): rebind for every section change because the
-// subscription was pinned to a sectionId.
-public handleToolkitReady(event: Event): void {
-  const coordinator = (event as CustomEvent).detail?.coordinator;
-  if (!coordinator) return;
-  this.controllerUnsubscribe?.();  // detach prior pin
-  const itemUnsub = coordinator.subscribeItemEvents({
-    sectionId: this.sectionId,
-    listener: handleItemEvent,
-  });
-  const sectionUnsub = coordinator.subscribeSectionLifecycleEvents({
-    sectionId: this.sectionId,
-    listener: handleSectionEvent,
-  });
-  this.controllerUnsubscribe = () => { itemUnsub?.(); sectionUnsub?.(); };
-}
-```
-
-```typescript
-// AFTER (Phase D): subscribe once; the listener follows the active
-// cohort across all subsequent navigation.
-public handleToolkitReady(event: Event): void {
-  const coordinator = (event as CustomEvent).detail?.coordinator;
-  if (!coordinator) return;
-  this.toolkitCoordinator = coordinator;
-  if (this.controllerUnsubscribe) return; // already subscribed; do nothing on re-fire
-  const itemUnsub = coordinator.subscribeItemEvents({
-    listener: handleItemEvent,
-  });
-  const sectionUnsub = coordinator.subscribeSectionLifecycleEvents({
-    listener: handleSectionEvent,
-  });
-  this.controllerUnsubscribe = () => { itemUnsub?.(); sectionUnsub?.(); };
-}
-```
-
 ### Option 2: Create Services Manually (Advanced)
 
 ```typescript
 import {
   TTSService,
   BrowserTTSProvider,
-  ToolCoordinator,
   HighlightCoordinator,
   AccessibilityCatalogResolver,
   ElementToolStateStore
@@ -425,7 +286,6 @@ import {
 
 // Initialize each service independently
 const ttsService = new TTSService();
-const toolCoordinator = new ToolCoordinator();
 const highlightCoordinator = new HighlightCoordinator();
 const elementToolStateStore = new ElementToolStateStore();
 const catalogResolver = new AccessibilityCatalogResolver([], 'en-US');
@@ -439,15 +299,15 @@ ttsService.setCatalogResolver(catalogResolver);
 No player element takes services one by one. The section and assessment
 players reach services only through a coordinator, `runtime.coordinator` on a
 section player and `coordinator` on an assessment player; manually created
-services serve host code that drives them directly.
+services serve host code that drives them directly. The tool coordinator is
+not among them: it is created and disposed by its `ToolkitCoordinator`.
 
 ### Without a Section Player
 
-`<pie-assessment-toolkit>` needs no section. Bind none and it provides tools,
-policy and services to the item toolbars and item players inside it, which is
-how the toolkit accompanies a plain item player. `<pie-item-scope>` holds the
-item for its tools, as it does in a section player's card. The tree this
-builds:
+`<pie-assessment-toolkit>` needs no section. Bind none and it serves the item
+toolbars inside it and the tools they open, around a plain item player that
+takes nothing from the toolkit. `<pie-item-scope>` holds the item for its tools,
+as it does in a section player's card. The tree this builds:
 
 ```html
 <pie-assessment-toolkit>
@@ -465,20 +325,17 @@ scope registers as soon as it mounts, and that first registration starts the
 coordinator from the toolkit's inputs at that moment; see the binding rules
 below.
 
+![Item player with the toolkit: the host sets tools, toolRegistry, toolContextResolvers and assessment on a pie-assessment-toolkit and receives runtime-ready with the coordinator; a pie-item-scope per item registers the item and its settings with the coordinator, its item toolbar takes tool policy and services from the coordinator, and the tools act on the content region that holds the item player](../../docs/img/toolkit-item-scope.excalidraw.svg)
+
 ```typescript
 import '@pie-players/pie-assessment-toolkit/components/pie-assessment-toolkit-element';
 import '@pie-players/pie-assessment-toolkit/components/item-scope-element';
 import '@pie-players/pie-assessment-toolkit/components/item-toolbar-element';
 import '@pie-players/pie-item-player';
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from '@pie-players/pie-default-tool-loaders';
+import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
 // With no section player, the registry's loaders are what define the tool elements.
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
+const toolRegistry = createPackagedToolRegistry();
 
 const toolkit = document.createElement('pie-assessment-toolkit');
 toolkit.tools = {
@@ -501,76 +358,107 @@ toolkit.append(scope);
 container.append(toolkit);
 ```
 
-The toolbars and tools inside the scope take the item and its id from it, and
-act on the scope, or on the element its `scopeElement` property names;
-`textToSpeech` reads the scope's `[data-region="content"]` first. A toolbar's
-own `item`, `item-id` and `scopeElement` still override the scope, and its
-`toolRegistry` the toolkit's. The scope
-registers the item with the toolkit once it finds one above it, so it may mount
-first, and the toolkit files the item's accessibility catalogs, which read-aloud
-speaks in place of the markup they name. Item player events pass through the
-scope unchanged, and the session stays the item player's. A registry built
-without `toolModuleLoaders` renders toolbar buttons whose tool elements never
-load.
-
-A profile change is a new `assessment` value; the toolbars re-derive on the
-policy change it emits. The toolkit announces `runtime-ready`, with
+Inside a scope:
+
+- The toolbars and tools take the item and its id from the scope, and act on
+  the scope or on the element its `scopeElement` property names.
+  `textToSpeech` reads the scope's `[data-region="content"]` first.
+- A toolbar's own `item`, `item-id` and `scopeElement` override the scope, and
+  its `toolRegistry` overrides the toolkit's.
+- The scope registers the item with the toolkit once it finds one above it, so
+  it may mount first. The toolkit files the item's accessibility catalogs,
+  which read-aloud speaks in place of the markup they name.
+- Item player events pass through the scope unchanged, and the session stays
+  the item player's.
+- A registry whose `toolModuleLoaders` leave a tool out renders a button for it
+  whose element never loads unless the host defines it.
+
+**Profile changes.** A profile change is a new `assessment` value; the toolbars
+re-derive on the policy change it emits. A host that holds the coordinator from
+`runtime-ready`, or passes its own as `coordinator`, changes the profile with
+`coordinator.updateAssessment(...)`; the toolkit applies its `assessment`
+property only to a coordinator it owns. The
+[`calculator-pnp` section demo](../../apps/section-demos/src/routes/%28demos%29/calculator-pnp/+page.svelte)
+composes the owned-coordinator form.
+
+**Readiness.** The toolkit announces `runtime-ready`, with
 `{ runtimeId, coordinator, ownership }`, once per coordinator, with or without a
 section. Without one, the coordinator starts at the first item that registers,
 and a host reads its readiness from `coordinator.waitUntilReady()` or
-`isReady()`; `toolkit-ready` and `section-ready` wait for a bound section. The
-toolkit emits no stage events: `pie-stage-change` is the section player's. A
-host that holds
-the coordinator from `runtime-ready`, or passes its own as `coordinator`,
-changes the profile with `coordinator.updateAssessment(...)`; the toolkit
-applies its `assessment` property only to a coordinator it owns. The
-`calculator-pnp` section demo composes the owned-coordinator form.
-
-The toolkit builds its own coordinator at mount from `tools`, `enabled-tools`,
-`assessment-id`, `accessibility`, `lazy-init`, `tool-config-strictness` and
-`toolRegistry`. Its first content binds it: the section, or without one the
-first item scope that registers. Content that arrives after one of those inputs
-changed binds a coordinator rebuilt from the current values, and the toolbars
-move to it. After that, a change to them is reported once in the console and
-does not reach the coordinator, except a `toolRegistry` given to a toolkit that
-had none, which the coordinator adopts in place; `tools.pnpEnforcement`,
-`assessment` and `toolContextResolvers` apply to it at any
-time. That
-coordinator reports feature policy asked with no assessment bound only while
-`tools.pnpEnforcement` is `on`: a toolkit given no `assessment` and no enforcement
-has asked for no accommodation.
-
-A toolkit nested in another inherits the outer one's coordinator when the outer
-one has a coordinator by the time the inner one connects, which holds for both
-mounted together. Otherwise the inner one builds its own and keeps it, and
-reports an outer coordinator arriving later once in the console. `isolation`
-`"force"` keeps a nested toolkit on its own coordinator by design.
-
-Text-to-speech starts at the toolkit's first content, once the section composes
-or the first item scope registers, and `coordinator.waitUntilReady()` waits for it. With `lazy-init` it starts at the first read-aloud instead, unless policy
-grants it. A tool provider or text-to-speech that fails to start is a
-recoverable framework error: the tool reports itself unavailable and the
-assessment goes on. When policy grants the tool, through an item or district
-requirement or a profile support, the failure is fatal, including one that a
-later policy change grants.
+`isReady()`. `toolkit-ready` and `section-ready` wait for a bound section, and
+both fire again for every section the toolkit initializes, `toolkit-ready`
+first, so a handler that needs the coordinator once guards itself. The toolkit
+emits no stage events: `pie-stage-change` is the section player's.
+
+**Coordinator binding.** The toolkit builds its own coordinator at mount from
+`tools`, `enabled-tools`, `assessment-id`, `accessibility`, `lazy-init`,
+`tool-config-strictness` and `toolRegistry`.
+
+- Its first content binds it: the section, or without one the first item scope
+  that registers.
+- Content that arrives after one of those inputs changed binds a coordinator
+  rebuilt from the current values, and the toolbars move to it.
+- Once bound, a change to those inputs is reported once in the console and does
+  not reach the coordinator. The exception is a `toolRegistry` given to a
+  toolkit that had none, which the coordinator adopts in place.
+- `tools.pnpEnforcement`, `assessment` and `toolContextResolvers` apply at any
+  time.
+- The coordinator reports feature policy asked with no assessment bound only
+  while `tools.pnpEnforcement` is `on`: a toolkit given no `assessment` and no
+  enforcement has asked for no accommodation.
+
+**Nested toolkits.** A toolkit nested in another inherits the outer one's
+coordinator when the outer one has a coordinator by the time the inner one
+connects, which holds for both mounted together. Otherwise the inner one builds
+its own and keeps it, and reports an outer coordinator arriving later once in
+the console. `isolation` `"force"` keeps a nested toolkit on its own coordinator
+by design.
+
+**Unmount.** At unmount the toolkit disposes the controller of every section it
+bound. A coordinator it owns it then disposes too; one the host passes, or an
+outer toolkit lends, stays with its owner, and a later toolkit on it restores
+those sections from their sessions.
+
+**TTS and provider startup.** Text-to-speech starts at the toolkit's first
+content, once the section composes or the first item scope registers, and
+`coordinator.waitUntilReady()` waits for it. With `lazy-init` it starts at the
+first read-aloud instead, unless policy grants it. A tool provider or
+text-to-speech that fails to start is a recoverable framework error: the tool
+reports itself unavailable and the assessment goes on. When policy grants the
+tool, through an item or district requirement, a profile support or a
+test-administration override set to `true`, the failure is fatal, including one
+that a later policy change grants. For a toolbar tool, only grants from
+decisions that PNP enforcement applies to make the failure fatal.
 
 ## Tool Configuration Model
 
-The toolkit uses one canonical `tools` model with three concerns:
+The toolkit uses one canonical `tools` model with four keys:
 
-- `policy`: allow/block constraints (global gates)
+- `policy`: which tools may appear at all. A non-empty `allowed` list is an
+  allow-list; `blocked` removes a tool absolutely, whatever else grants it.
 - `placement`: where tools appear (`section`, `item`, `passage`). Each tool
   declares the levels it supports; `calculator` is item-only, and a tool placed
   at a level it does not support fails validation, which throws under the
   default `toolConfigStrictness: "error"`.
-- `providers`: provider/runtime options (calculator, textToSpeech, etc.)
+- `providers`: provider and runtime options per tool (calculator,
+  textToSpeech and so on). `providers.<toolId>.enabled: false` vetoes the tool.
+- `pnpEnforcement`: `"on"` or `"off"` forces personal needs profile gating;
+  omitted, the toolkit turns it on when the assessment carries profile or
+  district material ([PNP enforcement](docs/PNP_CONFIGURATION.md#pnp-enforcement)).
+
+A profile, district policy or item setting names a tool by its `toolId`, and an
+id no registered tool carries raises `tool-policy.unknownSupportId`.
+[Support ids](docs/TOOL_REGISTRY.md#support-ids) lists the AfA PNP 3.0 terms the
+packaged ids serve.
 
 Example:
 
 ```typescript
 tools: {
   policy: {
+    // Only these tools may appear...
     allowed: ['calculator', 'textToSpeech', 'answerEliminator', 'graph', 'periodicTable'],
+    // ...and graph never does.
     blocked: ['graph']
   },
   placement: {
@@ -589,25 +477,38 @@ tools: {
 }
 ```
 
-### Scope and Lifecycle
+With this configuration the section toolbar shows only `periodicTable`:
+`graph` is blocked, and `protractor`, `lineReader` and `ruler` are outside the
+allow-list. The item and passage placements show every tool they list.
 
-The runtime still distinguishes between contextual (`item`/`passage`) and section-wide tools:
+### Scope and Lifecycle
 
-Tool instances use structured IDs so scope is explicit:
+Tool instances use structured ids that make their scope explicit:
 
 ```text
-<toolId>:<scopeLevel>:<scopeId>[:inline]
+<toolId>:<scopeLevel>:<scopeId>
 ```
 
-Examples:
-- `calculator:section:section-1`
-- `calculator:item:item-42`
+`scopeLevel` is one of `assessment`, `section`, `item`, `passage` or `rubric`,
+and `createScopedToolId` throws on any other. The toolbars the players render
+scope their ids at `section`, `item` or `passage`, and a rubric block's toolbar
+scopes at `passage`. Examples from a section player:
+
+- `lineReader:section:reading-1`
+- `theme:section:reading-1`
+- `calculator:item:q1`
 - `textToSpeech:passage:passage-1`
-- `highlighter:rubric:rubric-3`
+
+The section player keeps every item card of a section mounted while the student
+moves between its items. The ElementToolStateStore keeps answer eliminations,
+annotation highlights and the color-scheme choice, and the coordinator's
+`saveToolState`/`loadToolState` hooks carry them across reloads
+([Persistence Integration](#persistence-integration)). Which tools are open is
+not restored, and graph points start over.
 
 ### Item-Level Tools (`tools.placement.item`)
 
-Tools that operate **within the context of a specific question/item**:
+Tools that operate within the context of one item:
 
 ```typescript
 tools: {
@@ -618,24 +519,37 @@ tools: {
 ```
 
 **Characteristics:**
-- **Scope**: Bound to a specific item's DOM context
-- **Lifecycle**: Instance created/destroyed as you navigate between items
-- **State**: Isolated per-item (eliminations for Q5 don't affect Q6)
-- **UI Pattern**: Inline buttons in question headers/toolbars
-- **State Persistence**: Tracked per-item in ElementToolStateStore
-
-**Available Item-Level Tools:**
-- **TTS (Text-to-Speech)**: Reads the specific question/passage text
-- **Answer Eliminator**: Strikes through answer choices for that question
-- **Calculator**: Basic, scientific or graphing calculator
-- **Highlighter** (`annotationToolbar`): Highlights and annotates selected text; it opens from a text selection, outside the toolbars
+- **Scope**: bound to one item's DOM context
+- **Lifetime**: an item's tools live as long as its card, which stays mounted
+  until the section changes
+- **State**: isolated per item (eliminations on Q5 don't affect Q6)
+- **UI pattern**: buttons in the item toolbar; tools such as the calculator and
+  the dictionaries open in a floating panel
+- **Persistence**: answer eliminations and annotation highlights are kept per
+  PIE element in the ElementToolStateStore
+
+**Available item-level tools:**
+- **Text-to-speech** (`textToSpeech`): reads the item or passage text
+- **Answer eliminator** (`answerEliminator`, item only): strikes through answer
+  choices
+- **Calculator** (`calculator`, item only): basic, scientific or graphing
+  calculator
+- **Annotation toolbar** (`annotationToolbar`): highlights and annotates
+  selected text; it opens from a text selection, outside the toolbars
+- **Line reader** (`lineReader`), **ruler** (`ruler`), **protractor**
+  (`protractor`), **graph** (`graph`) and **periodic table** (`periodicTable`)
+- **Dictionaries** (`dictionary`, `pictureDictionary`, `dictionarySpanish`,
+  `pictureDictionarySpanish`)
+
+[Default Tools](docs/TOOL_REGISTRY.md#default-tools) lists every packaged tool
+with the content it applies to.
 
 **Example Use Case:**
 A student uses answer eliminator on Question 3 to cross out choices B and D. When they navigate to Question 4, they see fresh, uneliminated choices. When they return to Question 3, their eliminations are restored.
 
 ### Section-Level Tools (`tools.placement.section`)
 
-Tools that **float above the entire assessment** and persist across questions:
+Tools that float above the section and stay open across its items:
 
 ```typescript
 tools: {
@@ -645,26 +559,30 @@ tools: {
 }
 ```
 
-The section player renders the section toolbar only when its `show-toolbar`
-attribute is `true`; the attribute defaults to `false`.
-
 **Characteristics:**
-- **Scope**: Section-wide, shared across all questions
-- **Lifecycle**: Single instance initialized for entire section
-- **State**: Persistent (a tool stays open and in place as you navigate)
-- **UI Pattern**: Draggable floating panels/overlays with z-index management
-- **State Persistence**: Global state maintained throughout section
-
-**Available Floating Tools:**
-- **Graph**: Coordinate plane
-- **Periodic Table**: Interactive periodic table reference
-- **Protractor**: Angle measurement tool
-- **Ruler**: Linear measurement tool (metric/imperial)
-- **Line Reader**: Reading guide/masking overlay
-- **Color Scheme** (`theme`): High-contrast color adjustments
+- **Scope**: section-wide, shared across the section's items
+- **Lifetime**: one instance per section; at a section change the tool
+  re-scopes to the new section and its state starts over
+- **State**: an open tool stays open and in place while the student moves
+  between the section's items
+- **UI pattern**: draggable floating panels with z-index management
+
+**Available section-level tools:**
+- **Graph** (`graph`): coordinate plane
+- **Periodic table** (`periodicTable`): interactive periodic table reference
+- **Protractor** (`protractor`): angle measurement
+- **Ruler** (`ruler`): linear measurement (metric and imperial)
+- **Line reader** (`lineReader`): reading guide and masking overlay
+- **Dictionaries** (`dictionary`, `pictureDictionary`, `dictionarySpanish`,
+  `pictureDictionarySpanish`)
+- **The color-scheme tool** (`theme`): high-contrast color schemes; it also
+  supports assessment level
+
+Every section-level tool except the color-scheme tool also supports item
+placement.
 
 **Example Use Case:**
-A student opens the periodic table on Question 2 and moves it beside the passage. When they navigate to Question 7, it is still open where they left it.
+A student opens the periodic table on Question 2 and moves it beside the passage. When they navigate to Question 7 of the same section, it is still open where they left it.
 
 ### When to Use Each
 
@@ -674,25 +592,23 @@ Use **item-level tools** when:
 - Tool appears inline with the question (space-efficient)
 - Tool behavior is contextual to the current item
 
-Use **floating tools** when:
+Use **section-level tools** when:
 - Tool is a general-purpose utility used across multiple questions
-- State should persist across navigation
+- State should persist while the student moves between a section's items
 - Tool needs independent positioning and sizing
 - Tool provides reference information or computation capability
 
-### Configuration Example
+### Configuration example
 
-Complete example showing both types:
+A coordinator shows a tool only where `tools.placement` lists it, and its
+default placement is empty. This configuration places the commonly used tools
+at both kinds of level:
 
 ```typescript
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from '@pie-players/pie-default-tool-loaders';
+import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
+import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
+const toolRegistry = createPackagedToolRegistry();
 const coordinator = new ToolkitCoordinator({
   assessmentId: 'math-exam',
   toolRegistry,
@@ -726,52 +642,16 @@ const coordinator = new ToolkitCoordinator({
 });
 ```
 
-**A common placement:**
+### Calculator providers
 
-A coordinator shows a tool only where `tools.placement` lists it. Its default
-placement is empty, so a coordinator configured without one shows no tools, and
-a profile grant does not place a tool either. This placement covers the
-commonly used tools:
-
-```typescript
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from '@pie-players/pie-default-tool-loaders';
-
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
-const coordinator = new ToolkitCoordinator({
-  assessmentId: 'my-assessment',
-  toolRegistry,
-  tools: {
-    placement: {
-      section: ['graph', 'periodicTable', 'protractor', 'lineReader', 'ruler'],
-      item: ['calculator', 'textToSpeech', 'answerEliminator'],
-      passage: ['textToSpeech']
-    },
-    providers: {
-      calculator: {
-        enabled: true,
-        provider: {
-          runtime: { authFetcher: fetchLicensedDesmosApiKey }
-        }
-      },
-      textToSpeech: { enabled: true, backend: 'browser' }
-    }
-  }
-});
-```
-
-The ToolkitCoordinator handles service initialization, provider management, and
-state coordination. With no calculator provider configuration, the Desmos
-implementation remains the default. Desmos's CDN rejects a `calculator.js`
-request without an `apiKey` (HTTP 403), so the Desmos calculator opens only when
-the host supplies `provider.init.apiKey` or `provider.runtime.authFetcher`, or
-has already loaded `window.Desmos`; the adapter's keyless request grants no
-Desmos license either. Runtime key delivery avoids committing the key but does
-not hide it from the browser's Desmos script request. The bundled open-source
+With no calculator provider configured, the calculator is Desmos. Desmos's CDN
+rejects a `calculator.js` request without an `apiKey` (HTTP 403), so the Desmos
+calculator opens only when the host supplies a key through
+`provider.runtime.authFetcher`, a `provider.init.proxyEndpoint` that returns
+`{ apiKey }`, or `provider.init.apiKey`, or has already loaded `window.Desmos`.
+Without one the adapter throws "An apiKey or proxyEndpoint is required to load
+Desmos." Runtime key delivery keeps the key out of the bundle, and the
+browser's Desmos script request still carries it. The bundled open-source
 implementation below needs no key.
 
 Select the separate GeoGebra implementation explicitly without changing the
@@ -819,8 +699,9 @@ tools: {
 By default, server-backed TTS resolves:
 
 - `apiEndpoint: '/api/tts'`
-- `transportMode: 'pie'`
-- `endpointValidationMode: 'voices'`
+- `transportMode: 'custom'` for `serverProvider: 'custom'`, else `'pie'`
+- `endpointValidationMode: 'voices'`, so the provider reads the voices route
+  before it reports ready; `'none'` skips the probe
 
 You can still set `apiEndpoint` explicitly when your host route is not `/api/tts`.
 
@@ -957,9 +838,9 @@ Recommended host boundary:
   upstream.
 - Browser never receives shared secret, API key, or signing material.
 
-SchoolCity is used as a host-configured integration example for custom transport.
-Toolkit defaults still remain browser/standard providers unless the host explicitly
-configures custom server-backed TTS.
+The section demos' `/api/tts/sc` route, backed by the SC adapter
+(`@pie-players/tts-server-sc`), is the worked example of custom transport. TTS
+stays on browser speech unless the host configures a server backend.
 
 ## Test Attempt Session
 
@@ -994,7 +875,7 @@ const itemSessions = toItemSessionsRecord(testAttemptSession);
 ### Integration Boundary
 
 - `@pie-players/pie-section-player` stays backend-agnostic and emits session/state changes.
-- Host applications own backend I/O to pie backend (`../../kds/pie-api-aws`).
+- Host applications own backend I/O.
 - Hosts decide persistence policy (immediate, debounced, checkpoint, submit).
 
 ### Section session API (controller + persistence)
@@ -1006,34 +887,6 @@ For section-level session flows, the toolkit supports two complementary APIs:
 
 The persistence strategy works with the same `SectionControllerSessionState` shape exposed by the controller, so hosts can choose bulk restore (`applySession`) and fine-grained updates (`updateItemSession`) without internal runtime coupling.
 
-## Implementation Status
-
-### ✅ Toolkit Services
-
-- **ToolkitCoordinator**: ⭐ NEW - Centralized service orchestration
-- **ElementToolStateStore**: ⭐ NEW - Element-level ephemeral tool state management
-- **ToolRegistry**: ⭐ NEW - Registry-based tool management with AfA PNP 3.0 profile support
-- **ToolPolicyEngine**: AfA PNP 3.0 Personal Needs Profile and host policy decisions via registry-backed policy sources
-- **ToolCoordinator**: Manages z-index layering and visibility for floating tools
-- **HighlightCoordinator**: Separate highlight layers for TTS (temporary) and annotations (persistent)
-- **TTSService**: Text-to-speech with QTI 3.0 catalog support
-- **AccessibilityCatalogResolver**: QTI 3.0 accessibility catalog management
-- **SSMLExtractor**: Automatic extraction of embedded `<speak>` tags
-
-### ✅ PNP Support Ids
-
-- **Support ids are tool ids**: A profile, district policy or item setting names a tool by its `toolId`, and an id no registered tool carries raises `tool-policy.unknownSupportId`. [Support ids](docs/TOOL_REGISTRY.md#support-ids) lists the AfA PNP 3.0 terms the packaged ids serve.
-
-### ✅ Section Player Integration
-
-The toolkit integrates seamlessly with the **PIE Section Player**:
-
-- **Primary Interface**: Section player is the main integration point
-- **Default Coordinator**: Creates ToolkitCoordinator automatically if not provided
-- **Automatic SSML Extraction**: Extracts embedded `<speak>` tags from passages and items
-- **Catalog Lifecycle**: Manages item-level catalogs automatically
-- **Service Coordination**: All toolkit services work together automatically
-
 ## ToolkitCoordinator API
 
 ### Configuration
@@ -1051,13 +904,18 @@ export interface ToolkitCoordinatorConfig {
       item?: string[];
       passage?: string[];
     };
+    pnpEnforcement?: 'on' | 'off';  // omitted: auto-detected from the assessment
     providers?: {
+      // Abridged; TextToSpeechToolProviderConfig carries every option.
       textToSpeech?: {
         enabled?: boolean;
         backend?: 'browser' | 'server';
         serverProvider?: 'polly' | 'google' | 'custom';
+        apiEndpoint?: string;
         defaultVoice?: string;
         rate?: number;
+        speedOptions?: TTSSpeedOption[];
+        layoutMode?: 'reserved-row' | 'expanding-row' | 'floating-overlay' | 'left-aligned';
       };
       calculator?: {
         enabled?: boolean;
@@ -1073,63 +931,108 @@ export interface ToolkitCoordinatorConfig {
       };
     };
   };
+  toolConfigStrictness?: 'off' | 'warn' | 'error';  // default 'error'
   toolRegistry?: ToolRegistry | null;
+  toolContextResolvers?: ToolContextResolverMap;
   accessibility?: {
     catalogs?: any[];
     language?: string;
   };
+  hooks?: ToolkitCoordinatorHooks;
+  lazyInit?: boolean;   // default false
+  eagerInit?: boolean;  // default !lazyInit
 }
 ```
 
+A `ToolkitCoordinator` registers tool providers only from its `toolRegistry`.
+Built without one, it adopts the registry of the toolkit it is bound to, such as
+the section player's, which then validates its config and registers its
+providers. A registry passed at construction is never replaced. Bound to a
+toolkit that has none, it registers no providers, skips tool-id and placement
+validation, and warns once (`tools.registryUnavailable`).
+
 ### Methods
 
 ```typescript
 // Tool configuration
-coordinator.getToolConfig('textToSpeech');  // Get tool-specific config
-coordinator.updateToolConfig('textToSpeech', { rate: 1.5 });  // Update tool config; replaces the tool's provider, which starts again on next use
-
-// Final teardown by the owner that constructed the coordinator
-await coordinator.dispose();
+coordinator.getToolConfig('textToSpeech');
+coordinator.updateToolConfig('textToSpeech', { rate: 1.5 });  // replaces the tool's provider, which starts again on next use
+coordinator.updateToolsPlacement({ item: ['calculator', 'textToSpeech'] });
+
+// Tool policy
+coordinator.decideToolPolicy({ level: 'item', scope: { level: 'item', scopeId: 'item-42' } });
+coordinator.decideFeaturePolicy('transcript', { level: 'item', scopeId: 'item-42' });
+const unregisterItem = coordinator.registerItemSettings('item-42', itemSettings);
+const offPolicy = coordinator.onPolicyChange(listener);
+const offDiagnostics = coordinator.onPolicyDiagnostic(listener);
+coordinator.updateAssessment(assessment);  // new profile or settings; null unbinds
+coordinator.setPnpEnforcement('on');       // 'on' | 'off'; null returns to auto-detection
+coordinator.getPolicyInputs();             // read-only inputs behind current decisions
+const unregisterSource = coordinator.registerPolicySource(source);
+
+// Tool requests: ask the toolbar hosting a tool to open it
+const unregisterTarget = coordinator.registerToolRequestTarget(target);
+coordinator.canRequestTool('calculator');      // false for a tool the deployment lacks
+coordinator.requestTool({ toolId: 'calculator' });  // whether a toolbar claimed it; throws on an unknown id
+const offTargets = coordinator.onToolRequestTargetsChange(listener);
+
+// Providers and events
+const provider = await coordinator.ensureProviderReady('textToSpeech');
+const offErrors = coordinator.subscribeFrameworkErrors(listener);
+const offCatalogs = coordinator.onCatalogsChange(listener);
+
+// Readiness and teardown
+await coordinator.waitUntilReady();
+coordinator.isReady();
+coordinator.getToolRegistry();
+await coordinator.dispose();  // final teardown by the owner that constructed the coordinator
 ```
 
+Each `register*`, `on*` and `subscribe*` call returns a function that undoes it.
+The section-controller methods are under
+[Controller Event Subscriptions](#controller-event-subscriptions-helper-first).
+
 ### Direct Service Access
 
 All services are public properties for direct access:
 
 ```typescript
 coordinator.ttsService              // TTSService instance
-coordinator.toolCoordinator         // ToolCoordinator instance
+coordinator.toolCoordinator         // ToolCoordinatorApi, owned by the coordinator
 coordinator.highlightCoordinator    // HighlightCoordinator instance
 coordinator.elementToolStateStore   // ElementToolStateStore instance
 coordinator.catalogResolver         // AccessibilityCatalogResolver instance
+coordinator.toolProviderRegistry    // ToolProviderRegistry, the providers registered from toolRegistry
 ```
 
 ## ElementToolStateStore API
 
-The `ElementToolStateStore` manages ephemeral tool state at the element level using globally unique composite keys.
+The `ElementToolStateStore` holds tool state per PIE element under globally unique composite keys. It is kept apart from PIE session data and leaves the browser only through the coordinator's `saveToolState` hook ([Persistence Integration](#persistence-integration)).
 
 ### Key Concepts
 
-- **Global Element ID**: Composite key format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`
-- **Element-Level Granularity**: State tracked per PIE element (not per item)
-- **Ephemeral State**: Tool state is client-only, separate from PIE session data
+- **Global Element ID**: Composite key format: `${assessmentId}:${sectionId}:${attemptId}:${itemId}:${elementId}`, with `attemptId` `""` when the host names no attempt
+- **Element-Level Granularity**: State tracked per PIE element; a tool keyed by item or section leaves `elementId`, and for a section `itemId`, as `""`
+- **Per-Attempt State**: two attempts at one section never share a key
+- **Separate from session data**: tool state never enters the PIE session and is never scored
 - **Cross-Section Persistence**: State persists when navigating between sections
 
 ### ID Utilities
 
 ```typescript
 // Generate global element ID
-const globalElementId = store.getGlobalElementId(
-  'demo-assessment',
-  'section-1',
-  'question-1',
-  'mc1'
-);
-// Returns: "demo-assessment:section-1:question-1:mc1"
+const globalElementId = store.getGlobalElementId({
+  assessmentId: 'demo-assessment',
+  sectionId: 'section-1',
+  attemptId: 'attempt-1',
+  itemId: 'question-1',
+  elementId: 'mc1'
+});
+// Returns: "demo-assessment:section-1:attempt-1:question-1:mc1"
 
 // Parse global element ID
 const components = store.parseGlobalElementId(globalElementId);
-// Returns: { assessmentId, sectionId, itemId, elementId }
+// Returns: { assessmentId, sectionId, attemptId, itemId, elementId }
 ```
 
 ### CRUD Operations
@@ -1159,7 +1062,7 @@ store.clearElement(globalElementId);
 // Clear state for a specific tool across all elements
 store.clearTool('answerEliminator');
 
-// Clear all elements in a specific section
+// Clear all elements in a specific section, across its attempts
 store.clearSection('demo-assessment', 'section-1');
 
 // Clear all state
@@ -1168,17 +1071,21 @@ store.clearAll();
 
 ### Persistence Integration
 
+A coordinator's store reports changes to the coordinator, which forwards them
+to `hooks.saveToolState`; `loadToolState` is read once while the coordinator
+gets ready. Persist tool state through those hooks. `store.setOnStateChange`
+holds a single callback, so calling it on a coordinator's store disconnects
+`saveToolState`.
+
 ```typescript
-// Set callback for persistence (e.g., localStorage)
-store.setOnStateChange((state) => {
-  localStorage.setItem('tool-state', JSON.stringify(state));
+const coordinator = new ToolkitCoordinator({
+  assessmentId: 'demo-assessment',
+  toolRegistry,
+  hooks: {
+    loadToolState: () => JSON.parse(localStorage.getItem('tool-state') ?? 'null'),
+    saveToolState: (state) => localStorage.setItem('tool-state', JSON.stringify(state)),
+  },
 });
-
-// Load state from persistence
-const saved = localStorage.getItem('tool-state');
-if (saved) {
-  store.loadState(JSON.parse(saved));
-}
 ```
 
 ### Reactivity
@@ -1252,7 +1159,8 @@ onDestroy(() => registration.release());
 Visibility and stacking then go through the coordinator by scoped tool id:
 `showTool`, `hideTool`, `toggleTool`, `isToolVisible`, `bringToFront(element)`,
 and `getVisibleTools({ baseId })` / `hideAllTools({ baseId })` for one tool
-across scopes.
+across scopes. Disposing the toolkit coordinator releases every entry. Its
+debug lines print only under `window.PIE_DEBUG = true`.
 
 ### HighlightCoordinator
 
@@ -1282,12 +1190,14 @@ Reading highlights resolve through five `component-public` tokens registered in
 | `--pie-tts-word-underline` | `--pie-text` at 70% | Underline marking the current word |
 | `--pie-tts-word-shadow` | `--pie-text` at 35% | Shadow carrying the word over its fill |
 
-The coordinator derives all five from the active theme's accent, text and
-background — opacities clamped to a legible band, and the underline colour picked
-by background luminance so the cue survives a dark scheme — then writes them
-inline on the document element. Inline styles outrank any author selector, so a
-host override takes `!important` and owns the contrast the derivation was
-maintaining, across every scheme it ships.
+The coordinator derives all five from the active theme's `--pie-missing`,
+`--pie-text` and `--pie-background`. `--pie-missing` is the theme's
+missing-response feedback color, which reading highlights reuse as their accent.
+Opacities are clamped to a legible band, and the underline color is picked by
+background luminance so the cue survives a dark scheme. The coordinator writes
+the five inline on the document element. Inline styles outrank any author
+selector, so a host override takes `!important` and owns the contrast the
+derivation was maintaining, across every scheme it ships.
 
 ### AccessibilityCatalogResolver
 
@@ -1374,11 +1284,8 @@ catalogResolver.addItemCatalogs(result.catalogs);
 
 ### Cards without an extractor
 
-Not every catalog card is lifted out of item markup. A signed alternate is
-authored or written by an importer and has no extractor at all; one such lift
-existed and was removed, because nothing produced the inline form and a runtime
-that could not parse the markup left the video in the visible content, showing the
-accommodation to every learner regardless of eligibility.
+A signed alternate is authored or written by an importer; no extractor lifts it
+from markup.
 
 This package resolves and registers those cards through
 `AccessibilityCatalogResolver` and the generic media helpers it re-exports
@@ -1391,25 +1298,18 @@ needs them — signing's card validators and its resolution rules live in
 
 `ToolPolicyEngine.decideFeature(featureId, scope?)` (and
 `ToolkitCoordinator.decideFeaturePolicy(featureId, scope?)`) resolve one feature id
-through `PnpPolicySource`'s six-level precedence, independent of any toolbar
-placement. Use it for capabilities that are not toolbar surfaces — signing is the
-first — where a placement-scoped `decide(...)` would answer the wrong question:
-absent because it was never placed, rather than absent because policy said no.
-An item scope applies that item's registered settings, the item restriction and
+through `PnpPolicySource`'s PNP precedence, independent of any toolbar
+placement. Use it for capabilities that are not toolbar surfaces, such as
+signing: an item-level `decideToolPolicy(...)` also reports a tool absent when it
+was never placed, so it cannot tell a denial from a missing placement. An item
+scope applies that item's registered settings, the item restriction and
 requirement rungs; a decision without one applies no item's.
 
-This package ships no profile. Which capabilities a deployment grants by default is a property
-of the program rather than of a capability — TTS is a universal feature in one
-program and a documented accommodation in another — so it belongs in policy
-configuration alongside the district and test-administration levels. Hosts that
-want today's universal set take `createUniversalPersonalNeedsProfile()` from
-`@pie-players/pie-default-tool-loaders`, which ships it as data beside
-`createEmptyPersonalNeedsProfile()`.
+This package ships no profile.
+[Universal and empty profiles](../default-tool-loaders/README.md#universal-and-empty-profiles)
+covers the profiles `@pie-players/pie-default-tool-loaders` builds.
 
-Nothing derives a profile from the registry any more. Doing so read registry
-membership as eligibility tier — registration means "policy-addressable", not
-"universal, on by default" — and had to be corrected with a compile-time list of
-ids to exclude that a host could not extend for its own accommodation.
+Registry membership makes a tool policy-addressable; it grants nothing.
 
 ### Live registry changes
 
@@ -1430,15 +1330,10 @@ The section player provides automatic ToolkitCoordinator integration:
 
 <script type="module">
   import { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
-  import {
-    createPackagedToolRegistry,
-    DEFAULT_TOOL_MODULE_LOADERS,
-  } from '@pie-players/pie-default-tool-loaders';
+  import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
   // Create coordinator
-  const toolRegistry = createPackagedToolRegistry({
-    toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-  });
+  const toolRegistry = createPackagedToolRegistry();
   const coordinator = new ToolkitCoordinator({
     assessmentId: 'my-assessment',
     toolRegistry,
@@ -1511,7 +1406,7 @@ player.section = mySection;
 
 // Internally creates:
 // new ToolkitCoordinator({
-//   assessmentId: 'section-demo-direct', // or runtime.assessmentId
+//   assessmentId: runtime.assessmentId ?? section.identifier ?? 'assessment-<random>',
 //   toolRegistry,                        // the player's toolRegistry, else the packaged registry
 //   tools: player.runtime?.tools         // no tools are placed when this is unset
 // })
@@ -1519,12 +1414,7 @@ player.section = mySection;
 
 ### Safe Custom Tool Configuration
 
-Default behavior is now framework-owned: invalid tools/runtime initialization is handled in `pie-assessment-toolkit` without host try/catch.
-
-- Framework logs a deterministic console error prefix: `[pie-framework:<kind>:<source>]`
-- Framework emits a canonical `framework-error` event
-- Framework renders a fallback error panel instead of a blank player
-- Startup tool-config validation can surface as `kind: "coordinator-init"` when the owned coordinator construction path throws.
+Invalid tool or runtime initialization is handled inside `pie-assessment-toolkit`; the host needs no try/catch. The error model, its events and hooks, and the fallback panel are in [Framework-owned error handling](../../docs/tools-and-accomodations/framework-owned-error-handling.md); host-side config patterns are in [Safe custom tool configuration](../../docs/tools-and-accomodations/safe-custom-tool-config.md).
 
 Use `createToolsConfig()` when you want to pre-validate and inspect diagnostics before mounting:
 
@@ -1533,14 +1423,9 @@ import {
   createToolsConfig,
   ToolkitCoordinator
 } from "@pie-players/pie-assessment-toolkit";
-import {
-  createPackagedToolRegistry,
-  DEFAULT_TOOL_MODULE_LOADERS,
-} from "@pie-players/pie-default-tool-loaders";
+import { createPackagedToolRegistry } from "@pie-players/pie-default-tool-loaders";
 
-const toolRegistry = createPackagedToolRegistry({
-  toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
+const toolRegistry = createPackagedToolRegistry();
 const { config, diagnostics } = createToolsConfig({
   source: "host.bootstrap",
   strictness: "error",
@@ -1569,22 +1454,49 @@ Notes:
 - `providers.textToSpeech` is the canonical TTS provider key.
 - `providers.tts` is rejected by the validation contract.
 - A tool registration can declare `sanitizeConfig` and `validateConfig` hooks for its `providers.<toolId>` entry.
-- Hosts can react to framework errors via the `framework-error` DOM event,
-  the `onFrameworkError(model)` callback prop, or by subscribing directly
-  to the package-internal bus via
-  `ToolkitCoordinator.subscribeFrameworkErrors(listener)`. The callback
-  prop fires exactly once per error, regardless of wrapper depth. Filter
-  by `model.kind` (e.g. `"tts-init"`, `"provider-init"`,
-	`"provider-register"`, `"tool-surface"`) for tool- or provider-specific
-	handling. Recoverable warnings remain observable but do not move section
-	readiness to `error`.
-- See `docs/tools-and-accomodations/framework-owned-error-handling.md` for event payload and error-kind mapping details.
+
+## Instrumentation and Observability
+
+Toolkit instrumentation is provider-agnostic. It uses the shared
+`InstrumentationProvider` contract from `@pie-players/pie-players-shared`.
+
+### Injection Path
+
+When the toolkit is hosted by a section or assessment player, the provider
+comes from the item-player loader config:
+
+- `runtime.player.loaderConfig.instrumentationProvider`
+
+### Semantics
+
+- How an unset, `null` or invalid provider resolves is set out in [Instrumentation providers](../../docs/architecture/instrumentation-providers.md#provider-resolution).
+- Debug overlays can consume the same stream by composing providers with
+  `CompositeInstrumentationProvider` (for example New Relic + debug panel).
+- Toolkit telemetry forwarding uses the same provider path, so tool/backend
+  instrumentation is sent to production providers and is visible in debug panel
+  overlays.
+
+### Toolkit-Owned Canonical Event Stream
+
+- `pie-toolkit-runtime-owned`
+- `pie-toolkit-runtime-inherited`
+- `pie-toolkit-runtime-ready`
+- `pie-toolkit-ready`
+- `pie-toolkit-section-ready`
+- `pie-toolkit-framework-error`
+
+Toolkit operational events are listed in [Instrumentation providers](../../docs/architecture/instrumentation-providers.md#operational-events).
+
+The toolkit emits toolkit lifecycle events only; section and assessment events
+stay in their own layers, so no event has two emitters. The event bridge's
+optional `dedupeWindowMs` drops repeats within a window and is off by default.
 
 ## Section Runtime Engine (advanced)
 
 The section runtime engine is the section player's stage chain: a pure FSM that
-turns the cohort a layout shows, the controller resolving and the readiness
-signals the layout derives into `pie-stage-change` and `pie-loading-complete`.
+turns the cohort a layout shows (its `(sectionId, attemptId)` pair), the
+controller resolving and the readiness signals the layout derives into
+`pie-stage-change` and `pie-loading-complete`.
 The section player's layout kernel owns one per layout element, and it is the
 only stage emitter. `<pie-assessment-toolkit>` emits no stages: its
 `SectionControllerBinding` resolves the section's controller, which the toolkit
@@ -1611,14 +1523,16 @@ before `interactive` ends the chain: the first stage the cohort did not reach is
 `failed` and the rest up to `interactive` are `skipped`. The section player sets
 `runtimeError` from a non-recoverable `framework-error`, so a host waiting on
 `engine-ready` or `interactive` always hears an answer. `pie-loading-complete`
-fires once per cohort, when every item has loaded.
+fires once per cohort, on the condition that opens `interactive`: the section
+controller is ready and the element pre-warm for the current items has
+resolved. The items load after it; the controller's `section-loading-complete`
+marks them loaded.
 
 ### Common-host wiring example
 
 Most hosts never construct the engine: the section-player layout elements do,
 and a host-built section layout takes its engine from
-`pie-section-player-kernel-host` (see the section player's
-[Custom layout authoring](../section-player/README.md#custom-layout-authoring)).
+`pie-section-player-kernel-host` ([custom section layouts](../../docs/section-player/custom-layouts.md)).
 Use the facade for a section renderer outside the section player. The shape
 mirrors the section-player kernel:
 
@@ -1695,21 +1609,23 @@ in the package's build with a pattern that covers subpaths, not a bare specifier
 
 `@pie-players/pie-tool-sign-language` is the worked example end to end: a
 registration, a content resolver, its own custom element, and no edit to any
-generic package. `packages/default-tool-loaders/README.md` covers how a
-deployment then composes it in, and `docs/TOOL_REGISTRY.md` the registration and
+generic package. The [default-tool-loaders README](../default-tool-loaders/README.md)
+covers how a deployment then composes it in, and the
+[Tool Registry Reference](docs/TOOL_REGISTRY.md) the registration and
 host-surface contracts.
 
-## State Separation: Tool State vs Session Data
+## State separation
 
-The toolkit enforces a clear separation between ephemeral tool state and persistent session data:
+The toolkit keeps tool state and PIE session data in separate stores.
 
-### Tool State (Ephemeral - ElementToolStateStore)
+### Tool state (ElementToolStateStore)
 
-**Client-only**, never sent to server for scoring:
+Never scored; it leaves the browser only through the coordinator's
+`saveToolState` hook ([Persistence Integration](#persistence-integration)):
 
 ```typescript
 {
-  "demo-assessment:section-1:question-1:mc1": {
+  "demo-assessment:section-1:attempt-1:question-1:mc1": {
     "answerEliminator": {
       "eliminatedChoices": ["choice-b", "choice-d"]
     },
@@ -1726,9 +1642,9 @@ The toolkit enforces a clear separation between ephemeral tool state and persist
 - Tool preferences
 - UI state
 
-### PIE Session Data (Persistent)
+### PIE session data
 
-**Sent to server** for scoring:
+The host persists it, and its backend scores it:
 
 ```typescript
 {
@@ -1748,11 +1664,7 @@ The toolkit enforces a clear separation between ephemeral tool state and persist
 
 ## Examples
 
-See the [section-demos](../../apps/section-demos/) for complete examples:
-
-- **Three Questions Demo**: Element-level answer eliminator with state persistence
-- **TTS Integration Demo**: Toolkit coordinator with TTS service
-- **Paired Passages Demo**: Multi-section assessment with cross-section state
+See [section-demos](../../apps/section-demos/) for complete examples, among them "Demo 3: Three Questions, One Passage", "Demo 4: TTS with SSML Extraction" and "Two Passages with One Question".
 
 ## TypeScript Support
 
@@ -1776,31 +1688,27 @@ from tool configuration. Two sanitization layers apply:
   `pie-item-player`. See
   [pie-item-player README](../item-player/README.md#content-trust-boundary)
   for the `trust-markup` opt-out and the `sanitizeMarkup` override.
-  As a post-sanitization step, every authored `<img>` outside a `pie-*`
-  custom element is wrapped in `<span class="pie-image-scroll">` so
-  overwide images surface a horizontal scrollbar instead of being
-  clipped by the section layout's `overflow-x: hidden` ancestors
-  (PIE-94 / WCAG 1.4.10 Reflow at 400% zoom). The wrapper is
-  keyboard-scrollable (`tabindex="0"`, `role="region"`) and carries
-  the image's `alt` text in its `aria-label`; matching CSS lives in
-  `@pie-players/pie-theme` (`components.css`). Authored `<table>`
-  elements outside a `pie-*` custom element get the same treatment via
-  `<div class="pie-table-scroll">` so wide data grids reflow into a
-  horizontally scrollable region; the wrapper's `aria-label` is derived
-  from the table's `aria-label` / `aria-labelledby` / `<caption>`.
+  The player also wraps overwide images and tables in scrollable regions
+  ([reflow wrappers](../item-player/README.md#reflow-wrappers)).
 - **Tool icons and SSML** - tool-registered icon markup is parsed and
   DOMPurified inside the toolbar at render time; SSML payloads are
   restricted to an allow-listed subset of SSML tags/attributes before
   being forwarded to TTS providers. Do not ship tools that rely on raw
   `<script>` or event-handler attributes in their icon strings.
 
+[Security](../../docs/security/readme.md) sets out the full trust boundary and
+the host's obligations.
+
 ## Related Documentation
 
-- **[Tool Registry Architecture](docs/TOOL_REGISTRY.md)** - ⭐ NEW - Registry-based tool management and AfA PNP 3.0 profile support
-- **[PNP Configuration Guide](docs/PNP_CONFIGURATION.md)** - ⭐ NEW - How to configure student profiles, district policies, and governance rules
-- [ToolkitCoordinator Architecture](../../docs/architecture/architecture.md#toolkitcoordinator-centralized-service-management) - Design decisions and patterns
+- [Tool Registry Reference](docs/TOOL_REGISTRY.md) - Registry-based tool management and AfA PNP 3.0 profile support
+- [PNP Configuration Guide](docs/PNP_CONFIGURATION.md) - How to configure student profiles, district policies, and governance rules
+- [Configuring Tools](../../docs/tools-and-accomodations/tool_provider_system.md) - Placement, policy and provider configuration
+- [Toolkit Tool Host Contract](../../docs/tools-and-accomodations/tool_host_contract.md) - Runtime guarantees between hosts and toolkit-managed tools
+- [Tools and Accommodations Architecture](../../docs/tools-and-accomodations/architecture.md) - Tool design, scopes and activation
+- [Assessment toolkit in the architecture overview](../../docs/architecture/architecture.md#assessment-toolkit) - Where the toolkit sits among the players
 - [Section Player README](../section-player/README.md) - Section player integration
-- [Section Player Architecture](../section-player/ARCHITECTURE.md#layered-runtime-engine-post-m7) - Layered runtime engine, kernel/toolkit wiring, lifecycle emit invariant
+- [Section Player Architecture](../section-player/ARCHITECTURE.md#layered-runtime-engine) - Layered runtime engine, kernel/toolkit wiring, lifecycle emit invariant
 - [Framework-Owned Error Handling](../../docs/tools-and-accomodations/framework-owned-error-handling.md) - Canonical framework error model/events and fallback behavior
 - [Safe Custom Tool Configuration](../../docs/tools-and-accomodations/safe-custom-tool-config.md) - Host-side config patterns and validation guidance
 - [Architecture Overview](../../docs/architecture/architecture.md) - Complete system architecture