@videojs/html 10.2.0 → 10.3.0

package/dist/dev/ui/radio-options/controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"controller.js","names":[],"sources":["../../../../src/ui/radio-options/controller.ts"],"sourcesContent":["import type { RadioOption, RadioOptionsState } from '@videojs/core';\nimport { applyElementProps } from '@videojs/core/dom';\nimport { type Translator, translateText } from '@videojs/core/i18n';\nimport type { ReactiveController, ReactiveControllerHost } from '@videojs/element';\nimport { cloneTemplateRoot, getTemplateElement, getTemplateRoot } from '@videojs/utils/dom';\n\nimport { cacheKey } from '../../i18n/cache-key';\nimport { MenuItemIndicatorElement } from '../menu/item-indicator';\nimport { MenuRadioItemElement } from '../menu/radio-item';\n\nexport type RadioOptionsControllerHost = ReactiveControllerHost &\n  HTMLElement & {\n    value: string;\n  };\n\nexport interface RadioOptionsControllerConfig<Option extends RadioOption> {\n  renderItem?: ((item: MenuRadioItemElement, label: string, option: Option) => void) | undefined;\n  setItemAttributes?: ((item: MenuRadioItemElement, option: Option) => void) | undefined;\n  getOptionCacheKey?: ((option: Option) => string) | undefined;\n  onValueChange: (value: string) => void;\n}\n\n/** Renders normalized options into menu radio items and manages their interaction lifecycle. */\nexport class RadioOptionsController<Option extends RadioOption> implements ReactiveController {\n  readonly #host: RadioOptionsControllerHost;\n  readonly #config: RadioOptionsControllerConfig<Option>;\n\n  #contentKey = '';\n  #translator: Translator | null = null;\n  #disconnect: AbortController | null = null;\n\n  constructor(host: RadioOptionsControllerHost, config: RadioOptionsControllerConfig<Option>) {\n    this.#host = host;\n    this.#config = config;\n    host.addController(this);\n  }\n\n  hostConnected(): void {\n    this.#disconnect = new AbortController();\n    this.#host.addEventListener('value-change', this.#handleValueChange, { signal: this.#disconnect.signal });\n  }\n\n  hostDisconnected(): void {\n    this.#disconnect?.abort();\n    this.#disconnect = null;\n  }\n\n  hostDestroyed(): void {\n    this.hostDisconnected();\n  }\n\n  sync(state: RadioOptionsState<Option>, translator: Translator, locale: string): void {\n    this.#host.value = state.value;\n    applyElementProps(this.#host, {\n      'aria-disabled': state.disabled ? 'true' : undefined,\n      hidden: state.hidden ? '' : undefined,\n    });\n\n    const template = getTemplateElement(this.#host);\n    const templateRoot = template ? getTemplateRoot(template) : null;\n    const itemRoot = templateRoot?.localName === MenuRadioItemElement.tagName ? templateRoot : null;\n\n    const contentKey = `${state.options\n      .map(\n        (option) =>\n          `${option.value}:${cacheKey(option.label, option.labelParams)}:${this.#config.getOptionCacheKey?.(option) ?? ''}`\n      )\n      .join('|')}::${locale}::${template?.innerHTML ?? ''}`;\n\n    if (contentKey !== this.#contentKey || translator !== this.#translator) {\n      this.#contentKey = contentKey;\n      this.#translator = translator;\n\n      for (const child of [...this.#host.children]) {\n        if (child === template) continue;\n\n        child.remove();\n      }\n\n      const items = state.options.map((option) => {\n        const item = itemRoot\n          ? (cloneTemplateRoot(itemRoot, this.#host.ownerDocument) as MenuRadioItemElement)\n          : (this.#host.ownerDocument.createElement(MenuRadioItemElement.tagName) as MenuRadioItemElement);\n\n        item.value = option.value;\n        this.#config.setItemAttributes?.(item, option);\n        const label = translateText(option.label, translator, option.labelParams);\n\n        if (this.#config.renderItem) this.#config.renderItem(item, label, option);\n        else this.#setItemLabel(item, label);\n\n        return item;\n      });\n\n      this.#host.append(...items);\n    }\n\n    const optionsByValue = new Map(state.options.map((option) => [option.value, option]));\n\n    for (const item of this.#host.querySelectorAll<MenuRadioItemElement>(MenuRadioItemElement.tagName)) {\n      const checked = item.value === state.value;\n      const option = optionsByValue.get(item.value);\n\n      item.disabled = state.disabled || option?.disabled === true;\n\n      for (const indicator of item.querySelectorAll<MenuItemIndicatorElement>(MenuItemIndicatorElement.tagName)) {\n        indicator.checked = checked;\n      }\n    }\n  }\n\n  #handleValueChange = (event: Event): void => {\n    if (event.target !== this.#host) return;\n\n    const { value } = (event as CustomEvent<{ value: string }>).detail;\n\n    this.#config.onValueChange(value);\n  };\n\n  #setItemLabel(item: MenuRadioItemElement, label: string): void {\n    const labelPart = item.querySelector<HTMLElement>('[data-part~=\"label\"]');\n\n    if (labelPart) labelPart.textContent = label;\n    else item.textContent = label;\n  }\n}\n"],"mappings":";;;;;;;;AAuBA,IAAa,yBAAb,MAA8F;CAC5F;CACA;CAEA,cAAc;CACd,cAAiC;CACjC,cAAsC;CAEtC,YAAY,MAAkC,QAA8C;EAC1F,KAAK,QAAQ;EACb,KAAK,UAAU;EACf,KAAK,cAAc,IAAI;CACzB;CAEA,gBAAsB;EACpB,KAAK,cAAc,IAAI,gBAAgB;EACvC,KAAK,MAAM,iBAAiB,gBAAgB,KAAK,oBAAoB,EAAE,QAAQ,KAAK,YAAY,OAAO,CAAC;CAC1G;CAEA,mBAAyB;EACvB,KAAK,aAAa,MAAM;EACxB,KAAK,cAAc;CACrB;CAEA,gBAAsB;EACpB,KAAK,iBAAiB;CACxB;CAEA,KAAK,OAAkC,YAAwB,QAAsB;EACnF,KAAK,MAAM,QAAQ,MAAM;EACzB,kBAAkB,KAAK,OAAO;GAC5B,iBAAiB,MAAM,WAAW,SAAS,KAAA;GAC3C,QAAQ,MAAM,SAAS,KAAK,KAAA;EAC9B,CAAC;EAED,MAAM,WAAW,mBAAmB,KAAK,KAAK;EAC9C,MAAM,eAAe,WAAW,gBAAgB,QAAQ,IAAI;EAC5D,MAAM,WAAW,cAAc,cAAc,qBAAqB,UAAU,eAAe;EAE3F,MAAM,aAAa,GAAG,MAAM,QACzB,KACE,WACC,GAAG,OAAO,MAAM,GAAG,SAAS,OAAO,OAAO,OAAO,WAAW,EAAE,GAAG,KAAK,QAAQ,oBAAoB,MAAM,KAAK,IACjH,CAAC,CACA,KAAK,GAAG,EAAE,IAAI,OAAO,IAAI,UAAU,aAAa;EAEnD,IAAI,eAAe,KAAK,eAAe,eAAe,KAAK,aAAa;GACtE,KAAK,cAAc;GACnB,KAAK,cAAc;GAEnB,KAAK,MAAM,SAAS,CAAC,GAAG,KAAK,MAAM,QAAQ,GAAG;IAC5C,IAAI,UAAU,UAAU;IAExB,MAAM,OAAO;GACf;GAEA,MAAM,QAAQ,MAAM,QAAQ,KAAK,WAAW;IAC1C,MAAM,OAAO,WACR,kBAAkB,UAAU,KAAK,MAAM,aAAa,IACpD,KAAK,MAAM,cAAc,cAAc,qBAAqB,OAAO;IAExE,KAAK,QAAQ,OAAO;IACpB,KAAK,QAAQ,oBAAoB,MAAM,MAAM;IAC7C,MAAM,QAAQ,cAAc,OAAO,OAAO,YAAY,OAAO,WAAW;IAExE,IAAI,KAAK,QAAQ,YAAY,KAAK,QAAQ,WAAW,MAAM,OAAO,MAAM;SACnE,KAAK,cAAc,MAAM,KAAK;IAEnC,OAAO;GACT,CAAC;GAED,KAAK,MAAM,OAAO,GAAG,KAAK;EAC5B;EAEA,MAAM,iBAAiB,IAAI,IAAI,MAAM,QAAQ,KAAK,WAAW,CAAC,OAAO,OAAO,MAAM,CAAC,CAAC;EAEpF,KAAK,MAAM,QAAQ,KAAK,MAAM,iBAAuC,qBAAqB,OAAO,GAAG;GAClG,MAAM,UAAU,KAAK,UAAU,MAAM;GACrC,MAAM,SAAS,eAAe,IAAI,KAAK,KAAK;GAE5C,KAAK,WAAW,MAAM,YAAY,QAAQ,aAAa;GAEvD,KAAK,MAAM,aAAa,KAAK,iBAA2C,yBAAyB,OAAO,GACtG,UAAU,UAAU;EAExB;CACF;CAEA,sBAAsB,UAAuB;EAC3C,IAAI,MAAM,WAAW,KAAK,OAAO;EAEjC,MAAM,EAAE,UAAW,MAAyC;EAE5D,KAAK,QAAQ,cAAc,KAAK;CAClC;CAEA,cAAc,MAA4B,OAAqB;EAC7D,MAAM,YAAY,KAAK,cAA2B,wBAAsB;EAExE,IAAI,WAAW,UAAU,cAAc;OAClC,KAAK,cAAc;CAC1B;AACF"}
+{"version":3,"file":"controller.js","names":[],"sources":["../../../../src/ui/radio-options/controller.ts"],"sourcesContent":["import type { RadioOption, RadioOptionsState } from '@videojs/core';\nimport { applyElementProps } from '@videojs/core/dom';\nimport { type Translator, translateText } from '@videojs/core/i18n';\nimport type { ReactiveController, ReactiveControllerHost } from '@videojs/element';\nimport { cloneTemplateRoot, getTemplateElement, getTemplateRoot } from '@videojs/utils/dom';\nimport { isUndefined } from '@videojs/utils/predicate';\n\nimport { cacheKey } from '../../i18n/cache-key';\nimport { MenuItemIndicatorElement } from '../menu/item-indicator';\nimport { MenuRadioItemElement } from '../menu/radio-item';\n\nexport type RadioOptionsControllerHost = ReactiveControllerHost &\n  HTMLElement & {\n    value: string;\n  };\n\nexport interface RadioOptionsControllerConfig<Option extends RadioOption> {\n  renderItem?: ((item: MenuRadioItemElement, label: string, option: Option) => void) | undefined;\n  setItemAttributes?: ((item: MenuRadioItemElement, option: Option) => void) | undefined;\n  getOptionCacheKey?: ((option: Option) => string) | undefined;\n  onValueChange: (value: string) => void;\n}\n\n/** Renders normalized options into menu radio items and manages their interaction lifecycle. */\nexport class RadioOptionsController<Option extends RadioOption> implements ReactiveController {\n  readonly #host: RadioOptionsControllerHost;\n  readonly #config: RadioOptionsControllerConfig<Option>;\n\n  #contentKey = '';\n  #translator: Translator | null = null;\n  #disconnect: AbortController | null = null;\n\n  constructor(host: RadioOptionsControllerHost, config: RadioOptionsControllerConfig<Option>) {\n    this.#host = host;\n    this.#config = config;\n    host.addController(this);\n  }\n\n  hostConnected(): void {\n    this.#disconnect = new AbortController();\n    this.#host.addEventListener('value-change', this.#handleValueChange, { signal: this.#disconnect.signal });\n  }\n\n  hostDisconnected(): void {\n    this.#disconnect?.abort();\n    this.#disconnect = null;\n  }\n\n  hostDestroyed(): void {\n    this.hostDisconnected();\n  }\n\n  sync(state: RadioOptionsState<Option>, translator: Translator, locale: string): void {\n    this.#host.value = state.value;\n    applyElementProps(this.#host, {\n      'aria-disabled': state.disabled ? 'true' : undefined,\n      hidden: state.hidden ? '' : undefined,\n    });\n\n    const template = getTemplateElement(this.#host);\n    const templateRoot = template ? getTemplateRoot(template) : null;\n    const itemRoot = templateRoot?.localName === MenuRadioItemElement.tagName ? templateRoot : null;\n\n    const contentKey = `${state.options\n      .map(\n        (option) =>\n          `${option.value}:${cacheKey(option.label, option.labelParams)}:${cacheKey(option.ariaLabel ?? '', option.ariaLabelParams)}:${this.#config.getOptionCacheKey?.(option) ?? ''}`\n      )\n      .join('|')}::${locale}::${template?.innerHTML ?? ''}`;\n\n    if (contentKey !== this.#contentKey || translator !== this.#translator) {\n      this.#contentKey = contentKey;\n      this.#translator = translator;\n\n      const staleChildren = [...this.#host.children].filter((child) => child !== template);\n      const focusedValue = this.#getFocusedItem()?.value;\n\n      const items = state.options.map((option) => {\n        const item = itemRoot\n          ? (cloneTemplateRoot(itemRoot, this.#host.ownerDocument) as MenuRadioItemElement)\n          : (this.#host.ownerDocument.createElement(MenuRadioItemElement.tagName) as MenuRadioItemElement);\n\n        item.value = option.value;\n        this.#config.setItemAttributes?.(item, option);\n        const label = translateText(option.label, translator, option.labelParams);\n\n        if (this.#config.renderItem) this.#config.renderItem(item, label, option);\n        else this.#setItemLabel(item, label);\n\n        if (!isUndefined(option.ariaLabel)) {\n          item.setAttribute('aria-label', translateText(option.ariaLabel, translator, option.ariaLabelParams));\n        }\n\n        return item;\n      });\n\n      this.#host.append(...items);\n\n      const removeStale = () => {\n        for (const child of staleChildren) child.remove();\n      };\n\n      // Removing the focused item fires a `focusout` with no destination, which closes an open menu. Its replacement\n      // registers with the menu, and becomes focusable, on its first update, so the old items stay until focus can move.\n      const replacement = isUndefined(focusedValue)\n        ? undefined\n        : (items.find((item) => item.value === focusedValue) ?? items.find((item) => item.value === state.value));\n\n      if (replacement) {\n        void replacement.updateComplete.then(() => {\n          replacement.focus();\n          removeStale();\n        });\n      } else {\n        removeStale();\n      }\n    }\n\n    const optionsByValue = new Map(state.options.map((option) => [option.value, option]));\n\n    for (const item of this.#host.querySelectorAll<MenuRadioItemElement>(MenuRadioItemElement.tagName)) {\n      const checked = item.value === state.value;\n      const option = optionsByValue.get(item.value);\n\n      item.disabled = state.disabled || option?.disabled === true;\n\n      for (const indicator of item.querySelectorAll<MenuItemIndicatorElement>(MenuItemIndicatorElement.tagName)) {\n        indicator.checked = checked;\n      }\n    }\n  }\n\n  #handleValueChange = (event: Event): void => {\n    if (event.target !== this.#host) return;\n\n    const { value } = (event as CustomEvent<{ value: string }>).detail;\n\n    this.#config.onValueChange(value);\n  };\n\n  #getFocusedItem(): MenuRadioItemElement | null {\n    const active = (this.#host.getRootNode() as Document | ShadowRoot).activeElement;\n\n    return active instanceof MenuRadioItemElement && active.parentElement === this.#host ? active : null;\n  }\n\n  #setItemLabel(item: MenuRadioItemElement, label: string): void {\n    const labelPart = item.querySelector<HTMLElement>('[data-part~=\"label\"]');\n\n    if (labelPart) labelPart.textContent = label;\n    else item.textContent = label;\n  }\n}\n"],"mappings":";;;;;;;;;AAwBA,IAAa,yBAAb,MAA8F;CAC5F;CACA;CAEA,cAAc;CACd,cAAiC;CACjC,cAAsC;CAEtC,YAAY,MAAkC,QAA8C;EAC1F,KAAK,QAAQ;EACb,KAAK,UAAU;EACf,KAAK,cAAc,IAAI;CACzB;CAEA,gBAAsB;EACpB,KAAK,cAAc,IAAI,gBAAgB;EACvC,KAAK,MAAM,iBAAiB,gBAAgB,KAAK,oBAAoB,EAAE,QAAQ,KAAK,YAAY,OAAO,CAAC;CAC1G;CAEA,mBAAyB;EACvB,KAAK,aAAa,MAAM;EACxB,KAAK,cAAc;CACrB;CAEA,gBAAsB;EACpB,KAAK,iBAAiB;CACxB;CAEA,KAAK,OAAkC,YAAwB,QAAsB;EACnF,KAAK,MAAM,QAAQ,MAAM;EACzB,kBAAkB,KAAK,OAAO;GAC5B,iBAAiB,MAAM,WAAW,SAAS,KAAA;GAC3C,QAAQ,MAAM,SAAS,KAAK,KAAA;EAC9B,CAAC;EAED,MAAM,WAAW,mBAAmB,KAAK,KAAK;EAC9C,MAAM,eAAe,WAAW,gBAAgB,QAAQ,IAAI;EAC5D,MAAM,WAAW,cAAc,cAAc,qBAAqB,UAAU,eAAe;EAE3F,MAAM,aAAa,GAAG,MAAM,QACzB,KACE,WACC,GAAG,OAAO,MAAM,GAAG,SAAS,OAAO,OAAO,OAAO,WAAW,EAAE,GAAG,SAAS,OAAO,aAAa,IAAI,OAAO,eAAe,EAAE,GAAG,KAAK,QAAQ,oBAAoB,MAAM,KAAK,IAC7K,CAAC,CACA,KAAK,GAAG,EAAE,IAAI,OAAO,IAAI,UAAU,aAAa;EAEnD,IAAI,eAAe,KAAK,eAAe,eAAe,KAAK,aAAa;GACtE,KAAK,cAAc;GACnB,KAAK,cAAc;GAEnB,MAAM,gBAAgB,CAAC,GAAG,KAAK,MAAM,QAAQ,CAAC,CAAC,QAAQ,UAAU,UAAU,QAAQ;GACnF,MAAM,eAAe,KAAK,gBAAgB,CAAC,EAAE;GAE7C,MAAM,QAAQ,MAAM,QAAQ,KAAK,WAAW;IAC1C,MAAM,OAAO,WACR,kBAAkB,UAAU,KAAK,MAAM,aAAa,IACpD,KAAK,MAAM,cAAc,cAAc,qBAAqB,OAAO;IAExE,KAAK,QAAQ,OAAO;IACpB,KAAK,QAAQ,oBAAoB,MAAM,MAAM;IAC7C,MAAM,QAAQ,cAAc,OAAO,OAAO,YAAY,OAAO,WAAW;IAExE,IAAI,KAAK,QAAQ,YAAY,KAAK,QAAQ,WAAW,MAAM,OAAO,MAAM;SACnE,KAAK,cAAc,MAAM,KAAK;IAEnC,IAAI,CAAC,YAAY,OAAO,SAAS,GAC/B,KAAK,aAAa,cAAc,cAAc,OAAO,WAAW,YAAY,OAAO,eAAe,CAAC;IAGrG,OAAO;GACT,CAAC;GAED,KAAK,MAAM,OAAO,GAAG,KAAK;GAE1B,MAAM,oBAAoB;IACxB,KAAK,MAAM,SAAS,eAAe,MAAM,OAAO;GAClD;GAIA,MAAM,cAAc,YAAY,YAAY,IACxC,KAAA,IACC,MAAM,MAAM,SAAS,KAAK,UAAU,YAAY,KAAK,MAAM,MAAM,SAAS,KAAK,UAAU,MAAM,KAAK;GAEzG,IAAI,aACF,YAAiB,eAAe,WAAW;IACzC,YAAY,MAAM;IAClB,YAAY;GACd,CAAC;QAED,YAAY;EAEhB;EAEA,MAAM,iBAAiB,IAAI,IAAI,MAAM,QAAQ,KAAK,WAAW,CAAC,OAAO,OAAO,MAAM,CAAC,CAAC;EAEpF,KAAK,MAAM,QAAQ,KAAK,MAAM,iBAAuC,qBAAqB,OAAO,GAAG;GAClG,MAAM,UAAU,KAAK,UAAU,MAAM;GACrC,MAAM,SAAS,eAAe,IAAI,KAAK,KAAK;GAE5C,KAAK,WAAW,MAAM,YAAY,QAAQ,aAAa;GAEvD,KAAK,MAAM,aAAa,KAAK,iBAA2C,yBAAyB,OAAO,GACtG,UAAU,UAAU;EAExB;CACF;CAEA,sBAAsB,UAAuB;EAC3C,IAAI,MAAM,WAAW,KAAK,OAAO;EAEjC,MAAM,EAAE,UAAW,MAAyC;EAE5D,KAAK,QAAQ,cAAc,KAAK;CAClC;CAEA,kBAA+C;EAC7C,MAAM,SAAU,KAAK,MAAM,YAAY,CAAC,CAA2B;EAEnE,OAAO,kBAAkB,wBAAwB,OAAO,kBAAkB,KAAK,QAAQ,SAAS;CAClG;CAEA,cAAc,MAA4B,OAAqB;EAC7D,MAAM,YAAY,KAAK,cAA2B,wBAAsB;EAExE,IAAI,WAAW,UAAU,cAAc;OAClC,KAAK,cAAc;CAC1B;AACF"}

