libaribhtml5 0.1.1 → 0.1.3

package/dist/types/index.d.ts

@@ -1,13 +1,15 @@
 export { AribReceiverHost } from './receiver-host';
-export type { AribCaptionPacket, AribBroadcastClock, AribReceiverLifecycleEvent, AribReceiverHostOptions, } from './receiver-host';
+export type { AribApplicationInformation, AribApplicationReplaceHandler, AribApplicationReplaceRequest, AribCaptionPacket, AribBroadcastClock, AribExitManagedStateHandler, AribReceiverLifecycleEvent, AribReceiverHostOptions, } from './receiver-host';
 export { BehindIframeMediaPlaneAdapter, DomObjectMediaPlaneAdapter, } from './media-plane';
 export type { AribMediaPlane, AribMediaPlaneAdapter, AribMediaPlaneLayer, AribMediaPlaneStackEntry, AribMediaPlaneUnmountReason, AribVideoPlane, BehindIframeMediaPlaneAdapterOptions, DomObjectMediaPlaneAdapterOptions, } from './media-plane';
 export { installRuntime } from './runtime/install';
-export { createReceiverSystemInformation, RECEIVER_SYSTEM_IDENTITY, } from './runtime/system-information';
+export { createReceiverSystemInformation, readReceiverInformationArray, RECEIVER_SYSTEM_IDENTITY, synchronizeReceiverCompatibilityStorage, } from './runtime/system-information';
 export type { ReceiverSystemIdentity, ReceiverSystemInformation, ReceiverSystemInformationOverrides, } from './runtime/system-information';
 export { cloneProgramInfo } from './program-info';
 export type { ProgramInfo } from './program-info';
-export type { RuntimeEvent, RuntimeOptions, RuntimeWindow } from './runtime/install';
+export { runtimeEventMatchesSelector } from './runtime/stream-event';
+export type { RuntimeEvent, RuntimeEventSelector, RuntimeEventSource, } from './runtime/stream-event';
+export type { RuntimeApplicationInformation, RuntimeOptions, RuntimeWindow, } from './runtime/install';
 export { DEFAULT_RECEIVER_DEVICE_IDENTIFIER, resolveReceiverDeviceIdentifier, } from './device-identifier';
 export type { ReceiverDeviceIdentifierProvider } from './device-identifier';
 export type { BroadcastResourceCacheEvent, BroadcastResourceCacheListener, BroadcastResourceChange, BroadcastResourceStore, } from './runtime/resources';
@@ -15,7 +17,7 @@ export { installBroadcastClock } from './runtime/clock';
 export type { BroadcastNowProvider } from './runtime/clock';
 export { installAribSymbolFont } from './runtime/fonts';
 export { DEFAULT_BROADCAST_BASE_PATH, deriveBroadcastRootUrl, normalizeBroadcastBaseUrl, resolveBroadcastUrl, } from './broadcast-url';
-export { deferRomSoundMarkup, installRomSoundProtocol, resolveRomSoundUrl, } from './runtime/romsound';
+export { deferRomSoundMarkup, installRomSoundProtocol, resolveRomSoundUrl, } from './runtime/romsound.js';
 export { prefixBroadcastRootAttributes, prepareBroadcastHtml, prepareBroadcastStylesheet, rewriteBroadcastObjectMarkup, } from './broadcast-document';
 export type { BroadcastDocumentOptions } from './broadcast-document';
 export { BroadcastVfsSession, ServiceWorkerBroadcastVfs } from './service-worker-vfs';

package/dist/types/receiver-host.d.ts

@@ -1,4 +1,4 @@
-import { type RuntimeEvent, type RuntimeWindow } from './runtime/install';
+import { type RuntimeApplicationInformation, type RuntimeEvent, type RuntimeWindow } from './runtime/install';
 import { type ProgramInfo } from './program-info';
 import type { ReceiverSystemInformationOverrides } from './runtime/system-information';
 import type { ReceiverDeviceIdentifierProvider } from './device-identifier';
