@pie-players/pie-tool-sign-language 0.3.50

package/README.md

@@ -0,0 +1,83 @@
+# @pie-players/pie-tool-sign-language
+
+The sign-language accommodation for PIE assessment players: a signed translation
+of an item, docked beside its content.
+
+This package is also the worked example of a capability contributed entirely from
+outside the player. It is authored against
+`@pie-players/pie-assessment-toolkit/tools/internal` — the same entry point the
+packaged registrations use — and `@pie-players/pie-section-player` reaches it only
+through `ToolRegistry.getToolsBySurface("content-media")`. No package in the player
+names signing, the `signLanguage` support id, the `sign-language` catalog type or
+this package.
+
+## Opting in
+
+```ts
+import { signLanguageRegistration } from "@pie-players/pie-tool-sign-language";
+
+registry.register(signLanguageRegistration);
+```
+
+Importing the package registers the `pie-tool-sign-language` element, so there is
+nothing else to wire and no module-loader entry to add.
+
+Signing is deliberately absent from `createPackagedToolRegistry` and
+`DEFAULT_TOOL_MODULE_LOADERS`. It is an accommodation with an authored-content
+dependency: a default that granted it would hand the accommodation to every
+learner whose item happened to carry a card.
+
+## Availability
+
+Two independent halves, both required, neither implying the other.
+
+**Eligibility** — policy granted `signLanguage`. Signing is an accommodation, so
+silence means no. The host asks `decideFeaturePolicy` and never consults tool
+placement: `activation: "region"` means there is no button to press, so a
+`tools.placement` entry naming this capability is reported as unplaceable rather
+than silently doing nothing.
+
+**Content** — the item carries a matching `sign-language` catalog card. QTI
+approximates AfA's DRD in-band: the presence of the card *is* the resource
+declaration. This half is `requiresAuthoredContent.resolve`, and it is why a
+learner with the accommodation still sees nothing on the vast majority of items.
+
+A signed alternate reaches an item one way only: as a catalog card, authored or
+written by an importer. There is no path that lifts a signing video out of item
+markup at render time — one was implemented and removed, because it had no
+producer and failed in the wrong direction, leaving the video in visible content
+for every learner when the markup could not be parsed.
+
+## No cross-sign-language substitution
+
+ASL, BSL and LSF are not interchangeable. The catalog resolver's last fallback
+rung matches any card of the requested type regardless of language, which helps
+for spoken audio and harms here: handing an ASL learner a BSL recording is worse
+than handing them nothing. `resolveSignLanguageAlternate` therefore accepts a
+card reached by that rung only when its language matches, or when the card
+asserts no language at all.
+
+## The element
+
+`<pie-tool-sign-language>` — open shadow root, mounted by the registration's
+`renderSurface`, never authored directly. Props are `media` (a resolved
+alternate) and `ttsService`; signing playback and read-aloud pause each other, and
+the action the learner just took wins.
+
+Sizing is driven by the recording's own frame shape, because signing needs height
+for hands and face. Host overrides:
+
+| Custom property | Default |
+| --- | --- |
+| `--pie-section-player-item-media-aspect-ratio` | `3 / 4` |
+| `--pie-section-player-item-media-min-height` | `220px` |
+| `--pie-section-player-item-media-max-height` | `60vh` |
+
+The region's share of the card width, the drag-to-resize handle and the stacking
+breakpoint belong to the host: that is the card's layout, not the capability's.
+
+## Related
+
+- [`docs/prds/sign-language-asl-support.md`](../../docs/prds/sign-language-asl-support.md)
+- [`docs/TOOL_REGISTRY.md`](../assessment-toolkit/docs/TOOL_REGISTRY.md) — host
+  surfaces and content dependencies

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CONTENT_MEDIA_SURFACE, SIGN_LANGUAGE_ELEMENT_TAG, signLanguageRegistration, } from './src/sign-language-registration.js';
+export type { SignLanguageMedia } from './src/sign-language-cards.js';
+export { AMERICAN_SIGN_LANGUAGE, describeSignLanguage, isSignLanguageCard, matchesRequestedSignLanguage, resolveSignLanguageMedia, SIGN_LANGUAGE_CATALOG_TYPE, } from './src/sign-language-cards.js';
+export type { ResolvedSignLanguageAlternate, SignLanguageCatalogRef, SignLanguageLookupArgs, } from './src/sign-language-content.js';
+export { collectSignLanguageCatalogRefs, resolveRequestedSignLanguage, resolveSignLanguageAlternate, resolveSignLanguageContent, SIGN_LANGUAGE_FEATURE_ID, } from './src/sign-language-content.js';