package/dist/dev/version.js

@@ -1,7 +1,7 @@
 //#region src/version.ts
 const readVersion = () => {
 	try {
-		return "10.2.0";
+		return "10.3.0";
 	} catch {}
 	return "UNKNOWN";
 };

package/docs/README.md

@@ -1,6 +1,6 @@
 # @videojs/html documentation
 
-Bundled markdown documentation for `@videojs/html` v10.2.0.
+Bundled markdown documentation for `@videojs/html` v10.3.0.
 
 Start at [`./llms.txt`](./llms.txt) — it's the structured index of every page in this directory.
 

package/docs/guides/autoplay.md

@@ -87,7 +87,7 @@ import '@videojs/html/ui/play-button';
 
 The `autoplay`, `muted`, and `playsinline` attributes on `<video>` and similar media components pass through to the underlying media element. The media element applies the attributes it supports and requests playback as soon as it has enough data.
 
-The [playback feature](../reference/api/feature-playback.md) reflects the result in player state. When autoplay succeeds, `paused` becomes `false` and `started` becomes `true`. When the browser blocks autoplay, the player stays `paused: true` with `started: false`, and the [Play button](../reference/components/play-button.md) renders its play state. There is no separate autoplay failure event: a blocked autoplay looks like media that never started.
+The [playback feature](../reference/api/feature-playback.md) reflects the result in player state. While the media is trying to autoplay, `autoplaying` is `true`: the [Play button](../reference/components/play-button.md) shows pause, so clicking it cancels the autoplay, and the [Buffering indicator](../reference/components/buffering-indicator.md) appears after its delay. When autoplay succeeds, `paused` becomes `false` and `started` becomes `true`. When the browser blocks autoplay, the player stays `paused: true` with `started: false`, and the [Play button](../reference/components/play-button.md) renders its play state. There is no separate autoplay failure event: a blocked autoplay looks like media that never started.
 
 Calling `play()` from player state returns the native promise from the media element. When the browser blocks playback, that promise rejects with a `NotAllowedError`.
 

