libaribhtml5 0.1.3 → 0.1.5

package/dist/types/device-identifier.d.ts

@@ -1,4 +1,7 @@
 /** Current demo receiver identifier (48-bit hexadecimal ACAS source value). */
 export declare const DEFAULT_RECEIVER_DEVICE_IDENTIFIER = "4194c4ae4730";
+/** Legacy BML browser.getIRDID() type used for the receiver/CAS identifier. */
+export declare const RECEIVER_IRD_ID_TYPE = 5;
+export declare function getDefaultReceiverIrdId(type: number): string | null;
 export type ReceiverDeviceIdentifierProvider = (kind: number) => string | null | undefined | Promise<string | null | undefined>;
 export declare function resolveReceiverDeviceIdentifier(kind: number, provider?: ReceiverDeviceIdentifierProvider): Promise<string>;

package/dist/types/iframe-input.d.ts

@@ -0,0 +1,4 @@
+type PointerTransparentIframe = Pick<HTMLIFrameElement, 'inert' | 'style' | 'tabIndex'>;
+/** Keep the application plane visible without making it an input or focus target. */
+export declare function makeIframePointerTransparent(iframe: PointerTransparentIframe): void;
+export {};

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export { AribReceiverHost } from './receiver-host';
 export type { AribApplicationInformation, AribApplicationReplaceHandler, AribApplicationReplaceRequest, AribCaptionPacket, AribBroadcastClock, AribExitManagedStateHandler, AribReceiverLifecycleEvent, AribReceiverHostOptions, } from './receiver-host';
+export type { AribApplicationPresentationState, AribViewerParticipationEvent, AribViewerParticipationNotification, } from './viewer-participation';
 export { BehindIframeMediaPlaneAdapter, DomObjectMediaPlaneAdapter, } from './media-plane';
 export type { AribMediaPlane, AribMediaPlaneAdapter, AribMediaPlaneLayer, AribMediaPlaneStackEntry, AribMediaPlaneUnmountReason, AribVideoPlane, BehindIframeMediaPlaneAdapterOptions, DomObjectMediaPlaneAdapterOptions, } from './media-plane';
 export { installRuntime } from './runtime/install';
@@ -9,9 +10,12 @@ export { cloneProgramInfo } from './program-info';
 export type { ProgramInfo } from './program-info';
 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 { AribPermissionManagedArea, RuntimeApplicationInformation, RuntimePermissionManagedArea, RuntimeOptions, RuntimeWindow, } from './runtime/install';
+export { ARIB_PERMISSION_BITS, AribApplicationBoundaryPolicy, } from './runtime/application-boundary';
+export type { AribPermissionBit, AribPermissionEvaluation, } from './runtime/application-boundary';
+export { DEFAULT_RECEIVER_DEVICE_IDENTIFIER, getDefaultReceiverIrdId, RECEIVER_IRD_ID_TYPE, resolveReceiverDeviceIdentifier, } from './device-identifier';
 export type { ReceiverDeviceIdentifierProvider } from './device-identifier';
+export { normalizeLctBackgroundColor } from './layout';
 export type { BroadcastResourceCacheEvent, BroadcastResourceCacheListener, BroadcastResourceChange, BroadcastResourceStore, } from './runtime/resources';
 export { installBroadcastClock } from './runtime/clock';
 export type { BroadcastNowProvider } from './runtime/clock';

package/dist/types/layout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert the ARIB STD-B60 24-bit LCT background colour to a CSS colour.
+ * A null value removes the current LCT override and restores host fallback
+ * selection.
+ */
+export declare function normalizeLctBackgroundColor(value: number | null): string | null;
+export declare function resolveReceiverBackgroundColor(lctColor: string | null, stageColor: string | null): string;

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

@@ -5,6 +5,7 @@ import type { ReceiverDeviceIdentifierProvider } from './device-identifier';
 import { type AribMediaPlane, type AribMediaPlaneAdapter } from './media-plane';
 import type { BroadcastResourceChange, BroadcastResourceStore } from './runtime/resources';
 import { type AribProgramGuideHandler, type AribProgramGuideRequest, type AribProgramGuideUnavailableHandler } from './program-guide';
