[RFC] Primitives API & Feature Access

[mihar-22]

Closes #306

Summary

Folded feature accessor design into the player-api RFC as primitives.md.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

4 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
vjs-10-demo-html	Ignored	Preview	Jan 21, 2026 11:16am
vjs-10-demo-next	Ignored	Preview	Jan 21, 2026 11:16am
vjs-10-demo-react	Ignored	Preview	Jan 21, 2026 11:16am
vjs-10-website	Ignored	Preview	Jan 21, 2026 11:16am

[decepulis]

Amateur-hour question. Not asked skeptically.
What's the difference between the state returned from usePlayer() and useSlice()? Which will high-level authors have to access if they're, say, just building their own play button?

[mihar-22]

@decepulis useSlice is a both an internal and advanced API for anyone creating their own slices or primitives. The specific problems it's solving are outlined at the top of feature-accessor-design doc. Probably 99% of users will never see it. For everyone else, usePlayer is all you need.

Related-ish comment

[mihar-22]

• Renamed slice -> feature based on [RFC] Player API Design #300 (comment).
• Updated to use proxy design feat(store): add reactive state primitives #311

[decepulis]

@mihar-22 I had trouble grokking the top of feature-accessor-design.md in the context of my question (maybe that section could be fleshed out a bit for newbies like me). Regardless, I think I got my answer in feature-availability-design.md.

Seems to me like a high-level dev building their own volume slider would be accessing const { volume, volumeAvailability } = usePlayer() instead of useFeature(volumeFeature), right? Or... wait... this comment makes it seem like we can't use volumeAvailability internally. I wonder why. You say distributing UI components, but, I don't completely follow.

Meanwhile, feature developers will use useFeature for cross-feature access?

[mihar-22]

Thanks @luwes and @decepulis! Both of you calling it out made me go back to the drawing board and simplify the design.

I hope both of you are happy with this design! I'm merging to keep us moving but please feel free to leave more comments for us to discuss. Happy to update any time.

API surface

Primitives (component authors):

function PlayButton() {
  const player = usePlayer(); // UnknownPlayer
  
  // Type guard
  if (!hasFeature(player, features.playback)) {
    throwMissingFeature(features.playback, { displayName: 'PlayButton' });
  }
  
  // Typed here now
  return <button onClick={player.play}>{player.paused ? '▶' : '⏸'}</button>;
}

// Optional features
const volume = getFeature(player, features.volume);
volume.setVolume?.(0.5); // safe if missing

Feature authors — same flat API:

const fullscreen = createPlayerFeature({
  request: {
    enterFullscreen: (_, { target }) => {
      const mediaFS = getFeature(target.media, media.fullscreen);
      mediaFS.enterFullscreen?.(); // flat, not mediaFS.request.enterFullscreen()
    },
  },
});

Key changes

• target.media is now a flat proxy (UnknownMedia) — feature authors use same API as components
• Three utilities: hasFeature (guard), getFeature (optional), throwMissingFeature (critical)
• StoreProxy<T> interface — generic base for all proxies
• Folded into rfc/player-api/primitives.md