package/dist/src/sign-language-cards.d.ts

@@ -0,0 +1,52 @@
+import { CatalogCard, CatalogCardPayload, MediaFragmentRange, MediaSource } from '@pie-players/pie-players-shared/types';
+/** Catalog type token for signed alternates. Matches QTI 3's `support` value. */
+export declare const SIGN_LANGUAGE_CATALOG_TYPE = "sign-language";
+/** ISO 639-3 code for American Sign Language, and QTI 3's `xml:lang` value. */
+export declare const AMERICAN_SIGN_LANGUAGE = "ase";
+export declare function describeSignLanguage(signLang?: string): string;
+/**
+ * A validated signed alternate, flattened for rendering.
+ *
+ * `signLang` is optional because a card need not assert a language. Callers
+ * decide what to do with an unknown one; see `matchesRequestedSignLanguage`.
+ */
+export interface SignLanguageMedia {
+    signLang?: string;
+    sources: MediaSource[];
+    poster?: string;
+    label?: string;
+    fragment?: MediaFragmentRange;
+}
+type SignLanguageCardLike = {
+    language?: string;
+    content?: string;
+    payload?: CatalogCardPayload;
+};
+/**
+ * Validate a `sign-language` card into something renderable, or `null`.
+ *
+ * Returns `null` — meaning "this card is absent" — when the payload yields no
+ * usable source. Never returns a partially-valid result that would render an
+ * empty player.
+ *
+ * A payload that carries sources but no `signLang` falls back to the card's
+ * `language`, and then to unlabelled. Language *matching* is a separate
+ * decision (see `matchesRequestedSignLanguage`) so the strict
+ * no-cross-sign-language rule lives in exactly one place.
+ */
+export declare function resolveSignLanguageMedia(card: SignLanguageCardLike | null | undefined): SignLanguageMedia | null;
+/**
+ * Whether a resolved signed alternate may be shown for a requested sign
+ * language.
+ *
+ * Deliberately strict: there is no cross-sign-language fallback. ASL, BSL and
+ * LSF are not interchangeable, so showing a different sign language than the
+ * one requested would hand a learner a language they may not follow — worse
+ * than showing nothing. A card that asserts *no* language is accepted, because it
+ * cannot be shown to be a mismatch — only a positive claim of another language
+ * is refused.
+ */
+export declare function matchesRequestedSignLanguage(media: SignLanguageMedia, requestedSignLang: string): boolean;
+/** Whether a catalog card is a sign-language card at all. */
+export declare function isSignLanguageCard(card: CatalogCard): boolean;
+export {};

package/dist/src/sign-language-content.d.ts

