@wcstack/picture-in-picture 1.16.0

package/README.ja.md

@@ -0,0 +1,215 @@
+# @wcstack/picture-in-picture
+
+`@wcstack/picture-in-picture` は wcstack エコシステム向けのヘッドレスな Picture-in-Picture コンポーネントです。
+
+視覚的な UI ウィジェットではありません。
+`@wcstack/fullscreen` が要素の全画面状態をリアクティブな state に変えるのと同じように、`<video>` 要素の Picture-in-Picture 状態をリアクティブな state に変える **非同期プリミティブノード** です。
+
+`@wcstack/state` と組み合わせると、`<wcs-pip>` はパス契約で直接バインドできます:
+
+- **入力サーフェス**: `target` — どの `<video>` 要素を操作するか
+- **出力 state サーフェス**: `active`、`error`
+- **コマンドサーフェス**: `requestPictureInPicture()`、`exitPictureInPicture()`
+
+これにより、`document.pictureInPictureElement` を手動でポーリングしたりレイアウトを気にしたりせずに、「ポップアウト」ボタンを HTML 上で宣言的に表現できます。
+
+`@wcstack/picture-in-picture` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います:
+
+- **Core**（`PipCore`）が Picture-in-Picture API を解決し（呼び出し時、非キャッシュ）、対象 `<video>` の `enterpictureinpicture`/`leavepictureinpicture` を購読し、`active`/`error` を追跡
+- **Shell**（`<wcs-pip>`）が DOM からどの `<video>` を操作するか解決し、display・ライフサイクル・宣言的コマンドを管理
+- **Binding Contract**（`static wcBindable`）が観測可能な `properties`、書き込み可能な `inputs`、呼び出し可能な `commands` を宣言
+
+## なぜ存在するか — そして自分自身を操作しない理由
+
+`@wcstack/fullscreen` と同様、この Shell は非表示の**制御タグ**です。自分自身を Picture-in-Picture 化するのではなく、`target` で解決した要素に対して Picture-in-Picture API を実行します。典型的なユースケースは動画プレイヤーの「ポップアウト」ボタンです。
+
+`@wcstack/picture-in-picture` は `target` 解決のアーキタイプを `@wcstack/fullscreen` / `@wcstack/intersection` と共有します（詳細な根拠は `docs/fullscreen-tag-design.md` §1 参照）— 同じ3モード `target` 解決、同じ `_safeQuery` never-throw ラッパー、同じ Core 単位1つの `_gen` 世代ガード、同じシンプルな `error` フィールド（permission のような4値state は無し、`docs/fullscreen-tag-design.md` §8 参照）。
+
+## スコープ: 古典的な Picture-in-Picture API のみ（`<video>` 限定）
+
+「Picture-in-Picture」という名前を持つ、互いに無関係な2つのWeb Platform提案が存在します:
+
+- **古典的な Picture-in-Picture API**（`HTMLVideoElement.requestPictureInPicture()`）— `<video>` 限定で、広くサポートされています。**`<wcs-pip>` が包むのはこちらです。**
+- **Document Picture-in-Picture API**（`documentPictureInPicture.requestWindow()`）— 動画に限らず任意のDOMサブツリーを別の常に最前面のウィンドウに浮かせられます。API 形状（別の `Window` を取得してそこへ DOM を移動する）が、本ノードが `fullscreen`/`pointer-lock` と共有する「target を解決し、document レベルの状態を監視する」というアーキタイプと根本的に異なります。
+
+**`<wcs-pip>` は古典的な `<video>` 限定 API を対象とします。Document Picture-in-Picture API は v1 のスコープ外です**（`docs/picture-in-picture-tag-design.md` §4 参照）。将来的に別ノード（例: `<wcs-doc-pip>`）として切り出される可能性があります。
+
+### `target` は `<video>` 要素に解決されなければならない
+
+Fullscreen（任意の `Element` がサポート）と異なり、Picture-in-Picture は `HTMLVideoElement` にのみ定義されています。`target` が `<video>` 以外の要素に解決された場合、`<wcs-pip>` はこれを未解決の target と同じ扱いにします。`requestPictureInPicture()` は例外を投げず、即座に `error` を `{ message: "target must be a <video> element." }` にセットして resolve します。
+
+## インストール
+
+```bash
+npm install @wcstack/picture-in-picture
+```
+
+## クイックスタート
+
+### 1. 動画プレイヤーの「ポップアウト」ボタン
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/picture-in-picture/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["popOut", "backToPage"],
+      pipActive: false,
+    };
+  </script>
+</wcs-state>
+
+<video id="player" src="/movie.mp4" controls></video>
+
+<wcs-pip target="#player" data-wcs="active: pipActive; command.requestPictureInPicture: $command.popOut; command.exitPictureInPicture: $command.backToPage"></wcs-pip>
+
+<button data-wcs="onclick: $command.popOut">ポップアウト</button>
+<button data-wcs="onclick: $command.backToPage; hidden: pipActive|not">ページに戻す</button>
+```
+
+どちらのボタンも `<wcs-pip>` を直接触りません。クリックがコマンドトークンを emit し、`<wcs-pip>` は `command.requestPictureInPicture: $command.popOut` / `command.exitPictureInPicture: $command.backToPage` でそれらのトークンを購読します（[command-token プロトコル](../state/) — コマンドメソッドを持つ要素が emit 側ではなく *購読側* です）。バインドする state パスは事前に必ず宣言する必要があります — ここでは `pipActive: false`。未宣言パスへのバインドは初期化時に throw します。`data-wcs` パスでの否定は先頭 `!` ではなく `|not` フィルタで行います（`pipActive|not`）— パスは前置演算子をサポートしません。
+
+### 2. `<video>` を子要素としてラップする（セレクタ不要）
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      pipActive: false,
+    };
+  </script>
+</wcs-state>
+
+<wcs-pip data-wcs="active: pipActive">
+  <video src="/movie.mp4" controls></video>
+</wcs-pip>
+```
+
+### 3. 失敗を報告する（gesture 制約による reject 等）
+
+`error` には専用イベントが無く `data-wcs` でバインドできません（下記「出力 state」参照）— コマンドの promise が解決した後に命令的に読みます:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["popOut"],
+      pipActive: false,
+    };
+  </script>
+</wcs-state>
+
+<wcs-pip target="#player" data-wcs="active: pipActive; command.requestPictureInPicture: $command.popOut"></wcs-pip>
+<button data-wcs="onclick: $command.popOut">ポップアウト</button>
+```
+
+```js
+const pip = document.querySelector("wcs-pip");
+await pip.requestPictureInPicture();
+if (pip.error) {
+  console.log("Picture-in-Picture に入れませんでした:", pip.error);
+}
+```
+
+## `target` 属性が操作対象を決める
+
+| `target`          | 操作対象               | `display`   | ユースケース                |
+|-------------------|-------------------------|-------------|------------------------------|
+| 省略              | 最初の子要素             | `contents`  | `<video>` をインラインでラップ |
+| `"#player"` / セレクタ | マッチした要素      | `none`      | 独立した制御タグ             |
+| `"self"`          | 自分自身                 | `block`     | **常に失敗する** — `<wcs-pip>` 自身が `<video>` になることはないため、`requestPictureInPicture()` は必ず error になる（上記「`target` は `<video>` 要素に解決されなければならない」参照） |
+
+`display:contents` は `<video>` 子要素をラップしても自身のボックスを注入しないことを意味します。明示的な `target="self"` のみがボックスを持ちます。`packages/intersection` の `_resolveTarget()` をそのまま流用しています（`docs/fullscreen-tag-design.md` §1）。
+
+`@wcstack/fullscreen`（任意の `Element` を全画面化できるため `target="self"` がラッパー自体を全画面化する正当な手段になる）と異なり、本ノードでの `target="self"` は構造的な行き止まりです: `<wcs-pip>` 自身の `tagName` が `VIDEO` になることは無いため、常に `<video>` 限定チェックに失敗し、あらゆる `requestPictureInPicture()` 呼び出しが `error` に帰結します。それでもこのモード自体は、共有する3モード `_resolveTarget()` アーキタイプとの整合のため不正な属性値として拒否はされず受理され続けますが、実用上意味を持つことはありません。
+
+## 属性
+
+| 属性     | 型     | デフォルト   | 説明 |
+|----------|--------|--------------|------|
+| `target` | string | *(省略)*     | どの `<video>` を操作するか: 省略 → 最初の子要素、セレクタ → マッチした要素、`self` → 自分自身（常に失敗する — 上記参照）。 |
+
+## 出力 state
+
+| プロパティ | 型        | イベント          | 説明 |
+|------------|-----------|-------------------|------|
+| `active`   | `boolean` | `wcs-pip:change`  | 解決済みの `<video>` target が現在 document の Picture-in-Picture 要素かどうか。 |
+| `error`    | `any`     | *(無し — 単なる getter、data-wcs でバインド不可)* | 直近のコマンド失敗（不正なタグ・非対応API・gesture 制約による reject）、または `null`。 |
+
+`active` は、`enterpictureinpicture`/`leavepictureinpicture` が**その対象要素自身に**発火するたびに、`document.pictureInPictureElement` と解決済み `<video>` target を比較して導出されます（`document` レベルのイベントではありません — 詳細は下記「イベント購読」参照）。
+
+## コマンド
+
+| コマンド                      | 説明 |
+|-------------------------------|------|
+| `requestPictureInPicture()`   | `target` の `<video>` を解決し、Picture-in-Picture を要求する。例外を投げない: `<video>` でない target・非対応API・gesture 制約による reject（`NotAllowedError`）は全て `error` に集約される。 |
+| `exitPictureInPicture()`      | Picture-in-Picture を終了する。何も PiP 中でなければ**silent no-op**（`@wcstack/fullscreen` の `exitFullscreen()` と同型 — `docs/fullscreen-tag-design.md` §7 参照）。 |
+
+### ユーザージェスチャー要件
+
+`requestPictureInPicture()` はユーザージェスチャー内（例: クリックハンドラ）から呼び出す必要があります。これはブラウザレベルの要件であり `<wcs-pip>` では回避できません — Fullscreen における同じ制約は `docs/fullscreen-tag-design.md` §3 を参照してください。command-token プロトコルでクリックへ直接配線することを推奨します（`<wcs-pip>` 側で `command.requestPictureInPicture: $command.<token>`、ボタン側で `onclick: $command.<token>` — 上記クイックスタート参照）。その際、*トリガーとなるイベント自体*が本物のユーザージェスチャーであることを確認してください。
+
+`setTimeout` の中や `.then()` チェーンの奥から呼び出すと gesture 文脈が失われ、ブラウザがリクエストを拒否します — これは wcstack とは無関係な制約であり、このレイヤーでは修正できません。
+
+## イベント購読先: `document` ではなく `<video>` 要素自身
+
+Fullscreen の `fullscreenchange`（`document` に発火）と異なり、Picture-in-Picture の `enterpictureinpicture`/`leavepictureinpicture` は**`<video>` 要素自身に**発火します。`PipCore` はこれらのリスナーを解決済みの `<video>` に直接張り、`target` が再解決されるたび（例えば `target` 属性の変更）に旧要素から外し新要素に張り替えます。
+
+これにより、複数の `<wcs-pip>` インスタンスは自然に自己フィルタされます。各インスタンスは自分の `<video>` target のイベントのみを受け取るため、あるインスタンスが Picture-in-Picture に入っても他のインスタンスの `active` が誤って `true` になることはありません（`docs/picture-in-picture-tag-design.md` §5 参照）。
+
+## Binding Contract（`wcBindable`）
+
+Core と Shell の両方が [wc-bindable](https://github.com/csbc-dev) プロトコルを宣言します。
+
+```js
+// PipCore（ヘッドレス）
+PipCore.wcBindable = {
+  protocol: "wc-bindable",
+  version: 1,
+  properties: [
+    { name: "active", event: "wcs-pip:change", getter: (e) => e.detail.active },
+  ],
+  commands: [
+    { name: "requestPictureInPicture", async: true },
+    { name: "exitPictureInPicture", async: true },
+  ],
+};
+```
+
+Shell（`<wcs-pip>`）は Core の `properties`/`commands` を継承し、`target` 入力を宣言します。
+
+## Core 単体での利用
+
+`PipCore` はフレームワーク非依存です。操作したい `<video>` 要素を解決して渡します（Shell はこの解決を代わりに行います）:
+
+```js
+import { PipCore } from "@wcstack/picture-in-picture";
+
+const core = new PipCore();
+core.addEventListener("wcs-pip:change", (e) => {
+  console.log(e.detail.active);
+});
+
+const video = document.querySelector("video");
+core.observe(video);            // enterpictureinpicture/leavepictureinpicture を購読
+await core.requestPictureInPicture(video);
+
+// 後で
+await core.exitPictureInPicture();
+core.dispose();                 // リスナーを外す
+```
+
+## 注意・制限
+
+- **`<video>` 限定。** `target` は `HTMLVideoElement` に解決される必要があります。それ以外の要素は未解決扱いになり、`error` に `{ message: "target must be a <video> element." }` がセットされます（例外は投げません）。
+- **Document Picture-in-Picture API はスコープ外。** 上記「スコープ」参照。
+- **例外を投げない。** 非対応環境・不正なタグの target・gesture 制約による reject は全て `error` に集約されます。
+- **`document.pictureInPictureElement` は document 全体で単一の値**です（`document.fullscreenElement` と同様）。複数の `<wcs-pip>` インスタンスは、自分の `<video>` target の `enterpictureinpicture`/`leavepictureinpicture` リスナーによって自己フィルタされます — 上記「イベント購読先」参照。ただし非対称な点に注意してください: `exitPictureInPicture()` はインスタンス単位にスコープされて**いません** — document全体に作用する `document.exitPictureInPicture()` を呼ぶため、どのインスタンスから呼んでも、現在 Picture-in-Picture 中の `<video>`（別インスタンスの `target` が PiP 化したものであっても）を終了させます（silent no-op の判定も同様に document 全体の「何かが PiP 中か」であり、「自分の target が PiP 中か」ではありません）。これはプラットフォーム API 自体の挙動、および `@wcstack/fullscreen` の `exitFullscreen()`（`docs/fullscreen-tag-design.md` §7 の「スコープの注意（§2.1との非対称）」、および `packages/fullscreen/README.ja.md` の「複数インスタンス」節参照）をそのまま反映したものです。
+- **`desired`/`actual` の二相 state は無し** — 本ノードは単一の `active` boolean と `error` のみを公開し、`permission` より単純な `@wcstack/fullscreen` の state モデルと同型です。
+- **`error` には専用イベントが無く、`data-wcs` でバインドできません。** `@wcstack/fullscreen` と同様、`error` は単なる getter であり、`wcs-pip:error` のような専用イベントを持たず、`static wcBindable.properties` にも宣言されていません — バインディングシステムには購読対象が無いため、リアクティブに観測できません。コマンドの promise が解決した後に `element.error` を命令的に読んでください（例: `await el.requestPictureInPicture(); if (el.error) { ... }`）。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,215 @@
+# @wcstack/picture-in-picture
+
+`@wcstack/picture-in-picture` is a headless Picture-in-Picture component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns a `<video>` element's Picture-in-Picture state into reactive state — the same way `@wcstack/fullscreen` turns an element's fullscreen state into reactive state.
+
+With `@wcstack/state`, `<wcs-pip>` can be bound directly through path contracts:
+
+- **input surface**: `target` — which `<video>` element to control
+- **output state surface**: `active`, `error`
+- **command surface**: `requestPictureInPicture()`, `exitPictureInPicture()`
+
+This means a "pop out" video button — with no live-region layout thrashing, no manual `document.pictureInPictureElement` polling — can be expressed declaratively in HTML.
+
+`@wcstack/picture-in-picture` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`PipCore`) resolves the Picture-in-Picture API (call-time, never cached), subscribes to `enterpictureinpicture`/`leavepictureinpicture` on the target `<video>`, and tracks `active`/`error`
+- **Shell** (`<wcs-pip>`) resolves *which* `<video>` element to control from the DOM, manages display, lifecycle, and declarative commands
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`
+
+## Why this exists — and why it doesn't operate on itself
+
+Like `@wcstack/fullscreen`, this Shell is a non-visible **control tag**: it does not put itself into Picture-in-Picture. It resolves a `target` element and invokes the Picture-in-Picture API against *that* element. The typical use case is a video player's "pop out" button.
+
+`@wcstack/picture-in-picture` shares its `target`-resolution archetype with `@wcstack/fullscreen` and `@wcstack/intersection` (see `docs/fullscreen-tag-design.md` §1 for the detailed rationale) — the same 3-mode `target` resolution, the same `_safeQuery` never-throw wrapper, the same single Core-level `_gen` generation guard, and the same simple `error` field (no permission-style 4-value state; see `docs/fullscreen-tag-design.md` §8).
+
+## Scope: classic Picture-in-Picture API only (`<video>`-only)
+
+There are two unrelated web platform proposals under the "Picture-in-Picture" name:
+
+- **The classic Picture-in-Picture API** (`HTMLVideoElement.requestPictureInPicture()`) — `<video>`-only, broadly supported. **This is what `<wcs-pip>` wraps.**
+- **The Document Picture-in-Picture API** (`documentPictureInPicture.requestWindow()`) — lets you float an arbitrary DOM subtree in a separate always-on-top window, not limited to video. Its API shape (acquiring a separate `Window` and moving DOM into it) is fundamentally different from the "resolve a target, watch a document-level state" archetype this node shares with `fullscreen`/`pointer-lock`.
+
+**`<wcs-pip>` targets the classic, `<video>`-only API. The Document Picture-in-Picture API is out of scope for v1** — see `docs/picture-in-picture-tag-design.md` §4. It may become a separate node (e.g. `<wcs-doc-pip>`) in the future.
+
+### The `target` MUST resolve to a `<video>` element
+
+Unlike Fullscreen (which any `Element` supports), Picture-in-Picture is only defined on `HTMLVideoElement`. If `target` resolves to a non-`<video>` element, `<wcs-pip>` treats it the same as an unresolved target: `requestPictureInPicture()` never throws — it immediately sets `error` to `{ message: "target must be a <video> element." }` and resolves.
+
+## Install
+
+```bash
+npm install @wcstack/picture-in-picture
+```
+
+## Quick Start
+
+### 1. A "pop out" button for a video player
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/picture-in-picture/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["popOut", "backToPage"],
+      pipActive: false,
+    };
+  </script>
+</wcs-state>
+
+<video id="player" src="/movie.mp4" controls></video>
+
+<wcs-pip target="#player" data-wcs="active: pipActive; command.requestPictureInPicture: $command.popOut; command.exitPictureInPicture: $command.backToPage"></wcs-pip>
+
+<button data-wcs="onclick: $command.popOut">Pop out</button>
+<button data-wcs="onclick: $command.backToPage; hidden: pipActive|not">Back to page</button>
+```
+
+Neither button touches `<wcs-pip>` directly: each click emits a command token, and `<wcs-pip>` subscribes to those tokens via `command.requestPictureInPicture: $command.popOut` / `command.exitPictureInPicture: $command.backToPage` (the [command-token protocol](../state/) — the element with the command method is the *subscriber*, not the emitter). Every bound state path must be declared up front — `pipActive: false` here; binding an undeclared path throws at initialization. Negation in a `data-wcs` path is done with the `|not` filter (`pipActive|not`), not a leading `!` — paths do not support prefix operators.
+
+### 2. Wrapping the `<video>` as a child (no selector needed)
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      pipActive: false,
+    };
+  </script>
+</wcs-state>
+
+<wcs-pip data-wcs="active: pipActive">
+  <video src="/movie.mp4" controls></video>
+</wcs-pip>
+```
+
+### 3. Reporting failures (e.g. gesture-context rejection)
+
+`error` has no dedicated event and is not `data-wcs` bindable (see "Output state" below) — read it imperatively after the command's promise settles:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["popOut"],
+      pipActive: false,
+    };
+  </script>
+</wcs-state>
+
+<wcs-pip target="#player" data-wcs="active: pipActive; command.requestPictureInPicture: $command.popOut"></wcs-pip>
+<button data-wcs="onclick: $command.popOut">Pop out</button>
+```
+
+```js
+const pip = document.querySelector("wcs-pip");
+await pip.requestPictureInPicture();
+if (pip.error) {
+  console.log("Could not enter Picture-in-Picture:", pip.error);
+}
+```
+
+## The `target` attribute decides what is controlled
+
+| `target`        | controls               | `display`   | use case                |
+|-----------------|-------------------------|-------------|--------------------------|
+| omitted         | first element child     | `contents`  | wrap a `<video>` inline  |
+| `"#player"` / sel | the matched element   | `none`      | separate control tag     |
+| `"self"`        | the element itself       | `block`     | **always fails** — `<wcs-pip>` itself can never be a `<video>`, so `requestPictureInPicture()` immediately errors (see "The `target` MUST resolve to a `<video>` element" above) |
+
+`display:contents` means wrapping a `<video>` child injects no box of its own. Only the explicit `target="self"` sentinel takes a box. See `packages/intersection`'s `_resolveTarget()` — this Shell reuses it verbatim (docs/fullscreen-tag-design.md §1).
+
+Unlike `@wcstack/fullscreen` (where `target="self"` is a legitimate way to fullscreen the wrapper itself, since any `Element` can be fullscreened), `target="self"` here is a structural dead end: `<wcs-pip>`'s own `tagName` is never `VIDEO`, so it always fails the `<video>`-only check and every `requestPictureInPicture()` call resolves into `error`. The mode is still accepted rather than rejected as an invalid attribute value — for parity with the shared 3-mode `_resolveTarget()` archetype — it just never does anything useful.
+
+## Attributes
+
+| Attribute | Type   | Default     | Description |
+|-----------|--------|-------------|--------------|
+| `target`  | string | *(omitted)* | Which `<video>` to control: omitted → first child, a selector → that element, `self` → this element (always fails — see above). |
+
+## Output state
+
+| Property | Type      | Event            | Description |
+|----------|-----------|------------------|--------------|
+| `active` | `boolean` | `wcs-pip:change` | Whether the resolved `<video>` target is currently the document's Picture-in-Picture element. |
+| `error`  | `any`     | *(none — plain getter, not data-wcs bindable)* | The most recent command failure (wrong tag, unsupported API, gesture-context rejection), or `null`. |
+
+`active` is derived from comparing `document.pictureInPictureElement` against the resolved `<video>` target whenever `enterpictureinpicture`/`leavepictureinpicture` fires **on that target element** — not from a `document`-level event (see "Event subscription" below).
+
+## Commands
+
+| Command                      | Description |
+|-------------------------------|--------------|
+| `requestPictureInPicture()`   | Resolve the `target` `<video>` and request Picture-in-Picture for it. Never throws: a non-`<video>` target, an unsupported API, or a gesture-context rejection (`NotAllowedError`) all funnel into `error`. |
+| `exitPictureInPicture()`      | Exit Picture-in-Picture. **Silent no-op** if nothing is currently in Picture-in-Picture (mirrors `@wcstack/fullscreen`'s `exitFullscreen()` — see `docs/fullscreen-tag-design.md` §7). |
+
+### User gesture requirement
+
+`requestPictureInPicture()` must be called from within a user gesture (e.g. a click handler). This is a browser-level requirement `<wcs-pip>` cannot work around — see `docs/fullscreen-tag-design.md` §3 for the same constraint on Fullscreen. Prefer wiring the command directly to a click via the command-token protocol (`command.requestPictureInPicture: $command.<token>` on `<wcs-pip>`, emitted by a button's `onclick: $command.<token>` — see the Quick Start above), making sure the *triggering* event itself is a genuine user gesture.
+
+Calling it from inside a `setTimeout` or deep inside a `.then()` chain loses the gesture context and the browser will reject the request — this is unrelated to wcstack and cannot be fixed at this layer.
+
+## Event subscription: the `<video>` element itself, not `document`
+
+Unlike Fullscreen's `fullscreenchange` (which fires on `document`), Picture-in-Picture's `enterpictureinpicture`/`leavepictureinpicture` events fire **on the `<video>` element itself**. `PipCore` attaches these listeners directly to the resolved `<video>`, and re-wires them (detaching from the old target, attaching to the new one) whenever `target` is re-resolved (e.g. the `target` attribute changes).
+
+This also means multiple `<wcs-pip>` instances naturally self-filter: each instance only hears events from its own `<video>` target, so one instance entering Picture-in-Picture never flips another instance's `active` to `true` (see `docs/picture-in-picture-tag-design.md` §5).
+
+## Binding Contract (`wcBindable`)
+
+Both the Core and the Shell declare the [wc-bindable](https://github.com/csbc-dev) protocol.
+
+```js
+// PipCore (headless)
+PipCore.wcBindable = {
+  protocol: "wc-bindable",
+  version: 1,
+  properties: [
+    { name: "active", event: "wcs-pip:change", getter: (e) => e.detail.active },
+  ],
+  commands: [
+    { name: "requestPictureInPicture", async: true },
+    { name: "exitPictureInPicture", async: true },
+  ],
+};
+```
+
+The Shell (`<wcs-pip>`) inherits the Core's `properties`/`commands` and declares the `target` input.
+
+## Using the Core standalone
+
+`PipCore` is framework-agnostic. You resolve and hand it the `<video>` element to control (the Shell does this resolution for you):
+
+```js
+import { PipCore } from "@wcstack/picture-in-picture";
+
+const core = new PipCore();
+core.addEventListener("wcs-pip:change", (e) => {
+  console.log(e.detail.active);
+});
+
+const video = document.querySelector("video");
+core.observe(video);            // subscribe to enterpictureinpicture/leavepictureinpicture
+await core.requestPictureInPicture(video);
+
+// later
+await core.exitPictureInPicture();
+core.dispose();                 // detach listeners
+```
+
+## Notes & limitations
+
+- **`<video>`-only.** `target` must resolve to an `HTMLVideoElement`. Any other element is treated as unresolved: `error` is set to `{ message: "target must be a <video> element." }`, never throws.
+- **Document Picture-in-Picture API is out of scope.** See "Scope" above.
+- **Never throws.** Unsupported environments, wrong-tag targets, and gesture-context rejections are all funneled into `error`.
+- **`document.pictureInPictureElement` is a single document-wide value**, like `document.fullscreenElement`. Multiple `<wcs-pip>` instances self-filter via their own `<video>` target's `enterpictureinpicture`/`leavepictureinpicture` listeners — see "Event subscription" above. Note the asymmetry, though: `exitPictureInPicture()` is **not** scoped per instance — it calls the document-global `document.exitPictureInPicture()`, so invoking it on any instance exits whatever `<video>` is currently in Picture-in-Picture, even one entered via another instance's `target` (its silent no-op check is likewise document-wide: "is anything in Picture-in-Picture", not "is *my* target in Picture-in-Picture"). This mirrors the platform API itself and `@wcstack/fullscreen`'s `exitFullscreen()` (see `docs/fullscreen-tag-design.md` §7's "scope note" alongside §2.1, and the "Multiple instances" bullet in `packages/fullscreen/README.md`).
+- **No `desired`/`actual` two-phase state** — this node exposes a single `active` boolean plus `error`, mirroring `@wcstack/fullscreen`'s simpler-than-`permission` state model.
+- **`error` has no dedicated event, and is not `data-wcs` bindable.** Like `@wcstack/fullscreen`, `error` is a plain getter with no `wcs-pip:error` event of its own, and it is not declared in `static wcBindable.properties` — a binding system has nothing to subscribe to and cannot observe it reactively. Read `element.error` imperatively after a command's promise settles (e.g. `await el.requestPictureInPicture(); if (el.error) { ... }`).
+
+## License
+
+MIT

package/dist/auto.js

@@ -0,0 +1,3 @@
+import { bootstrapPip } from "./index.esm.js";
+
+bootstrapPip();

package/dist/auto.min.js

@@ -0,0 +1 @@
+import{bootstrapPip as o}from"./index.esm.min.js";o();

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+interface IWcBindableProperty {
+    readonly name: string;
+    readonly event: string;
+    readonly getter?: (event: Event) => any;
+}
+interface IWcBindableInput {
+    readonly name: string;
+    readonly attribute?: string;
+}
+interface IWcBindableCommand {
+    readonly name: string;
+    readonly async?: boolean;
+}
+interface IWcBindable {
+    readonly protocol: "wc-bindable";
+    readonly version: 1;
+    readonly properties: readonly IWcBindableProperty[];
+    readonly inputs?: readonly IWcBindableInput[];
+    readonly commands?: readonly IWcBindableCommand[];
+}
+
+interface ITagNames {
+    readonly pip: string;
+}
+interface IWritableTagNames {
+    pip?: string;
+}
+interface IConfig {
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    tagNames?: IWritableTagNames;
+}
+
+/**
+ * Value types for PipCore (headless) — the Core's readable value surface.
+ * Note that only `active` is *observable* (declared in
+ * `wcBindable.properties` with a change event); `error` is an
+ * imperative-read-only getter with no event of its own — a wc-bindable
+ * binding core will never deliver it, so read it after a command settles
+ * (docs/picture-in-picture-tag-design.md, README "Notes & limitations").
+ *
+ * @example
+ * ```typescript
+ * const core = new PipCore();
+ * // bind() only ever delivers "active" — see the note above about "error".
+ * bind(core, (name: keyof WcsPipCoreValues, value) => { ... });
+ * ```
+ */
+interface WcsPipCoreValues {
+    active: boolean;
+    error: any;
+}
+/**
+ * Value types for the Shell (`<wcs-pip>`) — identical value surface to the
+ * Core (same caveat: only `active` is observable). The Shell adds the
+ * `target` input (attribute-mirrored) and no additional observable
+ * properties.
+ */
+type WcsPipValues = WcsPipCoreValues;
+
+declare function bootstrapPip(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+/**
+ * Headless Picture-in-Picture primitive. A thin, framework-agnostic wrapper
+ * around the classic Picture-in-Picture API
+ * (`HTMLVideoElement.requestPictureInPicture()` / `document.exitPictureInPicture()` /
+ * `document.pictureInPictureElement`) exposed through the wc-bindable protocol.
+ *
+ * This Core follows the same basic pattern as `@wcstack/fullscreen`'s
+ * `FullscreenCore` (docs/fullscreen-tag-design.md): target resolution is done
+ * by the Shell (this Core receives the resolved element at call time), API
+ * resolution is call-time/non-cached, `_gen` is a single Core-level generation
+ * guard, and `error` is a simple single field (no permission-style 4-value
+ * state). See docs/picture-in-picture-tag-design.md for the differences from
+ * Fullscreen:
+ *
+ * - **§2 target constraint**: the resolved target MUST be a `<video>` element.
+ *   Picture-in-Picture is only defined as an instance method of
+ *   `HTMLVideoElement` — unlike Fullscreen, which any `Element` supports. A
+ *   non-`<video>` target is a never-throw failure: it is treated the same as
+ *   an unresolved target and reported via `error`.
+ * - **§3 event subscription target**: `enterpictureinpicture` /
+ *   `leavepictureinpicture` fire on the `<video>` element itself, not on
+ *   `document` (the reverse of Fullscreen's `document`-level
+ *   `fullscreenchange`). The Core attaches/detaches these listeners directly
+ *   on the resolved `<video>` element, re-wiring them whenever the target is
+ *   re-resolved (e.g. the Shell's `target` attribute changes).
+ */
+declare class PipCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _active;
+    private _error;
+    private _video;
+    private _gen;
+    private _ready;
+    constructor(target?: EventTarget);
+    get ready(): Promise<void>;
+    get active(): boolean;
+    get error(): any;
+    /**
+     * (Re-)subscribe to `enterpictureinpicture`/`leavepictureinpicture` on
+     * `element` (the Shell's resolved `<video>` target). Idempotent when called
+     * again with the same element; re-wires the listeners when the element
+     * changes (e.g. the `target` attribute was changed), detaching from the
+     * previous element first so no stale listener lingers.
+     */
+    observe(element: HTMLVideoElement | null): Promise<void>;
+    dispose(): void;
+    /**
+     * Request Picture-in-Picture for `element`. `element` must be a `<video>`
+     * (checked before the gesture-context failure path, since a type mismatch is
+     * an environment-independent, permanent error — docs/picture-in-picture-tag-design.md §2).
+     * Never throws: all failures (wrong tag, unsupported API, gesture-context
+     * rejection) are funneled into `error` and the returned promise resolves.
+     */
+    requestPictureInPicture(element: HTMLVideoElement | null): Promise<void>;
+    /**
+     * Exit Picture-in-Picture. Mirrors FullscreenCore.exitFullscreen(): a
+     * silent no-op (resolve, no error) when nothing is currently in
+     * Picture-in-Picture — see fullscreen-tag-design.md §7.
+     */
+    exitPictureInPicture(): Promise<void>;
+    private _requestPictureInPictureFn;
+    private _exitPictureInPictureFn;
+    private _pictureInPictureElement;
+    private _onEnter;
+    private _onLeave;
+    private _syncActive;
+    private _detach;
+    private _setActive;
+    private _setError;
+}
+
+/**
+ * `<wcs-pip target="...">` — declarative Picture-in-Picture control.
+ *
+ * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0/§1), this Shell
+ * does not operate on itself: it is a non-visible control tag that resolves a
+ * `target` element and invokes Picture-in-Picture commands against it. The
+ * `target` attribute resolves in the same 3 modes as `intersection`/`fullscreen`
+ * (`self` / a selector / the first element child), reused verbatim from
+ * `@wcstack/intersection`'s `_resolveTarget()`/`_safeQuery()`
+ * (packages/intersection/src/components/Intersect.ts).
+ *
+ * Picture-in-Picture-specific difference (docs/picture-in-picture-tag-design.md
+ * §2): the resolved target must be a `<video>` element. This Shell resolves the
+ * DOM element and hands it to the Core; the Core performs the `tagName ===
+ * "VIDEO"` validation (never-throw — a mismatch is treated as an unresolved
+ * target and reported via `error`, not thrown).
+ */
+declare class WcsPip extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    static observedAttributes: string[];
+    static wcBindable: IWcBindable;
+    private _core;
+    private _connectedCallbackPromise;
+    constructor();
+    get connectedCallbackPromise(): Promise<void>;
+    get target(): string;
+    set target(value: string);
+    get active(): boolean;
+    get error(): any;
+    requestPictureInPicture(): Promise<void>;
+    exitPictureInPicture(): Promise<void>;
+    /**
+     * `_resolveTarget()`/`_safeQuery()` copied verbatim from `@wcstack/intersection`
+     * (packages/intersection/src/components/Intersect.ts:243-267, 281-287) per the
+     * fullscreen/picture-in-picture batch's shared target-resolution archetype
+     * (docs/fullscreen-tag-design.md §1).
+     */
+    private _resolveTarget;
+    private _safeQuery;
+    /**
+     * Layers the Picture-in-Picture-specific `tagName === "VIDEO"` check on top
+     * of `_resolveTarget()` (docs/picture-in-picture-tag-design.md §2). A
+     * resolved-but-wrong-tag element is treated as unresolved (`element: null`)
+     * so it flows into the same "target not found" failure path as Fullscreen's
+     * missing-target case — never-throw, no exception escapes.
+     */
+    private _resolveVideoTarget;
+    private _observe;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+}
+
+export { PipCore, WcsPip, bootstrapPip, getConfig };
+export type { IWritableConfig, IWritableTagNames, WcsPipCoreValues, WcsPipValues };

package/dist/index.esm.js

@@ -0,0 +1,393 @@
+const _config = {
+    tagNames: {
+        pip: "wcs-pip",
+    },
+};
+function deepFreeze(obj) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    Object.freeze(obj);
+    for (const key of Object.keys(obj)) {
+        deepFreeze(obj[key]);
+    }
+    return obj;
+}
+function deepClone(obj) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    const clone = {};
+    for (const key of Object.keys(obj)) {
+        clone[key] = deepClone(obj[key]);
+    }
+    return clone;
+}
+let frozenConfig = null;
+const config = _config;
+function getConfig() {
+    if (!frozenConfig) {
+        frozenConfig = deepFreeze(deepClone(_config));
+    }
+    return frozenConfig;
+}
+function setConfig(partialConfig) {
+    if (partialConfig.tagNames) {
+        Object.assign(_config.tagNames, partialConfig.tagNames);
+    }
+    frozenConfig = null;
+}
+
+/**
+ * Headless Picture-in-Picture primitive. A thin, framework-agnostic wrapper
+ * around the classic Picture-in-Picture API
+ * (`HTMLVideoElement.requestPictureInPicture()` / `document.exitPictureInPicture()` /
+ * `document.pictureInPictureElement`) exposed through the wc-bindable protocol.
+ *
+ * This Core follows the same basic pattern as `@wcstack/fullscreen`'s
+ * `FullscreenCore` (docs/fullscreen-tag-design.md): target resolution is done
+ * by the Shell (this Core receives the resolved element at call time), API
+ * resolution is call-time/non-cached, `_gen` is a single Core-level generation
+ * guard, and `error` is a simple single field (no permission-style 4-value
+ * state). See docs/picture-in-picture-tag-design.md for the differences from
+ * Fullscreen:
+ *
+ * - **§2 target constraint**: the resolved target MUST be a `<video>` element.
+ *   Picture-in-Picture is only defined as an instance method of
+ *   `HTMLVideoElement` — unlike Fullscreen, which any `Element` supports. A
+ *   non-`<video>` target is a never-throw failure: it is treated the same as
+ *   an unresolved target and reported via `error`.
+ * - **§3 event subscription target**: `enterpictureinpicture` /
+ *   `leavepictureinpicture` fire on the `<video>` element itself, not on
+ *   `document` (the reverse of Fullscreen's `document`-level
+ *   `fullscreenchange`). The Core attaches/detaches these listeners directly
+ *   on the resolved `<video>` element, re-wiring them whenever the target is
+ *   re-resolved (e.g. the Shell's `target` attribute changes).
+ */
+class PipCore extends EventTarget {
+    static wcBindable = {
+        protocol: "wc-bindable",
+        version: 1,
+        properties: [
+            { name: "active", event: "wcs-pip:change", getter: (e) => e.detail.active },
+        ],
+        commands: [
+            { name: "requestPictureInPicture", async: true },
+            { name: "exitPictureInPicture", async: true },
+        ],
+    };
+    _target;
+    _active = false;
+    _error = null;
+    // The <video> element the Core currently subscribes to for
+    // enterpictureinpicture/leavepictureinpicture (null when unresolved/torn down).
+    _video = null;
+    // Generation guard (§3.4 / fullscreen-tag-design.md §6): bumped on dispose()
+    // and each async command start. A completion that lands after dispose() (or
+    // after a superseding call) is stale and MUST NOT write state.
+    _gen = 0;
+    // SSR (§3.8): no asynchronous probe to await, so readiness is immediate.
+    _ready = Promise.resolve();
+    constructor(target) {
+        super();
+        this._target = target ?? this;
+    }
+    get ready() {
+        return this._ready;
+    }
+    get active() {
+        return this._active;
+    }
+    get error() {
+        return this._error;
+    }
+    // --- Lifecycle (§3.5) ---
+    /**
+     * (Re-)subscribe to `enterpictureinpicture`/`leavepictureinpicture` on
+     * `element` (the Shell's resolved `<video>` target). Idempotent when called
+     * again with the same element; re-wires the listeners when the element
+     * changes (e.g. the `target` attribute was changed), detaching from the
+     * previous element first so no stale listener lingers.
+     */
+    observe(element) {
+        if (this._video === element) {
+            return this._ready;
+        }
+        this._detach();
+        this._video = element;
+        if (element) {
+            element.addEventListener("enterpictureinpicture", this._onEnter);
+            element.addEventListener("leavepictureinpicture", this._onLeave);
+        }
+        this._syncActive();
+        return this._ready;
+    }
+    dispose() {
+        this._gen++;
+        this._detach();
+        this._video = null;
+    }
+    // --- Commands (§3.6 never-throw) ---
+    /**
+     * Request Picture-in-Picture for `element`. `element` must be a `<video>`
+     * (checked before the gesture-context failure path, since a type mismatch is
+     * an environment-independent, permanent error — docs/picture-in-picture-tag-design.md §2).
+     * Never throws: all failures (wrong tag, unsupported API, gesture-context
+     * rejection) are funneled into `error` and the returned promise resolves.
+     */
+    async requestPictureInPicture(element) {
+        const gen = ++this._gen;
+        if (!element || element.tagName !== "VIDEO") {
+            this._setError({ message: "target must be a <video> element." });
+            return;
+        }
+        // Re-wire to `element` before issuing the platform call: a caller may
+        // request a <video> different from the one last passed to observe() (e.g.
+        // the Shell's target attribute pointed at nothing at connect time and the
+        // matching <video> was only inserted later, so no attributeChangedCallback
+        // ever re-resolved it). Without this, `_video` stays stale and
+        // `_syncActive()` below (and future enter/leave events) would never
+        // recognize `element` as this Core's target, leaving `active` permanently
+        // wrong even though the request succeeded (mirrors
+        // FullscreenCore.requestFullscreen()'s unconditional `this._resolvedTarget
+        // = element` assignment — docs/fullscreen-tag-design.md §6).
+        this.observe(element);
+        const fn = this._requestPictureInPictureFn(element);
+        if (!fn) {
+            this._setError({ message: "Picture-in-Picture API is not supported." });
+            return;
+        }
+        try {
+            await fn.call(element);
+            if (gen !== this._gen)
+                return; // stale
+            this._setError(null);
+            this._syncActive(); // belt-and-suspenders (mirrors FullscreenCore's _applyActive() on success)
+        }
+        catch (e) {
+            if (gen !== this._gen)
+                return; // stale
+            this._setError(e); // e.g. NotAllowedError (gesture-context rejection)
+        }
+    }
+    /**
+     * Exit Picture-in-Picture. Mirrors FullscreenCore.exitFullscreen(): a
+     * silent no-op (resolve, no error) when nothing is currently in
+     * Picture-in-Picture — see fullscreen-tag-design.md §7.
+     */
+    async exitPictureInPicture() {
+        // no-op checks come BEFORE the generation bump: a call that does nothing
+        // must not supersede an in-flight requestPictureInPicture() — bumping
+        // first would make the pending request's settle handling stale and
+        // silently swallow its error update (mirrors
+        // FullscreenCore.exitFullscreen()).
+        if (this._pictureInPictureElement() === null)
+            return; // already not in PiP: silent no-op
+        const fn = this._exitPictureInPictureFn();
+        if (!fn)
+            return; // unsupported: silent no-op (semantically already "not in PiP")
+        const gen = ++this._gen;
+        try {
+            await fn();
+            if (gen !== this._gen)
+                return;
+            this._setError(null);
+            this._syncActive(); // belt-and-suspenders (mirrors FullscreenCore.exitFullscreen()'s success-path _applyActive()); covers a delayed/dropped leavepictureinpicture
+        }
+        catch (e) {
+            if (gen !== this._gen)
+                return;
+            this._setError(e);
+        }
+    }
+    // --- Internal: API resolution (call-time, never cached — §3.7) ---
+    // Unlike FullscreenCore's _elementFullscreenFn(), a naive direct property
+    // lookup (`e.requestPictureInPicture`, walking the prototype chain) here is
+    // safe: it cannot recurse into the Shell's own command method,
+    // because the resolved target is validated to be a <video> element (§2)
+    // before this is called, and <wcs-pip> (the Shell) is never itself a
+    // <video>. Fullscreen's own→Element.prototype two-step resolution guards
+    // against `target="self"`/no-target resolving to the Shell element, which
+    // cannot happen here.
+    _requestPictureInPictureFn(el) {
+        const e = el;
+        return typeof e.requestPictureInPicture === "function" ? e.requestPictureInPicture : undefined;
+    }
+    _exitPictureInPictureFn() {
+        const d = document;
+        return typeof d.exitPictureInPicture === "function" ? d.exitPictureInPicture.bind(document) : undefined;
+    }
+    _pictureInPictureElement() {
+        const d = document;
+        return d.pictureInPictureElement ?? null;
+    }
+    // --- Internal: event wiring ---
+    _onEnter = () => {
+        this._syncActive();
+    };
+    _onLeave = () => {
+        this._syncActive();
+    };
+    _syncActive() {
+        const isActive = this._video !== null && this._pictureInPictureElement() === this._video;
+        this._setActive(isActive);
+    }
+    _detach() {
+        if (this._video) {
+            this._video.removeEventListener("enterpictureinpicture", this._onEnter);
+            this._video.removeEventListener("leavepictureinpicture", this._onLeave);
+        }
+    }
+    // --- State setters with event dispatch (§3.3 same-value guard) ---
+    _setActive(active) {
+        if (this._active === active)
+            return;
+        this._active = active;
+        this._target.dispatchEvent(new CustomEvent("wcs-pip:change", {
+            detail: { active },
+            bubbles: true,
+        }));
+    }
+    _setError(error) {
+        this._error = error;
+    }
+}
+
+/**
+ * `<wcs-pip target="...">` — declarative Picture-in-Picture control.
+ *
+ * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0/§1), this Shell
+ * does not operate on itself: it is a non-visible control tag that resolves a
+ * `target` element and invokes Picture-in-Picture commands against it. The
+ * `target` attribute resolves in the same 3 modes as `intersection`/`fullscreen`
+ * (`self` / a selector / the first element child), reused verbatim from
+ * `@wcstack/intersection`'s `_resolveTarget()`/`_safeQuery()`
+ * (packages/intersection/src/components/Intersect.ts).
+ *
+ * Picture-in-Picture-specific difference (docs/picture-in-picture-tag-design.md
+ * §2): the resolved target must be a `<video>` element. This Shell resolves the
+ * DOM element and hands it to the Core; the Core performs the `tagName ===
+ * "VIDEO"` validation (never-throw — a mismatch is treated as an unresolved
+ * target and reported via `error`, not thrown).
+ */
+class WcsPip extends HTMLElement {
+    // SSR (§4.4): observe() completes synchronously, but the Shell still exposes
+    // connectedCallbackPromise so the state binder can await it uniformly across
+    // all IO nodes before snapshotting.
+    static hasConnectedCallbackPromise = true;
+    static observedAttributes = ["target"];
+    static wcBindable = {
+        ...PipCore.wcBindable,
+        inputs: [{ name: "target", attribute: "target" }],
+        // Core の commands をそのまま継承（単一情報源）。fullscreen/intersection と同型。
+        commands: PipCore.wcBindable.commands,
+    };
+    _core;
+    _connectedCallbackPromise = Promise.resolve();
+    constructor() {
+        super();
+        this._core = new PipCore(this);
+    }
+    get connectedCallbackPromise() {
+        return this._connectedCallbackPromise;
+    }
+    // --- Attribute accessors ---
+    get target() {
+        return this.getAttribute("target") ?? "";
+    }
+    set target(value) {
+        this.setAttribute("target", value);
+    }
+    // --- Core delegated getters ---
+    get active() {
+        return this._core.active;
+    }
+    get error() {
+        return this._core.error;
+    }
+    // --- Commands ---
+    async requestPictureInPicture() {
+        const { element } = this._resolveVideoTarget();
+        return this._core.requestPictureInPicture(element);
+    }
+    async exitPictureInPicture() {
+        return this._core.exitPictureInPicture();
+    }
+    // --- Internal ---
+    /**
+     * `_resolveTarget()`/`_safeQuery()` copied verbatim from `@wcstack/intersection`
+     * (packages/intersection/src/components/Intersect.ts:243-267, 281-287) per the
+     * fullscreen/picture-in-picture batch's shared target-resolution archetype
+     * (docs/fullscreen-tag-design.md §1).
+     */
+    _resolveTarget() {
+        const target = this.target;
+        if (target === "self") {
+            return { element: this, display: "block" };
+        }
+        if (target !== "") {
+            const scope = this.getRootNode();
+            return { element: this._safeQuery(scope, target), display: "none" };
+        }
+        const child = this.firstElementChild;
+        if (child) {
+            return { element: child, display: "contents" };
+        }
+        return { element: this, display: "block" };
+    }
+    _safeQuery(scope, selector) {
+        try {
+            return scope.querySelector(selector);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Layers the Picture-in-Picture-specific `tagName === "VIDEO"` check on top
+     * of `_resolveTarget()` (docs/picture-in-picture-tag-design.md §2). A
+     * resolved-but-wrong-tag element is treated as unresolved (`element: null`)
+     * so it flows into the same "target not found" failure path as Fullscreen's
+     * missing-target case — never-throw, no exception escapes.
+     */
+    _resolveVideoTarget() {
+        const { element, display } = this._resolveTarget();
+        if (element !== null && element.tagName !== "VIDEO") {
+            return { element: null, display };
+        }
+        return { element: element, display };
+    }
+    _observe() {
+        const { element, display } = this._resolveVideoTarget();
+        this.style.display = display;
+        this._connectedCallbackPromise = this._core.observe(element);
+    }
+    // --- Lifecycle ---
+    connectedCallback() {
+        this._observe();
+    }
+    disconnectedCallback() {
+        this._core.dispose();
+    }
+    attributeChangedCallback(_name, oldValue, newValue) {
+        if (oldValue === newValue)
+            return;
+        if (!this.isConnected)
+            return;
+        this._observe();
+    }
+}
+
+function registerComponents() {
+    if (!customElements.get(config.tagNames.pip)) {
+        customElements.define(config.tagNames.pip, WcsPip);
+    }
+}
+
+function bootstrapPip(userConfig) {
+    if (userConfig) {
+        setConfig(userConfig);
+    }
+    registerComponents();
+}
+
+export { PipCore, WcsPip, bootstrapPip, getConfig };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/config.ts","../src/core/PipCore.ts","../src/components/Pip.ts","../src/registerComponents.ts","../src/bootstrapPip.ts"],"sourcesContent":["import { IConfig, IWritableConfig } from \"./types.js\";\n\ninterface IInternalConfig extends IConfig {\n  tagNames: {\n    pip: string;\n  };\n}\n\nconst _config: IInternalConfig = {\n  tagNames: {\n    pip: \"wcs-pip\",\n  },\n};\n\nfunction deepFreeze<T>(obj: T): T {\n  if (obj === null || typeof obj !== \"object\") return obj;\n  Object.freeze(obj);\n  for (const key of Object.keys(obj)) {\n    deepFreeze((obj as Record<string, unknown>)[key]);\n  }\n  return obj;\n}\n\nfunction deepClone<T>(obj: T): T {\n  if (obj === null || typeof obj !== \"object\") return obj;\n  const clone: Record<string, unknown> = {};\n  for (const key of Object.keys(obj)) {\n    clone[key] = deepClone((obj as Record<string, unknown>)[key]);\n  }\n  return clone as T;\n}\n\nlet frozenConfig: IConfig | null = null;\n\nexport const config: IConfig = _config as IConfig;\n\nexport function getConfig(): IConfig {\n  if (!frozenConfig) {\n    frozenConfig = deepFreeze(deepClone(_config));\n  }\n  return frozenConfig;\n}\n\nexport function setConfig(partialConfig: IWritableConfig): void {\n  if (partialConfig.tagNames) {\n    Object.assign(_config.tagNames, partialConfig.tagNames);\n  }\n  frozenConfig = null;\n}\n","import { IWcBindable } from \"../types.js\";\n\n/**\n * Headless Picture-in-Picture primitive. A thin, framework-agnostic wrapper\n * around the classic Picture-in-Picture API\n * (`HTMLVideoElement.requestPictureInPicture()` / `document.exitPictureInPicture()` /\n * `document.pictureInPictureElement`) exposed through the wc-bindable protocol.\n *\n * This Core follows the same basic pattern as `@wcstack/fullscreen`'s\n * `FullscreenCore` (docs/fullscreen-tag-design.md): target resolution is done\n * by the Shell (this Core receives the resolved element at call time), API\n * resolution is call-time/non-cached, `_gen` is a single Core-level generation\n * guard, and `error` is a simple single field (no permission-style 4-value\n * state). See docs/picture-in-picture-tag-design.md for the differences from\n * Fullscreen:\n *\n * - **§2 target constraint**: the resolved target MUST be a `<video>` element.\n *   Picture-in-Picture is only defined as an instance method of\n *   `HTMLVideoElement` — unlike Fullscreen, which any `Element` supports. A\n *   non-`<video>` target is a never-throw failure: it is treated the same as\n *   an unresolved target and reported via `error`.\n * - **§3 event subscription target**: `enterpictureinpicture` /\n *   `leavepictureinpicture` fire on the `<video>` element itself, not on\n *   `document` (the reverse of Fullscreen's `document`-level\n *   `fullscreenchange`). The Core attaches/detaches these listeners directly\n *   on the resolved `<video>` element, re-wiring them whenever the target is\n *   re-resolved (e.g. the Shell's `target` attribute changes).\n */\nexport class PipCore extends EventTarget {\n  static wcBindable: IWcBindable = {\n    protocol: \"wc-bindable\",\n    version: 1,\n    properties: [\n      { name: \"active\", event: \"wcs-pip:change\", getter: (e: Event) => (e as CustomEvent).detail.active },\n    ],\n    commands: [\n      { name: \"requestPictureInPicture\", async: true },\n      { name: \"exitPictureInPicture\", async: true },\n    ],\n  };\n\n  private _target: EventTarget;\n  private _active: boolean = false;\n  private _error: any = null;\n\n  // The <video> element the Core currently subscribes to for\n  // enterpictureinpicture/leavepictureinpicture (null when unresolved/torn down).\n  private _video: HTMLVideoElement | null = null;\n\n  // Generation guard (§3.4 / fullscreen-tag-design.md §6): bumped on dispose()\n  // and each async command start. A completion that lands after dispose() (or\n  // after a superseding call) is stale and MUST NOT write state.\n  private _gen = 0;\n\n  // SSR (§3.8): no asynchronous probe to await, so readiness is immediate.\n  private _ready: Promise<void> = Promise.resolve();\n\n  constructor(target?: EventTarget) {\n    super();\n    this._target = target ?? this;\n  }\n\n  get ready(): Promise<void> {\n    return this._ready;\n  }\n\n  get active(): boolean {\n    return this._active;\n  }\n\n  get error(): any {\n    return this._error;\n  }\n\n  // --- Lifecycle (§3.5) ---\n\n  /**\n   * (Re-)subscribe to `enterpictureinpicture`/`leavepictureinpicture` on\n   * `element` (the Shell's resolved `<video>` target). Idempotent when called\n   * again with the same element; re-wires the listeners when the element\n   * changes (e.g. the `target` attribute was changed), detaching from the\n   * previous element first so no stale listener lingers.\n   */\n  observe(element: HTMLVideoElement | null): Promise<void> {\n    if (this._video === element) {\n      return this._ready;\n    }\n    this._detach();\n    this._video = element;\n    if (element) {\n      element.addEventListener(\"enterpictureinpicture\", this._onEnter);\n      element.addEventListener(\"leavepictureinpicture\", this._onLeave);\n    }\n    this._syncActive();\n    return this._ready;\n  }\n\n  dispose(): void {\n    this._gen++;\n    this._detach();\n    this._video = null;\n  }\n\n  // --- Commands (§3.6 never-throw) ---\n\n  /**\n   * Request Picture-in-Picture for `element`. `element` must be a `<video>`\n   * (checked before the gesture-context failure path, since a type mismatch is\n   * an environment-independent, permanent error — docs/picture-in-picture-tag-design.md §2).\n   * Never throws: all failures (wrong tag, unsupported API, gesture-context\n   * rejection) are funneled into `error` and the returned promise resolves.\n   */\n  async requestPictureInPicture(element: HTMLVideoElement | null): Promise<void> {\n    const gen = ++this._gen;\n    if (!element || element.tagName !== \"VIDEO\") {\n      this._setError({ message: \"target must be a <video> element.\" });\n      return;\n    }\n    // Re-wire to `element` before issuing the platform call: a caller may\n    // request a <video> different from the one last passed to observe() (e.g.\n    // the Shell's target attribute pointed at nothing at connect time and the\n    // matching <video> was only inserted later, so no attributeChangedCallback\n    // ever re-resolved it). Without this, `_video` stays stale and\n    // `_syncActive()` below (and future enter/leave events) would never\n    // recognize `element` as this Core's target, leaving `active` permanently\n    // wrong even though the request succeeded (mirrors\n    // FullscreenCore.requestFullscreen()'s unconditional `this._resolvedTarget\n    // = element` assignment — docs/fullscreen-tag-design.md §6).\n    this.observe(element);\n    const fn = this._requestPictureInPictureFn(element);\n    if (!fn) {\n      this._setError({ message: \"Picture-in-Picture API is not supported.\" });\n      return;\n    }\n    try {\n      await fn.call(element);\n      if (gen !== this._gen) return; // stale\n      this._setError(null);\n      this._syncActive(); // belt-and-suspenders (mirrors FullscreenCore's _applyActive() on success)\n    } catch (e: any) {\n      if (gen !== this._gen) return; // stale\n      this._setError(e); // e.g. NotAllowedError (gesture-context rejection)\n    }\n  }\n\n  /**\n   * Exit Picture-in-Picture. Mirrors FullscreenCore.exitFullscreen(): a\n   * silent no-op (resolve, no error) when nothing is currently in\n   * Picture-in-Picture — see fullscreen-tag-design.md §7.\n   */\n  async exitPictureInPicture(): Promise<void> {\n    // no-op checks come BEFORE the generation bump: a call that does nothing\n    // must not supersede an in-flight requestPictureInPicture() — bumping\n    // first would make the pending request's settle handling stale and\n    // silently swallow its error update (mirrors\n    // FullscreenCore.exitFullscreen()).\n    if (this._pictureInPictureElement() === null) return; // already not in PiP: silent no-op\n    const fn = this._exitPictureInPictureFn();\n    if (!fn) return; // unsupported: silent no-op (semantically already \"not in PiP\")\n    const gen = ++this._gen;\n    try {\n      await fn();\n      if (gen !== this._gen) return;\n      this._setError(null);\n      this._syncActive(); // belt-and-suspenders (mirrors FullscreenCore.exitFullscreen()'s success-path _applyActive()); covers a delayed/dropped leavepictureinpicture\n    } catch (e: any) {\n      if (gen !== this._gen) return;\n      this._setError(e);\n    }\n  }\n\n  // --- Internal: API resolution (call-time, never cached — §3.7) ---\n\n  // Unlike FullscreenCore's _elementFullscreenFn(), a naive direct property\n  // lookup (`e.requestPictureInPicture`, walking the prototype chain) here is\n  // safe: it cannot recurse into the Shell's own command method,\n  // because the resolved target is validated to be a <video> element (§2)\n  // before this is called, and <wcs-pip> (the Shell) is never itself a\n  // <video>. Fullscreen's own→Element.prototype two-step resolution guards\n  // against `target=\"self\"`/no-target resolving to the Shell element, which\n  // cannot happen here.\n  private _requestPictureInPictureFn(el: HTMLVideoElement): (() => Promise<PictureInPictureWindow>) | undefined {\n    const e = el as any;\n    return typeof e.requestPictureInPicture === \"function\" ? e.requestPictureInPicture : undefined;\n  }\n\n  private _exitPictureInPictureFn(): (() => Promise<void>) | undefined {\n    const d = document as any;\n    return typeof d.exitPictureInPicture === \"function\" ? d.exitPictureInPicture.bind(document) : undefined;\n  }\n\n  private _pictureInPictureElement(): Element | null {\n    const d = document as any;\n    return d.pictureInPictureElement ?? null;\n  }\n\n  // --- Internal: event wiring ---\n\n  private _onEnter = (): void => {\n    this._syncActive();\n  };\n\n  private _onLeave = (): void => {\n    this._syncActive();\n  };\n\n  private _syncActive(): void {\n    const isActive = this._video !== null && this._pictureInPictureElement() === this._video;\n    this._setActive(isActive);\n  }\n\n  private _detach(): void {\n    if (this._video) {\n      this._video.removeEventListener(\"enterpictureinpicture\", this._onEnter);\n      this._video.removeEventListener(\"leavepictureinpicture\", this._onLeave);\n    }\n  }\n\n  // --- State setters with event dispatch (§3.3 same-value guard) ---\n\n  private _setActive(active: boolean): void {\n    if (this._active === active) return;\n    this._active = active;\n    this._target.dispatchEvent(new CustomEvent(\"wcs-pip:change\", {\n      detail: { active },\n      bubbles: true,\n    }));\n  }\n\n  private _setError(error: any): void {\n    this._error = error;\n  }\n}\n","import { IWcBindable } from \"../types.js\";\nimport { PipCore } from \"../core/PipCore.js\";\n\n/**\n * `<wcs-pip target=\"...\">` — declarative Picture-in-Picture control.\n *\n * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0/§1), this Shell\n * does not operate on itself: it is a non-visible control tag that resolves a\n * `target` element and invokes Picture-in-Picture commands against it. The\n * `target` attribute resolves in the same 3 modes as `intersection`/`fullscreen`\n * (`self` / a selector / the first element child), reused verbatim from\n * `@wcstack/intersection`'s `_resolveTarget()`/`_safeQuery()`\n * (packages/intersection/src/components/Intersect.ts).\n *\n * Picture-in-Picture-specific difference (docs/picture-in-picture-tag-design.md\n * §2): the resolved target must be a `<video>` element. This Shell resolves the\n * DOM element and hands it to the Core; the Core performs the `tagName ===\n * \"VIDEO\"` validation (never-throw — a mismatch is treated as an unresolved\n * target and reported via `error`, not thrown).\n */\nexport class WcsPip extends HTMLElement {\n  // SSR (§4.4): observe() completes synchronously, but the Shell still exposes\n  // connectedCallbackPromise so the state binder can await it uniformly across\n  // all IO nodes before snapshotting.\n  static hasConnectedCallbackPromise = true;\n\n  static observedAttributes = [\"target\"];\n\n  static wcBindable: IWcBindable = {\n    ...PipCore.wcBindable,\n    inputs: [{ name: \"target\", attribute: \"target\" }],\n    // Core の commands をそのまま継承（単一情報源）。fullscreen/intersection と同型。\n    commands: PipCore.wcBindable.commands,\n  };\n\n  private _core: PipCore;\n  private _connectedCallbackPromise: Promise<void> = Promise.resolve();\n\n  constructor() {\n    super();\n    this._core = new PipCore(this);\n  }\n\n  get connectedCallbackPromise(): Promise<void> {\n    return this._connectedCallbackPromise;\n  }\n\n  // --- Attribute accessors ---\n\n  get target(): string {\n    return this.getAttribute(\"target\") ?? \"\";\n  }\n\n  set target(value: string) {\n    this.setAttribute(\"target\", value);\n  }\n\n  // --- Core delegated getters ---\n\n  get active(): boolean {\n    return this._core.active;\n  }\n\n  get error(): any {\n    return this._core.error;\n  }\n\n  // --- Commands ---\n\n  async requestPictureInPicture(): Promise<void> {\n    const { element } = this._resolveVideoTarget();\n    return this._core.requestPictureInPicture(element);\n  }\n\n  async exitPictureInPicture(): Promise<void> {\n    return this._core.exitPictureInPicture();\n  }\n\n  // --- Internal ---\n\n  /**\n   * `_resolveTarget()`/`_safeQuery()` copied verbatim from `@wcstack/intersection`\n   * (packages/intersection/src/components/Intersect.ts:243-267, 281-287) per the\n   * fullscreen/picture-in-picture batch's shared target-resolution archetype\n   * (docs/fullscreen-tag-design.md §1).\n   */\n  private _resolveTarget(): { element: Element | null; display: string } {\n    const target = this.target;\n    if (target === \"self\") {\n      return { element: this, display: \"block\" };\n    }\n    if (target !== \"\") {\n      const scope = this.getRootNode() as Document | ShadowRoot;\n      return { element: this._safeQuery(scope, target), display: \"none\" };\n    }\n    const child = this.firstElementChild;\n    if (child) {\n      return { element: child, display: \"contents\" };\n    }\n    return { element: this, display: \"block\" };\n  }\n\n  private _safeQuery(scope: Document | ShadowRoot, selector: string): Element | null {\n    try {\n      return scope.querySelector(selector);\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Layers the Picture-in-Picture-specific `tagName === \"VIDEO\"` check on top\n   * of `_resolveTarget()` (docs/picture-in-picture-tag-design.md §2). A\n   * resolved-but-wrong-tag element is treated as unresolved (`element: null`)\n   * so it flows into the same \"target not found\" failure path as Fullscreen's\n   * missing-target case — never-throw, no exception escapes.\n   */\n  private _resolveVideoTarget(): { element: HTMLVideoElement | null; display: string } {\n    const { element, display } = this._resolveTarget();\n    if (element !== null && element.tagName !== \"VIDEO\") {\n      return { element: null, display };\n    }\n    return { element: element as HTMLVideoElement | null, display };\n  }\n\n  private _observe(): void {\n    const { element, display } = this._resolveVideoTarget();\n    this.style.display = display;\n    this._connectedCallbackPromise = this._core.observe(element);\n  }\n\n  // --- Lifecycle ---\n\n  connectedCallback(): void {\n    this._observe();\n  }\n\n  disconnectedCallback(): void {\n    this._core.dispose();\n  }\n\n  attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void {\n    if (oldValue === newValue) return;\n    if (!this.isConnected) return;\n    this._observe();\n  }\n}\n","import { WcsPip } from \"./components/Pip.js\";\nimport { config } from \"./config.js\";\n\nexport function registerComponents(): void {\n  if (!customElements.get(config.tagNames.pip)) {\n    customElements.define(config.tagNames.pip, WcsPip);\n  }\n}\n","import { setConfig } from \"./config.js\";\nimport { registerComponents } from \"./registerComponents.js\";\nimport { IWritableConfig } from \"./types.js\";\n\nexport function bootstrapPip(userConfig?: IWritableConfig): void {\n  if (userConfig) {\n    setConfig(userConfig);\n  }\n  registerComponents();\n}\n"],"names":[],"mappings":"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"}

