libaribhtml5 0.1.0

package/dist/types/broadcast-document.d.ts

@@ -0,0 +1,12 @@
+export type BroadcastDocumentOptions = {
+    /** Current carousel mount, for example /data-broadcast/sh4/. */
+    basePath?: string;
+    /** Worker/server scope containing the mount, for example /data-broadcast/. */
+    scopePath?: string;
+    /** Inline bootstrap inserted at the start of head, including its script tag. */
+    bootstrap?: string;
+};
+export declare function rewriteBroadcastObjectMarkup(source: string): string;
+export declare function prefixBroadcastRootAttributes(source: string, basePath?: string, scopePath?: string): string;
+export declare function prepareBroadcastStylesheet(source: string, options?: BroadcastDocumentOptions): string;
+export declare function prepareBroadcastHtml(source: string, options?: BroadcastDocumentOptions): string;

package/dist/types/broadcast-url.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_BROADCAST_BASE_PATH = "/data-broadcast/";
+export declare function normalizeBroadcastBaseUrl(value: string | URL | undefined, documentUrl: string | URL): URL;
+/**
+ * Derive the current carousel mount from a served document URL.
+ * `/data-broadcast/<mount>/...` maps broadcast-root paths below `<mount>`.
+ */
+export declare function deriveBroadcastRootUrl(documentUrl: string | URL, base: URL): URL;
+/** Map a receiver-visible broadcast path into its isolated HTTP namespace. */
+export declare function resolveBroadcastUrl(value: string | URL, base: URL, broadcastRoot?: URL): URL;

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

@@ -0,0 +1,4 @@
+/** Current demo receiver identifier (48-bit hexadecimal ACAS source value). */
+export declare const DEFAULT_RECEIVER_DEVICE_IDENTIFIER = "4194c4ae4730";
+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/index.d.ts