@@ -0,0 +1,73 @@
+import { CatalogOwnerContext, AccessibilityCatalogResolverApi, ToolContentDependencyContext } from '@pie-players/pie-assessment-toolkit';
+import { ItemEntity } from '@pie-players/pie-players-shared/types';
+import { SignLanguageMedia } from './sign-language-cards.js';
+/** QTI 3.0 / AfA support id gating signed alternates. */
+export declare const SIGN_LANGUAGE_FEATURE_ID = "signLanguage";
+/** A catalog on this item that carries at least one sign-language card. */
+export interface SignLanguageCatalogRef {
+    catalogId: string;
+    /** Set when the catalog is owned by one model rather than the item root. */
+    modelId?: string;
+}
+export interface ResolvedSignLanguageAlternate extends SignLanguageMedia {
+    catalogId: string;
+}
+/**
+ * Collect the catalog identifiers on an item that carry signing cards.
+ *
+ * The region resolves through the catalog resolver, but the resolver is keyed by
+ * identifier within an owner scope — something has to say *which* identifiers
+ * this item put in play, and whether each belongs to the item or to one model.
+ * That is the same walk the runtime does when it registers an item's catalogs,
+ * so it is borrowed rather than repeated: a ref can only name a scope
+ * registration actually files under. Only the "does this catalog carry signing"
+ * filter is ours.
+ *
+ * The owner identity here is a placeholder: the assessment and section ids are
+ * not known at extraction time and are supplied by the caller at lookup time
+ * (see `resolveSignLanguageAlternate`). Nothing but `modelId` is read from the
+ * walk's contexts.
+ */
+export declare function collectSignLanguageCatalogRefs(item: ItemEntity | null | undefined): SignLanguageCatalogRef[];
+export interface SignLanguageLookupArgs {
+    resolver: AccessibilityCatalogResolverApi;
+    refs: SignLanguageCatalogRef[];
+    /** Owner context for the item, without `modelId` — added per ref. */
+    ownerContext: CatalogOwnerContext;
+    /** Sign language the learner is entitled to, ISO 639-3. */
+    requestedSignLang?: string;
+}
+/**
+ * Resolve the signed alternate to show for an item, or `null`.
+ *
+ * Priority, language fallback and owner scoping are the resolver's job and are
+ * not re-implemented here. What *is* enforced here is the one deliberate
+ * departure from the resolver's default behaviour: **no cross-sign-language
+ * substitution.** The resolver's last fallback rung matches any card of the
+ * requested type regardless of language, which for spoken content is helpful
+ * and for signing is not — handing an ASL learner a BSL recording is worse than
+ * handing them nothing. So a card the resolver returns by that rung is accepted
+ * only if its language actually matches, or if the card asserts no language at
+ * all.
+ *
+ * MVP takes the first resolvable card: sample content is one recording per item.
+ * The refs stay per-node capable for when choice-level docking lands.
+ */
+export declare function resolveSignLanguageAlternate(args: SignLanguageLookupArgs): ResolvedSignLanguageAlternate | null;
+/**
+ * Which sign language the learner is entitled to.
+ *
+ * Read from the feature's policy parameters (`toolParameters` / `toolConfigs`),
+ * never inferred from the item's content language — a Spanish item's signed
+ * alternate is LSM, not ASL.
+ */
+export declare function resolveRequestedSignLanguage(parameters: unknown): string | undefined;
+/**
+ * The registration's `requiresAuthoredContent` implementation: the whole
+ * content half behind the one call the host makes.
+ *
+ * The host supplies the item, the resolver and the owner scope, and learns only
+ * whether there is something to render. It never sees a catalog type, a card
+ * shape or a sign-language code.
+ */
+export declare function resolveSignLanguageContent(context: ToolContentDependencyContext): ResolvedSignLanguageAlternate | null;

package/dist/src/sign-language-registration.d.ts

@@ -0,0 +1,12 @@
+import { ToolRegistration } from '@pie-players/pie-assessment-toolkit/tools/internal';
+/**
+ * Host surface this capability docks into: media beside a card's content.
+ *
+ * Item cards and passage cards open the same surface, so declaring it once
+ * reaches both. A signed alternate is authored against a content node, and a
+ * passage owns content nodes as an item does.
+ */
+export declare const CONTENT_MEDIA_SURFACE = "content-media";
+/** Element tag this package registers. A host may substitute its own. */
+export declare const SIGN_LANGUAGE_ELEMENT_TAG = "pie-tool-sign-language";
+export declare const signLanguageRegistration: ToolRegistration;