From e5ccf25b45a56f2b4f30ff2bf3886f7623adb161 Mon Sep 17 00:00:00 2001
From: winoffrg <rohangupta1528@gmail.com>
Date: Sat, 13 Jun 2026 17:37:15 +0530
Subject: [PATCH 1/5] fix: player controls improvements

---
 apps/www/package.json                         |  2 +-
 .../components/playback-controls.tsx          | 30 ++++++----
 .../components/playback-mode-controls.tsx     | 55 ++++++++++++++++---
 .../audio-player/components/playlist.tsx      | 29 +++++++---
 .../audio-player/components/track-info.tsx    | 46 ++++++----------
 .../components/bottom-controls.tsx            |  4 ++
 .../playlist-navigation-controls.tsx          | 32 +++++++++++
 bun.lock                                      |  4 +-
 8 files changed, 143 insertions(+), 59 deletions(-)
 create mode 100644 apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx

diff --git a/apps/www/package.json b/apps/www/package.json
index 939b3d89..29a56099 100644
--- a/apps/www/package.json
+++ b/apps/www/package.json
@@ -65,7 +65,7 @@
     "remark-code-import": "^1.2.0",
     "remark-gfm": "^4.0.1",
     "remark-rehype": "^11.1.2",
-    "shaka-player": "^4.16.32",
+    "shaka-player": "^4.16.34",
     "tailwind-merge": "^3.6.0",
     "ts-morph": "27.0.2",
     "tw-animate-css": "^1.4.0",
diff --git a/apps/www/registry/default/blocks/audio-player/components/playback-controls.tsx b/apps/www/registry/default/blocks/audio-player/components/playback-controls.tsx
index fa27d261..52846041 100644
--- a/apps/www/registry/default/blocks/audio-player/components/playback-controls.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/playback-controls.tsx
@@ -16,7 +16,11 @@ import { RECOMMENDED_PLAYER_BUFFERING_THROTTLE_MS } from "@/registry/default/hoo
 import { usePlaylist } from "@/registry/default/hooks/use-playlist"
 import { PlaybackControl } from "@/registry/default/ui/playback-control"
 
