docs(packages): ship skin eject discoverability via JSDoc @see links#1574
Open
decepulis wants to merge 2 commits into
Open
docs(packages): ship skin eject discoverability via JSDoc @see links#1574decepulis wants to merge 2 commits into
decepulis wants to merge 2 commits into
Conversation
AI coding agents read .d.ts files directly when answering Video.js questions. Without JSDoc on skin entry points, the eject path (copy/customize a packaged skin) is invisible to agents — they can see the skin function but not the docs page that explains how to use it. Adds an @see link in every skin export's JSDoc pointing to the published concepts/skins guide. The URL ships discoverability into the .d.ts so the eject pattern surfaces alongside the symbol. - Every skin variant in @videojs/react and @videojs/html, including Tailwind siblings. - Background-video plumbing (skin + player element + media element) gets matching JSDoc since it ships as part of the background preset. - CLAUDE.md gets a small "Skin JSDoc" section to codify the convention.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
decepulis
pushed a commit
that referenced
this pull request
May 20, 2026
Moves all skin JSDoc additions to #1574 — a smaller, focused PR that ships the eject-discoverability fix from #1558 with low review burden. This PR keeps the broader sweep (every public-API export across react / html / core, plus the CLAUDE.md rule that justifies it) for team discussion. Reverts: - All 16 React skin presets (audio, video, background, live-audio, live-video; including Tailwind siblings). - All 16 HTML skin defines (matching set). - Background plumbing: define/background/{skin,player}.ts, define/media/background-video.ts, react/media/background-video/index.tsx.
Contributor
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (8)
Players (5)
Skins (30)
UI Components (35)
Sizes are marginal over the root entry point. ⚛️ @videojs/react — no changesPresets (7)
Media (7)
Skins (27)
UI Components (29)
Sizes are marginal over the root entry point. 🧩 @videojs/core — no changesEntries (9)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (10)
📦 @videojs/spf — no changesEntries (3)
ℹ️ How to interpretAll sizes are standalone totals (minified + brotli).
Run |
6 tasks
The skin .d.ts files ship into AI agent context. Leading the customize sentence with "eject" puts the searchable term right in the symbol's JSDoc — agents pick it up without an extra round trip to the docs. Replaces the longer per-skin "build from primitives like X, Y, Z" prose with a single line that names the eject pattern explicitly and points at the docs for the rest.
mihar-22
approved these changes
May 20, 2026
Comment on lines
+523
to
+539
| ### Skin JSDoc | ||
|
|
||
| Skins — preset components that compose primitives into a complete player experience — carry an `@see` link in their JSDoc that points to the published skins guide. The URL ships discoverability into the `.d.ts` so IDE hover-docs, generated reference pages, and AI coding agents surface the guide alongside the symbol. | ||
|
|
||
| ```ts | ||
| /** | ||
| * Default video player skin with a complete media UI. | ||
| * | ||
| * To customize, eject this skin and build from primitives. Read more about eject in the docs. | ||
| * | ||
| * @see https://videojs.org/docs/framework/react/concepts/skins | ||
| */ | ||
| export function VideoSkin(props: VideoSkinProps): ReactNode; | ||
| ``` | ||
|
|
||
| The `@see` target must already exist. Tailwind variants share the body of their non-Tailwind sibling and add a one-liner noting the variant. | ||
|
|
Member
There was a problem hiding this comment.
Prefer if this was more generic by detailing how to document UI components for HTML and React.
Comment on lines
+86
to
89
| /** Custom element tag name. */ | ||
| static readonly tagName = 'live-audio-skin-tailwind'; | ||
| /** Shadow DOM template cloned into each instance. */ | ||
| static template = createTemplate(getTemplateHTML()); |
Member
There was a problem hiding this comment.
These comments add no value. Recommend removing all of the class field comments from the PR.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an
@seelink to every skin's JSDoc pointing to the publishedconcepts/skinsguide. Ships skin eject discoverability into the.d.tsfiles that AI coding agents read directly.Background
#1558 surfaced that AI coding agents Read 15–27 distinct
.d.tsfiles per Video.js install — they have the type signature in context but not the docs page that explains how to use it. The eject pattern — copy a packaged skin into your project and customize it — was invisible to agents because the skin's.d.tsdidn't link to the guide. Agents could seeVideoSkinbut not know "eject" was an option.What changed
@videojs/reactand@videojs/html(including Tailwind siblings) gets@see https://videojs.org/docs/framework/{react|html}/concepts/skins.define/background/{skin,player}.ts,define/media/background-video.ts,react/src/media/background-video/index.tsx) gets matching JSDoc since it ships as part of the background preset.CLAUDE.mdgets a small Skin JSDoc section codifying the convention.Pure additions — 38 files, +327 / -0.
Test plan
pnpm -F @videojs/react build && pnpm -F @videojs/html build— confirm@seesurvives into emitted.d.tspnpm typecheckcleanpnpm lintcleanRelationship to #1570
This is the first slice of #1570 — the eject-discoverability portion that fixes the immediate problem from #1558 with low review burden. The broader sweep (JSDoc on every public API export across react / html / core, plus the CLAUDE.md rule that justifies it) stays in #1570 for team discussion.
https://claude.ai/code/session_01YDMP31nT51YrdWKSqvkT98
Generated by Claude Code
Note
Low Risk
Low risk: changes are documentation-only JSDoc additions that should not affect runtime behavior, with the main risk being accidental TypeScript declaration/doc-generation formatting issues.
Overview
Adds a new Skin JSDoc convention to
CLAUDE.md, requiring skins to include an@seelink to the published skins guide so the link is carried into generated.d.tshover/docs.Applies that convention across
@videojs/htmland@videojs/reactby adding JSDoc blocks (including@see https://videojs.org/docs/framework/{html|react}/concepts/skins) to all skin exports/variants and to the background-video preset elements (BackgroundVideo*web components and the ReactBackgroundVideocomponent).Reviewed by Cursor Bugbot for commit 3196b04. Bugbot is set up for automated code reviews on this repo. Configure here.