libaribhtml5 0.1.0

package/docs/broadcast-clock.md

@@ -0,0 +1,57 @@
+# 録画再生時の放送時計
+
+データ放送アプリケーションは現在時刻を `new Date()` / `Date.now()` で取得します。
+録画再生でブラウザのシステム時計をそのまま返すと、録画当時ではなく再生日の日時が表示されます。
+
+`AribReceiverHost.setBroadcastClock()` へ、放送時刻とメディア時刻の対応点を渡してください。
+runtime は子 iframe に限って、引数なしの `new Date()`、`Date()`、`Date.now()` をこの時計へ
+置き換えます。`new Date(value)`、`Date.parse()`、`Date.UTC()` は通常の JavaScript と同じです。
+
+## tlvdemux WASM との接続
+
+tlvdemux の `onBroadcastClock` は NTP epoch の絶対時刻と、それに対応するメディア時刻を返します。
+
+```js
+const NTP_UNIX_EPOCH_SECONDS = 2208988800;
+
+onBroadcastClock(clock) {
+  const epochMilliseconds =
+    Number(clock.broadcastTimeValue) * 1000 /
+      Number(clock.broadcastTimeTimescale) -
+    NTP_UNIX_EPOCH_SECONDS * 1000;
+
+  const mediaTimeSeconds =
+    Number(clock.mediaTimeValue) / Number(clock.mediaTimeTimescale);
+
+  host.setBroadcastClock({
+    epochMilliseconds,
+    mediaTimeSeconds,
+    currentMediaTimeSeconds: () => video.currentTime,
+  });
+}
+```
+
+runtime が返す時刻は次の式になります。
+
+```text
+録画内の現在時刻
+= epochMilliseconds
+ + (video.currentTime - mediaTimeSeconds) * 1000
+```
+
+このため、pause 中は時計も停止し、倍速再生では同じ倍率で進み、seek 後は移動先の放送時刻へ
+追従します。新しい入力またはチャンネルへ切り替える時は `host.clearBroadcastClock()` を呼びます。
+
+NTP の値がまだ得られていない場合、`getBroadcastTime()` と子 iframe の Date はシステム時刻へ
+フォールバックします。録画ファイルの更新日やファイル名から日時を推測しないでください。
+
+## 絶対時刻だけを持つ場合
+
+メディア timeline がない入力では、受信した絶対時刻から通常速度で進む時計も設定できます。
+
+```ts
+host.setBroadcastTime(new Date('2026-07-01T12:00:00+09:00'))
+```
+
+この形式は pause、再生倍率、seek には追従しません。録画プレーヤーでは
+`setBroadcastClock()` と `currentMediaTimeSeconds` を使用してください。

package/docs/broadcast-resources-and-fonts.md

