@wcstack/wakelock 1.12.1

package/README.ja.md

@@ -0,0 +1,173 @@
+# @wcstack/wakelock
+
+`@wcstack/wakelock` は wcstack エコシステムのためのヘッドレスな Screen Wake Lock コンポーネントです。
+
+視覚的な UI ウィジェットではありません。
+**非同期プリミティブノード** ですが、他のすべての @wcstack センサーとは *逆向き* に動作します。`@wcstack/geolocation` や `@wcstack/intersection` などは **プロデューサー**（`element → state`）で、デバイスのシグナルをリアクティブな状態に変換します。`@wcstack/wakelock` は **純粋なシンク**（`state → element`）で、バインドされた真偽値が画面を起こし続けるかどうかを駆動します。
+
+`@wcstack/state` と組み合わせると、`<wcs-wakelock>` は宣言的な1行として読めます:
+
+```html
+<wcs-wakelock data-wcs="active: isPlaying"></wcs-wakelock>
+```
+
+*「`isPlaying` が true である **間** 画面を起こし続ける」*。`navigator.wakeLock.request()` も、`visibilitychange` での再取得のグルーコードも、後始末も不要です。
+
+- **入力サーフェス**: `active`, `type`, `manual`
+- **出力ステートサーフェス**: `held`, `error`
+- **コマンド**: `request()`, `release()`
+
+`@wcstack/wakelock` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います:
+
+- **Core** (`WakeLockCore`) が sentinel、desired/actual の分離、自動解放後の再取得ループ、never-throw な失敗処理を所有
+- **Shell** (`<wcs-wakelock>`) が `active` 属性を `request()` / `release()` にマップし、ライフサイクルを管理
+- **Binding Contract** (`static wcBindable`) が観測可能な `properties`、書き込み可能な `inputs`、呼び出し可能な `commands` を宣言
+
+## なぜ存在するのか
+
+Screen Wake Lock API には扱いにくい性質があります。ページが可視でなくなった瞬間（タブが非表示、ウィンドウが最小化）に、OS が **自動的にロックを解放** してしまうのです。実際に「再生中は画面を起こし続ける」を実現するには、望み（desired intent）を自分で保持し、ページが再び可視になるたびにロックを再取得しなければなりません。
+
+`@wcstack/wakelock` はそのリース管理をコンポーネントの内側に閉じ込めます。真偽値をバインドすれば、その値が true である限り、コンポーネントが可視性変化をまたいでロックを生かし続けます。
+
+## 望み（`active`）と実状態（`held`）
+
+自動解放があるため、*望んでいること* と *いま実際に保持していること* は乖離します。そこで両者は別々のサーフェスになっています:
+
+| サーフェス  | 向き    | 意味 |
+|----------|---------|------|
+| `active` | 入力     | **望み（desired intent）。** `true` の間ロックを保持。OS の自動解放を越えて維持される。 |
+| `held`   | 出力     | **実状態。** *いま* sentinel を保持しているか。自動解放で `false` になり、ページが再び可視になると `true` に戻る。 |
+
+`active` は意図的に観測可能な出力 **ではありません**。OS がロックを落としても変化せず、変化するのは `held` だけだからです。UI でライブな「画面が起き続けている」状態を反映したい場合は `held` をバインドしてください。
+
+## インストール
+
+```bash
+npm install @wcstack/wakelock
+```
+
+## クイックスタート
+
+### 動画再生中に画面を起こし続ける
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/wakelock/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      playing: false,
+      startPlaying() { this.playing = true; },
+      stopPlaying() { this.playing = false; },
+    };
+  </script>
+
+  <video
+    src="/movie.mp4"
+    data-wcs="onplay: startPlaying; onpause: stopPlaying"
+  ></video>
+
+  <!-- ロックは `playing` が true の間だけ保持され、タブ切り替えを越えて生き残る。 -->
+  <wcs-wakelock data-wcs="active: playing"></wcs-wakelock>
+</wcs-state>
+```
+
+### 実際のロック状態を UI に反映する
+
+```html
+<wcs-wakelock data-wcs="active: keepAwake; held: screenLocked"></wcs-wakelock>
+
+<span data-wcs="textContent: screenLocked"></span>
+```
+
+### コマンド駆動（命令的）
+
+```html
+<wcs-wakelock data-wcs="command.request: $command.stayAwake"></wcs-wakelock>
+```
+
+> **コマンドは `active` 属性をミラーしません。** `request` / `release` コマンドは
+> `active` 属性に触れずに Core の望み（desired intent）を直接切り替えるため、コマンド後は
+> 要素の `active` プロパティ（属性のミラー）が `false` のまま `held` が `true`（またはその逆）
+> になりえます。同一要素でコマンド駆動と `active` 属性バインドを混在させないでください
+> — どちらか一方を選ぶこと。単一情報源には `active: ...` でバインドします。
+
+## 属性
+
+| 属性      | 型      | 既定値    | 説明 |
+|-----------|---------|----------|------|
+| `active`  | boolean | `false`  | 望み: 存在する間、画面を起こし続ける。看板バインディング（`active: isPlaying`）。 |
+| `type`    | string  | `screen` | ロックの種類。標準化されているのは `screen` のみ。属性は将来互換のために存在。 |
+| `manual`  | boolean | `false`  | `active` が付いていても接続時に自動取得しない。代わりに `request()` / `release()` で駆動する。 |
+
+> **`manual` は接続時のポリシーであり、ライブなスイッチではありません。** 接続 *後* に `manual` 属性を外しても自動取得はしません — `active` をトグルするか `request()` を呼んでください。（ライブな `active` のトグルは `manual` に関係なく常に request/release を駆動します。）
+
+## 出力ステート
+
+| プロパティ | 型               | 説明 |
+|----------|------------------|------|
+| `held`   | `boolean`        | wake lock の sentinel をいま保持しているか。OS の自動解放と再取得を反映する。 |
+| `error`  | `Error \| null`  | 直近のリクエスト失敗（拒否、未対応など）、または `null`。 |
+
+> **`wcs-wakelock:error` は単なる失敗シグナルではなく、プロパティ変更通知**（wc-bindable モデル）です: 失敗時には `detail` = エラーで発火し、その後のリクエストが成功して `error` プロパティがクリアされると `detail = null` で再度発火します。`error == null` は「過去に一度もエラーがなかった」ではなく「いまエラーがない」と解釈してください。
+
+## コマンド
+
+| コマンド     | 説明 |
+|-------------|------|
+| `request()` | ロックを望み状態にして取得する（可視かつ対応環境なら）。reject しない — `error` を参照。 |
+| `release()` | ロックを望まない状態にして、保持中の sentinel を解放する。 |
+
+## Binding Contract（`wcBindable`）
+
+Core も Shell も [wc-bindable](https://github.com/csbc-dev) プロトコルを宣言します。
+
+```js
+// WakeLockCore (ヘッドレス)
+WakeLockCore.wcBindable = {
+  protocol: "wc-bindable",
+  version: 1,
+  properties: [
+    { name: "held", event: "wcs-wakelock:held-changed" },
+    { name: "error", event: "wcs-wakelock:error" },
+  ],
+  commands: [
+    { name: "request", async: true }, { name: "release" },
+  ],
+};
+```
+
+Shell（`<wcs-wakelock>`）は Core の `properties` / `commands` を継承し、DOM 駆動の `inputs`（`active`, `type`, `manual`）を宣言します。
+
+## Core を単体で使う
+
+`WakeLockCore` はフレームワーク非依存で、カスタム要素なしでも使えます:
+
+```js
+import { WakeLockCore } from "@wcstack/wakelock";
+
+const core = new WakeLockCore();
+core.addEventListener("wcs-wakelock:held-changed", (e) => {
+  console.log("screen awake:", e.detail);
+});
+
+await core.request();   // 取得（そして可視性変化をまたいで維持）
+// 後で
+core.release();         // 起こし続けるのを停止
+core.dispose();         // visibilitychange リスナを除去
+```
+
+Core を直接駆動する場合は、終わったら `dispose()` を呼んで `visibilitychange` リスナを除去してください。
+
+## ノートと制限
+
+- **プロデューサーではなくシンク。** 他の @wcstack センサーとは違い、wake lock は状態に *よって* 駆動されます（`state → element`）。それが返すのは `held` だけです。
+- **自動解放は肩代わりされます。** OS は複数の理由でロックを落とします — ページの非表示だけでなく、ページが可視のままでもバッテリー低下や省電力モードで落ちることがあります。コンポーネントはどちらの場合もリースを更新します: *可視*中の解放は即座に再取得し、*非表示*中の解放は次に可視へ戻ったときに再取得します（`active` が立っている限り）。このバインディングは「一度取得する」ではなく「active の **間** 起こし続ける」を意味します。再取得が**拒否**された場合はループせず、`error` で surface して静止します（支配的なケース: 仕様上バッテリー低下/省電力下の再リクエストは拒否されます）。再取得が**許可**された場合はリースを更新するため、OS が許可と解放を繰り返す限りコンポーネントも更新を続けます（解放1回につき request 1回、OS 駆動であり同期的なスピンではありません）。
+- **セキュアコンテキスト（HTTPS）。** Screen Wake Lock API はセキュアコンテキスト（HTTPS、または `localhost`）でのみ動作します。
+- **決して throw しない。** 未対応環境はサイレントな no-op（`held` は `false` のまま）。拒否されたリクエストは throw せず `error` プロパティで surface します。`request()` は決して reject しません。
+- **パーミッションゲートなし。** 別個のパーミッションプロンプトはありません（ページが可視でない場合はリクエストが拒否されることがあり、それは `error` として surface します）。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,175 @@
+# @wcstack/wakelock
+
+`@wcstack/wakelock` is a headless Screen Wake Lock component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** — but, unlike every other @wcstack sensor, it runs *the other way*. `@wcstack/geolocation`, `@wcstack/intersection`, and friends are **producers** (`element → state`): they turn a device signal into reactive state. `@wcstack/wakelock` is a **pure sink** (`state → element`): a bound boolean drives whether the screen is kept awake.
+
+With `@wcstack/state`, `<wcs-wakelock>` reads as one declarative line:
+
+```html
+<wcs-wakelock data-wcs="active: isPlaying"></wcs-wakelock>
+```
+
+*"Keep the screen awake **while** `isPlaying` is true."* No `navigator.wakeLock.request()`, no `visibilitychange` re-acquire glue, no teardown.
+
+- **input surface**: `active`, `type`, `manual`
+- **output state surface**: `held`, `error`
+- **commands**: `request()`, `release()`
+
+`@wcstack/wakelock` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`WakeLockCore`) owns the sentinel, the desired/actual split, the auto-release re-acquire loop, and never-throw failure handling
+- **Shell** (`<wcs-wakelock>`) maps the `active` attribute to `request()` / `release()` and manages lifecycle
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`
+
+## Why this exists
+
+The Screen Wake Lock API has an awkward edge: the OS **automatically releases** the lock the moment the page stops being visible (tab hidden, window minimized). To actually "keep the screen awake while playing", you must hold the desired intent yourself and re-acquire the lock every time the page becomes visible again.
+
+`@wcstack/wakelock` moves that lease management into the component. You bind a boolean; the component keeps the lock alive across visibility changes for as long as the boolean is true.
+
+## Desired (`active`) vs actual (`held`)
+
+Because of auto-release, *what you want* and *what is currently held* diverge — so they are two separate surfaces:
+
+| Surface  | Direction        | Meaning |
+|----------|------------------|---------|
+| `active` | input            | **Desired intent.** Hold the lock while `true`. Survives an OS auto-release. |
+| `held`   | output           | **Actual state.** Whether a sentinel is held *right now*. Flips to `false` on auto-release, back to `true` when the page is visible again. |
+
+`active` is deliberately **not** an observable output: it does not change when the OS drops the lock — only `held` does. Bind `held` if your UI needs to reflect the live "screen is being kept awake" state.
+
+## Install
+
+```bash
+npm install @wcstack/wakelock
+```
+
+## Quick Start
+
+### Keep the screen awake during video playback
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/wakelock/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      playing: false,
+      startPlaying() { this.playing = true; },
+      stopPlaying() { this.playing = false; },
+    };
+  </script>
+
+  <video
+    src="/movie.mp4"
+    data-wcs="onplay: startPlaying; onpause: stopPlaying"
+  ></video>
+
+  <!-- Lock is held only while `playing` is true, and survives tab switches. -->
+  <wcs-wakelock data-wcs="active: playing"></wcs-wakelock>
+</wcs-state>
+```
+
+### Reflect the actual lock state in the UI
+
+```html
+<wcs-wakelock data-wcs="active: keepAwake; held: screenLocked"></wcs-wakelock>
+
+<span data-wcs="textContent: screenLocked"></span>
+```
+
+### Command-driven (imperative)
+
+```html
+<wcs-wakelock data-wcs="command.request: $command.stayAwake"></wcs-wakelock>
+```
+
+> **Commands do not mirror the `active` attribute.** The `request` / `release`
+> commands flip the desired intent on the Core directly without touching the
+> `active` attribute, so the element's `active` property (an attribute mirror) can
+> read `false` while `held` is `true` (or vice versa) after a command. Don't mix
+> command-driven control with `active` attribute binding on the same element —
+> pick one. Bind via `active: ...` for a single source of truth.
+
+## Attributes
+
+| Attribute | Type    | Default  | Description |
+|-----------|---------|----------|-------------|
+| `active`  | boolean | `false`  | Desired intent: hold the screen awake while present. The headline binding (`active: isPlaying`). |
+| `type`    | string  | `screen` | Lock type. Only `screen` is standardized; the attribute exists for forward compatibility. |
+| `manual`  | boolean | `false`  | Do not auto-acquire on connect even if `active` is present; drive via `request()` / `release()` instead. |
+
+> **`manual` is a connect-time policy, not a live switch.** Removing the `manual` attribute *after* connect does not auto-acquire — toggle `active` or call `request()`. (A live `active` toggle always drives request/release regardless of `manual`.)
+
+## Output state
+
+| Property | Type             | Description |
+|----------|------------------|-------------|
+| `held`   | `boolean`        | Whether a wake lock sentinel is currently held. Reflects OS auto-release and re-acquisition. |
+| `error`  | `Error \| null`  | The last request failure (e.g. denied, unsupported), or `null`. |
+
+> **`wcs-wakelock:error` is a property-change notification** (wc-bindable model), not just a failure signal: it fires with `detail` = the Error on a failed request, and fires again with `detail = null` when a later request succeeds and the `error` property is cleared. Read `error == null` as "no error *right now*", not "an error never happened".
+
+## Commands
+
+| Command     | Description |
+|-------------|-------------|
+| `request()` | Mark the lock desired and acquire it (if visible & supported). Never rejects — see `error`. |
+| `release()` | Mark the lock no longer desired and release any held sentinel. |
+
+## Binding Contract (`wcBindable`)
+
+Both the Core and the Shell declare the [wc-bindable](https://github.com/csbc-dev) protocol.
+
+```js
+// WakeLockCore (headless)
+WakeLockCore.wcBindable = {
+  protocol: "wc-bindable",
+  version: 1,
+  properties: [
+    { name: "held", event: "wcs-wakelock:held-changed" },
+    { name: "error", event: "wcs-wakelock:error" },
+  ],
+  commands: [
+    { name: "request", async: true }, { name: "release" },
+  ],
+};
+```
+
+The Shell (`<wcs-wakelock>`) inherits the Core's `properties` / `commands` and declares the DOM-driven `inputs` (`active`, `type`, `manual`).
+
+## Using the Core standalone
+
+`WakeLockCore` is framework-agnostic and can be used without the custom element:
+
+```js
+import { WakeLockCore } from "@wcstack/wakelock";
+
+const core = new WakeLockCore();
+core.addEventListener("wcs-wakelock:held-changed", (e) => {
+  console.log("screen awake:", e.detail);
+});
+
+await core.request();   // acquire (and keep across visibility changes)
+// later
+core.release();         // stop keeping awake
+core.dispose();         // remove the visibilitychange listener
+```
+
+When you drive the Core directly, call `dispose()` when you are done so its
+`visibilitychange` listener is removed.
+
+## Notes & limitations
+
+- **Sink, not producer.** Unlike the other @wcstack sensors, the wake lock is driven *by* state (`state → element`). `held` is the only thing it produces back.
+- **Auto-release is handled for you.** The OS may drop the lock for several reasons — the page being hidden, but also battery-low or power-saver mode while the page stays visible. The component renews the lease in both cases: a release while *visible* is re-acquired immediately, and a release while *hidden* is re-acquired on the next return to visibility — as long as `active` is still set. The binding means "keep awake *while* active", not "acquire once". A **denied** re-acquire does not loop — it surfaces via `error` and stays quiet (the dominant case: the spec rejects re-requests under battery-low / power-saver). A **granted** re-acquire renews the lease, so if the OS keeps granting and releasing, the component keeps renewing (one request per release, driven by the OS, not a synchronous spin).
+- **Secure context (HTTPS).** The Screen Wake Lock API only works in a secure context (HTTPS, or `localhost`).
+- **Never throws.** An unsupported environment is a silent no-op (`held` stays `false`); a rejected request surfaces via the `error` property rather than throwing. `request()` never rejects.
+- **No permission gate.** There is no separate permission prompt (a request may still be denied if the page is not visible — that surfaces as `error`).
+
+## License
+
+MIT

package/dist/auto.js

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

package/dist/auto.min.js

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

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+interface ITagNames {
+    readonly wakelock: string;
+}
+interface IWritableTagNames {
+    wakelock?: string;
+}
+interface IConfig {
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    tagNames?: IWritableTagNames;
+}
+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: number;
+    readonly properties: IWcBindableProperty[];
+    readonly inputs?: IWcBindableInput[];
+    readonly commands?: IWcBindableCommand[];
+}
+/**
+ * Wake lock type. The spec currently standardizes only `"screen"`; the field
+ * exists for forward compatibility with future lock types.
+ */
+type WakeLockKind = "screen";
+/**
+ * Value types for WakeLockCore (headless) — the observable state properties.
+ * Use with `bind()` from `@wc-bindable/core` for compile-time type checking.
+ *
+ * Unlike the @wcstack sensor tags (geolocation / intersection), the wake lock is
+ * a pure *sink*: a bound state drives whether the lock is held (`active`, an
+ * input), and the only outputs are `held` — whether a sentinel is actually held
+ * right now — and `error`. `active` (the desired intent) is deliberately not an
+ * observable output: it does not change when the OS auto-releases the lock, only
+ * `held` does.
+ *
+ * @example
+ * ```typescript
+ * const core = new WakeLockCore();
+ * bind(core, (name: keyof WcsWakeLockCoreValues, value) => { ... });
+ * await core.request();
+ * ```
+ */
+interface WcsWakeLockCoreValues {
+    /** Whether a wake lock sentinel is currently held (actual state). */
+    held: boolean;
+    /** The last request failure, or `null` while none. */
+    error: Error | null;
+}
+/**
+ * Value types for the Shell (`<wcs-wakelock>`) — identical observable surface to
+ * the Core (`held` / `error`).
+ */
+type WcsWakeLockValues = WcsWakeLockCoreValues;
+interface WcsWakeLockInputs {
+    /**
+     * Desired intent: hold the screen awake while `true`. The headline declarative
+     * binding (`active@isPlaying`). Mirrored to the `active` boolean attribute.
+     * Setting it `false` releases the lock. It stays `true` across an OS auto-release
+     * (tab hidden) so the lock is re-acquired when the page becomes visible again —
+     * read `held` for the actual current state.
+     */
+    active: boolean;
+    /** Lock type. Only `"screen"` is standardized; defaults to `"screen"`. */
+    type: WakeLockKind;
+    /** Do not auto-acquire on connect even if `active` is present; drive via commands. */
+    manual: boolean;
+}
+interface WcsWakeLockCoreCommands {
+    /**
+     * Mark the lock as desired and acquire it (if the page is visible and the API
+     * is supported). Never rejects — a failure surfaces via the `error` property.
+     */
+    request(): Promise<void>;
+    /** Mark the lock as no longer desired and release any held sentinel. */
+    release(): void;
+}
+interface WcsWakeLockCommands {
+    request(): Promise<void>;
+    release(): void;
+}
+
+declare function bootstrapWakeLock(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+/**
+ * Headless screen-wake-lock primitive — a thin, framework-agnostic wrapper around
+ * the Screen Wake Lock API exposed through the wc-bindable protocol.
+ *
+ * Unlike the other @wcstack sensors (geolocation / intersection), the wake lock is
+ * a pure *sink*: nothing is read from the device. A bound state drives the desired
+ * intent (`request()` / `release()`), and the only observable outputs are `held`
+ * (whether a sentinel is actually held) and `error`.
+ *
+ * The OS releases the lock whenever the page stops being visible (tab hidden,
+ * window minimized). To honor the declarative intent ("keep awake *while* active"),
+ * the Core keeps the desired flag (`_active`) and re-acquires the lock on the next
+ * `visibilitychange` back to visible. So `_active` (desired) and `held` (actual)
+ * diverge across an auto-release — and only `held` is published, because desired
+ * does not change when the OS drops the lock.
+ *
+ * Never-throw: `request()` never rejects (a failure surfaces via `error`), and an
+ * unsupported environment is a silent no-op (`held` stays false), consistent with
+ * the other @wcstack sensors.
+ */
+declare class WakeLockCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _type;
+    private _active;
+    private _held;
+    private _error;
+    private _sentinel;
+    private _gen;
+    private _acquiring;
+    private _visibilityBound;
+    constructor(target?: EventTarget, type?: WakeLockKind);
+    get held(): boolean;
+    get error(): Error | null;
+    /** The desired intent. Read-only reflection; not a wc-bindable property (it does
+     * not change on an OS auto-release, so there is nothing to observe). */
+    get active(): boolean;
+    get type(): WakeLockKind;
+    set type(value: WakeLockKind);
+    private _setHeld;
+    private _setError;
+    private _sameError;
+    /**
+     * Mark the lock as desired and acquire it. Idempotent while already held. If the
+     * API is unavailable or the page is currently hidden, the desired flag is still
+     * set (so the lock is acquired on the next return to visibility) but nothing is
+     * acquired now. Never rejects — a request failure surfaces via `error`.
+     */
+    request(): Promise<void>;
+    /** Mark the lock as no longer desired and release any held sentinel. */
+    release(): void;
+    /**
+     * Full teardown: remove the visibility listener and release any held sentinel.
+     * Call from the Shell's `disconnectedCallback`.
+     *
+     * Semantics: this is a terminal teardown, not a pause. After `dispose()` the Core
+     * is meant to be discarded — there is no re-arm step, and the visibility listener
+     * is gone, so an OS auto-release will no longer be followed by a re-acquire. A
+     * later `request()` would still work in isolation (it re-attaches the listener via
+     * `_ensureVisibilityListener`), but reusing a disposed Core is not an intended path;
+     * the Shell always constructs a fresh Core per element instead.
+     */
+    dispose(): void;
+    private _acquire;
+    /**
+     * Re-attempt an acquire after an in-flight one was *superseded* (its generation no
+     * longer matches), but only if the lock is still desired, not already held, and the
+     * page is visible. This recovers a request() that was coalesced away by the
+     * in-flight `_acquiring` guard: during a release()→request() overlap, the second
+     * request() bumps `_gen` and is a no-op at the guard, so without this retry its
+     * still-live intent would be lost until the next visibilitychange or manual call.
+     *
+     * Bounded — cannot loop forever: a retry runs ONLY on supersession, and a
+     * supersession requires an external release()/request() to bump `_gen` mid-flight.
+     * A retry's own `_acquire()`, if it is itself not superseded, terminates by either
+     * acquiring (held=true) or recording the live failure (held=false, error set) —
+     * neither path retries. So a denied environment that keeps rejecting does not
+     * recurse; the retry chain length is bounded by the number of external overlaps.
+     */
+    private _retryIfStillDesired;
+    private _onRelease;
+    /**
+     * Lease renewal after an OS release while the page is still visible. Honors the
+     * "keep awake *while* active" promise for releases that do NOT coincide with a
+     * visibility change (battery-low / power-saver), which otherwise leave the lock
+     * stuck at desired=true / held=false until the next hide→show cycle.
+     *
+     * Bounded on failure: this only runs from `_onRelease`, which only fires when a
+     * sentinel was genuinely acquired and then released. A re-acquire that FAILS takes
+     * `_acquire()`'s live-failure path (error recorded, held=false) and attaches no
+     * listener, so it cannot re-enter `_onRelease` — a denied environment records the
+     * error once and stops. This is the dominant real path: per the Wake Lock spec a
+     * re-request under battery-low / power-saver is rejected (`NotAllowedError`), so the
+     * renewal terminates there.
+     *
+     * The one path NOT bounded by a counter is a pathological host that keeps GRANTING
+     * the re-request and then immediately auto-releasing it (grant→release reflux). Each
+     * iteration yields to the event loop and consumes a real OS grant, so it is not a
+     * tight/synchronous loop, but it would churn request() calls. We deliberately do NOT
+     * add a debounce or renewal cap: that reflux is not documented browser behavior
+     * (real browsers reject, not grant-then-revoke), and the extra timing state would
+     * complicate the pure-sink design to defend a case that does not occur in practice.
+     *
+     * The `_isVisible()` / `!_acquiring` guards (doubled by `_acquire()`'s own in-flight
+     * and held guards) prevent re-entry during an in-flight acquire and while hidden.
+     */
+    private _reacquireAfterRelease;
+    private _onVisibilityChange;
+    private _ensureVisibilityListener;
+    private _wakeLock;
+    private _isVisible;
+    private _normalizeError;
+}
+
+/**
+ * `<wcs-wakelock>` — declarative Screen Wake Lock.
+ *
+ * The first @wcstack tag that is a pure *sink*: every other sensor is an
+ * element→state producer, but the wake lock is state→element. The headline
+ * binding is `active@isPlaying` — hold the screen awake while a bound boolean is
+ * true. `active` is the single input knob (a mirrored attribute); `held` and
+ * `error` are the observable outputs.
+ *
+ * The OS auto-releases the lock when the page is hidden; the Core re-acquires it
+ * on the next return to visibility while `active` is still set, so the binding
+ * means "keep awake *while* active", not just "acquire once".
+ */
+declare class WcsWakeLock extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    static observedAttributes: string[];
+    static wcBindable: IWcBindable;
+    private _core;
+    constructor();
+    get active(): boolean;
+    set active(value: boolean);
+    get type(): WakeLockKind;
+    set type(value: WakeLockKind);
+    get manual(): boolean;
+    set manual(value: boolean);
+    get held(): boolean;
+    get error(): Error | null;
+    /** Acquire (and keep) the wake lock. Never rejects — see the `error` property. */
+    request(): Promise<void>;
+    /** Release the wake lock and stop re-acquiring it. */
+    release(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}
+
+export { WakeLockCore, WcsWakeLock, bootstrapWakeLock, getConfig };
+export type { IWritableConfig, IWritableTagNames, WakeLockKind, WcsWakeLockCommands, WcsWakeLockCoreCommands, WcsWakeLockCoreValues, WcsWakeLockInputs, WcsWakeLockValues };