@pie-players/pie-assessment-toolkit 0.3.63 → 0.3.65

package/README.md

@@ -1047,6 +1047,40 @@ const alternative = resolver.getAlternative('prompt-001', {
 resolver.clearItemCatalogs();
 ```
 
+A resolved card carries either a string `content` (SSML for `spoken`, text for
+`braille`) or a structured `payload`, decided by its `catalog` type — never both.
+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:
+
+```typescript
+import {
+  catalogOwnerContextFor,
+  collectEntityCatalogRegistrations,
+} from '@pie-players/pie-assessment-toolkit';
+
+const context = catalogOwnerContextFor({
+  kind: 'item',
+  itemId: item.id,
+  canonicalItemId,
+  assessmentId,
+  sectionId,
+});
+
+// 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,
+});
+```
+
 ### SSMLExtractor
 
 ```typescript
@@ -1063,6 +1097,43 @@ item.config.extractedCatalogs = result.catalogs;
 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.
+
+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
+
+`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.
+
 ## Integration with Section Player
 
 The section player provides automatic ToolkitCoordinator integration:
@@ -1164,10 +1235,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({
@@ -1240,6 +1311,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-84nv78dy.js";import"./chunks/ItemToolBar-843902tp.js";export{a as default};
+import{a}from"./chunks/ItemToolBar-pryf0rtz.js";import"./chunks/ItemToolBar-cckwpz6c.js";export{a as default};