Release Notes — 2026.02.01
Release notes for the playback-refactor branch merge into main. Highlights are summarized at the top; new and updated documentation are linked below.
Highlights
1. Global Playback refactor
- Single global playback: One audio/video stream site-wide. Hidden
<audio>and<video>live in GlobalMediaRenderer; playback survives navigation and view switches (e.g. carousel → grid/list). - Context-driven architecture: GlobalPlaybackContext is the single source of truth. New hooks useGlobalAudioElement and useGlobalVideoElement drive the native elements from context (no DOM polling).
- Unified progress and seek: MediaProgress reads
currentTime,duration, andsetSeekTofrom context; the global bar and in-page controls stay in sync. - Position persistence: playback-position.ts centralizes restore-on-load and save-on-seek; volume, mute, and preferences persist to localStorage.
See Global Playback 2026-FEB for full architecture and data flow.
2. NavigationClient layout and behavior
- Layout and fonts: Refinements for mobile and desktop; heading and icon adjustments.
- Click-to-hide and chevron behavior: Document click hides the nav when outside the panel and toggle; clicks inside the panel (chevrons, folder toggles, links) no longer bubble, so expand/collapse works without closing the nav.
- Single-path folder expansion: Only one folder hierarchy (root → one leaf) is expanded at a time; expanding another branch collapses the previous one.
See NavigationClient for modes, state, and data loading.
3. Assets and build
- SVG location: SVGs moved from
packages/site/public/svgtopackages/site/public/assets/svg(or equivalent under build output). Copy-assets and nav generation updated. - Public directory: Removed
packages/site/publicas a source of static files where superseded by build output; showcase and data now come from site-provided assets. - Showcase data: Site relies on a site-provided
showcase-home.json(e.g. under build output) instead of a fixed repo path; removedpackages/site/data/showcase-home.jsonfrom source.
4. Full-width carousel and directives
- fullWidthCarouselOnly: New option for custom markdown directives; full-width carousel on Album Details Page.
- Markdown: Markdown Directives and SVG Directive updated as needed.
5. Playback shortcuts and UX
- PlaybackShortcutsContext: New context controls when the keyboard-shortcuts button is shown (only where playback shortcuts apply, e.g. Photo, AlbumShowcase).
- PlaybackShortcutsButtonSlot: New component; keyboard shortcuts (e.g. play/pause, prev/next) display only in relevant views; z-index fix so shortcuts overlay correctly.
- URL encoding: Media URLs encoded for playback components to avoid broken sources.
- Error messaging: Playback errors use
text-orange-500for visibility.
6. SEO and Open Graph
- ogImage metadata: Structured data and OG tags updated; multiple OG images supported (e.g.
ogImage-01.jpg,ogImage-02.jpg,ogImage-03.jpginpackages/site/public/assets/og/). - StructuredData: StructuredData and metadata helpers updated for OG and SEO.
7. Other changes
- IPTC: Plan added for IPTC/location in album index (see
.cursor/plans/). - Polish: Left nav, OG image wiring, and assorted bugfixes across showcase, album detail, and audio playlist wrappers.
New documentation
| Document | Description |
|---|---|
| Global Playback 2026-FEB | Current-state architecture: GlobalPlaybackProvider, GlobalMediaRenderer, hooks, persistence, consumers, and known gaps. |
| NavigationClient | Client-side nav panel: modes, single-path folder expansion, click-to-hide, resize, data loading. |
| Plans/Global Media Renderer | Single source of truth for playback: single <audio>/<video>, replace-on-play, no merge on mount, optional source id. |
| Plans/Global Playback Architecture Improvements | Suggestions implemented in this refactor: unified progress/seek, hooks, position persistence, context surface. |
| Plans/Playlist Queue Roadmap | Future queue feature: add to queue, play next, on top of single-source playback. |
Updated documentation
- Albums — Album generation, metadata, and usage (alignments with nav and playback).
- Authoring — Authoring workflow and content patterns.
- Config Files — Config and paths (e.g. showcase, assets).
- Markdown/Markdown Directives — Directives including full-width carousel and related options.
- Markdown/SVG Directive — SVG paths and asset location.
- Plans/Notecards Plugin Quick Start — Notecards plugin usage and links.
Code and layout changes (summary)
- Layout: app/layout.tsx — GlobalPlaybackProvider, GlobalMediaRenderer, GlobalPlaybackControl, PlaybackShortcutsButtonSlot.
- New components: PlaybackShortcutsButtonSlot; new hooks: useGlobalAudioElement, useGlobalVideoElement; new lib: playback-position.
- Playback: GlobalPlaybackContext, GlobalMediaRenderer, MediaProgress, AudioPlayer, VideoPlayer, MediaRenderer, showcase and album carousels wired to global context.
- Build: copy-assets (SVG/output paths), generate-nav-data; removal of legacy public/data paths.
- Config: tailwind, content.json, showcase example; .gitignore updates.
For implementation details and file-level references, see the new docs above and the linked plan documents.