docs: align platform and C API documentation

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+Erika welcomes respectful, technical collaboration across Rust, C/C++, Flutter, platform-native, and media-engineering communities. Discuss code and evidence, not people.
+
+Harassment, discrimination, disclosure of personal data or credentials, and deliberate disruption are not acceptable. Maintainers may remove content or limit participation when needed to protect contributors and users.
+
+Use [SECURITY.md](SECURITY.md) for private security reporting and the repository issue tracker for ordinary bugs and feature discussions.

README.md

@@ -25,7 +25,7 @@
 - **字幕** — SRT / WebVTT / ASS 解析，libass 渲染 (静态链接)，嵌入与外挂字幕轨
 - **弹幕** — Bilibili XML / JSON 解析，DFM+ 碰撞避让布局引擎，glyph atlas 原生 GPU 渲染
 - **播放引擎** — play / pause / stop / seek / 倍速，音频主时钟同步，vsync 量化调度
-- **C ABI** — 79 个导出函数，opaque handle 设计，可从 C / C++ / Swift / Dart FFI / 任何 FFI 语言调用
+- **C ABI** — opaque handle 设计，可从 C / C++ / Swift / Dart FFI / 任何 FFI 语言调用；以 `erika.h` 中的导出声明为准
 - **Flutter 插件** — macOS + iOS + tvOS + Windows + Android + HarmonyOS 原生视图/Texture 嵌入
 - **wgpu 后端** — Android 播放、overlay、截图与 Vulkan/GLES 恢复路径可用；HarmonyOS 走 Vulkan，用 OHNativeWindow 呈现、OHNativeBuffer 零拷贝导入；Linux 仍在规划中
 
@@ -112,6 +112,7 @@ docs/                     架构与嵌入文档
 - [原生接入指南](docs/integration.zh.md) — C/C++/Win32/Swift 等非 Flutter 宿主的端到端嵌入
 - [构建与依赖指南](docs/building.zh.md) — xtask、native 依赖、交叉编译
 - [Flutter 嵌入](docs/flutter_embedding.zh.md) ・ [弹幕架构](docs/danmaku_architecture.md)
+- [平台能力矩阵](docs/platform_matrix.zh.md) — 区分可编译、CI 覆盖、真机验收与预编译发布
 - [发布与预编译产物](docs/releasing.md) — 各平台预编译 `erika_capi` 库下载与打包(英文)
 - [贡献 / 开发者指南](CONTRIBUTING.zh.md) — 仓库布局、线程模型、新增平台后端
 

SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+Please report vulnerabilities through GitHub Security Advisories or a private maintainer channel. Do not publish credentials, real media-server URLs, private video samples, or exploit details in public issues.
+
+Reports should include the affected tag/commit, platform and target triple, a minimal reproduction, impact, and whether the issue involves the C ABI, prebuilt archives, native build scripts, Flutter glue, or network media handling.
+
+Security fixes are prioritized for maintained release tags and the default branch. Locally rebuilt forks, unpinned prebuilt archives, and platform-preview paths may require separate validation.

SUPPORT.md

@@ -0,0 +1,7 @@
+# Support
+
+For integration help, start with the architecture, build, C ABI, Flutter embedding, and platform-matrix documents under `docs/`.
+
+When filing a bug, include the Erika tag/commit, host platform, Rust target triple, renderer, media container/codecs, whether a prebuilt archive or source build was used, and a minimal reproduction. Remove credentials and private URLs from logs.
+
+For NipaPlay integration issues, also include the NipaPlay commit and `ERIKA_PREBUILT_TAG` or dependency pin.

docs/architecture.ja.md

@@ -19,7 +19,7 @@ Rust Player Core
   D3D11 renderer ─────── zero-copy D3D11VA, HDR10, subtitle/danmaku pass (Windows)
   wgpu renderer ──────── cross-platform video, overlays, capture, Android scRGB, OHOS Vulkan
   presenter runtime ──── ties player + renderer + audio + overlays
-  C ABI ──────────────── 79 exported functions, two handle families
+  C ABI ──────────────── versioned public header、2 つの handle ファミリー
   Flutter plugin ─────── macOS + iOS + tvOS + Windows + Android + OpenHarmony embedding
 ```
 

docs/architecture.md

@@ -22,7 +22,7 @@ Rust Player Core
   D3D11 renderer ─────── zero-copy D3D11VA, HDR10, subtitle/danmaku pass (Windows)
   wgpu renderer ──────── cross-platform video, overlays, capture, Android scRGB, OHOS Vulkan
   presenter runtime ──── ties player + renderer + audio + overlays
-  C ABI ──────────────── 79 exported functions, two handle families
+  C ABI ──────────────── versioned public header, two handle families
   Flutter plugin ─────── macOS + iOS + tvOS + Windows + Android + OpenHarmony embedding
 ```
 

docs/architecture.zh.md

@@ -19,7 +19,7 @@ Rust Player Core
   D3D11 renderer ─────── zero-copy D3D11VA, HDR10, subtitle/danmaku pass (Windows)
   wgpu renderer ──────── cross-platform video, overlays, capture, Android scRGB, OHOS Vulkan
   presenter runtime ──── ties player + renderer + audio + overlays
-  C ABI ──────────────── 79 exported functions, two handle families
+  C ABI ──────────────── 版本化公开头文件，两组 handle 接口族
   Flutter plugin ─────── macOS + iOS + tvOS + Windows + Android + OpenHarmony embedding
 ```
 

docs/capi_reference.ja.md

@@ -22,9 +22,12 @@ Erika は独立した 2 つのエントリーポイントを公開します。
 | `ErikaPresenterHandle` | **プッシュ** | Erika | native surface を Erika に渡し、表示フレームごとに `render_tick` を 1 回呼ぶ。Erika が decode・timing・audio・overlay・presentation を所有する。 |
 
 `ErikaPresenterHandle` が推奨パスで、Flutter plugin と native demo もこれを使います。
-コンパイルされるのは **macOS / iOS / tvOS / Windows / Android**。他のターゲットでは
-`erika_presenter_create` は export されますが `NULL` を返し、presenter ファミリーの
-残りは存在しません——presenter の利用はプラットフォームでガードしてください。
+コンパイルされるのは **macOS / iOS / tvOS / Windows / Android / HarmonyOS**。surface attach は
+platform ごとに異なり、Apple は Metal、Windows は HWND/D3D11、Android/HarmonyOS は
+wgpu/Vulkan surface を使います。HarmonyOS Flutter bridge は ArkTS platform channel が
+構造化値を serialize して渡すため、presenter の JSON helper を使います。未対応 target では
+`erika_presenter_create` が export されても `NULL` を返す場合があるため、platform guard と
+create 成功の両方を確認してください。
 
 2 つのファミリーは状態を共有しません。1 プロセスで両方使えますが、1 つのメディア
 セッションは正確に 1 つの handle に属します。
@@ -206,7 +209,7 @@ capabilities を渡すため Android extended-linear output は active になり
 ## `ErikaPresenterHandle` —— プッシュモデル
 
 Erika がフルスタックを所有し、ホストは surface を提供して `render_tick` を呼びます。
-**macOS / iOS / tvOS / Windows / Android。**
+**macOS / iOS / tvOS / Windows / Android / HarmonyOS。**
 
 ### ライフサイクルと設定
 

docs/capi_reference.md

@@ -22,10 +22,13 @@ Erika exposes two independent entry points. Pick one per integration.
 | `ErikaPresenterHandle` | **Push** | Erika | You give Erika a native surface and call `render_tick` once per display frame. Erika owns decode, timing, audio, overlays, and presentation. |
 
 `ErikaPresenterHandle` is the recommended path and what the Flutter plugin and
-the native demos use. It is compiled on **macOS, iOS, tvOS, Windows, and Android**.
-On other targets `erika_presenter_create` is still exported but returns `NULL`,
-and the rest of the presenter family is absent — guard presenter usage by
-platform.
+the native demos use. It is compiled on **macOS, iOS, tvOS, Windows, Android,
+and HarmonyOS**. Surface attachment is platform-specific: Apple uses Metal,
+Windows uses HWND/D3D11, and Android/HarmonyOS use wgpu/Vulkan surfaces. The
+HarmonyOS Flutter bridge uses the JSON presenter helpers because ArkTS platform
+channels already exchange structured serialized values. On unsupported targets
+`erika_presenter_create` may be exported but returns `NULL`; guard presenter
+usage by platform and by a successful create call.
 
 The two families do not share state; a process may use both, but a given media
 session lives in exactly one handle.
@@ -225,7 +228,7 @@ capabilities and therefore cannot activate Android extended-linear output.
 ## `ErikaPresenterHandle` — push model
 
 Erika owns the full stack; the host supplies a surface and calls `render_tick`.
-**macOS / iOS / tvOS / Windows / Android.**
+**macOS / iOS / tvOS / Windows / Android / HarmonyOS.**
 
 ### Lifecycle and configuration
 

docs/capi_reference.zh.md

@@ -19,9 +19,12 @@ Erika 暴露两个相互独立的入口，每个集成选其一。
 | `ErikaHandle` | **拉取（Pull）** | 宿主 | 你拥有渲染循环、自己拉取解码帧 / 驱动自己的合成器。 |
 | `ErikaPresenterHandle` | **推送（Push）** | Erika | 你把一个原生 surface 交给 Erika，每个显示帧调一次 `render_tick`。Erika 负责解码、时序、音频、overlay 和呈现。 |
 
-`ErikaPresenterHandle` 是推荐路径，也是 Flutter 插件和原生 demo 所用的。它只在
-**macOS、iOS、tvOS、Windows、Android** 上编译。其它平台上 `erika_presenter_create` 仍然
-导出但返回 `NULL`，presenter 族的其余函数不存在——请按平台守卫 presenter 用法。
+`ErikaPresenterHandle` 是推荐路径，也是 Flutter 插件和原生 demo 所用的。它在
+**macOS、iOS、tvOS、Windows、Android、HarmonyOS** 上编译。surface attach 按平台不同：
+Apple 使用 Metal，Windows 使用 HWND/D3D11，Android/HarmonyOS 使用 wgpu/Vulkan surface。
+HarmonyOS Flutter bridge 因 ArkTS 平台通道本身传递序列化结构化值，使用 presenter 的 JSON
+辅助入口。其它不支持的平台上 `erika_presenter_create` 可能仍导出但返回 `NULL`；请同时按平台
+守卫 presenter 用法，并检查 create 是否成功。
 
 两个族不共享状态；一个进程可同时使用两者，但单个媒体会话只活在一个 handle 里。
 
@@ -204,7 +207,7 @@ Android extended-linear 输出。
 ## `ErikaPresenterHandle` —— 推送模型
 
 Erika 拥有完整栈；宿主提供 surface 并调用 `render_tick`。
-**macOS / iOS / tvOS / Windows / Android。**
+**macOS / iOS / tvOS / Windows / Android / HarmonyOS。**
 
 ### 生命周期与配置
 

docs/integration.ja.md

@@ -23,7 +23,9 @@ Rust の `PresenterRuntime` を直接駆動します。以下の C ABI 呼び出
 `ErikaHandle` は、独自コンポジタを持ち Erika の decode/timing/state だけが欲しいホスト
 向けです。本ガイドの残りは presenter ベースです。
 
-presenter ファミリーは **macOS / iOS / tvOS / Windows / Android** でコンパイルされます。
+presenter ファミリーは **macOS / iOS / tvOS / Windows / Android / HarmonyOS** でコンパイルされます。
+native host API は platform ごとに異なります。HarmonyOS Flutter host は desktop sample を
+そのまま再現するのではなく、通常 plugin の ArkTS JSON bridge を使います。
 
 ## 2. ライフサイクル
 

docs/integration.md

@@ -24,7 +24,10 @@ Use `ErikaPresenterHandle` unless you have a reason to render yourself. The
 pull-model `ErikaHandle` is for hosts that own their compositor and only want
 Erika's decode/timing/state. The rest of this guide is presenter-based.
 
-The presenter family is compiled on **macOS, iOS, tvOS, Windows, and Android**.
+The presenter family is compiled on **macOS, iOS, tvOS, Windows, Android, and
+HarmonyOS**. The native host API is platform-specific; HarmonyOS Flutter hosts
+normally use the plugin's ArkTS JSON bridge rather than reproducing the desktop
+sample code.
 
 ## 2. The lifecycle
 

docs/platform_matrix.zh.md

@@ -0,0 +1,24 @@
+# Erika 平台能力矩阵
+
+本文把“能编译”“CI 构建覆盖”“真机验收”和“有可下载预编译包”分开描述。任何一项为真，都不自动代表其它三项为真。
+
+| 平台 | 主要解码/渲染 | C ABI presenter | CI/产物 | 真机验收状态 |
+|---|---|---|---|---|
+| macOS | VideoToolbox + Metal | 是 | CI 与预编译包 | 持续维护；HDR/EDR 依显示器和系统而定 |
+| iOS | VideoToolbox + Metal | 是 | CI 与 XCFramework | 持续维护；需使用真机验证 HDR/后台行为 |
+| tvOS | VideoToolbox + Metal | 是 | CI 与 XCFramework | 开发者预览；真机与模拟器分别记录 |
+| Windows x64/ARM64 | D3D11VA + D3D11 | 是 | CI 与预编译包 | 持续维护；HDR10 受显示器、驱动和系统设置影响 |
+| Android | MediaCodec/软解 + wgpu | 是 | CI 与预编译包 | SDR 已验证；API 35 HDR active path 仍需真机验收 |
+| HarmonyOS | AVCodec/软解 + wgpu Vulkan | 是 | 预编译包；CI 覆盖需以 workflow 为准 | 已有真机验证，尚未纳入完整 CI 验收 |
+| Linux | 规划中的 wgpu 路径 | 不作为发布承诺 | 无正式预编译发布 | 未验收 |
+
+## surface 与嵌入选择
+
+- Apple：优先 native Metal surface；Flutter 完整播放器优先 window overlay，platform view 用于兼容或诊断。
+- Windows：使用 HWND/D3D11 attach，调用方负责窗口生命周期与 display tick。
+- Android：SDR 使用 TextureView；extended-linear 输出使用 SurfaceView/Hybrid Composition，能力协商失败明确回退 SDR。
+- HarmonyOS：ArkTS 外部纹理提供 `OHNativeWindow`，通过 `erika_presenter_attach_wgpu_surface` attach；平台桥接优先使用 JSON presenter helper。
+
+## 发布前记录
+
+发布说明应写明每个平台的目标 triple、FFmpeg profile、prebuilt tag、C header 版本、CI 结果及真机验收设备。没有真机结论时应标记“待验收”，不要写成“已完全支持”。

docs/releasing.ja.md

@@ -39,6 +39,20 @@ git push origin v0.1.5
 
 macOS arm64 と x64 はどちらも `macos-26` で cross build し、その後 universal package を合成します。iOS と tvOS の XCFramework も `macos-26` を使用します。Windows x64 は `windows-latest`、ARM64 は `windows-11-arm` で native build します。
 
+## Release 前の検証
+
+`v*` tag を push する前に、clean worktree で次を実行して結果を記録してください。
+
+```sh
+cargo fmt --all -- --check
+cargo test -p erika -p erika_capi
+cargo test --workspace
+cargo clippy -p erika -p erika_capi --all-targets -- -D warnings
+```
+
+さらに、影響を受ける example を compile し、公開 `erika.h` と C ABI reference / Flutter
+FFI glue の整合性、各 archive の manifest と license、NipaPlay で固定した prebuilt tag を確認してから Release Notes を公開してください。
+
 ## Flutter で prebuilt を使用
 
 ```sh

docs/releasing.md

@@ -72,6 +72,21 @@ To dry-run the builds without publishing, trigger the workflow manually
 ("Run workflow" / `workflow_dispatch`) — the build jobs run, but the publish job
 is skipped because it is gated on a tag ref.
 
+## Pre-release validation
+
+Before pushing a `v*` tag, use a clean worktree and record:
+
+```sh
+cargo fmt --all -- --check
+cargo test -p erika -p erika_capi
+cargo test --workspace
+cargo clippy -p erika -p erika_capi --all-targets -- -D warnings
+```
+
+Also compile affected examples, compare the public `erika.h` header with the C
+ABI reference and Flutter FFI glue, inspect every archive manifest/license, and
+verify the pinned prebuilt tag in NipaPlay before publishing release notes.
+
 ## Packaging
 
 [`packaging/bundle.sh`](../packaging/bundle.sh) stages and zips a bundle from a

docs/releasing.zh.md

@@ -38,6 +38,25 @@ git push origin v0.1.5
 
 macOS arm64 和 x64 都在 `macos-26` 交叉构建，然后合并 universal 包；iOS 和 tvOS XCFramework 同样使用 `macos-26`。Windows x64 在 `windows-latest` 构建，ARM64 在 `windows-11-arm` 原生构建。
 
+## 发布前检查
+
+在推送 `v*` tag 前，维护者应在干净工作树中完成并记录：
+
+```sh
+cargo fmt --all -- --check
+cargo test -p erika -p erika_capi
+cargo test --workspace
+cargo clippy -p erika -p erika_capi --all-targets -- -D warnings
+```
+
+此外还应：
+
+- 编译受影响的平台示例，避免示例继续引用已删除的 C ABI、uniform 或配置字段；
+- 对比 `crates/erika_capi/include/erika.h`，同步 C ABI 参考文档和 Flutter FFI glue；
+- 检查每个预编译归档的 `MANIFEST.txt`、LICENSE、第三方声明及目标架构；
+- 更新 package README、CHANGELOG 和 [平台能力矩阵](platform_matrix.zh.md)；
+- 在 NipaPlay 中验证固定的 `ERIKA_PREBUILT_TAG`，并同步 NipaPlay 的 pin 与 Release Notes。
+
 ## Flutter 使用预构建包
 
 ```sh

readme/README.en.md

@@ -25,7 +25,7 @@ The host application provides a rendering surface and sends playback commands 
 - **Subtitles** -- SRT / WebVTT / ASS parsing, libass rendering (statically linked), embedded and external subtitle tracks
 - **Danmaku** -- Bilibili XML / JSON parsing, DFM+ collision-aware lane layout engine, glyph atlas native GPU rendering
 - **Playback engine** -- play / pause / stop / seek / rate control, audio-master clock discipline, vsync-quantized frame scheduling
-- **C ABI** -- 79 exported functions, opaque handle design, callable from C / C++ / Swift / Dart FFI / any FFI-capable language
+- **C ABI** -- opaque handle design with a versioned public header; callable from C / C++ / Swift / Dart FFI / any FFI-capable language. See `erika.h` for the authoritative export set.
 - **Flutter plugin** -- macOS + iOS + tvOS + Windows + Android + HarmonyOS native view/Texture embedding with platform-native high-dynamic-range surface paths
 - **wgpu backend** -- Android playback, overlays, capture, and bounded Vulkan/GLES recovery are available; HarmonyOS runs on Vulkan, presenting through OHNativeWindow with OHNativeBuffer zero-copy import; Linux remains planned
 
@@ -79,7 +79,7 @@ Erika provides two C ABI entrypoint families for different embedding scenarios:
 | `ErikaHandle` | Host manages its own render loop | Host pulls frame data |
 | `ErikaPresenterHandle` | Erika owns the full playback stack | Host provides a surface and drives `render_tick` |
 
-Header: [`crates/erika_capi/include/erika.h`](crates/erika_capi/include/erika.h)
+Header: [`crates/erika_capi/include/erika.h`](../crates/erika_capi/include/erika.h)
 
 ## Platform Support
 

readme/README.ja.md

@@ -25,7 +25,7 @@
 - **字幕** -- SRT / WebVTT / ASS パーサー、libass レンダリング（静的リンク）、埋め込みおよび外部字幕トラック
 - **弾幕** -- Bilibili XML / JSON パーサー、DFM+ 衝突回避レーン配置エンジン、グリフアトラスによるネイティブ GPU レンダリング
 - **再生エンジン** -- play / pause / stop / seek / 再生速度制御、音声マスタークロック同期、vsync 量子化フレームスケジューリング
-- **C ABI** -- 79 のエクスポート関数、不透明ハンドル設計、C / C++ / Swift / Dart FFI / 任意の FFI 対応言語から呼び出し可能
+- **C ABI** -- 不透明ハンドル設計で、C / C++ / Swift / Dart FFI / 任意の FFI 対応言語から呼び出し可能。正確なエクスポート集合は `erika.h` を参照
 - **Flutter プラグイン** -- macOS + iOS + tvOS + Windows + Android + HarmonyOS の native view / Texture embedding と platform-native high-dynamic-range surface path
 - **wgpu バックエンド** -- Android の playback、overlay、capture、bounded Vulkan/GLES recovery は利用可能。HarmonyOS は Vulkan で動作し、OHNativeWindow で present して OHNativeBuffer を zero-copy import します。Linux は引き続き計画中