Packages and entry points

This page is for hosts choosing what to install. It lists every published @pie-players/* package by job, says which entry points run in Node.js, which load raw in a browser and which need a bundler, and gives the Node.js and TypeScript settings the packages require. Versioning and stability covers versions and pinning.

Requirements

• Node.js 20 or later. Every package declares engines.node >=20.0.0.
• TypeScript moduleResolution bundler, node16 or nodenext, for a host that type-checks against the published declarations (see TypeScript).
• One exact version for every @pie-players/* package (pinning).

Hosts install no Svelte. The players and tools bundle their UI runtime (Svelte 5; Lit for the print player), no package declares a peer dependency, and no published declaration imports svelte.

Choosing packages

Package catalog

Each package name links to its README. @pie-players/pie-preloaded-player is published separately, outside the lockstep set (preloaded player).

Players

Toolkit and shared runtime

Tools

Each tool package registers one custom element. The tool id is the name a tool configuration and a toolbar placement use.

Calculator providers

Text-to-speech

Development panels

These panels inspect a running player during development.

The item player's ./components/item-session-debugger-element entry registers <pie-item-player-session-debugger>, the item-level session panel.

Entry points

A package's entry points are the subpaths in its exports map (public surface). Each falls in one of three classes.

Node-safe

These import in Node.js without a DOM, for example in a server or during server-side rendering. A release gate imports each one in plain Node.js from the packed tarball.

@pie-players/tts-server-sc imports in Node.js as well, but the gate does not test it. Treat every entry point outside this table as browser code.

Browser, raw from a CDN

These import no bare specifier, so a page loads them through <script type="module"> with no bundler and no import map. Loading from a CDN covers loading them; a bundler loads them too.

Browser, through a bundler

Every other entry point loads in a browser through a bundler, for example import "@pie-players/pie-section-player";. These entries import their @pie-players/* siblings and speech-rule-engine by bare specifier, and the toolkit's text-to-speech service loads the engine's JSON locale tables with an import() that carries no import attributes. A browser resolves neither without a bundler, and both Node.js and browsers refuse a JSON module imported without with { type: "json" }. The class includes:

• the section player's root, its npm build;
• the item list's root, which imports the item player by bare specifier;
• the assessment player;
• the toolkit's custom-element entries (./components/*);
• every tool package.

The release gate confirms that the item player's and section player's roots fail to import in Node.js on a browser global.

A CDN URL without a file path serves the file a package's unpkg and jsdelivr fields name. For the section player that file is the npm build, so a page names dist/browser/pie-section-player.js in full, and the item list dist/browser/pie-item-list.js.

Third-party dependencies

Beyond their @pie-players/* siblings, the packages install:

The section player's npm build leaves speech-rule-engine external, so every PIE bundle a host loads shares the one copy in the host's node_modules.

TypeScript

Each JavaScript entry point ships its declarations in dist, named by the types condition of its exports entry. TypeScript resolves them with moduleResolution bundler, node16 or nodenext.

node10, spelled node in a tsconfig, is unsupported. It ignores exports, through which the packages publish their subpaths, so a declaration that imports a subpath fails with TS2307 under skipLibCheck: false. TypeScript 6.0 deprecates node10 and 7.0 removes it, so the packages carry no typesVersions fallback for it.