docs: document HEVC input support and the preview-only codec caveat

docs/guides/rendering.mdx

@@ -157,6 +157,19 @@ npx hyperframes render --video-bitrate 10M --output controlled.mp4
 
 **Tip**: The default `standard` preset (CRF 18) is visually lossless at 1080p — most people cannot distinguish it from the source. Use `--quality draft` for faster iteration, or `--quality high` / `--crf 10` when file size is no concern.
 
+## Input Video Codecs
+
+Video assets referenced by a composition (a `<video src="...">` clip) are decoded by FFmpeg, not by the browser: the pipeline pre-extracts every input video into frame images and injects them during capture, so the render never depends on what the capture browser can play. Any codec your FFmpeg build decodes works as an input, including:
+
+- H.264 / AVC
+- **HEVC / H.265, 8-bit and 10-bit** (`hvc1` and `hev1`): common for storage-optimized asset libraries; renders identically on macOS and Linux, no hardware decoder required
+- VP8 / VP9 and ProRes 4444 (with alpha; see [Transparent Video](#transparent-video))
+- HDR sources (HLG / PQ) are tone-mapped for SDR renders; see the [HDR guide](/guides/hdr)
+
+The one caveat is **live preview**: `preview`, `play`, Studio, and published player pages play the file in a real browser, so playback there depends on that browser's codec support. Chrome (107+), Edge, and Safari hardware-decode HEVC on most modern machines; Firefox does not. If an HEVC asset shows a black frame in preview while rendering fine, generate an H.264 proxy for authoring (for example with `ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4`, or via the media-use skill) and swap the original back in for the final render, or just keep the HEVC source, since the rendered output is unaffected.
+
+`hyperframes lint` emits an info-level `hevc_preview_codec` note when a composition references an HEVC video, as a reminder of this preview-only limitation.
+
 ## Animated GIF
 
 Use GIF when the output needs to autoplay inline in GitHub PRs, READMEs, issue reports, and docs pages:

docs/guides/troubleshooting.mdx

@@ -135,6 +135,18 @@ If your issue is about a specific coding mistake (animations not working, video
 
     See [Rendering: Options](/guides/rendering#options) for all available flags.
   </Accordion>
+
+  <Accordion title="Video asset plays black in preview but renders fine (HEVC/H.265)">
+    Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: `preview`, `play`, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not).
+
+    If an HEVC asset shows a black or frozen frame in preview:
+
+    1. Confirm the render itself is fine: `npx hyperframes render` output will contain the video.
+    2. For authoring, generate an H.264 proxy (`ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4`) and point the composition at it while you iterate.
+    3. Swap the HEVC original back before the final render, or keep the proxy; both render correctly.
+
+    `npx hyperframes lint` flags HEVC assets with an info-level `hevc_preview_codec` note. See [Rendering: Input Video Codecs](/guides/rendering#input-video-codecs).
+  </Accordion>
 </AccordionGroup>
 
 ## System Diagnostics

skills-manifest.json

@@ -30,7 +30,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "627ad77d778ec13d",
+      "hash": "546d4b1a0f0a8440",
       "files": 17
     },
     "hyperframes-creative": {
@@ -46,7 +46,7 @@
       "files": 10
     },
     "media-use": {
-      "hash": "675a735177b23d1b",
+      "hash": "36630c2bb9d281da",
       "files": 133
     },
     "motion-graphics": {

skills/hyperframes-core/references/variables-and-media.md

@@ -105,3 +105,5 @@ Video elements must be muted and inline. Audio must be a separate `<audio>` elem
 - For volume fades/ducking, animate `volume` on the timeline (`tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`) rather than swapping `data-volume`. The runtime probes the timeline's volume keyframes and applies them identically in preview and render; `data-volume` is the static baseline for elements no tween touches.
 
 For media duration: `<video>` and `<audio>` can omit `data-duration` if the media's intrinsic length is known and you want the full clip. Otherwise provide `data-duration` explicitly.
+
+Input codecs: render decodes video via FFmpeg (frames are pre-extracted and injected), so HEVC/H.265 assets (8/10-bit) render correctly everywhere; only live preview depends on the browser's codec support (`lint` emits an info-level `hevc_preview_codec` note; use an H.264 proxy for authoring if preview shows black).

skills/media-use/SKILL.md

@@ -392,6 +392,12 @@ removal, upscale, lipsync, translate). Run the tool, then register the output
 with `resolve --from <output> --type <type>` so it joins the ledger + global
 cache.
 
+HEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all
+input video); only live preview depends on the browser's codec support. If an
+HEVC asset previews black, make an H.264 authoring proxy (`ffmpeg -i in.mp4
+-c:v libx264 -crf 18 proxy.mp4`), register it with `resolve --from`, and keep
+either file for the final render.
+
 ## CLI tools used (what to run, and how to enable each)
 
 `resolve` auto-cascades; each provider shells one CLI. HeyGen is the