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

package/README.md

@@ -235,7 +235,7 @@ const coordinator = new ToolkitCoordinator({
   assessmentId: 'demo-assessment',
   tools: {
     providers: {
-      textToSpeech: { enabled: true, backend: 'browser', defaultVoice: 'en-US' },
+      textToSpeech: { enabled: true, backend: 'browser' },
       calculator: { enabled: true }
     },
     placement: {
@@ -418,7 +418,7 @@ tools: {
   },
   providers: {
     calculator: { authFetcher: async () => ({ apiKey: '...' }) },
-    textToSpeech: { enabled: true, backend: 'browser', defaultVoice: 'en-US' }
+    textToSpeech: { enabled: true, backend: 'browser' }
   }
 }
 ```
@@ -1053,34 +1053,42 @@ Consumers select by type and then validate the form they expect; a card with no
 string form is not text content, and treating it as such would speak or render an
 empty string.
 
-Catalogs registered for a rendered item or passage are filed under a
-`CatalogOwnerContext`, which the resolver matches field by field. Build lookup
-contexts with `catalogOwnerContextFor` rather than as a literal — it is the same
-function the runtime registers with, so the two cannot drift:
+Catalogs carried by a rendered item or passage are registered as one owner-level
+transaction. The resolver owns the walk over entity-root,
+`config.extractedCatalogs`, and model catalogs, along with their registration
+precedence and change notification:
 
 ```typescript
 import {
   catalogOwnerContextFor,
-  collectEntityCatalogRegistrations,
 } from '@pie-players/pie-assessment-toolkit';
 
-const context = catalogOwnerContextFor({
+const owner = {
   kind: 'item',
   itemId: item.id,
   canonicalItemId,
   assessmentId,
   sectionId,
-});
+} as const;
 
-// Every catalog an entity carries, paired with the scope it belongs in:
-// entity-level `accessibilityCatalogs`, `config.extractedCatalogs`, and each
-// model's own catalogs (filed under that `modelId`).
-const registrations = collectEntityCatalogRegistrations(item, {
-  kind: 'item',
-  itemId: item.id,
+const unregister = resolver.registerOwner({ owner, entity: item });
+const ownerView = resolver.forOwner(catalogOwnerContextFor(owner));
+
+const stopObserving = ownerView.onChange(() => {
+  const snapshot = ownerView.snapshot();
+  // Interpret only the card types your capability owns.
 });
+
+stopObserving();
+unregister();
 ```
 
+`CatalogOwnerSnapshot` is immutable and deterministic. A content capability
+receives it as `ToolContentDependencyContext.catalogs`; it does not receive the
+raw entity, resolver, or separately assembled lookup context. Direct consumers
+such as TTS may still call `getAlternative(...)` with a context built by
+`catalogOwnerContextFor`.
+
 ### SSMLExtractor
 
 ```typescript
@@ -1097,20 +1105,20 @@ item.config.extractedCatalogs = result.catalogs;
 catalogResolver.addItemCatalogs(result.catalogs);
 ```
 
-### Sign-language cards
+### Cards without an extractor
 
-Signed alternates have no extractor and deliberately so: a `sign-language` card is
-authored or written by an importer, never lifted out of item markup at render
-time. One such lift existed and was removed — 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.
+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.
 
-Whether a card describes a playable signed alternate is decided in one place,
-`resolveSignLanguageMedia` — a payload with no usable source resolves to `null`
-rather than rendering an empty player, and source URLs are restricted to schemes
-a media element can actually fetch. `matchesRequestedSignLanguage` holds the
-deliberate strictness: there is no cross-sign-language substitution, since
-handing an ASL learner a BSL recording is worse than handing them nothing.
+This package resolves and registers those cards through
+`AccessibilityCatalogResolver` and the generic media helpers in
+`catalog-media.ts`. Which card types mean what belongs to the capability that
+needs them — signing's card validators and its resolution rules live in
+`@pie-players/pie-tool-sign-language`, behind that capability's
+`requiresAuthoredContent`.
 
 ### Feature policy without a placement
 
@@ -1121,10 +1129,28 @@ placement. Use it for capabilities that are not toolbar surfaces — signing is
 first — where a placement-scoped `decide(...)` would answer the wrong question:
 absent because it was never placed, rather than absent because policy said no.
 
-`computeDefaultSupports()` excludes `ACCOMMODATION_ONLY_SUPPORT_IDS`, which lists
-`signLanguage`. The computed default profile derives from every registered tool's
-`pnpSupportIds`, which is right for universal features and wrong for an
-accommodation requiring a documented need.
+`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.
+
+### Live registry changes
+
+`ToolRegistry.onRegistryChange(listener)` observes successful `register`,
+`override`, `unregister`, `clear`, component-override, and module-loader
+changes synchronously. Invalid and no-op mutations do not emit, listener
+failures do not interrupt other listeners, and unsubscribe is idempotent.
+Section-player subscribes internally, so a capability registered after mount
+appears without a host-forced rerender; unregister and clear destroy their
+mounted surface elements immediately.
 
 ## Integration with Section Player
 
@@ -1227,10 +1253,10 @@ Use `createToolsConfig()` when you want to pre-validate and inspect diagnostics
 
 ```typescript
 import {
-  createPackagedToolRegistry,
   createToolsConfig,
   ToolkitCoordinator
 } from "@pie-players/pie-assessment-toolkit";
+import { createPackagedToolRegistry } from "@pie-players/pie-default-tool-loaders";
 
 const toolRegistry = createPackagedToolRegistry();
 const { config, diagnostics } = createToolsConfig({
@@ -1267,7 +1293,9 @@ Notes:
   `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"`) for tool- or provider-specific handling.
+	`"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.
 
 ## Section Runtime Engine (advanced)
@@ -1303,6 +1331,26 @@ pick the stability surface that matches their use case:
   `resolveSectionEngineRuntimeState` helpers. Symbols here may change
   between minor versions with a changeset note.
 
+## Writing a capability package
+
+`@pie-players/pie-assessment-toolkit/tools/internal` is what a capability
+package imports: the `ToolRegistration` contract, 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.
+
+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.
+
+`@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.
+
 ### Lifecycle emit coordination
 
 When `<pie-assessment-toolkit>` is nested inside a section-player layout,

package/dist/components/ItemToolBar.custom-element.js

@@ -1 +1 @@
-import{a}from"./chunks/ItemToolBar-7rq2gj8b.js";import"./chunks/ItemToolBar-3cppre9r.js";export{a as default};
+import{a}from"./chunks/ItemToolBar-cvs646j3.js";import"./chunks/ItemToolBar-8jgdz50p.js";export{a as default};