add placeholder (blur-up) prop and fix rate persistence across swaps

placeholder: pass a low-res data URI or URL and kino paints it behind the
video while the poster and first frame load, then the sharp poster covers
it. Rendered as a .kino-placeholder <img> at the video host's z-level but
earlier in the DOM, so the video paints over it. Plumbed through both the
headless Player and the MuxPlayer wrapper.

rate: loading a new source resets the media element's playbackRate to
defaultPlaybackRate, so the chosen speed dropped to 1x on every
swapSource. Seed defaultPlaybackRate at mount and keep it in lockstep in
setRate so the rate survives source changes.

Also widen the eslint ignore to **/dist/** so a built demo/dist no longer
poisons `pnpm lint`.

Author: karngyan

.changeset/placeholder-and-rate.md

@@ -0,0 +1,7 @@
+---
+"@karnstack/kino": minor
+---
+
+Add a `placeholder` prop (blur-up): pass a low-res data URI or URL and kino paints it behind the video while the poster and first frame load, then the sharp poster covers it. Works on `MuxPlayer` and the headless `Player`.
+
+Fix playback-rate persistence across source swaps. Loading a new source resets the media element's `playbackRate` to `defaultPlaybackRate`, so the chosen speed dropped to 1x on every `swapSource`. kino now keeps `defaultPlaybackRate` in lockstep with the rate (seeded at mount, updated in `setRate`), so the rate survives lesson/source changes.

README.md

@@ -57,6 +57,16 @@ Give the player a sized container. It fills `100%` width and height of its paren
 
 kino is auth-agnostic. For signed playback you mint the `playback`, `thumbnail`, and `storyboard` tokens server-side and hand them to the player through the `tokens` prop. The player never holds a signing key and never talks to your auth layer; it only appends the tokens you give it to the media, thumbnail, and storyboard URLs. For public playback you can omit `tokens` entirely.
 
+### Blur-up placeholder
+
+Before the poster and first frame load, the video box is empty. Pass a small `placeholder` (a base64 data URI or a URL) and kino paints it behind the video as a blur-up; the sharp poster covers it once decoded, and it reappears briefly across source swaps.
+
+```tsx
+<MuxPlayer playbackId="..." placeholder={blurDataUrl} />
+```
+
+The poster itself stays the signed Mux thumbnail (kino derives it from `playbackId` + the `thumbnail` token), so `placeholder` is purely the instant low-res layer underneath.
+
 ## Theming
 
 The quickest knob is the `accentColor` prop, which drives the scrubber fill, active menu items, and range controls.

eslint.config.js

@@ -11,6 +11,6 @@ export default [
     },
   },
   {
-    ignores: ["dist/**", "node_modules/**"],
+    ignores: ["**/dist/**", "**/node_modules/**"],
   },
 ]

src/mux/mux-player.tsx

@@ -10,13 +10,16 @@ export type MuxPlayerProps = MuxProviderOptions & {
   accentColor?: string
   theme?: Record<string, string>
   className?: string
+  /** Blur-up still painted behind the video until the poster/first frame loads. */
+  placeholder?: string
   children?: ReactNode
 }
 
 export function MuxPlayer({
   accentColor,
   theme,
   className,
+  placeholder,
   children,
   ...opts
 }: MuxPlayerProps) {
@@ -57,6 +60,7 @@ export function MuxPlayer({
       accentColor={accentColor}
       theme={theme}
       className={className}
+      placeholder={placeholder}
     >
       <IdleOverlay />
       <Captions />

src/mux/provider.ts

@@ -298,7 +298,11 @@ export function createMuxProvider(opts: MuxProviderOptions): Provider {
       if (el) el.currentTime = t
     },
     setRate: (r) => {
-      if (el) el.playbackRate = r
+      if (!el) return
+      el.playbackRate = r
+      // Loading a new source resets playbackRate to defaultPlaybackRate, so keep
+      // them in lockstep — otherwise the chosen rate drops to 1x on every swap.
+      el.defaultPlaybackRate = r
     },
     setVolume: (v) => {
       if (el) el.volume = Math.min(1, Math.max(0, v))
@@ -367,6 +371,9 @@ export function createMuxProvider(opts: MuxProviderOptions): Provider {
         buildImageUrl(opts.playbackId, "thumbnail", opts.tokens?.thumbnail)
       if (opts.autoPlay) el.autoplay = true
       el.playbackRate = state.rate
+      // defaultPlaybackRate is what the element reverts to when a new source
+      // loads; seed it so the initial rate survives the first (and every) load.
+      el.defaultPlaybackRate = state.rate
       if (opts.envKey) el.envKey = opts.envKey
       if (opts.metadata) {
         el.metadata = {

src/styles/kino.css

@@ -34,6 +34,18 @@
   width: 100%;
   height: 100%;
 }
+.kino .kino-placeholder {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  /* Same level as the video host but earlier in the DOM, so the video element
+     (and its sharp poster, once decoded) paints over this blur-up. */
+  z-index: 0;
+  pointer-events: none;
+  user-select: none;
+}
 .kino .kino-video-host {
   position: absolute;
   inset: 0;

src/ui/player.test.tsx

@@ -16,6 +16,28 @@ test("renders children overlay and applies accent var", () => {
   expect(root.style.getPropertyValue("--kino-accent")).toBe("rgb(1,2,3)")
 })
 
+test("renders the placeholder behind the video host when given", () => {
+  const provider = createFakeProvider()
+  const { container } = render(
+    <Player provider={provider} placeholder="data:image/png;base64,AAAA" />,
+  )
+  const img = container.querySelector(".kino-placeholder") as HTMLImageElement
+  expect(img).toBeInTheDocument()
+  expect(img.getAttribute("src")).toBe("data:image/png;base64,AAAA")
+  // Must paint behind the video, so it precedes the host in the DOM.
+  const host = container.querySelector(".kino-video-host")
+  expect(
+    img.compareDocumentPosition(host as Node) &
+      Node.DOCUMENT_POSITION_FOLLOWING,
+  ).toBeTruthy()
+})
+
+test("omits the placeholder when not given", () => {
+  const provider = createFakeProvider()
+  const { container } = render(<Player provider={provider} />)
+  expect(container.querySelector(".kino-placeholder")).toBeNull()
+})
+
 test("space toggles playback via keyboard", () => {
   const provider = createFakeProvider({ paused: true })
   const { container } = render(<Player provider={provider} />)

src/ui/player.tsx

@@ -50,6 +50,12 @@ type PlayerProps = {
   accentColor?: string
   theme?: Record<string, string>
   className?: string
+  /**
+   * Low-res still (data URI or URL) painted behind the video while the poster
+   * and first frame load — a blur-up. The sharp poster covers it once decoded,
+   * so it only shows during the initial load and across source swaps.
+   */
+  placeholder?: string
   children?: ReactNode
 }
 
@@ -58,6 +64,7 @@ export function Player({
   accentColor,
   theme,
   className,
+  placeholder,
   children,
 }: PlayerProps) {
   const wrapperRef = useRef<HTMLDivElement | null>(null)
@@ -170,6 +177,15 @@ export function Player({
           style={style as CSSProperties}
           tabIndex={0}
         >
+          {placeholder && (
+            <img
+              className="kino-placeholder"
+              src={placeholder}
+              alt=""
+              aria-hidden="true"
+              draggable={false}
+            />
+          )}
           <div ref={videoHostRef} className="kino-video-host" />
           <PlayerChrome compact={compact}>{children}</PlayerChrome>
         </div>