@@ -0,0 +1,143 @@
+# Broadcast resources, Worker routing, and fonts
+
+## URL namespace
+
+`AribReceiverHost` mounts receiver paths below `/data-broadcast/` by default:
+
+```ts
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  broadcastBaseUrl: '/data-broadcast/',
+})
+
+host.loadApplication('/sh4/40/001/startup/html/index.html')
+// iframe: /data-broadcast/sh4/40/001/startup/html/index.html
+```
+
+The base must be same-origin and end-user code may change it. The runtime
+reports this stable scope as `receiverDevice.getSystemInformation().baseurl`.
+Broadcaster startup libraries may append a selected mount such as `sh4`
+themselves. Separately, HTML/CSS/runtime URL mapping derives the active mount
+from the current document when resolving root-relative paths such as `/60/...`.
+
+A production server or Service Worker should route only this prefix to its
+carousel/VFS and remove the prefix before looking up the broadcast path:
+
+```text
+/data-broadcast/sh4/60/001/image/logo.png
+                 -> /sh4/60/001/image/logo.png in the carousel
+```
+
+Keeping the prefix makes Worker scope and receiver-owned HTTP resources
+explicit. `subt://` caption resources and `romsound://` receiver sounds are not
+HTTP URLs and must not be rewritten into this namespace.
+
+## Optional browser VFS
+
+The SDK build emits `arib-vfs-sw.js` and exports a matching client. The demuxer
+or carousel owner feeds complete resources; application/context selection stays
+outside the receiver runtime:
+
+```ts
+const backend = new ServiceWorkerBroadcastVfs({
+  workerUrl: '/receiver/arib-vfs-sw.js',
+  baseUrl: '/data-broadcast/',
+})
+const vfs = new BroadcastVfsSession(backend)
+
+await vfs.beginSession()
+const revision = vfs.enqueue({ path, contentType, data })
+await vfs.waitFor(revision)
+await vfs.ensure(entry)
+host.loadApplication(entry)
+```
+
+`enqueue()` copies a callback-lifetime `Uint8Array` synchronously. Writes are
+ordered in the background and its returned revision is an application launch
+barrier. `ensure()` probes the Worker and, if its memory was reclaimed, begins
+a fresh Worker session and replays the page-owned resource mirror. Demuxer
+context selection and the `contextId -> revision` mapping stay in the player.
+
+`ServiceWorkerBroadcastVfs.begin()`, `put()`, and `canRead()` remain available
+as low-level backend operations for hosts which already own these guarantees.
+
+The server which hosts the Worker script must permit the chosen scope. When the
+script itself is outside `/data-broadcast/`, return this response header:
+
+```http
+Service-Worker-Allowed: /data-broadcast/
+```
+
+The main player page may intentionally live outside the Worker scope. VFS
+mutations and probes therefore use direct messages to the scoped active Worker;
+only the data-broadcast iframe's HTTP requests are intercepted. Cache Storage
+preserves the active resource session if the browser reclaims or replaces the
+Worker.
+
+HTML and CSS preparation is shared by the development middleware and Worker.
+`prepareBroadcastHtml()` handles the receiver object marker, ROM-sound deferral,
+root-relative URL mapping, and runtime bootstrap. `prepareBroadcastStylesheet()`
+maps root-relative CSS resources into the same namespace.
+
+## Stored-resource lifecycle
+
+`navigator.receiverDevice.cacheEvent.storeDataResource()` now waits for the
+complete response before dispatching `store_finished`. A failed response emits
+`store_failed`; `releaseDataResource()` aborts an in-flight request. Page exit
+releases every retained resource.
+
+The default implementation fetches from the broadcast document, which lets a
+Service Worker controlling `/data-broadcast/` handle and cache the request. A
+native carousel or another VFS may instead provide `resourceStore`:
+
+```ts
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  resourceStore: {
+    async store(url, { signal }) {
+      await carousel.retain(url, signal)
+    },
+    release(url) {
+      return carousel.release(url)
+    },
+  },
+})
+```
+
+When a carousel module changes, notify the active application. An update is
+downloaded again before its listener receives `updated`; deletion aborts and
+releases it before the listener receives `deleted`.
+
+```ts
+host.notifyDataResource('/sh4/60/001/font/service.woff', 'updated')
+host.notifyDataResource('/sh4/60/001/font/service.woff', 'deleted')
+```
+
+CSS fonts referenced by a d-data page are ordinary broadcast HTTP resources
+and therefore follow the Worker route. A font explicitly retained through
+`storeDataResource()` additionally follows the lifecycle above. TTML
+`subt://n` fonts remain part of the caption data pipeline.
+
+## Receiver symbol font
+
+`src/runtime/fonts/arib-symbols.svg` is the auditable SVG Font source for the
+television-symbol block `U+1F19B..U+1F1AC`, including `U+1F19E SQUARED FOUR K`
+(`🆞`). They are a minimal subset of the OFL-licensed Noto Sans Symbols font
+used by the reference receiver. See `src/runtime/fonts/NOTICE.md` and
+`src/runtime/fonts/OFL.txt`; no commercial font outline is included.
+
+Modern browsers no longer reliably render SVG Fonts, so the same script emits
+`arib-symbols.woff` for runtime use. The runtime registers the sparse font only
+for its 18 code points under `ARIB Symbols` and the ARIB generic family names
+`丸ゴシック`, `太丸ゴシック`, and `角ゴシック`. Ordinary Japanese glyphs continue
+through the page's next fallback font. Dynamic DRCS and broadcaster-delivered
+SVG/WOFF fonts stay separate from this static receiver font.
+
+Regenerate both assets with:
+
+```sh
+nix-shell -p python313Packages.fonttools --run \
+  'python scripts/build-arib-symbol-font.py /path/to/NotoSansSymbols.ttf'
+```

package/docs/media-plane-integration.md

