@pie-players/pie-assessment-toolkit 0.3.74 → 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
 
@@ -15,144 +43,52 @@ The examples build their tool registry with `createPackagedToolRegistry()` from
 in its own dependencies. The section player depends on it too, but strict
 installers such as pnpm expose only the packages a host declares.
 
-Server-backed TTS (`backend: "polly"`, `"google"` or `"server"`) loads
+Server-backed TTS (`backend: "server"`) loads
 `@pie-players/tts-client-server`, a dependency of
 `@pie-players/pie-default-tool-loaders` whose TTS registration imports it on
 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 } from '@pie-players/pie-default-tool-loaders';
-
-// Create one coordinator with configuration
-const toolRegistry = createPackagedToolRegistry();
-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-stage-change`
-- `pie-toolkit-runtime-owned`
-- `pie-toolkit-runtime-inherited`
-- `pie-toolkit-ready`
-- `pie-toolkit-section-ready`
-- `pie-toolkit-framework-error`
-
-Toolkit tool/backend operational stream:
+## Capabilities
 
-- `pie-tool-init-start|success|error`
-- `pie-tool-backend-call-start|success|error`
-- `pie-tool-library-load-start|success|error`
+- **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
 
-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.
+## 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, persistence, layout, backend
+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 tiers: easy attribute + sophisticated `runtime`
+## Configuration: attributes and a constructed coordinator
 
-This package and `@pie-players/pie-section-player` follow a deliberate
-two-tier configuration model. The same knob can usually be set in either
-tier; the choice is about ergonomics, not capability.
+This package and `@pie-players/pie-section-player` give each input one entry
+point (see [One tier per input](#one-tier-per-input)). A host that needs more
+than the element inputs builds the coordinator itself.
 
-### When to use each tier
+### Element inputs and a constructed coordinator
 
-- **Easy tier — top-level CE attributes / properties.** Use these for the
+- **Element attributes / properties.** Use these for the
   common cases that are static for the lifetime of the player or that hosts
   want to set declaratively in HTML / templating frameworks. Example:
 
@@ -164,13 +100,14 @@ tier; the choice is about ergonomics, not capability.
   ></pie-assessment-toolkit>
   ```
 