+import { type AribApplicationPresentationState, type AribViewerParticipationEvent, type AribViewerParticipationNotification } from './viewer-participation';
 export type { AribMediaPlane, AribMediaPlaneAdapter, AribMediaPlaneLayer, AribMediaPlaneStackEntry, AribMediaPlaneUnmountReason, AribVideoPlane, } from './media-plane';
 export type AribCaptionPacket = {
     componentTag: number;
@@ -90,6 +91,8 @@ export type AribReceiverHostOptions = {
     systemInformation?: ReceiverSystemInformationOverrides;
     /** Resolve receiver/CAS identifiers; defaults to the bundled Huggy demo identity. */
     getDeviceIdentifier?: ReceiverDeviceIdentifierProvider;
+    /** Receiver UI hook for a TR-B39 viewer-participation corner notification. */
+    onViewerParticipation?: (event: AribViewerParticipationEvent) => void;
 };
 export declare class AribReceiverHost {
     readonly iframe: HTMLIFrameElement;
@@ -115,6 +118,8 @@ export declare class AribReceiverHost {
     private readonly onProgramGuideUnavailable?;
     private readonly systemInformation?;
     private readonly getDeviceIdentifier?;
+    private readonly onViewerParticipation?;
+    private readonly viewerParticipation;
     private readonly resizeObserver;
     private activeRuntimeId;
     private logicalWidth;
@@ -124,6 +129,8 @@ export declare class AribReceiverHost {
     private programInfo;
     private readonly pendingStreamEvents;
     private broadcastClock;
+    private lctBackgroundColor;
+    private stageBackgroundColor;
     private video;
     private mediaPlaneEnabled;
     private applicationExited;
@@ -133,12 +140,25 @@ export declare class AribReceiverHost {
     installRuntime(target: RuntimeWindow): void;
     /** Set the MH-AIT identity exposed by applicationManager.getOwnerApplication(). */
     setApplicationInformation(application: AribApplicationInformation | null): void;
+    /**
+     * Set the receiver-owned background plane from the current LCT
+     * Background_Color_Descriptor. Pass null when changing service/session or
+     * when the active LCT no longer carries the descriptor.
+     */
+    setLctBackgroundColor(backgroundColorRgb: number | null): void;
     /** @deprecated Pass an AribMediaPlaneAdapter to the constructor. */
     attachVideo(video: HTMLVideoElement): void;
     loadApplication(url: string, status?: string): void;
     /** Leave data-broadcast mode and restore media to the ordinary player. */
     exitApplication(status?: string): void;
-    dispatchKey(code: number): void;
+    dispatchKey(code: number): boolean;
+    /** Transfer or release receiver-key ownership for the broadcast application. */
+    setApplicationInputActive(active: boolean): void;
+    getApplicationPresentationState(): AribApplicationPresentationState;
+    /** Handle the descriptor-less TR-B39 receiver notification outside the application. */
+    notifyViewerParticipationCorner(notification: AribViewerParticipationNotification): void;
+    /** Discard notification versions while changing service or playback session. */
+    resetViewerParticipationNotifications(): void;
     setCaptionTracks(componentTags: number[]): void;
     pushCaption(packet: AribCaptionPacket): void;
     resetCaptions(): void;
@@ -172,4 +192,5 @@ export declare class AribReceiverHost {
     private invalidateRuntime;
     private fitBroadcastCanvas;
     private assertAlive;
+    private applyReceiverBackgroundColor;
 }

package/dist/types/runtime/application-boundary.d.ts

@@ -0,0 +1,45 @@
+export declare const ARIB_PERMISSION_BITS: {
+    readonly broadcastMedia: 12;
+    readonly monomediaOverBroadcastVideo: 11;
+    readonly currentEventInformation: 10;
+    readonly persistentStorage: 9;
+    readonly boundaryExtension: 8;
+    readonly deviceIdentifier: 7;
+    readonly ipNetworkConfirmation: 6;
+    readonly broadcastResources: 5;
+    readonly scheduling: 4;
+    readonly cas: 3;
+};
+export type AribPermissionBit = typeof ARIB_PERMISSION_BITS[keyof typeof ARIB_PERMISSION_BITS];
+/** One loop of the MH-application boundary and permission descriptor. */
+export type RuntimePermissionManagedArea = {
+    /** Raw 16-bit permission_bitmap values, including the three-bit bitmap id. */
+    permissionBitmaps: readonly number[] | null;
+    /** managed_URL values. null or an empty array means all locations. */
+    managedUrls: readonly string[] | null;
+};
+/** Shape exposed by ApplicationBoundaryAndPermissionDescriptor in ARIB STD-B62. */
+export type AribPermissionManagedArea = {
+    /** Raw 16-bit permission_bitmap values, or null for maximum permission. */
+    permission: number[] | null;
+    /** Managed URL strings, or null for all locations. */
+    urls: string[] | null;
+};
+export type AribPermissionEvaluation = {
+    withinBoundary: boolean;
+    permissionBits: number;
+};
+export declare class AribApplicationBoundaryPolicy {
+    private readonly broadcastBaseUrl;
+    private readonly documentUrl;
+    private baseAreas;
+    private readonly addedAreas;
+    constructor(broadcastBaseUrl: string | URL, documentUrl: string | URL, areas?: readonly RuntimePermissionManagedArea[]);
+    /** Apply a new MH-AIT descriptor without discarding areas added by the application. */
+    update(areas?: readonly RuntimePermissionManagedArea[]): void;
+    hasDescriptor(): boolean;
+    getCurrentBoundary(): AribPermissionManagedArea[];
+    addPermissionManagedArea(area: AribPermissionManagedArea): void;
+    evaluate(value: string | URL): AribPermissionEvaluation;
+    permits(value: string | URL, bit: AribPermissionBit): boolean;
+}

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

@@ -3,8 +3,10 @@ import type { AribMediaPlaneAdapter } from '../media-plane';
 import { type BroadcastResourceStore } from './resources';
 import { type ReceiverSystemInformationOverrides } from './system-information';
 import { type ReceiverDeviceIdentifierProvider } from '../device-identifier';
+import { type RuntimePermissionManagedArea } from './application-boundary';
 export type { ProgramInfo } from '../program-info';
 export type { RuntimeEvent, RuntimeEventSelector, RuntimeEventSource, } from './stream-event';
+export type { AribPermissionManagedArea, RuntimePermissionManagedArea, } from './application-boundary';
 export type RuntimeWindow = Window & typeof globalThis & Record<string, unknown>;
 export type RuntimeOptions = {
     /** Permit HTTP requests outside the receiver-managed application origin. */
@@ -30,5 +32,7 @@ export type RuntimeApplicationInformation = {
     applicationId?: number;
     controlCode?: string;
     autostartPriority?: number;
+    /** Decoded loops from MH-AIT descriptor 0x802C. Omit when absent. */
+    permissionManagedAreas?: readonly RuntimePermissionManagedArea[];
 };
 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/platform.d.ts

@@ -0,0 +1,4 @@
+type NavigatorPlatform = Pick<Navigator, 'maxTouchPoints' | 'platform' | 'userAgent'>;
+/** iOS media elements can replace the receiver player's active media session. */
+export declare function shouldSuppressRomSoundPlayback(navigator: NavigatorPlatform): boolean;
+export {};

package/dist/types/viewer-participation.d.ts

@@ -0,0 +1,29 @@
+export type AribApplicationPresentationState = {
+    visible: boolean;
+    inputActive: boolean;
+};
+export type AribViewerParticipationNotification = {
+    contextId: number;
+    sourcePacketId: number;
+    eventMessageTag: number;
+    dataEventId: number;
+    messageGroupId: number;
+    version: number;
+    currentNext: boolean;
+    sectionNumber: number;
+    lastSectionNumber: number;
+    inputOffset: bigint;
+};
+export type AribViewerParticipationEvent = AribViewerParticipationNotification & {
+    requiresUserAction: true;
+};
+export declare class ViewerParticipationController {
+    private state;
+    private generation;
+    private readonly delivered;
+    get presentation(): AribApplicationPresentationState;
+    setPresentation(state: Partial<AribApplicationPresentationState>): void;
+    resetPresentation(): void;
+    resetSession(): void;
+    notify(notification: AribViewerParticipationNotification): AribViewerParticipationEvent | null;
+}

package/docs/application-lifecycle.md

@@ -65,6 +65,40 @@ const host = new AribReceiverHost({
 許可境界と外部 network policy を receiver 側で検証し、対応する場合だけ
 `onExitManagedState` で処理します。
 
+## アプリケーション境界と権限
+
+MH-AIT の `MH-Application Boundary and Permission Descriptor` (`descriptor_tag=0x802C`)
+は、decoder 側で一つの application に属する loop を平坦化し、次の形で渡します。
+
+```ts
+host.setApplicationInformation({
+  organizationId: application.organizationId,
+  applicationId: application.applicationId,
+  permissionManagedAreas: application.boundaryDescriptors.flatMap(descriptor =>
+    descriptor.areas.map(area => ({
+      // bitmap ID を含む raw 16-bit 値
+      permissionBitmaps: area.permissionBitmaps,
+      managedUrls: area.managedUrls,
+    })),
+  ),
+})
+```
+
+descriptor がない場合は `permissionManagedAreas` 自体を省略します。この場合は境界が無限で
+全権限です。descriptor が存在し、ある area の `managed_URL_count` が 0 の場合は
+`managedUrls: []`（または `null`）で全 location を表します。より狭い domain/sub-directory の
+設定が一致した場合はそちらを優先します。放送 VFS (`broadcastBaseUrl`) から取得した content は、
+TR-B39 の規定どおり descriptor にかかわらず境界内・全権限として扱います。
+
+runtime は bitmap 0/1 を解釈し、bit 12/10/9/8/7/5 を現在実装済みの broadcast media、番組情報、
+persistent array、boundary extension、receiver ID、application/cache/EMT/system-information API に
+適用します。権限がない同期 API は `Error` (`code="NOT_AUTHORIZED_ERR"`) を送出し、AIT 更新後も
+同じ runtime に直ちに反映します。更新によって現在の communication document が境界外になった場合、
+host は application を終了します。
+
+境界権限と `allowExternalNetwork` は別条件です。MH-AIT が URL を許可しても、host の network policy が
+offline なら外部 HTTP へは遷移・通信できません。
+
 ## AUTOSTART と PRESENT の同居
 
 一つの tuning/session generation につき managed application slot は一つにします。

package/docs/browser-iframe-compositing.md

@@ -25,11 +25,44 @@ object だけを子に持つ media-only wrapper は wrapper 自身も隠しま
 独立した 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 に対する割合へ
 変換して配置します。
 
+## プレーヤー操作への pointer 穿透
+
+データ放送 iframe は全面が透明でも、一つの不透明な矩形と同じように hit test されます。そのまま
+プレーヤーへ重ねると、特に touch device で下の再生 UI がクリックできなくなります。
+
+`AribReceiverHost` は iframe を表示専用の application plane として扱い、既定で `inert`、
+`pointer-events: none !important`、`tabindex="-1"` を設定します。`tabindex="-1"` だけでは iframe 内の
+document が focus を取得できるため不十分です。`inert` によって子 document 全体を focus と hit test の
+対象から外し、下のプレーヤー container へ mouse / touch event と `:hover` を渡します。描画、timer、通信、
+media-plane report は継続します。リモコン入力は iframe の focus に頼らず `host.dispatchKey()` で
+document へ送ってください。
+
+iframe 内の pointer event を親へ再送する実装は使いません。iframe の event は親 document へ bubble
+しないため、再送には座標から対象要素を再決定する処理が必要になり、player controller の click、drag、
+pointer capture を壊します。
+
+HTML/iframe には SVG の `pointer-events: painted` に相当する、非透明 pixel だけを hit test する
+モードはありません。透明度や root の背景色を見て iframe を `display: none` にすると、debug overlay
+以外の application UI や後から表示される画面まで失われるため使用しません。
+
 ## Chromium の白い iframe backdrop
 
 Chromium は iframe owner と iframe 内 root の used `color-scheme` が異なる場合、透明 iframe の

package/docs/media-plane-integration.md

@@ -26,6 +26,24 @@ MMT の source of truth は LCT です。実装時の優先順位は次の通り
    fallback として使ってよい。ただし、これはアプリケーション CSS を LCT と解釈するものではない。
 3. どちらも得られない間の receiver-owned fallback は黒 (`#000`) とする。
 
+`tlvdemux` の WASM 回調は LCT の 24 bit RGB を `backgroundColorRgb` として渡す。
+その値はページ CSS に変換せず、receiver host の背景プレーンへ渡す。
+
+```ts
+const demuxer = new TlvDemuxer({
+  onLayoutConfiguration(layout) {
+    host.setLctBackgroundColor(layout.backgroundColorRgb)
+  },
+})
+
+// 選局・別サービス・別チューニング session へ移る前に前回の LCT を破棄する。
+host.setLctBackgroundColor(null)
+```
+
+LCT の色が設定されている間、後から到着した application stage の CSS 色は
+背景プレーンを上書きしない。`null` で LCT 色を解除した場合だけ、stage 色または
+黒の fallback へ戻る。
+
 この fallback は規格上の既定色ではありません。白いブラウザ canvas の露出を避けるための
 実装上の選択です。確認に使った NHK BS8K の `8k.mmts` から抽出したファイルも、
 `top/source/top.css` の `body` と `#vstream`、および
@@ -127,6 +145,11 @@ window.__ARIB_HTML5_INSTALL__ = (child: RuntimeWindow) => {
 }
 ```
 
+`AribReceiverHost` は全面 iframe を表示専用の inert overlay として扱うため、データ放送の描画を
+残したまま touch/mouse 操作と `:hover` は下のプレーヤー UI へ通り、iframe 内へ browser focus も
+移りません。`pointer-events: none !important` と `tabindex="-1"` も互換用 fallback として設定します。
+放送アプリケーションのリモコン操作には `host.dispatchKey()` を使用してください。
+
 データ放送への出入りは次の二つだけです。
 
 ```ts
@@ -242,6 +265,7 @@ type AribMediaPlane = {
       opacity: number
       transform: string
     }>
+    externalPlacement?: 'behind-application' | 'above-application'
   }
 }
 ```
@@ -254,6 +278,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 の間で選べるのは次の順序だけです。