package/dist/index.esm.min.js

@@ -0,0 +1,2 @@
+const e={tagNames:{pip:"wcs-pip"}};function t(e){if(null===e||"object"!=typeof e)return e;Object.freeze(e);for(const r of Object.keys(e))t(e[r]);return e}function r(e){if(null===e||"object"!=typeof e)return e;const t={};for(const i of Object.keys(e))t[i]=r(e[i]);return t}let i=null;const s=e;function n(){return i||(i=t(r(e))),i}class c extends EventTarget{static wcBindable={protocol:"wc-bindable",version:1,properties:[{name:"active",event:"wcs-pip:change",getter:e=>e.detail.active}],commands:[{name:"requestPictureInPicture",async:!0},{name:"exitPictureInPicture",async:!0}]};_target;_active=!1;_error=null;_video=null;_gen=0;_ready=Promise.resolve();constructor(e){super(),this._target=e??this}get ready(){return this._ready}get active(){return this._active}get error(){return this._error}observe(e){return this._video===e||(this._detach(),this._video=e,e&&(e.addEventListener("enterpictureinpicture",this._onEnter),e.addEventListener("leavepictureinpicture",this._onLeave)),this._syncActive()),this._ready}dispose(){this._gen++,this._detach(),this._video=null}async requestPictureInPicture(e){const t=++this._gen;if(!e||"VIDEO"!==e.tagName)return void this._setError({message:"target must be a <video> element."});this.observe(e);const r=this._requestPictureInPictureFn(e);if(r)try{if(await r.call(e),t!==this._gen)return;this._setError(null),this._syncActive()}catch(e){if(t!==this._gen)return;this._setError(e)}else this._setError({message:"Picture-in-Picture API is not supported."})}async exitPictureInPicture(){if(null===this._pictureInPictureElement())return;const e=this._exitPictureInPictureFn();if(!e)return;const t=++this._gen;try{if(await e(),t!==this._gen)return;this._setError(null),this._syncActive()}catch(e){if(t!==this._gen)return;this._setError(e)}}_requestPictureInPictureFn(e){const t=e;return"function"==typeof t.requestPictureInPicture?t.requestPictureInPicture:void 0}_exitPictureInPictureFn(){const e=document;return"function"==typeof e.exitPictureInPicture?e.exitPictureInPicture.bind(document):void 0}_pictureInPictureElement(){return document.pictureInPictureElement??null}_onEnter=()=>{this._syncActive()};_onLeave=()=>{this._syncActive()};_syncActive(){const e=null!==this._video&&this._pictureInPictureElement()===this._video;this._setActive(e)}_detach(){this._video&&(this._video.removeEventListener("enterpictureinpicture",this._onEnter),this._video.removeEventListener("leavepictureinpicture",this._onLeave))}_setActive(e){this._active!==e&&(this._active=e,this._target.dispatchEvent(new CustomEvent("wcs-pip:change",{detail:{active:e},bubbles:!0})))}_setError(e){this._error=e}}class o extends HTMLElement{static hasConnectedCallbackPromise=!0;static observedAttributes=["target"];static wcBindable={...c.wcBindable,inputs:[{name:"target",attribute:"target"}],commands:c.wcBindable.commands};_core;_connectedCallbackPromise=Promise.resolve();constructor(){super(),this._core=new c(this)}get connectedCallbackPromise(){return this._connectedCallbackPromise}get target(){return this.getAttribute("target")??""}set target(e){this.setAttribute("target",e)}get active(){return this._core.active}get error(){return this._core.error}async requestPictureInPicture(){const{element:e}=this._resolveVideoTarget();return this._core.requestPictureInPicture(e)}async exitPictureInPicture(){return this._core.exitPictureInPicture()}_resolveTarget(){const e=this.target;if("self"===e)return{element:this,display:"block"};if(""!==e){const t=this.getRootNode();return{element:this._safeQuery(t,e),display:"none"}}const t=this.firstElementChild;return t?{element:t,display:"contents"}:{element:this,display:"block"}}_safeQuery(e,t){try{return e.querySelector(t)}catch{return null}}_resolveVideoTarget(){const{element:e,display:t}=this._resolveTarget();return null!==e&&"VIDEO"!==e.tagName?{element:null,display:t}:{element:e,display:t}}_observe(){const{element:e,display:t}=this._resolveVideoTarget();this.style.display=t,this._connectedCallbackPromise=this._core.observe(e)}connectedCallback(){this._observe()}disconnectedCallback(){this._core.dispose()}attributeChangedCallback(e,t,r){t!==r&&this.isConnected&&this._observe()}}function u(t){var r;t&&((r=t).tagNames&&Object.assign(e.tagNames,r.tagNames),i=null),customElements.get(s.tagNames.pip)||customElements.define(s.tagNames.pip,o)}export{c as PipCore,o as WcsPip,u as bootstrapPip,n as getConfig};
+//# sourceMappingURL=index.esm.min.js.map

