Skip to content
This repository was archived by the owner on Oct 21, 2026. It is now read-only.

feat(site): check that undocumented public exports are tagged internal - #3063

Merged
decepulis merged 25 commits into
claude/keen-mccarthy-7ams8m-radio-groupsfrom
claude/keen-mccarthy-7ams8m
Oct 1, 2026
Merged

decepulis merged 25 commits into
claude/keen-mccarthy-7ams8m-radio-groupsfrom
claude/keen-mccarthy-7ams8m

Conversation

@decepulis

@decepulis decepulis commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Part 2 of the API stability stack: #3073 (radio groups) → this PR → #3066 (docs rewrites) → #3067 (reference pages) → #3082 (exports) → #3068 (tags and CI) → #3083 (store).

Summary

Adds pnpm -F site check:api-stability (site/scripts/check-api-stability.ts). It reads the public surface from the built .d.ts files that each published package's exports map points at, so run pnpm build:packages first. Each export is resolved to its declaration, because that's where TypeScript reads JSDoc tags from.

Rules:

  1. Documented means stable. An export is stable when a reference page documents it. It's experimental when only a stability: unstable page documents it. A page documents:

    • its subject (title, frameworkTitle and doc-component props). media- is dropped only from a framework title, so media-play-button names PlayButton.
    • companion types (*Props, *State, *Element, *Options, *Result, *Config, and hook Use* types), when @videojs/react, @videojs/html or an extension package declares them. A same-named core or store type, such as core's MenuOptions beside the Menu page, isn't one.
    • parts written as Subject.Part
    • the select* selectors named on feature pages
    • a name that is a heading's whole text, such as ### `isMediaPauseCapable`
    • names in the first column of the tables under an ## Exports heading
    • anything in the new apis frontmatter field: an export name, an exact @videojs/... entry point (every export it has), or a * module pattern (each matched module's default export)

    Guides and examples don't count.

  2. Stability spreads through public types. An export named in a stable export's public types is stable too. That covers heritage clauses (extends/implements), public and protected members, type-alias targets, parameters, return types, type-parameter constraints and defaults, and declared types. The same applies to experimental.

    • Protected members count because they're what a subclass overrides or implements. A subclass's narrower redeclaration of an inherited protected member doesn't count, so each button element's core keeps its *Core class internal.
    • Private and @internal members don't count.
    • A type no entry exports, such as a local helper interface or the _base constant a mixin class extends, passes its own references on, because readers reach them through the export that names it.
    • A @videojs/utils type alias (Constructor, MixinReturn, …) counts as written out where it's used: it stays internal, and its target is checked instead.
    • A global the packages only augment, such as HTMLElementTagNameMap, doesn't spread stability to every element registered on it.
  3. Stable exports must be importable from a public package. Every stable or experimental export must be importable from @videojs/react, @videojs/html, @videojs/store or an extension package. Core, media, utils, element, SPF and the adapter packages don't count. --fix can't resolve this; you re-export the type or change the signature.

  4. Everything else is @internal. @deprecated also satisfies the rule. @experimental has to be earned by an unstable page or an experimental referrer; on an export nothing documents or references, --fix replaces it with @internal.

  5. A page overrides a tag. A stable export that still carries @internal or @experimental fails, and --fix removes the tag.

  6. Every declaration carries the tag: each declaration of a merged name, and each overload signature (not the implementation).

Other behaviour:

  • Stale apis entries fail. An entry that matches no public export or entry point fails the check, so a rename or removal can't leave one behind.
  • Namespaces: export * as Slider namespaces are walked, so parts such as Slider.Buffer are checked as SliderBuffer.
  • --fix: adds, replaces or removes tags on the matching src/ declaration. New comments go above // @ts-expect-error-style directives so those keep applying. Its output passes vp fmt.
  • Warnings (non-failing):
    • exports that can't be resolved, such as third-party re-exports
    • docs code that imports a non-stable export or an internal package
  • Out of scope: @videojs/spf (its maintainers own it) and @videojs/cdn (it re-bundles @videojs/html). @videojs/store is skipped here and checked in chore(store): check and tag store's public exports #3083.
  • Contributor docs: writing-style/write-references explains the rules and apis, the write-api-reference skill has a new step, and AGENTS.md has a one-line policy.

#3068 turns the check on in CI.

Preview pages

The only page this PR changes is Writing references. The Writing Style section is dev-only, so it isn't in the Netlify preview. Read the source on this branch, or run pnpm dev:site and open /docs/framework/react/writing-style/write-references.

Testing

  • site/scripts/tests/check-api-stability.test.ts: 65 tests pass.
  • pnpm -F site astro check --minimumSeverity warning: 0 errors, 0 warnings.
  • pnpm lint, pnpm check:workspace: pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH


Note

Low Risk
Adds an opt-in site script and documentation; it does not change runtime packages or enable CI until a follow-up PR.

Overview
Adds pnpm -F site check:api-stability, a TypeScript checker that walks published package .d.ts surfaces (after build:packages), reference MDX coverage, and JSDoc tags to enforce the public API stability model.

The script classifies exports as stable, experimental, or internal from what reference pages document (title, components, ## Exports, new optional apis frontmatter, module patterns, etc.) and transitive type references; it fails on wrong or missing @internal / @experimental tags, stable APIs not re-exported from framework-facing packages, and stale documented names. --fix rewrites tags in matching src/ declarations.

Contributor docs expand write-references, AGENTS.md, and the write-api-reference skill; content.config.ts validates optional apis. ~65 unit tests cover parsing, propagation, and fix behavior. SPF/store are excluded for now.

Reviewed by Cursor Bugbot for commit f33e3b6. Bugbot is set up for automated code reviews on this repo. Configure here.

Checks that every public package export is either documented on the
site or tagged @experimental/@internal/@deprecated, with a --fix mode
that adds @experimental. The documented-name rule is still being
decided; not yet wired into CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
@netlify

netlify Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for vjs-registry ready!

Name Link
🔨 Latest commit f33e3b6
🔍 Latest deploy log https://app.netlify.com/projects/vjs-registry/deploys/6abecd04a7e1fe00088c8053
😎 Deploy Preview https://deploy-preview-3063--vjs-registry.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@vercel

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
v10-sandbox Ready Ready Preview Oct 1, 2026 9:15pm UTC

Request Review

@netlify

netlify Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for vjs10-site ready!

Name Link
🔨 Latest commit f33e3b6
🔍 Latest deploy log https://app.netlify.com/projects/vjs10-site/deploys/6abecd043fd33500086043f8
😎 Deploy Preview https://deploy-preview-3063--vjs10-site.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@pkg-pr-new

pkg-pr-new Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
@videojs/cdn

pnpm add https://pkg.pr.new/@videojs/cdn@3063

@videojs/cli

pnpm add https://pkg.pr.new/@videojs/cli@3063

@videojs/core

pnpm add https://pkg.pr.new/@videojs/core@3063

@videojs/element

pnpm add https://pkg.pr.new/@videojs/element@3063

@videojs/html

pnpm add https://pkg.pr.new/@videojs/html@3063

@videojs/media

pnpm add https://pkg.pr.new/@videojs/media@3063

@videojs/react

pnpm add https://pkg.pr.new/@videojs/react@3063

@videojs/spf

pnpm add https://pkg.pr.new/@videojs/spf@3063

@videojs/store

pnpm add https://pkg.pr.new/@videojs/store@3063

@videojs/utils

pnpm add https://pkg.pr.new/@videojs/utils@3063

@videojs/cloudflare-video

pnpm add https://pkg.pr.new/@videojs/cloudflare-video@3063

@videojs/dash-video

pnpm add https://pkg.pr.new/@videojs/dash-video@3063

@videojs/hlsjs-video

pnpm add https://pkg.pr.new/@videojs/hlsjs-video@3063

@videojs/mux-audio

pnpm add https://pkg.pr.new/@videojs/mux-audio@3063

@videojs/mux-video

pnpm add https://pkg.pr.new/@videojs/mux-video@3063

@videojs/native-hls-video

pnpm add https://pkg.pr.new/@videojs/native-hls-video@3063

@videojs/shaka-video

pnpm add https://pkg.pr.new/@videojs/shaka-video@3063

@videojs/spotify-audio

pnpm add https://pkg.pr.new/@videojs/spotify-audio@3063

@videojs/tiktok-video

pnpm add https://pkg.pr.new/@videojs/tiktok-video@3063

@videojs/twitch-video

pnpm add https://pkg.pr.new/@videojs/twitch-video@3063

@videojs/vimeo-video

pnpm add https://pkg.pr.new/@videojs/vimeo-video@3063

@videojs/wistia-video

pnpm add https://pkg.pr.new/@videojs/wistia-video@3063

@videojs/youtube-video

pnpm add https://pkg.pr.new/@videojs/youtube-video@3063

@videojs/google-cast

pnpm add https://pkg.pr.new/@videojs/google-cast@3063

@videojs/mux-data

pnpm add https://pkg.pr.new/@videojs/mux-data@3063

commit: 7182bdb

The site typechecks against the ES2022 lib, so astro check rejected it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle Size Report

🎨 @videojs/html — no changes
Presets (7)
Entry Initial Lazy
/video (default) 65.26 kB 56.03 kB
/video (default + hls) 67.12 kB 56.03 kB
/video (neutral) 65.75 kB 56.03 kB
/video (neutral + hls) 67.52 kB 56.03 kB
/audio (default) 49.09 kB 56.03 kB
/audio (neutral) 49.45 kB 56.03 kB
/background 12.76 kB 56.03 kB
Media (18)
Entry Initial
/media/mux-video 3.03 kB
/media/mux-audio 2.71 kB
/media/background-video 1.17 kB
/media/cloudflare-video 2.91 kB
/media/dash-video 2.63 kB
/media/hls-audio 23.54 kB
/media/hls-background-video 17.56 kB
/media/hls-video 33.95 kB
/media/hlsjs-video 2.64 kB
/media/mux-background-video 17.58 kB
/media/native-hls-video 7.54 kB
/media/shaka-video 2.64 kB
/media/spotify-audio 3.03 kB
/media/tiktok-video 3.14 kB
/media/twitch-video 2.94 kB
/media/vimeo-video 2.92 kB
/media/wistia-video 615 B
/media/youtube-video 2.91 kB
Players (5)
Entry Initial Lazy
/video/player 10.85 kB 56.03 kB
/audio/player 7.05 kB 56.03 kB
/background/player 5.34 kB 56.03 kB
/live-video/player 10.23 kB 56.03 kB
/live-audio/player 7.06 kB 56.03 kB
Skins (41)
Entry Type Initial Lazy
/video/compat-skin.css css 7.48 kB —
/video/neutral-skin.css css 8.33 kB —
/video/skin.css css 8.05 kB —
/video/compat-skin js 62.40 kB 56.03 kB
/video/compat-skin2 js 7.45 kB —
/video/neutral-skin js 63.28 kB 56.03 kB
/video/neutral-skin2 js 8.32 kB —
/video/skin js 62.92 kB 56.03 kB
/video/skin2 js 8.02 kB —
/audio/compat-skin.css css 6.13 kB —
/audio/neutral-skin.css css 6.07 kB —
/audio/skin.css css 5.80 kB —
/audio/compat-skin js 53.92 kB 56.03 kB
/audio/compat-skin2 js 6.13 kB —
/audio/neutral-skin js 47.06 kB 56.03 kB
/audio/neutral-skin2 js 6.05 kB —
/audio/skin js 46.78 kB 56.03 kB
/audio/skin2 js 5.78 kB —
/background/skin.css css 141 B —
/background/skin js 10.18 kB 56.03 kB
/background/skin2 js 159 B —
/live-video/compat-skin.css css 6.92 kB —
/live-video/neutral-skin.css css 6.82 kB —
/live-video/skin.css css 6.72 kB —
/live-video/compat-skin js 53.70 kB 56.03 kB
/live-video/compat-skin2 js 6.91 kB —
/live-video/neutral-skin js 50.90 kB 56.03 kB
/live-video/neutral-skin2 js 6.82 kB —
/live-video/skin js 50.90 kB 56.03 kB
/live-video/skin2 js 6.72 kB —
/live-audio/compat-skin.css css 5.63 kB —
/live-audio/neutral-skin.css css 4.77 kB —
/live-audio/skin.css css 4.67 kB —
/live-audio/compat-skin js 40.87 kB 56.03 kB
/live-audio/compat-skin2 js 5.64 kB —
/live-audio/neutral-skin js 36.28 kB 56.03 kB
/live-audio/neutral-skin2 js 4.77 kB —
/live-audio/skin js 36.21 kB 56.03 kB
/live-audio/skin2 js 4.66 kB —
/global.css css 239 B —
/shadow.css css 78 B —
UI Components (62)
Entry Initial Lazy
/ui/airplay-button 11.57 kB 56.03 kB
/ui/alert-dialog 8.99 kB 56.03 kB
/ui/audio-track-radio-group 11.68 kB 56.03 kB
/ui/buffering-indicator 8.91 kB 56.03 kB
/ui/captions-button 11.83 kB 56.03 kB
/ui/captions-radio-group 11.73 kB 56.03 kB
/ui/cast-button 11.56 kB 56.03 kB
/ui/container 9.79 kB 56.03 kB
/ui/controls 9.10 kB 56.03 kB
/ui/controls-backdrop 1.69 kB 56.03 kB
/ui/controls-content 1.67 kB 56.03 kB
/ui/dialog 8.92 kB 56.03 kB
/ui/dialog-backdrop 1.70 kB 56.03 kB
/ui/dialog-close 2.06 kB 56.03 kB
/ui/dialog-description 1.69 kB 56.03 kB
/ui/dialog-popup 1.90 kB 56.03 kB
/ui/dialog-title 1.69 kB 56.03 kB
/ui/error-dialog 12.69 kB 56.03 kB
/ui/fullscreen-button 11.57 kB 56.03 kB
/ui/gesture 10.01 kB 56.03 kB
/ui/hotkey 10.40 kB 56.03 kB
/ui/live-button 10.09 kB 56.03 kB
/ui/menu 19.25 kB 56.03 kB
/ui/menu-checkbox-item 1.97 kB 56.03 kB
/ui/menu-content 7.65 kB 56.03 kB
/ui/menu-group 2.09 kB 56.03 kB
/ui/menu-group-label 1.64 kB —
/ui/menu-item 2.29 kB 56.03 kB
/ui/menu-item-indicator 1.38 kB 56.03 kB
/ui/menu-radio-group 3.03 kB 56.03 kB
/ui/menu-radio-item 2.14 kB 56.03 kB
/ui/menu-separator 1.30 kB 56.03 kB
/ui/mute-button 11.59 kB 56.03 kB
/ui/pip-button 11.54 kB 56.03 kB
/ui/play-button 11.53 kB 56.03 kB
/ui/playback-rate-button 11.63 kB 56.03 kB
/ui/playback-rate-radio-group 11.69 kB 56.03 kB
/ui/popover 8.77 kB 56.03 kB
/ui/poster 9.21 kB 56.03 kB
/ui/quality-radio-group 12.18 kB 56.03 kB
/ui/seek-button 11.58 kB 56.03 kB
/ui/seek-indicator 13.39 kB 56.03 kB
/ui/seek-indicator-value 1.10 kB —
/ui/slider 11.94 kB 56.03 kB
/ui/slider-preview 2.01 kB 56.03 kB
/ui/status-announcer 10.94 kB 56.03 kB
/ui/status-indicator 13.34 kB 56.03 kB
/ui/status-indicator-value 1.10 kB —
/ui/thumbnail 10.64 kB 56.03 kB
/ui/time 11.36 kB 56.03 kB
/ui/time-slider 13.44 kB 56.03 kB
/ui/time-slider-chapter-title 9.10 kB 56.03 kB
/ui/time-slider-chapters 9.92 kB 56.03 kB
/ui/title 8.48 kB 56.03 kB
/ui/tooltip 10.15 kB 56.03 kB
/ui/tooltip-label 1.21 kB —
/ui/tooltip-shortcut 1.18 kB —
/ui/volume-indicator 13.31 kB 56.03 kB
/ui/volume-indicator-fill 1.11 kB —
/ui/volume-indicator-value 1.10 kB —
/ui/volume-popover 15.21 kB 56.03 kB
/ui/volume-slider 12.65 kB 56.03 kB
⚛️ @videojs/react — no changes
Presets (7)
Entry Initial Lazy
/video (default) 58.75 kB 56.03 kB
/video (default + hls) 59.36 kB 56.03 kB
/video (neutral) 58.80 kB 56.03 kB
/video (neutral + hls) 59.38 kB 56.03 kB
/audio (default) 45.78 kB 56.03 kB
/audio (neutral) 45.67 kB 56.03 kB
/background 921 B 56.03 kB
Media (22)
Entry Initial
/media/mux-video/hls-js 1.47 kB
/media/mux-video/spf 1.47 kB
/media/mux-audio/hls-js 1.15 kB
/media/mux-audio/spf 1.14 kB
/media/background-video 532 B
/media/cloudflare-video 1.88 kB
/media/dash-video 1.13 kB
/media/hls-audio 22.20 kB
/media/hls-background-video 17.60 kB
/media/hls-video 32.64 kB
/media/hlsjs-video 1.13 kB
/media/mux-audio 1.13 kB
/media/mux-background-video 17.63 kB
/media/mux-video 1.46 kB
/media/native-hls-video 6.19 kB
/media/shaka-video 1.13 kB
/media/spotify-audio 1.94 kB
/media/tiktok-video 1.88 kB
/media/twitch-video 1.89 kB
/media/vimeo-video 1.85 kB
/media/wistia-video 1.42 kB
/media/youtube-video 1.86 kB
Extensions (2)
Entry Initial
/extensions/google-cast 613 B
/extensions/mux-data 665 B
Players (5)
Entry Initial Lazy
/video/player 8.68 kB 56.03 kB
/audio/player 4.90 kB 56.03 kB
/background/player 3.16 kB 56.03 kB
/live-video/player 8.07 kB 56.03 kB
/live-audio/player 4.91 kB 56.03 kB
Skins (26)
Entry Type Initial Lazy
/video/compat-skin.css css 7.35 kB —
/video/neutral-skin.css css 8.16 kB —
/video/skin.css css 7.86 kB —
/video/compat-skin js 59.66 kB 56.03 kB
/video/neutral-skin js 58.66 kB 56.03 kB
/video/skin js 58.72 kB 56.03 kB
/audio/compat-skin.css css 5.97 kB —
/audio/neutral-skin.css css 5.89 kB —
/audio/skin.css css 5.60 kB —
/audio/compat-skin js 50.66 kB 56.03 kB
/audio/neutral-skin js 45.57 kB 56.03 kB
/audio/skin js 45.58 kB 56.03 kB
/background/skin.css css 97 B —
/background/skin js 516 B —
/live-video/compat-skin.css css 6.81 kB —
/live-video/neutral-skin.css css 6.65 kB —
/live-video/skin.css css 6.55 kB —
/live-video/compat-skin js 55.54 kB 56.03 kB
/live-video/neutral-skin js 48.55 kB 56.03 kB
/live-video/skin js 48.59 kB 56.03 kB
/live-audio/compat-skin.css css 5.48 kB —
/live-audio/neutral-skin.css css 4.58 kB —
/live-audio/skin.css css 4.47 kB —
/live-audio/compat-skin js 41.85 kB 56.03 kB
/live-audio/neutral-skin js 33.86 kB 56.03 kB
/live-audio/skin js 33.86 kB 56.03 kB
UI Components (39)
Entry Initial Lazy
/ui/airplay-button 11.28 kB 56.03 kB
/ui/alert-dialog 5.21 kB 56.03 kB
/ui/audio-track 8.40 kB 56.03 kB
/ui/audio-track-radio-group 10.74 kB 56.03 kB
/ui/buffering-indicator 8.45 kB 56.03 kB
/ui/captions-button 11.26 kB 56.03 kB
/ui/captions-radio-group 10.81 kB 56.03 kB
/ui/cast-button 11.27 kB 56.03 kB
/ui/controls 8.34 kB 56.03 kB
/ui/dialog 5.20 kB 56.03 kB
/ui/error-dialog 12.66 kB 56.03 kB
/ui/fullscreen-button 11.24 kB 56.03 kB
/ui/gesture 8.61 kB 56.03 kB
/ui/hotkey 9.03 kB 56.03 kB
/ui/live-button 9.58 kB 56.03 kB
/ui/menu 22.05 kB 56.03 kB
/ui/mute-button 11.28 kB 56.03 kB
/ui/pip-button 11.24 kB 56.03 kB
/ui/play-button 11.20 kB 56.03 kB
/ui/playback-rate 8.45 kB 56.03 kB
/ui/playback-rate-button 11.20 kB 56.03 kB
/ui/playback-rate-radio-group 10.81 kB 56.03 kB
/ui/popover 9.12 kB 56.03 kB
/ui/poster 8.65 kB 56.03 kB
/ui/quality 8.82 kB 56.03 kB
/ui/quality-radio-group 11.15 kB 56.03 kB
/ui/seek-button 11.24 kB 56.03 kB
/ui/seek-indicator 13.12 kB 56.03 kB
/ui/slider 14.43 kB 56.03 kB
/ui/status-announcer 10.86 kB 56.03 kB
/ui/status-indicator 13.40 kB 56.03 kB
/ui/thumbnail 9.82 kB 56.03 kB
/ui/time 10.66 kB 56.03 kB
/ui/time-slider 16.18 kB 56.03 kB
/ui/title 7.93 kB 56.03 kB
/ui/tooltip 9.98 kB 56.03 kB
/ui/volume-indicator 13.43 kB 56.03 kB
/ui/volume-popover 15.58 kB 56.03 kB
/ui/volume-slider 13.02 kB 56.03 kB
🧩 @videojs/core — no changes
Entries (76)
Entry Initial Lazy
. 13.48 kB —
/dom 23.92 kB 56.03 kB
/vjsc 1.90 kB —
/i18n 3.21 kB 56.03 kB
/i18n/locales/all 33.91 kB —
/i18n/locales/ar 1.16 kB —
/i18n/locales/az 1.08 kB —
/i18n/locales/bg 1.29 kB —
/i18n/locales/bn 1.25 kB —
/i18n/locales/bs 1.02 kB —
/i18n/locales/ca 1.04 kB —
/i18n/locales/cs 1.10 kB —
/i18n/locales/cy 1.02 kB —
/i18n/locales/da 984 B —
/i18n/locales/de 1.06 kB —
/i18n/locales/el 1.42 kB —
/i18n/locales/en 801 B —
/i18n/locales/es 999 B —
/i18n/locales/et 1.02 kB —
/i18n/locales/eu 1.04 kB —
/i18n/locales/fa 1.21 kB —
/i18n/locales/fi 1.05 kB —
/i18n/locales/fr 1.01 kB —
/i18n/locales/gd 1.09 kB —
/i18n/locales/gl 1017 B —
/i18n/locales/he 1.10 kB —
/i18n/locales/hi 1.25 kB —
/i18n/locales/hr 1.05 kB —
/i18n/locales/hu 1.10 kB —
/i18n/locales/id 953 B —
/i18n/locales/it 1.01 kB —
/i18n/locales/ja 1.16 kB —
/i18n/locales/ko 1.08 kB —
/i18n/locales/lt 1.04 kB —
/i18n/locales/lv 1.09 kB —
/i18n/locales/mr 1.23 kB —
/i18n/locales/nb 990 B —
/i18n/locales/ne 1.23 kB —
/i18n/locales/nl 1.01 kB —
/i18n/locales/nn 983 B —
/i18n/locales/oc 1.05 kB —
/i18n/locales/pl 1.11 kB —
/i18n/locales/pt 1.02 kB —
/i18n/locales/pt-BR 1.02 kB —
/i18n/locales/pt-PT 1.02 kB —
/i18n/locales/ro 1.04 kB —
/i18n/locales/ru 1.36 kB —
/i18n/locales/sk 1.10 kB —
/i18n/locales/sl 1.04 kB —
/i18n/locales/sr 1.05 kB —
/i18n/locales/sv 1.01 kB —
/i18n/locales/te 1.29 kB —
/i18n/locales/th 1.20 kB —
/i18n/locales/tr 1.00 kB —
/i18n/locales/uk 1.37 kB —
/i18n/locales/vi 1.10 kB —
/i18n/locales/zh 1.01 kB —
/i18n/locales/zh-CN 1.01 kB —
/i18n/locales/zh-TW 1.02 kB —
/i18n/text/airplay 101 B —
/i18n/text/buttons 137 B —
/i18n/text/captions 93 B —
/i18n/text/cast 114 B —
/i18n/text/common 90 B —
/i18n/text/container 75 B —
/i18n/text/errors 285 B —
/i18n/text/fullscreen 98 B —
/i18n/text/live 126 B —
/i18n/text/menu 249 B —
/i18n/text/pip 101 B —
/i18n/text/playback 80 B —
/i18n/text/seek 105 B —
/i18n/text/slider 65 B —
/i18n/text/status 222 B —
/i18n/text/time 322 B —
/i18n/text/volume 133 B —
🏷️ @videojs/element — no changes
Entries (2)
Entry Initial
. 1.05 kB
/context 1.15 kB
📦 @videojs/store — no changes
Entries (3)
Entry Initial
. 1.85 kB
/html 703 B
/react 511 B
🔧 @videojs/utils — no changes
Entries (13)
Entry Initial
/array 271 B
/dom 5.25 kB
/events 320 B
/function 414 B
/i18n 249 B
/jwt 176 B
/object 535 B
/predicate 297 B
/percent 281 B
/string 239 B
/style 212 B
/time 1018 B
/number 199 B
📦 @videojs/cdn — no changes
📦 @videojs/cloudflare-video — no changes
📦 @videojs/dash-video — no changes
📦 @videojs/google-cast — no changes
📦 @videojs/hlsjs-video — no changes
📦 @videojs/media — no changes
Entries (3)
Entry Initial
. 3.22 kB
/dom 4.00 kB
/media-tracks 2.05 kB
📦 @videojs/mux — no changes
📦 @videojs/mux-audio — no changes
Entries (2)
Entry Initial
. 136.01 kB
/spf 22.76 kB
📦 @videojs/mux-data — no changes
📦 @videojs/mux-video — no changes
Entries (2)
Entry Initial
. 135.92 kB
/spf 32.99 kB
📦 @videojs/native-hls-video — no changes
📦 @videojs/shaka-video — no changes
📦 @videojs/spf — no changes
Entries (7)
Entry Initial
. 4.56 kB
/dom 7.85 kB
/hls 28.40 kB
/media-tracks 507 B
/hls-background-video 16.60 kB
/hls-audio 21.28 kB
/hls-video 31.73 kB
📦 @videojs/spotify-audio — no changes
📦 @videojs/tiktok-video — no changes
📦 @videojs/twitch-video — no changes
📦 @videojs/other — no changes
Entries (3)
Entry Initial Lazy
video.js 74.33 kB 56.03 kB
video.js/package.json 608 B —
video.js/errors 1.03 kB —
📦 @videojs/vimeo-video — no changes
📦 @videojs/wistia-video — no changes
Entries (2)
Entry Initial
. 1.91 kB
/helpers 1.76 kB
📦 @videojs/youtube-video — no changes

ℹ️ How to interpret

Each entry is independently bundled, minified, and brotli-compressed. Initial size includes its static import graph; lazy dynamic chunks are reported separately.

Entries are not additive because their dependency graphs overlap. Preset rows represent realistic combined bundles.

Changes of 300 B or less across initial, lazy, and total size are collapsed, not discarded.

Run pnpm size locally to check current initial sizes.

An export of a published package is stable only when a reference page
documents it: its subject, companion types, parts, feature selectors, or
names listed in the new `apis` frontmatter field. Every other export must
be tagged @internal, or @experimental when a `stability: unstable` page
documents it. `--fix` adds the missing tags to the source declaration.

SPF and store declarations are not checked yet. Docs imports of internal
packages or non-stable exports are reported as warnings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
@decepulis decepulis changed the title chore(site): enforce stability tags on undocumented public exports feat(site): check that undocumented public exports are tagged internal Sep 29, 2026
Each overload carries its own JSDoc, so tagging only the first left the
others looking stable in editor hovers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Matching `PlayerContext` against a documented `playerContext` made an
undocumented type stable. Case folding is only meant for a hook's
companion types, such as `UseHotkeyOptions` for `useHotkey`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Builds rename some entries (src/core/i18n/text built to i18n/text) and
copy private packages into another's dist, so their declarations don't
mirror src/. Match the path after the last dist/ against authored files
that declare the name, and use it only when the match is unique.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
- Fail when a stable or experimental export's public type surface
  (heritage, public members, aliased type, parameters, return and type
  parameters, declared type) names another public export that is
  internal. Private, protected, and @internal members are skipped, and
  --fix leaves these for a person to resolve. Report them grouped by
  the referenced export.
- Treat exports only @videojs/core, media, utils, element, icons, or
  skins entries expose as internal, whatever their name.
- Let the page win over the tag: a documented export tagged @internal
  (or @experimental on a stable page) fails, and --fix removes the tag
  or replaces @internal with @experimental, keeping any text the tag
  carried and deleting a comment it leaves empty.
- Walk `export * as X` namespaces and check each member, named
  `SliderBuffer` for `Slider.Buffer` and merged with its direct export.
- Require the tag on every declaration of a merged name and every
  overload signature, ignoring overload implementations.
- Insert tags where the formatter keeps them: after an @example block
  with a blank line, and before @see and @todo.
- Warn about exports that resolve to no declaration.
- Read `export default x` JSDoc from the declaration of `x`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
- Replace the failing "references internal" check with propagation to a
  fixed point: an export a stable export's public surface names becomes
  stable, and one only experimental exports name becomes experimental,
  whichever package exposes it. The surface is the one the reference
  check used (heritage, public members, aliased type, parameters, return
  and type parameters, declared type), with qualified names resolved to
  the rightmost public export and bundle copies matched by source.
- Keep heritage propagation behind PROPAGATE_THROUGH_HERITAGE (on), also
  exposed as the `heritage` option of resolveStabilities.
- Apply the tag rules to exports stable or experimental by reference:
  they lose a contradicting @internal (or get @experimental), --fix
  applies it, and the message names one referrer plus a count.
- Fail when a stable or experimental export is importable only from an
  internal or adapter package, suggesting the framework or /media/*
  entry to re-export it from. --fix leaves these alone.
- Print the exports stable and experimental by reference, grouped by
  package, with one referrer each.
- Update write-references and AGENTS.md for the transitive rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
… stability check

Types no entry exports (local helper interfaces, mixin _base constants) now
pass their own references on, so their public surface is checked. Undocumented
exports need @internal or @deprecated; @experimental is replaced. --fix inserts
tags above directive comments and skips overload implementations. Only react,
html, store and extension packages count as importable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

Comment thread site/scripts/check-api-stability.ts Resolved
…een-mccarthy-7ams8m

# Conflicts:
#	site/package.json

Copy link
Copy Markdown
Collaborator Author

The Website Tests test failure here comes from main, not this PR. It's the issue described in #3066 (comment): three analytics tests that #3087 added expect installation_skin: "minimal-video" but get "video". #3073 fails the same way, and nothing in the stack touches the installation code. There's no fix yet; I'll merge one in once it lands on main.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 1e67ed0. Configure here.

Comment thread site/scripts/check-api-stability.ts Resolved

@mihar-22 mihar-22 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stack review (Claude, cross-checked with Codex gpt-6.1-sol). I built the top of the stack at f30ca59. check:api-stability passes (1,901 exports), its 65 tests pass, and pnpm typecheck passes uncached. Three items below, none blocking: one medium, two low. Everything already raised and resolved in earlier threads is left out.

Comment thread site/scripts/check-api-stability.ts Resolved
Comment thread site/scripts/check-api-stability.ts Resolved
Comment thread site/scripts/check-api-stability.ts Resolved
claude added 3 commits October 1, 2026 18:51
- Feature pages no longer cover their title: `Volume`, `Error`, and
  the other feature titles are labels, and the `*Feature` the page's
  reference names is the subject.
- Destructured exports, such as the presets'
  `export const { Player: VideoPlayer, usePlayer } = …`, resolve to
  their source, so `--fix` can tag them.
- The stale check covers code headings and Exports-table names as well
  as `apis`, so a rename fails wherever a page names the export.
- Namespace and side-effect imports, and `export … from`, reach the
  internal-package warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
@decepulis
decepulis removed this pull request from stack #3089 October 1, 2026 20:38
@decepulis
decepulis changed the base branch from main to claude/keen-mccarthy-7ams8m-radio-groups October 1, 2026 20:39
@decepulis
decepulis added this pull request to stack #3123 October 1, 2026 20:42
@decepulis
decepulis merged commit 58122c9 into main Oct 1, 2026
20 of 21 checks passed
@decepulis
decepulis deleted the claude/keen-mccarthy-7ams8m branch October 1, 2026 21:17

This branch was successfully deployed

1 active deployment
Preview — f33e3b61 Deployed Oct 1, 2026 by vercel[bot]
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants