feat(renderer): report forwardFrames delivery state via forwardStatus

[naporin0624]

なぜ

Cannelloni で「プレビューだけが無言で死ぬ」事故を実機計測で確認した。3 時間のセッションでも、5 回の起動中 3 回でも再現した状態は次のとおり:

計測点	故障時	正常時
OSR paint	正常 25fps (600枚)	正常
frameDropped / error	0 件	0 件
sharedTexture.sendSharedTexture	一度も呼ばれない	300 回/10 秒
renderer に届いたフレーム	0	25fps
main プロセスのログ	例外なし	例外なし

paint も native sender も preview も droppedReason も全部健全なまま、監視ウィンドウだけが黙って黒くなる。切り分けようにも materials が無い:

• 毎フレームの ForwardDefect は handlePaint の .catch(() => {}) で捨てられている
• 登録の拒否 (bridge が dispose 済み / target が破壊済み) は inert handle として黙殺され、生きている handle と見分けがつかない

調査には計測コードの注入が必要で、しかも計装するとレースが消えた (計装前 3/5 失敗 → 計装後 22/22 成功)。ライブラリが状態を報告しない限り、この故障は現場で追えない。

なにを

forwardStatus イベント + FrameForwardOptions.onStatus

どちらも 状態遷移だけ を通知する — 初回成功 / 初回失敗 / 失敗理由の変化 / 復帰。30fps で同じ状態を垂れ流さない (frameDropped と同じ dedupe 方針)。

type ForwardStatus =
  | { ok: true }
  | { ok: false; reason: "target-destroyed" | "import-failed" | "send-failed"; cause?: Error };

// bridge 全体で受ける (どの登録かは extraArgs で識別)
bridge.on("forwardStatus", (s) => log(`slot ${s.extraArgs[0]}`, s.ok ? "ok" : s.reason));

// 登録単位で受ける
bridge.forwardFrames(target, { extraArgs: [slot], onStatus: (s) => log(slot, s) });

遷移だけを出すので、ログを素直に読むだけで停止区間になる: { ok: false } の後に { ok: true } が無ければ、そのターゲットはその時刻から今も暗い。

FrameForward.active

登録が成立したかどうか。set のメンバーシップを見る getter なので、登録拒否・dispose()・target の後からの破壊をすべて反映する。

const fwd = bridge.forwardFrames(target, { extraArgs: [slot] });
if (!fwd.active) log(`slot ${slot} was refused — no frames will ever arrive`);

設計上の判断

• "error" イベントは使わない。 購読者ゼロだと throw するため、まさに「誰も見ていない」状況を生き延びる必要がある診断チャネルには不適。
• 購読側の throw を握る。 両 sink は promise continuation の中で走るので、逃げた例外は main プロセスの unhandled rejection になる。どちらの sink も転送を止めてはいけない (console.error に落とす)。
• reject は send-failed として報告。 import 側は primitive が Result で包んでいるので、reject し得るのは send 側だけ。
• dispose 後に着弾した結果は捨てる。 誰も所有していない登録の状態をログに復活させない。

テスト

新規 9 件 (renderer 201 件 / core 33 件すべてパス)。dedupe・復帰・理由変化・reject 経路・in-flight dispose・active の 4 状態を個別に固定した。

typecheck クリーン、lint 0 errors、oxfmt 済み。

ドキュメント

docs/API.md と 3 つの skill に「defect は driver が捨てる」「登録は無言」と書いてあり、この PR で嘘になるため全部更新した。

🤖 Generated with Claude Code

https://claude.ai/code/session_01TErgwokxkbfxexfUNeuMoW

---

追記: diagnosing-dead-frame-forwards skill

同じ事故に次に当たった人が 2 手で層を特定できるよう、診断 skill を TDD で追加した。

RED (skill 無しのベースライン, 2 エージェント): どちらも根拠の薄い仮説から始めた。片方は in-flight promise の積み上がりを疑い、ライブラリが既に公開している信号を読む前に handlePaint へ pending カウンタを足すと提案した。両者とも FrameForward.active に触れず、「アイドルなソースはそもそも paint を出さない」を考慮せず、「フリーズ画像 / 空白プレースホルダ」の弁別も使わなかった。

GREEN (skill 有り): Syphon が生きている事実から「死んだのは転送だけ」と推論し、active を確認し、4 つの結果すべてに分岐を用意し、paint ループへの一時プローブ追加を明示的に見送った。

skill には計測済みの警告も入れた — 計装するとこのバグは隠れる (実測: 再現率 3/5 → 0/22)。

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@napolab/texture-bridge-renderer@85

commit: fe22098