Prepare browser client for next release

.changeset/brave-browsers-remember.md

@@ -0,0 +1,8 @@
+---
+"@rrweb/browser-client": patch
+"rrweb": patch
+"rrweb-snapshot": patch
+"@rrweb/types": patch
+---
+
+Add asset capture support across rrweb recording, snapshotting, replay, and shared types, and prepare `@rrweb/browser-client` for release with capture asset defaults, diagnostics coverage, and commit-aware build metadata.

docs/recipes/assets.md

@@ -0,0 +1,53 @@
+# Asset Capture
+
+Asset capture records external resources as `Asset` events that are associated with the snapshot or mutation where rrweb found the resource. During replay, rrweb applies those assets when rebuilding the matching snapshot, so images, media, and stylesheets can be replayed even when the original URL is unavailable or has changed.
+
+Use `captureAssets` with `record`:
+
+```js
+import { record } from '@rrweb/record';
+
+record({
+  emit(event) {},
+  captureAssets: {
+    objectURLs: true,
+    origins: ['https://static.example.com'],
+    images: true,
+    video: false,
+    audio: false,
+    stylesheets: 'without-fetch',
+    processStylesheetsWithin: 2000,
+    stylesheetsRuleThreshold: 0,
+  },
+});
+```
+
+## Asset events
+
+Assets are emitted after the `FullSnapshot` or `IncrementalSnapshot` that detected them. Their event timestamp can be later than the related snapshot, but replay still uses the asset with the snapshot it belongs to.
+
+For stylesheets, rrweb can process CSS rules asynchronously and emit them as asset events. This keeps expensive stylesheet serialization out of the initial snapshot path while still letting replay apply the captured stylesheet before visual replay when the asset is available.
+
+## Options
+
+`captureAssets` is an object with these fields:
+
+- `objectURLs` (default: `true`): capture same-origin `blob:` assets created with `URL.createObjectURL()`.
+- `origins` (default: `false`): choose which URL origins rrweb captures. Use `false` or `[]` to disable origin-based capture, `true` to capture from any origin, or an array such as `['https://static.example.com']` to allow specific origins.
+- `images`: capture images even when their origin does not match `origins`. If unset, images are captured only when `origins` matches. `inlineImages: true` maps to `captureAssets.images: true`.
+- `video`: capture video assets even when their origin does not match `origins`. If unset, videos are captured only when `origins` matches.
+- `audio`: capture audio assets even when their origin does not match `origins`. If unset, audio files are captured only when `origins` matches.
+- `stylesheets`: controls stylesheet asset capture. Use `false` to disable it, `'without-fetch'` to capture stylesheets whose CSS rules are already browser-accessible, or `true` to also fetch stylesheet URLs when needed. When stylesheet capture is enabled, including `'without-fetch'`, configured `origins` can allow fetch capture for matching stylesheet URLs.
+- `processStylesheetsWithin` (default: `2000`): maximum delay, in milliseconds, for asynchronous stylesheet processing. Lower values reduce the chance that short visits unload before stylesheet assets are emitted. Set `0` or a negative value to process synchronously, which can block the main thread.
+- `stylesheetsRuleThreshold` (default: `0`): stylesheets with fewer rules than this threshold are processed immediately and included in the snapshot instead of emitted as separate assets.
+
+## Legacy inline options
+
+`inlineImages` and `inlineStylesheet` are still accepted for compatibility, but new integrations should use `captureAssets`.
+
+- `inlineImages: true` maps to `captureAssets.images: true` when `captureAssets.images` is not set.
+- `inlineStylesheet: 'all'` maps to `captureAssets.stylesheets: true`.
+- `inlineStylesheet: true` maps to `captureAssets.stylesheets: 'without-fetch'`.
+- `inlineStylesheet: false` maps to `captureAssets.stylesheets: false`.
+
+When calling `rrweb-snapshot` directly, the historical inline behavior is preserved. The mapping above applies to `record`.

docs/recipes/assets.zh_CN.md

