libaribhtml5 0.1.9 → 0.2.0

package/dist/types/runtime/external-media-hole.d.ts

@@ -9,7 +9,7 @@ export declare class ExternalMediaHoleController {
     private readonly placeholderOpacities;
     private readonly backgrounds;
     constructor(target: RuntimeWindow);
-    set(object: HTMLElement, enabled: boolean): void;
+    set(object: HTMLElement, enabled: boolean, clearBackgrounds?: boolean): void;
     restore(): void;
     /** Read application styles while temporarily exposing backgrounds hidden for external video. */
     withApplicationBackgrounds<T>(callback: () => T): T;

package/dist/types/runtime/media-plane-runtime.d.ts

@@ -51,6 +51,8 @@ export declare class RuntimeMediaPlaneController {
     private slotIdFor;
     private callMediaPlaneAdapter;
     private unmountMediaPlane;
+    /** A foreground surface must not cover opaque application dialogs above its slot. */
+    private isCoveredByApplication;
     private reportMediaPlane;
 }
 export {};

package/docs/browser-iframe-compositing.md

@@ -37,6 +37,11 @@ receiver runtime は object が wrapper の唯一の子である場合に限り
 iframe より前の layer に置きます。標準の `BehindIframeMediaPlaneAdapter` は通常 `z=0`、この場合だけ
 `z=2` を使います（必要なら `behindZIndex` / `aboveZIndex` で host の stacking context に合わせます）。
 通常の全面映像や application background として使われる slot は `behind-application` のままです。
+`above-application` では背景に穴を開ける必要がないため、object / media-only wrapper の透明化だけを行い、
+application element の背景色・背景画像は保持します。後景から前景へ切り替わる場合は退避した背景を復元します。
+前景 slot 全体が上位の不透明な矩形パネルで覆われた場合は、外部 surface のみ visible=false として
+調査の選択・閉じるボタンを保護します。パネルを閉じると元の矩形・layer のまま表示を復元します。
+半透明や部分的な重なりの完全な interleave は、この外部 iframe 合成方式の対象外です。
 
 `display: none`、`visibility: hidden`、`content-visibility: hidden` は矩形計測または可視判定を壊すため
 使用しません。runtime は隠す前の computed opacity を media-plane report に使い、host 側の video は

package/package.json

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

package/docs/receiver-compatibility-roadmap.md

@@ -1,300 +0,0 @@
-# Receiver compatibility roadmap
-
-## Purpose and scope
-
-This document records the remaining receiver-runtime work needed to run long-lived ARIB
-HTML5 data services in HonomiTV. The primary target is live and recorded BS4K/BS8K
-playback, including viewer-participation programmes. An isolated demo and Komorebi are useful
-secondary checks, but they are not the integration source of truth.
-
-The component boundary is:
-
-| Component | Responsibility |
-| --- | --- |
-| `tlvdemux` | Parse MMT/TLV, MMT-SI, LCT, MH-AIT, EMT, EIT, and carousel resources |
-| DPlayer | Own playback and forward typed TLV events without changing their meaning |
-| `libaribhtml5` | Own iframe/VFS, receiver API objects, application state, permissions, media slots, and receiver input state |
-| HonomiTV | Own live/recorded mode, service/session lifetime, remote-control UI, network proxy, and user-facing notices |
-
-Broadcaster directory names such as `sh4`, `sh8`, or `bsfuji4k` are not protocol fields and
-must not become policy. Application entries come from the active MH-AIT/resource context.
-
-This status was reviewed on 2026-08-02 against the English ARIB TR-B39 2.5 and STD-B62 2.2
-documents in `../ARIB-docs`, plus extracted NHK BS4K/BS8K applications.
-
-## Current coverage
-
-The current runtime already covers the receiver API surface exercised by the inspected NHK
-applications:
-
-- early runtime bootstrap and `receiverDevice.getSystemInformation(null)`;
-- `getDeviceIdentifier()` and the legacy `bmlCompat.browserPseudo.getIRDID()` path;
-- persistent-array compatibility and receiver-owned regional information;
-- current/following EIT delivery;
-- immediate general event-message delivery;
-- carousel resource retention callbacks;
-- caption existence, subscription, and TTML/resource delivery;
-- MH-AIT identity, application replacement, destruction, and managed-state exit;
-- application boundary/permission bitmap evaluation;
-- broadcast media-slot discovery and external media-plane composition;
-- LCT receiver background colour with an application-stage fallback;
-- receiver clock projection from stream time and media position.
-
-The important remaining work is mostly state and lifecycle semantics rather than adding names
-which only return a placeholder value.
-
-## P0: required for long-lived interactive broadcasts
-
-### Viewer-participation corner notification and input ownership
-
-TR-B39 Part 1 Volume 3 section 6.2.5 defines a receiver-level notification for games,
-questionnaires, and viewer voting:
-
-- `data_event_id` is `0xF`;
-- `event_msg_group_id` is `0xF00`;
-- the EMT has no event-message descriptor;
-- receiving it does not raise an interrupt event in the broadcast application;
-- when receiver input is not directed to the data application, the receiver may show a notice
-  which lets the viewer make the application controllable with a simple operation.
-
-This differs from an application `GeneralEventMessageListener`. It must not be injected into
-the page as an invented EMT callback.
-
-`Application.show()`, `hide()`, `activateInput()`, and `deactivateInput()` currently return
-success without changing receiver state. They need to update a receiver-owned application
-presentation/input state. `AribReceiverHost` then needs a host-facing viewer-participation
-notification contract. HonomiTV remains responsible for rendering the notice and deciding
-which UI action transfers control to the application.
-
-A future API may resemble the following, but these names are not yet a stable contract:
-
-```ts
-const host = new AribReceiverHost({
-  iframe,
-  viewport,
-  onViewerParticipation(event) {
-    if (event.requiresUserAction) showDataBroadcastParticipationNotice()
-  },
-})
-
-host.notifyViewerParticipationCorner({
-  contextId,
-  serviceId,
-  version,
-})
-```
-
-Repeated transmissions must be deduplicated by the current tuning generation, service, and
-message version. A service/session reset clears the notification state.
-
-Parser prerequisite: the current `tlvdemux` EMT parser emits events only for an event-message
-descriptor (`descriptor_tag=0xF003`). It must expose the descriptor-less `0xF00` receiver
-notification separately instead of fabricating a general event message.
-
-Acceptance criteria:
-
-1. A hidden or input-inactive application causes one host notification for a new participation
-   corner version.
-2. An already controllable application does not cause an unnecessary notice.
-3. Repeated transmission of the same version does not spam the UI.
-4. The notification is never delivered to an application EMT listener.
-5. Changing service or playback session discards the old notification.
-
-### Carousel resource update and deletion semantics
-
-Real NHK application code uses `storeDataResource("./", listener)` to monitor a directory and
-detect source updates or disappearance. The current cache implementation is centered on an
-exact resolved URL:
-
-- directory listeners do not observe descendant resource changes;
-- VFS `put()` does not automatically notify the active receiver runtime;
-- the Service Worker protocol has no single-resource deletion operation;
-- `notifyDataResource()` is a separate manual action which an integrator may omit;
-- a removed resource may therefore remain readable from the VFS mirror.
-
-VFS mutation and CacheEvent notification should share one receiver-owned lifecycle. The
-event contract needs atomic `updated`, `deleted`, `store_finished`, and `store_failed`
-semantics for both file and directory targets. A directory listener must match descendants
-without receiving unrelated application resources.
-
-A future high-level host contract should cover update, deletion, and session reset in one place,
-for example:
-
-```ts
-host.updateBroadcastResource({ path, revision })
-host.removeBroadcastResource(path)
-host.resetBroadcastResources()
-```
-
-The VFS may retain older bytes until a complete new resource is committed, but the runtime
-must not report `updated` before those new bytes are readable.
-
-### Complete MH-AIT state and update listeners
-
-`setApplicationInformation()` currently describes only the application owning the active
-document. The receiver also needs the complete current MH-AIT so it can implement:
-
-- `Application.getOwnerAIT()`;
-- `ApplicationInformationTable.getApplications()`;
-- `streamEvent.addAITUpdateListener()`;
-- `streamEvent.removeAITUpdateListener()`.
-
-The host should accept one detached, validated table snapshot containing the table version and
-all applications in transmission order. Updating the table must preserve the currently running
-document when the continuation rules allow it, update its identity/permission snapshot in
-place, and notify registered AIT listeners. A removed or killed active application must exit.
-
-HonomiTV already maintains all demuxed application states, so it should pass that snapshot
-rather than reimplementing the AIT object in application code.
-
-### Correct event-ID update behaviour
-
-TR-B39 requires `addEventIDUpdateListener()` to call the listener once immediately with an
-`ISDBResourceReference`, then again whenever the current event ID changes. The current
-runtime queues a zero-argument callback only after a later `program-info` update.
-
-The runtime must additionally:
-
-- provide `original_network_id`, `tlv_stream_id`, `service_id`, and `event_id`;
-- use `event_id: null` when no current event exists;
-- distinguish `tlv_stream_id` from the legacy `transport_stream_id` compatibility alias;
-- avoid notifying merely because a title, description, or duration changed;
-- return the present/following fields and `null` values required by the receiver API contract.
-
-The inspected NHK application includes a delayed polling fallback when this listener does not
-start, so fixing the semantics removes a real receiver-compatibility workaround rather than an
-abstract completeness issue.
-
-### Atomic broadcast-session reset
-
-An integrator currently has to clear captions, EIT, the broadcast clock, LCT colour,
-application information, queued EMT events, resource state, and the iframe separately. Missing
-one call leaks old-service state into the next application.
-
-Add one generation-changing operation, tentatively `resetBroadcastSession()` or
-`beginBroadcastSession()`, which atomically:
-
-- invalidates the previous runtime and asynchronous completions;
-- clears application/AIT and participation state;
-- clears EIT, EMT backlog, UTC/NPT alarms, and broadcast clock;
-- clears caption tracks/subscriptions;
-- clears LCT colour and application-stage fallback;
-- resets retained carousel resources and CacheEvent listeners;
-- restores the ordinary media plane.
-
-The individual setters may remain for incremental updates within a session.
-
-## P1: compatibility needed after the P0 state model
-
-### Capabilities and playback source
-
-Implement `navigator.capabilities.hasCapability()` as a host-configurable feature matrix.
-Unknown queries must return `false`; advertising a feature requires the corresponding API and
-host bridge to work.
-
-Implement `receiverDevice.streamEvent.sourceIs("onair")`. HonomiTV already knows whether
-the manager was created for live or recorded playback, so the runtime must not guess from a
-carousel path or current URL. TR-B39 recommends this optional API for receivers that execute
-data content during recording playback.
-
-### Broadcast video/audio object controls
-
-Only caption discovery/listener methods are currently implemented. STD-B62 Volume 2 section
-2.2 also defines:
-
-- fullscreen enable, disable, and query;
-- audio mute enable, disable, and query;
-- video/audio source selection and query;
-- caption source selection;
-- caption visibility set/query.
-
-These operations should be added to the media-plane adapter contract. The runtime must not
-pretend they succeeded without changing DPlayer/native media state.
-
-### Receiver API error and callback conformance
-
-Centralize ARIB receiver errors with `INVALID_PARAM_ERR`, `NOT_AUTHORIZED_ERR`,
-`NOT_FOUND_ERR`, `TIMEOUT_ERR`, and `MISC_ERR`. In particular:
-
-- asynchronous callbacks must not run after a synchronous API exception;
-- device-identifier acquisition failure returns `null`, not an empty string;
-- `confirmIPNetwork(destination, confirmType, timeout)` needs argument validation and a
-  host-provided result rather than only returning the configuration flag;
-- synchronous APIs must validate object shapes and integer ranges consistently.
-
-### Storage and network isolation
-
-All broadcast documents currently share the HonomiTV origin. Without an emulated application
-storage boundary, different broadcasters can collide in `_wlocal*`, Ureg, and other
-`localStorage` names. Persistence should be scoped by receiver policy and application identity
-while retaining explicitly receiver-owned regional information.
-
-Application-boundary permission bit 9 must apply to direct storage access as well as the
-`readPersistentArray()` and `writePersistentArray()` compatibility functions.
-
-External traffic should use a typed host request provider. HonomiTV currently rewrites
-`fetch`, XHR, and `sendBeacon` to its same-origin proxy after runtime installation. Moving that
-contract into the receiver host allows permission/boundary checks to precede the proxy and
-avoids competing monkey patches. Subresources, forms, WebSocket/EventSource, redirects, and
-managed-state navigation need an explicit support or rejection policy.
-
-## P2: optional and lower-risk receiver functions
-
-Implement these only after the session state and parser inputs are stable:
-
-- UTC-NPT reference listeners, `getUTCNPT()`, alarms, and cancellation;
-- data-event-ID update listeners;
-- `tuneTo()` through an explicit host callback;
-- viewing/recording scheduling APIs through the receiver EPG/backend;
-- CAS-provider-specific extensions.
-
-The runtime must not expose these through `hasCapability()` until their end-to-end behaviour is
-available.
-
-## Integration event matrix
-
-| Input/state | `tlvdemux`/DPlayer output | `libaribhtml5` action | HonomiTV action |
-| --- | --- | --- | --- |
-| LCT background | layout configuration | Set/reset receiver background plane | Forward event only |
-| MH-AIT | complete table/application states | Update AIT, active application, permissions, listeners | Select lifecycle candidate and pass snapshot |
-| Carousel file | complete resource/revision/delete | Commit VFS mutation and CacheEvent atomically | Forward owned bytes and session generation |
-| MH-EIT p/f | present/following event | Update event object and event-ID listeners | Convert demux time/fields only |
-| General EMT | typed event message | Match registered application listeners | Forward without interpreting broadcaster IDs |
-| Participation EMT `0xF00` | dedicated receiver notification | Evaluate visibility/input state and request a notice | Render notice and transfer control on user action |
-| Liveness source | host playback mode | Implement `sourceIs("onair")` | Supply live versus recorded state |
-| Service/session change | generation change | Atomic receiver-session reset | Call once before replaying the new snapshot |
-
-## Validation plan
-
-Library tests should cover each contract without requiring broadcaster media:
-
-- immediate and change-only event-ID callbacks with structured references;
-- complete AIT snapshots, ordering, version changes, continuation, removal, and KILL;
-- directory CacheEvent matching, atomic update, deletion, and reset;
-- participation notification deduplication and input/visibility combinations;
-- session-reset rejection of late callbacks from the old generation;
-- capability truthfulness and live/recorded `sourceIs()` behaviour;
-- media object state and adapter command failures;
-- application-scoped storage and permission changes.
-
-End-to-end replay should then use:
-
-- NHK BS Premium 4K for ordinary startup, EIT, receiver API, and long-running resource updates;
-- NHK BS8K for LCT/background, external media holes, caption applications, and 8K viewport state;
-- BS Fuji 4K for a non-NHK application entry and storage/path compatibility check;
-- a synthetic descriptor-less `0xF00` EMT fixture for viewer-participation UI, because an
-  archived programme is not guaranteed to contain that notification.
-
-Passing unit tests or a local SDK build is not equivalent to proving the deployed HonomiTV
-bundle, browser composition, remote focus, or multi-hour live behaviour.
-
-## Standards references
-
-- ARIB TR-B39 2.5-E1, Part 1 Volume 3, section 6.2.5 and Appendix 1: viewer-participation
-  corner notification and expected receiver UI.
-- ARIB TR-B39 2.5-E1, Part 1 Volume 3, section 10.7: permissions and receiver extended APIs.
-- ARIB STD-B62 2.2-E1, Volume 2, section 2.2: broadcast video/audio object.
-- ARIB STD-B62 2.2-E1, Volume 2, sections 3.3.7 through 3.3.13: application, capabilities,
-  receiver device, stream events, and cache control.
-- ARIB STD-B60 and STD-B62: MH-AIT/LCT transport state and receiver media/background-plane
-  composition; see the focused lifecycle and media-plane documents in this repository.