libaribhtml5 0.1.2 → 0.1.4

package/docs/media-plane-integration.md

@@ -37,13 +37,34 @@ MMT の source of truth は LCT です。実装時の優先順位は次の通り
 - 背景プレーンは viewport 全体を覆い、映像、アプリケーション、字幕、文字スーパーより後ろに置く。
 - LCT の色はアプリケーションやサービスの切り替え時に引き継がない。新しい LCT を受け取るまでは
   fallback に戻す。
-- アプリケーションの `html` / `body` を透明化して映像を見せる場合でも、透明部分の下には
-  receiver-owned background plane を残す。
+- `in-object` adapter では、runtime はアプリケーションの `html` / `body` を透明化しない。
+  放送アプリケーションが指定した背景色や背景画像は multimedia plane の描画として保持する。
+- `external` adapter では、外部映像面を iframe 越しに見せるため application canvas を透明化する。
+  その場合は receiver 背景、外部映像、iframe を別々の sibling layer として、この順に重ねる。
+  receiver 背景と iframe を同じ wrapper に入れると、外部映像を両者の間へ合成できない。
+  application canvas を透明化する前の stage 色は receiver viewport の最背面に移し、映像領域外に
+  host アプリの背景が露出しないようにする。stage 色を取得できない間の fallback は黒とする。
+- dark theme の host に light canvas の放送ページを埋め込む場合、iframe owner と iframe 内 root に
+  `color-scheme: only light` を明示する。Chromium は owner と iframe 内の root で used color scheme が
+  異なると、`html` / `body` の computed background が透明でも、不透明な scheme backdrop
+  （light の場合は白）を frame canvas に描画する。これは CSS の `background`、iframe の
+  `z-index`、`opacity` では除去できない。
+- `#vstream` 等、media object の祖先が不透明な背景を描く場合、external runtime はその祖先の
+  背景だけを media object の存続中に透明化する。兄弟要素の UI は変更しない。video を iframe
+  より前へ上げて穴を作ってはならない。そうすると字幕説明など、映像より前にあるべき
+  application UI まで隠れる。
+- `#vstream > object#av` のように media object と同じ矩形で object だけを子に持つ wrapper は、
+  背景だけでなく wrapper 自身を `opacity: 0` にする。高い `z-index` の純 media wrapper が作る
+  空の compositing layer を残さないためであり、字幕や操作 UI を含む wrapper には適用しない。
+- 映像の位置と寸法は、どちらの adapter でも放送アプリケーションが宣言した video object に従う。
 - 放送アプリケーション内の背景画像、要素背景、半透明 UI は multimedia plane の描画であり、
   LCT の背景色を置き換えない。
 - native compositor でも DOM 実装でも、LCT の単色を iframe 内の装飾要素として実装しない。
   動画領域の切り抜きや iframe のページ遷移から独立した、受信機所有の最背面レイヤーにする。
 
+Chromium の `color-scheme` backdrop、external media hole、DevTools での切り分けは
+[ブラウザ iframe 合成の注意事項](browser-iframe-compositing.md)も参照してください。
+
 根拠は `../ARIB-docs` の次の条項です。
 
 - ARIB STD-B62 1.5版 第一編 第1部 5.2(4): 背景プレーンは最背面で、前面が透明または
@@ -89,6 +110,9 @@ const viewport = document.querySelector<HTMLElement>('#viewport')!
 const normalPlayer = document.querySelector<HTMLElement>('#normal-player')!
 const video = document.querySelector<HTMLVideoElement>('#video')!
 
+// dark theme の host でも、放送ページの標準 light canvas と scheme を一致させる。
+iframe.style.colorScheme = 'light'
+
 const host = new AribReceiverHost({
   iframe,
   viewport,
@@ -218,6 +242,7 @@ type AribMediaPlane = {
       opacity: number
       transform: string
     }>
+    externalPlacement?: 'behind-application' | 'above-application'
   }
 }
 ```
@@ -230,6 +255,12 @@ type AribMediaPlane = {
 合成方針を決めます。ブラウザ用 `DomObjectMediaPlaneAdapter` では DOM 自身が合成するため、
 この変換は不要です。
 
+`externalPlacement` は iframe 外の video を使うブラウザ統合向けの限定的なヒントです。
+`above-application` は、既定寸法の object を包む media-only wrapper が正の `z-index` を持つ場合にだけ
+報告されます。この場合、host は media surface 全体を iframe より前の stacking level にできます。
+ただし iframe 内部との完全な interleave はできないため、映像枠と重なる application UI がある実装では
+`in-object` adapter を使用してください。
+
 ## なぜ iframe 背面方式では不足するか
 
 iframe と親 document の間で選べるのは次の順序だけです。
@@ -259,6 +290,9 @@ iframe 内の背景 < 映像 < iframe 内の字幕説明ボタン
 
 D Data の字幕コンテンツはアプリケーション DOM です。`setCaptionTracks()` と
 `pushCaption()` で iframe へ渡し、通常の放送字幕として親側へ二重描画しないでください。
+アプリケーションが `addCaptionListener()` を登録している間は
+`onCaptionSubscription` に要求中の component tag が通知されます。ネイティブ受信機は
+この通知を使い、同じ字幕を通常の字幕 renderer で二重表示しないようにできます。
 
 ---
 

package/docs/receiver-host-contracts.md

@@ -53,6 +53,11 @@ example `sh4`) themselves. The current document mount is used only when mapping
 root-relative resources such as `/60/...`; it is not included in `baseurl`.
 An injected `baseurl` cannot override the actual VFS scope.
 
+The regional fields `zipcode`, `prefecture`, and `regioncode` are also exposed
+read-only through the legacy `receiverinfo` Ureg used by broadcaster apps. The
+host owns persistence and passes a snapshot; writes inside the app do not flow
+back into the host's settings.
+
 ## Device identifiers
 
 The default package combination remains `huggy`, `Huggy ARIB HTML5 Receiver`,
@@ -81,12 +86,17 @@ const host = new AribReceiverHost({
   viewport,
   onStatus: text => statusLabel.textContent = text,
   onLifecycle(event) {
-    if (event.type === 'installed') clearApplicationTimeout()
-    if (event.type === 'navigating') armApplicationTimeout()
     if (event.type === 'error') reportRuntimeError(event.message)
   },
 })
 ```
 
+`loadApplication()` とアプリケーション内遷移で読み込まれた文書が receiver runtime を
+導入しなかった場合は、iframe の `load` 直後に `about:blank` へ戻し、media plane を
+通常視聴状態へ復元して `error`、`exited` の順に通知します。これにより VFS の未命中や
+通常の 404 文書を画面へ残しません。文書の `load` 自体が発生しない要求には既定 5 秒の
+watchdog を適用します。待機時間は `applicationLoadTimeoutMs` で変更でき、`0` を指定した
+場合は watchdog だけを無効化します。
+
 Lifecycle event types are `loading`, `installed`, `navigating`, `exited`,
 `navigation-blocked`, `frame-blocked`, and `error`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libaribhtml5",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Browser runtime and receiver host for ARIB HTML5 data broadcasting",
   "keywords": [
     "arib",