-export function PlaybackControls() {
+export function PlaybackControls({
+  showNavigation = true,
+}: {
+  showNavigation?: boolean
+}) {
   const status = usePlaybackStore((state) => state.status)
   const { hasNext, hasPrevious, next, previous } = usePlaylist()
 
@@ -29,13 +33,15 @@ export function PlaybackControls() {
 
   return (
     <div className="flex items-center gap-1">
-      <Button
-        aria-label="Previous track"
-        disabled={!hasPrevious}
-        onClick={previous}
-      >
-        <PreviousIcon aria-hidden="true" />
-      </Button>
+      {showNavigation ? (
+        <Button
+          aria-label="Previous track"
+          disabled={!hasPrevious}
+          onClick={previous}
+        >
+          <PreviousIcon aria-hidden="true" />
+        </Button>
+      ) : null}
 
       <PlaybackControl asChild>
         <Button aria-label={isPlaying ? "Pause" : "Play"} size="xl">
@@ -57,9 +63,11 @@ export function PlaybackControls() {
         </Button>
       </PlaybackControl>
 
-      <Button aria-label="Next track" disabled={!hasNext} onClick={next}>
-        <NextIcon aria-hidden="true" />
-      </Button>
+      {showNavigation ? (
+        <Button aria-label="Next track" disabled={!hasNext} onClick={next}>
+          <NextIcon aria-hidden="true" />
+        </Button>
+      ) : null}
     </div>
   )
 }
diff --git a/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx b/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx
index 2901e400..4f8fb415 100644
--- a/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx
@@ -1,6 +1,9 @@
 "use client"
 
 import { AnimatePresence, motion } from "motion/react"
+import { useEffect, useMemo } from "react"
+
+import type { RepeatMode } from "@/registry/default/hooks/use-playlist"
 
 import { cn } from "@/lib/utils"
 import { Button } from "@/registry/default/blocks/audio-player/components/button"
@@ -16,19 +19,46 @@ import {
   usePlaylistStore,
 } from "@/registry/default/hooks/use-playlist"
 
-export function RepeatControl() {
-  const { cycleRepeatMode } = usePlaylist()
+type RepeatControlVariant = "asset" | "playlist"
+
+const REPEAT_MODES: Record<RepeatControlVariant, RepeatMode[]> = {
+  asset: ["off", "one"],
+  playlist: ["off", "all", "one"],
+}
+
+export function RepeatControl({
+  variant = "playlist",
+}: {
+  variant?: RepeatControlVariant
+}) {
+  const { setRepeatMode } = usePlaylist()
   const repeatMode = usePlaylistStore((state) => state.repeatMode)
-  const isActive = repeatMode !== "off"
+  const modes = REPEAT_MODES[variant]
+  const normalizedRepeatMode = useMemo(
+    () => normalizeRepeatMode(repeatMode, modes),
+    [modes, repeatMode]
+  )
+  const isActive = normalizedRepeatMode !== "off"
+
+  useEffect(() => {
+    if (repeatMode === normalizedRepeatMode) return
+    setRepeatMode(normalizedRepeatMode)
+  }, [normalizedRepeatMode, repeatMode, setRepeatMode])
+
+  const handleCycleRepeatMode = () => {
+    const modeIndex = modes.indexOf(normalizedRepeatMode)
+    const nextMode = modes[(modeIndex + 1) % modes.length] ?? "off"
+    setRepeatMode(nextMode)
+  }
 
   return (
     <Button
-      aria-label={`Repeat: ${repeatMode}`}
+      aria-label={`Repeat: ${normalizedRepeatMode}`}
       aria-pressed={isActive}
       className={cn({
         "text-secondary": !isActive,
       })}
-      onClick={cycleRepeatMode}
+      onClick={handleCycleRepeatMode}
     >
       <AnimatePresence initial={false} mode="popLayout">
         <motion.span
@@ -36,12 +66,12 @@ export function RepeatControl() {
           className="flex items-center justify-center"
           exit={{ filter: "blur(4px)", opacity: 0, scale: 0.25 }}
           initial={{ filter: "blur(4px)", opacity: 0, scale: 0.25 }}
-          key={repeatMode}
+          key={normalizedRepeatMode}
           transition={{ bounce: 0, duration: 0.3, type: "spring" }}
         >
-          {repeatMode === "one" ? (
+          {normalizedRepeatMode === "one" ? (
             <RepeatOneIcon aria-hidden="true" />
-          ) : repeatMode === "off" ? (
+          ) : normalizedRepeatMode === "off" ? (
             <RepeatIcon aria-hidden="true" />
           ) : (
             <RepeatAllIcon aria-hidden="true" />
@@ -88,3 +118,12 @@ export function ShuffleControl() {
     </Button>
   )
 }
+
+function normalizeRepeatMode(
+  mode: RepeatMode,
+  modes: RepeatMode[]
+): RepeatMode {
+  if (modes.includes(mode)) return mode
+  if (mode === "all" && modes.includes("one")) return "one"
+  return modes[0] ?? "off"
+}
diff --git a/apps/www/registry/default/blocks/audio-player/components/playlist.tsx b/apps/www/registry/default/blocks/audio-player/components/playlist.tsx
index de1cc938..e8659fde 100644
--- a/apps/www/registry/default/blocks/audio-player/components/playlist.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/playlist.tsx
@@ -4,18 +4,21 @@ import { CardsThreeIcon, PlayIcon } from "@phosphor-icons/react"
 import { Volume2Icon } from "lucide-react"
 import { useCallback, useMemo, useRef } from "react"
 
-import type { AudioPlayerAsset } from "@/registry/default/blocks/audio-player/components/audio-source"
-
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu"
 import { cn } from "@/lib/utils"
-import { useAudioSource } from "@/registry/default/blocks/audio-player/components/audio-source"
+import {
+  type AudioPlayerAsset,
+  getAudioAssetMetadata,
+  useAudioSource,
+} from "@/registry/default/blocks/audio-player/components/audio-source"
 import { Button } from "@/registry/default/blocks/audio-player/components/button"
 import { usePlayerStore } from "@/registry/default/hooks/use-player"
 import { usePlaylistStore } from "@/registry/default/hooks/use-playlist"
+import { LimeplayLogo } from "@/registry/default/ui/limeplay-logo"
 
 export function Playlist() {
   const currentItem = usePlaylistStore(
@@ -161,6 +164,8 @@ function TrackRow({
   preloaded: boolean
   setSize: number
 }) {
+  const metadata = getAudioAssetMetadata(asset, "Untitled track")
+
   return (
     <Button
       aria-posinset={index + 1}
@@ -176,13 +181,21 @@ function TrackRow({
       onClick={onSelect}
     >
       <div className="relative size-10 shrink-0 overflow-hidden rounded-sm bg-white/4 outline-1 -outline-offset-1 outline-white/10">
-        {asset.poster && (
+        {metadata.poster && (
           <img
             alt=""
             className="absolute inset-0 size-full object-cover"
-            src={asset.poster}
+            src={metadata.poster}
           />
         )}
+        {!metadata.poster && (
+          <div
+            aria-hidden="true"
+            className="absolute inset-0 flex items-center justify-center text-white/35"
+          >
+            <LimeplayLogo className="size-5" />
+          </div>
+        )}
         <div
           className={cn(
             "absolute inset-0 flex items-center justify-center transition-[background-color] duration-150 ease-out",
@@ -225,15 +238,15 @@ function TrackRow({
                 `
             )}
           >
-            {asset.title ?? "Untitled track"}
+            {metadata.title}
           </p>
           {preloaded && !isActive && (
             <span className="size-1.5 shrink-0 rounded-full bg-white/30" />
           )}
         </div>
-        {asset.genre && (
+        {metadata.subtitle && (
           <p className="mt-0.5 truncate text-[11px] text-white/40">
-            {asset.genre}
+            {metadata.subtitle}
           </p>
         )}
       </div>
diff --git a/apps/www/registry/default/blocks/audio-player/components/track-info.tsx b/apps/www/registry/default/blocks/audio-player/components/track-info.tsx
index 2d0e0ab2..7a7ac5b9 100644
--- a/apps/www/registry/default/blocks/audio-player/components/track-info.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/track-info.tsx
@@ -1,52 +1,40 @@
 "use client"
 
-import type { AudioPlayerAsset } from "@/registry/default/blocks/audio-player/components/audio-source"
-
+import {
+  type AudioPlayerAsset,
+  getAudioAssetMetadata,
+} from "@/registry/default/blocks/audio-player/components/audio-source"
 import { useAsset } from "@/registry/default/hooks/use-asset"
+import { LimeplayLogo } from "@/registry/default/ui/limeplay-logo"
 
 export function TrackInfo() {
   const { currentItem } = useAsset<AudioPlayerAsset>()
 
   const asset = currentItem?.properties
-  const title = asset?.title ?? "No track playing"
-  const genre = asset?.genre ?? ""
-  const releaseYear = asset?.releaseYear ?? asset?.year
+  const metadata = getAudioAssetMetadata(asset)
 
   return (
     <div className="flex min-w-0 items-center gap-3">
-      <div className="relative size-10 shrink-0 overflow-hidden rounded-sm bg-secondary outline-1 -outline-offset-1 outline-white/10">
-        {asset?.poster ? (
+      {metadata.poster ? (
+        <div className="relative size-10 shrink-0 overflow-hidden rounded-sm bg-secondary outline-1 -outline-offset-1 outline-white/10">
           <img
-            alt={`Album art for ${title}`}
+            alt={`Album art for ${metadata.title}`}
             className="size-full object-cover"
             height={40}
-            src={asset.poster}
+            src={metadata.poster}
             width={40}
           />
-        ) : (
-          <div
-            aria-hidden="true"
-            className="flex size-full items-center justify-center text-secondary"
-          >
-            <svg
-              aria-hidden="true"
-              className="size-5"
-              fill="currentColor"
-              viewBox="0 0 24 24"
-            >
-              <path d="M12 3v10.55c-.59-.34-1.27-.55-2-.55-2.21 0-4 1.79-4 4s1.79 4 4 4 4-1.79 4-4V7h4V3h-6z" />
-            </svg>
-          </div>
-        )}
-      </div>
+        </div>
+      ) : (
+          <LimeplayLogo className="size-10" />
+      )}
       <div className="min-w-0 flex-1">
         <div className="truncate text-sm/snug font-medium text-secondary-foreground">
-          {title}
+          {metadata.title}
         </div>
-        {genre && (
+        {metadata.subtitle && (
           <div className="truncate text-xs/snug text-secondary">
-            {genre}
-            {releaseYear ? ` • ${releaseYear}` : ""}
+            {metadata.subtitle}
           </div>
         )}
       </div>
diff --git a/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx b/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx
index aeecb875..ec12e811 100644
--- a/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx
+++ b/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx
@@ -3,6 +3,9 @@ import { PictureInPictureControl } from "@/registry/default/blocks/video-player/
 import { PlaybackRateControl } from "@/registry/default/blocks/video-player/components/playback-rate-control"
 import { PlaybackStateControl } from "@/registry/default/blocks/video-player/components/playback-state-control"
 import { Playlist } from "@/registry/default/blocks/video-player/components/playlist"
+import {
+  PlaylistNextControl,
+} from "@/registry/default/blocks/video-player/components/playlist-navigation-controls"
 import { TimelineSliderControl } from "@/registry/default/blocks/video-player/components/timeline-slider-control"
 import { VolumeGroupControl } from "@/registry/default/blocks/video-player/components/volume-group-control"
 import * as Layout from "@/registry/default/ui/player-layout"
@@ -11,6 +14,7 @@ export function BottomControls() {
   return (
     <Layout.ControlsBottomContainer>
       <PlaybackStateControl />
+      <PlaylistNextControl />
       <VolumeGroupControl />
       <TimelineSliderControl />
       <PlaybackRateControl />
diff --git a/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx b/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx
new file mode 100644
index 00000000..322305eb
--- /dev/null
+++ b/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx
@@ -0,0 +1,32 @@
+"use client"
+
+import { SkipForwardIcon } from "@phosphor-icons/react"
+
+import { Button } from "@/registry/default/blocks/video-player/components/button"
+import {
+  usePlaylist,
+  usePlaylistStore,
+} from "@/registry/default/hooks/use-playlist"
+
+export function PlaylistNextControl() {
+  const { hasNext, next } = usePlaylist()
+  const hasPlaylist = useHasPlaylist()
+
+  if (!hasPlaylist) return null
+
+  return (
+    <Button
+      aria-label="Next video"
+      disabled={!hasNext}
+      onClick={next}
+      size="icon"
+      variant="glass"
+    >
+      <SkipForwardIcon weight="fill" />
+    </Button>
+  )
+}
+
+function useHasPlaylist() {
+  return usePlaylistStore((state) => state.queue.length > 1)
+}
diff --git a/bun.lock b/bun.lock
index e21a0bc2..6f1cd22f 100644
--- a/bun.lock
+++ b/bun.lock
@@ -65,7 +65,7 @@
         "remark-code-import": "^1.2.0",
         "remark-gfm": "^4.0.1",
         "remark-rehype": "^11.1.2",
-        "shaka-player": "^4.16.32",
+        "shaka-player": "^4.16.34",
         "tailwind-merge": "^3.6.0",
         "ts-morph": "27.0.2",
         "tw-animate-css": "^1.4.0",
@@ -1834,7 +1834,7 @@
 
     "shadcn": ["shadcn@4.8.0", "", { "dependencies": { "@babel/core": "^7.28.0", "@babel/parser": "^7.28.0", "@babel/plugin-transform-typescript": "^7.28.0", "@babel/preset-typescript": "^7.27.1", "@dotenvx/dotenvx": "^1.48.4", "@modelcontextprotocol/sdk": "^1.26.0", "@types/validate-npm-package-name": "^4.0.2", "browserslist": "^4.26.2", "commander": "^14.0.0", "cosmiconfig": "^9.0.0", "dedent": "^1.6.0", "deepmerge": "^4.3.1", "diff": "^8.0.2", "execa": "^9.6.0", "fast-glob": "^3.3.3", "fs-extra": "^11.3.1", "fuzzysort": "^3.1.0", "https-proxy-agent": "^7.0.6", "kleur": "^4.1.5", "msw": "^2.10.4", "node-fetch": "^3.3.2", "open": "^11.0.0", "ora": "^8.2.0", "postcss": "^8.5.6", "postcss-selector-parser": "^7.1.0", "prompts": "^2.4.2", "recast": "^0.23.11", "stringify-object": "^5.0.0", "tailwind-merge": "^3.0.1", "ts-morph": "^26.0.0", "tsconfig-paths": "^4.2.0", "validate-npm-package-name": "^7.0.1", "zod": "^3.24.1", "zod-to-json-schema": "^3.24.6" }, "bin": { "shadcn": "dist/index.js" } }, "sha512-LAm3I/1FdoU/zu5GVG8Hbna4X9zlzEG5TeeCPXqsopkjvGk8QUF9OFhqeRN8oM6Oh/ynUI/yQHZxQAO3Ymcqsg=="],
 
-    "shaka-player": ["shaka-player@4.16.32", "", {}, "sha512-IctqLYNczkX3PzH/iG/N+m4r12WOgqIPnuvqIXRZlQssMAmKaaUP8pB2MGX9l7SwSG7/PUwQVtIlbt+o/BZl+A=="],
+    "shaka-player": ["shaka-player@4.16.34", "", {}, "sha512-magCRFwu1TsWvUJEQm6DlKK6u8EsP7WJzpIThN/gBiIhvedTI8lFxHew4qYPLMwXZ305RRpSEDZHJ/KwuOz/og=="],
 
     "sharp": ["sharp@0.34.5", "", { "dependencies": { "@img/colour": "^1.0.0", "detect-libc": "^2.1.2", "semver": "^7.7.3" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "0.34.5", "@img/sharp-darwin-x64": "0.34.5", "@img/sharp-libvips-darwin-arm64": "1.2.4", "@img/sharp-libvips-darwin-x64": "1.2.4", "@img/sharp-libvips-linux-arm": "1.2.4", "@img/sharp-libvips-linux-arm64": "1.2.4", "@img/sharp-libvips-linux-ppc64": "1.2.4", "@img/sharp-libvips-linux-riscv64": "1.2.4", "@img/sharp-libvips-linux-s390x": "1.2.4", "@img/sharp-libvips-linux-x64": "1.2.4", "@img/sharp-libvips-linuxmusl-arm64": "1.2.4", "@img/sharp-libvips-linuxmusl-x64": "1.2.4", "@img/sharp-linux-arm": "0.34.5", "@img/sharp-linux-arm64": "0.34.5", "@img/sharp-linux-ppc64": "0.34.5", "@img/sharp-linux-riscv64": "0.34.5", "@img/sharp-linux-s390x": "0.34.5", "@img/sharp-linux-x64": "0.34.5", "@img/sharp-linuxmusl-arm64": "0.34.5", "@img/sharp-linuxmusl-x64": "0.34.5", "@img/sharp-wasm32": "0.34.5", "@img/sharp-win32-arm64": "0.34.5", "@img/sharp-win32-ia32": "0.34.5", "@img/sharp-win32-x64": "0.34.5" } }, "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg=="],
 

From 85691df9e67b13d180c05587183359e1bb58b602 Mon Sep 17 00:00:00 2001
From: winoffrg <rohangupta1528@gmail.com>
Date: Sat, 13 Jun 2026 17:37:47 +0530
Subject: [PATCH 2/5] fix: player controls improvements

---
 .../default/blocks/audio-player/components/track-info.tsx     | 2 +-
 .../blocks/video-player/components/bottom-controls.tsx        | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/apps/www/registry/default/blocks/audio-player/components/track-info.tsx b/apps/www/registry/default/blocks/audio-player/components/track-info.tsx
index 7a7ac5b9..0dcb4055 100644
--- a/apps/www/registry/default/blocks/audio-player/components/track-info.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/track-info.tsx
@@ -26,7 +26,7 @@ export function TrackInfo() {
           />
         </div>
       ) : (
-          <LimeplayLogo className="size-10" />
+        <LimeplayLogo className="size-10" />
       )}
       <div className="min-w-0 flex-1">
         <div className="truncate text-sm/snug font-medium text-secondary-foreground">
diff --git a/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx b/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx
index ec12e811..c58f02e1 100644
--- a/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx
+++ b/apps/www/registry/default/blocks/video-player/components/bottom-controls.tsx
@@ -3,9 +3,7 @@ import { PictureInPictureControl } from "@/registry/default/blocks/video-player/
 import { PlaybackRateControl } from "@/registry/default/blocks/video-player/components/playback-rate-control"
 import { PlaybackStateControl } from "@/registry/default/blocks/video-player/components/playback-state-control"
 import { Playlist } from "@/registry/default/blocks/video-player/components/playlist"
-import {
-  PlaylistNextControl,
-} from "@/registry/default/blocks/video-player/components/playlist-navigation-controls"
+import { PlaylistNextControl } from "@/registry/default/blocks/video-player/components/playlist-navigation-controls"
 import { TimelineSliderControl } from "@/registry/default/blocks/video-player/components/timeline-slider-control"
 import { VolumeGroupControl } from "@/registry/default/blocks/video-player/components/volume-group-control"
 import * as Layout from "@/registry/default/ui/player-layout"

From 751fb204fa9a302c981902bb700244bc7403db28 Mon Sep 17 00:00:00 2001
From: winoffrg <rohangupta1528@gmail.com>
Date: Sun, 14 Jun 2026 03:38:05 +0530
Subject: [PATCH 3/5] feat: usage revamp and documentation update

---
 apps/www/app/layout.config.tsx                |  33 +-
 apps/www/components/mdx-components.tsx        |   2 +
 apps/www/components/mdx/mermaid.tsx           |  41 ++
 .../players/audio-player/demo-player.tsx      |   7 +-
 .../stream-panel/use-stream-panel-sync.ts     |  80 +-
 apps/www/content/docs/blocks/audio-player.mdx |  51 +-
 apps/www/content/docs/blocks/meta.json        |   3 +-
 apps/www/content/docs/blocks/video-player.mdx |  68 +-
 .../docs/components/media-provider.mdx        |   2 +-
 apps/www/content/docs/concepts.mdx            | 137 ++--
 apps/www/content/docs/events.mdx              | 117 ---
 apps/www/content/docs/hooks/use-asset.mdx     | 121 +++-
 .../docs/hooks/use-playback-source.mdx        |  36 +-
 apps/www/content/docs/hooks/use-playback.mdx  |   2 +-
 apps/www/content/docs/hooks/use-player.mdx    |   8 +-
 apps/www/content/docs/quick-start.mdx         |  41 +-
 apps/www/content/docs/usage.mdx               | 289 ++++++++
 apps/www/package.json                         |   4 +-
 .../audio-player/components/audio-source.tsx  | 266 ++++---
 .../audio-player/components/controls.tsx      |  24 +-
 .../audio-player/components/media-player.tsx  |  36 +-
 .../audio-player/components/playlist.tsx      |  21 +-
 .../audio-player/hooks/use-playlist-asset.ts  |   5 +-
 .../video-player/components/media-player.tsx  |  43 +-
 .../default/blocks/video-player/page.tsx      |   2 +-
 apps/www/registry/default/hooks/use-asset.ts  | 684 ++++++++++++------
 .../default/hooks/use-playback-source.ts      |  91 ++-
 apps/www/registry/default/hooks/use-player.ts |  15 +-
 bun.lock                                      |   9 +-
 29 files changed, 1504 insertions(+), 734 deletions(-)
 create mode 100644 apps/www/components/mdx/mermaid.tsx
 delete mode 100644 apps/www/content/docs/events.mdx
 create mode 100644 apps/www/content/docs/usage.mdx

diff --git a/apps/www/app/layout.config.tsx b/apps/www/app/layout.config.tsx
index 80fc38fe..91830451 100644
--- a/apps/www/app/layout.config.tsx
+++ b/apps/www/app/layout.config.tsx
@@ -1,11 +1,10 @@
 import type { BaseLayoutProps, LinkItemType } from "fumadocs-ui/layouts/shared"
 
-import {
-  BlueprintIcon,
-  QuestionIcon,
-  SparkleIcon,
-} from "@phosphor-icons/react/dist/ssr"
-import { RssIcon } from "lucide-react"
+import { IconBlocks } from "@central-icons-react/round-filled-radius-0-stroke-1/IconBlocks"
+import { IconBook } from "@central-icons-react/round-filled-radius-0-stroke-1/IconBook"
+import { IconBuildingBlocks } from "@central-icons-react/round-filled-radius-0-stroke-1/IconBuildingBlocks"
+import { IconNewspaper2 } from "@central-icons-react/round-filled-radius-0-stroke-1/IconNewspaper2"
+import { IconRocket } from "@central-icons-react/round-filled-radius-0-stroke-1/IconRocket"
 import Image from "next/image"
 
 import { Icons } from "@/components/icons"
@@ -33,28 +32,34 @@ const COMMON_LINKS: LinkItemType[] = [
 export const baseOptions: BaseLayoutProps = {
   links: [
     {
-      icon: <SparkleIcon />,
+      icon: <IconRocket />,
       text: "Quick Start",
       type: "main",
       url: "/docs/quick-start",
     },
     {
-      icon: <QuestionIcon />,
+      icon: <IconBook />,
       text: "Introduction",
       type: "main",
       url: "/docs/introduction",
     },
     {
-      icon: <BlueprintIcon />,
-      text: "Concepts",
+      icon: <IconNewspaper2 />,
+      text: "Usage",
       type: "main",
-      url: "/docs/concepts",
+      url: "/docs/usage",
     },
     {
-      icon: <RssIcon />,
-      text: "Events",
+      icon: <IconBlocks />,
+      text: "Blocks",
       type: "main",
-      url: "/docs/events",
+      url: "/blocks/video-player",
+    },
+    {
+      icon: <IconBuildingBlocks />,
+      text: "Concepts",
+      type: "main",
+      url: "/docs/concepts",
     },
     ...COMMON_LINKS,
   ],
diff --git a/apps/www/components/mdx-components.tsx b/apps/www/components/mdx-components.tsx
index 8e36d5bf..a8a10415 100644
--- a/apps/www/components/mdx-components.tsx
+++ b/apps/www/components/mdx-components.tsx
@@ -8,6 +8,7 @@ import * as TabsComponents from "fumadocs-ui/components/tabs"
 import defaultComponents from "fumadocs-ui/mdx"
 
 import { ComponentPreview } from "@/components/component-preview"
+import { Mermaid } from "@/components/mdx/mermaid"
 
 const generator = createGenerator()
 
@@ -21,6 +22,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
     Attribution,
     ComponentPreview,
     License,
+    Mermaid,
     pre: ({ ref: _ref, ...props }: React.ComponentPropsWithRef<typeof Pre>) => (
       <CodeBlock {...props} keepBackground>
         <Pre>{props.children}</Pre>
diff --git a/apps/www/components/mdx/mermaid.tsx b/apps/www/components/mdx/mermaid.tsx
new file mode 100644
index 00000000..257b3f8b
--- /dev/null
+++ b/apps/www/components/mdx/mermaid.tsx
@@ -0,0 +1,41 @@
+import { renderMermaidSVG } from "beautiful-mermaid"
+import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock"
+
+export async function Mermaid({ chart }: { chart: string }) {
+  try {
+    const svg = renderMermaidSVG(chart, {
+      accent: "var(--color-fd-primary)",
+      bg: "transparent",
+      border: "color-mix(in oklab, var(--color-fd-border) 86%, transparent)",
+      fg: "var(--color-fd-foreground)",
+      font: "var(--font-sans), ui-sans-serif, system-ui, sans-serif",
+      interactive: true,
+      layerSpacing: 52,
+      line: "color-mix(in oklab, var(--color-fd-muted-foreground) 58%, transparent)",
+      muted: "var(--color-fd-muted-foreground)",
+      nodeSpacing: 36,
+      padding: 32,
+      surface:
+        "color-mix(in oklab, var(--color-fd-card) 92%, var(--color-fd-primary) 8%)",
+      transparent: true,
+    })
+
+    return (
+      <figure className="not-prose my-8 overflow-hidden rounded-2xl border bg-fd-card/70 shadow-sm ring-1 ring-fd-border/40">
+        <div
+          className="
+            overflow-x-auto p-4
+            sm:p-6
+          "
+          dangerouslySetInnerHTML={{ __html: svg }}
+        />
+      </figure>
+    )
+  } catch {
+    return (
+      <CodeBlock title="Mermaid">
+        <Pre>{chart}</Pre>
+      </CodeBlock>
+    )
+  }
+}
diff --git a/apps/www/components/players/audio-player/demo-player.tsx b/apps/www/components/players/audio-player/demo-player.tsx
index b52d23d2..e00e1585 100644
--- a/apps/www/components/players/audio-player/demo-player.tsx
+++ b/apps/www/components/players/audio-player/demo-player.tsx
@@ -28,9 +28,8 @@ export function AudioPlayerDemo({
 }: AudioPlayerDemoProps) {
   const [playlist, setPlaylist] = useState<AudioPlayerAsset[]>([])
   const storeHydrated = useStreamPanelStoreHydrated()
-  const hasPersistedAudioSelection = useStreamPanelStore((s) =>
-    Boolean(s.contentSelections.audio)
-  )
+  const audioSelection = useStreamPanelStore((s) => s.contentSelections.audio)
+  const hasPersistedAudioSelection = Boolean(audioSelection)
 
   useEffect(() => {
     const abortController = new AbortController()
@@ -54,7 +53,7 @@ export function AudioPlayerDemo({
   return (
     <AudioPlayer
       autoLoad={storeHydrated ? !hasPersistedAudioSelection : false}
-      playlist={playlist}
+      source={playlist}
     >
       {children}
     </AudioPlayer>
diff --git a/apps/www/components/stream-panel/use-stream-panel-sync.ts b/apps/www/components/stream-panel/use-stream-panel-sync.ts
index d49ac601..e6f6c002 100644
--- a/apps/www/components/stream-panel/use-stream-panel-sync.ts
+++ b/apps/www/components/stream-panel/use-stream-panel-sync.ts
@@ -2,7 +2,11 @@
 
 import { useCallback, useEffect, useMemo, useRef } from "react"
 
-import type { Asset, UseAssetOptions } from "@/registry/default/hooks/use-asset"
+import type {
+  Asset,
+  AssetEvents,
+  UseAssetOptions,
+} from "@/registry/default/hooks/use-asset"
 import type { PlaybackStore } from "@/registry/default/hooks/use-playback"
 
 import {
@@ -22,12 +26,18 @@ import {
   useStreamPanelStoreHydrated,
 } from "@/components/stream-panel/use-stream-panel"
 import { getPresetsForType, type StreamPreset } from "@/lib/stream-presets"
-import { useAsset } from "@/registry/default/hooks/use-asset"
+import {
+  AssetRecoveryAction,
+  useAsset,
+} from "@/registry/default/hooks/use-asset"
 import { useMediaStore } from "@/registry/default/hooks/use-media"
 import { PLAYBACK_FEATURE_KEY } from "@/registry/default/hooks/use-playback"
 import { usePlayerStore } from "@/registry/default/hooks/use-player"
 import { useVolumeStore } from "@/registry/default/hooks/use-volume"
-import { useMediaFeatureApi } from "@/registry/default/ui/media-provider"
+import {
+  useMediaEvents,
+  useMediaFeatureApi,
+} from "@/registry/default/ui/media-provider"
 
 const DEFAULT_VIDEO_PRESET_ID = "mux-big-buck-bunny"
 
@@ -37,6 +47,7 @@ export function useStreamPanelSync({
   playerType?: StreamPanelPlayerType
 } = {}) {
   const playbackApi = useMediaFeatureApi<PlaybackStore>(PLAYBACK_FEATURE_KEY)
+  const events = useMediaEvents<AssetEvents>()
   const mediaElement = useMediaStore((state) => state.mediaElement)
   const player = usePlayerStore((state) => state.instance)
 
@@ -112,26 +123,31 @@ export function useStreamPanelSync({
           })
         },
       },
-      onAssetChange: (event) => {
-        const selection =
-          useStreamPanelStore.getState().contentSelections[playerType]
-        if (!selection || selection.kind !== "playlist") return
-        if (selection.index === event.currentIndex) return
-
-        setContentSelection(playerType, {
-          ...selection,
-          index: event.currentIndex,
-        })
-      },
-      onLoadError: (_asset, error) => {
-        playbackApi.getState().playback.setError(error)
-        return "stop"
+      recover: {
+        loadError: (_asset, error) => {
+          playbackApi.getState().playback.setError(error)
+          return AssetRecoveryAction.Stop
+        },
       },
     }),
-    [blenderStreamCache, playbackApi, playerType, setContentSelection]
+    [blenderStreamCache, playbackApi]
   )
 
-  const { loadPlaylist } = useAsset(assetOptions)
+  const { loadSource } = useAsset<Asset>()
+
+  useEffect(() => {
+    return events.on("assetchange", (event) => {
+      const selection =
+        useStreamPanelStore.getState().contentSelections[playerType]
+      if (!selection || selection.kind !== "playlist") return
+      if (selection.index === event.currentIndex) return
+
+      setContentSelection(playerType, {
+        ...selection,
+        index: event.currentIndex,
+      })
+    })
+  }, [events, playerType, setContentSelection])
 
   useEffect(() => {
     if (!mediaElement) return
@@ -180,10 +196,10 @@ export function useStreamPanelSync({
         src,
         type: playerType,
       }
-      loadPlaylist([asset as unknown as Asset])
+      loadSource(asset as unknown as Asset, { loading: assetOptions })
       return asset
     },
-    [loadPlaylist, playbackApi, playerType]
+    [assetOptions, loadSource, playbackApi, playerType]
   )
 
   const loadPlaylistPreset = useCallback(
@@ -202,7 +218,10 @@ export function useStreamPanelSync({
             index,
             kind: "playlist",
           })
-          loadPlaylist(assets, index)
+          loadSource(assets, {
+            initialIndex: index,
+            loading: assetOptions,
+          })
         })
         .catch((error: unknown) => {
           if (error instanceof DOMException && error.name === "AbortError")
@@ -211,7 +230,7 @@ export function useStreamPanelSync({
           playbackApi.getState().playback.setError(error)
         })
     },
-    [loadPlaylist, playbackApi, playerType, setContentSelection]
+    [assetOptions, loadSource, playbackApi, playerType, setContentSelection]
   )
 
   const restoreContentSelection = useCallback(
@@ -226,7 +245,7 @@ export function useStreamPanelSync({
       )
       if (preset) {
         abortPlaylistRequest()
-        loadPlaylist([preset as unknown as Asset])
+        loadSource(preset as unknown as Asset, { loading: assetOptions })
         return
       }
 
@@ -237,7 +256,8 @@ export function useStreamPanelSync({
     [
       abortPlaylistRequest,
       loadCustomStream,
-      loadPlaylist,
+      assetOptions,
+      loadSource,
       loadPlaylistPreset,
       playerType,
     ]
@@ -277,9 +297,15 @@ export function useStreamPanelSync({
     (preset: StreamPreset, kind: StreamPanelContentKind = "stream") => {
       abortPlaylistRequest()
       setContentSelection(playerType, { id: preset.id, index: 0, kind })
-      loadPlaylist([preset as unknown as Asset])
+      loadSource(preset as unknown as Asset, { loading: assetOptions })
     },
-    [abortPlaylistRequest, loadPlaylist, playerType, setContentSelection]
+    [
+      abortPlaylistRequest,
+      assetOptions,
+      loadSource,
+      playerType,
+      setContentSelection,
+    ]
   )
 
   const handlePlaylistPresetChange = useCallback(
diff --git a/apps/www/content/docs/blocks/audio-player.mdx b/apps/www/content/docs/blocks/audio-player.mdx
index cf266382..32eca7bd 100644
--- a/apps/www/content/docs/blocks/audio-player.mdx
+++ b/apps/www/content/docs/blocks/audio-player.mdx
@@ -13,7 +13,7 @@ status: free
 npx shadcn add @limeplay/audio-player
 ```
 
-## Usage
+## Minimal Usage
 
 ```tsx
 import {
@@ -32,10 +32,53 @@ const playlist: AudioPlayerAsset[] = [
 ]
 
 export function Player() {
-  return <AudioPlayer playlist={playlist} />
+  return <AudioPlayer source={playlist} />
 }
 ```
 
+Use `source` for media loading. Use `mediaProps` only for native audio attributes.
+
+```tsx
+<AudioPlayer
+  source={playlist}
+  mediaProps={{ autoPlay: true, loop: false }}
+/>
+```
+
+## Single Track Usage
+
+Pass one asset object when you do not need a queue.
+
+```tsx
+<AudioPlayer
+  source={{
+    artist: "SoundHelix",
+    id: "soundhelix-1",
+    poster: "https://placehold.co/160x160/png",
+    src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
+    title: "SoundHelix Song 1",
+  }}
+/>
+```
+
+## Custom Loading
+
+The audio block includes an opinionated default resolver for `src` and `playbackUrls.primary`. Use `loading.resolveSource` when your app needs signed URLs, token refresh, or a different URL shape.
+
+```tsx
+<AudioPlayer
+  source={{ id: "track-123", title: "Track" }}
+  loading={{
+    resolveSource: async ({ asset, signal }) => {
+      const response = await fetch(`/api/tracks/${asset.id}/source`, { signal })
+      const source = await response.json()
+
+      return source.url
+    },
+  }}
+/>
+```
+
 ## Features
 
 - Playlist queue with track artwork, title, genre, and duration.
@@ -43,12 +86,14 @@ export function Player() {
 - Previous, play/pause, next, volume, mute, repeat, and shuffle controls.
 - Playback URL resolution for direct `src` values or `playbackUrls.primary` endpoints.
 - Automatic skip/reload behavior for recoverable load and playback failures.
+- Shared `source` and `loading` contract used by all source-driven blocks.
 
 ## Notes
 
 - `AudioPlayer` does not ship with bundled tracks. Pass a playlist from your app.
 - Use `duration` in milliseconds when you want stable duration labels before metadata loads.
-- Use `resolveSource` for signed audio URLs, token refresh, or custom playback URL APIs.
+- Do not pass `mediaProps.src`; pass `source` instead.
+- For the full block loading model, see [Usage](/docs/usage).
 
 ## API Reference
 
diff --git a/apps/www/content/docs/blocks/meta.json b/apps/www/content/docs/blocks/meta.json
index 4be6b723..67f56810 100644
--- a/apps/www/content/docs/blocks/meta.json
+++ b/apps/www/content/docs/blocks/meta.json
@@ -1,5 +1,6 @@
 {
   "title": "Blocks",
-  "description": "Headless showcase pages for registry blocks.",
+  "description": "Ready-to-use player blocks with shared source loading APIs.",
+  "pages": ["video-player", "audio-player"],
   "defaultOpen": true
 }
diff --git a/apps/www/content/docs/blocks/video-player.mdx b/apps/www/content/docs/blocks/video-player.mdx
index 4ab680e7..d9606258 100644
--- a/apps/www/content/docs/blocks/video-player.mdx
+++ b/apps/www/content/docs/blocks/video-player.mdx
@@ -13,7 +13,7 @@ status: free
 npx shadcn add @limeplay/video-player
 ```
 
-## Usage
+## Minimal Usage
 
 ```tsx
 import { VideoPlayer } from "@/components/limeplay/video-player/components/media-player"
@@ -22,10 +22,70 @@ const src =
   "https://ad391cc0d55b44c6a86d232548adc225.mediatailor.us-east-1.amazonaws.com/v1/master/d02fedbbc5a68596164208dd24e9b48aa60dadc7/singssai/master.m3u8"
 
 export function Player() {
-  return <VideoPlayer mediaProps={{ src }} />
+  return <VideoPlayer source={src} />
 }
 ```
 
+Use `source` for media loading. Use `mediaProps` only for native video attributes.
+
+```tsx
+<VideoPlayer
+  source={src}
+  mediaProps={{ autoPlay: true, muted: true, playsInline: true }}
+/>
+```
+
+## Playlist Usage
+
+Pass an array to `source` when the player should manage a queue.
+
+```tsx
+import {
+  VideoPlayer,
+  type VideoPlayerAsset,
+} from "@/components/limeplay/video-player/components/media-player"
+
+const playlist: VideoPlayerAsset[] = [
+  {
+    id: "episode-1",
+    poster: "/posters/episode-1.jpg",
+    src: "https://example.com/episode-1.mpd",
+    title: "Episode 1",
+  },
+  {
+    id: "episode-2",
+    poster: "/posters/episode-2.jpg",
+    src: "https://example.com/episode-2.mpd",
+    title: "Episode 2",
+  },
+]
+
+export function Player() {
+  return <VideoPlayer initialIndex={0} source={playlist} />
+}
+```
+
+## Custom Loading
+
+Use `loading.resolveSource` when your app needs signed URLs, token refresh, or source lookup before Shaka loads the asset.
+
+```tsx
+<VideoPlayer
+  source={{ id: "movie-123", title: "Movie" }}
+  loading={{
+    resolveSource: async ({ asset, signal }) => {
+      const response = await fetch(`/api/assets/${asset.id}/source`, { signal })
+      const source = await response.json()
+
+      return {
+        config: source.config,
+        src: source.url,
+      }
+    },
+  }}
+/>
+```
+
 ## Features
 
 - Single-source and playlist-backed loading APIs.
@@ -33,12 +93,14 @@ export function Player() {
 - Timeline scrubbing with buffered progress feedback.
 - Volume, mute, captions, playback rate, and picture-in-picture controls.
 - Shaka-backed playback for HLS, DASH, and DRM-capable streams.
+- Shared `source` and `loading` contract used by all source-driven blocks.
 
 ## Notes
 
 - `VideoPlayer` renders a video element internally. You do not need an `as` prop.
 - Pass `mediaProps` for native video options like `muted`, `playsInline`, or `autoPlay`.
-- Use `resolveSource` when your app needs signed URLs, token refresh, or custom asset loading.
+- Do not pass `mediaProps.src`; pass `source` instead.
+- For the full block loading model, see [Usage](/docs/usage).
 
 ## API Reference
 
diff --git a/apps/www/content/docs/components/media-provider.mdx b/apps/www/content/docs/components/media-provider.mdx
index 3d6b86a9..d2663e87 100644
--- a/apps/www/content/docs/components/media-provider.mdx
+++ b/apps/www/content/docs/components/media-provider.mdx
@@ -117,7 +117,7 @@ function Logger() {
 }
 ```
 
-See [Events](/docs/events) for the full event reference.
+See [Concepts](/docs/concepts#event-and-action-bridge) for the event model.
 
 ## Multi-Instance
 
diff --git a/apps/www/content/docs/concepts.mdx b/apps/www/content/docs/concepts.mdx
index 16663808..0cadaafb 100644
--- a/apps/www/content/docs/concepts.mdx
+++ b/apps/www/content/docs/concepts.mdx
@@ -5,15 +5,17 @@ index: true
 
 The key ideas behind Limeplay's architecture.
 
-## Features
+## Feature Model
 
-Every capability — playback, volume, timeline, captions — is a **feature**. A feature is a self-contained unit that provides:
+Limeplay is built from **features**. A feature owns one capability, such as playback, volume, timeline, playlist, player setup, or asset loading.
 
-- **Store slice** — A namespaced piece of state (e.g. `volume.level`, `playback.paused`)
-- **Setup component** — An internal component that attaches DOM event listeners and syncs state (auto-mounted by `MediaProvider`)
-- **Events** — Typed events emitted when state changes (e.g. `volumechange`, `seek`)
+Each feature can provide:
 
-You compose features with `createMediaKit`:
+- A namespaced store slice, such as `playback.paused` or `volume.level`.
+- A setup component that syncs native media or Shaka Player state.
+- Typed events for state changes, such as `play`, `seek`, or `assetloaded`.
+
+You compose the features you need with `createMediaKit`.
 
 ```tsx title="lib/media.ts"
 "use client"
@@ -26,97 +28,94 @@ import { volumeFeature } from "@/hooks/limeplay/use-volume"
 export const media = createMediaKit({
   features: [mediaFeature(), playbackFeature(), volumeFeature()] as const,
 })
-```
-
-This returns a `MediaProvider` component and typed hooks. Each feature's Setup component is auto-mounted inside `MediaProvider` — no manual wiring required.
 
-### Available Features
+export const { MediaProvider, useMediaApi, useMediaEvents, useMediaStore } =
+  media
+```
 
-| Feature                                                  | Key                | Factory                     | Events                                                           |
-| -------------------------------------------------------- | ------------------ | --------------------------- | ---------------------------------------------------------------- |
-| [Media](/docs/concepts)                                  | `media`            | `mediaFeature()`            | —                                                                |
-| [Player](/docs/hooks/use-player)                         | `player`           | `playerFeature()`           | `playerready`, `playererror`, `playbackerror`, `bufferingchange` |
-| [Playback](/docs/hooks/use-playback)                     | `playback`         | `playbackFeature()`         | `play`, `pause`, `ended`, `buffering`, `statuschange`            |
-| [Volume](/docs/hooks/use-volume)                         | `volume`           | `volumeFeature()`           | `volumechange`, `mute`                                           |
-| [Timeline](/docs/hooks/use-timeline)                     | `timeline`         | `timelineFeature()`         | `timeupdate`, `durationchange`, `seek`                           |
-| [Playlist](/docs/hooks/use-playlist)                     | `playlist`         | `playlistFeature()`         | `playlistchange`                                                 |
-| [Playback Rate](/docs/hooks/use-playback-rate)           | `playbackRate`     | `playbackRateFeature()`     | `ratechange`                                                     |
-| [Picture-in-Picture](/docs/hooks/use-picture-in-picture) | `pictureInPicture` | `pictureInPictureFeature()` | `enterpictureinpicture`, `leavepictureinpicture`                 |
-| [Captions](/docs/hooks/use-captions)                     | `captions`         | `captionsFeature()`         | —                                                                |
-| [Asset](/docs/hooks/use-asset)                           | `asset`            | `assetFeature()`            | —                                                                |
+Use this page to understand the model. Use the [Hooks](/docs/hooks) section when you need exact APIs.
 
 ## Store
 
-State is managed by [Zustand](https://zustand.docs.pmnd.rs/) with [Immer](https://immerjs.github.io/immer/) middleware. Each `MediaProvider` creates an isolated store instance via React Context, so multiple players on the same page maintain independent state.
-
-### Reading State
+Each `MediaProvider` creates an isolated Zustand store. Multiple players on the same page do not share state unless you explicitly wire them together.
 
-Use the typed selector hooks to subscribe to specific fields:
+Read state with selectors so components only re-render for the fields they use.
 
 ```tsx
-// Per-feature convenience hook
-const level = useVolumeStore((s) => s.level)
-const paused = usePlaybackStore((s) => s.paused)
-
-// Or the unified hook from createMediaKit
-const level = media.useMediaStore((s) => s.volume.level)
+const paused = usePlaybackStore((state) => state.paused)
+const volume = useVolumeStore((state) => state.volume)
 ```
 
-Components only re-render when the selected value changes.
-
-### Mutating State
-
-For imperative mutations (effects, callbacks), use the store API:
+For imperative code, use the media API returned by your kit.
 
 ```tsx
-const api = media.useMediaApi()
-
-// Read without subscribing
-api.getState().volume.level
+const api = useMediaApi()
 
-// Mutate with Immer draft
 api.setState(({ volume }) => {
   volume.level = 0.5
 })
 ```
 
-## Event & Action Bridge
-
-Limeplay separates concerns into two bridges:
-
-### Event Bridge
+## Event And Action Bridge
 
-Each feature's Setup component attaches native DOM event listeners to the `<video>` / `<audio>` element and syncs changes into the Zustand store. For example, the playback feature listens to native `play`, `pause`, `ended`, `waiting` events and updates `playback.paused`, `playback.status`, etc.
+Limeplay keeps events and actions separate.
 
-This is automatic — registering a feature in `createMediaKit` handles everything.
+- UI components call actions, such as `playback.togglePaused()` or `timeline.seek()`.
+- Actions update the native media element or Shaka Player.
+- Native events flow back into feature setup components.
+- Feature setup components update the store and emit typed events.
 
-### Action Bridge
+<Mermaid
+  chart="
+flowchart LR
+  UI[UI Component<br/>React] -- action --> Media[Media Element<br/>DOM or Shaka];
+  Media -- native event --> Store[Feature Store<br/>Zustand];
+  Store -- render update --> UI;
+  Store -- typed event --> Events[Media Events];
+"
+/>
 
-UI components call store methods that directly manipulate the native media element. For example, `playback.togglePaused()` calls `mediaElement.play()` or `mediaElement.pause()`. The native element fires events, the Event Bridge captures them, and the store updates — completing the cycle.
+Subscribe to events with `useMediaEvents`.
 
-For high-frequency operations like seeking, both native and React states are updated simultaneously to prevent visual jank.
+```tsx
+const events = useMediaEvents()
 
+React.useEffect(() => {
+  return events.on("play", () => {
+    console.log("playing")
+  })
+}, [events])
 ```
-┌─────────────┐    action     ┌─────────────┐    native event    ┌─────────────┐
-│  UI Component│ ──────────▶ │ Media Element │ ──────────────▶  │ Store (Zustand)│
-│  (React)     │ ◀────────── │ (DOM)         │                   │              │
-└─────────────┘   re-render  └─────────────┘                   └──────────────┘
-```
+
+For exact event names and payloads, use the relevant hook docs. Each feature exports its own event type.
 
 ## Component Hierarchy
 
-```
-MediaProvider            ← Isolated store + event emitter + feature Setup components
-  └─ RootContainer       ← Accessible wrapper, manages control visibility
-      └─ PlayerContainer ← Media element container with aspect ratio
-          ├─ Media       ← Native <video> or <audio> element
-          ├─ ControlsContainer ← Layout for controls (top, middle, bottom)
-          │   ├─ PlaybackControl, VolumeControl, TimelineControl, etc.
-          │   └─ ...
-          └─ FallbackPoster ← Poster image for PiP / loading states
-```
+Most Limeplay players follow this shape. Blocks package this structure for you; custom players can compose the pieces directly.
+
+<Mermaid
+  chart="
+flowchart TD
+  Provider[MediaProvider<br/>Store, events, feature setup] --> Root[RootContainer<br/>Control visibility];
+  Root --> Player[PlayerContainer<br/>Media layout];
+  Player --> Media[Media<br/>video or audio element];
+  Player --> Controls[ControlsContainer];
+  Controls --> Playback[Playback controls];
+  Controls --> Timeline[Timeline controls];
+  Controls --> Volume[Volume controls];
+  Player --> Poster[FallbackPoster];
+"
+/>
+
+## Source Loading
+
+For blocks, pass content through `source` and loading behavior through `loading`. Blocks use [use-playback-source](/docs/hooks/use-playback-source), which calls [use-asset](/docs/hooks/use-asset) internally.
+
+Use `useAsset` directly when you need lower-level source orchestration. Use `usePlayer` directly only when you intentionally want to bypass asset, playlist, preload, and recovery behavior.
+
+See [Usage](/docs/usage) for the full loading model.
 
 ## Core Dependencies
 
-- **[Shaka Player](https://github.com/shaka-project/shaka-player)** — Streaming engine for HLS, DASH, and DRM. Peer dependency you control directly.
-- **[Zustand](https://zustand.docs.pmnd.rs/)** — Lightweight state management (1.2kb) with Immer middleware for immutable updates.
+- [Shaka Player](https://github.com/shaka-project/shaka-player) for HLS, DASH, adaptive bitrate, and DRM-capable playback.
+- [Zustand](https://zustand.docs.pmnd.rs/) and [Immer](https://immerjs.github.io/immer/) for isolated player state.
diff --git a/apps/www/content/docs/events.mdx b/apps/www/content/docs/events.mdx
deleted file mode 100644
index b3cdea0a..00000000
--- a/apps/www/content/docs/events.mdx
+++ /dev/null
@@ -1,117 +0,0 @@
----
-title: Events
-index: true
----
-
-Limeplay provides a typed event emitter for reacting to media state changes. Features emit events automatically — you subscribe to them.
-
-## Subscribing
-
-Access the event emitter via `useMediaEvents`:
-
-```tsx
-import { useMediaEvents } from "@/components/limeplay/media-provider"
-import type { VolumeEvents } from "@/hooks/limeplay/use-volume"
-
-function VolumeLogger() {
-  const events = useMediaEvents<VolumeEvents>()
-
-  React.useEffect(() => {
-    const off = events.on("volumechange", ({ volume, muted }) => {
-      console.log("Volume:", volume, "Muted:", muted)
-    })
-    return off
-  }, [events])
-
-  return null
-}
-```
-
-### One-time Listeners
-
-```tsx
-events.once("playerready", ({ player }) => {
-  // Runs once, then auto-removes
-})
-```
-
-### Unsubscribing
-
-`on()` and `once()` return an unsubscribe function:
-
-```tsx
-const off = events.on("play", () => { ... })
-off() // removes the listener
-```
-
-## Event Reference
-
-### Playback
-
-| Event          | Payload                                            | Emitted When                |
-| -------------- | -------------------------------------------------- | --------------------------- |
-| `play`         | —                                                  | Media starts playing        |
-| `pause`        | —                                                  | Media is paused             |
-| `ended`        | —                                                  | Media reaches the end       |
-| `buffering`    | `{ isBuffering: boolean }`                         | Buffering state changes     |
-| `statuschange` | `{ status: MediaStatus, prevStatus: MediaStatus }` | Playback status transitions |
-
-### Volume
-
-| Event          | Payload                              | Emitted When                       |
-| -------------- | ------------------------------------ | ---------------------------------- |
-| `volumechange` | `{ volume: number, muted: boolean }` | Volume level or mute state changes |
-| `mute`         | `{ muted: boolean }`                 | Mute is toggled                    |
-
-### Timeline
-
-| Event            | Payload                                                       | Emitted When                       |
-| ---------------- | ------------------------------------------------------------- | ---------------------------------- |
-| `timeupdate`     | `{ currentTime: number, duration: number, progress: number }` | Playback position updates (polled) |
-| `durationchange` | `{ duration: number }`                                        | Media duration changes             |
-| `seek`           | `{ from: number, to: number }`                                | User seeks to a new position       |
-
-### Player
-
-| Event             | Payload                    | Emitted When                         |
-| ----------------- | -------------------------- | ------------------------------------ |
-| `playerready`     | `{ player: shaka.Player }` | Shaka Player instance is initialized |
-| `playererror`     | `{ error: Error }`         | Player-level error occurs            |
-| `playbackerror`   | `{ error: Error }`         | Playback-level error occurs          |
-| `bufferingchange` | `{ isBuffering: boolean }` | Player buffering state changes       |
-
-### Playback Rate
-
-| Event        | Payload            | Emitted When           |
-| ------------ | ------------------ | ---------------------- |
-| `ratechange` | `{ rate: number }` | Playback speed changes |
-
-### Picture-in-Picture
-
-| Event                   | Payload | Emitted When    |
-| ----------------------- | ------- | --------------- |
-| `enterpictureinpicture` | —       | Enters PiP mode |
-| `leavepictureinpicture` | —       | Leaves PiP mode |
-
-### Playlist
-
-| Event            | Payload               | Emitted When                  |
-| ---------------- | --------------------- | ----------------------------- |
-| `playlistchange` | `PlaylistChangeEvent` | Current playlist item changes |
-
-`PlaylistChangeEvent` contains `currentIndex`, `currentItem`, `previousIndex`, `previousItem`, and `reason` (`"load"`, `"next"`, `"previous"`, `"skip"`, `"remove"`).
-
-## Typing Events
-
-Each feature exports its event type. Import and pass it to `useMediaEvents` for type-safe subscriptions:
-
-```tsx
-import type { PlaybackEvents } from "@/hooks/limeplay/use-playback"
-import type { TimelineEvents } from "@/hooks/limeplay/use-timeline"
-
-const events = useMediaEvents<PlaybackEvents & TimelineEvents>()
-
-// ✅ Type-safe — autocompletion for event names and payloads
-events.on("statuschange", ({ status, prevStatus }) => { ... })
-events.on("seek", ({ from, to }) => { ... })
-```
diff --git a/apps/www/content/docs/hooks/use-asset.mdx b/apps/www/content/docs/hooks/use-asset.mdx
index 8d4e9f15..b0169e37 100644
--- a/apps/www/content/docs/hooks/use-asset.mdx
+++ b/apps/www/content/docs/hooks/use-asset.mdx
@@ -34,6 +34,7 @@ createMediaKit({
 
 ```tsx
 import { useAsset, type Asset } from "@/hooks/limeplay/use-asset"
+import { usePlaylist } from "@/hooks/limeplay/use-playlist"
 
 interface VideoAsset extends Asset {
   playbackUrl: string
@@ -41,17 +42,26 @@ interface VideoAsset extends Asset {
 }
 
 export function PlaylistController({ assets }: { assets: VideoAsset[] }) {
-  const { currentItem, loadPlaylist, next, previous } = useAsset<VideoAsset>({
-    getAssetId: (asset) => asset.slug,
-    resolveSource: ({ asset }) => ({
-      config: asset.config,
-      src: asset.playbackUrl,
-    }),
-  })
+  const { currentItem, loadSource } = useAsset<VideoAsset>()
+  const { next, previous } = usePlaylist<VideoAsset>()
 
   return (
     <div>
-      <button onClick={() => loadPlaylist(assets)}>Load playlist</button>
+      <button
+        onClick={() =>
+          loadSource(assets, {
+            loading: {
+              getAssetId: (asset) => asset.slug,
+              resolveSource: ({ asset }) => ({
+                config: asset.config,
+                src: asset.playbackUrl,
+              }),
+            },
+          })
+        }
+      >
+        Load playlist
+      </button>
       <button onClick={previous}>Previous</button>
       <button onClick={next}>Next</button>
       <span>{currentItem?.properties.title}</span>
@@ -60,7 +70,17 @@ export function PlaylistController({ assets }: { assets: VideoAsset[] }) {
 }
 ```
 
-Use `loadAsset` for a single item and `loadPlaylist` for a queue. When a playlist advances, `useAsset` loads the active item and can preload the next item.
+Use `loadSource` for the public source contract: a URL string, one asset, or an asset array. Use `loadAsset` and `loadPlaylist` when you are building lower-level controls that already know which asset or queue should be loaded.
+
+`useAsset()` does not accept options. Loading configuration is session-local and belongs to `loadSource`, `loadPlaylist`, or the `loading` prop on a block. The latest explicit load session wins.
+
+`sourceType` reports the active loading mode as `"asset"`, `"playlist"`, or `null` before a source has been selected. Use it to render mode-specific controls:
+
+```tsx
+const { sourceType } = useAsset()
+
+const showPlaylistControls = sourceType === "playlist"
+```
 
 ### Asset Interface
 
@@ -80,20 +100,75 @@ If `id` is omitted, `useAsset` derives one from `getAssetId` or `src`. Assets wi
 Use `resolveSource` when the playable source is not stored directly on `asset.src`.
 
 ```tsx
-useAsset({
-  resolveSource: async ({ asset, operation, signal }) => {
-    const response = await fetch(`/api/assets/${asset.id}/source`, { signal })
-    const source = await response.json()
-
-    return {
-      config: source.config,
-      src: source.url,
-    }
+const { loadSource } = useAsset()
+
+loadSource(
+  { id: "movie-123", title: "Movie" },
+  {
+    loading: {
+      resolveSource: async ({ asset, signal }) => {
+        const response = await fetch(`/api/assets/${asset.id}/source`, {
+          signal,
+        })
+        const source = await response.json()
+
+        return {
+          config: source.config,
+          src: source.url,
+        }
+      },
+    },
+  }
+)
+```
+
+`resolveSource` is used by the default load and preload paths. Use `loader.load` or `loader.preload` when loading and preloading need different behavior.
+
+### Recovery
+
+Use `recover.loadError` and `recover.playbackError` to decide how Limeplay should recover from failures.
+
+```tsx
+import { AssetRecoveryAction, useAsset } from "@/hooks/limeplay/use-asset"
+
+const { loadSource } = useAsset()
+
+loadSource(playlist, {
+  loading: {
+    maxRetries: 2,
+    recover: {
+      loadError: (_asset, _error, { hasNext, retryCount }) => {
+        if (retryCount < 2) return AssetRecoveryAction.Retry
+        return hasNext ? AssetRecoveryAction.Skip : AssetRecoveryAction.Stop
+      },
+      playbackError: async (_asset, _error, { currentTime }) => ({
+        action: AssetRecoveryAction.Reload,
+        startTime: currentTime,
+      }),
+    },
   },
 })
 ```
 
-`operation` is `"load"` or `"preload"`, so source endpoints can avoid expensive work during preloading when needed.
+Lifecycle notifications are media events, not `UseAssetOptions` callbacks.
+
+```tsx
+import { useEffect } from "react"
+
+import { useMediaEvents } from "@/components/limeplay/media-provider"
+
+export function AssetEventsLogger() {
+  const events = useMediaEvents()
+
+  useEffect(() => {
+    return events.on("assetloaderror", ({ asset, error }) => {
+      console.error("Asset failed", asset.id, error)
+    })
+  }, [events])
+
+  return null
+}
+```
 
 ### Options
 
@@ -111,7 +186,7 @@ useAsset({
 
 ## Store
 
-`assetFeature` adds a store slice that tracks active options, load cancellation, retry state, and preload cancellation.
+`assetFeature` adds a store slice that tracks the active load session, source type, load cancellation, retry state, and preload cancellation.
 
 ### State
 
@@ -129,11 +204,11 @@ useAsset({
 
 ## Events
 
-`useAsset` listens to player and playlist events instead of exposing a separate event emitter.
+`useAsset` emits asset lifecycle events through the shared media event emitter.
 
 <AutoTypeTable
   path="./registry/default/hooks/use-asset.ts"
-  name="UseAssetEvents"
+  name="AssetEvents"
 />
 
-`useAsset` orchestrates `usePlayer` and `usePlaylist`. It owns load cancellation, playlist-driven loading, preloading, auto-advance on playback end, and error recovery.
+`useAsset` orchestrates `usePlayer` and `usePlaylist`. It owns load cancellation, playlist-driven loading, preloading, auto-advance on playback end, and error recovery. Queue mutation methods still live on [`usePlaylist`](/docs/hooks/use-playlist).
diff --git a/apps/www/content/docs/hooks/use-playback-source.mdx b/apps/www/content/docs/hooks/use-playback-source.mdx
index 6df75bd6..3838cf4f 100644
--- a/apps/www/content/docs/hooks/use-playback-source.mdx
+++ b/apps/www/content/docs/hooks/use-playback-source.mdx
@@ -16,17 +16,17 @@ npx shadcn add @limeplay/use-playback-source
 
 ## Usage
 
-Use `PlaybackSourceController` inside a block to load exactly one source model: `asset`, `playlist`, or `mediaSrc`.
+Use `PlaybackSourceController` inside a block to normalize the block's `source` prop and pass it into `useAsset().loadSource(...)` after the Shaka player is ready.
 
 ```tsx
 import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"
 
 export function SourceController({ src }: { src?: string }) {
-  return <PlaybackSourceController mediaSrc={src} />
+  return <PlaybackSourceController source={src} />
 }
 ```
 
-For typed assets, pass `asset`, `playlist`, `getAssetId`, and `resolveSource` through to `useAsset`.
+For typed assets, pass one asset or an asset array to `source`, then pass source resolution and recovery policies through `loading`.
 
 ```tsx
 import type { Asset } from "@/hooks/limeplay/use-asset"
@@ -40,17 +40,28 @@ interface VideoAsset extends Asset {
 export function VideoSource({ playlist }: { playlist: VideoAsset[] }) {
   return (
     <PlaybackSourceController
-      getAssetId={(asset) => asset.slug}
-      playlist={playlist}
-      resolveSource={({ asset }) => asset.playbackUrl}
+      source={playlist}
+      loading={{
+        getAssetId: (asset) => asset.slug,
+        resolveSource: ({ asset }) => asset.playbackUrl,
+      }}
     />
   )
 }
 ```
 
+Use `sourceKey` when the source is recreated often but represents the same logical media session.
+
+```tsx
+<PlaybackSourceController
+  source={playlist}
+  sourceKey={playlist.map((item) => item.slug).join("|")}
+/>
+```
+
 ## Feature Registration
 
-`use-playback-source` is a controller helper, not a store feature. Register `assetFeature` with your media kit, then mount `PlaybackSourceController` inside the player tree.
+`use-playback-source` is an opinionated controller helper, not a store feature. Register `assetFeature` with your media kit, then mount `PlaybackSourceController` inside the player tree.
 
 ```tsx title="lib/media.ts"
 "use client"
@@ -72,10 +83,11 @@ export const media = createMediaKit({
 ```
 
 ```tsx
+import type { Asset } from "@/hooks/limeplay/use-asset"
 import type { UsePlaybackSourceOptions } from "@/hooks/limeplay/use-playback-source"
 import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"
 
-export function Source<TAsset extends { src?: string }>(
+export function Source<TAsset extends Asset>(
   props: UsePlaybackSourceOptions<TAsset>
 ) {
   return <PlaybackSourceController {...props} />
@@ -86,7 +98,7 @@ export function Source<TAsset extends { src?: string }>(
 
 | State | Owner | Description |
 | ----- | ----- | ----------- |
-| `asset`, `playlist`, `mediaSrc` | `UsePlaybackSourceOptions` | Source inputs normalized by `PlaybackSourceController`. |
+| `source` | `UsePlaybackSourceOptions` | Source string, one asset, or asset array normalized by `PlaybackSourceController`. |
 | `sourceKey` | `UsePlaybackSourceOptions` | Optional stable key used to avoid duplicate playlist loads. |
 | `player` | `use-player` | The current Shaka player instance required before loading. |
 
@@ -95,15 +107,15 @@ export function Source<TAsset extends { src?: string }>(
 | Action | Symbol | Description |
 | ------ | ------ | ----------- |
 | Load source | `PlaybackSourceController` | Mounts a controller that calls `usePlaybackSource`. |
-| Normalize options | `usePlaybackSource` | Converts one asset, a playlist, or `mediaSrc` into a playlist load. |
-| Load playlist | `loadPlaylist` from `useAsset` | Receives normalized assets and the configured `initialIndex`. |
+| Normalize options | `usePlaybackSource` | Converts a source string, one asset, or an asset array into a load session. |
+| Load source | `loadSource` from `useAsset` | Receives the source plus `loading`, `initialIndex`, `sourceKey`, and `sourceType`. |
 
 ## Events
 
 | Event | Emitted by | Description |
 | ----- | ---------- | ----------- |
 | `playlistchange` | `use-playlist` | Fired after the normalized source is loaded into the queue and the active item changes. |
-| `playerready` | `use-player` | The controller waits for a player instance before calling `loadPlaylist`. |
+| `playerready` | `use-player` | The controller waits for a player instance before calling `loadSource`. |
 | None | `use-playback-source` | The hook itself does not emit custom events. |
 
 ## API Reference
diff --git a/apps/www/content/docs/hooks/use-playback.mdx b/apps/www/content/docs/hooks/use-playback.mdx
index 241fc863..eb4e777f 100644
--- a/apps/www/content/docs/hooks/use-playback.mdx
+++ b/apps/www/content/docs/hooks/use-playback.mdx
@@ -60,7 +60,7 @@ const togglePaused = usePlaybackStore((s) => s.togglePaused)
 
 ## Events
 
-Emits to the [event system](/docs/events):
+Emits to the [event system](/docs/concepts#event-and-action-bridge):
 
 | Event          | Payload                  | When                    |
 | -------------- | ------------------------ | ----------------------- |
diff --git a/apps/www/content/docs/hooks/use-player.mdx b/apps/www/content/docs/hooks/use-player.mdx
index 82b2b7f1..90dacb99 100644
--- a/apps/www/content/docs/hooks/use-player.mdx
+++ b/apps/www/content/docs/hooks/use-player.mdx
@@ -1,6 +1,6 @@
 ---
 title: use-player
-description: Feature for Shaka Player initialization, asset loading, and preloading.
+description: Low-level feature for Shaka Player initialization and manual load/preload control.
 ---
 
 ## Installation
@@ -42,7 +42,7 @@ const containerRef = usePlayerStore((s) => s.containerRef)
 
 ## usePlayer Hook
 
-The `usePlayer` hook provides methods to load and preload assets:
+The `usePlayer` hook provides low-level methods to load and preload assets. Prefer [`useAsset`](/docs/hooks/use-asset) or block `source` props for most application code because they include playlist state, cancellation, preloading lifecycle, and recovery policies.
 
 ```tsx
 import { usePlayer } from "@/hooks/limeplay/use-player"
@@ -78,9 +78,9 @@ const { load, preload, player } = usePlayer({
 
 | Event             | Payload           | When                     |
 | ----------------- | ----------------- | ------------------------ |
-| `playerready`     | `{ player }`      | Shaka Player initialized |
+| `playerready`     | `void`            | Shaka Player initialized |
 | `playererror`     | `{ error }`       | Player-level error       |
-| `playbackerror`   | `Error`           | Playback error           |
+| `playbackerror`   | `{ error, currentTime }` | Playback error    |
 | `bufferingchange` | `{ isBuffering }` | Buffering state changes  |
 
 ### Debug Mode
diff --git a/apps/www/content/docs/quick-start.mdx b/apps/www/content/docs/quick-start.mdx
index 3f4b31cf..6dabe69e 100644
--- a/apps/www/content/docs/quick-start.mdx
+++ b/apps/www/content/docs/quick-start.mdx
@@ -23,7 +23,7 @@ The fastest path — install a complete, ready-to-use player:
 npx shadcn add @limeplay/video-player
 ```
 
-This gives you a full-featured video player with playback controls, volume, timeline, captions, and more. Customize it from your `components/` directory.
+This gives you a full-featured video player with playback controls, volume, timeline, captions, and more. Customize it from your `components/` directory. For more details, see the [video player documentation](/blocks/video-player).
 
 ## Option B: Build from Scratch
 
@@ -35,7 +35,7 @@ This gives you a full-featured video player with playback controls, volume, time
 Install the core provider and the features you need:
 
 ```npm
-npx shadcn add @limeplay/media-provider @limeplay/use-playback @limeplay/use-volume @limeplay/use-timeline @limeplay/use-player
+npx shadcn add @limeplay/media-provider @limeplay/use-player @limeplay/use-playback @limeplay/use-volume @limeplay/use-timeline @limeplay/use-playlist @limeplay/use-asset @limeplay/use-playback-source
 ```
 
 Create a `lib/media.ts` file that composes your features:
@@ -44,8 +44,10 @@ Create a `lib/media.ts` file that composes your features:
 "use client"
 
 import { mediaFeature } from "@/hooks/limeplay/use-media"
+import { assetFeature } from "@/hooks/limeplay/use-asset"
 import { playerFeature } from "@/hooks/limeplay/use-player"
 import { playbackFeature } from "@/hooks/limeplay/use-playback"
+import { playlistFeature } from "@/hooks/limeplay/use-playlist"
 import { volumeFeature } from "@/hooks/limeplay/use-volume"
 import { timelineFeature } from "@/hooks/limeplay/use-timeline"
 import { createMediaKit } from "@/components/limeplay/media-provider"
@@ -55,6 +57,8 @@ export const media = createMediaKit({
     mediaFeature(),
     playerFeature(),
     playbackFeature(),
+    playlistFeature(),
+    assetFeature(),
     volumeFeature(),
     timelineFeature(),
   ] as const,
@@ -87,10 +91,12 @@ import { PlaybackControl } from "@/components/limeplay/playback-control"
 import * as Volume from "@/components/limeplay/volume-control"
 import * as Timeline from "@/components/limeplay/timeline-control"
 import * as Layout from "@/components/limeplay/player-layout"
+import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"
 
-export function MediaPlayer() {
+export function MediaPlayer({ src }: { src: string }) {
   return (
     <MediaProvider>
+      <PlaybackSourceController source={src} />
       <Layout.PlayerContainer>
         <Media as="video" />
         <Layout.ControlsContainer>
@@ -115,32 +121,9 @@ export function MediaPlayer() {
 </Step>
 <Step>
 
-### Load content
-
-Pass a source to your player. The simplest approach is loading via [`usePlayer`](/docs/hooks/use-player) inside your `MediaPlayer`:
-
-```tsx title="components/media-player.tsx"
-"use client"
-
-import { usePlayer } from "@/hooks/limeplay/use-player"
-import { useMediaEvents } from "@/lib/media"
-// ... other imports from Step 3
-
-export function MediaPlayer({ src }: { src: string }) {
-  const { player } = usePlayer()
-  const events = useMediaEvents()
-
-  React.useEffect(() => {
-    return events.on("playerready", ({ player }) => {
-      player.load(src)
-    })
-  }, [events, src])
-
-  return <MediaProvider>{/* ... same layout as Step 3 */}</MediaProvider>
-}
-```
+### Render with content
 
-Then render it with a source:
+Render your player with a source. `PlaybackSourceController` passes this source through [`useAsset`](/docs/hooks/use-asset), so the same pattern works for URLs, asset objects, and playlists.
 
 ```tsx title="app/page.tsx"
 import { MediaPlayer } from "@/components/media-player"
@@ -152,7 +135,7 @@ export default function Page() {
 }
 ```
 
-For playlist management, error handling, and preloading, see [`useAsset`](/docs/hooks/use-asset).
+For blocks, custom loading, playlists, error recovery, and preloading, see [Usage](/docs/usage).
 
 </Step>
 </Steps>
diff --git a/apps/www/content/docs/usage.mdx b/apps/www/content/docs/usage.mdx
new file mode 100644
index 00000000..5c7079d2
--- /dev/null
+++ b/apps/www/content/docs/usage.mdx
@@ -0,0 +1,289 @@
+---
+title: Usage
+description: How to use Limeplay blocks, source loading, and asset orchestration.
+---
+
+Limeplay blocks are ready-to-use players built on the same asset loading contract. Pass playable content through `source`, pass native media attributes through `mediaProps`, and customize loading behavior through `loading`.
+
+## Start with a Block
+
+Install a block and render it with a source.
+
+```npm
+npx shadcn add @limeplay/video-player
+```
+
+```tsx title="components/player.tsx"
+import { VideoPlayer } from "@/components/limeplay/video-player/components/media-player"
+
+export function Player() {
+  return (
+    <VideoPlayer
+      source="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"
+      mediaProps={{ autoPlay: true, muted: true, playsInline: true }}
+    />
+  )
+}
+```
+
+For playlist-style blocks, pass an array of assets to the same `source` prop.
+
+```tsx title="components/audio-player.tsx"
+import {
+  AudioPlayer,
+  type AudioPlayerAsset,
+} from "@/components/limeplay/audio-player/components/media-player"
+
+const tracks: AudioPlayerAsset[] = [
+  {
+    id: "soundhelix-1",
+    poster: "https://placehold.co/160x160/png",
+    src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
+    title: "SoundHelix Song 1",
+  },
+]
+
+export function Player() {
+  return <AudioPlayer source={tracks} />
+}
+```
+
+Do not pass `src` through `mediaProps`. Blocks reserve the native media element for Limeplay and Shaka Player. Use `source` for media loading and `mediaProps` for native options such as `autoPlay`, `muted`, `loop`, `controls`, `playsInline`, and `className`.
+
+## Block Props
+
+Every source-driven block should expose the same loading props.
+
+| Prop | Purpose |
+| --- | --- |
+| `source` | A source string, one asset object, or an array of asset objects. |
+| `loading` | Source resolution, custom load/preload handlers, recovery policies, and asset ID rules. |
+| `sourceKey` | Stable key for dynamic sources when object identity changes between renders. |
+| `autoLoad` | Whether the block loads `source` automatically after the Shaka player is ready. Defaults to `true`. |
+| `initialIndex` | Initial item index when `source` is a playlist. |
+| `mediaProps` | Native media attributes except `src` and `as`. |
+| `children` | Optional custom UI rendered inside or alongside the block, depending on the block. |
+
+## Opinionated and Unopinionated APIs
+
+Limeplay has two source-loading layers.
+
+| Layer | Use it when | What it does |
+| --- | --- | --- |
+| Opinionated blocks and `usePlaybackSource` | You are building reusable player blocks. | Normalizes `source`, waits for the player, deduplicates loads with `sourceKey`, and calls `useAsset().loadSource(...)`. |
+| Unopinionated `useAsset` | You need app-specific orchestration. | Gives direct access to `loadSource`, `loadAsset`, `loadPlaylist`, `preloadAsset`, queue read state, and recovery behavior. |
+
+Blocks should usually wrap `PlaybackSourceController` from `use-playback-source`. App code that needs imperative control can call `useAsset` directly inside the same `MediaProvider` tree.
+
+```tsx title="components/source-controller.tsx"
+import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"
+
+export function SourceController({ src }: { src: string }) {
+  return <PlaybackSourceController source={src} />
+}
+```
+
+```tsx title="components/custom-actions.tsx"
+import { useAsset } from "@/hooks/limeplay/use-asset"
+
+export function CustomActions() {
+  const { currentItem, loadSource, preloadNext } = useAsset()
+
+  return (
+    <div>
+      <button onClick={() => loadSource("/trailers/main.mpd")}>Load</button>
+      <button onClick={() => void preloadNext()}>Preload next</button>
+      <span>{currentItem?.properties.title}</span>
+    </div>
+  )
+}
+```
+
+Use `usePlayer` directly only when you want to bypass asset, playlist, preload, and recovery orchestration and call Shaka Player yourself.
+
+## Source Shapes
+
+`source` accepts three shapes.
+
+```tsx
+<VideoPlayer source="https://example.com/stream.mpd" />
+```
+
+```tsx
+<VideoPlayer
+  source={{
+    id: "feature-film",
+    poster: "/poster.jpg",
+    src: "https://example.com/stream.m3u8",
+    title: "Feature Film",
+  }}
+/>
+```
+
+```tsx
+<VideoPlayer
+  initialIndex={1}
+  source={[
+    { id: "episode-1", src: "https://example.com/episode-1.mpd" },
+    { id: "episode-2", src: "https://example.com/episode-2.mpd" },
+  ]}
+/>
+```
+
+Assets can omit `src` when `loading.resolveSource` or `loading.loader.load` provides the playable URL.
+
+## Default Loaders
+
+The default loader covers the common path for HLS, DASH, progressive media, Shaka config, playlists, and recovery.
+
+| Capability | Default behavior |
+| --- | --- |
+| Single URL | A string source becomes `{ src }` and is loaded with `player.load(src)`. |
+| Asset URL | `asset.src` is loaded with Shaka Player. |
+| Shaka config | `asset.config` and resolved source config are applied before loading. |
+| Source resolution | `loading.resolveSource` can return a URL or `{ src, config }`. |
+| Preloaded source | If a preload manager exists for the asset ID, loading consumes it. |
+| Playlist | Arrays are normalized into the playlist queue and the active item is loaded. |
+| Asset IDs | IDs come from `asset.id`, then `loading.getAssetId`, then a hash of `asset.src`. |
+| Cancellation | Starting a new load aborts the previous load session. |
+| Load errors | By default, Limeplay skips to the next playlist item when one exists; otherwise it sets playback error state. |
+| Playback errors | By default, Limeplay reloads the current asset from the current playback time. |
+| Ended | Limeplay advances to the next playlist item when one exists. |
+
+Use `loading` when the default loader needs app-specific behavior.
+
+```tsx
+<VideoPlayer
+  source={{ id: "movie-123", title: "Movie" }}
+  loading={{
+    resolveSource: async ({ asset, signal }) => {
+      const response = await fetch(`/api/assets/${asset.id}/source`, { signal })
+      const source = await response.json()
+
+      return {
+        config: source.config,
+        src: source.url,
+      }
+    },
+  }}
+/>
+```
+
+Use `loading.loader` only when you need to fully control Shaka loading or preloading. Call `loadDefault` or `preloadDefault` to reuse Limeplay's built-in behavior after your custom work.
+
+```tsx
+<VideoPlayer
+  source={{ id: "protected", src: "https://example.com/manifest.mpd" }}
+  loading={{
+    loader: {
+      load: async ({ asset, loadDefault, player, signal }) => {
+        if (signal.aborted) return
+
+        player.configure({
+          drm: {
+            servers: {
+              "com.widevine.alpha": "/api/license/widevine",
+            },
+          },
+        })
+
+        await loadDefault(asset.src)
+      },
+    },
+  }}
+/>
+```
+
+## Recovery Policies
+
+Recovery policies decide what Limeplay should do after failures. Notifications belong to media events, not `loading` callbacks.
+
+```tsx
+import { AssetRecoveryAction } from "@/hooks/limeplay/use-asset"
+
+<VideoPlayer
+  source={playlist}
+  loading={{
+    maxRetries: 2,
+    recover: {
+      loadError: (_asset, _error, { hasNext, retryCount }) => {
+        if (retryCount < 2) return AssetRecoveryAction.Retry
+        return hasNext ? AssetRecoveryAction.Skip : AssetRecoveryAction.Stop
+      },
+      playbackError: async (_asset, _error, { currentTime }) => ({
+        action: AssetRecoveryAction.Reload,
+        startTime: currentTime,
+      }),
+    },
+  }}
+/>
+```
+
+Subscribe to asset lifecycle events with `useMediaEvents` from your media kit.
+
+```tsx
+import { useEffect } from "react"
+
+import { useMediaEvents } from "@/components/limeplay/video-player/lib/media-kit"
+
+export function AssetLogger() {
+  const events = useMediaEvents()
+
+  useEffect(() => {
+    return events.on("assetloaded", ({ asset }) => {
+      console.info("Loaded", asset.title ?? asset.id)
+    })
+  }, [events])
+
+  return null
+}
+```
+
+## Building New Blocks
+
+When you build a new block, keep the public loading API consistent with the existing blocks.
+
+```tsx title="components/custom-video-player.tsx"
+"use client"
+
+import type React from "react"
+import type { Asset, PlayerSource, UseAssetOptions } from "@/hooks/limeplay/use-asset"
+
+import { MediaProvider } from "@/components/limeplay/custom-video-player/lib/media-kit"
+import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"
+import { Media } from "@/components/limeplay/media"
+
+interface CustomVideoAsset extends Asset {
+  title?: string
+}
+
+interface CustomVideoPlayerProps {
+  autoLoad?: boolean
+  loading?: UseAssetOptions<CustomVideoAsset>
+  mediaProps?: Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "as" | "src">
+  source?: PlayerSource<CustomVideoAsset>
+  sourceKey?: string
+}
+
+export function CustomVideoPlayer({
+  autoLoad,
+  loading,
+  mediaProps,
+  source,
+  sourceKey,
+}: CustomVideoPlayerProps) {
+  return (
+    <MediaProvider>
+      <PlaybackSourceController
+        autoLoad={autoLoad}
+        loading={loading}
+        source={source}
+        sourceKey={sourceKey}
+      />
+      <Media {...mediaProps} as="video" />
+    </MediaProvider>
+  )
+}
+```
+
+This keeps future blocks predictable: consumers learn one `source` and `loading` contract, while block authors can still add block-specific UI props.
diff --git a/apps/www/package.json b/apps/www/package.json
index 29a56099..6f40d822 100644
--- a/apps/www/package.json
+++ b/apps/www/package.json
@@ -10,8 +10,9 @@
     "registry:dev": "REGISTRY_HOST=http://localhost:3000 bun --watch run ./scripts/registry-dev.mts --watch",
     "validate:registries": "bun run ./scripts/validate-registries.ts",
     "test:registry-install": "bun run scripts/test-registry-install.ts",
+    "docs:generate": "fumadocs-mdx",
     "install:vercel": "bash ./scripts/vercel-install.sh",
-    "postinstall": "fumadocs-mdx"
+    "postinstall": "true"
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^1.0.39",
@@ -38,6 +39,7 @@
     "@vercel/speed-insights": "^1.3.1",
     "ai": "^5.0.101",
     "async-retry": "^1.3.3",
+    "beautiful-mermaid": "^1.1.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
diff --git a/apps/www/registry/default/blocks/audio-player/components/audio-source.tsx b/apps/www/registry/default/blocks/audio-player/components/audio-source.tsx
index 9253865c..c78c3711 100644
--- a/apps/www/registry/default/blocks/audio-player/components/audio-source.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/audio-source.tsx
@@ -4,41 +4,51 @@ import * as React from "react"
 
 import type {
   Asset,
-  GetAssetId,
-  ResolveSource,
+  PlayerSource,
   UseAssetOptions,
 } from "@/registry/default/hooks/use-asset"
 
+import { AssetRecoveryAction } from "@/registry/default/hooks/use-asset"
 import { PlaybackSourceController } from "@/registry/default/hooks/use-playback-source"
 
+export interface AudioAssetDisplayMetadata {
+  poster?: string
+  subtitle?: string
+  title: string
+}
+
 export interface AudioPlayerAsset extends Asset {
+  albumName?: string
+  artistName?: string
+  artwork?: {
+    templateUrl?: string
+    url?: string
+  }
   description?: string
   duration?: number
+  features?: string[]
   genre?: string
+  group?: string
+  images?: {
+    backdrop?: string
+    poster?: string
+  }
+  name?: string
   playbackUrls?: PlaybackUrls
   poster?: string
   releaseYear?: number | string
+  subtitle?: string
   title?: string
   year?: number | string
 }
 
-export interface AudioSourceContextValue {
-  items: AudioPlayerAsset[]
-}
-
 export interface AudioSourceProviderProps {
-  asset?: AudioPlayerAsset
-  assetOptions?: Omit<
-    UseAssetOptions<AudioPlayerAsset>,
-    "getAssetId" | "resolveSource"
-  >
   autoLoad?: boolean
   children?: React.ReactNode
-  getAssetId?: GetAssetId<AudioPlayerAsset>
   initialIndex?: number
-  mediaSrc?: string
-  playlist?: AudioPlayerAsset[]
-  resolveSource?: ResolveSource<AudioPlayerAsset>
+  loading?: UseAssetOptions<AudioPlayerAsset>
+  source?: PlayerSource<AudioPlayerAsset>
+  sourceKey?: string
 }
 
 export interface PlaybackUrls {
@@ -46,125 +56,134 @@ export interface PlaybackUrls {
   secondary?: string
 }
 
-const AudioSourceContext = React.createContext<AudioSourceContextValue | null>(
-  null
-)
-
 interface RawPlaybackResponse {
   expires_at: string
   url: string
 }
 
 export function AudioSourceProvider({
-  asset,
-  assetOptions,
   autoLoad = true,
   children,
-  getAssetId,
   initialIndex,
-  mediaSrc,
-  playlist,
-  resolveSource,
+  loading,
+  source,
+  sourceKey,
 }: AudioSourceProviderProps) {
-  const items = React.useMemo(() => {
-    if (playlist) return playlist
-    if (asset) return [asset]
-    return []
-  }, [asset, playlist])
-
-  const resolvedAssetOptions = React.useMemo<UseAssetOptions<AudioPlayerAsset>>(
+  const resolvedLoading = React.useMemo<UseAssetOptions<AudioPlayerAsset>>(
     () => ({
-      onLoadError: (_asset: AudioPlayerAsset, _error: unknown, { hasNext }) => {
-        return hasNext ? "skip" : "stop"
+      ...loading,
+      getAssetId: (asset, context) =>
+        loading?.getAssetId?.(asset, context) ??
+        asset.id ??
+        asset.src ??
+        asset.playbackUrls?.primary,
+      recover: {
+        loadError: (_asset: AudioPlayerAsset, _error: unknown, { hasNext }) => {
+          return hasNext ? AssetRecoveryAction.Skip : AssetRecoveryAction.Stop
+        },
+        playbackError: async (
+          _asset: AudioPlayerAsset,
+          error: Error,
+          { currentTime }: { currentTime: number }
+        ) => {
+          if (isNetworkError(error)) {
+            return {
+              action: AssetRecoveryAction.Reload,
+              startTime: currentTime,
+            }
+          }
+
+          return { action: AssetRecoveryAction.Skip }
+        },
+        ...loading?.recover,
       },
-      onPlaybackError: async (
-        _asset: AudioPlayerAsset,
-        error: Error,
-        { currentTime }: { currentTime: number }
-      ): Promise<
-        | { action: "reload"; startTime?: number }
-        | { action: "skip" }
-        | { action: "stop" }
-      > => {
-        if (isNetworkError(error)) {
-          return { action: "reload", startTime: currentTime }
+      resolveSource: async (context) => {
+        if (loading?.resolveSource) return loading.resolveSource(context)
+
+        const { asset, signal } = context
+        if (asset.src) {
+          return {
+            config: asset.config,
+            src: asset.src,
+          }
         }
 
-        return { action: "skip" }
-      },
-      ...assetOptions,
-    }),
-    [assetOptions]
-  )
-  const resolvedGetAssetId = React.useCallback<GetAssetId<AudioPlayerAsset>>(
-    (asset, context) =>
-      getAssetId?.(asset, context) ??
-      asset.id ??
-      asset.src ??
-      asset.playbackUrls?.primary,
-    [getAssetId]
-  )
-  const resolvedSource = React.useCallback<ResolveSource<AudioPlayerAsset>>(
-    async (context) => {
-      if (resolveSource) return resolveSource(context)
+        if (!asset.playbackUrls?.primary) {
+          throw new Error(
+            "AudioPlayerAsset requires src or playbackUrls.primary"
+          )
+        }
+
+        const src = await fetchPlaybackUrl(asset.playbackUrls.primary, signal)
+        if (signal.aborted) {
+          throw new DOMException(
+            "Playback source request aborted",
+            "AbortError"
+          )
+        }
 
-      const { asset, signal } = context
-      if (asset.src) {
         return {
           config: asset.config,
-          src: asset.src,
+          src,
         }
-      }
-
-      if (!asset.playbackUrls?.primary) {
-        throw new Error("AudioPlayerAsset requires src or playbackUrls.primary")
-      }
-
-      const src = await fetchPlaybackUrl(asset.playbackUrls.primary, signal)
-      if (signal.aborted) {
-        throw new DOMException("Playback source request aborted", "AbortError")
-      }
-
-      return {
-        config: asset.config,
-        src,
-      }
-    },
-    [resolveSource]
-  )
-
-  const value = React.useMemo(
-    () => ({
-      items,
+      },
     }),
-    [items]
+    [loading]
   )
 
   return (
-    <AudioSourceContext.Provider value={value}>
+    <>
       <PlaybackSourceController
-        asset={asset}
-        assetOptions={resolvedAssetOptions}
         autoLoad={autoLoad}
-        getAssetId={resolvedGetAssetId}
         initialIndex={initialIndex}
-        mediaSrc={mediaSrc}
-        playlist={playlist}
-        resolveSource={resolvedSource}
+        loading={resolvedLoading}
+        source={source}
+        sourceKey={sourceKey}
       />
       {children}
-    </AudioSourceContext.Provider>
+    </>
   )
 }
 
-export function useAudioSource() {
-  const context = React.useContext(AudioSourceContext)
-
-  if (!context) {
-    throw new Error("Missing AudioSourceProvider")
+export function getAudioAssetMetadata(
+  asset: AudioPlayerAsset | null | undefined,
+  fallbackTitle = "Unknown Title"
+): AudioAssetDisplayMetadata {
+  if (!asset) {
+    return {
+      title: fallbackTitle,
+    }
   }
 
-  return context
+  const releaseYear = asset.releaseYear ?? asset.year
+  const artistAlbum = joinDisplayParts([asset.artistName, asset.albumName])
+  const genreYear = joinDisplayParts([asset.genre, releaseYear])
+  const streamLabel = getStreamLabel(asset)
+
+  return {
+    poster:
+      firstNonEmpty(
+        asset.poster,
+        getArtworkUrl(asset.artwork),
+        asset.images?.poster,
+        asset.images?.backdrop
+      ) ?? undefined,
+    subtitle:
+      firstNonEmpty(
+        artistAlbum,
+        genreYear,
+        asset.subtitle,
+        streamLabel,
+        asset.description
+      ) ?? undefined,
+    title:
+      firstNonEmpty(
+        asset.title,
+        asset.name,
+        asset.albumName,
+        asset.description
+      ) ?? fallbackTitle,
+  }
 }
 
 async function fetchPlaybackUrl(
@@ -183,6 +202,39 @@ async function fetchPlaybackUrl(
   return data.url
 }
 
+function firstNonEmpty(
+  ...values: (null | number | string | undefined)[]
+): string | undefined {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return String(value)
+    }
+
+    if (typeof value !== "string") continue
+
+    const trimmed = value.trim()
+    if (trimmed) return trimmed
+  }
+
+  return undefined
+}
+
+function getArtworkUrl(
+  artwork: AudioPlayerAsset["artwork"]
+): string | undefined {
+  const url = firstNonEmpty(artwork?.url, artwork?.templateUrl)
+  if (!url) return undefined
+
+  return url
+    .replaceAll("{w}", "80")
+    .replaceAll("{h}", "80")
+    .replaceAll("{f}", "jpg")
+}
+
+function getStreamLabel(asset: AudioPlayerAsset): string | undefined {
+  return joinDisplayParts([asset.group, ...(asset.features ?? [])])
+}
+
 function isNetworkError(error: unknown) {
   return (
     error &&
@@ -191,3 +243,13 @@ function isNetworkError(error: unknown) {
     (error as { category: number }).category === 1
   )
 }
+
+function joinDisplayParts(
+  values: (null | number | string | undefined)[]
+): string | undefined {
+  const parts = values
+    .map((value) => firstNonEmpty(value))
+    .filter((value): value is string => Boolean(value))
+
+  return parts.length > 0 ? parts.join(" • ") : undefined
+}
diff --git a/apps/www/registry/default/blocks/audio-player/components/controls.tsx b/apps/www/registry/default/blocks/audio-player/components/controls.tsx
index b9f6c5e3..ecfef831 100644
--- a/apps/www/registry/default/blocks/audio-player/components/controls.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/controls.tsx
@@ -1,3 +1,5 @@
+"use client"
+
 import { ActionControls } from "@/registry/default/blocks/audio-player/components/action-controls"
 import { TimeLabels } from "@/registry/default/blocks/audio-player/components/fixed-timeline-control"
 import { PlaybackControls } from "@/registry/default/blocks/audio-player/components/playback-controls"
@@ -8,12 +10,22 @@ import {
 import { Playlist } from "@/registry/default/blocks/audio-player/components/playlist"
 import { TrackInfo } from "@/registry/default/blocks/audio-player/components/track-info"
 import { VolumeControl } from "@/registry/default/blocks/audio-player/components/volume-group-control"
+import {
+  AssetSourceType,
+  useAssetStore,
+} from "@/registry/default/hooks/use-asset"
+import { usePlaylistStore } from "@/registry/default/hooks/use-playlist"
 
 export function PlayerControls() {
+  const sourceType = useAssetStore((state) => state.sourceType)
+  const queueLength = usePlaylistStore((state) => state.queue.length)
+  const isPlaylistMode =
+    sourceType === AssetSourceType.Playlist || queueLength > 1
+
   return (
     <div className="grid h-full grid-cols-3 items-center px-4">
       <div className="flex items-center justify-start gap-4">
-        <PlaybackControls />
+        <PlaybackControls showNavigation={isPlaylistMode} />
         <TimeLabels />
       </div>
       <div className="flex items-center justify-center gap-2">
@@ -22,9 +34,13 @@ export function PlayerControls() {
       </div>
       <div className="flex items-center justify-end gap-2">
         <VolumeControl />
-        <RepeatControl />
-        <ShuffleControl />
-        <Playlist />
+        <RepeatControl variant={isPlaylistMode ? "playlist" : "asset"} />
+        {isPlaylistMode ? (
+          <>
+            <ShuffleControl />
+            <Playlist />
+          </>
+        ) : null}
       </div>
     </div>
   )
diff --git a/apps/www/registry/default/blocks/audio-player/components/media-player.tsx b/apps/www/registry/default/blocks/audio-player/components/media-player.tsx
index 4499328c..90a493e0 100644
--- a/apps/www/registry/default/blocks/audio-player/components/media-player.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/media-player.tsx
@@ -24,53 +24,41 @@ import styles from "../audio-player.module.css"
 export type { AudioPlayerAsset, PlaybackUrls }
 
 export interface AudioPlayerProps {
-  asset?: AudioSourceProviderProps["asset"]
-  assetOptions?: AudioSourceProviderProps["assetOptions"]
   autoLoad?: boolean
-  autoPlay?: boolean
   children?: ReactNode
   className?: string
   debug?: boolean
-  getAssetId?: AudioSourceProviderProps["getAssetId"]
   initialIndex?: number
+  loading?: AudioSourceProviderProps["loading"]
   /**
    * Props to pass to the underlying audio element.
    */
-  mediaProps?: Omit<
-    AudioHTMLAttributes<HTMLAudioElement>,
-    "as" | "autoPlay" | "className"
-  >
-  playlist?: AudioPlayerAsset[]
-  resolveSource?: AudioSourceProviderProps["resolveSource"]
+  mediaProps?: Omit<AudioHTMLAttributes<HTMLAudioElement>, "as" | "src">
+  source?: AudioSourceProviderProps["source"]
+  sourceKey?: string
 }
 
 export function AudioPlayer({
-  asset,
-  assetOptions,
   autoLoad,
-  autoPlay = false,
   children,
   className,
   debug,
-  getAssetId,
   initialIndex,
+  loading,
   mediaProps,
-  playlist,
-  resolveSource,
+  source,
+  sourceKey,
 }: AudioPlayerProps = {}) {
-  const { src: mediaSrc, ...safeMediaProps } = mediaProps ?? {}
+  const { className: mediaClassName, ...safeMediaProps } = mediaProps ?? {}
 
   return (
     <MediaProvider debug={debug}>
       <AudioSourceProvider
-        asset={asset}
-        assetOptions={assetOptions}
         autoLoad={autoLoad}
-        getAssetId={getAssetId}
         initialIndex={initialIndex}
-        mediaSrc={typeof mediaSrc === "string" ? mediaSrc : undefined}
-        playlist={playlist}
-        resolveSource={resolveSource}
+        loading={loading}
+        source={source}
+        sourceKey={sourceKey}
       >
         <div
           className={cn(
@@ -82,7 +70,7 @@ export function AudioPlayer({
           <Media
             {...(safeMediaProps as ComponentPropsWithoutRef<typeof Media>)}
             as="audio"
-            autoPlay={autoPlay}
+            className={mediaClassName}
           />
           <TimelineControl />
           <PlayerControls />
diff --git a/apps/www/registry/default/blocks/audio-player/components/playlist.tsx b/apps/www/registry/default/blocks/audio-player/components/playlist.tsx
index e8659fde..af6f8ce1 100644
--- a/apps/www/registry/default/blocks/audio-player/components/playlist.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/playlist.tsx
@@ -13,7 +13,6 @@ import { cn } from "@/lib/utils"
 import {
   type AudioPlayerAsset,
   getAudioAssetMetadata,
-  useAudioSource,
 } from "@/registry/default/blocks/audio-player/components/audio-source"
 import { Button } from "@/registry/default/blocks/audio-player/components/button"
 import { usePlayerStore } from "@/registry/default/hooks/use-player"
@@ -34,7 +33,6 @@ export function Playlist() {
   const skipToId = usePlaylistStore((state) => state.skipToId)
   const scrollRef = useRef<HTMLDivElement>(null)
 
-  const { items } = useAudioSource()
   const orderedItems = useMemo(() => {
     if (!shuffle || shuffleOrder.length === 0) return queue
 
@@ -45,21 +43,14 @@ export function Playlist() {
       )
   }, [queue, shuffle, shuffleOrder])
 
-  const displayAssets = useMemo(() => {
-    if (orderedItems.length > 0)
-      return orderedItems.map((item) => ({
+  const displayAssets = useMemo(
+    () =>
+      orderedItems.map((item) => ({
         asset: item.properties,
         id: item.id,
-      }))
-    return items.map((asset, index) => ({
-      asset,
-      id:
-        asset.id ??
-        asset.src ??
-        asset.playbackUrls?.primary ??
-        `asset:${index}`,
-    }))
-  }, [orderedItems, items])
+      })),
+    [orderedItems]
+  )
 
   const handleAssetSelect = useCallback(
     (assetId: string) => {
diff --git a/apps/www/registry/default/blocks/audio-player/hooks/use-playlist-asset.ts b/apps/www/registry/default/blocks/audio-player/hooks/use-playlist-asset.ts
index 1cfa4f53..165a6f9a 100644
--- a/apps/www/registry/default/blocks/audio-player/hooks/use-playlist-asset.ts
+++ b/apps/www/registry/default/blocks/audio-player/hooks/use-playlist-asset.ts
@@ -6,7 +6,6 @@ import type {
 } from "@/registry/default/blocks/audio-player/components/audio-source"
 import type { UseAssetReturn } from "@/registry/default/hooks/use-asset"
 
-import { useAudioSource } from "@/registry/default/blocks/audio-player/components/audio-source"
 import { useAsset } from "@/registry/default/hooks/use-asset"
 
 export type { PlaybackUrls }
@@ -19,10 +18,10 @@ export interface UsePlaylistAssetReturn extends UseAssetReturn<PlaylistAsset> {
 
 export function usePlaylistAsset(): UsePlaylistAssetReturn {
   const asset = useAsset<PlaylistAsset>()
-  const source = useAudioSource()
+  const items = asset.orderedItems.map((item) => item.properties)
 
   return {
     ...asset,
-    items: source.items,
+    items,
   }
 }
diff --git a/apps/www/registry/default/blocks/video-player/components/media-player.tsx b/apps/www/registry/default/blocks/video-player/components/media-player.tsx
index ca7f98e3..a9357629 100644
--- a/apps/www/registry/default/blocks/video-player/components/media-player.tsx
+++ b/apps/www/registry/default/blocks/video-player/components/media-player.tsx
@@ -5,8 +5,7 @@ import React from "react"
 
 import type {
   Asset,
-  GetAssetId,
-  ResolveSource,
+  PlayerSource,
   UseAssetOptions,
 } from "@/registry/default/hooks/use-asset"
 
@@ -32,55 +31,45 @@ export interface VideoPlayerAsset extends Asset {
 }
 
 export interface VideoPlayerProps {
-  asset?: VideoPlayerAsset
-  assetOptions?: Omit<
-    UseAssetOptions<VideoPlayerAsset>,
-    "getAssetId" | "resolveSource"
-  >
+  autoLoad?: boolean
   children?: React.ReactNode
   className?: string
   debug?: boolean
-  getAssetId?: GetAssetId<VideoPlayerAsset>
   initialIndex?: number
+  loading?: UseAssetOptions<VideoPlayerAsset>
   /**
    * Props to pass to the underlying video element.
    */
-  mediaProps?: Omit<
-    React.VideoHTMLAttributes<HTMLVideoElement>,
-    "as" | "className"
-  >
-  playlist?: VideoPlayerAsset[]
-  resolveSource?: ResolveSource<VideoPlayerAsset>
+  mediaProps?: Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "as" | "src">
+  source?: PlayerSource<VideoPlayerAsset>
+  sourceKey?: string
 }
 
 export const VideoPlayer = React.forwardRef<HTMLDivElement, VideoPlayerProps>(
   (
     {
-      asset,
-      assetOptions,
+      autoLoad,
       children,
       className,
       debug,
-      getAssetId,
       initialIndex,
+      loading,
       mediaProps,
-      playlist,
-      resolveSource,
+      source,
+      sourceKey,
     },
     ref
   ) => {
-    const { src: mediaSrc, ...safeMediaProps } = mediaProps ?? {}
+    const { className: mediaClassName, ...safeMediaProps } = mediaProps ?? {}
 
     return (
       <MediaProvider debug={debug}>
         <PlaybackSourceController
-          asset={asset}
-          assetOptions={assetOptions}
-          getAssetId={getAssetId}
+          autoLoad={autoLoad}
           initialIndex={initialIndex}
-          mediaSrc={typeof mediaSrc === "string" ? mediaSrc : undefined}
-          playlist={playlist}
-          resolveSource={resolveSource}
+          loading={loading}
+          source={source}
+          sourceKey={sourceKey}
         />
         <RootContainer className={cn("m-auto w-full", className)} ref={ref}>
           <Layout.PlayerContainer>
@@ -93,7 +82,7 @@ export const VideoPlayer = React.forwardRef<HTMLDivElement, VideoPlayerProps>(
                 typeof Media
               >)}
               as="video"
-              className="size-full object-cover"
+              className={cn("size-full object-cover", mediaClassName)}
             />
             {children}
             <Layout.ControlsOverlayContainer />
diff --git a/apps/www/registry/default/blocks/video-player/page.tsx b/apps/www/registry/default/blocks/video-player/page.tsx
index 16a169ae..55fc2ce9 100644
--- a/apps/www/registry/default/blocks/video-player/page.tsx
+++ b/apps/www/registry/default/blocks/video-player/page.tsx
@@ -6,7 +6,7 @@ const src =
 export default function Page() {
   return (
     <section className="flex h-dvh w-dvw bg-black">
-      <VideoPlayer mediaProps={{ src }} />
+      <VideoPlayer source={src} />
     </section>
   )
 }
diff --git a/apps/www/registry/default/hooks/use-asset.ts b/apps/www/registry/default/hooks/use-asset.ts
index a2ff894f..76b1be9c 100644
--- a/apps/www/registry/default/hooks/use-asset.ts
+++ b/apps/www/registry/default/hooks/use-asset.ts
@@ -2,7 +2,7 @@
 
 import type shaka from "shaka-player"
 
-import { useCallback, useEffect, useId } from "react"
+import { useCallback, useEffect } from "react"
 
 import type {
   PlaybackEvents,
@@ -19,6 +19,7 @@ import type {
 } from "@/registry/default/hooks/use-playlist"
 import type {
   ImmerStoreApi,
+  MediaEventSlice,
   MediaFeature,
   MediaStore,
 } from "@/registry/default/ui/media-provider"
@@ -31,195 +32,372 @@ import {
   useMediaFeatureStore,
 } from "@/registry/default/ui/media-provider"
 
+/** Metadata and playback configuration for one playable media item. */
 export interface Asset {
+  /** Shaka Player configuration applied before this asset loads. */
   config?: shaka.extern.PlayerConfiguration
+  /** Optional description for player UI. */
   description?: string
+  /** Stable identifier used for playlist, preload, and recovery state. */
   id?: string
+  /** Poster artwork shown by player UI. */
   poster?: string
+  /** Direct playback URL. Use `resolveSource` when this is resolved lazily. */
   src?: string
+  /** Display title for player UI. */
   title?: string
 }
 
+/** Context passed to a custom asset load handler. */
 export interface AssetLoadContext<TAsset extends Asset = Asset> {
+  /** Asset being loaded. */
   asset: TAsset
+  /** Run Limeplay's default Shaka load behavior. */
   loadDefault: (
     source?: null | PlaybackSource | shaka.media.PreloadManager | string,
     options?: number | { startTime?: number }
   ) => Promise<void>
+  /** Active media element. */
   media: HTMLMediaElement
+  /** Active Shaka Player instance. */
   player: shaka.Player
+  /** Existing preload manager for this asset, when available. */
   preloadManager?: shaka.media.PreloadManager
+  /** Previous load or playback error for retry-aware loaders. */
   previousError?: unknown
+  /** Number of retry attempts for the active load session. */
   retryCount: number
+  /** Abort signal for the active load session. */
   signal: AbortSignal
+  /** Requested playback start time in seconds. */
   startTime?: number
 }
 
+/** Context passed to a custom asset preload handler. */
 export interface AssetPreloadContext<TAsset extends Asset = Asset> {
+  /** Asset being preloaded. */
   asset: TAsset
+  /** Active Shaka Player instance. */
   player: shaka.Player
+  /** Run Limeplay's default Shaka preload behavior. */
   preloadDefault: (
     source?: PlaybackSource | string
   ) => Promise<null | shaka.media.PreloadManager>
+  /** Previous load or preload error for retry-aware loaders. */
   previousError?: unknown
+  /** Number of retry attempts for the active session. */
   retryCount: number
+  /** Abort signal for the active preload request. */
   signal: AbortSignal
 }
 
-export type AssetSourceOperation = "load" | "preload"
+/** Source shape currently controlled by the asset feature. */
+export const AssetSourceType = {
+  Asset: "asset",
+  Playlist: "playlist",
+} as const
+
+export type AssetSourceType =
+  (typeof AssetSourceType)[keyof typeof AssetSourceType]
+
+/** Origin used when deriving or normalizing asset IDs. */
+export const AssetSourceOrigin = {
+  Asset: "asset",
+  MediaProps: "media-props",
+  Playlist: "playlist",
+} as const
+
+export type AssetSourceOrigin =
+  (typeof AssetSourceOrigin)[keyof typeof AssetSourceOrigin]
+
+/** Recovery actions returned by load and playback recovery policies. */
+export const AssetRecoveryAction = {
+  Reload: "reload",
+  Retry: "retry",
+  Skip: "skip",
+  Stop: "stop",
+} as const
+
+/** Asset lifecycle events emitted through `useMediaEvents`. */
+export interface AssetEvents {
+  /** Emitted when the active playlist asset changes. */
+  assetchange: PlaylistChangeEvent<Asset>
+  /** Emitted after an asset loads successfully. */
+  assetloaded: { asset: Asset }
+  /** Emitted when asset loading fails. */
+  assetloaderror: { asset: Asset; error: Error }
+  /** Emitted before asset loading starts. */
+  assetloadstart: { asset: Asset; sourceType: AssetSourceType | null }
+  /** Emitted after an asset preloads successfully. */
+  assetpreloaded: { asset: Asset }
+  /** Emitted when asset preloading fails. */
+  assetpreloaderror: { asset: Asset; error: Error }
+  /** Emitted before asset preloading starts. */
+  assetpreloadstart: { asset: Asset }
+}
+
+/** Decision returned from load-error recovery. */
+export type AssetLoadDecision =
+  | typeof AssetRecoveryAction.Retry
+  | typeof AssetRecoveryAction.Skip
+  | typeof AssetRecoveryAction.Stop
+
+/** Options for loading a source into the asset feature. */
+export interface AssetLoadSourceOptions<TAsset extends Asset> {
+  /** Initial playlist index when the source is an array. */
+  initialIndex?: number
+  /** Session-local loading configuration. */
+  loading?: UseAssetOptions<TAsset>
+  /** Stable key used by source controllers to identify equivalent sources. */
+  sourceKey?: string
+  /** Explicit source type override for UI and recovery behavior. */
+  sourceType?: AssetSourceType
+}
+
+/** Decision returned from playback-error recovery. */
+export type AssetPlaybackRecoveryDecision<TAsset extends Asset> =
+  | {
+      action: typeof AssetRecoveryAction.Reload
+      asset?: TAsset
+      startTime?: number
+    }
+  | { action: typeof AssetRecoveryAction.Skip }
+  | { action: typeof AssetRecoveryAction.Stop }
+
+export type AssetRecoveryAction =
+  (typeof AssetRecoveryAction)[keyof typeof AssetRecoveryAction]
 
+/** Active source loading session. */
+export interface AssetSession<TAsset extends Asset = Asset> {
+  /** Unique session ID generated for each explicit load. */
+  id: string
+  /** Loading configuration attached to this session. */
+  loading?: UseAssetOptions<TAsset>
+  /** Stable source key, when provided by the caller. */
+  sourceKey?: string
+  /** Source type for this session. */
+  sourceType: AssetSourceType
+}
+
+/** Returns a stable ID for an asset when `asset.id` is not enough. */
 export type GetAssetId<TAsset extends Asset = Asset> = (
   asset: TAsset,
   context: {
     index?: number
-    origin: "asset" | "media-props" | "playlist"
+    origin: AssetSourceOrigin
   }
 ) => null | string | undefined
 
+/** Asset normalized for playlist storage. */
 export interface NormalizedAsset<TAsset extends Asset = Asset> {
+  /** Stable playlist item ID. */
   id: string
+  /** Original asset object. */
   properties: TAsset
 }
 
+/** Resolved playback source passed to Shaka Player. */
 export interface PlaybackSource {
+  /** Shaka Player configuration applied before loading. */
   config?: shaka.extern.PlayerConfiguration
+  /** Playback URL. */
   src?: string
 }
 
+/** Public source input accepted by blocks and `loadSource`. */
+export type PlayerSource<TAsset extends Asset = Asset> =
+  | readonly TAsset[]
+  | string
+  | TAsset
+
+/** Lazily resolves a playable source for an asset. */
 export type ResolveSource<TAsset extends Asset = Asset> = (
   context: ResolveSourceContext<TAsset>
 ) => MaybePromise<null | PlaybackSource | string | undefined>
 
+/** Context passed to `resolveSource`. */
 export interface ResolveSourceContext<TAsset extends Asset = Asset> {
+  /** Asset whose source should be resolved. */
   asset: TAsset
-  operation: AssetSourceOperation
+  /** Previous error for retry-aware resolution. */
   previousError?: unknown
+  /** Number of retry attempts in the active session. */
   retryCount: number
+  /** Abort signal for the active load or preload request. */
   signal: AbortSignal
+  /** Requested playback start time in seconds. */
   startTime?: number
 }
 
+/** Store actions exposed by the asset feature. */
 export interface UseAssetActions {
-  clearOptions: (ownerId: string) => void
+  /** Current source loading session. */
+  activeSession: AssetSession | null
+  /** Load a single asset immediately. */
   loadAsset: (asset: Asset, startTime?: number) => Promise<boolean>
-  loadPlaylist: (assets: Asset[], startIndex?: number) => void
+  /** Load assets into the playlist and start from `startIndex`. */
+  loadPlaylist: (
+    assets: Asset[],
+    startIndex?: number,
+    sourceType?: AssetSourceType,
+    options?: Omit<AssetLoadSourceOptions<Asset>, "initialIndex" | "sourceType">
+  ) => void
+  /** Normalize and load a URL, asset, or asset array. */
+  loadSource: (
+    source: PlayerSource<Asset>,
+    options?: AssetLoadSourceOptions<Asset>
+  ) => void
+  /** Preload one asset for faster future playback. */
   preloadAsset: (asset: Asset) => Promise<void>
+  /** Preload the next playlist item, when one exists. */
   preloadNext: () => Promise<void>
-  setOptions: (options: UseAssetOptions<Asset>, ownerId: string) => void
-}
-
-export interface UseAssetEvents {
-  ended: "advance to the next playlist item when available"
-  playbackerror: "delegate reload, skip, or stop decisions to onPlaybackError"
-  playlistchange: "load the newly active playlist item"
 }
 
+/** Alias for custom load handler context. */
 export type UseAssetLoadContext<TAsset extends Asset> = AssetLoadContext<TAsset>
 
+/** Custom loader hooks for replacing or extending default Shaka behavior. */
 export interface UseAssetLoader<TAsset extends Asset> {
+  /** Custom load implementation. Call `context.loadDefault()` to reuse defaults. */
   load?: (context: AssetLoadContext<TAsset>) => Promise<void>
+  /** Custom preload implementation. Call `context.preloadDefault()` to reuse defaults. */
   preload?: (
     context: AssetPreloadContext<TAsset>
   ) => Promise<null | shaka.media.PreloadManager>
 }
 
+/** Session-local loading options for asset source loading. */
 export interface UseAssetOptions<TAsset extends Asset> {
+  /** Allow autoplay on the first loaded asset when the media element requests autoplay. */
   autoplayFirst?: boolean
+  /** Resolve a stable asset ID when `asset.id` is missing or insufficient. */
   getAssetId?: GetAssetId<TAsset>
+  /** Custom load and preload handlers. */
   loader?: UseAssetLoader<TAsset>
+  /** Maximum retry attempts used by `recover.loadError`. */
   maxRetries?: number
-  onAssetChange?: (event: PlaylistChangeEvent<TAsset>) => void
-  onAssetLoaded?: (asset: TAsset) => void
-  onError?: (error: Error, asset?: TAsset) => void
-  onLoadError?: (
-    asset: TAsset,
-    error: unknown,
-    context: { hasNext: boolean; retryCount: number }
-  ) => "retry" | "skip" | "stop"
-  onPlaybackError?: (
-    asset: TAsset,
-    error: Error,
-    context: { currentTime: number }
-  ) => Promise<
-    | { action: "reload"; asset?: TAsset; startTime?: number }
-    | { action: "skip" }
-    | { action: "stop" }
-  >
+  /** Recovery policies for load and playback errors. */
+  recover?: {
+    /** Decide whether to retry, skip, or stop after a load error. */
+    loadError?: (
+      asset: TAsset,
+      error: unknown,
+      context: { hasNext: boolean; retryCount: number }
+    ) => AssetLoadDecision
+    /** Decide whether to reload, skip, or stop after a playback error. */
+    playbackError?: (
+      asset: TAsset,
+      error: Error,
+      context: { currentTime: number }
+    ) => Promise<AssetPlaybackRecoveryDecision<TAsset>>
+  }
+  /** Lazily resolve the playback URL or source config for an asset. */
   resolveSource?: ResolveSource<TAsset>
 }
 
+/** Alias for custom preload handler context. */
 export type UseAssetPreloadContext<TAsset extends Asset> =
   AssetPreloadContext<TAsset>
 
+/** Values and actions returned by `useAsset`. */
 export interface UseAssetReturn<TAsset extends Asset> {
+  /** Cancel an active preload by asset ID. */
   cancelPreload: (assetId: string) => void
+  /** Current playlist index. */
   currentIndex: number
+  /** Current playlist item. */
   currentItem: null | { id: string; properties: TAsset }
-  cycleRepeatMode: () => void
+  /** Return a playlist item by ID. */
   getItem: (id: string) => null | { id: string; properties: TAsset }
+  /** Whether a next playlist item is available. */
   hasNext: boolean
+  /** Whether a previous playlist item is available. */
   hasPrevious: boolean
-  insert: (
-    items: { id: string; properties?: TAsset }[],
-    atIndex: number
-  ) => void
+  /** Check whether an asset has a stored Shaka preload manager. */
   isPreloaded: (assetId: string) => boolean
-  load: (
-    items: { id: string; properties?: TAsset }[],
-    startIndex?: number
-  ) => void
+  /** Load one asset immediately. */
   loadAsset: (asset: TAsset, startTime?: number) => Promise<boolean>
-  loadPlaylist: (assets: TAsset[], startIndex?: number) => void
-  newSession: () => string
-  next: () => boolean
+  /** Load a playlist and start from `startIndex`. */
+  loadPlaylist: (
+    assets: TAsset[],
+    startIndex?: number,
+    sourceType?: AssetSourceType,
+    options?: Omit<
+      AssetLoadSourceOptions<TAsset>,
+      "initialIndex" | "sourceType"
+    >
+  ) => void
+  /** Load a URL string, one asset, or an asset array. */
+  loadSource: (
+    source: PlayerSource<TAsset>,
+    options?: AssetLoadSourceOptions<TAsset>
+  ) => void
+  /** Next playlist item, when available. */
   nextItem: null | { id: string; properties: TAsset }
+  /** Playlist items in playback order. */
   orderedItems: { id: string; properties: TAsset }[]
-  playNext: (items: { id: string; properties?: TAsset }[]) => void
+  /** Preload one asset for faster future playback. */
   preloadAsset: (asset: TAsset) => Promise<void>
+  /** Preload the next playlist item, when one exists. */
   preloadNext: () => Promise<void>
-  prepend: (items: { id: string; properties?: TAsset }[]) => void
-  previous: () => boolean
+  /** Previous playlist item, when available. */
   previousItem: null | { id: string; properties: TAsset }
-  remove: (id: string) => void
-  removeAt: (index: number) => void
-  reorder: (fromIndex: number, toIndex: number) => void
-  setRepeatMode: (mode: "all" | "off" | "one") => void
-  setShuffle: (enabled: boolean) => void
-  skipTo: (index: number) => boolean
-  skipToId: (id: string) => boolean
-  toggleShuffle: () => void
+  /** Current source mode, or `null` before a source is loaded. */
+  sourceType: AssetSourceType | null
 }
 
+/** Internal state owned by the asset feature. */
 export interface UseAssetState {
-  installedOptions?: UseAssetOptions<Asset>
+  /** Current source loading session. */
+  activeSession: AssetSession | null
+  /** Whether the current session has not completed its first load. */
   isFirstLoad: boolean
+  /** Abort controller for the active load. */
   loadAbortController: AbortController | null
+  /** Monotonic generation used to ignore stale loads. */
   loadGeneration: number
-  optionsOwnerId: null | string
+  /** Most recent load or playback error. */
   previousError: unknown
+  /** Retry count for the active session. */
   retryCount: number
+  /** Current source mode, or `null` before a source is loaded. */
+  sourceType: AssetSourceType | null
 }
 
 export const ASSET_FEATURE_KEY = "asset"
 
-export interface AssetStore {
+/** Store slice installed by `assetFeature`. */
+export interface AssetStore extends MediaEventSlice<AssetEvents> {
   [ASSET_FEATURE_KEY]: {
-    clearOptions: (ownerId: string) => void
-    installedOptions?: UseAssetOptions<Asset>
+    activeSession: AssetSession | null
     isFirstLoad: boolean
     loadAbortController: AbortController | null
-    loadAsset: (asset: Asset, startTime?: number) => Promise<boolean>
+    loadAsset: (
+      asset: Asset,
+      startTime?: number,
+      sourceType?: AssetSourceType
+    ) => Promise<boolean>
     loadGeneration: number
-    loadPlaylist: (assets: Asset[], startIndex?: number) => void
-    optionsByOwner: Record<string, undefined | UseAssetOptions<Asset>>
-    optionsOwnerId: null | string
-    optionsOwnerOrder: string[]
+    loadPlaylist: (
+      assets: Asset[],
+      startIndex?: number,
+      sourceType?: AssetSourceType,
+      options?: Omit<
+        AssetLoadSourceOptions<Asset>,
+        "initialIndex" | "sourceType"
+      >
+    ) => void
+    loadSource: (
+      source: PlayerSource<Asset>,
+      options?: AssetLoadSourceOptions<Asset>
+    ) => void
     preloadAbortControllers: Record<string, AbortController | undefined>
     preloadAsset: (asset: Asset) => Promise<void>
     preloadNext: () => Promise<void>
     previousError: unknown
     retryCount: number
-    setOptions: (options: UseAssetOptions<Asset>, ownerId: string) => void
+    setSourceType: (sourceType: AssetSourceType | null) => void
+    sourceType: AssetSourceType | null
   }
 }
 
@@ -232,49 +410,38 @@ type NormalizedSource = {
   source?: null | shaka.media.PreloadManager | string
 }
 
+/**
+ * Adds source loading, playlist-backed playback, preloading, and recovery
+ * orchestration to a media kit.
+ */
 export function assetFeature(): MediaFeature<
   AssetStore,
   AssetStore & MediaStore & PlaybackStore & PlayerStore & PlaylistStore
 > {
   return {
-    createSlice: (set, get) => ({
+    createSlice: (set, get, _store, events) => ({
       [ASSET_FEATURE_KEY]: {
-        clearOptions: (ownerId) => {
-          if (!get().asset.optionsByOwner[ownerId]) return
-
-          set(({ asset }) => {
-            delete asset.optionsByOwner[ownerId]
-            asset.optionsOwnerOrder = asset.optionsOwnerOrder.filter(
-              (id) => id !== ownerId
-            )
-
-            if (asset.optionsOwnerId !== ownerId) return
-
-            const nextOwnerId =
-              asset.optionsOwnerOrder[asset.optionsOwnerOrder.length - 1] ??
-              null
-            asset.optionsOwnerId = nextOwnerId
-            asset.installedOptions = nextOwnerId
-              ? asset.optionsByOwner[nextOwnerId]
-              : undefined
-          })
-        },
-        installedOptions: undefined,
+        activeSession: null,
         isFirstLoad: true,
         loadAbortController: null,
-        loadAsset: async (asset, startTime) => {
+        loadAsset: async (asset, startTime, sourceType) => {
           const player = get().player.instance as null | shaka.Player
           const media = get().media.mediaElement
-          const options = get().asset.installedOptions as
-            | undefined
-            | UseAssetOptions<Asset>
+          const session = get().asset.activeSession
+          const options = session?.loading as undefined | UseAssetOptions<Asset>
+
+          if (sourceType) {
+            set(({ asset }) => {
+              asset.sourceType = sourceType
+            })
+          }
 
           if (!player || !media) {
             return false
           }
 
           const assetId = getNormalizedAssetId(asset, options, {
-            origin: "asset",
+            origin: AssetSourceOrigin.Asset,
           })
 
           const generation = get().asset.loadGeneration + 1
@@ -288,6 +455,10 @@ export function assetFeature(): MediaFeature<
           })
 
           get().playback.pause()
+          events.emit("assetloadstart", {
+            asset,
+            sourceType: sourceType ?? get().asset.sourceType,
+          })
 
           try {
             const preloadManagers = get().player.preloadManagers as Map<
@@ -298,47 +469,13 @@ export function assetFeature(): MediaFeature<
             const retryCount = get().asset.retryCount
             const previousError = get().asset.previousError ?? undefined
 
-            const loadDefault = async (
-              source?:
-                | null
-                | PlaybackSource
-                | shaka.media.PreloadManager
-                | string,
-              loadOptions?: number | { startTime?: number }
-            ) => {
-              const normalizedSource = normalizePlaybackSource(source)
-              player.resetConfiguration()
-
-              if (asset.config) {
-                player.configure(asset.config)
-              }
-
-              if (normalizedSource.config) {
-                player.configure(normalizedSource.config)
-              }
-
-              const shouldUseFallbackSource =
-                source === undefined ||
-                source === null ||
-                (Boolean(normalizedSource.config) && !normalizedSource.source)
-              const resolvedSource = shouldUseFallbackSource
-                ? (preloadManager ?? normalizedSource.source ?? asset.src)
-                : normalizedSource.source
-
-              const finalStartTime =
-                typeof loadOptions === "number"
-                  ? loadOptions
-                  : (loadOptions?.startTime ?? startTime)
-              const timeToLoad = finalStartTime ?? undefined
-
-              if (!resolvedSource) {
-                throw new Error(
-                  `[useAsset] Missing playback source for asset "${assetId}". Provide asset.src or resolveSource.`
-                )
-              }
-
-              await player.load(resolvedSource, timeToLoad)
-            }
+            const loadDefault = createDefaultLoad({
+              asset,
+              assetId,
+              player,
+              preloadManager,
+              startTime,
+            })
 
             if (options?.loader?.load) {
               await options.loader.load({
@@ -355,7 +492,6 @@ export function assetFeature(): MediaFeature<
             } else {
               const resolved = await resolveSourceValue(options, {
                 asset,
-                operation: "load",
                 previousError,
                 retryCount,
                 signal: abortController.signal,
@@ -397,7 +533,7 @@ export function assetFeature(): MediaFeature<
               asset.retryCount = 0
             })
 
-            options?.onAssetLoaded?.(asset)
+            events.emit("assetloaded", { asset })
             return true
           } catch (error) {
             if (
@@ -409,7 +545,7 @@ export function assetFeature(): MediaFeature<
             }
 
             const normalizedError = toError(error)
-            options?.onError?.(normalizedError, asset)
+            events.emit("assetloaderror", { asset, error: normalizedError })
             const playlist = get().playlist
             const maxRetries = options?.maxRetries ?? 0
             const currentRetryCount = get().asset.retryCount
@@ -419,22 +555,26 @@ export function assetFeature(): MediaFeature<
               asset.previousError = error
             })
 
-            if (options?.onLoadError) {
-              const decision = options.onLoadError(asset, error, {
+            if (options?.recover?.loadError) {
+              const decision = options.recover.loadError(asset, error, {
                 hasNext,
                 retryCount: currentRetryCount,
               })
 
-              if (decision === "retry" && currentRetryCount < maxRetries) {
+              if (
+                decision === AssetRecoveryAction.Retry &&
+                currentRetryCount < maxRetries
+              ) {
                 set(({ asset }) => {
                   asset.retryCount = currentRetryCount + 1
                 })
-                return get().asset.loadAsset(asset, startTime)
+                return get().asset.loadAsset(asset, startTime, sourceType)
               }
 
               if (
-                (decision === "skip" ||
-                  (decision === "retry" && currentRetryCount >= maxRetries)) &&
+                (decision === AssetRecoveryAction.Skip ||
+                  (decision === AssetRecoveryAction.Retry &&
+                    currentRetryCount >= maxRetries)) &&
                 hasNext
               ) {
                 set(({ asset }) => {
@@ -466,33 +606,45 @@ export function assetFeature(): MediaFeature<
           }
         },
         loadGeneration: 0,
-        loadPlaylist: (assets, startIndex = 0) => {
-          const options = get().asset.installedOptions as
-            | undefined
-            | UseAssetOptions<Asset>
-          const normalizedAssets = normalizeAssets(assets, options)
+        loadPlaylist: (assets, startIndex = 0, sourceType, options) => {
+          const resolvedSourceType = getSourceTypeForItems(assets, sourceType)
+          const activeSession = createAssetSession(
+            resolvedSourceType ?? AssetSourceType.Asset,
+            options
+          )
+          const normalizedAssets = normalizeAssets(
+            assets,
+            activeSession.loading
+          )
 
           set(({ asset }) => {
+            asset.activeSession = activeSession
             asset.isFirstLoad = true
             asset.previousError = null
             asset.retryCount = 0
+            asset.sourceType = resolvedSourceType
           })
 
           get().playlist.load(normalizedAssets, startIndex)
         },
-        optionsByOwner: {},
-        optionsOwnerId: null,
-        optionsOwnerOrder: [],
+        loadSource: (source, options) => {
+          const assets = normalizePlayerSource(source)
+          get().asset.loadPlaylist(
+            assets,
+            options?.initialIndex,
+            options?.sourceType,
+            options
+          )
+        },
         preloadAbortControllers: {},
         preloadAsset: async (asset) => {
           const player = get().player.instance as null | shaka.Player
-          const options = get().asset.installedOptions as
-            | undefined
-            | UseAssetOptions<Asset>
+          const session = get().asset.activeSession
+          const options = session?.loading as undefined | UseAssetOptions<Asset>
           if (!player) return
 
           const assetId = getNormalizedAssetId(asset, options, {
-            origin: "asset",
+            origin: AssetSourceOrigin.Asset,
           })
           get().asset.preloadAbortControllers[assetId]?.abort()
           const abortController = new AbortController()
@@ -500,6 +652,7 @@ export function assetFeature(): MediaFeature<
           set(({ asset }) => {
             asset.preloadAbortControllers[assetId] = abortController
           })
+          events.emit("assetpreloadstart", { asset })
 
           const isCurrentPreload = () => {
             return (
@@ -554,7 +707,6 @@ export function assetFeature(): MediaFeature<
             } else {
               const resolved = await resolveSourceValue(options, {
                 asset,
-                operation: "preload",
                 previousError,
                 retryCount,
                 signal: abortController.signal,
@@ -586,6 +738,7 @@ export function assetFeature(): MediaFeature<
               set(({ player }) => {
                 player.preloadManagers = updated
               })
+              events.emit("assetpreloaded", { asset })
             }
           } catch (error) {
             if (
@@ -596,7 +749,7 @@ export function assetFeature(): MediaFeature<
             }
 
             const err = toError(error)
-            options?.onError?.(err, asset)
+            events.emit("assetpreloaderror", { asset, error: err })
             console.error("[useAsset] Preload error:", error)
           }
         },
@@ -614,56 +767,65 @@ export function assetFeature(): MediaFeature<
         },
         previousError: null,
         retryCount: 0,
-        setOptions: (options, ownerId) => {
+        setSourceType: (sourceType) => {
           set(({ asset }) => {
-            asset.optionsByOwner[ownerId] = options
-            asset.optionsOwnerOrder = [
-              ...asset.optionsOwnerOrder.filter((id) => id !== ownerId),
-              ownerId,
-            ]
-            asset.installedOptions = options
-            asset.optionsOwnerId = ownerId
+            asset.sourceType = sourceType
           })
         },
+        sourceType: null,
       },
     }),
     key: ASSET_FEATURE_KEY,
     Setup: AssetSetup,
   }
 }
-export function useAsset<TAsset extends Asset = Asset>(
-  options?: UseAssetOptions<TAsset>
-): UseAssetReturn<TAsset> {
+
+/**
+ * Access asset loading state and actions for the current `MediaProvider`.
+ *
+ * `useAsset()` is optionless. Pass loading configuration to `loadSource`,
+ * `loadPlaylist`, or a block's `loading` prop so configuration is scoped to
+ * the active source session.
+ */
+export function useAsset<
+  TAsset extends Asset = Asset,
+>(): UseAssetReturn<TAsset> {
   const api = useMediaFeatureApi<AssetStore>(ASSET_FEATURE_KEY)
-  const optionsOwnerId = useId()
   const playlist = usePlaylist<TAsset>()
-  const loadAsset = useAssetStore((state) => state.loadAsset) as (
+  const loadAssetAction = useAssetStore((state) => state.loadAsset) as (
     asset: TAsset,
-    startTime?: number
+    startTime?: number,
+    sourceType?: AssetSourceType
   ) => Promise<boolean>
   const loadPlaylist = useAssetStore((state) => state.loadPlaylist) as (
     assets: TAsset[],
-    startIndex?: number
+    startIndex?: number,
+    sourceType?: AssetSourceType,
+    options?: Omit<
+      AssetLoadSourceOptions<TAsset>,
+      "initialIndex" | "sourceType"
+    >
+  ) => void
+  const loadSourceAction = useAssetStore((state) => state.loadSource) as (
+    source: PlayerSource<TAsset>,
+    options?: AssetLoadSourceOptions<TAsset>
   ) => void
   const preloadAsset = useAssetStore((state) => state.preloadAsset) as (
     asset: TAsset
   ) => Promise<void>
   const preloadNext = useAssetStore((state) => state.preloadNext)
+  const sourceType = useAssetStore((state) => state.sourceType)
 
-  useEffect(() => {
-    if (!options) return
-
-    api
-      .getState()
-      .asset.setOptions(
-        options as unknown as UseAssetOptions<Asset>,
-        optionsOwnerId
-      )
+  const loadAsset = useCallback<UseAssetReturn<TAsset>["loadAsset"]>(
+    (asset, startTime) =>
+      loadAssetAction(asset, startTime, AssetSourceType.Asset),
+    [loadAssetAction]
+  )
 
-    return () => {
-      api.getState().asset.clearOptions(optionsOwnerId)
-    }
-  }, [api, options, optionsOwnerId])
+  const loadSource = useCallback<UseAssetReturn<TAsset>["loadSource"]>(
+    (source, options) => loadSourceAction(source, options),
+    [loadSourceAction]
+  )
 
   const cancelPreload = useCallback(
     (assetId: string) => {
@@ -703,16 +865,26 @@ export function useAsset<TAsset extends Asset = Asset>(
   )
 
   return {
-    ...playlist,
     cancelPreload,
+    currentIndex: playlist.currentIndex,
+    currentItem: playlist.currentItem,
+    getItem: playlist.getItem,
+    hasNext: playlist.hasNext,
+    hasPrevious: playlist.hasPrevious,
     isPreloaded,
     loadAsset,
     loadPlaylist,
+    loadSource,
+    nextItem: playlist.nextItem,
+    orderedItems: playlist.orderedItems,
     preloadAsset,
     preloadNext,
+    previousItem: playlist.previousItem,
+    sourceType,
   }
 }
 
+/** Subscribe to a field from the asset feature store slice. */
 export function useAssetStore<TSelected>(
   selector: (state: AssetStore["asset"]) => TSelected
 ): TSelected {
@@ -725,7 +897,7 @@ export function useAssetStore<TSelected>(
 function AssetSetup() {
   const api = useMediaFeatureApi<AssetSetupStore>(ASSET_FEATURE_KEY)
   const events = useMediaEvents<
-    PlaybackEvents & PlayerEvents & PlaylistEvents
+    AssetEvents & PlaybackEvents & PlayerEvents & PlaylistEvents
   >()
   useEffect(() => {
     const getHasNext = () => {
@@ -738,46 +910,62 @@ function AssetSetup() {
     const offPlaylistChange = events.on("playlistchange", (event) => {
       const item = event.currentItem
       if (!item) return
-
-      const options = api.getState().asset.installedOptions as
-        | undefined
-        | UseAssetOptions<Asset>
-
-      options?.onAssetChange?.(event as unknown as PlaylistChangeEvent<Asset>)
-      void api.getState().asset.loadAsset(item.properties as unknown as Asset)
+      events.emit("assetchange", event as PlaylistChangeEvent<Asset>)
+      void api
+        .getState()
+        .asset.loadAsset(
+          item.properties as unknown as Asset,
+          undefined,
+          api.getState().asset.sourceType ?? AssetSourceType.Playlist
+        )
     })
 
     const offPlaybackError = events.on("playbackerror", (payload) => {
       void (async () => {
         const { currentItem } = api.getState().playlist
-        const options = api.getState().asset.installedOptions as
+        const options = api.getState().asset.activeSession?.loading as
           | undefined
           | UseAssetOptions<Asset>
-        if (!currentItem || !options?.onPlaybackError) return
+        if (!currentItem) return
 
         const mediaElement = api.getState().media.mediaElement
         try {
-          const currentTime = mediaElement ? mediaElement.currentTime : 0
-          const decision = await options.onPlaybackError(
-            currentItem.properties as unknown as Asset,
-            payload.error,
-            { currentTime }
-          )
+          const currentTime =
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            payload.currentTime ?? mediaElement?.currentTime ?? 0
+          const decision = options?.recover?.playbackError
+            ? await options.recover.playbackError(
+                currentItem.properties as unknown as Asset,
+                payload.error,
+                { currentTime }
+              )
+            : {
+                action: AssetRecoveryAction.Reload,
+              }
 
-          if (decision.action === "reload") {
+          if (decision.action === AssetRecoveryAction.Reload) {
             const assetToLoad = (decision.asset ??
               currentItem.properties) as unknown as Asset
             const startTime = decision.startTime ?? currentTime
             api.setState(({ asset }) => {
               asset.previousError = payload.error
             })
-            void api.getState().asset.loadAsset(assetToLoad, startTime)
-          } else if (decision.action === "skip" && getHasNext()) {
+            await api
+              .getState()
+              .asset.loadAsset(
+                assetToLoad,
+                startTime,
+                api.getState().asset.sourceType ?? AssetSourceType.Asset
+              )
+          } else if (
+            decision.action === AssetRecoveryAction.Skip &&
+            getHasNext()
+          ) {
             api.getState().playlist.next()
           }
         } catch (callbackErr) {
           console.error(
-            "[useAsset] onPlaybackError callback failed:",
+            "[useAsset] recover.playbackError callback failed:",
             callbackErr
           )
         }
@@ -799,11 +987,75 @@ function AssetSetup() {
 
   return null
 }
+function createAssetSession(
+  sourceType: AssetSourceType,
+  options?: Omit<AssetLoadSourceOptions<Asset>, "initialIndex" | "sourceType">
+): AssetSession {
+  return {
+    id: generateAssetSessionId(),
+    loading: options?.loading,
+    sourceKey: options?.sourceKey,
+    sourceType,
+  }
+}
+
+function createDefaultLoad({
+  asset,
+  assetId,
+  player,
+  preloadManager,
+  startTime,
+}: {
+  asset: Asset
+  assetId: string
+  player: shaka.Player
+  preloadManager?: shaka.media.PreloadManager
+  startTime?: number
+}): AssetLoadContext["loadDefault"] {
+  return async (source, loadOptions) => {
+    const normalizedSource = normalizePlaybackSource(source)
+    player.resetConfiguration()
+
+    if (asset.config) {
+      player.configure(asset.config)
+    }
+
+    if (normalizedSource.config) {
+      player.configure(normalizedSource.config)
+    }
+
+    const shouldUseFallbackSource =
+      source === undefined ||
+      source === null ||
+      (Boolean(normalizedSource.config) && !normalizedSource.source)
+    const resolvedSource = shouldUseFallbackSource
+      ? (preloadManager ?? normalizedSource.source ?? asset.src)
+      : normalizedSource.source
+
+    const finalStartTime =
+      typeof loadOptions === "number"
+        ? loadOptions
+        : (loadOptions?.startTime ?? startTime)
+    const timeToLoad = finalStartTime ?? undefined
+
+    if (!resolvedSource) {
+      throw new Error(
+        `[useAsset] Missing playback source for asset "${assetId}". Provide asset.src or resolveSource.`
+      )
+    }
+
+    await player.load(resolvedSource, timeToLoad)
+  }
+}
+
+function generateAssetSessionId(): string {
+  return `lp_asset_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`
+}
 
 function getNormalizedAssetId(
   asset: Asset,
   options: undefined | UseAssetOptions<Asset>,
-  context: { index?: number; origin: "asset" | "media-props" | "playlist" }
+  context: { index?: number; origin: AssetSourceOrigin }
 ): string {
   const id = asset.id ?? options?.getAssetId?.(asset, context)
   if (id) return id
@@ -817,6 +1069,20 @@ function getNormalizedAssetId(
   )
 }
 
+function getSourceTypeForItems<T>(
+  items: T[],
+  sourceType?: AssetSourceType
+): AssetSourceType | null {
+  return (
+    sourceType ??
+    (items.length === 0
+      ? null
+      : items.length > 1
+        ? AssetSourceType.Playlist
+        : AssetSourceType.Asset)
+  )
+}
+
 function hashString(value: string): string {
   let hash = 0
 
@@ -850,7 +1116,7 @@ function normalizeAssets(
   return assets.map((asset, index) => {
     const id = getNormalizedAssetId(asset, options, {
       index,
-      origin: "playlist",
+      origin: AssetSourceOrigin.Playlist,
     })
 
     if (usedIds.has(id)) {
@@ -891,6 +1157,12 @@ function normalizePlaybackSource(
   return { source: source as shaka.media.PreloadManager }
 }
 
+function normalizePlayerSource(source: PlayerSource<Asset>): Asset[] {
+  if (Array.isArray(source)) return [...source]
+  if (typeof source === "string") return [{ src: source }]
+  return [source as Asset]
+}
+
 async function resolveSourceValue(
   options: undefined | UseAssetOptions<Asset>,
   context: ResolveSourceContext<Asset>
diff --git a/apps/www/registry/default/hooks/use-playback-source.ts b/apps/www/registry/default/hooks/use-playback-source.ts
index 5eaacfbd..05dc94e6 100644
--- a/apps/www/registry/default/hooks/use-playback-source.ts
+++ b/apps/www/registry/default/hooks/use-playback-source.ts
@@ -5,22 +5,22 @@ import { useEffect, useMemo, useRef } from "react"
 import type {
   Asset,
   GetAssetId,
-  ResolveSource,
+  PlayerSource,
   UseAssetOptions,
 } from "@/registry/default/hooks/use-asset"
 
-import { useAsset } from "@/registry/default/hooks/use-asset"
+import {
+  AssetSourceOrigin,
+  AssetSourceType,
+  useAsset,
+} from "@/registry/default/hooks/use-asset"
 import { usePlayerStore } from "@/registry/default/hooks/use-player"
 
 export interface UsePlaybackSourceOptions<TAsset extends Asset> {
-  asset?: TAsset
-  assetOptions?: Omit<UseAssetOptions<TAsset>, "getAssetId" | "resolveSource">
   autoLoad?: boolean
-  getAssetId?: GetAssetId<TAsset>
   initialIndex?: number
-  mediaSrc?: string
-  playlist?: TAsset[]
-  resolveSource?: ResolveSource<TAsset>
+  loading?: UseAssetOptions<TAsset>
+  source?: PlayerSource<TAsset>
   sourceKey?: string
 }
 
@@ -36,41 +36,28 @@ export function usePlaybackSource<TAsset extends Asset>(
   options: UsePlaybackSourceOptions<TAsset>
 ): void {
   const {
-    asset,
-    assetOptions,
     autoLoad = true,
-    getAssetId,
     initialIndex = 0,
-    mediaSrc,
-    playlist,
-    resolveSource,
+    loading,
+    source,
     sourceKey,
   } = options
 
+  const assets = useMemo(() => {
+    if (Array.isArray(source)) return [...source]
+    if (typeof source === "string") return [{ src: source } as TAsset]
+    if (source) return [source]
+
+    return []
+  }, [source])
   const player = usePlayerStore((state) => state.instance)
-  const installedOptions = useMemo<UseAssetOptions<TAsset>>(
-    () => ({
-      ...assetOptions,
-      getAssetId,
-      resolveSource,
-    }),
-    [assetOptions, getAssetId, resolveSource]
-  )
-  const { loadPlaylist } = useAsset<TAsset>(installedOptions)
+  const { loadSource } = useAsset<TAsset>()
   const loadedSourceKeyRef = useRef<null | string>(null)
 
   useEffect(() => {
     loadedSourceKeyRef.current = null
   }, [player])
 
-  const assets = useMemo(() => {
-    if (playlist) return playlist
-    if (asset) return [asset]
-    if (mediaSrc) return [{ src: mediaSrc } as TAsset]
-
-    return []
-  }, [asset, mediaSrc, playlist])
-
   const resolvedSourceKey = useMemo(() => {
     if (sourceKey) return sourceKey
 
@@ -78,23 +65,53 @@ export function usePlaybackSource<TAsset extends Asset>(
       .map((item, index) => {
         const id =
           item.id ??
-          getAssetId?.(item, {
+          loading?.getAssetId?.(item, {
             index,
-            origin: playlist ? "playlist" : asset ? "asset" : "media-props",
+            origin: getSourceOrigin(source),
           }) ??
           item.src
 
         return id ?? `item:${index}`
       })
       .join("|")
-  }, [asset, assets, getAssetId, playlist, sourceKey])
+  }, [assets, loading, source, sourceKey])
+  const sourceType = useMemo<AssetSourceType>(() => {
+    return Array.isArray(source)
+      ? AssetSourceType.Playlist
+      : AssetSourceType.Asset
+  }, [source])
 
   useEffect(() => {
-    if (!autoLoad || !player || assets.length === 0) return
+    if (!autoLoad || !player || source === undefined || assets.length === 0)
+      return
 
     if (loadedSourceKeyRef.current === resolvedSourceKey) return
     loadedSourceKeyRef.current = resolvedSourceKey
 
-    loadPlaylist(assets, initialIndex)
-  }, [assets, autoLoad, initialIndex, loadPlaylist, player, resolvedSourceKey])
+    loadSource(source, {
+      initialIndex,
+      loading,
+      sourceKey,
+      sourceType,
+    })
+  }, [
+    assets,
+    autoLoad,
+    initialIndex,
+    loadSource,
+    player,
+    resolvedSourceKey,
+    source,
+    sourceKey,
+    sourceType,
+    loading,
+  ])
+}
+
+function getSourceOrigin<TAsset extends Asset>(
+  source: PlayerSource<TAsset> | undefined
+): Parameters<GetAssetId<TAsset>>[1]["origin"] {
+  if (Array.isArray(source)) return AssetSourceOrigin.Playlist
+  if (typeof source === "string") return AssetSourceOrigin.MediaProps
+  return AssetSourceOrigin.Asset
 }
diff --git a/apps/www/registry/default/hooks/use-player.ts b/apps/www/registry/default/hooks/use-player.ts
index d1c51727..ae2747fa 100644
--- a/apps/www/registry/default/hooks/use-player.ts
+++ b/apps/www/registry/default/hooks/use-player.ts
@@ -32,9 +32,9 @@ export const PLAYER_FEATURE_KEY = "player"
 
 export interface PlayerEvents {
   bufferingchange: { isBuffering: boolean }
-  playbackerror: { error: Error }
+  playbackerror: { currentTime: number; error: Error }
   playererror: { error: Error }
-  playerready: { player: shaka.Player }
+  playerready: void
 }
 
 export interface PlayerStore extends MediaEventSlice<PlayerEvents> {
@@ -276,7 +276,7 @@ function PlayerSetup() {
         mediaElement.player = playerInstance.current
         window.shaka = shakaLib as unknown as Window["shaka"]
 
-        events.emit("playerready", { player: localPlayer })
+        events.emit("playerready")
       } catch (error) {
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- mutated by cleanup closure during await
         if (aborted) {
@@ -359,9 +359,14 @@ function PlayerSetup() {
     const errorHandler = (event: Event) => {
       const detail = (event as CustomEvent).detail as shaka.util.Error
       if (isLoadInterrupted(detail)) return
+      const media = store.getState().media.mediaElement
+      const currentTime = media?.currentTime ?? 0
 
       store.getState().playback.setError(detail)
-      events.emit("playbackerror", { error: detail as unknown as Error })
+      events.emit("playbackerror", {
+        currentTime,
+        error: detail as unknown as Error,
+      })
     }
 
     player.addEventListener("error", errorHandler)
@@ -374,7 +379,7 @@ function PlayerSetup() {
       player.removeEventListener("error", errorHandler)
       clearBufferingTimeout()
     }
-  }, [mediaElement, player, store])
+  }, [events, mediaElement, player, store])
 
   return null
 }
diff --git a/bun.lock b/bun.lock
index 6f1cd22f..54dabb63 100644
--- a/bun.lock
+++ b/bun.lock
@@ -38,6 +38,7 @@
         "@vercel/speed-insights": "^1.3.1",
         "ai": "^5.0.101",
         "async-retry": "^1.3.3",
+        "beautiful-mermaid": "^1.1.3",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "date-fns": "^4.1.0",
@@ -784,6 +785,8 @@
 
     "baseline-browser-mapping": ["baseline-browser-mapping@2.10.23", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-xwVXGqevyKPsiuQdLj+dZMVjidjJV508TBqexND5HrF89cGdCYCJFB3qhcxRHSeMctdCfbR1jrxBajhDy7o29g=="],
 
+    "beautiful-mermaid": ["beautiful-mermaid@1.1.3", "", { "dependencies": { "elkjs": "^0.11.0", "entities": "^7.0.1" } }, "sha512-TItrtrAyHp1vwFfFVYauWGrquouk/6SS21Aq3RsxindSYZODcN4xYrPZD6BiZRU+o5mKJzDPz9MUSMvELdylyg=="],
+
     "body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],
 
     "brace-expansion": ["brace-expansion@1.1.12", "", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg=="],
@@ -932,13 +935,15 @@
 
     "electron-to-chromium": ["electron-to-chromium@1.5.260", "", {}, "sha512-ov8rBoOBhVawpzdre+Cmz4FB+y66Eqrk6Gwqd8NGxuhv99GQ8XqMAr351KEkOt7gukXWDg6gJWEMKgL2RLMPtA=="],
 
+    "elkjs": ["elkjs@0.11.1", "", {}, "sha512-zxxR9k+rx5ktMwT/FwyLdPCrq7xN6e4VGGHH8hA01vVYKjTFik7nHOxBnAYtrgYUB1RpAiLvA1/U2YraWxyKKg=="],
+
     "emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
 
     "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
 
     "enhanced-resolve": ["enhanced-resolve@5.21.0", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.3" } }, "sha512-otxSQPw4lkOZWkHpB3zaEQs6gWYEsmX4xQF68ElXC/TWvGxGMSGOvoNbaLXm6/cS/fSfHtsEdw90y20PCd+sCA=="],
 
-    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
+    "entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
 
     "env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],
 
@@ -2276,6 +2281,8 @@
 
     "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
 
+    "parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
+
     "prompts/kleur": ["kleur@3.0.3", "", {}, "sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w=="],
 
     "radix-ui/@radix-ui/react-separator": ["@radix-ui/react-separator@1.1.7", "", { "dependencies": { "@radix-ui/react-primitive": "2.1.3" }, "peerDependencies": { "@types/react": "*", "@types/react-dom": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-0HEb8R9E8A+jZjvmFCy/J4xhbXy3TV+9XSnGJ3KvTtjlIUy/YQ/p6UYZvi7YbeoeXdyU9+Y3scizK6hkY37baA=="],

From 5b67fde433c19c48bb377f5b6d4fbb8217f9aa98 Mon Sep 17 00:00:00 2001
From: winoffrg <rohangupta1528@gmail.com>
Date: Sun, 14 Jun 2026 16:26:51 +0530
Subject: [PATCH 4/5] fix: resolved AI comments

---
 .../stream-panel/use-stream-panel-sync.ts     |  3 ++
 apps/www/content/docs/blocks/audio-player.mdx |  2 +-
 apps/www/content/docs/concepts.mdx            |  2 +-
 apps/www/content/docs/usage.mdx               |  3 ++
 .../registry/collection/registry-blocks.ts    |  1 +
 .../components/playback-mode-controls.tsx     |  2 +-
 .../playlist-navigation-controls.tsx          | 18 +++++-----
 .../blocks/video-player/lib/media-kit.ts      |  1 +
 apps/www/registry/default/hooks/use-asset.ts  | 34 ++++++++++++++-----
 .../default/hooks/use-playback-source.ts      | 13 +++++--
 10 files changed, 55 insertions(+), 24 deletions(-)

diff --git a/apps/www/components/stream-panel/use-stream-panel-sync.ts b/apps/www/components/stream-panel/use-stream-panel-sync.ts
index e6f6c002..d13c4794 100644
--- a/apps/www/components/stream-panel/use-stream-panel-sync.ts
+++ b/apps/www/components/stream-panel/use-stream-panel-sync.ts
@@ -89,6 +89,7 @@ export function useStreamPanelSync({
             context.signal,
             blenderStreamCache
           )
+          // DEV: The selected asset may change while the Blender stream URL is resolving.
           context.signal.throwIfAborted()
 
           await context.loadDefault(
@@ -97,6 +98,8 @@ export function useStreamPanelSync({
               src: stream.playback.hls,
             }
           )
+          // DEV: loadDefault is async; avoid adding captions to a superseded player load.
+          context.signal.throwIfAborted()
 
           try {
             await addBlenderCaptions(context.player, stream)
diff --git a/apps/www/content/docs/blocks/audio-player.mdx b/apps/www/content/docs/blocks/audio-player.mdx
index 32eca7bd..245f1675 100644
--- a/apps/www/content/docs/blocks/audio-player.mdx
+++ b/apps/www/content/docs/blocks/audio-player.mdx
@@ -52,7 +52,7 @@ Pass one asset object when you do not need a queue.
 ```tsx
 <AudioPlayer
   source={{
-    artist: "SoundHelix",
+    artistName: "SoundHelix",
     id: "soundhelix-1",
     poster: "https://placehold.co/160x160/png",
     src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
diff --git a/apps/www/content/docs/concepts.mdx b/apps/www/content/docs/concepts.mdx
index 0cadaafb..4670d548 100644
--- a/apps/www/content/docs/concepts.mdx
+++ b/apps/www/content/docs/concepts.mdx
@@ -43,7 +43,7 @@ Read state with selectors so components only re-render for the fields they use.
 
 ```tsx
 const paused = usePlaybackStore((state) => state.paused)
-const volume = useVolumeStore((state) => state.volume)
+const volume = useVolumeStore((state) => state.level)
 ```
 
 For imperative code, use the media API returned by your kit.
diff --git a/apps/www/content/docs/usage.mdx b/apps/www/content/docs/usage.mdx
index 5c7079d2..8c10e289 100644
--- a/apps/www/content/docs/usage.mdx
+++ b/apps/www/content/docs/usage.mdx
@@ -259,6 +259,7 @@ interface CustomVideoAsset extends Asset {
 
 interface CustomVideoPlayerProps {
   autoLoad?: boolean
+  initialIndex?: number
   loading?: UseAssetOptions<CustomVideoAsset>
   mediaProps?: Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "as" | "src">
   source?: PlayerSource<CustomVideoAsset>
@@ -267,6 +268,7 @@ interface CustomVideoPlayerProps {
 
 export function CustomVideoPlayer({
   autoLoad,
+  initialIndex,
   loading,
   mediaProps,
   source,
@@ -276,6 +278,7 @@ export function CustomVideoPlayer({
     <MediaProvider>
       <PlaybackSourceController
         autoLoad={autoLoad}
+        initialIndex={initialIndex}
         loading={loading}
         source={source}
         sourceKey={sourceKey}
diff --git a/apps/www/registry/collection/registry-blocks.ts b/apps/www/registry/collection/registry-blocks.ts
index 54e0fb36..ca88f5ee 100644
--- a/apps/www/registry/collection/registry-blocks.ts
+++ b/apps/www/registry/collection/registry-blocks.ts
@@ -214,6 +214,7 @@ export const blocks: Registry["items"] = [
       "use-asset",
       "use-media",
       "use-playback-source",
+      "limeplay-logo",
       "utils",
     ],
     title: "Audio Player",
diff --git a/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx b/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx
index 4f8fb415..fa09dab3 100644
--- a/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx
+++ b/apps/www/registry/default/blocks/audio-player/components/playback-mode-controls.tsx
@@ -31,7 +31,7 @@ export function RepeatControl({
 }: {
   variant?: RepeatControlVariant
 }) {
-  const { setRepeatMode } = usePlaylist()
+  const setRepeatMode = usePlaylistStore((state) => state.setRepeatMode)
   const repeatMode = usePlaylistStore((state) => state.repeatMode)
   const modes = REPEAT_MODES[variant]
   const normalizedRepeatMode = useMemo(
diff --git a/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx b/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx
index 322305eb..a9b0c0ef 100644
--- a/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx
+++ b/apps/www/registry/default/blocks/video-player/components/playlist-navigation-controls.tsx
@@ -3,14 +3,16 @@
 import { SkipForwardIcon } from "@phosphor-icons/react"
 
 import { Button } from "@/registry/default/blocks/video-player/components/button"
-import {
-  usePlaylist,
-  usePlaylistStore,
-} from "@/registry/default/hooks/use-playlist"
+import { usePlaylistStore } from "@/registry/default/hooks/use-playlist"
 
 export function PlaylistNextControl() {
-  const { hasNext, next } = usePlaylist()
-  const hasPlaylist = useHasPlaylist()
+  const next = usePlaylistStore((state) => state.next)
+  const hasNext = usePlaylistStore((state) => {
+    if (state.repeatMode === "all" && state.queue.length > 0) return true
+
+    return state.getNextIndex() !== -1
+  })
+  const hasPlaylist = usePlaylistStore((state) => state.queue.length > 0)
 
   if (!hasPlaylist) return null
 
@@ -26,7 +28,3 @@ export function PlaylistNextControl() {
     </Button>
   )
 }
-
-function useHasPlaylist() {
-  return usePlaylistStore((state) => state.queue.length > 1)
-}
diff --git a/apps/www/registry/default/blocks/video-player/lib/media-kit.ts b/apps/www/registry/default/blocks/video-player/lib/media-kit.ts
index 6e496642..afe0e460 100644
--- a/apps/www/registry/default/blocks/video-player/lib/media-kit.ts
+++ b/apps/www/registry/default/blocks/video-player/lib/media-kit.ts
@@ -28,3 +28,4 @@ export const media = createMediaKit({
 })
 
 export const MediaProvider = media.MediaProvider
+export const useMediaEvents = media.useMediaEvents
diff --git a/apps/www/registry/default/hooks/use-asset.ts b/apps/www/registry/default/hooks/use-asset.ts
index 76b1be9c..d725f3f2 100644
--- a/apps/www/registry/default/hooks/use-asset.ts
+++ b/apps/www/registry/default/hooks/use-asset.ts
@@ -607,11 +607,8 @@ export function assetFeature(): MediaFeature<
         },
         loadGeneration: 0,
         loadPlaylist: (assets, startIndex = 0, sourceType, options) => {
-          const resolvedSourceType = getSourceTypeForItems(assets, sourceType)
-          const activeSession = createAssetSession(
-            resolvedSourceType ?? AssetSourceType.Asset,
-            options
-          )
+          const resolvedSourceType = sourceType ?? AssetSourceType.Playlist
+          const activeSession = createAssetSession(resolvedSourceType, options)
           const normalizedAssets = normalizeAssets(
             assets,
             activeSession.loading
@@ -629,10 +626,16 @@ export function assetFeature(): MediaFeature<
         },
         loadSource: (source, options) => {
           const assets = normalizePlayerSource(source)
+          const sourceType =
+            options?.sourceType ??
+            (Array.isArray(source)
+              ? AssetSourceType.Playlist
+              : (getSourceTypeForItems(assets) ?? AssetSourceType.Asset))
+
           get().asset.loadPlaylist(
             assets,
             options?.initialIndex,
-            options?.sourceType,
+            sourceType,
             options
           )
         },
@@ -922,11 +925,22 @@ function AssetSetup() {
 
     const offPlaybackError = events.on("playbackerror", (payload) => {
       void (async () => {
-        const { currentItem } = api.getState().playlist
-        const options = api.getState().asset.activeSession?.loading as
+        const state = api.getState()
+        const { currentItem } = state.playlist
+        const sessionId = state.asset.activeSession?.id
+        const options = state.asset.activeSession?.loading as
           | undefined
           | UseAssetOptions<Asset>
         if (!currentItem) return
+        const currentItemId = currentItem.id
+
+        const getFreshCurrentItem = () => {
+          const freshState = api.getState()
+          if (freshState.asset.activeSession?.id !== sessionId) return null
+          if (freshState.playlist.currentItem?.id !== currentItemId) return null
+
+          return freshState.playlist.currentItem
+        }
 
         const mediaElement = api.getState().media.mediaElement
         try {
@@ -942,10 +956,12 @@ function AssetSetup() {
             : {
                 action: AssetRecoveryAction.Reload,
               }
+          const freshCurrentItem = getFreshCurrentItem()
+          if (!freshCurrentItem) return
 
           if (decision.action === AssetRecoveryAction.Reload) {
             const assetToLoad = (decision.asset ??
-              currentItem.properties) as unknown as Asset
+              freshCurrentItem.properties) as unknown as Asset
             const startTime = decision.startTime ?? currentTime
             api.setState(({ asset }) => {
               asset.previousError = payload.error
diff --git a/apps/www/registry/default/hooks/use-playback-source.ts b/apps/www/registry/default/hooks/use-playback-source.ts
index 05dc94e6..a142526c 100644
--- a/apps/www/registry/default/hooks/use-playback-source.ts
+++ b/apps/www/registry/default/hooks/use-playback-source.ts
@@ -80,13 +80,21 @@ export function usePlaybackSource<TAsset extends Asset>(
       ? AssetSourceType.Playlist
       : AssetSourceType.Asset
   }, [source])
+  const requestKey = useMemo(
+    () => `${resolvedSourceKey}::${sourceType}::${initialIndex}`,
+    [initialIndex, resolvedSourceKey, sourceType]
+  )
+
+  useEffect(() => {
+    loadedSourceKeyRef.current = null
+  }, [requestKey])
 
   useEffect(() => {
     if (!autoLoad || !player || source === undefined || assets.length === 0)
       return
 
-    if (loadedSourceKeyRef.current === resolvedSourceKey) return
-    loadedSourceKeyRef.current = resolvedSourceKey
+    if (loadedSourceKeyRef.current === requestKey) return
+    loadedSourceKeyRef.current = requestKey
 
     loadSource(source, {
       initialIndex,
@@ -100,6 +108,7 @@ export function usePlaybackSource<TAsset extends Asset>(
     initialIndex,
     loadSource,
     player,
+    requestKey,
     resolvedSourceKey,
     source,
     sourceKey,

From 05eafeb79c6e369a86f6b5502d3db8d46910f4ea Mon Sep 17 00:00:00 2001
From: winoffrg <rohangupta1528@gmail.com>
Date: Sun, 14 Jun 2026 16:34:07 +0530
Subject: [PATCH 5/5] fix: missing block file

---
 apps/www/registry/collection/registry-blocks.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/apps/www/registry/collection/registry-blocks.ts b/apps/www/registry/collection/registry-blocks.ts
index ca88f5ee..eb8076f0 100644
--- a/apps/www/registry/collection/registry-blocks.ts
+++ b/apps/www/registry/collection/registry-blocks.ts
@@ -56,6 +56,10 @@ export const blocks: Registry["items"] = [
         path: `${VIDEO_PLAYER_SRC_URL}/components/playlist.tsx`,
         type: "registry:component",
       },
+      {
+        path: `${VIDEO_PLAYER_SRC_URL}/components/playlist-navigation-controls.tsx`,
+        type: "registry:component",
+      },
       {
         path: `${VIDEO_PLAYER_SRC_URL}/components/captions-state-control.tsx`,
         type: "registry:component",