The PIE Players project provides a comprehensive, modern architecture for rendering and delivering Platform for Interactive Education (PIE) assessment content. The system consists of multiple item players (for rendering individual questions) and an assessment toolkit (for coordinating full test experiences with tools, accommodations, and navigation).
Built with Bun, TypeScript, and Svelte 5, the architecture leverages modern web standards (Web Components, CSS Custom Highlight API) while maintaining framework independence and backwards compatibility with existing PIE content.
- Multiple Player Strategies: IIFE (legacy compatible), ESM (modern), and Preloaded static (pre-bundled) delivery
- Unified Authoring & Delivery: Single players support both student/teacher delivery views and authoring/configuration modes
- Assessment Toolkit: Composable services for full test delivery with navigation, tools, and accommodations
- Accessibility First: WCAG 2.2 AA compliance, IEP/504 accommodation support
- Framework Agnostic: Web Components work with any JavaScript framework
- System Overview
- Item Players
- Assessment Toolkit
- Tools & Accommodations
- Technology Stack
- Integration Patterns
- Instrumentation & Observability
- References
The PIE Players architecture consists of three major areas organized into logical layers:
Layer 1: Content Rendering - Item players that render individual PIE assessment items Layer 2: Orchestration - Section player and assessment toolkit services that coordinate full assessments Layer 3: Tools & Accommodations - Accessibility tools and test-taking accommodations
Item players are Web Components that render individual PIE assessment items. They handle element loading, model transformation, and session management.
Purpose: Load PIE elements dynamically from IIFE bundles (legacy format).
Architecture:
- Fetches IIFE bundles from PIE build service (PITS) or CDN
- Executes IIFE to register elements globally in window
- Renders item markup with registered custom elements
- Initializes models via PIE controllers
Use Cases:
- Drop-in replacement for
@pie-framework/pie-player-components - Backwards compatibility with existing PIE deployments
- Dynamic element loading from PIE build service or CDN
Key Features:
- Dynamic bundle loading from PITS (prod/stage/dev environments)
- CDN support with bundle hash
- Hosted mode (server-side vs client-side controllers)
Purpose: Load PIE elements from modern ESM packages with view-based architecture.
Architecture:
- Generates import maps for PIE packages and dependencies
- Uses native dynamic import() for package loading
- Supports view-based loading (delivery, author, print, custom variants)
- Automatic fallback to standard view if custom view unavailable
Use Cases:
- Modern browsers with native ESM support
- Smaller bundle sizes (~85% reduction vs IIFE)
- UI variant selection (mobile, accessibility, branding)
View System:
The ESM player supports loading different views/variants of elements through ESM subpath exports.
Built-in views:
delivery- Standard student/teacher interaction (root export)author- Configuration UI (/authorexport)print- Print views (/printexport)
Custom views (enabled by package.json subpath exports):
delivery-mobile- Touch-optimized UI for tablets/phonesdelivery-a11y- Accessibility-optimized (screen readers, high contrast)delivery-simple- Simplified UI for younger studentsdelivery-branded- Custom district branding
Benefits:
- Shared controller logic across all UI variants
- Consistent assessment results regardless of view
- Easy maintenance with single business logic codebase
- Graceful degradation with automatic fallback
Purpose: Pre-bundled player with predefined element combinations (performance optimized).
Architecture:
- All elements pre-bundled at build time
- Zero runtime bundle fetching
- Hash-based versioning for deterministic builds
Use Cases:
- Performance-critical deployments
- Predefined question type sets
- Reduced runtime overhead
Key Features:
- Build-time element combination
- Smaller API payload (data only, no bundles)
- CI/CD publishing from in-repo configs
See: docs/preloaded-player/readme.md
Purpose: Render complete assessment items for print (paper tests, answer keys, PDF export).
Architecture:
- Loads print modules from CDN
- Transforms markup (replaces interactive tags with print tags)
- Role-based rendering (student worksheets vs instructor answer keys)
- Hash-based element naming to avoid conflicts
Use Cases:
- Paper-based assessments
- Teacher answer keys with rationales
- PDF exports for archival/compliance
- Print previews in content authoring systems
See: packages/print-player/README.md
| Feature | IIFE Strategy | ESM Strategy | Preloaded Static | Print Player |
|---|---|---|---|---|
| Bundle Format | IIFE | ESM | Pre-bundled | ESM |
| Loading | Dynamic | Dynamic | Static | Dynamic |
| Browser Support | All | Modern | All | Modern |
| Bundle Size | Large | Small | Smallest | Small |
| Performance | Medium | Medium | Fast | Fast |
| Interactivity | Yes | Yes | Yes | No (static) |
| Use Case | Legacy compat | Modern apps | Performance | Print/PDF |
The section player implements element aggregation to eliminate duplicate bundle loads when multiple items use the same PIE elements.
Problem: Without aggregation, each item loads elements independently, causing duplicate network requests.
Solution: Aggregate elements from all items and load once:
- Section player analyzes all items upfront
- Creates element loader (IIFE or ESM)
- Loads all unique elements in one operation
- Items initialize from pre-loaded registry
Performance Benefits:
- Section with 5 items (3 multiple-choice, 2 hotspot)
- Before: 5 loader calls, ~550ms total
- After: 1 loader call, ~250ms total
- 50% faster
Architecture: Element loaders implement a common interface with loadFromItems() method that handles aggregation and version conflict detection.
See: @pie-players/pie-players-shared/loaders for implementation details.
New in this generation: All players support both delivery (student/teacher views) and authoring (configuration) modes in a single package.
Benefits:
- Single package to install and maintain
- Consistent API across modes
- Easier version management
- Reduced bundle duplication
Mode Switching: Players accept a mode attribute/property that switches between delivery and authoring views, loading the appropriate element view variant.
The Assessment Toolkit provides composable services for coordinating tools, accommodations, and full test delivery. It's designed as a toolkit, not a framework — products use only what they need.
- Composable Services - Import only what you need
- No Framework Lock-in - Works with any JavaScript framework
- Product Control - Products control navigation, persistence, layout, backend
- Standard Contracts - Well-defined event types for component communication
- QTI-Inspired Patterns - Reuses QTI 3.0 Personal Needs Profile (PNP) concepts for accessibility accommodations
- Section Player Integration - Toolkit services integrate seamlessly with the section player
The splitpane custom element from @pie-players/pie-section-player is the primary container/interface for integrating assessment toolkit services. When services are passed to the splitpane player, it automatically:
- Extracts SSML from embedded
<speak>tags in passages and items - Manages accessibility catalog lifecycle (add on load, clear on navigation)
- Renders TTS tools inline in passage/item headers
- Resolves catalogs with priority: extracted → item → assessment
- Coordinates z-index layering for tools
- Synchronizes text highlighting with TTS playback
Integration Pattern: Products initialize toolkit services and pass them as JavaScript properties to pie-section-player-splitpane. The player handles the rest automatically.
See: TOOL_PROVIDER_SYSTEM for integration details.
The toolkit uses QTI-inspired patterns for industry-standard assessment delivery workflows.
This approach is intentional:
- It avoids reinventing established assessment patterns.
- It is easier to understand for teams already familiar with QTI concepts.
- It makes PIE↔QTI conversion easier (for example via
pie-qti).
1. Personal Needs Profile (PNP) - Student accommodations and IEP/504 support
Maps QTI 3.0 PNP support IDs to PIE tools with precedence hierarchy:
- District block (absolute veto) - highest priority
- Test administration override
- Item restriction (per-item block)
- Item requirement (forces enable)
- District requirement
- PNP supports (student needs)
2. Context Declarations - Global variables shared across items
Enables:
- Cross-item randomization (shared random seeds)
- Adaptive testing (difficulty adjustment based on performance)
- Shared configuration (currency symbols, measurement units)
- Item dependencies
- QTI-Inspired Model: Reuses QTI 3.0 concepts while remaining PIE-oriented
- Simpler Code: 72% reduction in abstraction complexity
- Easy Integration: One-line initialization for QTI-inspired toolkit services
- Third-Party Friendly: All services work independently
The ToolkitCoordinator is a centralized orchestrator for all PIE Assessment Toolkit services, providing a single entry point for initialization, configuration, and service management.
Problem Solved: Before ToolkitCoordinator, applications had to manage multiple independent services (TTSService, ToolCoordinator, HighlightCoordinator, AccessibilityCatalogResolver, ElementToolStateStore), wire them together, and pass all separately to the player.
Solution: Single coordinator that owns all services as public properties. Products initialize one coordinator with configuration and pass it to the section player.
Benefits:
- Single initialization point
- Centralized configuration
- Services owned by coordinator
- Tool state management included
- Sensible defaults (section player creates default coordinator if not provided)
Architecture: The coordinator manages five core services and provides convenience methods for tool configuration and state management.
See: packages/assessment-toolkit/README.md for API details.
The toolkit provides six core services that work together:
Purpose: Central service managing tool visibility and z-index layering.
Architecture: Maintains tool registry with visibility state and manages z-index layers:
- 0-999: PIE content and player chrome
- 1000-1999: Non-modal tools (ruler, protractor, line reader)
- 2000-2999: Modal tools (calculator)
- 3000-3999: Tool control handles (drag, resize)
- 4000-4999: Highlight infrastructure (TTS, annotations)
- 5000+: Critical overlays (errors, notifications)
Purpose: Manages text highlighting for TTS and annotations using CSS Custom Highlight API.
Problem Solved: Both TTS (temporary word highlighting) and student annotations (persistent highlighting) need to highlight text simultaneously without interfering.
Technology: CSS Custom Highlight API (Chrome 105+, Safari 17.2+, Firefox 128+)
Benefits:
- Zero DOM mutation (preserves framework virtual DOM)
- Framework-compatible
- Screen reader friendly
- Multiple highlights overlap gracefully
- Better performance
Purpose: Text-to-speech service with word highlighting synchronization.
Architecture:
- Provider-based (BrowserTTSProvider, AWS Polly Provider)
- Integrates with HighlightCoordinator for synchronized highlighting
- Works with AccessibilityCatalogResolver for QTI 3.0 catalog support
Key Features:
- Read full question or selected text
- Pause, resume, stop playback
- Word-level highlighting synchronized with audio
- Voice selection and speed control
- State management (playing, paused, stopped)
Purpose: QTI 3.0 accessibility catalog resolution with automatic SSML extraction.
Architecture:
- Resolves catalogs with priority: extracted → item → assessment
- Supports pre-recorded audio, sign language videos, braille
- Integrates with section player for automatic SSML extraction
Purpose: Manages element-level ephemeral tool state using globally unique composite keys.
Architecture: Uses composite key format ${assessmentId}:${sectionId}:${itemId}:${elementId} to ensure uniqueness across multi-section assessments.
State Separation: Tool state (ephemeral, client-only) is separate from PIE session data (persistent, sent to server for scoring).
Purpose: QTI 3.0 Personal Needs Profile (PNP) tool resolution with precedence hierarchy.
Architecture: Resolves tool availability following QTI 3.0 PNP precedence rules, mapping QTI support IDs to PIE tool IDs.
The toolkit includes 15+ accessibility accommodations and assessment tools implemented as Web Components and coordinated via shared services.
Tools Include:
- Text-to-Speech (TTS)
- Calculator (Desmos, TI)
- Ruler & Protractor
- Line Reader
- Answer Eliminator
- Magnifier
- Highlighter
- Color Contrast
- And more...
Coordination: Tools register with ToolCoordinator for z-index management, use HighlightCoordinator for text highlighting, and integrate with TTSService for read-aloud functionality.
Canonical Documentation:
- Bun - Fast all-in-one toolkit (package manager, bundler, runtime)
- TypeScript - Type-safe development with enhanced IDE support
- Svelte 5 - Reactive UI framework with runes, compiles to efficient vanilla JavaScript
- Turbo - High-performance build system for monorepo task orchestration
- Vite - Lightning-fast dev server with HMR
- Web Components (Custom Elements) - Framework-agnostic standard with native browser support
- CSS Custom Highlight API - Native highlighting without DOM mutation
- Web Speech API - Browser-native text-to-speech with word boundary events
- CSS Container Queries - Component-level responsive design
- Moveable.js - Drag, rotate, resize functionality for ruler and protractor tools
- Desmos API - Graphing and scientific calculator integration
- Target: Modern evergreen browsers
- Coverage: ~85% global browser market (2026)
- Fallback Strategy: Graceful degradation for advanced features
Use a single item player for rendering individual questions. Suitable for embedding single questions in content management systems or learning platforms.
Players: IIFE, ESM, or preloaded static strategy Complexity: Low Use Case: Single question rendering
Add individual assessment tools to item player without full toolkit integration. Suitable for simple test-taking experiences with limited accommodation needs.
Architecture: Direct tool registration with ToolCoordinator Complexity: Medium Use Case: Simple assessments with basic tools
Use section player with full assessment toolkit for complete section delivery using QTI-inspired structures. This is the recommended pattern for production assessments.
Architecture:
- Initialize toolkit services (TTSService, catalogResolver, coordinators)
- Pass services to section player as JavaScript properties
- Section player automatically handles SSML extraction, catalog lifecycle, TTS tools, service coordination
Complexity: Medium Use Case: Production assessments with full accessibility support
See: TOOL_HOST_CONTRACT for runtime host/tool examples.
Build your own assessment player using toolkit services for complete control over navigation, layout, and persistence.
Architecture: Use toolkit services directly with custom player logic Complexity: High Use Case: Custom assessment experiences with specific requirements
Instrumentation across players is intentionally provider-agnostic and built on
InstrumentationProvider contracts rather than backend-specific APIs.
- With tracking enabled, missing/
undefinedprovider values use the default New Relic provider path. instrumentationProvider: nullexplicitly disables instrumentation.- Invalid provider objects are ignored (optional debug warning), also no-op.
- Existing
item-playerbehavior is the compatibility anchor. - For local debugging, you can compose providers (for example New Relic + debug panel) by using a fan-out provider rather than replacing production telemetry.
- Debug panel parity rule: production-bound events are preserved as events (same filtering/sampling pipeline), and debug-only metric rows are additive.
- Toolkit layer owns toolkit lifecycle stream (for example
pie-toolkit-*). - Section layer owns section runtime/public stream (for example
pie-section-*). - Assessment layer owns assessment orchestration stream (for example
pie-assessment-*). - Tool/backend layer (via toolkit telemetry forwarding) owns operational stream for tool init/backend/library calls (for example
pie-tool-init-*,pie-tool-backend-call-*,pie-tool-library-load-*).
Bridge dedupe exists as a safety net for accidental duplicate dispatch paths, but correctness is ownership-first by design.
- Tools & Accommodations Architecture - Tools system design
- Question Layout Engine Architecture - Layout system design
- Assessment Toolkit README - Toolkit usage and QTI 3.0 examples
- Section Player README - Complete section player API
- Tool Provider System - Service integration details
- Tools README - Tool development guide
The PIE Players architecture provides a comprehensive, modern foundation for rendering PIE assessment content. The system is organized into three major areas:
- Item Players - Multiple player strategies (IIFE, ESM, Preloaded Static, Print) for different deployment scenarios
- Assessment Toolkit - Composable services for full test delivery with tools and accommodations
- Tools & Accommodations - 15+ assessment tools with WCAG 2.2 AA compliance
By leveraging modern web standards (Web Components, CSS Custom Highlight API) and maintaining framework independence, the architecture ensures long-term maintainability, excellent performance, and broad compatibility.
The toolkit approach (vs framework) gives products maximum flexibility while providing battle-tested reference implementations for common scenarios. The section player serves as the primary interface, automatically handling SSML extraction, catalog lifecycle, and service coordination.