@@ -0,0 +1,227 @@
+# メディアスロットの使い方
+
+## まず結論
+
+通常は次のどれか一つを選びます。
+
+| 用途 | 選ぶもの | できる重なり順 |
+| --- | --- | --- |
+| 通常ブラウザの demo / Web プレーヤー | `DomObjectMediaPlaneAdapter` | アプリ背景 `<` 映像 `<` アプリ UI |
+| ネイティブ Surface / plugin / compositor | 独自 `AribMediaPlaneAdapter` | compositor の能力に依存 |
+| 既存コードを当面維持 | `BehindIframeMediaPlaneAdapter` | 映像 `<` iframe 全体のみ |
+
+caption ページを正しく表示するなら、1 番目または 2 番目が必要です。
+`BehindIframeMediaPlaneAdapter` では実現できません。
+
+## ブラウザへ組み込む最小コード
+
+普通の動画表示領域とデータ放送 iframe を同じ viewport に置きます。
+
+```html
+<div id="viewport">
+  <div id="normal-player">
+    <video id="video" autoplay muted playsinline></video>
+  </div>
+  <iframe id="broadcast" sandbox="allow-scripts allow-same-origin"></iframe>
+</div>
+```
+
+`DomObjectMediaPlaneAdapter` に既存の video と、データ放送を終了した時に video を戻す
+通常プレーヤー container を渡します。
+
+```ts
+import {
+  AribReceiverHost,
+  DomObjectMediaPlaneAdapter,
+  type RuntimeWindow,
+} from 'libaribhtml5'
+
+const iframe = document.querySelector<HTMLIFrameElement>('#broadcast')!
+const viewport = document.querySelector<HTMLElement>('#viewport')!
+const normalPlayer = document.querySelector<HTMLElement>('#normal-player')!
+const video = document.querySelector<HTMLVideoElement>('#video')!
+
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  mediaPlaneAdapter: new DomObjectMediaPlaneAdapter({
+    media: video,
+    normalPlayerContainer: normalPlayer,
+  }),
+})
+
+window.__ARIB_HTML5_INSTALL__ = (child: RuntimeWindow) => {
+  host.installRuntime(child)
+}
+```
+
+データ放送への出入りは次の二つだけです。
+
+```ts
+// データ放送へ入る。video は放送 object の中へ移動する。
+// The receiver path is mounted at /data-broadcast/sh4/... by default.
+host.loadApplication('/sh4/40/001/startup/html/index.html')
+
+// データ放送を終了する。iframe を閉じ、video を通常プレーヤーへ戻して表示する。
+host.exitApplication()
+```
+
+ページ内の「戻る」はアプリケーション内遷移です。`exitApplication()` ではありません。
+テレビ UI の「データ放送終了」操作、チャンネル変更、または
+`applicationManager.destroyApplication()` を受けた時だけ `exitApplication()` を呼びます。
+
+## 実行時に何が起きるか
+
+```text
+通常プレーヤー
+  host.loadApplication()
+        ↓
+runtime が broadcast object を検出
+  mountMediaPlane(object, plane)
+        ↓
+データ放送ページ内で object が移動・非表示
+  updateMediaPlane(object, plane)
+        ↓
+別のデータ放送 document へ遷移
+  unmountMediaPlane('document-unload') → 次ページで mount
+        ↓
+host.exitApplication()
+  unmountMediaPlane('application-exit')
+        ↓
+通常プレーヤーへ video / Surface を戻す
+```
+
+`DomObjectMediaPlaneAdapter` は `document-unload` では video を通常 container へ一時退避して
+非表示にします。`application-exit` の時だけ通常 container を全画面表示します。この区別に
+より、データ放送のページ遷移中に普通のプレーヤー UI が点滅しません。
+
+## 独自 adapter を書く
+
+ネイティブ Surface や compositor を使う場合の最小骨格です。
+
+```ts
+import type {
+  AribMediaPlane,
+  AribMediaPlaneAdapter,
+  AribMediaPlaneUnmountReason,
+} from 'libaribhtml5'
+
+class NativeSurfaceAdapter implements AribMediaPlaneAdapter {
+  readonly renderMode = 'external' as const
+
+  mountMediaPlane(object: HTMLElement, plane: AribMediaPlane): void {
+    nativeSurface.bindBroadcastSource(plane.videoSource, plane.audioSource)
+    this.updateMediaPlane(object, plane)
+  }
+
+  updateMediaPlane(_object: HTMLElement, plane: AribMediaPlane): void {
+    nativeSurface.setVisible(plane.visible)
+    nativeSurface.setLogicalCanvas(plane.screenWidth, plane.screenHeight)
+    nativeSurface.setRect(plane.x, plane.y, plane.width, plane.height)
+    nativeSurface.setApplicationLayer(plane.layer)
+  }
+
+  unmountMediaPlane(reason: AribMediaPlaneUnmountReason): void {
+    if (reason === 'application-exit') {
+      nativeSurface.returnToNormalPlayer()
+    } else if (reason === 'host-destroy') {
+      nativeSurface.release()
+    } else {
+      nativeSurface.hide()
+    }
+  }
+}
+```
+
+`unmountMediaPlane` の reason は次の意味です。
+
+| reason | adapter の動作 |
+| --- | --- |
+| `slot-removed` | decoder は維持し、Surface を隠す |
+| `document-unload` | 次のデータ放送ページに備えて一時退避する |
+| `application-exit` | 通常プレーヤーへ映像を戻して表示する |
+| `host-destroy` | listener、Surface、decoder など所有資源を解放する |
+
+各メソッドは同じ状態で複数回呼ばれても壊れないように実装してください。
+
+## `AribMediaPlane` の読み方
+
+```ts
+type AribMediaPlane = {
+  slotId: string
+  visible: boolean
+  x: number
+  y: number
+  width: number
+  height: number
+  screenWidth: number
+  screenHeight: number
+  videoSource?: string
+  audioSource?: string
+  layer: {
+    documentOrder: number
+    stackingPath: Array<{
+      tagName: string
+      id?: string
+      position: string
+      zIndex: string
+      display: string
+      visibility: string
+      opacity: number
+      transform: string
+    }>
+  }
+}
+```
+
+`x`、`y`、`width`、`height` は iframe の表示 pixel ではなく、アプリケーションの
+論理画布上の CSS pixel です。たとえば `screenWidth=3840`、`x=480` なら左端は 12.5% です。
+
+`stackingPath` は html から object までの祖先を順番に格納します。ネイティブ compositor は
+単一の `zIndex` だけで判断せず、この path と `documentOrder` を使ってアプリケーションとの
+合成方針を決めます。ブラウザ用 `DomObjectMediaPlaneAdapter` では DOM 自身が合成するため、
+この変換は不要です。
+
+## なぜ iframe 背面方式では不足するか
+
+iframe と親 document の間で選べるのは次の順序だけです。
+
+```text
+映像 < iframe 全体
+```
+
+一方、caption ページの要求は次です。
+
+```text
+iframe 内の背景 < 映像 < iframe 内の字幕説明ボタン
+```
+
+親側の z-index を何度変更しても、iframe の内部を二つに分割できません。
+`DomObjectMediaPlaneAdapter` は video を object の fallback content にすることで解決します。
+ネイティブ統合では compositor が同じ役割を担当します。
+
+旧 API の `videoSurface` だけを `AribReceiverHost` に渡すと、互換のため自動的に
+`BehindIframeMediaPlaneAdapter` が選択されます。`attachVideo()` と `keepVideoVisible` も
+旧統合用です。新規コードでは使用しないでください。
+
+## 字幕
+
+通常の放送字幕は video / native Surface と同じプレーヤー側 renderer に置きます。
+したがって media plane の移動、非表示、通常プレーヤーへの復帰へ一緒に追従します。
+
+D Data の字幕コンテンツはアプリケーション DOM です。`setCaptionTracks()` と
+`pushCaption()` で iframe へ渡し、通常の放送字幕として親側へ二重描画しないでください。
+
+---
+
+## English summary
+
+Use `DomObjectMediaPlaneAdapter` for browser integration, implement
+`AribMediaPlaneAdapter` for a native Surface/compositor, and use
+`BehindIframeMediaPlaneAdapter` only as a limited compatibility fallback.
+
+Call `host.loadApplication()` to enter data-broadcast mode. Call
+`host.exitApplication()` to leave it; this produces
+`unmountMediaPlane('application-exit')`, hides the iframe, and lets the adapter
+return video to the ordinary player. A data-broadcast document navigation uses
+`document-unload` instead and must not flash the ordinary player UI.