@@ -0,0 +1,23 @@
+export { AribReceiverHost } from './receiver-host';
+export type { AribCaptionPacket, AribBroadcastClock, 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 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 { DEFAULT_RECEIVER_DEVICE_IDENTIFIER, resolveReceiverDeviceIdentifier, } from './device-identifier';
+export type { ReceiverDeviceIdentifierProvider } from './device-identifier';
+export type { BroadcastResourceCacheEvent, BroadcastResourceCacheListener, BroadcastResourceChange, BroadcastResourceStore, } from './runtime/resources';
+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 { prefixBroadcastRootAttributes, prepareBroadcastHtml, prepareBroadcastStylesheet, rewriteBroadcastObjectMarkup, } from './broadcast-document';
+export type { BroadcastDocumentOptions } from './broadcast-document';
+export { BroadcastVfsSession, ServiceWorkerBroadcastVfs } from './service-worker-vfs';
+export type { BroadcastVfsBackend, BroadcastVfsResource, BroadcastVfsSessionOptions, ServiceWorkerBroadcastVfsOptions, } from './service-worker-vfs';
+export type { AribProgramGuideHandler, AribProgramGuideRequest, AribProgramGuideUnavailableEvent, AribProgramGuideUnavailableHandler, AribProgramGuideUnavailableReason, } from './program-guide';

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

@@ -0,0 +1,79 @@
+export type AribMediaPlaneStackEntry = {
+    tagName: string;
+    id?: string;
+    position: string;
+    zIndex: string;
+    display: string;
+    visibility: string;
+    opacity: number;
+    transform: string;
+};
+export type AribMediaPlaneLayer = {
+    documentOrder: number;
+    stackingPath: AribMediaPlaneStackEntry[];
+};
+export type AribMediaPlane = {
+    slotId: string;
+    visible: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    screenWidth: number;
+    screenHeight: number;
+    videoSource?: string;
+    audioSource?: string;
+    layer: AribMediaPlaneLayer;
+};
+/** @deprecated Use AribMediaPlane. */
+export type AribVideoPlane = AribMediaPlane;
+export type AribMediaPlaneUnmountReason = 'slot-removed' | 'document-unload' | 'application-exit' | 'host-destroy';
+export interface AribMediaPlaneAdapter {
+    /**
+     * `in-object` renders at the actual object position in the application DOM.
+     * `external` uses a host/native plane and receives the object's layer metadata.
+     */
+    readonly renderMode: 'in-object' | 'external';
+    mountMediaPlane(object: HTMLElement, plane: AribMediaPlane): void;
+    updateMediaPlane(object: HTMLElement, plane: AribMediaPlane): void;
+    unmountMediaPlane(reason: AribMediaPlaneUnmountReason): void;
+}
+export type DomObjectMediaPlaneAdapterOptions = {
+    media: HTMLElement;
+    /** Container used by the ordinary player outside data-broadcast mode. */
+    normalPlayerContainer?: HTMLElement;
+    /** @deprecated Use normalPlayerContainer. */
+    parkingContainer?: HTMLElement;
+};
+/**
+ * Browser demo adapter which adopts the media element into the broadcast
+ * object's fallback content. This preserves the application's own DOM order.
+ */
+export declare class DomObjectMediaPlaneAdapter implements AribMediaPlaneAdapter {
+    readonly renderMode: "in-object";
+    private readonly media;
+    private readonly normalPlayerContainer?;
+    private mountedObject;
+    constructor(options: DomObjectMediaPlaneAdapterOptions);
+    mountMediaPlane(object: HTMLElement, plane: AribMediaPlane): void;
+    updateMediaPlane(object: HTMLElement, plane: AribMediaPlane): void;
+    unmountMediaPlane(reason: AribMediaPlaneUnmountReason): void;
+}
+export type BehindIframeMediaPlaneAdapterOptions = {
+    surface: HTMLElement;
+    keepVisible?: boolean;
+};
+/**
+ * Simplified compatibility fallback. It cannot interleave media with elements
+ * inside the application iframe; the complete iframe is always above it.
+ */
+export declare class BehindIframeMediaPlaneAdapter implements AribMediaPlaneAdapter {
+    readonly renderMode: "external";
+    private readonly surface;
+    private readonly keepVisible;
+    constructor(options: BehindIframeMediaPlaneAdapterOptions);
+    mountMediaPlane(_object: HTMLElement, plane: AribMediaPlane): void;
+    updateMediaPlane(_object: HTMLElement, plane: AribMediaPlane): void;
+    unmountMediaPlane(reason: AribMediaPlaneUnmountReason): void;
+    private apply;
+}

package/dist/types/program-guide.d.ts

@@ -0,0 +1,25 @@
+import { type ProgramInfo } from './program-info.js';
+export type AribProgramGuideRequest = {
+    /**
+     * Open the receiver's full program guide, or focus a particular program.
+     * Android/WebView hosts normally map `program-detail` to their native EPG UI.
+     */
+    destination: 'program-guide' | 'program-detail';
+    /** Program identity and metadata supplied by the player/EPG search result. */
+    program?: ProgramInfo;
+    /** Presentation state used by the host; Android distinguishes live and future results. */
+    state?: 'current' | 'future';
+};
+export type AribProgramGuideHandler = (request: AribProgramGuideRequest) => boolean | void | Promise<boolean | void>;
+export type AribProgramGuideUnavailableReason = 'unsupported' | 'rejected' | 'error';
+export type AribProgramGuideUnavailableEvent = {
+    request: AribProgramGuideRequest;
+    reason: AribProgramGuideUnavailableReason;
+    error?: unknown;
+};
+export type AribProgramGuideUnavailableHandler = (event: AribProgramGuideUnavailableEvent) => void;
+/**
+ * Dispatch a receiver-owned EPG transition without coupling the SDK to a
+ * particular Android activity, WebView bridge, or browser player UI.
+ */
+export declare function dispatchProgramGuideRequest(request: AribProgramGuideRequest, handler?: AribProgramGuideHandler, unavailable?: AribProgramGuideUnavailableHandler): Promise<boolean>;

package/dist/types/program-info.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Receiver-owned current/following event information exposed to broadcast apps.
+ * Dates are JavaScript Date objects and durations are milliseconds.
+ */
+export type ProgramInfo = {
+    original_network_id?: number;
+    transport_stream_id?: number;
+    service_id?: number;
+    event_id?: number;
+    name?: string;
+    event_name?: string;
+    start_time?: Date;
+    /** Event duration in milliseconds. */
+    duration?: number;
+    desc?: string;
+    event_text?: string;
+    event_extended_text?: string;
+    running_status?: number;
+    free_ca_mode?: boolean;
+    f_event_id?: number;
+    f_name?: string;
+    f_start_time?: Date;
+    /** Following-event duration in milliseconds. */
+    f_duration?: number;
+    f_desc?: string;
+    [key: string]: unknown;
+};
+/** Validate and detach program information before it crosses the host boundary. */
+export declare function cloneProgramInfo(value: ProgramInfo): ProgramInfo;

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

@@ -0,0 +1,144 @@
+import { 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';
+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';
+export type { AribMediaPlane, AribMediaPlaneAdapter, AribMediaPlaneLayer, AribMediaPlaneStackEntry, AribMediaPlaneUnmountReason, AribVideoPlane, } from './media-plane';
+export type AribCaptionPacket = {
+    componentTag: number;
+    payload?: string;
+    dataType?: string;
+    tmd?: string;
+    data?: string;
+};
+export type AribBroadcastClock = {
+    /** Absolute broadcast time at the anchor, as Unix epoch milliseconds. */
+    epochMilliseconds: number;
+    /** Media timeline value which corresponds to epochMilliseconds. */
+    mediaTimeSeconds?: number;
+    /** Current playback position; enables pause, rate, and seek aware projection. */
+    currentMediaTimeSeconds?: () => number;
+};
+export type AribReceiverLifecycleEvent = {
+    type: 'loading';
+    url: string;
+} | {
+    type: 'installed';
+    url: string;
+    runtimeId: string;
+} | {
+    type: 'navigating';
+    url: string;
+} | {
+    type: 'exited';
+} | {
+    type: 'navigation-blocked';
+    url: string;
+} | {
+    type: 'frame-blocked';
+    url: string;
+} | {
+    type: 'error';
+    message: string;
+};
+export type AribReceiverHostOptions = {
+    iframe: HTMLIFrameElement;
+    viewport: HTMLElement;
+    /** Surface used only by the behind-iframe compatibility adapter. */
+    videoSurface?: HTMLElement;
+    mediaPlaneAdapter?: AribMediaPlaneAdapter;
+    onStatus?: (status: string) => void;
+    /** Machine-readable application/runtime lifecycle; never branch on onStatus text. */
+    onLifecycle?: (event: AribReceiverLifecycleEvent) => void;
+    onUrlChange?: (url: string) => void;
+    onMediaPlane?: (plane: AribMediaPlane) => void;
+    /** @deprecated Use onMediaPlane. */
+    onVideoPlane?: (plane: AribMediaPlane) => void;
+    keepVideoVisible?: boolean;
+    /** Allow broadcaster applications to use HTTP origins outside this host. */
+    allowExternalNetwork?: boolean;
+    /** Same-origin namespace where a Worker or HTTP server exposes carousel data. */
+    broadcastBaseUrl?: string | URL;
+    /** Optional bridge to a Service Worker, Cache Storage, or carousel VFS. */
+    resourceStore?: BroadcastResourceStore;
+    /** Receiver/WebView bridge which opens the native EPG or a program detail page. */
+    onOpenProgramGuide?: AribProgramGuideHandler;
+    /** Override the default browser alert when the receiver cannot open the EPG. */
+    onProgramGuideUnavailable?: AribProgramGuideUnavailableHandler;
+    /** Receiver identity/capabilities exposed to the broadcast application. */
+    systemInformation?: ReceiverSystemInformationOverrides;
+    /** Resolve receiver/CAS identifiers; defaults to the bundled Huggy demo identity. */
+    getDeviceIdentifier?: ReceiverDeviceIdentifierProvider;
+};
+export declare class AribReceiverHost {
+    readonly iframe: HTMLIFrameElement;
+    readonly viewport: HTMLElement;
+    readonly videoSurface?: HTMLElement;
+    private readonly ownerWindow;
+    private readonly origin;
+    private readonly onStatus?;
+    private readonly onLifecycle?;
+    private readonly onUrlChange?;
+    private readonly onMediaPlane?;
+    private readonly onVideoPlane?;
+    private readonly mediaPlaneAdapter?;
+    private readonly runtimeMediaPlaneAdapter?;
+    private readonly allowExternalNetwork;
+    private readonly broadcastBaseUrl;
+    private readonly resourceStore?;
+    private readonly onOpenProgramGuide?;
+    private readonly onProgramGuideUnavailable?;
+    private readonly systemInformation?;
+    private readonly getDeviceIdentifier?;
+    private readonly resizeObserver;
+    private activeRuntimeId;
+    private logicalWidth;
+    private logicalHeight;
+    private captionComponentTags;
+    private programInfo;
+    private broadcastClock;
+    private video;
+    private mediaPlaneEnabled;
+    private applicationExited;
+    private destroyed;
+    constructor(options: AribReceiverHostOptions);
+    installRuntime(target: RuntimeWindow): 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;
+    setCaptionTracks(componentTags: number[]): void;
+    pushCaption(packet: AribCaptionPacket): void;
+    resetCaptions(): void;
+    /** Notify a stored carousel resource after the receiver updates or removes it. */
+    notifyDataResource(path: string, change: BroadcastResourceChange): void;
+    setProgramInfo(value: ProgramInfo): void;
+    /** Clear stale EIT state while changing services or broadcast sessions. */
+    clearProgramInfo(): void;
+    /**
+     * Ask the receiver host to open its EPG. A WebView host can bridge this to a
+     * native activity; an ordinary browser receives a clear unsupported notice.
+     */
+    openProgramGuide(request?: AribProgramGuideRequest): Promise<boolean>;
+    /** Set a free-running broadcast clock from an absolute Unix time. */
+    setBroadcastTime(value: number | Date): void;
+    /** Set an absolute clock anchor, optionally projected from the media timeline. */
+    setBroadcastClock(value: AribBroadcastClock): void;
+    clearBroadcastClock(): void;
+    getBroadcastTime(): number;
+    emitStreamEvent(value: RuntimeEvent): void;
+    destroy(): void;
+    private readonly handleFrameLoad;
+    private readonly reportProgramGuideUnavailable;
+    private readonly handleRuntimeMessage;
+    private applyMediaPlane;
+    private readMediaLayer;
+    private postToRuntime;
+    private invalidateRuntime;
+    private fitBroadcastCanvas;
+    private assertAlive;
+}

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

@@ -0,0 +1,5 @@
+type ClockWindow = Window & typeof globalThis & Record<string, unknown>;
+export type BroadcastNowProvider = () => number;
+/** Override only the zero-argument Date paths used for the receiver clock. */
+export declare function installBroadcastClock(target: ClockWindow, provider?: BroadcastNowProvider): void;
+export {};

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

@@ -0,0 +1,4 @@
+type RuntimeWindow = Window & typeof globalThis & Record<string, unknown>;
+/** Install the sparse receiver font without replacing ordinary Japanese text. */
+export declare function installAribSymbolFont(target: RuntimeWindow): void;
+export {};

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

@@ -0,0 +1,31 @@
+import { type BroadcastNowProvider } from './clock';
+import type { AribMediaPlaneAdapter } from '../media-plane';
+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 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;
+    /** Same-origin namespace where receiver-managed broadcast resources live. */
+    broadcastBaseUrl?: string | URL;
+    /** Optional Worker/cache bridge used by storeDataResource(). */
+    resourceStore?: BroadcastResourceStore;
+    /** Bind the broadcast object to a browser, native, or compositor media plane. */
+    mediaPlaneAdapter?: AribMediaPlaneAdapter;
+    /** Return current broadcast time as Unix epoch milliseconds. */
+    now?: BroadcastNowProvider;
+    /** Receiver identity/capabilities exposed by receiverDevice.getSystemInformation(). */
+    systemInformation?: ReceiverSystemInformationOverrides;
+    /** Resolve receiver/CAS identifiers by receiverDevice identifier kind. */
+    getDeviceIdentifier?: ReceiverDeviceIdentifierProvider;
+};
+export declare function installRuntime(target: RuntimeWindow, options?: RuntimeOptions): void;

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

@@ -0,0 +1,22 @@
+export type BroadcastResourceChange = 'updated' | 'deleted';
+export type BroadcastResourceCacheEvent = 'store_finished' | 'store_failed' | BroadcastResourceChange;
+export type BroadcastResourceStore = {
+    /** Resolve and retain a complete carousel resource. */
+    store: (url: string, options: {
+        signal: AbortSignal;
+    }) => Promise<void>;
+    /** Drop receiver-managed state for a previously retained resource. */
+    release?: (url: string) => void | Promise<void>;
+};
+export type BroadcastResourceCacheListener = (path: string, event: BroadcastResourceCacheEvent) => void;
+type RuntimeWindow = Window & typeof globalThis;
+export type BroadcastResourceCache = {
+    addListener: (path: string, listener: BroadcastResourceCacheListener) => boolean;
+    removeListener: (path: string, listener?: BroadcastResourceCacheListener) => boolean;
+    store: (path: string, listener?: BroadcastResourceCacheListener) => boolean;
+    release: (path?: string) => boolean;
+    change: (path: string, event: BroadcastResourceChange) => void;
+    dispose: () => void;
+};
+export declare function createBroadcastResourceCache(target: RuntimeWindow, resolve: (path: string) => URL, configuredStore?: BroadcastResourceStore): BroadcastResourceCache;
+export {};

package/dist/types/runtime/romsound-markup.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Keep receiver ROM-sound URLs out of the browser's HTML parser. The runtime
+ * resolves the deferred marker after it has installed the custom protocol.
+ */
+export declare function deferRomSoundMarkup(source: string): string;

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

@@ -0,0 +1,4 @@
+export { deferRomSoundMarkup } from './romsound-markup';
+type RuntimeWindow = Window & typeof globalThis & Record<string, unknown>;
+export declare function resolveRomSoundUrl(value: unknown): string | null;
+export declare function installRomSoundProtocol(target: RuntimeWindow): void;

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

@@ -0,0 +1,14 @@
+export type ReceiverSystemIdentity = {
+    browsername: string;
+    browserversion: string;
+    makerid: string;
+    modelname: string;
+};
+export type ReceiverSystemInformation = ReceiverSystemIdentity & {
+    baseurl: string;
+    [key: string]: unknown;
+};
+/** Additional receiver-owned fields. baseurl is always derived from the VFS mount. */
+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;

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

@@ -0,0 +1,66 @@
+export type BroadcastVfsResource = {
+    path: string;
+    contentType?: string;
+    data: Uint8Array | ArrayBuffer;
+};
+export type ServiceWorkerBroadcastVfsOptions = {
+    workerUrl: string | URL;
+    /** Same-origin scope used to expose broadcast files. */
+    baseUrl?: string | URL;
+    /** Compatibility fallback for applications which omit a carousel directory. */
+    uniqueBasenameFallback?: boolean;
+};
+export type BroadcastVfsBackend = {
+    begin(): Promise<void>;
+    put(resource: BroadcastVfsResource): Promise<void>;
+    canRead(path: string): Promise<boolean>;
+};
+export type BroadcastVfsSessionOptions = {
+    /** Report background write failures; ensure() still rejects to its caller. */
+    onError?: (error: unknown) => void;
+    /** Override background scheduling, primarily for embedded hosts and tests. */
+    schedule?: (task: () => void) => void;
+};
+/**
+ * Ordered, recoverable write session above a VFS backend. enqueue() copies
+ * callback-lifetime data synchronously and returns a revision barrier.
+ */
+export declare class BroadcastVfsSession {
+    private readonly backend;
+    private readonly onError?;
+    private readonly scheduleTask;
+    private readonly mirror;
+    private readonly queue;
+    private waiters;
+    private generation;
+    private nextRevision;
+    private completedRevision;
+    private drainScheduled;
+    private ioTail;
+    private sessionReady;
+    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>;
+    private appendIo;
+    private scheduleDrain;
+    private drainOne;
+    private resolveWaiters;
+}
+export declare class ServiceWorkerBroadcastVfs {
+    private readonly workerUrl;
+    private readonly scopeUrl;
+    private readonly uniqueBasenameFallback;
+    private registration;
+    private ready;
+    constructor(options: ServiceWorkerBroadcastVfsOptions);
+    initialize(): Promise<ServiceWorkerRegistration>;
+    begin(): Promise<void>;
+    put(resource: BroadcastVfsResource): Promise<void>;
+    canRead(path: string): Promise<boolean>;
+    reset(): Promise<void>;
+    private request;
+    private waitForActivation;
+}

package/docs/android-program-guide.md

@@ -0,0 +1,127 @@
+# Android の「放送予定」と番組表連携
+
+## Android ファームウェアで確認できた処理
+
+「放送予定」は放送 HTML 内のページではなく、受信機が所有する EPG 機能です。
+SMB400 rev24.24 では次の経路になっています。
+
+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 は次の内蔵ページを開く。
+
+```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 検索結果から番組詳細を開く処理とは
+別のインターフェースです。
+
+## libaribhtml5 のホストインターフェース
+
+プレーヤー側は `AribReceiverHost` の `onOpenProgramGuide` で、WebView または
+ネイティブの番組表へ接続できます。SDK は任意 URL を受け取らず、番組情報だけを渡します。
+
+```ts
+const host = new ARIBHTML5.AribReceiverHost({
+  iframe,
+  viewport,
+  onOpenProgramGuide(request) {
+    const bridge = window.ARIBNative
+    if (!bridge?.openProgramGuide) return false
+
+    bridge.openProgramGuide(JSON.stringify(request))
+  },
+})
+
+await host.openProgramGuide({
+  destination: 'program-detail',
+  state: 'future',
+  program: {
+    original_network_id: 4,
+    tlv_stream_id: 1,
+    service_id: 101,
+    event_id: 42,
+  },
+})
+```
+
+Android 側では JSON 内の識別子を検証したうえで、自アプリの番組詳細 Activity を開きます。
+URL を JSON からそのままロードしてはいけません。
+
+`onOpenProgramGuide` が未設定、`false` を返す、または例外を送出した場合、SDK は
+`false` を返して次の標準メッセージを表示します。
+
+- 番組詳細: `このプレーヤーでは放送予定の番組詳細を表示できません。`
+- 番組表: `このプレーヤーでは番組表を表示できません。`
+
+独自のダイアログや toast を使う場合は `onProgramGuideUnavailable` を指定します。
+
+```ts
+const host = new ARIBHTML5.AribReceiverHost({
+  iframe,
+  viewport,
+  onProgramGuideUnavailable({ request, reason, error }) {
+    showPlayerNotice({ request, reason, error })
+  },
+})
+```