package/dist/index.esm.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.min.js","sources":["../src/config.ts","../src/core/PipCore.ts","../src/components/Pip.ts","../src/bootstrapPip.ts","../src/registerComponents.ts"],"sourcesContent":["import { IConfig, IWritableConfig } from \"./types.js\";\n\ninterface IInternalConfig extends IConfig {\n  tagNames: {\n    pip: string;\n  };\n}\n\nconst _config: IInternalConfig = {\n  tagNames: {\n    pip: \"wcs-pip\",\n  },\n};\n\nfunction deepFreeze<T>(obj: T): T {\n  if (obj === null || typeof obj !== \"object\") return obj;\n  Object.freeze(obj);\n  for (const key of Object.keys(obj)) {\n    deepFreeze((obj as Record<string, unknown>)[key]);\n  }\n  return obj;\n}\n\nfunction deepClone<T>(obj: T): T {\n  if (obj === null || typeof obj !== \"object\") return obj;\n  const clone: Record<string, unknown> = {};\n  for (const key of Object.keys(obj)) {\n    clone[key] = deepClone((obj as Record<string, unknown>)[key]);\n  }\n  return clone as T;\n}\n\nlet frozenConfig: IConfig | null = null;\n\nexport const config: IConfig = _config as IConfig;\n\nexport function getConfig(): IConfig {\n  if (!frozenConfig) {\n    frozenConfig = deepFreeze(deepClone(_config));\n  }\n  return frozenConfig;\n}\n\nexport function setConfig(partialConfig: IWritableConfig): void {\n  if (partialConfig.tagNames) {\n    Object.assign(_config.tagNames, partialConfig.tagNames);\n  }\n  frozenConfig = null;\n}\n","import { IWcBindable } from \"../types.js\";\n\n/**\n * Headless Picture-in-Picture primitive. A thin, framework-agnostic wrapper\n * around the classic Picture-in-Picture API\n * (`HTMLVideoElement.requestPictureInPicture()` / `document.exitPictureInPicture()` /\n * `document.pictureInPictureElement`) exposed through the wc-bindable protocol.\n *\n * This Core follows the same basic pattern as `@wcstack/fullscreen`'s\n * `FullscreenCore` (docs/fullscreen-tag-design.md): target resolution is done\n * by the Shell (this Core receives the resolved element at call time), API\n * resolution is call-time/non-cached, `_gen` is a single Core-level generation\n * guard, and `error` is a simple single field (no permission-style 4-value\n * state). See docs/picture-in-picture-tag-design.md for the differences from\n * Fullscreen:\n *\n * - **§2 target constraint**: the resolved target MUST be a `<video>` element.\n *   Picture-in-Picture is only defined as an instance method of\n *   `HTMLVideoElement` — unlike Fullscreen, which any `Element` supports. A\n *   non-`<video>` target is a never-throw failure: it is treated the same as\n *   an unresolved target and reported via `error`.\n * - **§3 event subscription target**: `enterpictureinpicture` /\n *   `leavepictureinpicture` fire on the `<video>` element itself, not on\n *   `document` (the reverse of Fullscreen's `document`-level\n *   `fullscreenchange`). The Core attaches/detaches these listeners directly\n *   on the resolved `<video>` element, re-wiring them whenever the target is\n *   re-resolved (e.g. the Shell's `target` attribute changes).\n */\nexport class PipCore extends EventTarget {\n  static wcBindable: IWcBindable = {\n    protocol: \"wc-bindable\",\n    version: 1,\n    properties: [\n      { name: \"active\", event: \"wcs-pip:change\", getter: (e: Event) => (e as CustomEvent).detail.active },\n    ],\n    commands: [\n      { name: \"requestPictureInPicture\", async: true },\n      { name: \"exitPictureInPicture\", async: true },\n    ],\n  };\n\n  private _target: EventTarget;\n  private _active: boolean = false;\n  private _error: any = null;\n\n  // The <video> element the Core currently subscribes to for\n  // enterpictureinpicture/leavepictureinpicture (null when unresolved/torn down).\n  private _video: HTMLVideoElement | null = null;\n\n  // Generation guard (§3.4 / fullscreen-tag-design.md §6): bumped on dispose()\n  // and each async command start. A completion that lands after dispose() (or\n  // after a superseding call) is stale and MUST NOT write state.\n  private _gen = 0;\n\n  // SSR (§3.8): no asynchronous probe to await, so readiness is immediate.\n  private _ready: Promise<void> = Promise.resolve();\n\n  constructor(target?: EventTarget) {\n    super();\n    this._target = target ?? this;\n  }\n\n  get ready(): Promise<void> {\n    return this._ready;\n  }\n\n  get active(): boolean {\n    return this._active;\n  }\n\n  get error(): any {\n    return this._error;\n  }\n\n  // --- Lifecycle (§3.5) ---\n\n  /**\n   * (Re-)subscribe to `enterpictureinpicture`/`leavepictureinpicture` on\n   * `element` (the Shell's resolved `<video>` target). Idempotent when called\n   * again with the same element; re-wires the listeners when the element\n   * changes (e.g. the `target` attribute was changed), detaching from the\n   * previous element first so no stale listener lingers.\n   */\n  observe(element: HTMLVideoElement | null): Promise<void> {\n    if (this._video === element) {\n      return this._ready;\n    }\n    this._detach();\n    this._video = element;\n    if (element) {\n      element.addEventListener(\"enterpictureinpicture\", this._onEnter);\n      element.addEventListener(\"leavepictureinpicture\", this._onLeave);\n    }\n    this._syncActive();\n    return this._ready;\n  }\n\n  dispose(): void {\n    this._gen++;\n    this._detach();\n    this._video = null;\n  }\n\n  // --- Commands (§3.6 never-throw) ---\n\n  /**\n   * Request Picture-in-Picture for `element`. `element` must be a `<video>`\n   * (checked before the gesture-context failure path, since a type mismatch is\n   * an environment-independent, permanent error — docs/picture-in-picture-tag-design.md §2).\n   * Never throws: all failures (wrong tag, unsupported API, gesture-context\n   * rejection) are funneled into `error` and the returned promise resolves.\n   */\n  async requestPictureInPicture(element: HTMLVideoElement | null): Promise<void> {\n    const gen = ++this._gen;\n    if (!element || element.tagName !== \"VIDEO\") {\n      this._setError({ message: \"target must be a <video> element.\" });\n      return;\n    }\n    // Re-wire to `element` before issuing the platform call: a caller may\n    // request a <video> different from the one last passed to observe() (e.g.\n    // the Shell's target attribute pointed at nothing at connect time and the\n    // matching <video> was only inserted later, so no attributeChangedCallback\n    // ever re-resolved it). Without this, `_video` stays stale and\n    // `_syncActive()` below (and future enter/leave events) would never\n    // recognize `element` as this Core's target, leaving `active` permanently\n    // wrong even though the request succeeded (mirrors\n    // FullscreenCore.requestFullscreen()'s unconditional `this._resolvedTarget\n    // = element` assignment — docs/fullscreen-tag-design.md §6).\n    this.observe(element);\n    const fn = this._requestPictureInPictureFn(element);\n    if (!fn) {\n      this._setError({ message: \"Picture-in-Picture API is not supported.\" });\n      return;\n    }\n    try {\n      await fn.call(element);\n      if (gen !== this._gen) return; // stale\n      this._setError(null);\n      this._syncActive(); // belt-and-suspenders (mirrors FullscreenCore's _applyActive() on success)\n    } catch (e: any) {\n      if (gen !== this._gen) return; // stale\n      this._setError(e); // e.g. NotAllowedError (gesture-context rejection)\n    }\n  }\n\n  /**\n   * Exit Picture-in-Picture. Mirrors FullscreenCore.exitFullscreen(): a\n   * silent no-op (resolve, no error) when nothing is currently in\n   * Picture-in-Picture — see fullscreen-tag-design.md §7.\n   */\n  async exitPictureInPicture(): Promise<void> {\n    // no-op checks come BEFORE the generation bump: a call that does nothing\n    // must not supersede an in-flight requestPictureInPicture() — bumping\n    // first would make the pending request's settle handling stale and\n    // silently swallow its error update (mirrors\n    // FullscreenCore.exitFullscreen()).\n    if (this._pictureInPictureElement() === null) return; // already not in PiP: silent no-op\n    const fn = this._exitPictureInPictureFn();\n    if (!fn) return; // unsupported: silent no-op (semantically already \"not in PiP\")\n    const gen = ++this._gen;\n    try {\n      await fn();\n      if (gen !== this._gen) return;\n      this._setError(null);\n      this._syncActive(); // belt-and-suspenders (mirrors FullscreenCore.exitFullscreen()'s success-path _applyActive()); covers a delayed/dropped leavepictureinpicture\n    } catch (e: any) {\n      if (gen !== this._gen) return;\n      this._setError(e);\n    }\n  }\n\n  // --- Internal: API resolution (call-time, never cached — §3.7) ---\n\n  // Unlike FullscreenCore's _elementFullscreenFn(), a naive direct property\n  // lookup (`e.requestPictureInPicture`, walking the prototype chain) here is\n  // safe: it cannot recurse into the Shell's own command method,\n  // because the resolved target is validated to be a <video> element (§2)\n  // before this is called, and <wcs-pip> (the Shell) is never itself a\n  // <video>. Fullscreen's own→Element.prototype two-step resolution guards\n  // against `target=\"self\"`/no-target resolving to the Shell element, which\n  // cannot happen here.\n  private _requestPictureInPictureFn(el: HTMLVideoElement): (() => Promise<PictureInPictureWindow>) | undefined {\n    const e = el as any;\n    return typeof e.requestPictureInPicture === \"function\" ? e.requestPictureInPicture : undefined;\n  }\n\n  private _exitPictureInPictureFn(): (() => Promise<void>) | undefined {\n    const d = document as any;\n    return typeof d.exitPictureInPicture === \"function\" ? d.exitPictureInPicture.bind(document) : undefined;\n  }\n\n  private _pictureInPictureElement(): Element | null {\n    const d = document as any;\n    return d.pictureInPictureElement ?? null;\n  }\n\n  // --- Internal: event wiring ---\n\n  private _onEnter = (): void => {\n    this._syncActive();\n  };\n\n  private _onLeave = (): void => {\n    this._syncActive();\n  };\n\n  private _syncActive(): void {\n    const isActive = this._video !== null && this._pictureInPictureElement() === this._video;\n    this._setActive(isActive);\n  }\n\n  private _detach(): void {\n    if (this._video) {\n      this._video.removeEventListener(\"enterpictureinpicture\", this._onEnter);\n      this._video.removeEventListener(\"leavepictureinpicture\", this._onLeave);\n    }\n  }\n\n  // --- State setters with event dispatch (§3.3 same-value guard) ---\n\n  private _setActive(active: boolean): void {\n    if (this._active === active) return;\n    this._active = active;\n    this._target.dispatchEvent(new CustomEvent(\"wcs-pip:change\", {\n      detail: { active },\n      bubbles: true,\n    }));\n  }\n\n  private _setError(error: any): void {\n    this._error = error;\n  }\n}\n","import { IWcBindable } from \"../types.js\";\nimport { PipCore } from \"../core/PipCore.js\";\n\n/**\n * `<wcs-pip target=\"...\">` — declarative Picture-in-Picture control.\n *\n * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0/§1), this Shell\n * does not operate on itself: it is a non-visible control tag that resolves a\n * `target` element and invokes Picture-in-Picture commands against it. The\n * `target` attribute resolves in the same 3 modes as `intersection`/`fullscreen`\n * (`self` / a selector / the first element child), reused verbatim from\n * `@wcstack/intersection`'s `_resolveTarget()`/`_safeQuery()`\n * (packages/intersection/src/components/Intersect.ts).\n *\n * Picture-in-Picture-specific difference (docs/picture-in-picture-tag-design.md\n * §2): the resolved target must be a `<video>` element. This Shell resolves the\n * DOM element and hands it to the Core; the Core performs the `tagName ===\n * \"VIDEO\"` validation (never-throw — a mismatch is treated as an unresolved\n * target and reported via `error`, not thrown).\n */\nexport class WcsPip extends HTMLElement {\n  // SSR (§4.4): observe() completes synchronously, but the Shell still exposes\n  // connectedCallbackPromise so the state binder can await it uniformly across\n  // all IO nodes before snapshotting.\n  static hasConnectedCallbackPromise = true;\n\n  static observedAttributes = [\"target\"];\n\n  static wcBindable: IWcBindable = {\n    ...PipCore.wcBindable,\n    inputs: [{ name: \"target\", attribute: \"target\" }],\n    // Core の commands をそのまま継承（単一情報源）。fullscreen/intersection と同型。\n    commands: PipCore.wcBindable.commands,\n  };\n\n  private _core: PipCore;\n  private _connectedCallbackPromise: Promise<void> = Promise.resolve();\n\n  constructor() {\n    super();\n    this._core = new PipCore(this);\n  }\n\n  get connectedCallbackPromise(): Promise<void> {\n    return this._connectedCallbackPromise;\n  }\n\n  // --- Attribute accessors ---\n\n  get target(): string {\n    return this.getAttribute(\"target\") ?? \"\";\n  }\n\n  set target(value: string) {\n    this.setAttribute(\"target\", value);\n  }\n\n  // --- Core delegated getters ---\n\n  get active(): boolean {\n    return this._core.active;\n  }\n\n  get error(): any {\n    return this._core.error;\n  }\n\n  // --- Commands ---\n\n  async requestPictureInPicture(): Promise<void> {\n    const { element } = this._resolveVideoTarget();\n    return this._core.requestPictureInPicture(element);\n  }\n\n  async exitPictureInPicture(): Promise<void> {\n    return this._core.exitPictureInPicture();\n  }\n\n  // --- Internal ---\n\n  /**\n   * `_resolveTarget()`/`_safeQuery()` copied verbatim from `@wcstack/intersection`\n   * (packages/intersection/src/components/Intersect.ts:243-267, 281-287) per the\n   * fullscreen/picture-in-picture batch's shared target-resolution archetype\n   * (docs/fullscreen-tag-design.md §1).\n   */\n  private _resolveTarget(): { element: Element | null; display: string } {\n    const target = this.target;\n    if (target === \"self\") {\n      return { element: this, display: \"block\" };\n    }\n    if (target !== \"\") {\n      const scope = this.getRootNode() as Document | ShadowRoot;\n      return { element: this._safeQuery(scope, target), display: \"none\" };\n    }\n    const child = this.firstElementChild;\n    if (child) {\n      return { element: child, display: \"contents\" };\n    }\n    return { element: this, display: \"block\" };\n  }\n\n  private _safeQuery(scope: Document | ShadowRoot, selector: string): Element | null {\n    try {\n      return scope.querySelector(selector);\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Layers the Picture-in-Picture-specific `tagName === \"VIDEO\"` check on top\n   * of `_resolveTarget()` (docs/picture-in-picture-tag-design.md §2). A\n   * resolved-but-wrong-tag element is treated as unresolved (`element: null`)\n   * so it flows into the same \"target not found\" failure path as Fullscreen's\n   * missing-target case — never-throw, no exception escapes.\n   */\n  private _resolveVideoTarget(): { element: HTMLVideoElement | null; display: string } {\n    const { element, display } = this._resolveTarget();\n    if (element !== null && element.tagName !== \"VIDEO\") {\n      return { element: null, display };\n    }\n    return { element: element as HTMLVideoElement | null, display };\n  }\n\n  private _observe(): void {\n    const { element, display } = this._resolveVideoTarget();\n    this.style.display = display;\n    this._connectedCallbackPromise = this._core.observe(element);\n  }\n\n  // --- Lifecycle ---\n\n  connectedCallback(): void {\n    this._observe();\n  }\n\n  disconnectedCallback(): void {\n    this._core.dispose();\n  }\n\n  attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void {\n    if (oldValue === newValue) return;\n    if (!this.isConnected) return;\n    this._observe();\n  }\n}\n","import { setConfig } from \"./config.js\";\nimport { registerComponents } from \"./registerComponents.js\";\nimport { IWritableConfig } from \"./types.js\";\n\nexport function bootstrapPip(userConfig?: IWritableConfig): void {\n  if (userConfig) {\n    setConfig(userConfig);\n  }\n  registerComponents();\n}\n","import { WcsPip } from \"./components/Pip.js\";\nimport { config } from \"./config.js\";\n\nexport function registerComponents(): void {\n  if (!customElements.get(config.tagNames.pip)) {\n    customElements.define(config.tagNames.pip, WcsPip);\n  }\n}\n"],"names":["_config","tagNames","pip","deepFreeze","obj","Object","freeze","key","keys","deepClone","clone","frozenConfig","config","getConfig","PipCore","EventTarget","static","protocol","version","properties","name","event","getter","e","detail","active","commands","async","_target","_active","_error","_video","_gen","_ready","Promise","resolve","constructor","target","super","this","ready","error","observe","element","_detach","addEventListener","_onEnter","_onLeave","_syncActive","dispose","requestPictureInPicture","gen","tagName","_setError","message","fn","_requestPictureInPictureFn","call","exitPictureInPicture","_pictureInPictureElement","_exitPictureInPictureFn","el","undefined","d","document","bind","pictureInPictureElement","isActive","_setActive","removeEventListener","dispatchEvent","CustomEvent","bubbles","WcsPip","HTMLElement","wcBindable","inputs","attribute","_core","_connectedCallbackPromise","connectedCallbackPromise","getAttribute","value","setAttribute","_resolveVideoTarget","_resolveTarget","display","scope","getRootNode","_safeQuery","child","firstElementChild","selector","querySelector","_observe","style","connectedCallback","disconnectedCallback","attributeChangedCallback","_name","oldValue","newValue","isConnected","bootstrapPip","userConfig","partialConfig","assign","customElements","get","define"],"mappings":"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"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@wcstack/picture-in-picture",
+  "version": "1.16.0",
+  "description": "Declarative Picture-in-Picture component for Web Components. Framework-agnostic <video> Picture-in-Picture control via wc-bindable-protocol.",
+  "type": "module",
+  "main": "./dist/index.esm.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js"
+    },
+    "./auto": "./dist/auto.min.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist .tsc-out",
+    "build": "rimraf dist .tsc-out && tsc && rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "prepublishOnly": "npm run build && npm run test:coverage"
+  },
+  "keywords": [
+    "web-components",
+    "picture-in-picture",
+    "video",
+    "media",
+    "custom-elements",
+    "wc-bindable",
+    "declarative",
+    "zero-dependencies",
+    "framework-agnostic"
+  ],
+  "author": "mogera551",
+  "homepage": "https://wcstack.github.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wcstack/wcstack.git",
+    "directory": "packages/picture-in-picture"
+  },
+  "bugs": {
+    "url": "https://github.com/wcstack/wcstack/issues"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/ui": "^4.0.15",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
+    "happy-dom": "^20.0.11",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.22.4",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-copy": "^3.5.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.49.0",
+    "vitest": "^4.0.15"
+  }
+}