package/docs/receiver-host-contracts.md

@@ -0,0 +1,92 @@
+# Receiver host contracts
+
+`libaribhtml5` owns the browser-facing receiver API. Stream and product data
+remain owned by the integrating player and are supplied through
+`AribReceiverHost`.
+
+## Program information
+
+Pass decoded present/following event information with `host.setProgramInfo()`.
+`start_time` and `f_start_time` must be JavaScript `Date` objects; `duration`
+and `f_duration` are milliseconds.
+
+```ts
+host.setProgramInfo({
+  original_network_id: event.originalNetworkId,
+  transport_stream_id: event.transportStreamId,
+  service_id: event.serviceId,
+  event_id: event.eventId,
+  event_name: event.title,
+  start_time: new Date(event.startTimeUnixMilliseconds),
+  duration: event.durationSeconds * 1000,
+})
+```
+
+Call `host.clearProgramInfo()` before changing input, service, or demux session.
+Until the host supplies an event, `receiverDevice.getCurrentEventInformation()`
+returns `null`. The SDK does not infer a service or video format from carousel
+directory names such as `sh4` or `sh8`.
+
+EIT parsing, present/following selection, AIT context selection, and synthetic
+demo metadata belong to the integrating player rather than this SDK.
+
+## System information
+
+Receiver identity and capability fields can be injected when the host is
+created. Defaults come from the SDK package metadata.
+
+```ts
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  systemInformation: {
+    makerid: 'receiver-vendor',
+    modelname: 'Living Room Receiver',
+    decoder: 'native',
+  },
+})
+```
+
+`baseurl` is the stable receiver VFS scope, normally `/data-broadcast/`.
+Broadcaster startup libraries may append their selected carousel mount (for
+example `sh4`) themselves. The current document mount is used only when mapping
+root-relative resources such as `/60/...`; it is not included in `baseurl`.
+An injected `baseurl` cannot override the actual VFS scope.
+
+## Device identifiers
+
+The default package combination remains `huggy`, `Huggy ARIB HTML5 Receiver`,
+and the 48-bit identifier `4194c4ae4730`. A product host can resolve identifiers
+by the requested receiver API kind without changing the runtime:
+
+```ts
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  getDeviceIdentifier: async kind => nativeReceiver.identifierFor(kind),
+})
+```
+
+Returning `null` means that identifier kind is unavailable. Provider failures
+are isolated and reported to the application as an empty identifier.
+
+## Runtime lifecycle
+
+`onStatus` is presentation text and may be localized. State machines must use
+the typed `onLifecycle` callback instead:
+
+```ts
+const host = new AribReceiverHost({
+  iframe,
+  viewport,
+  onStatus: text => statusLabel.textContent = text,
+  onLifecycle(event) {
+    if (event.type === 'installed') clearApplicationTimeout()
+    if (event.type === 'navigating') armApplicationTimeout()
+    if (event.type === 'error') reportRuntimeError(event.message)
+  },
+})
+```
+
+Lifecycle event types are `loading`, `installed`, `navigating`, `exited`,
+`navigation-blocked`, `frame-blocked`, and `error`.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "libaribhtml5",
+  "version": "0.1.0",
+  "description": "Browser runtime and receiver host for ARIB HTML5 data broadcasting",
+  "keywords": [
+    "arib",
+    "html5",
+    "data-broadcasting",
+    "bml",
+    "isdb",
+    "broadcast"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "huggy",
+    "url": "https://huggy.moe",
+    "email": "libaribhtml5@huggy.moe"
+  },
+  "aribReceiver": {
+    "modelName": "Huggy ARIB HTML5 Receiver"
+  },
+  "type": "module",
+  "main": "./dist/sdk/libaribhtml5.mjs",
+  "module": "./dist/sdk/libaribhtml5.mjs",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "./dist/sdk/libaribhtml5.js",
+  "jsdelivr": "./dist/sdk/libaribhtml5.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/sdk/libaribhtml5.mjs",
+      "default": "./dist/sdk/libaribhtml5.mjs"
+    },
+    "./iife": "./dist/sdk/libaribhtml5.js",
+    "./arib-vfs-sw.js": "./dist/sdk/arib-vfs-sw.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/sdk",
+    "dist/types",
+    "docs",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makeding/libaribhtml5.git"
+  },
+  "bugs": {
+    "url": "https://github.com/makeding/libaribhtml5/issues"
+  },
+  "homepage": "https://github.com/makeding/libaribhtml5#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vite": "^7.0.0"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "test": "node --experimental-strip-types scripts/test-runtime-contracts.mjs && node --experimental-strip-types scripts/test-vfs-worker.mjs",
+    "build": "tsc --noEmit && vite build && vite build --config vite.sdk.config.mjs && vite build --config vite.worker.config.mjs",
+    "build:sdk": "tsc --noEmit && vite build --config vite.sdk.config.mjs && vite build --config vite.worker.config.mjs && npm run build:types",
+    "build:types": "tsc -p tsconfig.build.json && node scripts/rewrite-declaration-imports.mjs",
+    "preview": "vite preview --host 127.0.0.1"
+  }
+}