package/docs/guides/browser-support.md

@@ -16,6 +16,8 @@ These versions account for 92.5% of global web usage according to [caniuse-lite]
 
 We test in and fix bugs for these versions. Each minimum comes from a feature with no fallback: `:has()` sets Firefox, [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix) and [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) set Chrome and Edge (Chrome 111, Firefox 113, Safari 16.2), and the JavaScript sets Safari, because it uses ES2022 syntax and [`adoptedStyleSheets`](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets). Newer JavaScript APIs are feature-detected.
 
+These versions apply to every skin. The [Compat and Scaffold skins](./skins.md#choose-a-skin) avoid newer visual effects such as backdrop blur, anchor-positioned menu highlights, and squircle corners, so they look the same in browsers that skip them. They still need the CSS features below.
+
 ## CSS requirements
 
 The packaged skins are generated CSS, and the build lowers them for the browsers above. It flattens CSS nesting, adds vendor prefixes such as `-webkit-backdrop-filter`, and writes each skin’s scope as a [`:where()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where) selector, which adds no specificity, rather than [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope).

package/docs/guides/build-your-own-skin.md

@@ -8,7 +8,7 @@ If a packaged skin is already close to what you want, [Customize skins](./custom
 
 ## Create a skin project
 
-The quickest way to start is a standalone skin project:
+The quickest way to start is a standalone skin project. You need [Node.js](https://nodejs.org/) to create the project, run the workbench that previews your skin, and deploy it. Run `node -v` to see which version you have. If you don’t have Node.js, or yours is a few years old, install the latest LTS release.
 
 **npm**
 
@@ -107,6 +107,8 @@ If you work with a coding agent, such as Claude Code, Codex, or Cursor, it can d
 npx @videojs/cli agents skills
 ```
 
+The agent runs the same commands as you would, so it needs Node.js too. If Node.js isn’t installed, you can ask the agent to install it, but it may need your permission or your password to do so.
+
 Then ask your agent something like “Help me design my own Video.js skin for our podcast player.” It asks for the same choices as the command, creates the project, starts the workbench, and agrees a design with you before styling. It can also match an existing player’s look from a screenshot or a link, then checks its work against the reference and for accessibility before handing back. [Build with AI](./build-with-ai.md) covers installing the skills in each agent.
 
 ## Other starting points

package/docs/guides/cdn.md

@@ -25,6 +25,7 @@ Each installation [preset](./presets.md) ships its bundles at the package root:
 | `video.js` | `<video-player>`, `<video-skin>`, and the UI elements the skin composes |
 | `video-neutral.js` | `<video-player>`, `<video-neutral-skin>`, and the UI elements the neutral skin composes |
 | `video-compat.js` | `<video-player>`, `<video-compat-skin>`, and the UI elements the compat skin composes |
+| `video-scaffold.js` | `<video-player>`, `<video-scaffold-skin>`, and the UI elements the scaffold skin composes |
 | `video-player.js` | `<video-player>` alone, for markup without a packaged skin |
 
 The other presets follow the same pattern. Background video is the exception: one bundle, `background.js`, registers the player, the skin, and the `<background-video>` media component.
@@ -36,8 +37,8 @@ A skin bundle registers every UI element its skin is built from. Any element the
 Each [UI element](./ui-components.md) is its own bundle under `ui/`, for markup that a skin bundle does not already cover: a player-only bundle, [skin source](./customize-skins.md#style-skin-source) that adds a component the packaged skin lacks, or a [dialog](../reference/components/dialog.md) your page opens beside a packaged skin.
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video-player.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/ui/play-button.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video-player.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/ui/play-button.js"></script>
 ```
 
 Each path mirrors its npm subpath: `ui/play-button.js` registers the element that `@videojs/html/ui/play-button` does. Compound components list one bundle per part in their reference page’s Import section, and all of the bundles share chunks with the player.
@@ -47,8 +48,8 @@ Each path mirrors its npm subpath: `ui/play-button.js` registers the element tha
 The default presets play through the browser’s own `<video>` and `<audio>`. Every other [media component](./media-sources.md) is its own bundle under `media/`, loaded beside the player bundle:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/hlsjs-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/hlsjs-video.js"></script>
 ```
 
 Each path mirrors its npm subpath. Elements with more than one playback engine keep the extra flavors in a directory named for the element, such as `media/mux-video/spf.js`. Load one flavor per page: every flavor claims the same tag name, and the first registration wins.
@@ -58,9 +59,9 @@ Each path mirrors its npm subpath. Elements with more than one playback engine k
 Each [extension](./architecture.md) is its own bundle under `extensions/`, loaded beside the player and media bundles:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/mux-video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/extensions/mux-data.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/extensions/mux-data.js"></script>
 ```
 
 As with media, each path mirrors its npm subpath: `extensions/mux-data.js` registers the element that `@videojs/html/extensions/mux-data` does.
@@ -70,8 +71,8 @@ As with media, each path mirrors its npm subpath: `extensions/mux-data.js` regis
 English ships inside the skin bundles. Each other locale is a bundle under `locales/` that registers its translations on import. Load it before the player script to avoid a flash of English:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/locales/es.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video.js"></script>
 ```
 
 One bundle exists per locale pack, plus bare-language aliases such as `pt`. For custom strings, see [Internationalize the player](./internationalization.md).

package/docs/guides/content-security-policy.md

@@ -40,9 +40,12 @@ Add only the origins for the providers you use. Extend `script-src` with their s
 | --- | --- | --- |
 | YouTube | `https://www.youtube.com` | `https://www.youtube.com` or `https://www.youtube-nocookie.com`, depending on your source URL |
 | Vimeo | — | `https://player.vimeo.com`; `https://vimeo.com` for live events |
+| SoundCloud | — | `https://w.soundcloud.com` |
+| Mixcloud | \- | `https://player-widget.mixcloud.com` |
 | Spotify | `https://open.spotify.com` | `https://open.spotify.com` |
 | TikTok | — | `https://www.tiktok.com` |
 | Twitch | — | `https://player.twitch.tv` |
+| Dailymotion | `https://geo.dailymotion.com` | `https://geo.dailymotion.com` |
 | Cloudflare | `https://embed.videodelivery.net` | `https://iframe.videodelivery.net` or your `https://customer-<code>.cloudflarestream.com` origin |
 | Google Cast | `https://www.gstatic.com` | — |
 | Wistia | `https://fast.wistia.com` and `https://fast.wistia.net` | `https://fast.wistia.com` and `https://fast.wistia.net` if the SDK falls back to an iframe |

package/docs/guides/customize-skins.md

@@ -2,7 +2,9 @@
 
 Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
 
-Start with the path that matches the change you want:
+Pick the skin closest to the design you want first. To apply your brand to a finished design, the Neutral skin is the usual starting point. To build your own design, start from the Scaffold skin. See [Choose a skin](./skins.md#choose-a-skin).
+
+Then start with the path that matches the change you want:
 
 | If you want to… | Use this path |
 | --- | --- |
@@ -36,7 +38,7 @@ Packaged skins expose [CSS custom properties](https://developer.mozilla.org/en-U
 
 If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Browsers before Chrome 147, Firefox 146, and Safari 26 lack `contrast-color()` and use the theme’s default text color instead, which suits only the default accent, so set both properties together if you support those browsers.
 
-The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font.
+The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font. The Scaffold skin inherits your page’s font instead, and it has no hairline, so `--media-border-color` doesn’t change it.
 
 The media component and poster share `--media-object-fit` and `--media-object-position`, so a `cover` poster stays aligned with `cover` video. See [Add a poster and loading placeholder](./poster.md).
 

package/docs/guides/features.md

@@ -74,7 +74,7 @@ if (media?.paused) media.play();
 
 ## Feature availability
 
-Volume, fullscreen, and picture-in-picture expose availability properties because platform support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
+Volume, playback rate, fullscreen, and picture-in-picture expose availability properties because platform and media support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
 
 | Value | Meaning |
 | --- | --- |

package/docs/guides/google-analytics.md

@@ -0,0 +1,199 @@
+# Track video telemetry with Google Analytics 4
+
+Track video engagement, progress milestones, and playback interactions by adding the Google Analytics extension to a player
+
+Google Analytics 4 (GA4) Enhanced Measurement tracks video engagement and viewer interaction. Add the Google Analytics [extension](./architecture.md) to a player and it monitors whichever media that player is playing, automatically dispatching standard GA4 Enhanced Measurement video events and playback interaction events to `window.dataLayer` and `window.gtag`.
+
+Install the extension alongside the framework façade:
+
+```bash
+pnpm add @videojs/html @videojs/google-analytics
+```
+
+**index.html**
+
+```html
+<video-player>
+  <media-container>
+    <video src="https://example.com/video.mp4"></video>
+    <google-analytics></google-analytics>
+  </media-container>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/extensions/google-analytics';
+
+  document.querySelector('google-analytics').metadata = { video_title: 'My Video' };
+</script>
+```
+
+### Load from a CDN
+
+When loading Video.js from a CDN, include the `extensions/google-analytics.js` script tag:
+
+**index.html**
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn/extensions/google-analytics.js"></script>
+
+<video-player>
+  <media-container>
+    <video src="https://example.com/video.mp4"></video>
+    <google-analytics></google-analytics>
+  </media-container>
+</video-player>
+<script type="module">
+  document.querySelector('google-analytics').metadata = { video_title: 'My Video' };
+</script>
+```
+
+That’s the entire setup for standard video tracking. The extension renders nothing; place it anywhere inside the player.
+
+> **Note**
+>
+> Google Analytics tracking is opt-in. No media component sends telemetry on its own until you add the extension to the player.
+
+## How events are reported
+
+When Google Tag (`gtag.js`) or Google Tag Manager (GTM) is configured on your site, `window.dataLayer` is available globally. The extension pushes structured event objects into `window.dataLayer`:
+
+```js
+window.dataLayer.push({
+  event: 'video_progress',
+  video_current_time: 30,
+  video_duration: 120,
+  video_percent: 25,
+  video_provider: 'video.js',
+  video_stream_type: 'on-demand',
+  video_title: 'My Video',
+  video_url: 'https://example.com/video.mp4',
+  visible: true,
+});
+```
+
+If `window.gtag` is defined, the extension also calls `window.gtag('event', event, params)` with the same parameters. If you use a custom data layer array on `window`, specify its property name with `dataLayerName` (or `data-layer-name` in HTML).
+
+### GA4 Enhanced Measurement events
+
+The extension dispatches standard GA4 Enhanced Measurement video events:
+
+- `video_start`: Dispatched when playback begins for the first time or starts at `currentTime > 0`.
+- `video_progress`: Dispatched when playback crosses 10%, 25%, 50%, and 75% milestones.
+- `video_complete`: Dispatched when the video reaches the end (`ended` event) or loops back to the start.
+
+### Video.js interaction events
+
+In addition to GA4 Enhanced Measurement events, the extension emits player interaction events to measure how viewers engage with controls:
+
+- `play`: Dispatched on first play.
+- `pause`: Dispatched when playback is paused (not triggered during seeking or when ended).
+- `resume`: Dispatched when playback resumes after a pause.
+- `end`: Dispatched when the video finishes.
+- `seek`: Dispatched when scrubbing or seeking completes (bypassed on loop restarts).
+- `mute`: Dispatched when audio is muted or volume drops to 0.
+- `unmute`: Dispatched when audio is unmuted with non-zero volume.
+- `fullscreenEnter`: Dispatched when entering fullscreen.
+- `fullscreenExit`: Dispatched when exiting fullscreen.
+
+## Set stream type
+
+By default, the stream type is inferred from the media (`media.streamType === 'live' ? 'live' : 'on-demand'`). For on-demand videos, duration is known and the extension calculates playback percentage to fire progress milestones at 10%, 25%, 50%, and 75%.
+
+To override or explicitly specify a live stream, pass `video_stream_type: 'live'` in `metadata`:
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.metadata = { video_title: 'Live Stream', video_stream_type: 'live' };
+</script>
+```
+
+When the effective stream type is `'live'`, milestone progress tracking is bypassed since live streams have unbounded or dynamic duration.
+
+## Disable progress tracking
+
+By default, the extension tracks progress milestones at 10%, 25%, 50%, and 75% for on-demand playback. To turn off milestone progress tracking, set `disableProgress` (or `disable-progress` in HTML):
+
+```html
+<google-analytics disable-progress></google-analytics>
+```
+
+## Set video title
+
+Set `metadata.video_title` on the extension so GA4 gets an explicit title for every media type, including iframe embeds that do not expose a useful DOM `title`.
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.metadata = { video_title: 'Keynote Presentation' };
+</script>
+```
+
+When `metadata.video_title` is omitted, the extension derives a title in this order: the title the media reports in its content data (Mux, Vimeo, and SoundCloud media report one, for example), then the resolved `video_url`, then `'Untitled Video'`. Do not rely on a `<video title="...">` attribute as your analytics title; set `metadata.video_title` instead.
+
+## Metadata and custom dimensions
+
+Pass `metadata` to set official GA4 video parameters (`video_title`, `video_provider`, `video_url`) and custom dimensions (such as Mux Data compatible names `video_id`, `video_series`, `video_producer`, `video_content_type`, or custom dimensions like `custom_1`):
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.metadata = {
+    video_title: 'Keynote Presentation',
+    video_series: 'Annual Conference',
+    video_producer: 'Video.js Team',
+    video_id: 'conf_2026_01',
+    custom_1: 'attendee_pro',
+  };
+</script>
+```
+
+### GA4 collection limits
+
+Google Analytics 4 enforces collection limits on event parameters:
+
+- **25 parameters per event**: The extension sends 8 standard parameters (`video_current_time`, `video_duration`, `video_percent`, `video_provider`, `video_stream_type`, `video_title`, `video_url`, and `visible`), leaving room for up to 17 custom dimensions in `metadata`.
+- **Parameter names**: Up to 40 characters in length.
+- **String values**: Up to 100 characters in length.
+
+## Debugging
+
+Enable console logging by setting the `debug` option:
+
+```html
+<google-analytics debug></google-analytics>
+```
+
+When enabled, the extension logs every dispatched event and its parameters:
+
+```plaintext
+[GoogleAnalyticsExtension] Event: "video_start" {video_current_time: 0, video_duration: 120, ...}
+```
+
+You can also provide an `onEvent` callback to intercept dispatched events programmatically:
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.onEvent = (event, params) => {
+    console.log('Telemetry event:', event, params);
+  };
+</script>
+```
+
+## Related pages
+
+### Components
+
+- [google-analytics](../reference/components/google-analytics.md): Options for the Google Analytics 4 extension that tracks video engagement and playback events
+- [mux-data](../reference/components/mux-data.md): Options for the Mux Data extension that monitors playback quality
+
+### Guides
+
+- [Monitor playback with Mux Data](./mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player

package/docs/guides/installation-cdn.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses CDN scripts for plain HTML. Use an existing page when one is available, and scaffold a minimal Vite app only when no app exists.
@@ -89,7 +89,7 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method cdn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --template none
+npx @videojs/cli@10.3.0 agents init --method cdn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --template none
 ```
 
 ## Load Video.js
@@ -101,7 +101,7 @@ Add these module scripts to the page head. Module scripts are deferred, so they
 _Merge this into the page `<head>`._
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video.js"></script>
 ```
 
 ## Add your player

package/docs/guides/installation-shadcn.md

@@ -31,7 +31,7 @@ npx @videojs/cli agents init
 - `framework`: The application framework that will host the player. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html. Values: `react`, `html`. Default: react.
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -46,7 +46,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses Shadcn to copy editable skin source. React uses the React source catalog; plain HTML uses the HTML source catalog. Vue and Svelte use packaged modules.
@@ -94,7 +94,7 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method shadcn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite --styling css
+npx @videojs/cli@10.3.0 agents init --method shadcn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite --styling css
 ```
 
 ## Configure app aliases

package/docs/guides/installation-svelte.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
@@ -90,13 +90,13 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method packaged --framework svelte --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
+npx @videojs/cli@10.3.0 agents init --method packaged --framework svelte --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
 ```
 
 ## Install the packages
 
 ```bash
-pnpm add @videojs/html@10.2.0
+pnpm add @videojs/html@10.3.0
 ```
 
 ## Add your player

package/docs/guides/installation-vue.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
@@ -90,13 +90,13 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method packaged --framework vue --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
+npx @videojs/cli@10.3.0 agents init --method packaged --framework vue --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
 ```
 
 ## Install the packages
 
 ```bash
-pnpm add @videojs/html@10.2.0
+pnpm add @videojs/html@10.3.0
 ```
 
 ## Register custom elements

package/docs/guides/installation.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
@@ -92,13 +92,13 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method packaged --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
+npx @videojs/cli@10.3.0 agents init --method packaged --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
 ```
 
 ## Install the packages
 
 ```bash
-pnpm add @videojs/html@10.2.0
+pnpm add @videojs/html@10.3.0
 ```
 
 ## Add your player