libaribhtml5 0.1.2 → 0.1.4

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/media-plane.d.ts

@@ -11,6 +11,11 @@ export type AribMediaPlaneStackEntry = {
 export type AribMediaPlaneLayer = {
     documentOrder: number;
     stackingPath: AribMediaPlaneStackEntry[];
+    /**
+     * External compositor fallback for a media-only foreground wrapper.
+     * Omitted/behind-application keeps the host surface below the iframe.
+     */
+    externalPlacement?: 'behind-application' | 'above-application';
 };
 export type AribMediaPlane = {
     slotId: string;
@@ -62,15 +67,22 @@ export declare class DomObjectMediaPlaneAdapter implements AribMediaPlaneAdapter
 export type BehindIframeMediaPlaneAdapterOptions = {
     surface: HTMLElement;
     keepVisible?: boolean;
+    /** Stacking level used for the ordinary media plane behind the iframe. */
+    behindZIndex?: string | number;
+    /** Stacking level used for a foreground media-only wrapper. */
+    aboveZIndex?: string | number;
 };
 /**
- * Simplified compatibility fallback. It cannot interleave media with elements
- * inside the application iframe; the complete iframe is always above it.
+ * Simplified iframe compositor. It normally keeps media behind the complete
+ * application iframe, but can raise a foreground media-only slot as a whole.
+ * It still cannot interleave that surface with individual elements in iframe.
  */
 export declare class BehindIframeMediaPlaneAdapter implements AribMediaPlaneAdapter {
     readonly renderMode: "external";
     private readonly surface;
     private readonly keepVisible;
+    private readonly behindZIndex;
+    private readonly aboveZIndex;
     constructor(options: BehindIframeMediaPlaneAdapterOptions);
     mountMediaPlane(_object: HTMLElement, plane: AribMediaPlane): void;
     updateMediaPlane(_object: HTMLElement, plane: AribMediaPlane): void;

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/media-slot.d.ts

@@ -0,0 +1,13 @@
+export type BroadcastMediaSlot = {
+    element: HTMLElement;
+    rect: DOMRect;
+};
+/**
+ * Resolve the receiver video slot represented by a broadcast object.
+ *
+ * Chromium gives an unsized `<object>` its replaced-element fallback size
+ * (normally 300 x 150). Broadcast applications also use an unsized object as
+ * the sole child of a positioned video-slot wrapper. In that case the wrapper,
+ * rather than the browser fallback box, is the receiver media plane.
+ */
+export declare const resolveBroadcastMediaSlot: (object: HTMLElement) => BroadcastMediaSlot;

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,106 @@
+# ブラウザ 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 として扱いません。
+
+放送ページが object 自身に `width` / `height` を指定せず、positioned wrapper だけに映像枠の寸法を
+指定する場合があります。通常ブラウザはその object を 300 x 150 の既定 replaced-element として計測しますが、
+receiver runtime は object が wrapper の唯一の子である場合に限り wrapper を media slot として採用します。
+この wrapper は外部合成中だけ object と一緒に透明化されるため、放送ページが指定した高い `z-index` を
+削除したり、host の video を iframe より前へ出したりする必要はありません。
+
+ただし、異なる寸法の media-only wrapper が正の `z-index` を持つ場合、その video slot はページ背景の
+前に置くことを意図した foreground media です。runtime は `layer.externalPlacement` を
+`above-application` として報告します。external adapter はこの場合だけ media surface を application
+iframe より前の layer に置きます。標準の `BehindIframeMediaPlaneAdapter` は通常 `z=0`、この場合だけ
+`z=2` を使います（必要なら `behindZIndex` / `aboveZIndex` で host の stacking context に合わせます）。
+通常の全面映像や application background として使われる slot は `behind-application` のままです。
+
+`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 ではありません。