-- **Sophisticated tier — passing a constructed `ToolkitCoordinator` (or a
-  `runtime` object on consumer CEs).** Use this for advanced cases: composed
-  configuration, dynamic overrides, runtime mutation, fields without a
-  tier-1 attribute, or anything that benefits from being a single typed
+- **A constructed `ToolkitCoordinator` (or a
+  `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 { ToolkitCoordinator } from "@pie-players/pie-assessment-toolkit";
   import { createPackagedToolRegistry } from "@pie-players/pie-default-tool-loaders";
 
   const toolRegistry = createPackagedToolRegistry();
@@ -192,73 +129,77 @@ Top-level attributes use kebab-case (`assessment-id`,
 `tool-config-strictness`). Section-player runtime configuration is grouped
 under the `runtime` object instead of duplicated as top-level props.
 
-### Precedence rule
-
-The configuration object owns runtime fields. Section-player layout attributes
-cover identity, layout, diagnostics, and callback/event convenience:
+### One tier per input
 
-1. Use `runtime.<key>` for player, tool, accessibility, coordinator, env,
-   isolation, and runtime factories.
-2. Use top-level layout attributes for section identity and layout controls.
-3. Use documented defaults when neither is provided.
+Each input has one entry point. On the section-player layout elements,
+`runtime` carries `assessmentId`, the player, tool, accessibility,
+coordinator, env and isolation fields, runtime factories and the `on*`
+callbacks; attributes carry section identity, layout controls, `nds-icons`,
+`locale` and `tool-config-strictness`. Unset inputs take their documented
+defaults.
 
-### Canonical tier-1 attribute set
-
-The tier-1 attribute set is the same shape across
-`pie-assessment-toolkit`, `pie-section-player-base`, and the
-`pie-section-player-*` layout elements (locked in M5). Every tier-1
-surface obeys the strict mirror rule:
-
-```
-kebab-attribute  ↔  camelCaseProp  ↔  runtime.<sameCamelCaseKey>
-```
+`<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`.
 
-Common members include:
+### Canonical attribute set
 
-- Identity: `assessment-id`, `section-id`, `attempt-id`
-- Runtime config on section-player CEs: `runtime`
-- Toolkit-only object properties: `tools`, `tool-registry`, `coordinator`,
+- Identity: `assessment-id` on the toolkit, `section-id`, `attempt-id`
+- Runtime config on section-player custom elements: `runtime`
+- Toolkit-only object properties: `tools`, `toolRegistry`, `coordinator`,
   `accessibility`
-- Diagnostics: `tool-config-strictness`, `debug`. Framework-error
-  delivery is via the canonical `onFrameworkError` callback prop and the
-  `framework-error` DOM event dispatched on the layout CE host.
+- Interface: `nds-icons`, `locale`
+- 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 element.
 
-Documented exceptions to the mirror rule:
+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>`. `<pie-assessment-toolkit>`
-  itself keeps `createSectionController` and `isolation` as JS-only
-  props (no kebab-attribute surface): section-player layouts forward
-  `runtime.isolation` and `runtime.createSectionController` to the
-  wrapped toolkit via property bindings; standalone hosts that need
-  to override coordinator inheritance should pass an explicit
-  `coordinator={...}` instead.
+  `runtime.<key>`. Section-player layouts forward both to the wrapped
+  toolkit as properties. `<pie-assessment-toolkit>` keeps
+  `createSectionController` JS-only and takes `isolation` as an
+  attribute or a property. A `coordinator` passed to it wins over an
+  outer toolkit's.
 
-### When to add a tier-1 attribute
+### Adding an attribute (contributors)
 
-Add a tier-1 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
@@ -273,7 +214,7 @@ const coordinator = new ToolkitCoordinator({
   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: {
@@ -299,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({
@@ -320,10 +261,11 @@ 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.
+- A section's subscriptions receive `content-loaded` only for that section's renderables, live or replayed; the previous section's loads stay with it. A renderable in both sections, such as a passage that stays mounted across the switch, counts as loaded in each.
 - Subscribing the **same listener function** twice replaces the first subscription (filter args from the second call win).
 - A listener that throws is caught and `console.warn`-logged; the throw does not interrupt fan-out to other listeners.
 
@@ -331,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*` now throws if no active section cohort exists. 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
@@ -417,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');
@@ -425,92 +293,172 @@ const catalogResolver = new AccessibilityCatalogResolver([], 'en-US');
 await ttsService.initialize(new BrowserTTSProvider());
 ttsService.setCatalogResolver(catalogResolver);
 
-// Pass services individually
-player.ttsService = ttsService;
-player.toolCoordinator = toolCoordinator;
-// ...
+// Use them from host-built UI
 ```
 
+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. 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-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 pnp-enforcement="on">
-  <pie-item-toolbar item-id="q1"></pie-item-toolbar>
-  <pie-item-player></pie-item-player>
+<pie-assessment-toolkit>
+  <pie-item-scope item-id="q1">
+    <pie-item-toolbar></pie-item-toolbar>
+    <div data-region="content">
+      <pie-item-player></pie-item-player>
+    </div>
+  </pie-item-scope>
 </pie-assessment-toolkit>
 ```
 
+The host sets the toolkit's properties before the tree enters the document. A
+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();
 
-toolkit.tools = { placement: { item: ['calculator'] } };
+const toolkit = document.createElement('pie-assessment-toolkit');
+toolkit.tools = {
+  pnpEnforcement: 'on',
+  placement: { item: ['textToSpeech', 'calculator'] },
+};
 toolkit.toolRegistry = toolRegistry;
 toolkit.toolContextResolvers = toolContextResolvers;
 toolkit.assessment = { id: 'a1', personalNeedsProfile: { supports: ['calculator'] } };
 
-toolbar.item = item;
-toolbar.toolRegistry = toolRegistry; // the toolbar does not read the toolkit's
-toolbar.scopeElement = player; // the content answerEliminator acts on
+const scope = document.createElement('pie-item-scope');
+scope.setAttribute('item-id', 'q1');
+scope.item = item;
+scope.innerHTML = `
+  <pie-item-toolbar></pie-item-toolbar>
+  <div data-region="content"><pie-item-player></pie-item-player></div>
+`;
+
+toolkit.append(scope);
+container.append(toolkit);
 ```
 
-A registry built without `toolModuleLoaders` renders toolbar buttons whose tool
-elements never load. `textToSpeech` reads the region an item shell publishes,
-which only the section player's cards provide, so it has no reading target in
-this composition.
-
-A profile change is a new `assessment` value; the toolbars re-derive on the
-policy change it emits. Readiness events are section events: `toolkit-ready`,
-`section-ready` and every stage, `composed` included, wait for a bound section,
-and the toolkit builds its own coordinator only after it mounts. A host that needs a
-readiness point constructs the `ToolkitCoordinator`, passes it as
-`coordinator`, awaits `coordinator.waitUntilReady()`, and changes the profile
-with `coordinator.updateAssessment(...)`, since the toolkit applies its
-`assessment` property 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`. A section that arrives after one of those changed initializes
-with a coordinator rebuilt from the current values, and the toolbars move to
-it. After a section has initialized, a change to them is reported once in the
-console and does not reach the coordinator; `pnp-enforcement`, `assessment`,
-`currentItemRef` and `toolContextResolvers` apply to it at any time. That
-coordinator reports feature policy asked with no assessment bound only while
-`pnp-enforcement` is `on`: a toolkit given no `assessment` and no enforcement
-has asked for no accommodation.
+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, 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: {
@@ -529,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: {
@@ -558,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: {
@@ -585,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
 
@@ -614,17 +592,20 @@ 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 { ToolkitCoordinator } from '@pie-players/pie-assessment-toolkit';
 import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
 
 const toolRegistry = createPackagedToolRegistry();
@@ -661,44 +642,16 @@ const coordinator = new ToolkitCoordinator({
 });
 ```
 
-**Simple Default (All Tools Enabled):**
-
-For most use cases, simply enable all available tools:
+### Calculator providers
 
-```typescript
-import { createPackagedToolRegistry } from '@pie-players/pie-default-tool-loaders';
-
-const toolRegistry = createPackagedToolRegistry();
-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
@@ -736,7 +689,8 @@ tools: {
   providers: {
     textToSpeech: {
       enabled: true,
-      backend: 'polly'
+      backend: 'server',
+      serverProvider: 'polly'
     }
   }
 }
@@ -745,14 +699,15 @@ 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`.
 
 ### Inline TTS Speed Options
 
-Inline TTS speed buttons are configurable via `speedOptions` in provider settings.
+Inline TTS speed buttons are configurable via `speedOptions` on the provider config.
 
 ```typescript
 tools: {
@@ -760,9 +715,7 @@ tools: {
     textToSpeech: {
       enabled: true,
       backend: "browser",
-      settings: {
-        speedOptions: [2, 1.25, 1.5] // host options keep this order; Normal is added if omitted
-      }
+      speedOptions: [2, 1.25, 1.5] // host options keep this order; Normal is added if omitted
     }
   }
 }
@@ -779,13 +732,11 @@ tools: {
       enabled: true,
       backend: "server",
       serverProvider: "custom",
-      settings: {
-        speedOptions: [
-          { rate: 0.8, label: "Slow", ariaLabel: "Slow speed" },
-          { rate: 1, label: "Normal", ariaLabel: "Normal speed", default: true },
-          { rate: 1.5, label: "Fast", ariaLabel: "Fast speed" }
-        ]
-      }
+      speedOptions: [
+        { rate: 0.8, label: "Slow", ariaLabel: "Slow speed" },
+        { rate: 1, label: "Normal", ariaLabel: "Normal speed", default: true },
+        { rate: 1.5, label: "Fast", ariaLabel: "Fast speed" }
+      ]
     }
   }
 }
@@ -810,25 +761,15 @@ tools: {
 - Speed choices are exposed as a `Playback speed` radio group: one option is
   always selected, and choosing the already-selected speed is a no-op.
 - If only one speed option remains, the speed group is hidden by default. Set
-  `showSingleSpeedOption: true` in TTS settings to surface that one-option state.
-
-### Runtime Fallback: Server TTS -> Browser TTS
-
-When server-backed playback fails at runtime (for example `503`, network outage,
-or synthesized asset fetch failure), `TTSService` now performs a one-time
-runtime fallback for that session:
+  `showSingleSpeedOption: true` on the provider config to surface that one-option state.
 
-1. Switches provider from server-backed implementation to browser speech synthesis.
-2. Rebinds highlight callbacks to the browser provider.
-3. Retries the same `speak()` request once.
+### Browser Fallback
 
-This keeps the inline/passage TTS controls usable during transient backend
-incidents without requiring host-side reconfiguration.
-
-Telemetry emitted for observability:
-
-- `pie-tool-runtime-fallback` (fallback switch succeeded)
-- `pie-tool-runtime-fallback-error` (fallback switch failed)
+The coordinator owns fallback to browser speech. When a server-backed provider
+fails to initialize, the coordinator re-initializes TTS on the browser backend
+and reports `pie-tool-init-fallback`. `TTSService.initialize` itself rejects
+when its provider fails to start, and a playback failure after initialization
+rejects that read without switching provider.
 
 `provider.runtime.authFetcher` is optional. Add it only when your host environment
 requires runtime auth material for TTS requests:
@@ -838,7 +779,8 @@ tools: {
   providers: {
     textToSpeech: {
       enabled: true,
-      backend: 'polly',
+      backend: 'server',
+      serverProvider: 'polly',
       apiEndpoint: '/api/tts',
       provider: {
         runtime: {
@@ -858,10 +800,10 @@ provider config: a returned `authToken` is sent as `Authorization: Bearer <token
 and returned `headers` with every synthesis request, and under
 `includeAuthOnAssetFetch` the `Authorization` header also reaches the custom
 transport's speech-mark and audio fetches. A failed fetch falls back to browser
-speech and reports `pie-tool-init-error`.
+speech and reports `pie-tool-init-fallback`.
 
 For a server that authenticates by cookie on another origin, set `credentials:
-"include"` in the `textToSpeech` provider settings, beside
+"include"` on the `textToSpeech` provider config, beside
 `includeAuthOnAssetFetch`. The cookie reaches speech-mark and audio fetches only
 for origins in `assetOrigins`; unset, every TTS fetch keeps the browser default.
 
@@ -896,37 +838,44 @@ 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 Adapter (pie backend)
+## Test Attempt Session
 
-The toolkit exposes a canonical `TestAttemptSession` runtime and a deterministic adapter for pie backend activity payloads from `../../kds/pie-api-aws`.
+The toolkit exposes a canonical `TestAttemptSession` runtime. The host maps its
+backend's attempt payload into it and back out.
 
 ```typescript
 import {
-  mapActivityToTestAttemptSession,
+  createNewTestAttemptSession,
   toItemSessionsRecord,
-  buildActivitySessionPatchFromTestAttemptSession
+  upsertItemSessionFromPieSessionChange,
 } from "@pie-players/pie-assessment-toolkit";
 
-const testAttemptSession = mapActivityToTestAttemptSession({
-  activityDefinition,
-  activitySession
+let testAttemptSession = createNewTestAttemptSession({
+  testAttemptSessionIdentifier: attempt.id,
+  assessmentId: assessment.id,
+  seed: attempt.id,
+  itemIdentifiers: assessment.itemIdentifiers,
+});
+
+// Record a PIE session change against its item
+testAttemptSession = upsertItemSessionFromPieSessionChange(testAttemptSession, {
+  itemIdentifier: "q1",
+  pieSessionId: change.session.id,
+  session: change.session,
 });
 
 // Use in section-player handoff (same item session shape as item players expect)
 const itemSessions = toItemSessionsRecord(testAttemptSession);
-
-// Host-owned backend persistence payload
-const patch = buildActivitySessionPatchFromTestAttemptSession(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)
@@ -938,38 +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 QTI 3.0 PNP support
-- **ToolPolicyEngine**: QTI 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
-- **ThemeProvider**: Consistent accessibility theming
-
-### ✅ QTI 3.0 Standard Access Features
-
-- **95+ Standardized Features**: Complete QTI 3.0 / IMS AfA 3.0 accessibility features
-- **8 Feature Categories**: Visual, auditory, motor, cognitive, reading, navigation, linguistic, assessment
-- **Example Configurations**: Illustrative PNP profile examples (low vision, dyslexia, ADHD, etc.)
-- **Tool Mappings**: Every packaged tool registration maps to standard QTI 3.0 features
-
-### ✅ 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
@@ -987,12 +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' | 'polly' | 'google' | 'server';
+        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;
@@ -1008,68 +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
-// Get all services as a bundle
-const services = coordinator.getServiceBundle();
-// Returns: { ttsService, toolCoordinator, highlightCoordinator, elementToolStateStore, catalogResolver }
-
 // Tool configuration
-coordinator.isToolEnabled('textToSpeech');  // Check if tool is enabled
-coordinator.getToolConfig('textToSpeech');  // Get tool-specific config
-coordinator.updateToolConfig('textToSpeech', { rate: 1.5 });  // Update tool config
-
-// 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
@@ -1099,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
@@ -1108,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
@@ -1138,6 +1105,8 @@ unsubscribe();
 ### TTSService
 
 ```typescript
+import { BrowserTTSProvider, TTSService } from '@pie-players/pie-assessment-toolkit';
+
 const ttsService = new TTSService();
 
 // Initialize with provider
@@ -1146,8 +1115,8 @@ await ttsService.initialize(new BrowserTTSProvider());
 // Set catalog resolver for SSML support
 ttsService.setCatalogResolver(catalogResolver);
 
-// Playback
-await ttsService.speak('Read this text', {
+// Playback: reads an element or a range, or the named card in its place
+await ttsService.speak(promptElement, {
   catalogId: 'prompt-001',
   language: 'en-US'
 });
@@ -1166,36 +1135,47 @@ await ttsService.updateSettings({
 
 ### ToolCoordinator
 
-```typescript
-const toolCoordinator = new ToolCoordinator();
-
-// Register tools
-toolCoordinator.registerTool('calculator', 'Calculator', element);
+The toolkit owns the coordinator. A tool element registers with the one in its
+runtime context and hands it the element once it renders:
 
-// Manage visibility
-toolCoordinator.showTool('calculator');
-toolCoordinator.hideTool('calculator');
-toolCoordinator.toggleTool('calculator');
+```typescript
+import {
+  createToolCoordinatorRegistration,
+  ZIndexLayer,
+} from '@pie-players/pie-assessment-toolkit/tools/registration';
 
-// Z-index management
-toolCoordinator.bringToFront(element);
+const registration = createToolCoordinatorRegistration('Calculator', ZIndexLayer.TOOL);
 
-// Check state
-const isVisible = toolCoordinator.isToolVisible('calculator');
+// Re-registers when a republished context brings a new coordinator.
+$effect(() => registration.sync(coordinator, toolId));
+$effect(() => {
+  if (coordinator && containerEl && toolId) {
+    coordinator.updateToolElement(toolId, containerEl);
+  }
+});
+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. Disposing the toolkit coordinator releases every entry. Its
+debug lines print only under `window.PIE_DEBUG = true`.
+
 ### HighlightCoordinator
 
 ```typescript
+import { HighlightColor, HighlightCoordinator } from '@pie-players/pie-assessment-toolkit';
+
 const highlightCoordinator = new HighlightCoordinator();
 
 // TTS highlights (temporary)
-highlightCoordinator.highlightTTSWord(textNode, start, end);
+highlightCoordinator.highlightTTSWord([wordRange]); // one range per tree the word spans
 highlightCoordinator.highlightTTSSentence([range1, range2]);
 highlightCoordinator.clearTTS();
 
 // Annotation highlights (persistent)
-const id = highlightCoordinator.addAnnotation(range, 'yellow');
+const id = highlightCoordinator.addAnnotation(range, HighlightColor.YELLOW);
 highlightCoordinator.removeAnnotation(id);
 ```
 
@@ -1210,16 +1190,20 @@ 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
 
 ```typescript
+import { AccessibilityCatalogResolver } from '@pie-players/pie-assessment-toolkit';
+
 const resolver = new AccessibilityCatalogResolver(
   assessment.accessibilityCatalogs,
   'en-US'
@@ -1283,6 +1267,8 @@ such as TTS may still call `getAlternative(...)` with a context built by
 ### SSMLExtractor
 
 ```typescript
+import { SSMLExtractor } from '@pie-players/pie-assessment-toolkit';
+
 const extractor = new SSMLExtractor();
 
 // Extract from item config
@@ -1298,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
@@ -1313,25 +1296,20 @@ needs them — signing's card validators and its resolution rules live in
 
 ### Feature policy without a placement
 
-`ToolPolicyEngine.decideFeature(featureId)` (and
-`ToolkitCoordinator.decideFeaturePolicy(featureId)`) 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.
-
-`createEmptyPersonalNeedsProfile()` is the only profile this package ships, and it
-grants nothing. 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.
-
-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.
+`ToolPolicyEngine.decideFeature(featureId, scope?)` (and
+`ToolkitCoordinator.decideFeaturePolicy(featureId, scope?)`) resolve one feature id
+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.
+[Universal and empty profiles](../default-tool-loaders/README.md#universal-and-empty-profiles)
+covers the profiles `@pie-players/pie-default-tool-loaders` builds.
+
+Registry membership makes a tool policy-addressable; it grants nothing.
 
 ### Live registry changes
 
@@ -1378,21 +1356,27 @@ The section player provides automatic ToolkitCoordinator integration:
   // - Extracts services from coordinator
   // - Scopes its runtime engine to `section-id`
   // - Provides runtime context to child components
-  // - Manages SSML extraction
+  // - Registers item catalogs, including SSML catalogs a host extracted
+  //   into `config.extractedCatalogs` with `SSMLExtractor`
   // - Handles catalog lifecycle
 </script>
 ```
 
 ### Runtime Context Contract
 
-The toolkit now exports a shared context key used by section-player and toolkit
-components:
+Section-player and toolkit components share one runtime context. An element
+inside the toolkit's tree connects to it:
 
 ```typescript
 import {
-  assessmentToolkitRuntimeContext,
+  connectToolRuntimeContext,
   type AssessmentToolkitRuntimeContext
 } from "@pie-players/pie-assessment-toolkit";
+
+let runtime: AssessmentToolkitRuntimeContext | undefined;
+const disconnect = connectToolRuntimeContext(hostElement, (value) => {
+  runtime = value;
+});
 ```
 
 `AssessmentToolkitRuntimeContext` carries ambient orchestration dependencies
@@ -1422,7 +1406,7 @@ player.section = mySection;
 
 // Internally creates:
 // new ToolkitCoordinator({
-//   assessmentId: 'section-demo-direct', // or the assessment-id attribute
+//   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
 // })
@@ -1430,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:
 
@@ -1474,147 +1453,106 @@ const coordinator = new ToolkitCoordinator({
 Notes:
 - `providers.textToSpeech` is the canonical TTS provider key.
 - `providers.tts` is rejected by the validation contract.
-- Custom tools can provide provider-level `sanitizeConfig` and `validateConfig` hooks.
-- 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.
+- A tool registration can declare `sanitizeConfig` and `validateConfig` hooks for its `providers.<toolId>` entry.
 
-## Section Runtime Engine (advanced)
+## Instrumentation and Observability
 
-The toolkit exposes a layered **section runtime engine** that consolidates
-runtime resolution, FSM-driven stage progression, framework-error reporting,
-DOM-event fan-out, and instrumentation into a single object hosts can mount
-and dispose. The engine is what `<pie-section-player-…>` and
-`<pie-assessment-toolkit>` use internally, and it is also the surface
-custom hosts (or alternate layout shells) consume directly.
-
-### Two import paths
-
-The engine ships with two deliberately separate entry points so consumers
-pick the stability surface that matches their use case:
-
-- **Stable facade — `@pie-players/pie-assessment-toolkit/runtime/engine`.**
-  Narrow, semver-stable surface for hosts that want to mount, drive, and
-  dispose a section runtime. Re-exports `SectionRuntimeEngine`,
-  `SECTION_RUNTIME_ENGINE_KEY` (Svelte context), the cross-CE host
-  context (`sectionRuntimeEngineHostContext`), and the consumer-side
-  helper for that bridge (`connectSectionRuntimeEngineHostContext`).
-  The cross-CE host context exposes only a lifecycle handle; controller
-  methods stay on `SectionRuntimeEngine`.
-- **Internal surface — `@pie-players/pie-assessment-toolkit/runtime/internal`.**
-  Wider, evolving surface for advanced hosts that need to construct an
-  engine manually, inspect FSM state, or build alternate fan-out paths.
-  Exposes `SectionEngineCore`, the four adapter bridges
-  (`createDomEventBridge`, `createFrameworkErrorBridge`,
-  `createCoordinatorBridge`, `createInstrumentationBridge`),
-  `FrameworkErrorBus`, cohort helpers,
-  and the `resolveRuntime` / `resolveToolsConfig` /
-  `resolveSectionEngineRuntimeState` helpers. Symbols here may change
-  between minor versions with a changeset note.
+Toolkit instrumentation is provider-agnostic. It uses the shared
+`InstrumentationProvider` contract from `@pie-players/pie-players-shared`.
 
-## Writing a capability package
+### Injection Path
 
-`@pie-players/pie-assessment-toolkit/tools/internal` is what a capability
-package imports: the `ToolRegistration` contract, the `ToolProviderApi` its
-provider descriptor creates, the surface and content dependency types,
-`resolveToolTag` and the toolbar registration helpers. Same
-stability contract as the other `*/internal` entry points — symbols may change
-between minor versions with a changeset note.
+When the toolkit is hosted by a section or assessment player, the provider
+comes from the item-player loader config:
 
-Import it rather than the package root: the root pulls in `ToolkitCoordinator`,
-`TTSService` and the components, none of which a registration needs, and a
-capability bundle that inlines them ends up with a second `ToolRegistry` class
-that fails every `instanceof` across the host boundary. Mark the toolkit external
-in the package's build with a pattern that covers subpaths, not a bare specifier.
+- `runtime.player.loaderConfig.instrumentationProvider`
 
-`@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
-host-surface contracts.
+### 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.
 
-### Lifecycle emit coordination
-
-When `<pie-assessment-toolkit>` is nested inside a section-player layout,
-the layout kernel publishes a lifecycle handle via
-`sectionRuntimeEngineHostContext`. The toolkit detects that host
-lifecycle owner and **suppresses its own external lifecycle DOM emits
-and `onStageChange` callback** in favor of the layout CE host. From the
-outside, one cohort yields one `pie-stage-change` /
-`pie-loading-complete` chain on the layout CE host regardless of wrapper
-depth. Controller-side
-registration, content loading, session propagation, and persistence
-remain toolkit-local through its own `SectionRuntimeEngine` instance.
-A standalone `<pie-assessment-toolkit>` (no host context) emits from
-its own engine.
-
-**Detection.** If a custom layout shell emits two `pie-stage-change`
-events per stage transition (or two `pie-loading-complete` per cohort)
-on the same layout CE — typically with two distinct `detail.runtimeId`
-values — the shell has not published its engine via
-`sectionRuntimeEngineHostContext`, so the wrapped
-`<pie-assessment-toolkit>` falls back to its standalone lifecycle emit
-path. Wire the bridge as shown below.
+### 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 (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
+announces with `toolkit-ready`, and the toolkit publishes framework errors.
+
+### Entry point
+
+`@pie-players/pie-assessment-toolkit/runtime/engine` is the stable entry for a
+host that drives a section's stage chain. It carries `SectionRuntimeEngine` and
+the vocabulary of its surface: the `SectionEngineInput`s `dispatchInput` takes,
+the `SectionEngineOutput`s `subscribe` delivers, the `SectionEngineState` and
+`SectionEnginePhase` `getState` returns, the cohort helpers (`makeCohort`,
+`cohortsEqual`), the runtime config types with
+`resolveSectionEngineRuntimeState`, and the readiness signals. The engine core, its adapter and its DOM bridge have no
+entry: a host reaches them through the facade.
+
+### Stage chain
+
+A cohort moves through `composed`, `engine-ready` and `interactive`, and ends at
+`disposed` on a cohort change or unmount. `engine-ready` follows the
+`section-controller-resolved` input, `interactive` the readiness signals that
+satisfy the readiness mode. A readiness update that reports `runtimeError`
+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, 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 directly — the section-player
-layout CE and the toolkit CE handle it. Use the facade only when
-building an alternate layout shell (e.g. a custom kernel host). The
-shape mirrors what the section-player kernel does internally:
+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` ([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:
 
 ```ts
-import { ContextProvider } from "@pie-players/pie-context";
 import {
   SectionRuntimeEngine,
-  sectionRuntimeEngineHostContext,
-} from "@pie-players/pie-assessment-toolkit/runtime/engine";
-import {
-  FrameworkErrorBus,
   makeCohort,
-} from "@pie-players/pie-assessment-toolkit/runtime/internal";
+} from "@pie-players/pie-assessment-toolkit/runtime/engine";
 
-const bus = new FrameworkErrorBus();
 const engine = new SectionRuntimeEngine();
 
-// 1. Attach to the layout CE host. `sourceCe` is stamped onto every
-//    DOM event the engine dispatches and is required.
-engine.attachHost({
-  host: layoutHostElement,
-  sourceCe: "my-custom-layout",
-  frameworkErrorBus: bus,
-  coordinator: toolkitCoordinator,
-});
-
-// 2. Publish a lifecycle handle on the layout CE host so any wrapped
-//    <pie-assessment-toolkit> suppresses duplicate external lifecycle
-//    emits. The toolkit still owns its controller registration/session
-//    plumbing locally.
-const engineProvider = new ContextProvider(layoutHostElement, {
-  context: sectionRuntimeEngineHostContext,
-  initialValue: {
-    engine: {
-      getRuntimeId: () => engine.getRuntimeId(),
-    },
-  },
-});
-engineProvider.connect();
+// 1. Attach to the layout host. `sourceCe` is stamped onto every event.
+engine.attachHost({ host: layoutHostElement, sourceCe: "my-custom-layout" });
 
-// 3. (Optional) Subscribe to the structured output stream — same set
-//    of outputs the DOM-event bridge fans out to the host element.
-engine.subscribe((output) => {
-  // tap stage transitions, readiness updates, framework errors,
-  // instrumentation events
+// 2. (Optional) Subscribe to the output batches the DOM bridge dispatches.
+engine.subscribe((outputs) => {
+  // `stage-change` and `loading-complete` outputs
 });
 
-// 4. Drive the engine. Use real `SectionEngineInput` shapes:
+// 3. Drive the engine with `SectionEngineInput`s.
 const cohort = makeCohort({ sectionId, attemptId });
 engine.dispatchInput({
   kind: "initialize",
@@ -1624,7 +1562,10 @@ engine.dispatchInput({
   itemCount,
 });
 
-// On loading-progress / readiness signal updates:
+// When the toolkit's `section-ready` delivers the cohort's section controller:
+engine.dispatchInput({ kind: "section-controller-resolved" });
+
+// On readiness signal updates:
 engine.dispatchInput({
   kind: "update-readiness-signals",
   signals: {
@@ -1633,46 +1574,58 @@ engine.dispatchInput({
     allLoadingComplete,
     runtimeError,
   },
-  loadedCount,
   itemCount,
   mode: "progressive",
 });
 
-// On unmount:
-engineProvider.disconnect();
+// On unmount; emits `disposed` for the active cohort.
 engine.dispose();
 ```
 
-The DOM events `pie-stage-change`, `pie-loading-complete`, and
-`framework-error` are dispatched on `host` automatically by the
-adapter's `dom-event-bridge`. The canonical `onFrameworkError` callback
-prop and the package-internal `FrameworkErrorBus` deliver each error
-exactly once regardless of wrapper depth. The `framework-error` DOM
-event on the layout CE host also delivers each error exactly once: the
-section-player kernel intercepts the toolkit's bubbled emit at
-`<pie-section-player-base>` and calls `event.stopPropagation()`, so the
-layout host sees only the canonical engine-bridge emit. Direct
-listeners on `<pie-assessment-toolkit>` itself still see the toolkit's
-own emit (the toolkit dispatch reaches them before the kernel listener
-runs). A coordinator the host passes in reports through the same
-surfaces. `packages/section-player/tests/section-player-event-delivery.spec.ts`
-pins these counts.
-The layout host emits one `framework-error` DOM event per framework error.
+The adapter dispatches `pie-stage-change` and `pie-loading-complete` on `host`,
+bubbling and composed, as the toolkit dispatches its own events. Framework
+errors are not an engine output. The toolkit that owns the coordinator publishes
+each one once: one bubbling, composed `framework-error` event, which reaches the
+layout host and `document`, and one `onFrameworkError` call. A coordinator the
+host passes in reports through the same surfaces.
+`packages/section-player/tests/section-player-event-delivery.spec.ts` pins these
+counts.
 
-Hosts should listen to `pie-stage-change` (with the readiness detail also
-available via the kernel's `selectReadiness()`) and `pie-loading-complete`.
+## Writing a capability package
 
-## State Separation: Tool State vs Session Data
+`@pie-players/pie-assessment-toolkit/tools/registration` is the stable entry a
+capability package imports: the `ToolRegistration` contract, the
+`ToolProviderApi` its provider descriptor creates, the surface and content
+dependency types, the context predicates, `createToolElement`, `resolveToolTag`
+and the toolbar registration helpers. A renderer that puts registrations on
+screen uses the same entry for `createToolSurfaceHost` and
+`resolveContentCapabilities`.
 
-The toolkit enforces a clear separation between ephemeral tool state and persistent session data:
+Import it rather than the package root: the root pulls in `ToolkitCoordinator`,
+`TTSService` and the components, none of which a registration needs, and a
+capability bundle that inlines them ends up with a second `ToolRegistry` class
+that fails every `instanceof` across the host boundary. Mark the toolkit external
+in the package's build with a pattern that covers subpaths, not a bare specifier.
 
-### Tool State (Ephemeral - ElementToolStateStore)
+`@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. 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
+
+The toolkit keeps tool state and PIE session data in separate stores.
 
-**Client-only**, never sent to server for scoring:
+### Tool state (ElementToolStateStore)
+
+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"]
     },
@@ -1689,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
 {
@@ -1711,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
 
@@ -1725,8 +1674,7 @@ Full TypeScript definitions included:
 import type {
   ToolkitCoordinatorApi,
   ElementToolStateStoreApi,
-  ToolkitCoordinatorConfig,
-  ToolkitServiceBundle
+  ToolkitCoordinatorConfig
 } from '@pie-players/pie-assessment-toolkit';
 ```
 
@@ -1740,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 QTI 3.0 PNP 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