@@ -0,0 +1,53 @@
+# 静态资源录制
+
+静态资源录制会把外部资源记录为 `Asset` 事件，并关联到发现该资源的快照或 mutation。回放时，rrweb 会在重建对应快照时应用这些资源，因此即使原始 URL 不可访问或内容已变化，也可以回放图像、媒体和样式表。
+
+在 `record` 中使用 `captureAssets`：
+
+```js
+import { record } from '@rrweb/record';
+
+record({
+  emit(event) {},
+  captureAssets: {
+    objectURLs: true,
+    origins: ['https://static.example.com'],
+    images: true,
+    video: false,
+    audio: false,
+    stylesheets: 'without-fetch',
+    processStylesheetsWithin: 2000,
+    stylesheetsRuleThreshold: 0,
+  },
+});
+```
+
+## Asset 事件
+
+Asset 事件会在发现它的 `FullSnapshot` 或 `IncrementalSnapshot` 之后发出。事件时间戳可能晚于关联的快照，但回放时仍会把它应用到对应的快照上。
+
+对于样式表，rrweb 可以异步处理 CSS 规则并将结果发为 Asset 事件。这样可以避免在初始快照路径上同步执行较重的样式表序列化，同时在资源可用时仍能让回放先应用捕获到的样式表。
+
+## 配置项
+
+`captureAssets` 是一个对象，包含以下字段：
+
+- `objectURLs`（默认值：`true`）：录制通过 `URL.createObjectURL()` 创建的同源 `blob:` 资源。
+- `origins`（默认值：`false`）：选择 rrweb 录制哪些 URL origin。使用 `false` 或 `[]` 关闭基于 origin 的录制，使用 `true` 录制任意 origin，或使用 `['https://static.example.com']` 这样的数组指定允许的 origin。
+- `images`：即使图片 origin 不匹配 `origins`，也录制图片资源。未设置时，只有匹配 `origins` 的图片会被录制。`inlineImages: true` 会映射为 `captureAssets.images: true`。
+- `video`：即使视频 origin 不匹配 `origins`，也录制视频资源。未设置时，只有匹配 `origins` 的视频会被录制。
+- `audio`：即使音频 origin 不匹配 `origins`，也录制音频资源。未设置时，只有匹配 `origins` 的音频会被录制。
+- `stylesheets`：控制样式表资源录制。使用 `false` 关闭，使用 `'without-fetch'` 录制浏览器已经可访问 CSS 规则的样式表，使用 `true` 时在需要时也会 fetch 样式表 URL。启用样式表录制时，包括 `'without-fetch'` 模式，配置的 `origins` 可以允许对匹配的样式表 URL 进行 fetch 录制。
+- `processStylesheetsWithin`（默认值：`2000`）：异步处理样式表的最长延迟，单位为毫秒。较低的值可以降低短访问在样式表 Asset 发出前卸载页面的概率。设置为 `0` 或负数会同步处理，但可能阻塞主线程。
+- `stylesheetsRuleThreshold`（默认值：`0`）：规则数少于该阈值的样式表会立即处理并放入快照，而不是作为单独的 Asset 事件发出。
+
+## 旧的 inline 配置
+
+`inlineImages` 和 `inlineStylesheet` 仍然可以作为兼容配置使用，但新的集成应使用 `captureAssets`。
+
+- `inlineImages: true` 会在 `captureAssets.images` 未设置时映射为 `captureAssets.images: true`。
+- `inlineStylesheet: 'all'` 映射为 `captureAssets.stylesheets: true`。
+- `inlineStylesheet: true` 映射为 `captureAssets.stylesheets: 'without-fetch'`。
+- `inlineStylesheet: false` 映射为 `captureAssets.stylesheets: false`。
+
+直接调用 `rrweb-snapshot` 时，历史 inline 行为仍会保留。以上映射适用于 `record`。

docs/recipes/index.md

@@ -10,6 +10,12 @@ Record and Replay is the most common use case, which is suitable for any scenari
 
 [link](./record-and-replay.md)
 
+### Asset Capture
+
+Asset capture records external resources as asset events so replay can apply images, media, object URLs, and stylesheets even when the original URL is unavailable or has changed.
+
+[link](./assets.md)
+
 ### Dive Into Events
 
 The events recorded by rrweb are a set of strictly-typed JSON data. You may discover some flexible ways to use them when you are familiar with the details.

docs/recipes/index.zh_CN.md

@@ -10,6 +10,12 @@
 
 [链接](./record-and-replay.zh_CN.md)
 
+### 静态资源录制
+
+静态资源录制会把外部资源记录为 Asset 事件，让回放在原始 URL 不可访问或内容变化时仍能应用图像、媒体、对象 URL 和样式表。
+
+[链接](./assets.zh_CN.md)
+
 ### 深入录制数据
 
 录制数据是一组类型严格的 JSON 数据，通过熟悉其格式，可以更灵活的使用录制数据。