@wcstack/pointer-lock 1.16.0

package/README.ja.md

@@ -0,0 +1,143 @@
+# @wcstack/pointer-lock
+
+`@wcstack/pointer-lock` は wcstack エコシステム向けのヘッドレスな Pointer Lock API コンポーネントです。
+
+視覚的な UI ウィジェットではありません。
+`@wcstack/fullscreen` が Fullscreen API のアクティブ状態をリアクティブな state に変えるのと同じように、Pointer Lock API のロック状態をリアクティブな state に変える **非同期プリミティブノード** です。
+
+`@wcstack/state` と組み合わせると、`<wcs-pointer-lock>` はパス契約で直接バインドできます:
+
+- **入力サーフェス**: `target`
+- **出力 state サーフェス**: `active`、`error`
+- **コマンド**: `requestPointerLock`、`exitPointerLock`
+
+`@wcstack/pointer-lock` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います:
+
+- **Core**（`PointerLockCore`）が `Element.requestPointerLock()` / `document.exitPointerLock()` / `document.pointerLockElement` をラップし、`document`単位で発火する `pointerlockchange` イベントを自身が解決した target と自己判定でフィルタする
+- **Shell**（`<wcs-pointer-lock target="...">`）がDOMから「どの要素を操作するか」を解決し、display とライフサイクルを管理
+- **Binding Contract**（`static wcBindable`）が観測可能な `active` プロパティと `requestPointerLock`/`exitPointerLock` コマンドを宣言
+
+## 用途が限定的なノード — 使う前に必ず読んでください
+
+他の大半の wcstack IO ノードと異なり、`<wcs-pointer-lock>` は本プロジェクトの主眼である**宣言的な SPA UI 構築**を主たる対象としていません。Pointer Lock API の実際の用途はほぼ排他的に、マウスの**相対移動量**（`movementX`/`movementY`）を必要とする**ゲームや canvas/WebGL 描画 UI**（FPS視点操作、お絵描きツールのパン操作等）に限られます。こうした利用者は多くの場合すでに命令的な `requestAnimationFrame` ループを回しており、動画プレイヤーが `<wcs-fullscreen>` を使う場合ほど、入力を宣言的なバインディング層経由にする動機は強くありません。
+
+このノードは「ロックのON/OFFを切り替える宣言的なスイッチ」（例: command-token プロトコル経由の「マウスルック有効化」ボタン）が欲しい場合に使ってください。`movementX`/`movementY` の取得源としては使えません（後述）。
+
+## `movementX`/`movementY` はスコープ外（v1）
+
+ポインタロック中に発火する `mousemove` イベントは `movementX`/`movementY`（相対移動量）を持ちますが、**本Coreは現時点のいかなるバージョンでもこれを公開しません。** これらは高頻度データ（環境によっては毎秒数百イベントに達しうる）であり、本プロトコルが前提とする同値ガード付きの宣言的 `properties` モデルに馴染みません。そのまま `wc-bindable` に流すと、バインドされた state を毎フレーム単位の更新で溢れさせるリスクがあります。
+
+将来のバージョンで追加する場合の設計意図（`docs/pointer-lock-tag-design.md` §3 参照）は、明示的な opt-in の背後に置き、`@wcstack/debounce`/`@wcstack/throttle` と組み合わせてレート制限することです。これにより、opt-in していないインスタンスには「無制限のファイアホースを流さない」という性質を保てます。現時点で生の `movementX`/`movementY` が必要な場合は、本ノードの `active` state と並行して、自前の命令的コードで `mousemove` を直接読んでください。
+
+## `target` 属性がロック対象を決める
+
+`@wcstack/fullscreen` と同様、この Shell は**自分自身をロックしません** — `target` 属性で指し示した**参照先の要素**を操作する非表示の制御タグであり、`@wcstack/intersection` と同じ3モード解決を使います:
+
+| `target`         | 操作対象                  | `display`   |
+|------------------|--------------------------|-------------|
+| 省略             | 先頭の子要素              | `contents`  |
+| `"#selector"`    | 一致した要素               | `none`      |
+| `"self"`         | 自分自身                  | `block`     |
+
+## インストール
+
+```bash
+npm install @wcstack/pointer-lock
+```
+
+## クイックスタート
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/pointer-lock/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["lockPointer", "unlockPointer"],
+      locked: false,
+    };
+  </script>
+</wcs-state>
+
+<canvas id="scene" width="640" height="480"></canvas>
+<wcs-pointer-lock target="#scene"
+  data-wcs="active: locked; command.requestPointerLock: $command.lockPointer; command.exitPointerLock: $command.unlockPointer">
+</wcs-pointer-lock>
+
+<button data-wcs="onclick: $command.lockPointer">マウスルックを有効化</button>
+<button data-wcs="hidden: locked|not; onclick: $command.unlockPointer">解除</button>
+```
+
+ボタンは`<wcs-pointer-lock>`に直接触れません。クリックが`lockPointer`/`unlockPointer`コマンドトークンを発行し、`<wcs-pointer-lock>`が`command.requestPointerLock: $command.lockPointer` / `command.exitPointerLock: $command.unlockPointer`でそれを購読します（[command-tokenプロトコル](../state/) — commandメソッドを持つ要素が*購読者*であり、発行者ではありません）。
+
+バインドするstateパスは事前にすべて宣言する必要があります — ここでは`locked: false`。未宣言パスをバインドすると初期化時に例外になります。`data-wcs`パス内の否定は先頭`!`ではなく`|not`フィルタ（`locked|not`）で行います — パスはプレフィックス演算子をサポートしません。
+
+`requestPointerLock()` は **user gesture 文脈を必須とします** — 後述。
+
+## user gesture 制約
+
+`Element.requestPointerLock()` はuser gesture文脈（同期的なクリックハンドラ等）の外から呼ばれると `NotAllowedError` で reject します。本ノードは自らgestureを生成できません。**実際のuser gesture内から`requestPointerLock`を呼ぶ責務は呼び出し元にあります。** command-token プロトコル（`<wcs-pointer-lock>`上の`command.requestPointerLock: $command.<token>`、ボタンの`onclick: $command.<token>`が発行する）を配線してください — `setTimeout`内や`.then()`チェーンの奥から呼ぶとgesture文脈を失い呼び出しがrejectされますが、例外は伝播しません（never-throw、`error`に格納されます）。
+
+## 観測可能プロパティ（出力）
+
+| プロパティ | イベント                    | 説明 |
+| ---------- | ---------------------------- | ------------ |
+| `active`   | `wcs-pointer-lock:change`    | `document.pointerLockElement` がこのインスタンスの解決済み target と一致していれば `true`、それ以外は `false`。 |
+
+`error`（後述コマンド参照）は単純な getter として公開され、`wcBindable` の property ではありません — コマンド呼び出しの副作用としてのみ変化します（`@wcstack/fullscreen` と同型）。直近の失敗は次のいずれか: rejectされたPromise（gesture外呼び出しなら`NotAllowedError`等）、プラットフォームAPI非対応なら`{ message: "Pointer Lock API is not supported." }`、`target`が要素へ未解決なら`{ message: "Pointer Lock target could not be resolved." }`。直近の呼び出しが成功済み・まだ何も失敗していない場合は`null`。
+
+## コマンド
+
+| コマンド              | Async | 説明 |
+| --------------------- | ----- | ------------ |
+| `requestPointerLock`  | あり  | `target`を解決し、それに対して`requestPointerLock()`を呼びます。never-throw: 失敗（targetが未解決、gesture不在の`NotAllowedError`、非対応API等）は例外でなく `error` に格納されます。 |
+| `exitPointerLock`     | **無し** | `document.exitPointerLock()` を呼びます。**同期API** — `@wcstack/fullscreen`の`exitFullscreen()`（Promiseベース）と異なり、`exitPointerLock()`は`void`を返します。何もロックされていない、またはAPI非対応時はsilent no-opです。 |
+
+## 属性 / 入力
+
+| 属性      | 説明 |
+| --------- | ------------ |
+| `target`  | ロック対象の要素を指すセレクタ（または`"self"`）。上記「`target`属性がロック対象を決める」を参照。省略時は先頭の子要素。 |
+
+## 複数インスタンス — 「documentがロック中か」ではなくインスタンスごとに`active`を見る
+
+`document.pointerLockElement` はdocument全体で単一の値しか持ちません（同時にロックできる要素は高々1つ）。複数の`<wcs-pointer-lock>`インスタンス（例: `target="#a"`と`target="#b"`）が同時に存在する場合、各インスタンスは`document.pointerLockElement`を**自分自身の**解決済みtargetと比較します（単に「documentがロック中か」ではありません）。`#a`をロックすると、`target="#a"`のインスタンスは`active: true`、`target="#b"`のインスタンスは`active: false`を報告します — document全体では何か（`#a`）がロックされているにもかかわらずです。
+
+## ベンダープレフィックス
+
+一部の古いWebKit実装は標準名の代わりに`webkitRequestPointerLock`/`webkitExitPointerLock`/`webkitPointerLockElement`/`webkitpointerlockchange`イベントを公開します。API解決は**呼び出し時**（キャッシュしない）に行われ、標準名を優先し、無ければレガシー名にフォールバックします — これにより非対応環境（どちらの名前も存在しない）を正しく検出でき、テストがAPIを自由にinstall/removeできます。
+
+## 注意・制限
+
+- **user gesture が必須。** 上記参照 — プラットフォームの制約であり、本ノードで回避する手段はありません。
+- **`exitPointerLock()`は同期API**、`@wcstack/fullscreen`のPromiseベースの`exitFullscreen()`とは異なります。単独の`_gen`世代ガードは持ちません（非同期の`requestPointerLock()`のみがガードを必要とします）。それでも非準拠実装が例外を投げないよう防御的に`try/catch`で包んでいます。
+- **`movementX`/`movementY`はv1ではスコープ外。** 上記参照。
+- **autoTriggerなし。** `requestPointerLock()`はuser gesture文脈を必要とするため、主な起動経路は`data-*target`のクリックショートカットではなくcommand-tokenプロトコル（`<wcs-pointer-lock>`上の`command.requestPointerLock: $command.<token>`）です。
+- **SSR（`@wcstack/server`）。** `static hasConnectedCallbackPromise = true`を宣言し`connectedCallbackPromise`を公開します。`observe()`が同期的なため、このpromiseは常に即座にsettleします。
+
+## ヘッドレス利用（`PointerLockCore`）
+
+CoreはDOM非依存（Pointer Lockプラットフォーム APIの呼び出しを除く）で、`@wc-bindable/core`の`bind()`と直接使えます:
+
+```typescript
+import { PointerLockCore } from "@wcstack/pointer-lock";
+
+const lock = new PointerLockCore();
+lock.addEventListener("wcs-pointer-lock:change", (e) => {
+  console.log((e as CustomEvent).detail); // boolean —新しい active 値そのもの
+});
+
+const canvas = document.querySelector("#scene")!;
+lock.observe(canvas);              // document の pointerlockchange を購読し、canvas に対して自己判定
+await lock.requestPointerLock(canvas); // user gesture 内から呼ぶ必要がある
+console.log(lock.active, lock.error);
+
+// 後始末:
+lock.exitPointerLock();  // 同期的
+lock.dispose();          // document リスナーを外す
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,143 @@
+# @wcstack/pointer-lock
+
+`@wcstack/pointer-lock` is a headless Pointer Lock API component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns the Pointer Lock API's lock state into reactive state — the same way `@wcstack/fullscreen` turns the Fullscreen API's active state into reactive state.
+
+With `@wcstack/state`, `<wcs-pointer-lock>` can be bound directly through path contracts:
+
+- **input surface**: `target`
+- **output state surface**: `active`, `error`
+- **commands**: `requestPointerLock`, `exitPointerLock`
+
+`@wcstack/pointer-lock` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`PointerLockCore`) wraps `Element.requestPointerLock()` / `document.exitPointerLock()` / `document.pointerLockElement`, self-filtering the `document`-scoped `pointerlockchange` event against its own resolved target
+- **Shell** (`<wcs-pointer-lock target="...">`) resolves *which* element to operate on from the DOM, manages display and lifecycle
+- **Binding Contract** (`static wcBindable`) declares the observable `active` property and the `requestPointerLock`/`exitPointerLock` commands
+
+## A narrow-purpose node — read this before reaching for it
+
+Unlike most wcstack IO nodes, `<wcs-pointer-lock>` is **not** aimed at the project's main use case of building declarative SPA UI. The Pointer Lock API's real-world usage is almost exclusively **games and canvas/WebGL rendering UI** that need the mouse's *relative* movement (`movementX`/`movementY`) — first-person camera controls, drawing-tool panning, and similar. Those consumers typically already run an imperative `requestAnimationFrame` loop and have less reason to route input through a declarative binding layer than, say, a video player reaching for `<wcs-fullscreen>`.
+
+Reach for this node when you need a declarative *lock on/off* switch (e.g. a "Enable mouse look" button wired via the command-token protocol) — not as a source of `movementX`/`movementY` data. See below.
+
+## `movementX`/`movementY` are out of scope (v1)
+
+`mousemove` events fired while the pointer is locked carry `movementX`/`movementY` deltas. **This Core does not expose them, in any version up to this one.** They are high-frequency data (potentially hundreds of events/sec) that do not fit the same-value-guarded, declarative `properties` model this protocol is built around — piping them through `wc-bindable` as-is would risk flooding the bound state with per-frame updates.
+
+If a future version adds them, the design intent (see `docs/pointer-lock-tag-design.md` §3) is to gate them behind an explicit opt-in and pair them with `@wcstack/debounce`/`@wcstack/throttle` for rate-limiting, keeping the "no unbounded firehose" property intact for instances that don't opt in. For now, if you need raw `movementX`/`movementY`, read them directly off `mousemove` in your own imperative code alongside this node's `active` state.
+
+## The `target` attribute decides what is locked
+
+Like `@wcstack/fullscreen`, this Shell does not lock *itself* — it is a hidden control tag that operates on a **referenced element** via the `target` attribute, using the same 3-mode resolution as `@wcstack/intersection`:
+
+| `target`         | operates on            | `display`   |
+|------------------|--------------------------|-------------|
+| *omitted*        | first element child      | `contents`  |
+| `"#selector"`    | the matched element       | `none`      |
+| `"self"`         | the element itself        | `block`     |
+
+## Install
+
+```bash
+npm install @wcstack/pointer-lock
+```
+
+## Quick Start
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/pointer-lock/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["lockPointer", "unlockPointer"],
+      locked: false,
+    };
+  </script>
+</wcs-state>
+
+<canvas id="scene" width="640" height="480"></canvas>
+<wcs-pointer-lock target="#scene"
+  data-wcs="active: locked; command.requestPointerLock: $command.lockPointer; command.exitPointerLock: $command.unlockPointer">
+</wcs-pointer-lock>
+
+<button data-wcs="onclick: $command.lockPointer">Enable mouse look</button>
+<button data-wcs="hidden: locked|not; onclick: $command.unlockPointer">Release</button>
+```
+
+The buttons never touch `<wcs-pointer-lock>` directly: their clicks emit the `lockPointer`/`unlockPointer` command tokens, and `<wcs-pointer-lock>` subscribes to them via `command.requestPointerLock: $command.lockPointer` / `command.exitPointerLock: $command.unlockPointer` (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 — `locked: false` here; binding an undeclared path throws at initialization. Negation in a `data-wcs` path is done with the `|not` filter (`locked|not`), not a leading `!` — paths do not support prefix operators.
+
+`requestPointerLock()` **requires a user-gesture context** — see below.
+
+## User gesture requirement
+
+`Element.requestPointerLock()` rejects with `NotAllowedError` when called outside a user-gesture context (e.g. a synchronous click handler). This node cannot manufacture a gesture on your behalf: **the responsibility for calling `requestPointerLock` from within an actual user gesture belongs to the caller.** Wire the command-token protocol (`command.requestPointerLock: $command.<token>` on `<wcs-pointer-lock>`, emitted by a button's `onclick: $command.<token>`) — calling it from a `setTimeout` or deep inside a `.then()` chain loses the gesture context and the call will reject, `error` will be set, but no exception will propagate (never-throw).
+
+## Observable Properties (outputs)
+
+| Property   | Event                       | Description |
+| ---------- | ---------------------------- | ------------ |
+| `active`   | `wcs-pointer-lock:change`    | `true` when `document.pointerLockElement` is this instance's resolved target, `false` otherwise. |
+
+`error` (see Commands below) is exposed as a plain getter, not as a `wcBindable` property — it only changes as a side effect of a command call, mirroring `@wcstack/fullscreen`. The most recent failure is one of: a rejected promise (e.g. `NotAllowedError` for a gesture-less call), `{ message: "Pointer Lock API is not supported." }` when the platform API is missing, `{ message: "Pointer Lock target could not be resolved." }` when `target` did not resolve to an element, or `null` if the last attempt succeeded / nothing has failed yet.
+
+## Commands
+
+| Command              | Async | Description |
+| --------------------- | ----- | ------------ |
+| `requestPointerLock`  | yes   | Resolve `target` and call `requestPointerLock()` on it. Never-throw: failures (an unresolvable `target`, `NotAllowedError` for a missing gesture, or an unsupported API) are captured into `error`, not thrown. |
+| `exitPointerLock`     | **no**| Calls `document.exitPointerLock()`. **Synchronous** — unlike `@wcstack/fullscreen`'s `exitFullscreen()` (which is Promise-based), `exitPointerLock()` returns `void`. Silent no-op if nothing is currently locked or the API is unsupported. |
+
+## Attributes / Inputs
+
+| Attribute | Description |
+| --------- | ------------ |
+| `target`  | Selector (or `"self"`) identifying the element to lock. See "The `target` attribute decides what is locked" above. Omitted → first element child. |
+
+## Multiple instances — read `active` per-instance, not "is *anything* locked"
+
+`document.pointerLockElement` is a single document-wide value — at most one element can be locked at a time. When several `<wcs-pointer-lock>` instances exist simultaneously (e.g. `target="#a"` and `target="#b"`), each instance compares `document.pointerLockElement` against **its own** resolved target, not merely "is the document locked". Locking `#a` makes the `target="#a"` instance report `active: true` and the `target="#b"` instance report `active: false` — even though *some* element (`#a`) is locked document-wide.
+
+## Vendor prefixes
+
+Some older WebKit builds expose `webkitRequestPointerLock` / `webkitExitPointerLock` / `webkitPointerLockElement` / the `webkitpointerlockchange` event instead of the standard names. API resolution happens **at call time** (never cached), probing the standard name first and falling back to the legacy name — this lets an unsupported environment (neither name present) be detected correctly and lets tests install/remove the API freely.
+
+## Notes & limitations
+
+- **User gesture required.** See above — this is a platform constraint, not something this node can work around.
+- **`exitPointerLock()` is synchronous**, unlike `@wcstack/fullscreen`'s Promise-based `exitFullscreen()`. It carries no `_gen` generation guard of its own (only `requestPointerLock()`, being asynchronous, needs one); it is still wrapped in `try/catch` defensively so a non-conformant implementation can never throw out of it.
+- **`movementX`/`movementY` are out of scope for v1.** See above.
+- **No autoTrigger.** Because `requestPointerLock()` needs a user-gesture context, the primary activation path is the command-token protocol (`command.requestPointerLock: $command.<token>` on `<wcs-pointer-lock>`) rather than a `data-*target` click shortcut.
+- **SSR (`@wcstack/server`).** Declares `static hasConnectedCallbackPromise = true` and exposes `connectedCallbackPromise`; since `observe()` is synchronous, this promise always settles immediately.
+
+## Headless usage (`PointerLockCore`)
+
+The Core has no DOM dependency (beyond calling the Pointer Lock platform API) and can be used directly with `bind()` from `@wc-bindable/core`:
+
+```typescript
+import { PointerLockCore } from "@wcstack/pointer-lock";
+
+const lock = new PointerLockCore();
+lock.addEventListener("wcs-pointer-lock:change", (e) => {
+  console.log((e as CustomEvent).detail); // boolean — the new `active` value directly
+});
+
+const canvas = document.querySelector("#scene")!;
+lock.observe(canvas);              // subscribe to document pointerlockchange, self-filtering on `canvas`
+await lock.requestPointerLock(canvas); // must be called from within a user gesture
+console.log(lock.active, lock.error);
+
+// later, when done:
+lock.exitPointerLock();  // synchronous
+lock.dispose();          // detach the document listener
+```
+
+## License
+
+MIT

package/dist/auto.js

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

package/dist/auto.min.js

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

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+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 pointerLock: string;
+}
+interface IWritableTagNames {
+    pointerLock?: string;
+}
+interface IConfig {
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    tagNames?: IWritableTagNames;
+}
+
+/**
+ * Value types for PointerLockCore (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/pointer-lock-tag-design.md §2, docs/fullscreen-tag-design.md §8).
+ *
+ * @example
+ * ```typescript
+ * const core = new PointerLockCore();
+ * // bind() only ever delivers "active" — see the note above about "error".
+ * bind(core, (name: keyof WcsPointerLockCoreValues, value) => { ... });
+ * ```
+ */
+interface WcsPointerLockCoreValues {
+    active: boolean;
+    error: any;
+}
+/**
+ * Value types for the Shell (`<wcs-pointer-lock>`) — identical value surface
+ * to the Core (same caveat: only `active` is observable). The Shell
+ * additionally accepts a `target` attribute
+ * (see docs/pointer-lock-tag-design.md / docs/fullscreen-tag-design.md §1).
+ */
+type WcsPointerLockValues = WcsPointerLockCoreValues;
+
+declare function bootstrapPointerLock(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+/**
+ * Headless Pointer Lock primitive. A thin, framework-agnostic wrapper around
+ * the Pointer Lock API (`Element.requestPointerLock()` /
+ * `document.exitPointerLock()` / `document.pointerLockElement` / the
+ * `document`-scoped `pointerlockchange` event) exposed through the
+ * wc-bindable protocol.
+ *
+ * This Core follows the same basic pattern as `FullscreenCore`
+ * (docs/fullscreen-tag-design.md, referenced by docs/pointer-lock-tag-design.md
+ * §1): target resolution happens in the Shell, `pointerlockchange` is
+ * subscribed on `document` (not on the target element) and each instance
+ * self-filters by comparing `document.pointerLockElement` against its own
+ * resolved target, API resolution is call-time (never cached) and probes the
+ * standard name before the legacy (`webkit`-prefixed) name, and a single
+ * Core-level `_gen` generation guard protects the asynchronous
+ * `requestPointerLock()` call from stale resolution after dispose().
+ *
+ * Key difference from Fullscreen (docs/pointer-lock-tag-design.md §2):
+ * `exitPointerLock()` is a *synchronous* platform API (it returns `void`, not
+ * a `Promise`), so the Core's `exitPointerLock()` command is synchronous too
+ * and carries no `_gen` guard of its own — it is wrapped in `try/catch` only
+ * as a defensive measure (never-throw), not because it can go stale.
+ *
+ * Scope note (docs/pointer-lock-tag-design.md §3): `movementX`/`movementY`
+ * are intentionally NOT exposed by this Core (v1 scope). They are
+ * high-frequency `mousemove` data unsuited to the same-value-guarded
+ * declarative `properties` surface; see the design doc for the rationale and
+ * the planned `debounce`/`throttle`-based opt-in for a future version.
+ */
+declare class PointerLockCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _active;
+    private _error;
+    private _resolvedTarget;
+    private _subscribed;
+    private _gen;
+    private _ready;
+    constructor(target?: EventTarget);
+    get ready(): Promise<void>;
+    get active(): boolean;
+    get error(): any;
+    observe(target: Element | null): Promise<void>;
+    dispose(): void;
+    /**
+     * Request pointer lock on `element`. Never-throw: a missing API or a
+     * rejected promise (e.g. called outside a user-gesture context —
+     * `NotAllowedError`, docs/fullscreen-tag-design.md §3) is captured into
+     * `error` rather than propagated. `element` may be `null` when the Shell's
+     * `target` selector did not resolve (docs/pointer-lock-tag-design.md §1
+     * defers error representation to FullscreenCore verbatim — this null-target
+     * case mirrors `FullscreenCore.requestFullscreen(null)`,
+     * docs/fullscreen-tag-design.md §6): distinct from "API is not supported"
+     * below, so a typo'd selector doesn't masquerade as an unsupported platform.
+     */
+    requestPointerLock(element: Element | null): Promise<void>;
+    /**
+     * Exit pointer lock. Synchronous platform API (docs/pointer-lock-tag-design.md
+     * §2) — returns `void`, not a `Promise`. Silent no-op when nothing is
+     * currently locked or the API is unsupported (mirrors
+     * `FullscreenCore.exitFullscreen()`'s no-op contract,
+     * docs/fullscreen-tag-design.md §7). Wrapped in try/catch defensively: even
+     * though the platform API is synchronous and documented as not throwing in
+     * this case, a synchronous throw from a non-conformant/fake implementation
+     * must never escape (never-throw).
+     */
+    exitPointerLock(): void;
+    private _requestPointerLockFn;
+    private _exitPointerLockFn;
+    private _pointerLockElement;
+    private _pointerLockChangeEventName;
+    private _onChange;
+    private _applyActive;
+    private _setActive;
+    private _setError;
+}
+
+/**
+ * `<wcs-pointer-lock target="...">` — declarative Pointer Lock API control.
+ *
+ * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0), this Shell does
+ * not lock itself — it operates on a *referenced* element via the `target`
+ * attribute, using the same 3-mode resolution rule as `intersection`
+ * (`_resolveTarget()`/`_safeQuery()`, copied verbatim per
+ * docs/pointer-lock-tag-design.md §1 / docs/fullscreen-tag-design.md §1):
+ *
+ * | `target`        | operates on            | display     |
+ * |-----------------|-------------------------|-------------|
+ * | omitted         | first element child     | `contents`  |
+ * | `"#selector"`    | the matched element      | `none`      |
+ * | `"self"`         | the element itself       | `block`     |
+ *
+ * `requestPointerLock()` requires a user-gesture context (docs/fullscreen-tag-design.md
+ * §3) — the primary activation path is the command-token protocol
+ * (`command.requestPointerLock: $command.<token>` on `<wcs-pointer-lock>`,
+ * emitted by a button's `onclick: $command.<token>`), not an
+ * autoTrigger attribute (none is provided in v1,
+ * docs/pointer-lock-tag-design.md §4).
+ *
+ * `movementX`/`movementY` are intentionally out of scope for v1
+ * (docs/pointer-lock-tag-design.md §3) — do not add them without revisiting
+ * the design doc.
+ */
+declare class WcsPointerLock 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;
+    /**
+     * Resolve `target` and request pointer lock on it. Requires a user-gesture
+     * context. never-throw: an unresolvable target or an unsupported/rejected
+     * API call are both surfaced via `error`, never thrown (mirrors
+     * `<wcs-fullscreen>`'s `requestFullscreen()`, docs/fullscreen-tag-design.md
+     * §3/§6 — the Shell passes the (possibly `null`) resolved element straight
+     * through and lets the Core set `error`, rather than silently no-op'ing
+     * here).
+     */
+    requestPointerLock(): Promise<void>;
+    /** Exit pointer lock. Synchronous command — silent no-op if nothing is locked. */
+    exitPointerLock(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    private _applyDisplayAndObserve;
+    private _resolveTarget;
+    private _safeQuery;
+}
+
+export { PointerLockCore, WcsPointerLock, bootstrapPointerLock, getConfig };
+export type { IWritableConfig, IWritableTagNames, WcsPointerLockCoreValues, WcsPointerLockValues };

package/dist/index.esm.js

@@ -0,0 +1,416 @@
+const _config = {
+    tagNames: {
+        pointerLock: "wcs-pointer-lock",
+    },
+};
+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 Pointer Lock primitive. A thin, framework-agnostic wrapper around
+ * the Pointer Lock API (`Element.requestPointerLock()` /
+ * `document.exitPointerLock()` / `document.pointerLockElement` / the
+ * `document`-scoped `pointerlockchange` event) exposed through the
+ * wc-bindable protocol.
+ *
+ * This Core follows the same basic pattern as `FullscreenCore`
+ * (docs/fullscreen-tag-design.md, referenced by docs/pointer-lock-tag-design.md
+ * §1): target resolution happens in the Shell, `pointerlockchange` is
+ * subscribed on `document` (not on the target element) and each instance
+ * self-filters by comparing `document.pointerLockElement` against its own
+ * resolved target, API resolution is call-time (never cached) and probes the
+ * standard name before the legacy (`webkit`-prefixed) name, and a single
+ * Core-level `_gen` generation guard protects the asynchronous
+ * `requestPointerLock()` call from stale resolution after dispose().
+ *
+ * Key difference from Fullscreen (docs/pointer-lock-tag-design.md §2):
+ * `exitPointerLock()` is a *synchronous* platform API (it returns `void`, not
+ * a `Promise`), so the Core's `exitPointerLock()` command is synchronous too
+ * and carries no `_gen` guard of its own — it is wrapped in `try/catch` only
+ * as a defensive measure (never-throw), not because it can go stale.
+ *
+ * Scope note (docs/pointer-lock-tag-design.md §3): `movementX`/`movementY`
+ * are intentionally NOT exposed by this Core (v1 scope). They are
+ * high-frequency `mousemove` data unsuited to the same-value-guarded
+ * declarative `properties` surface; see the design doc for the rationale and
+ * the planned `debounce`/`throttle`-based opt-in for a future version.
+ */
+class PointerLockCore extends EventTarget {
+    static wcBindable = {
+        protocol: "wc-bindable",
+        version: 1,
+        // `active`'s CustomEvent detail is the bare boolean value itself — no
+        // getter needed (docs/pointer-lock-tag-design.md §2). This differs from
+        // FullscreenCore's `{ active }`-shaped detail + getter.
+        properties: [
+            { name: "active", event: "wcs-pointer-lock:change" },
+        ],
+        commands: [
+            { name: "requestPointerLock", async: true },
+            // Synchronous platform API (document.exitPointerLock() returns void) —
+            // no `async` flag (docs/pointer-lock-tag-design.md §2).
+            { name: "exitPointerLock" },
+        ],
+    };
+    _target;
+    _active = false;
+    _error = null;
+    // The element this instance last resolved requestPointerLock()/observe()
+    // against, kept so the document-scoped `pointerlockchange` handler can
+    // self-filter under multiple concurrent instances (docs/fullscreen-tag-design.md
+    // §2.1, inherited verbatim by pointer-lock per docs/pointer-lock-tag-design.md §1).
+    _resolvedTarget = null;
+    // True once observe() has attached the live `document` listener. Guards
+    // observe() so a redundant call does not re-subscribe; dispose() resets it
+    // so a later observe() resumes cleanly.
+    _subscribed = false;
+    // Core-level generation guard (§3.4 of the guidelines / §6 of
+    // fullscreen-tag-design.md): only requestPointerLock() is asynchronous and
+    // needs it. exitPointerLock() is synchronous and has no stale-resolution
+    // race to guard against.
+    _gen = 0;
+    // SSR (§3.8): no asynchronous probe to await — observe() completes
+    // synchronously, 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). Idempotent: a second observe() while already subscribed
+    // updates the tracked resolved target without re-subscribing to `document`.
+    observe(target) {
+        this._resolvedTarget = target;
+        if (!this._subscribed) {
+            this._subscribed = true;
+            document.addEventListener(this._pointerLockChangeEventName(), this._onChange);
+        }
+        this._applyActive();
+        return this._ready;
+    }
+    dispose() {
+        this._gen++; // invalidate any in-flight requestPointerLock() resolution
+        if (this._subscribed) {
+            this._subscribed = false;
+            document.removeEventListener(this._pointerLockChangeEventName(), this._onChange);
+        }
+        this._resolvedTarget = null;
+    }
+    /**
+     * Request pointer lock on `element`. Never-throw: a missing API or a
+     * rejected promise (e.g. called outside a user-gesture context —
+     * `NotAllowedError`, docs/fullscreen-tag-design.md §3) is captured into
+     * `error` rather than propagated. `element` may be `null` when the Shell's
+     * `target` selector did not resolve (docs/pointer-lock-tag-design.md §1
+     * defers error representation to FullscreenCore verbatim — this null-target
+     * case mirrors `FullscreenCore.requestFullscreen(null)`,
+     * docs/fullscreen-tag-design.md §6): distinct from "API is not supported"
+     * below, so a typo'd selector doesn't masquerade as an unsupported platform.
+     */
+    async requestPointerLock(element) {
+        const gen = ++this._gen;
+        this._resolvedTarget = element;
+        if (!element) {
+            this._setError({ message: "Pointer Lock target could not be resolved." });
+            return;
+        }
+        const fn = this._requestPointerLockFn(element);
+        if (!fn) {
+            // Resolved synchronously in the same tick as the call — dispose()
+            // cannot have run yet, so no staleness check is needed here (matches
+            // the reference `requestFullscreen()` implementation,
+            // docs/fullscreen-tag-design.md §6).
+            this._setError({ message: "Pointer Lock API is not supported." });
+            return;
+        }
+        try {
+            // fn is already bound to `element` by _requestPointerLockFn().
+            await fn();
+            if (gen !== this._gen)
+                return; // stale
+            this._setError(null);
+            this._applyActive();
+        }
+        catch (e) {
+            if (gen !== this._gen)
+                return; // stale
+            this._setError(e);
+        }
+    }
+    /**
+     * Exit pointer lock. Synchronous platform API (docs/pointer-lock-tag-design.md
+     * §2) — returns `void`, not a `Promise`. Silent no-op when nothing is
+     * currently locked or the API is unsupported (mirrors
+     * `FullscreenCore.exitFullscreen()`'s no-op contract,
+     * docs/fullscreen-tag-design.md §7). Wrapped in try/catch defensively: even
+     * though the platform API is synchronous and documented as not throwing in
+     * this case, a synchronous throw from a non-conformant/fake implementation
+     * must never escape (never-throw).
+     */
+    exitPointerLock() {
+        try {
+            if (this._pointerLockElement() === null)
+                return; // already unlocked: silent no-op
+            const fn = this._exitPointerLockFn();
+            if (!fn)
+                return; // unsupported: silent no-op (semantically already "not locked")
+            fn();
+            this._setError(null);
+            this._applyActive();
+        }
+        catch (e) {
+            this._setError(e);
+        }
+    }
+    // --- API resolution (call-time, never cached — §3.7) ---
+    // Resolved from `Element.prototype` rather than `el.requestPointerLock`
+    // directly: when `target="self"`, `el` is the `<wcs-pointer-lock>` Shell
+    // itself, whose own class declares an instance method also named
+    // `requestPointerLock()` (the wcBindable command). Reading the property off
+    // the instance would pick up that Shell method instead of the native
+    // platform API and recurse infinitely (Shell.requestPointerLock() ->
+    // Core.requestPointerLock() -> resolves "el.requestPointerLock" -> the same
+    // Shell method again). Going through `Element.prototype` sidesteps the name
+    // collision — note this does NOT pick up an override on a subclass's own
+    // prototype (e.g. `WcsPointerLock.prototype`); it deliberately jumps
+    // straight to the platform-defined layer. Both the standard and legacy name
+    // are resolved the same way, for symmetry — matching FullscreenCore's
+    // `_elementFullscreenFn` (docs/fullscreen-tag-design.md §4) ONLY in that one
+    // respect. Unlike that Core, this one does not check `el`'s own properties
+    // first: there is no test-stub/per-element monkey-patch path to accommodate
+    // here (mocks.ts installs the fakes directly on `Element.prototype`), so it
+    // goes straight there for both names.
+    _requestPointerLockFn(el) {
+        const proto = Element.prototype;
+        const standard = proto.requestPointerLock;
+        if (typeof standard === "function")
+            return standard.bind(el);
+        const legacy = proto.webkitRequestPointerLock;
+        return typeof legacy === "function" ? legacy.bind(el) : undefined;
+    }
+    _exitPointerLockFn() {
+        const d = document;
+        return d.exitPointerLock?.bind(document) ?? d.webkitExitPointerLock?.bind(document);
+    }
+    _pointerLockElement() {
+        const d = document;
+        return d.pointerLockElement ?? d.webkitPointerLockElement ?? null;
+    }
+    // NOTE (test-environment caveat, not a production concern): happy-dom
+    // always implements `document.onpointerlockchange` (as `null`) regardless
+    // of which fake API surface a test installs, so `"onpointerlockchange" in
+    // document` can never observably be `false` under this test runner and the
+    // `webkitpointerlockchange` branch below cannot be driven through
+    // `observe()` in a unit test. The branch is still correct and required for
+    // real legacy WebKit builds that lack `onpointerlockchange` entirely — kept
+    // as documented, deliberate, untestable-in-this-harness code per
+    // docs/pointer-lock-tag-design.md.
+    /* v8 ignore next 3 */
+    _pointerLockChangeEventName() {
+        return "onpointerlockchange" in document ? "pointerlockchange" : "webkitpointerlockchange";
+    }
+    _onChange = () => {
+        this._applyActive();
+    };
+    // Self-filter (docs/fullscreen-tag-design.md §2.1): compares against this
+    // instance's own resolved target, not merely "is *something* locked" — so
+    // multiple concurrent instances each report the correct `active` value.
+    _applyActive() {
+        const next = this._resolvedTarget !== null && this._pointerLockElement() === this._resolvedTarget;
+        this._setActive(next);
+    }
+    // Same-value guard (MUST, §3.3 of the guidelines). detail itself is the
+    // bare boolean value (no getter needed) per docs/pointer-lock-tag-design.md
+    // §2 — unlike FullscreenCore's `{ active }`-shaped detail + getter.
+    _setActive(v) {
+        if (this._active === v)
+            return;
+        this._active = v;
+        this._target.dispatchEvent(new CustomEvent("wcs-pointer-lock:change", {
+            detail: v,
+            bubbles: true,
+        }));
+    }
+    _setError(e) {
+        this._error = e;
+    }
+}
+
+/**
+ * `<wcs-pointer-lock target="...">` — declarative Pointer Lock API control.
+ *
+ * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0), this Shell does
+ * not lock itself — it operates on a *referenced* element via the `target`
+ * attribute, using the same 3-mode resolution rule as `intersection`
+ * (`_resolveTarget()`/`_safeQuery()`, copied verbatim per
+ * docs/pointer-lock-tag-design.md §1 / docs/fullscreen-tag-design.md §1):
+ *
+ * | `target`        | operates on            | display     |
+ * |-----------------|-------------------------|-------------|
+ * | omitted         | first element child     | `contents`  |
+ * | `"#selector"`    | the matched element      | `none`      |
+ * | `"self"`         | the element itself       | `block`     |
+ *
+ * `requestPointerLock()` requires a user-gesture context (docs/fullscreen-tag-design.md
+ * §3) — the primary activation path is the command-token protocol
+ * (`command.requestPointerLock: $command.<token>` on `<wcs-pointer-lock>`,
+ * emitted by a button's `onclick: $command.<token>`), not an
+ * autoTrigger attribute (none is provided in v1,
+ * docs/pointer-lock-tag-design.md §4).
+ *
+ * `movementX`/`movementY` are intentionally out of scope for v1
+ * (docs/pointer-lock-tag-design.md §3) — do not add them without revisiting
+ * the design doc.
+ */
+class WcsPointerLock extends HTMLElement {
+    // SSR (§4.4): the Core subscribes synchronously on connect, 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 = {
+        ...PointerLockCore.wcBindable,
+        inputs: [{ name: "target", attribute: "target" }],
+        // Core の commands をそのまま継承（単一情報源）。network/intersection と同型。
+        commands: PointerLockCore.wcBindable.commands,
+    };
+    _core;
+    _connectedCallbackPromise = Promise.resolve();
+    constructor() {
+        super();
+        this._core = new PointerLockCore(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 ---
+    /**
+     * Resolve `target` and request pointer lock on it. Requires a user-gesture
+     * context. never-throw: an unresolvable target or an unsupported/rejected
+     * API call are both surfaced via `error`, never thrown (mirrors
+     * `<wcs-fullscreen>`'s `requestFullscreen()`, docs/fullscreen-tag-design.md
+     * §3/§6 — the Shell passes the (possibly `null`) resolved element straight
+     * through and lets the Core set `error`, rather than silently no-op'ing
+     * here).
+     */
+    async requestPointerLock() {
+        const { element } = this._resolveTarget();
+        await this._core.requestPointerLock(element);
+    }
+    /** Exit pointer lock. Synchronous command — silent no-op if nothing is locked. */
+    exitPointerLock() {
+        this._core.exitPointerLock();
+    }
+    // --- Lifecycle ---
+    connectedCallback() {
+        this._applyDisplayAndObserve();
+    }
+    disconnectedCallback() {
+        this._core.dispose();
+    }
+    attributeChangedCallback(name) {
+        if (name === "target" && this.isConnected) {
+            this._applyDisplayAndObserve();
+        }
+    }
+    // --- Internal ---
+    _applyDisplayAndObserve() {
+        const { element, display } = this._resolveTarget();
+        this.style.display = display;
+        this._connectedCallbackPromise = this._core.observe(element);
+    }
+    // Copied verbatim from packages/intersection/src/components/Intersect.ts
+    // (§1 of docs/pointer-lock-tag-design.md / docs/fullscreen-tag-design.md).
+    _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" };
+    }
+    // Copied verbatim from packages/intersection/src/components/Intersect.ts.
+    _safeQuery(scope, selector) {
+        try {
+            return scope.querySelector(selector);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+
+function registerComponents() {
+    if (!customElements.get(config.tagNames.pointerLock)) {
+        customElements.define(config.tagNames.pointerLock, WcsPointerLock);
+    }
+}
+
+function bootstrapPointerLock(userConfig) {
+    if (userConfig) {
+        setConfig(userConfig);
+    }
+    registerComponents();
+}
+
+export { PointerLockCore, WcsPointerLock, bootstrapPointerLock, 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/PointerLockCore.ts","../src/components/PointerLock.ts","../src/registerComponents.ts","../src/bootstrapPointerLock.ts"],"sourcesContent":["import { IConfig, IWritableConfig } from \"./types.js\";\n\ninterface IInternalConfig extends IConfig {\n  tagNames: {\n    pointerLock: string;\n  };\n}\n\nconst _config: IInternalConfig = {\n  tagNames: {\n    pointerLock: \"wcs-pointer-lock\",\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 Pointer Lock primitive. A thin, framework-agnostic wrapper around\n * the Pointer Lock API (`Element.requestPointerLock()` /\n * `document.exitPointerLock()` / `document.pointerLockElement` / the\n * `document`-scoped `pointerlockchange` event) exposed through the\n * wc-bindable protocol.\n *\n * This Core follows the same basic pattern as `FullscreenCore`\n * (docs/fullscreen-tag-design.md, referenced by docs/pointer-lock-tag-design.md\n * §1): target resolution happens in the Shell, `pointerlockchange` is\n * subscribed on `document` (not on the target element) and each instance\n * self-filters by comparing `document.pointerLockElement` against its own\n * resolved target, API resolution is call-time (never cached) and probes the\n * standard name before the legacy (`webkit`-prefixed) name, and a single\n * Core-level `_gen` generation guard protects the asynchronous\n * `requestPointerLock()` call from stale resolution after dispose().\n *\n * Key difference from Fullscreen (docs/pointer-lock-tag-design.md §2):\n * `exitPointerLock()` is a *synchronous* platform API (it returns `void`, not\n * a `Promise`), so the Core's `exitPointerLock()` command is synchronous too\n * and carries no `_gen` guard of its own — it is wrapped in `try/catch` only\n * as a defensive measure (never-throw), not because it can go stale.\n *\n * Scope note (docs/pointer-lock-tag-design.md §3): `movementX`/`movementY`\n * are intentionally NOT exposed by this Core (v1 scope). They are\n * high-frequency `mousemove` data unsuited to the same-value-guarded\n * declarative `properties` surface; see the design doc for the rationale and\n * the planned `debounce`/`throttle`-based opt-in for a future version.\n */\nexport class PointerLockCore extends EventTarget {\n  static wcBindable: IWcBindable = {\n    protocol: \"wc-bindable\",\n    version: 1,\n    // `active`'s CustomEvent detail is the bare boolean value itself — no\n    // getter needed (docs/pointer-lock-tag-design.md §2). This differs from\n    // FullscreenCore's `{ active }`-shaped detail + getter.\n    properties: [\n      { name: \"active\", event: \"wcs-pointer-lock:change\" },\n    ],\n    commands: [\n      { name: \"requestPointerLock\", async: true },\n      // Synchronous platform API (document.exitPointerLock() returns void) —\n      // no `async` flag (docs/pointer-lock-tag-design.md §2).\n      { name: \"exitPointerLock\" },\n    ],\n  };\n\n  private _target: EventTarget;\n  private _active = false;\n  private _error: any = null;\n\n  // The element this instance last resolved requestPointerLock()/observe()\n  // against, kept so the document-scoped `pointerlockchange` handler can\n  // self-filter under multiple concurrent instances (docs/fullscreen-tag-design.md\n  // §2.1, inherited verbatim by pointer-lock per docs/pointer-lock-tag-design.md §1).\n  private _resolvedTarget: Element | null = null;\n\n  // True once observe() has attached the live `document` listener. Guards\n  // observe() so a redundant call does not re-subscribe; dispose() resets it\n  // so a later observe() resumes cleanly.\n  private _subscribed = false;\n\n  // Core-level generation guard (§3.4 of the guidelines / §6 of\n  // fullscreen-tag-design.md): only requestPointerLock() is asynchronous and\n  // needs it. exitPointerLock() is synchronous and has no stale-resolution\n  // race to guard against.\n  private _gen = 0;\n\n  // SSR (§3.8): no asynchronous probe to await — observe() completes\n  // synchronously, 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). Idempotent: a second observe() while already subscribed\n  // updates the tracked resolved target without re-subscribing to `document`.\n  observe(target: Element | null): Promise<void> {\n    this._resolvedTarget = target;\n    if (!this._subscribed) {\n      this._subscribed = true;\n      document.addEventListener(this._pointerLockChangeEventName(), this._onChange);\n    }\n    this._applyActive();\n    return this._ready;\n  }\n\n  dispose(): void {\n    this._gen++; // invalidate any in-flight requestPointerLock() resolution\n    if (this._subscribed) {\n      this._subscribed = false;\n      document.removeEventListener(this._pointerLockChangeEventName(), this._onChange);\n    }\n    this._resolvedTarget = null;\n  }\n\n  /**\n   * Request pointer lock on `element`. Never-throw: a missing API or a\n   * rejected promise (e.g. called outside a user-gesture context —\n   * `NotAllowedError`, docs/fullscreen-tag-design.md §3) is captured into\n   * `error` rather than propagated. `element` may be `null` when the Shell's\n   * `target` selector did not resolve (docs/pointer-lock-tag-design.md §1\n   * defers error representation to FullscreenCore verbatim — this null-target\n   * case mirrors `FullscreenCore.requestFullscreen(null)`,\n   * docs/fullscreen-tag-design.md §6): distinct from \"API is not supported\"\n   * below, so a typo'd selector doesn't masquerade as an unsupported platform.\n   */\n  async requestPointerLock(element: Element | null): Promise<void> {\n    const gen = ++this._gen;\n    this._resolvedTarget = element;\n    if (!element) {\n      this._setError({ message: \"Pointer Lock target could not be resolved.\" });\n      return;\n    }\n    const fn = this._requestPointerLockFn(element);\n    if (!fn) {\n      // Resolved synchronously in the same tick as the call — dispose()\n      // cannot have run yet, so no staleness check is needed here (matches\n      // the reference `requestFullscreen()` implementation,\n      // docs/fullscreen-tag-design.md §6).\n      this._setError({ message: \"Pointer Lock API is not supported.\" });\n      return;\n    }\n    try {\n      // fn is already bound to `element` by _requestPointerLockFn().\n      await fn();\n      if (gen !== this._gen) return; // stale\n      this._setError(null);\n      this._applyActive();\n    } catch (e: any) {\n      if (gen !== this._gen) return; // stale\n      this._setError(e);\n    }\n  }\n\n  /**\n   * Exit pointer lock. Synchronous platform API (docs/pointer-lock-tag-design.md\n   * §2) — returns `void`, not a `Promise`. Silent no-op when nothing is\n   * currently locked or the API is unsupported (mirrors\n   * `FullscreenCore.exitFullscreen()`'s no-op contract,\n   * docs/fullscreen-tag-design.md §7). Wrapped in try/catch defensively: even\n   * though the platform API is synchronous and documented as not throwing in\n   * this case, a synchronous throw from a non-conformant/fake implementation\n   * must never escape (never-throw).\n   */\n  exitPointerLock(): void {\n    try {\n      if (this._pointerLockElement() === null) return; // already unlocked: silent no-op\n      const fn = this._exitPointerLockFn();\n      if (!fn) return; // unsupported: silent no-op (semantically already \"not locked\")\n      fn();\n      this._setError(null);\n      this._applyActive();\n    } catch (e: any) {\n      this._setError(e);\n    }\n  }\n\n  // --- API resolution (call-time, never cached — §3.7) ---\n\n  // Resolved from `Element.prototype` rather than `el.requestPointerLock`\n  // directly: when `target=\"self\"`, `el` is the `<wcs-pointer-lock>` Shell\n  // itself, whose own class declares an instance method also named\n  // `requestPointerLock()` (the wcBindable command). Reading the property off\n  // the instance would pick up that Shell method instead of the native\n  // platform API and recurse infinitely (Shell.requestPointerLock() ->\n  // Core.requestPointerLock() -> resolves \"el.requestPointerLock\" -> the same\n  // Shell method again). Going through `Element.prototype` sidesteps the name\n  // collision — note this does NOT pick up an override on a subclass's own\n  // prototype (e.g. `WcsPointerLock.prototype`); it deliberately jumps\n  // straight to the platform-defined layer. Both the standard and legacy name\n  // are resolved the same way, for symmetry — matching FullscreenCore's\n  // `_elementFullscreenFn` (docs/fullscreen-tag-design.md §4) ONLY in that one\n  // respect. Unlike that Core, this one does not check `el`'s own properties\n  // first: there is no test-stub/per-element monkey-patch path to accommodate\n  // here (mocks.ts installs the fakes directly on `Element.prototype`), so it\n  // goes straight there for both names.\n  private _requestPointerLockFn(el: Element): (() => Promise<void>) | undefined {\n    const proto = Element.prototype as any;\n    const standard = proto.requestPointerLock;\n    if (typeof standard === \"function\") return standard.bind(el);\n    const legacy = proto.webkitRequestPointerLock;\n    return typeof legacy === \"function\" ? legacy.bind(el) : undefined;\n  }\n\n  private _exitPointerLockFn(): (() => void) | undefined {\n    const d = document as any;\n    return d.exitPointerLock?.bind(document) ?? d.webkitExitPointerLock?.bind(document);\n  }\n\n  private _pointerLockElement(): Element | null {\n    const d = document as any;\n    return d.pointerLockElement ?? d.webkitPointerLockElement ?? null;\n  }\n\n  // NOTE (test-environment caveat, not a production concern): happy-dom\n  // always implements `document.onpointerlockchange` (as `null`) regardless\n  // of which fake API surface a test installs, so `\"onpointerlockchange\" in\n  // document` can never observably be `false` under this test runner and the\n  // `webkitpointerlockchange` branch below cannot be driven through\n  // `observe()` in a unit test. The branch is still correct and required for\n  // real legacy WebKit builds that lack `onpointerlockchange` entirely — kept\n  // as documented, deliberate, untestable-in-this-harness code per\n  // docs/pointer-lock-tag-design.md.\n  /* v8 ignore next 3 */\n  private _pointerLockChangeEventName(): string {\n    return \"onpointerlockchange\" in document ? \"pointerlockchange\" : \"webkitpointerlockchange\";\n  }\n\n  private _onChange = (): void => {\n    this._applyActive();\n  };\n\n  // Self-filter (docs/fullscreen-tag-design.md §2.1): compares against this\n  // instance's own resolved target, not merely \"is *something* locked\" — so\n  // multiple concurrent instances each report the correct `active` value.\n  private _applyActive(): void {\n    const next = this._resolvedTarget !== null && this._pointerLockElement() === this._resolvedTarget;\n    this._setActive(next);\n  }\n\n  // Same-value guard (MUST, §3.3 of the guidelines). detail itself is the\n  // bare boolean value (no getter needed) per docs/pointer-lock-tag-design.md\n  // §2 — unlike FullscreenCore's `{ active }`-shaped detail + getter.\n  private _setActive(v: boolean): void {\n    if (this._active === v) return;\n    this._active = v;\n    this._target.dispatchEvent(new CustomEvent(\"wcs-pointer-lock:change\", {\n      detail: v,\n      bubbles: true,\n    }));\n  }\n\n  private _setError(e: any): void {\n    this._error = e;\n  }\n}\n","import { IWcBindable } from \"../types.js\";\nimport { PointerLockCore } from \"../core/PointerLockCore.js\";\n\n/**\n * `<wcs-pointer-lock target=\"...\">` — declarative Pointer Lock API control.\n *\n * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0), this Shell does\n * not lock itself — it operates on a *referenced* element via the `target`\n * attribute, using the same 3-mode resolution rule as `intersection`\n * (`_resolveTarget()`/`_safeQuery()`, copied verbatim per\n * docs/pointer-lock-tag-design.md §1 / docs/fullscreen-tag-design.md §1):\n *\n * | `target`        | operates on            | display     |\n * |-----------------|-------------------------|-------------|\n * | omitted         | first element child     | `contents`  |\n * | `\"#selector\"`    | the matched element      | `none`      |\n * | `\"self\"`         | the element itself       | `block`     |\n *\n * `requestPointerLock()` requires a user-gesture context (docs/fullscreen-tag-design.md\n * §3) — the primary activation path is the command-token protocol\n * (`command.requestPointerLock: $command.<token>` on `<wcs-pointer-lock>`,\n * emitted by a button's `onclick: $command.<token>`), not an\n * autoTrigger attribute (none is provided in v1,\n * docs/pointer-lock-tag-design.md §4).\n *\n * `movementX`/`movementY` are intentionally out of scope for v1\n * (docs/pointer-lock-tag-design.md §3) — do not add them without revisiting\n * the design doc.\n */\nexport class WcsPointerLock extends HTMLElement {\n  // SSR (§4.4): the Core subscribes synchronously on connect, but the Shell\n  // still exposes connectedCallbackPromise so the state binder can await it\n  // uniformly across all IO nodes before snapshotting.\n  static hasConnectedCallbackPromise = true;\n\n  static observedAttributes = [\"target\"];\n\n  static wcBindable: IWcBindable = {\n    ...PointerLockCore.wcBindable,\n    inputs: [{ name: \"target\", attribute: \"target\" }],\n    // Core の commands をそのまま継承（単一情報源）。network/intersection と同型。\n    commands: PointerLockCore.wcBindable.commands,\n  };\n\n  private _core: PointerLockCore;\n  private _connectedCallbackPromise: Promise<void> = Promise.resolve();\n\n  constructor() {\n    super();\n    this._core = new PointerLockCore(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  /**\n   * Resolve `target` and request pointer lock on it. Requires a user-gesture\n   * context. never-throw: an unresolvable target or an unsupported/rejected\n   * API call are both surfaced via `error`, never thrown (mirrors\n   * `<wcs-fullscreen>`'s `requestFullscreen()`, docs/fullscreen-tag-design.md\n   * §3/§6 — the Shell passes the (possibly `null`) resolved element straight\n   * through and lets the Core set `error`, rather than silently no-op'ing\n   * here).\n   */\n  async requestPointerLock(): Promise<void> {\n    const { element } = this._resolveTarget();\n    await this._core.requestPointerLock(element);\n  }\n\n  /** Exit pointer lock. Synchronous command — silent no-op if nothing is locked. */\n  exitPointerLock(): void {\n    this._core.exitPointerLock();\n  }\n\n  // --- Lifecycle ---\n\n  connectedCallback(): void {\n    this._applyDisplayAndObserve();\n  }\n\n  disconnectedCallback(): void {\n    this._core.dispose();\n  }\n\n  attributeChangedCallback(name: string): void {\n    if (name === \"target\" && this.isConnected) {\n      this._applyDisplayAndObserve();\n    }\n  }\n\n  // --- Internal ---\n\n  private _applyDisplayAndObserve(): void {\n    const { element, display } = this._resolveTarget();\n    this.style.display = display;\n    this._connectedCallbackPromise = this._core.observe(element);\n  }\n\n  // Copied verbatim from packages/intersection/src/components/Intersect.ts\n  // (§1 of docs/pointer-lock-tag-design.md / docs/fullscreen-tag-design.md).\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  // Copied verbatim from packages/intersection/src/components/Intersect.ts.\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","import { WcsPointerLock } from \"./components/PointerLock.js\";\nimport { config } from \"./config.js\";\n\nexport function registerComponents(): void {\n  if (!customElements.get(config.tagNames.pointerLock)) {\n    customElements.define(config.tagNames.pointerLock, WcsPointerLock);\n  }\n}\n","import { setConfig } from \"./config.js\";\nimport { registerComponents } from \"./registerComponents.js\";\nimport { IWritableConfig } from \"./types.js\";\n\nexport function bootstrapPointerLock(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:{pointerLock:"wcs-pointer-lock"}};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 n of Object.keys(e))t[n]=r(e[n]);return t}let n=null;const s=e;function i(){return n||(n=t(r(e))),n}class o extends EventTarget{static wcBindable={protocol:"wc-bindable",version:1,properties:[{name:"active",event:"wcs-pointer-lock:change"}],commands:[{name:"requestPointerLock",async:!0},{name:"exitPointerLock"}]};_target;_active=!1;_error=null;_resolvedTarget=null;_subscribed=!1;_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._resolvedTarget=e,this._subscribed||(this._subscribed=!0,document.addEventListener(this._pointerLockChangeEventName(),this._onChange)),this._applyActive(),this._ready}dispose(){this._gen++,this._subscribed&&(this._subscribed=!1,document.removeEventListener(this._pointerLockChangeEventName(),this._onChange)),this._resolvedTarget=null}async requestPointerLock(e){const t=++this._gen;if(this._resolvedTarget=e,!e)return void this._setError({message:"Pointer Lock target could not be resolved."});const r=this._requestPointerLockFn(e);if(r)try{if(await r(),t!==this._gen)return;this._setError(null),this._applyActive()}catch(e){if(t!==this._gen)return;this._setError(e)}else this._setError({message:"Pointer Lock API is not supported."})}exitPointerLock(){try{if(null===this._pointerLockElement())return;const e=this._exitPointerLockFn();if(!e)return;e(),this._setError(null),this._applyActive()}catch(e){this._setError(e)}}_requestPointerLockFn(e){const t=Element.prototype,r=t.requestPointerLock;if("function"==typeof r)return r.bind(e);const n=t.webkitRequestPointerLock;return"function"==typeof n?n.bind(e):void 0}_exitPointerLockFn(){const e=document;return e.exitPointerLock?.bind(document)??e.webkitExitPointerLock?.bind(document)}_pointerLockElement(){const e=document;return e.pointerLockElement??e.webkitPointerLockElement??null}_pointerLockChangeEventName(){return"onpointerlockchange"in document?"pointerlockchange":"webkitpointerlockchange"}_onChange=()=>{this._applyActive()};_applyActive(){const e=null!==this._resolvedTarget&&this._pointerLockElement()===this._resolvedTarget;this._setActive(e)}_setActive(e){this._active!==e&&(this._active=e,this._target.dispatchEvent(new CustomEvent("wcs-pointer-lock:change",{detail:e,bubbles:!0})))}_setError(e){this._error=e}}class c extends HTMLElement{static hasConnectedCallbackPromise=!0;static observedAttributes=["target"];static wcBindable={...o.wcBindable,inputs:[{name:"target",attribute:"target"}],commands:o.wcBindable.commands};_core;_connectedCallbackPromise=Promise.resolve();constructor(){super(),this._core=new o(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 requestPointerLock(){const{element:e}=this._resolveTarget();await this._core.requestPointerLock(e)}exitPointerLock(){this._core.exitPointerLock()}connectedCallback(){this._applyDisplayAndObserve()}disconnectedCallback(){this._core.dispose()}attributeChangedCallback(e){"target"===e&&this.isConnected&&this._applyDisplayAndObserve()}_applyDisplayAndObserve(){const{element:e,display:t}=this._resolveTarget();this.style.display=t,this._connectedCallbackPromise=this._core.observe(e)}_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}}}function a(t){var r;t&&((r=t).tagNames&&Object.assign(e.tagNames,r.tagNames),n=null),customElements.get(s.tagNames.pointerLock)||customElements.define(s.tagNames.pointerLock,c)}export{o as PointerLockCore,c as WcsPointerLock,a as bootstrapPointerLock,i 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/PointerLockCore.ts","../src/components/PointerLock.ts","../src/bootstrapPointerLock.ts","../src/registerComponents.ts"],"sourcesContent":["import { IConfig, IWritableConfig } from \"./types.js\";\n\ninterface IInternalConfig extends IConfig {\n  tagNames: {\n    pointerLock: string;\n  };\n}\n\nconst _config: IInternalConfig = {\n  tagNames: {\n    pointerLock: \"wcs-pointer-lock\",\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 Pointer Lock primitive. A thin, framework-agnostic wrapper around\n * the Pointer Lock API (`Element.requestPointerLock()` /\n * `document.exitPointerLock()` / `document.pointerLockElement` / the\n * `document`-scoped `pointerlockchange` event) exposed through the\n * wc-bindable protocol.\n *\n * This Core follows the same basic pattern as `FullscreenCore`\n * (docs/fullscreen-tag-design.md, referenced by docs/pointer-lock-tag-design.md\n * §1): target resolution happens in the Shell, `pointerlockchange` is\n * subscribed on `document` (not on the target element) and each instance\n * self-filters by comparing `document.pointerLockElement` against its own\n * resolved target, API resolution is call-time (never cached) and probes the\n * standard name before the legacy (`webkit`-prefixed) name, and a single\n * Core-level `_gen` generation guard protects the asynchronous\n * `requestPointerLock()` call from stale resolution after dispose().\n *\n * Key difference from Fullscreen (docs/pointer-lock-tag-design.md §2):\n * `exitPointerLock()` is a *synchronous* platform API (it returns `void`, not\n * a `Promise`), so the Core's `exitPointerLock()` command is synchronous too\n * and carries no `_gen` guard of its own — it is wrapped in `try/catch` only\n * as a defensive measure (never-throw), not because it can go stale.\n *\n * Scope note (docs/pointer-lock-tag-design.md §3): `movementX`/`movementY`\n * are intentionally NOT exposed by this Core (v1 scope). They are\n * high-frequency `mousemove` data unsuited to the same-value-guarded\n * declarative `properties` surface; see the design doc for the rationale and\n * the planned `debounce`/`throttle`-based opt-in for a future version.\n */\nexport class PointerLockCore extends EventTarget {\n  static wcBindable: IWcBindable = {\n    protocol: \"wc-bindable\",\n    version: 1,\n    // `active`'s CustomEvent detail is the bare boolean value itself — no\n    // getter needed (docs/pointer-lock-tag-design.md §2). This differs from\n    // FullscreenCore's `{ active }`-shaped detail + getter.\n    properties: [\n      { name: \"active\", event: \"wcs-pointer-lock:change\" },\n    ],\n    commands: [\n      { name: \"requestPointerLock\", async: true },\n      // Synchronous platform API (document.exitPointerLock() returns void) —\n      // no `async` flag (docs/pointer-lock-tag-design.md §2).\n      { name: \"exitPointerLock\" },\n    ],\n  };\n\n  private _target: EventTarget;\n  private _active = false;\n  private _error: any = null;\n\n  // The element this instance last resolved requestPointerLock()/observe()\n  // against, kept so the document-scoped `pointerlockchange` handler can\n  // self-filter under multiple concurrent instances (docs/fullscreen-tag-design.md\n  // §2.1, inherited verbatim by pointer-lock per docs/pointer-lock-tag-design.md §1).\n  private _resolvedTarget: Element | null = null;\n\n  // True once observe() has attached the live `document` listener. Guards\n  // observe() so a redundant call does not re-subscribe; dispose() resets it\n  // so a later observe() resumes cleanly.\n  private _subscribed = false;\n\n  // Core-level generation guard (§3.4 of the guidelines / §6 of\n  // fullscreen-tag-design.md): only requestPointerLock() is asynchronous and\n  // needs it. exitPointerLock() is synchronous and has no stale-resolution\n  // race to guard against.\n  private _gen = 0;\n\n  // SSR (§3.8): no asynchronous probe to await — observe() completes\n  // synchronously, 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). Idempotent: a second observe() while already subscribed\n  // updates the tracked resolved target without re-subscribing to `document`.\n  observe(target: Element | null): Promise<void> {\n    this._resolvedTarget = target;\n    if (!this._subscribed) {\n      this._subscribed = true;\n      document.addEventListener(this._pointerLockChangeEventName(), this._onChange);\n    }\n    this._applyActive();\n    return this._ready;\n  }\n\n  dispose(): void {\n    this._gen++; // invalidate any in-flight requestPointerLock() resolution\n    if (this._subscribed) {\n      this._subscribed = false;\n      document.removeEventListener(this._pointerLockChangeEventName(), this._onChange);\n    }\n    this._resolvedTarget = null;\n  }\n\n  /**\n   * Request pointer lock on `element`. Never-throw: a missing API or a\n   * rejected promise (e.g. called outside a user-gesture context —\n   * `NotAllowedError`, docs/fullscreen-tag-design.md §3) is captured into\n   * `error` rather than propagated. `element` may be `null` when the Shell's\n   * `target` selector did not resolve (docs/pointer-lock-tag-design.md §1\n   * defers error representation to FullscreenCore verbatim — this null-target\n   * case mirrors `FullscreenCore.requestFullscreen(null)`,\n   * docs/fullscreen-tag-design.md §6): distinct from \"API is not supported\"\n   * below, so a typo'd selector doesn't masquerade as an unsupported platform.\n   */\n  async requestPointerLock(element: Element | null): Promise<void> {\n    const gen = ++this._gen;\n    this._resolvedTarget = element;\n    if (!element) {\n      this._setError({ message: \"Pointer Lock target could not be resolved.\" });\n      return;\n    }\n    const fn = this._requestPointerLockFn(element);\n    if (!fn) {\n      // Resolved synchronously in the same tick as the call — dispose()\n      // cannot have run yet, so no staleness check is needed here (matches\n      // the reference `requestFullscreen()` implementation,\n      // docs/fullscreen-tag-design.md §6).\n      this._setError({ message: \"Pointer Lock API is not supported.\" });\n      return;\n    }\n    try {\n      // fn is already bound to `element` by _requestPointerLockFn().\n      await fn();\n      if (gen !== this._gen) return; // stale\n      this._setError(null);\n      this._applyActive();\n    } catch (e: any) {\n      if (gen !== this._gen) return; // stale\n      this._setError(e);\n    }\n  }\n\n  /**\n   * Exit pointer lock. Synchronous platform API (docs/pointer-lock-tag-design.md\n   * §2) — returns `void`, not a `Promise`. Silent no-op when nothing is\n   * currently locked or the API is unsupported (mirrors\n   * `FullscreenCore.exitFullscreen()`'s no-op contract,\n   * docs/fullscreen-tag-design.md §7). Wrapped in try/catch defensively: even\n   * though the platform API is synchronous and documented as not throwing in\n   * this case, a synchronous throw from a non-conformant/fake implementation\n   * must never escape (never-throw).\n   */\n  exitPointerLock(): void {\n    try {\n      if (this._pointerLockElement() === null) return; // already unlocked: silent no-op\n      const fn = this._exitPointerLockFn();\n      if (!fn) return; // unsupported: silent no-op (semantically already \"not locked\")\n      fn();\n      this._setError(null);\n      this._applyActive();\n    } catch (e: any) {\n      this._setError(e);\n    }\n  }\n\n  // --- API resolution (call-time, never cached — §3.7) ---\n\n  // Resolved from `Element.prototype` rather than `el.requestPointerLock`\n  // directly: when `target=\"self\"`, `el` is the `<wcs-pointer-lock>` Shell\n  // itself, whose own class declares an instance method also named\n  // `requestPointerLock()` (the wcBindable command). Reading the property off\n  // the instance would pick up that Shell method instead of the native\n  // platform API and recurse infinitely (Shell.requestPointerLock() ->\n  // Core.requestPointerLock() -> resolves \"el.requestPointerLock\" -> the same\n  // Shell method again). Going through `Element.prototype` sidesteps the name\n  // collision — note this does NOT pick up an override on a subclass's own\n  // prototype (e.g. `WcsPointerLock.prototype`); it deliberately jumps\n  // straight to the platform-defined layer. Both the standard and legacy name\n  // are resolved the same way, for symmetry — matching FullscreenCore's\n  // `_elementFullscreenFn` (docs/fullscreen-tag-design.md §4) ONLY in that one\n  // respect. Unlike that Core, this one does not check `el`'s own properties\n  // first: there is no test-stub/per-element monkey-patch path to accommodate\n  // here (mocks.ts installs the fakes directly on `Element.prototype`), so it\n  // goes straight there for both names.\n  private _requestPointerLockFn(el: Element): (() => Promise<void>) | undefined {\n    const proto = Element.prototype as any;\n    const standard = proto.requestPointerLock;\n    if (typeof standard === \"function\") return standard.bind(el);\n    const legacy = proto.webkitRequestPointerLock;\n    return typeof legacy === \"function\" ? legacy.bind(el) : undefined;\n  }\n\n  private _exitPointerLockFn(): (() => void) | undefined {\n    const d = document as any;\n    return d.exitPointerLock?.bind(document) ?? d.webkitExitPointerLock?.bind(document);\n  }\n\n  private _pointerLockElement(): Element | null {\n    const d = document as any;\n    return d.pointerLockElement ?? d.webkitPointerLockElement ?? null;\n  }\n\n  // NOTE (test-environment caveat, not a production concern): happy-dom\n  // always implements `document.onpointerlockchange` (as `null`) regardless\n  // of which fake API surface a test installs, so `\"onpointerlockchange\" in\n  // document` can never observably be `false` under this test runner and the\n  // `webkitpointerlockchange` branch below cannot be driven through\n  // `observe()` in a unit test. The branch is still correct and required for\n  // real legacy WebKit builds that lack `onpointerlockchange` entirely — kept\n  // as documented, deliberate, untestable-in-this-harness code per\n  // docs/pointer-lock-tag-design.md.\n  /* v8 ignore next 3 */\n  private _pointerLockChangeEventName(): string {\n    return \"onpointerlockchange\" in document ? \"pointerlockchange\" : \"webkitpointerlockchange\";\n  }\n\n  private _onChange = (): void => {\n    this._applyActive();\n  };\n\n  // Self-filter (docs/fullscreen-tag-design.md §2.1): compares against this\n  // instance's own resolved target, not merely \"is *something* locked\" — so\n  // multiple concurrent instances each report the correct `active` value.\n  private _applyActive(): void {\n    const next = this._resolvedTarget !== null && this._pointerLockElement() === this._resolvedTarget;\n    this._setActive(next);\n  }\n\n  // Same-value guard (MUST, §3.3 of the guidelines). detail itself is the\n  // bare boolean value (no getter needed) per docs/pointer-lock-tag-design.md\n  // §2 — unlike FullscreenCore's `{ active }`-shaped detail + getter.\n  private _setActive(v: boolean): void {\n    if (this._active === v) return;\n    this._active = v;\n    this._target.dispatchEvent(new CustomEvent(\"wcs-pointer-lock:change\", {\n      detail: v,\n      bubbles: true,\n    }));\n  }\n\n  private _setError(e: any): void {\n    this._error = e;\n  }\n}\n","import { IWcBindable } from \"../types.js\";\nimport { PointerLockCore } from \"../core/PointerLockCore.js\";\n\n/**\n * `<wcs-pointer-lock target=\"...\">` — declarative Pointer Lock API control.\n *\n * Like `<wcs-fullscreen>` (docs/fullscreen-tag-design.md §0), this Shell does\n * not lock itself — it operates on a *referenced* element via the `target`\n * attribute, using the same 3-mode resolution rule as `intersection`\n * (`_resolveTarget()`/`_safeQuery()`, copied verbatim per\n * docs/pointer-lock-tag-design.md §1 / docs/fullscreen-tag-design.md §1):\n *\n * | `target`        | operates on            | display     |\n * |-----------------|-------------------------|-------------|\n * | omitted         | first element child     | `contents`  |\n * | `\"#selector\"`    | the matched element      | `none`      |\n * | `\"self\"`         | the element itself       | `block`     |\n *\n * `requestPointerLock()` requires a user-gesture context (docs/fullscreen-tag-design.md\n * §3) — the primary activation path is the command-token protocol\n * (`command.requestPointerLock: $command.<token>` on `<wcs-pointer-lock>`,\n * emitted by a button's `onclick: $command.<token>`), not an\n * autoTrigger attribute (none is provided in v1,\n * docs/pointer-lock-tag-design.md §4).\n *\n * `movementX`/`movementY` are intentionally out of scope for v1\n * (docs/pointer-lock-tag-design.md §3) — do not add them without revisiting\n * the design doc.\n */\nexport class WcsPointerLock extends HTMLElement {\n  // SSR (§4.4): the Core subscribes synchronously on connect, but the Shell\n  // still exposes connectedCallbackPromise so the state binder can await it\n  // uniformly across all IO nodes before snapshotting.\n  static hasConnectedCallbackPromise = true;\n\n  static observedAttributes = [\"target\"];\n\n  static wcBindable: IWcBindable = {\n    ...PointerLockCore.wcBindable,\n    inputs: [{ name: \"target\", attribute: \"target\" }],\n    // Core の commands をそのまま継承（単一情報源）。network/intersection と同型。\n    commands: PointerLockCore.wcBindable.commands,\n  };\n\n  private _core: PointerLockCore;\n  private _connectedCallbackPromise: Promise<void> = Promise.resolve();\n\n  constructor() {\n    super();\n    this._core = new PointerLockCore(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  /**\n   * Resolve `target` and request pointer lock on it. Requires a user-gesture\n   * context. never-throw: an unresolvable target or an unsupported/rejected\n   * API call are both surfaced via `error`, never thrown (mirrors\n   * `<wcs-fullscreen>`'s `requestFullscreen()`, docs/fullscreen-tag-design.md\n   * §3/§6 — the Shell passes the (possibly `null`) resolved element straight\n   * through and lets the Core set `error`, rather than silently no-op'ing\n   * here).\n   */\n  async requestPointerLock(): Promise<void> {\n    const { element } = this._resolveTarget();\n    await this._core.requestPointerLock(element);\n  }\n\n  /** Exit pointer lock. Synchronous command — silent no-op if nothing is locked. */\n  exitPointerLock(): void {\n    this._core.exitPointerLock();\n  }\n\n  // --- Lifecycle ---\n\n  connectedCallback(): void {\n    this._applyDisplayAndObserve();\n  }\n\n  disconnectedCallback(): void {\n    this._core.dispose();\n  }\n\n  attributeChangedCallback(name: string): void {\n    if (name === \"target\" && this.isConnected) {\n      this._applyDisplayAndObserve();\n    }\n  }\n\n  // --- Internal ---\n\n  private _applyDisplayAndObserve(): void {\n    const { element, display } = this._resolveTarget();\n    this.style.display = display;\n    this._connectedCallbackPromise = this._core.observe(element);\n  }\n\n  // Copied verbatim from packages/intersection/src/components/Intersect.ts\n  // (§1 of docs/pointer-lock-tag-design.md / docs/fullscreen-tag-design.md).\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  // Copied verbatim from packages/intersection/src/components/Intersect.ts.\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","import { setConfig } from \"./config.js\";\nimport { registerComponents } from \"./registerComponents.js\";\nimport { IWritableConfig } from \"./types.js\";\n\nexport function bootstrapPointerLock(userConfig?: IWritableConfig): void {\n  if (userConfig) {\n    setConfig(userConfig);\n  }\n  registerComponents();\n}\n","import { WcsPointerLock } from \"./components/PointerLock.js\";\nimport { config } from \"./config.js\";\n\nexport function registerComponents(): void {\n  if (!customElements.get(config.tagNames.pointerLock)) {\n    customElements.define(config.tagNames.pointerLock, WcsPointerLock);\n  }\n}\n"],"names":["_config","tagNames","pointerLock","deepFreeze","obj","Object","freeze","key","keys","deepClone","clone","frozenConfig","config","getConfig","PointerLockCore","EventTarget","static","protocol","version","properties","name","event","commands","async","_target","_active","_error","_resolvedTarget","_subscribed","_gen","_ready","Promise","resolve","constructor","target","super","this","ready","active","error","observe","document","addEventListener","_pointerLockChangeEventName","_onChange","_applyActive","dispose","removeEventListener","requestPointerLock","element","gen","_setError","message","fn","_requestPointerLockFn","e","exitPointerLock","_pointerLockElement","_exitPointerLockFn","el","proto","Element","prototype","standard","bind","legacy","webkitRequestPointerLock","undefined","d","webkitExitPointerLock","pointerLockElement","webkitPointerLockElement","next","_setActive","v","dispatchEvent","CustomEvent","detail","bubbles","WcsPointerLock","HTMLElement","wcBindable","inputs","attribute","_core","_connectedCallbackPromise","connectedCallbackPromise","getAttribute","value","setAttribute","_resolveTarget","connectedCallback","_applyDisplayAndObserve","disconnectedCallback","attributeChangedCallback","isConnected","display","style","scope","getRootNode","_safeQuery","child","firstElementChild","selector","querySelector","bootstrapPointerLock","userConfig","partialConfig","assign","customElements","get","define"],"mappings":"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"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@wcstack/pointer-lock",
+  "version": "1.16.0",
+  "description": "Declarative Pointer Lock component for Web Components. Framework-agnostic Pointer Lock API 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",
+    "pointer-lock",
+    "mouse",
+    "game-input",
+    "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/pointer-lock"
+  },
+  "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"
+  }
+}