@pie-players/pie-players-shared
v0.3.73
Published
Shared runtime + UI utilities for PIE players
Readme
PIE Players Shared
Shared runtime utilities for the @pie-players/* player suite. This package is
for framework code and host integrations that need the same loader, PIE config,
security, object, i18n, or type helpers used by the player packages.
Public Exports
import { safeLocalStorageGet } from "@pie-players/pie-players-shared";
import { makeUniqueTags } from "@pie-players/pie-players-shared/pie";
import { normalizeItemPlayerStrategy } from "@pie-players/pie-players-shared";Supported subpaths are declared in package.json:
@pie-players/pie-players-shared@pie-players/pie-players-shared/loader-config@pie-players/pie-players-shared/security@pie-players/pie-players-shared/object@pie-players/pie-players-shared/types@pie-players/pie-players-shared/formative@pie-players/pie-players-shared/timed-media@pie-players/pie-players-shared/pie@pie-players/pie-players-shared/pie/tag-names@pie-players/pie-players-shared/loaders@pie-players/pie-players-shared/server/npm-registry@pie-players/pie-players-shared/i18n
Formative Delivery
@pie-players/pie-players-shared/formative holds the policy resolution, outcome
aggregation, Try-state reducer, item view, and mastery rollup that
pie-section-player drives. It is pure — no DOM, no timers, no element registry
— so it is testable without a browser and importable by an adapter that has no
player.
import {
aggregateFormativeOutcome,
resolveFormativePolicy,
resolveFormativeItemView,
rollupFormativeMastery,
} from "@pie-players/pie-players-shared/formative";The authored half — FormativeDeliveryPolicy on AssessmentSection and
FormativeItemPolicy on AssessmentItemRef — is re-exported from the package
root and from /types, beside the section types it annotates.
The contract is docs/prds/formative-delivery-contract.md,
including the QTI 3 mapping and why PIE says Try rather than "attempt".
Timed Media
@pie-players/pie-players-shared/timed-media holds the timed-media section
vocabulary, its validation, the cue reduction, the session slice, and the Media
Time Source port that a section reaches media through. Pure apart from
createMediaElementTimeSource, which is inert until called, so the contract stays
importable in Node beside the rest.
import {
createMediaElementTimeSource,
normalizeTimedMediaSectionData,
reduceTimedMediaState,
resolveTimedMediaProjection,
type MediaTimeSource,
} from "@pie-players/pie-players-shared/timed-media";The port is shaped after HTMLMediaElement on purpose — a native <video>
satisfies it through the adapter above — with two departures: seeking is
seekTo(seconds) rather than a writable currentTime, and capabilities declares
canPause / canRestrictSeeking, because a source that cannot control playback
needs a way to say so. A host implementing the port directly needs no PIE element to
deliver timed media.
The authored half — sectionType and timedMedia on AssessmentSection — is
re-exported from the package root and from /types, beside the section types it
annotates.
The contract is docs/prds/timed-media-section-contract.md,
including why cue gate conditions name the formative vocabulary and why an
unenforceable policy degrades to advisory rather than failing closed.
Browser ESM Element Contract
The canonical producer-side contract lives with the pie-elements-ng package
contract. The loader assumptions here must stay aligned with that producer
surface.
The ESM element loader consumes static @pie-element/* browser entries such as
dist/browser/delivery/index.js; it does not transform element packages through
CDN +esm entry points. Browser ESM elements must publish exact shared runtime
metadata in package.json under pie.browserSharedDependencies.
jsDelivr is the default npm CDN provider. Hosts can opt into esm.sh with
loaderOptions.esmCdnProvider = "esm.sh" and loaderOptions.esmCdnUrl =
"https://esm.sh". For esm.sh, PIE package artifacts are loaded from
raw.esm.sh while shared browser dependencies are loaded from esm.sh.
Provider names are open-ended: custom/internal providers can pass their own name
when they follow the jsDelivr-compatible package-file URL layout, or pass a
provider object when package artifacts and shared dependencies need different
route builders.
dependencies and peerDependencies are not used as fallback runtime contracts.
If multiple elements request different minor or patch versions of a shared
singleton such as React, the loader chooses the highest same-major version and
emits console plus instrumentation warnings. Different major versions fail the
load and are also reported through console and instrumentation.
Preloaded mode means the host has already registered the expected custom element tag; it is not a separate package format. IIFE mode remains supported through the same package exports and controller compatibility shim used by legacy builders.