@@ -13,6 +13,17 @@ export type AribCaptionPacket = {
     tmd?: string;
     data?: string;
 };
+export type AribCaptionSubscription = {
+    componentTags: number[];
+};
+export type AribApplicationInformation = RuntimeApplicationInformation;
+export type AribApplicationReplaceRequest = {
+    organizationId: number;
+    applicationId: number;
+    aitUrl: string | null;
+};
+export type AribApplicationReplaceHandler = (request: AribApplicationReplaceRequest) => void | Promise<void>;
+export type AribExitManagedStateHandler = (url: string) => void | Promise<void>;
 export type AribBroadcastClock = {
     /** Absolute broadcast time at the anchor, as Unix epoch milliseconds. */
     epochMilliseconds: number;
@@ -52,6 +63,8 @@ export type AribReceiverHostOptions = {
     onStatus?: (status: string) => void;
     /** Machine-readable application/runtime lifecycle; never branch on onStatus text. */
     onLifecycle?: (event: AribReceiverLifecycleEvent) => void;
+    /** Time to wait for a loaded document to install the receiver runtime. 0 disables the fallback. */
+    applicationLoadTimeoutMs?: number;
     onUrlChange?: (url: string) => void;
     onMediaPlane?: (plane: AribMediaPlane) => void;
     /** @deprecated Use onMediaPlane. */
@@ -65,6 +78,12 @@ export type AribReceiverHostOptions = {
     resourceStore?: BroadcastResourceStore;
     /** Receiver/WebView bridge which opens the native EPG or a program detail page. */
     onOpenProgramGuide?: AribProgramGuideHandler;
+    /** Active caption components requested by the current broadcast document. */
+    onCaptionSubscription?: (subscription: AribCaptionSubscription) => void;
+    /** Resolve Application.replaceApplication() through the receiver's current MH-AIT. */
+    onReplaceApplication?: AribApplicationReplaceHandler;
+    /** Transfer an application to an unmanaged general-application URL. */
+    onExitManagedState?: AribExitManagedStateHandler;
     /** Override the default browser alert when the receiver cannot open the EPG. */
     onProgramGuideUnavailable?: AribProgramGuideUnavailableHandler;
     /** Receiver identity/capabilities exposed to the broadcast application. */
@@ -80,6 +99,7 @@ export declare class AribReceiverHost {
     private readonly origin;
     private readonly onStatus?;
     private readonly onLifecycle?;
+    private readonly applicationLoadTimeoutMs;
     private readonly onUrlChange?;
     private readonly onMediaPlane?;
     private readonly onVideoPlane?;
@@ -89,6 +109,9 @@ export declare class AribReceiverHost {
     private readonly broadcastBaseUrl;
     private readonly resourceStore?;
     private readonly onOpenProgramGuide?;
+    private readonly onCaptionSubscription?;
+    private readonly onReplaceApplication?;
+    private readonly onExitManagedState?;
     private readonly onProgramGuideUnavailable?;
     private readonly systemInformation?;
     private readonly getDeviceIdentifier?;
@@ -97,14 +120,19 @@ export declare class AribReceiverHost {
     private logicalWidth;
     private logicalHeight;
     private captionComponentTags;
+    private applicationInformation;
     private programInfo;
+    private readonly pendingStreamEvents;
     private broadcastClock;
     private video;
     private mediaPlaneEnabled;
     private applicationExited;
+    private applicationLoadTimer;
     private destroyed;
     constructor(options: AribReceiverHostOptions);
     installRuntime(target: RuntimeWindow): void;
+    /** Set the MH-AIT identity exposed by applicationManager.getOwnerApplication(). */
+    setApplicationInformation(application: AribApplicationInformation | null): void;
     /** @deprecated Pass an AribMediaPlaneAdapter to the constructor. */
     attachVideo(video: HTMLVideoElement): void;
     loadApplication(url: string, status?: string): void;
@@ -138,6 +166,9 @@ export declare class AribReceiverHost {
     private applyMediaPlane;
     private readMediaLayer;
     private postToRuntime;
+    private armApplicationLoadTimer;
+    private failApplicationLoad;
+    private clearApplicationLoadTimer;
     private invalidateRuntime;
     private fitBroadcastCanvas;
     private assertAlive;

package/dist/types/runtime/install.d.ts

@@ -4,14 +4,8 @@ import { type BroadcastResourceStore } from './resources';
 import { type ReceiverSystemInformationOverrides } from './system-information';
 import { type ReceiverDeviceIdentifierProvider } from '../device-identifier';
 export type { ProgramInfo } from '../program-info';
+export type { RuntimeEvent, RuntimeEventSelector, RuntimeEventSource, } from './stream-event';
 export type RuntimeWindow = Window & typeof globalThis & Record<string, unknown>;
-export type RuntimeEvent = {
-    source: {
-        event_message_tag: number;
-    };
-    message_id: number;
-    private_data_byte: string;
-};
 export type RuntimeOptions = {
     /** Permit HTTP requests outside the receiver-managed application origin. */
     allowExternalNetwork?: boolean;
@@ -27,5 +21,14 @@ export type RuntimeOptions = {
     systemInformation?: ReceiverSystemInformationOverrides;
     /** Resolve receiver/CAS identifiers by receiverDevice identifier kind. */
     getDeviceIdentifier?: ReceiverDeviceIdentifierProvider;
+    /** MH-AIT metadata for the application which owns this document. */
+    application?: RuntimeApplicationInformation;
+};
+export type RuntimeApplicationInformation = {
+    type?: string;
+    organizationId?: number;
+    applicationId?: number;
+    controlCode?: string;
+    autostartPriority?: number;
 };
 export declare function installRuntime(target: RuntimeWindow, options?: RuntimeOptions): void;

package/dist/types/runtime/stream-event.d.ts

@@ -0,0 +1,21 @@
+export type RuntimeEventSource = {
+    original_network_id?: number;
+    tlv_stream_id?: number;
+    service_id?: number;
+    event_message_tag: number;
+};
+export type RuntimeEvent = {
+    source: RuntimeEventSource;
+    message_group_id: number;
+    message_id: number;
+    message_version: number;
+    private_data_byte: string;
+};
+export type RuntimeEventSelector = {
+    source?: Partial<RuntimeEventSource>;
+    message_group_id?: number;
+    message_id?: number;
+    message_version?: number;
+};
+export declare function runtimeEventMatchesSelector(event: RuntimeEvent, selector: RuntimeEventSelector): boolean;
+export declare function sameRuntimeEventSelector(first: RuntimeEventSelector, second: RuntimeEventSelector): boolean;

package/dist/types/runtime/system-information.d.ts

@@ -12,3 +12,15 @@ export type ReceiverSystemInformation = ReceiverSystemIdentity & {
 export type ReceiverSystemInformationOverrides = Partial<ReceiverSystemIdentity> & Record<string, unknown>;
 export declare const RECEIVER_SYSTEM_IDENTITY: Readonly<ReceiverSystemIdentity>;
 export declare function createReceiverSystemInformation(baseurl: string, overrides?: ReceiverSystemInformationOverrides): ReceiverSystemInformation;
+/**
+ * Mirror receiver-owned regional data into compatibility keys used directly
+ * by broadcaster libraries. NHK's nhksh.getZipCode(), for example, reads the
+ * historical `_zipcode` localStorage key instead of receiverinfo NVRAM.
+ */
+export declare function synchronizeReceiverCompatibilityStorage(storage: Pick<Storage, 'setItem' | 'removeItem'>, systemInformation: ReceiverSystemInformation): void;
+/**
+ * Project receiver-owned regional settings into the legacy receiverinfo Ureg.
+ * The host remains the sole owner of persistence; broadcast applications only
+ * receive the snapshot supplied in systemInformation.
+ */
+export declare function readReceiverInformationArray(namespace: string, structure: string, systemInformation: ReceiverSystemInformation): unknown[] | null;

package/dist/types/service-worker-vfs.d.ts

@@ -38,12 +38,19 @@ export declare class BroadcastVfsSession {
     private drainScheduled;
     private ioTail;
     private sessionReady;
+    private disposed;
     constructor(backend: BroadcastVfsBackend, options?: BroadcastVfsSessionOptions);
     beginSession(): Promise<void>;
     enqueue(resource: BroadcastVfsResource): number;
     waitFor(revision: number): Promise<void>;
     /** Ensure a staged path is readable, replaying the page-owned mirror if needed. */
     ensure(path: string, revision?: number): Promise<void>;
+    /**
+     * Stop accepting resources, discard queued writes, and wait for the one
+     * backend operation which may already be running. The backend itself remains
+     * owned by the caller and can be reset or disposed after this resolves.
+     */
+    dispose(): Promise<void>;
     private appendIo;
     private scheduleDrain;
     private drainOne;
@@ -55,12 +62,23 @@ export declare class ServiceWorkerBroadcastVfs {
     private readonly uniqueBasenameFallback;
     private registration;
     private ready;
+    private readonly inFlight;
+    private disposing;
+    private disposed;
     constructor(options: ServiceWorkerBroadcastVfsOptions);
     initialize(): Promise<ServiceWorkerRegistration>;
     begin(): Promise<void>;
     put(resource: BroadcastVfsResource): Promise<void>;
     canRead(path: string): Promise<boolean>;
     reset(): Promise<void>;
+    /**
+     * Clear the receiver-owned VFS session after outstanding requests finish.
+     * The shared Service Worker registration is intentionally retained so other
+     * tabs and future receiver instances keep a stable scoped fetch handler.
+     */
+    dispose(): Promise<void>;
     private request;
+    private performRequest;
+    private performRequestWithRegistration;
     private waitForActivation;
 }

package/docs/android-program-guide.md

@@ -1,80 +1,17 @@
 # Android の「放送予定」と番組表連携
 
-## Android ファームウェアで確認できた処理
+## 受信機所有の EPG へ渡す
 
-「放送予定」は放送 HTML 内のページではなく、受信機が所有する EPG 機能です。
-SMB400 rev24.24 では次の経路になっています。
+「放送予定」は放送 HTML 内へ任意の番組表 URL を開く操作ではなく、受信機が所有する
+番組詳細・予約 UI へ番組識別子を渡す host operation として扱います。
 
-1. `ProgramInfoProvider` がチューナーの `program_info.sqlite3` を検索用 DB へ同期する。
-2. `ProgramInfoOpenHelper` が現在時刻と番組の開始・終了時刻を比較する。
-   放送中は `live`、開始前は `future` とし、future の検索タイトルへ
-   `[放送予定]` を付ける。
-3. Android TV の検索結果を選ぶと `SearchableProgramInfo` が
-   `TvTunerService` を起動し、番組情報と `future` を渡す。
-4. `TvTunerService` は future の場合に `StartMode.Reserve` を選び、別パッケージの
-   `jp.pixela.atv_app.MainActivity` を起動する。
-5. その Activity の WebView は次の内蔵ページを開く。
+現在時刻と番組の開始・終了時刻から `live` / `future` を判定し、放送種別、network ID、
+service ID、event ID を receiver bridge へ渡します。受信機側は識別子を現在の EIT/EPG と
+照合してから、自アプリ内の画面を開いてください。放送 application から渡された URL を
+そのまま WebView や外部 Activity へ転送してはいけません。
 
-```text
-file:///android_asset/programList/index.html?ts=...
-  #/?program_id=...&broadcast_type=...&service_id=...&event_id=...
-```
-
-したがって、これは任意の外部 URL を開く機能ではありません。検索結果から受信機所有の
-番組詳細・予約 UI へ移る、明示的なホスト機能です。
-
-### future 判定と検索データ
-
-`ProgramInfoOpenHelper` の判定は単純な派生状態です。番組時刻は DB 内では秒単位で、
-比較時にミリ秒へ変換されます。
-
-```text
-now >= start + duration  -> 検索結果に入れない
-start <= now < end       -> live
-now < start              -> future（最大 50 件）
-```
-
-future の `suggest_text_1` は `[放送予定] 番組名` になります。同じ放送種別、
-service ID、event ID の有効な予約があれば `[予約済]` も追加されます。
-`suggest_intent_extra_data` には番組 JSON と `#future`、live の場合は `#live` が入り、
-クリック後の `TvTunerService` はこの suffix で遷移を分けます。
-
-Provider は次の標準 suggestion 列を公開します。
-
-- `suggest_text_1` / `suggest_text_2`
-- `suggest_result_card_image`（ジャンル別 320 x 180 画像）
-- `suggest_is_live`
-- `suggest_intent_extra_data`
-- `suggest_intent_data_id`
-
-Katniss 側のローカル suggestion 変換では、タイトル、説明、カード画像、intent extra data
-をそのまま読み、`suggest_is_live` 自体では分岐していません。したがって、この機種で
-future を決定している本体は `ProgramInfoOpenHelper` と `#future` の受け側です。
-
-また、APK の日本語リソースに存在する原文は `[放送予定]` で、括弧なしの
-`放送予定` という独立した文字列リソースは見つかりません。スクリーンショットの括弧なし
-表示は検索 UI 側のプレゼンテーションであり、放送 HTML やフォントが生成する状態では
-ありません。
-
-### EPG の保存と更新
-
-検索時に放送波を直接スキャンしているわけではありません。ネイティブチューナーが持つ
-`program_info.sqlite3` の更新時刻を監視し、検索用の `program_info.db` へコピーします。
-検索要求ごとに一時 `suggest_content.db` を作り直し、番組名・説明とチャンネル名を検索します。
-
-バックグラウンド更新は起動後 5 分、その後 30 分ごとに判定されます。EPG スキャンを
-実行する JST の時間帯はコード上で次の二つです。
-
-- 04:38–07:37
-- 16:38–19:37
-
-更新サービスは `StartMode.UpdateEPG` でチューナーを初期化し、EPG cache target `0` を
-更新して最大 120 秒待ちます。録画対応機では録画コンテンツ target `5` と予約 target `6`
-も更新します。テレビアプリが前面へ出た場合、バックグラウンド更新は中止されます。
-
-なお、ARIB STD-B62 Volume 2 には `receiverDevice.scheduleToTune()` などの
-視聴・録画予約 API もありますが、上記の Android 検索結果から番組詳細を開く処理とは
-別のインターフェースです。
+ARIB STD-B62 Volume 2 の `receiverDevice.scheduleToTune()` 等の視聴・録画予約 API と、
+この host 固有の番組表画面を開く操作は別のインターフェースです。
 
 ## libaribhtml5 のホストインターフェース
 

package/docs/application-lifecycle.md

@@ -0,0 +1,95 @@
+# MH-AIT アプリケーションライフサイクル
+
+この文書は、ARIB HTML5 データ放送の自動起動、表示用アプリケーションへの切替、終了、
+および EMT の責務境界を receiver host 向けにまとめます。放送局固有の URL や EMT ID を
+プレーヤーへハードコードしないための実装条件です。
+
+## 制御の所有者
+
+アプリケーションの起動と終了は MH-AIT の application control code が制御します。
+
+| control code | 値 | receiver の動作 |
+| --- | ---: | --- |
+| `AUTOSTART` | `0x01` | entry resource が利用可能になった時点で自動起動する |
+| `PRESENT` | `0x02` | 実行可能として保持する。新しいページを自動起動しない |
+| `KILL` | `0x04` | 対象の managed application を直ちに終了する |
+| `PREFETCH` | `0x05` | resource を取得・保持する。表示や起動は行わない |
+
+根拠は ARIB STD-B60 1.5版 10.3.2.1 表10-8の application control code と、同規格
+10.3.3.1 の MH-application descriptor です。
+
+`AUTOSTART` は起動を指示する control code であり、CSS の表示状態を指示しません。
+ユーザーへの可視性は別フィールドである MH-application descriptor の `visibility` で決まります。
+
+| visibility | receiver の動作 |
+| ---: | --- |
+| `00` | エラー報告等を除き、ユーザーと他 application の双方へ不可視 |
+| `01` | ユーザーへ不可視。他 application からは API 等を介して可視 |
+| `10` | reserved |
+| `11` | ユーザーと他 application の双方へ可視 |
+
+`00` / `01` でも document、timer、通信、EMT listener は実行を続けます。iframe を `display:none`
+にして実行を止めず、receiver compositor の application plane だけをユーザーへ合成しません。
+`11` の AUTOSTART は通常どおり画面を描画できます。
+
+別 application へ切り替える必要がある場合、実行中のページが
+`navigator.applicationManager.getOwnerApplication().replaceApplication(...)` を呼びます。
+
+## replaceApplication
+
+ARIB STD-B62 第二編 3.3.7–3.3.8 は `ApplicationManager` と `Application` を定義します。
+`replaceApplication(organization_id, application_id, ait_url)` は現在の application を終了し、
+指定した application を起動する受信機要求です。EMT を受信した host が URL を推測する機能ではありません。
+
+`libaribhtml5` はこの要求を `AribReceiverHostOptions.onReplaceApplication` へ渡します。
+host は現在の MH-AIT から `(organizationId, applicationId)` を検索し、entry resource の VFS commit を
+待ってから、同じ `AribReceiverHost` / iframe で `loadApplication()` を実行してください。
+
+```ts
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  onReplaceApplication: async request => {
+    const target = currentApplications.get(
+      `${request.organizationId}:${request.applicationId}`,
+    )
+    if (!target) throw new Error('Application is not present in the current MH-AIT')
+    await vfs.waitFor(target.entryRevision)
+    host.setApplicationInformation(target.information)
+    host.loadApplication(target.entryUrl, 'アプリケーション切替中')
+  },
+})
+```
+
+`exitFromManagedState(url)` は放送管理外の general application へ移る別の操作です。
+許可境界と外部 network policy を receiver 側で検証し、対応する場合だけ
+`onExitManagedState` で処理します。
+
+## AUTOSTART と PRESENT の同居
+
+一つの tuning/session generation につき managed application slot は一つにします。
+
+1. active application がない時だけ、ready になった `AUTOSTART` を読み込む。
+2. `PRESENT` は data button 用の候補として保持するが、それだけで iframe を reload しない。
+3. 同じ application が AUTOSTART から PRESENT へ更新され、継続条件を満たす場合は既存 runtime を再利用する。
+4. `KILL`、AIT からの消失、AIT location descriptor の消失、tune/session reset で runtime と listener を破棄する。
+5. 404 または runtime bootstrap 不成立が確定した時点で直ちに破棄する。固定の再試行待ち時間中、
+   壊れたページを表示し続けない。
+
+application state、resource revision、EMT listener、version deduplication はすべて tuning generation に
+所属させます。前チャンネルの非同期完了や event を新しい iframe へ渡してはいけません。
+
+## EMT は起動コマンドではない
+
+ARIB STD-B60 1.5版 11章の Event Message Table は、実行中 application の登録済み selector へ
+event message を指定時刻に配送する仕組みです。規格には即時、UTC、NPT、相対時刻等の time mode が
+あります。現在の runtime が保証するのは即時配送 (`time_mode=0`) だけであり、その他の ignition time は
+receiver clock scheduler を実装するまで未対応です。
+
+- EMT `40/5` 等を見て host が表示ページ URL を決めない。
+- application が listener を登録する前に到着した event を、起動後に独自再生しない。
+- 同じ message ID/version は重複配送しない。
+- listener 登録後に受信した、または放送側が再送した event だけを application へ渡す。
+
+したがって紅白等の連動ページは、MH-AIT による AUTOSTART、ページ内 listener 登録、EMT 配送、
+ページによる `replaceApplication()` の順に進みます。

package/docs/browser-iframe-compositing.md

@@ -0,0 +1,93 @@
+# ブラウザ iframe 合成の注意事項
+
+この文書は、通常ブラウザでデータ放送 iframe と既存プレーヤーの `<video>` を合成する際の
+ブラウザ固有の制約をまとめます。ARIB のプレーン順序そのものは
+[メディアプレーン統合ガイド](media-plane-integration.md)を参照してください。
+
+## 必須のレイヤー構成
+
+外部映像面を使う場合は、同じ 16:9 container の sibling として次の順に置きます。
+
+```text
+z=0  receiver-owned background plane
+z=1  プレーヤーが所有する既存 video
+z=2  データ放送 iframe
+```
+
+video の複製や canvas への 1:1 コピーは行いません。MSE に接続済みのプレーヤー所有 video を
+media object の矩形へ移動・リサイズして使います。video を iframe より前へ上げると、字幕説明、
+ダイアログ、字幕ボタンなど本来映像より前にある application UI まで隠れるため禁止です。
+
+iframe 内の `object[type="video/x-arib2-broadcast"]` は映像そのものではなく、外部 video plane の
+位置・寸法・可視状態を宣言する geometry anchor として残します。external adapter は object の描画を
+`opacity: 0 !important` で隠します。さらに `#vstream > object#av` のように、object と同じ矩形で
+object だけを子に持つ media-only wrapper は wrapper 自身も隠します。wrapper が高い `z-index` の
+独立した compositing layer を作る場合、背景だけを透明化しても Chromium が外部 video の上へその layer を
+残すためです。字幕、ダイアログ、操作 UI を含む祖先は media-only wrapper として扱いません。
+
+`display: none`、`visibility: hidden`、`content-visibility: hidden` は矩形計測または可視判定を壊すため
+使用しません。runtime は隠す前の computed opacity を media-plane report に使い、host 側の video は
+object の CSS を複製せず、報告された `getBoundingClientRect()` を logical viewport に対する割合へ
+変換して配置します。
+
+## Chromium の白い iframe backdrop
+
+Chromium は iframe owner と iframe 内 root の used `color-scheme` が異なる場合、透明 iframe の
+代わりに scheme に対応する不透明 backdrop を描画します。dark theme の host に、標準の light
+canvas を使う放送ページを埋め込むと白になります。
+
+この白は DOM の背景ではないため、次をすべて確認しても残ります。
+
+- iframe、`html`、`body` の computed `background-color` が透明
+- 背景画像と疑似要素がない
+- iframe の `opacity` や `z-index` を変更した
+
+この判定を無効化する公開 feature flag はありません。receiver が管理する iframe owner と
+放送ページ root の双方に同じ scheme を明示します。
+
+```ts
+iframe.style.colorScheme = 'only light'
+iframe.contentDocument.documentElement.style.setProperty('color-scheme', 'only light', 'important')
+```
+
+これは clickjacking/XSS 対策による透明 iframe の禁止ではありません。Blink は owner と embedded
+document の scheme が異なる場合に canvas backdrop を意図的に描画しています。
+
+## application background と media hole
+
+external adapter は video を iframe の背後に置くため、application canvas の `html` / `body` を
+透明化します。ただし元の stage 背景色まで捨てると、映像領域外に host アプリの背景が露出します。
+runtime は透明化前の stage 色を host へ報告し、host はその色を z=0 の receiver background plane
+へ置きます。`body` が白でも `#backscreen` のような不透明要素が application canvas 全体を覆う場合は、
+その全画布要素を実際の stage 色として優先します。色を取得できない間の実装 fallback は黒です。
+
+iframe 内では、media object 自身を透明にしても、その祖先や object より前にある装飾用背景要素が
+同じ矩形を塗ると外部 video を隠します。external runtime は次の背景だけを一時的に透明化します。
+
+- media object の不透明な祖先背景
+- media object の矩形全体を覆う application element の不透明な背景
+
+要素自体は削除せず、`background-color` と `background-image` だけを退避して透明化します。
+media object が消える、ページが遷移する、または application が終了すると元の inline style を
+復元します。要素内の文字、画像、字幕、ダイアログ、操作 UI は削除せず、透明な debug overlay
+も変更しません。media slot 全体を覆わないボタンやパネルの背景も対象外です。
+
+runtime が一度透明化した背景要素は、media slot を覆っている間は管理対象として保持します。
+透明化後の computed style だけを見て対象外にすると、MutationObserver の各走査で
+「透明化 → 元へ復元」を繰り返し、映像面と application 背景が点滅します。
+
+## DevTools での切り分け
+
+白い全面シートでは、まず owner/root の scheme を確認します。
+
+```js
+const frame = document.querySelector('iframe.dplayer-tlv-data-broadcast')
+console.table({
+  owner: getComputedStyle(frame).colorScheme,
+  root: getComputedStyle(frame.contentDocument.documentElement).colorScheme,
+})
+```
+
+黒い media slot では、video の `readyState` と矩形を確認した後、iframe 内で media object より前に
+ある covering element の背景を確認します。DevTools の青い半透明表示は選択要素の highlight で、
+実際の video frame や application background ではありません。

package/docs/media-plane-integration.md

@@ -13,6 +13,68 @@
 caption ページを正しく表示するなら、1 番目または 2 番目が必要です。
 `BehindIframeMediaPlaneAdapter` では実現できません。
 
+## 背景プレーンの制約
+
+BS4K/BS8K の背景は、データ放送ページが任意に選ぶ壁紙ではありません。受信機は
+マルチメディアプレーンより後ろに、画面全体を覆う単色の背景プレーンを持ちます。
+前面のプレーンが透明、または何も描画していない画素だけに、この色が見えます。
+
+MMT の source of truth は LCT です。実装時の優先順位は次の通りです。
+
+1. LCT の `Background_Color_Descriptor` があれば、その RGB 各 8 bit の値を使う。
+2. LCT の色をまだ受け取っていない間は、アプリケーションが報告した stage の単色を互換
+   fallback として使ってよい。ただし、これはアプリケーション CSS を LCT と解釈するものではない。
+3. どちらも得られない間の receiver-owned fallback は黒 (`#000`) とする。
+
+この fallback は規格上の既定色ではありません。白いブラウザ canvas の露出を避けるための
+実装上の選択です。確認に使った NHK BS8K の `8k.mmts` から抽出したファイルも、
+`top/source/top.css` の `body` と `#vstream`、および
+`caption/source/caption.css` の `#backscreen` と `.bs8k #container` に黒を指定しています。
+したがって、このサンプル用に背景画像やグラデーションを追加しません。
+
+背景の実装には、さらに次の制約があります。
+
+- 背景プレーンは viewport 全体を覆い、映像、アプリケーション、字幕、文字スーパーより後ろに置く。
+- LCT の色はアプリケーションやサービスの切り替え時に引き継がない。新しい LCT を受け取るまでは
+  fallback に戻す。
+- `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): 背景プレーンは最背面で、前面が透明または
+  未描画の部分に指定色を表示する。
+- 同 5.3: MMT 方式の受信機は LCT で指定された色を背景プレーンへ描画して合成する。
+- 同 6.1.1: 背景プレーンは 7680x4320、BT.2020 系の RGB 各 8 bit として定義される。
+- ARIB STD-B60 1.5版 7.3.3.3 および 7.4.3.3: LCT と
+  `Background_Color_Descriptor` (`descriptor_tag=0x8002`) を定義し、24 bit を RGB 各 8 bit
+  の背景色として扱う。
+
 ## ブラウザへ組み込む最小コード
 
 普通の動画表示領域とデータ放送 iframe を同じ viewport に置きます。
@@ -48,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 +283,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.1",
+  "version": "0.1.3",
   "description": "Browser runtime and receiver host for ARIB HTML5 data broadcasting",
   "keywords": [
     "arib",