Component Tree

All components live under projects/player/src/lib/components/, are standalone (no NgModules), use the pw- selector prefix, and run with ChangeDetectionStrategy.OnPush. This page describes what each component renders and its role; for the injectable services behind them see Core Services.

Tree at a glance

Shell

PlayerShellComponent (pw-player-shell)

components/player-shell/ — the main orchestrator and the component hosts embed. It:

• loads the manifest via ManifestService (manifestUrl over HTTP, or the manifest object),
• arms the paywall (PaywallService with the manifest's rules and the host's entitlement snapshot, restoring a stored age verification), seeds initialVariables and entitlement context variables, and configures TrackingService from manifest.tracking,
• restores the reader's like/bookmark for the work and resumes the bookmark when the host gives no start position,
• owns navigation (navigateNext/navigatePrevious/navigateToPanel/navigateToChapter, page-view navigateToNextPage/navigateToPreviousPage) through FlowEngineService (getNextInChapter / getPreviousInChapter, so chapters without edges follow their reading order),
• owns the 'panel' | 'page' | 'canvas' view-mode switch and autoplay (wall-clock timer per panel — the author's durationMs or the reader's speed, summed over the page in page view — or media-driven advance for video panels via VideoControllerService.passComplete$ and VideoSequencerService.queueComplete, with a stall watchdog),
• picks page view's page sequence for the screen (pageFormat, re-picked on window resize) and shows the work's cover before the first panel (showCover),
• feeds the viewport its reading-order look-ahead (preloadTargets) and warms the first panel or page while the cover is up,
• handles keyboard shortcuts (ArrowLeft/ArrowRight navigate, T toggles toolbar, O/+/- in canvas view, Escape closes the topmost dialog or else hides the toolbar — with a dialog open, the other shortcuts are ignored) and swipe gestures forwarded by the viewport,
• derives the effective reduced-motion state (host input, reader setting, live OS media query) and passes it to the viewport and canvas stage,
• raises the paywall overlay or age gate when a navigation hits a locked panel (the entry panel on load included) or a page-view lock placeholder is activated, resumes the interrupted navigation after a passed age gate, keeps a locked panel's audio silent, and turns PaywallService enforcement off while a host entitlementAdapter decides access,
• computes the branch choices (outgoing edges whose conditions pass) for the Choices button, shown only when at least two are open, and traverses the chosen edge,
• toggles all modal/overlay visibility flags.

Key inputs: manifestUrl, manifest, locale, initialChapterId, initialPanelId, initialVariables, entitlementSnapshot, entitlementEndpoint, readerToken, entitlementAdapter, viewModeOverride, pageFormat, showCover, reducedMotion, secondsPerPanel, autoplay, showToolbar — all of them may change after init (ngOnChanges: a new manifest reloads via the public reload(), the rest apply live; showCover and the initial-position inputs are read on load). Key outputs: ready, panelChange, chapterChange, localeChange, variableChange, navigationAttempt, cameraChange, paywallAction, ageVerified, likeChange, bookmarkChange, error. The full integrator-facing contract is documented in Inputs & Outputs.

Viewport and layers

ViewportComponent (pw-viewport)

components/viewport/ — the rendering surface for the current panel (panel view) or page (page view, using Page.layout.placements and the panels map). Implements:

• mouse drag panning, touch panning, pinch zoom, and swipe detection (min 50 px within 300 ms), emitting swipe, transformChange, navigatePrevious/navigateNext,
• hover navigation arrows in the outer 15% zones and overflow indicators,
• optional viewport culling (enableViewportCulling) and lazy loading (enableLazyLoading),
• a performanceMetrics output (renderTime, panel counts, culled count, transform calculation time),
• the locked placeholder (pw-locked-panel-placeholder) in place of any panel that is an x-locked stub or that PaywallService.isPanelLocked() reports, repainted on PaywallService.changes$; in page view the placeholder is a button whose activation emits lockedPanelActivate (the panel id) so the shell can raise that panel's gate,
• page view's page box in the page's format aspect ratio (pageAspectRatio), filling the screen,
• warming the out-edge targets (panel view) and the host's preloadTargets ({ panelId, panel, widthFraction? }[], both views) at the image variant each will render at,
• passing workBalloonConfig and characters down to the speech-bubble overlay for the balloon config cascade.

LayerRendererComponent (pw-layer-renderer)

components/layer-renderer/ — renders exactly one manifest layer, switching on layer.kind, and applies positioning styles (x/y/w/h/z, defaulting to full-size). For video layers it resolves the effective play/start/muted configuration via resolvePlayMode / resolveStartMode / resolveMuted (utils/video-config-utils.ts, cascading layer → asset → settings.ui defaults) and forwards sequencing metadata (panelId, placementId, readingOrderIndex, placement z/y/x). Image layers of the panel currently on screen (viewActive) load eagerly with fetchpriority="high"; every other panel's artwork loads lazily.

Layer components (components/layers/)

Overlays (components/overlays/)

Overlays render on top of the viewport content:

Modals (components/modals/)

Modal dialogs opened from the toolbar (or by a hotspot action); each has a visibility input and a close output managed by the shell:

Toolbar

ToolbarComponent (pw-toolbar)

components/toolbar/ — the bottom control bar. Inputs reflect the current state (locale, availableLocales, viewMode, pageViewAvailable, speechEnabled, audioEnabled, sfxEnabled, autoplayEnabled, secondsPerPanel, autoplayTiming ('author' | 'manual'), autoplayProgress, thumbnailsVisible, hasAlternatives, hasBranches, showSocial); plus liked / bookmarked for the highlighted state; outputs fire one event per control (toggle view/speech/audio/SFX/autoplay, open ToC/settings/characters/extras/share/comments, show branches, cycle alternatives, locale change, thumbnails, like/bookmark; secondsPerPanelChange and autoplayTimingChange for the autoplay speed and the Author button). All labels go through ngx-translate. The shell shows it on viewport click and auto-hides it after 5 seconds; while it is hidden, the shell's own floating button (the PanelWave icon, bottom right) opens it. See Reader Interface for the user-facing description.

Helper components (components/helpers/ and others)

Public API exports

Only a subset of components is exported from public-api.ts for direct use by hosts: PlayerShellComponent, PwIconComponent, CanvasStageComponent, SpeechBubblesComponent, HotspotsOverlayComponent, ActionModalComponent, BranchChooserComponent, PaywallOverlayComponent, AgeGateComponent, PluginSandboxComponent, and VideoLayerComponent. Everything else is an internal building block reached through the shell. If you need an internal component externally, export it deliberately through public-api.ts (see Development).