libaribhtml5 0.1.3 → 0.1.4

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/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/docs/browser-iframe-compositing.md

@@ -25,6 +25,19 @@ 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 に対する割合へ

package/docs/media-plane-integration.md

@@ -242,6 +242,7 @@ type AribMediaPlane = {
       opacity: number
       transform: string
     }>
+    externalPlacement?: 'behind-application' | 'above-application'
   }
 }
 ```
@@ -254,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 の間で選べるのは次の順序だけです。

package/package.json

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