@wcstack/raf 1.18.0

package/README.ja.md

@@ -0,0 +1,176 @@
+# @wcstack/raf
+
+`@wcstack/raf` は wcstack エコシステムのヘッドレス requestAnimationFrame コンポーネントです。
+
+視覚的な UI ウィジェットではありません。
+ブラウザの「描画機会」をリアクティブな状態に変える**非同期プリミティブノード**であり、時間源を周期（`setInterval`）からフレーム（`requestAnimationFrame`）に差し替えた `@wcstack/timer` の兄弟です。
+
+`@wcstack/state` と組み合わせると、`<wcs-raf>` はパス契約で直接バインドできます:
+
+- **入力面**: `once` / `repeat` / `manual` / `trigger`
+- **出力状態面**: `tick` / `elapsed` / `dt` / `running` / `suspended`
+- **コマンド**: `start` / `stop` / `reset` / `pause` / `resume`
+
+ゲームループやアニメーションドライバを、rAF の再登録・dt の簿記・後始末コードなしに、HTML で宣言的に書けるということです。
+
+## なぜ存在するか — `wcs-timer` とどう使い分けるか
+
+`<wcs-timer interval="16">` でもゲームループは回せますが、`setInterval` はディスプレイのリフレッシュに揃わず、フレーム差分は利用側で自前計測が必要でした。`<wcs-raf>` は実際の描画機会で tick し、差分（`dt`）を一級の出力として配ります。
+
+| | `<wcs-timer>` | `<wcs-raf>` |
+|---|---|---|
+| 時間源 | `setInterval`（選んだ周期） | `requestAnimationFrame`（ディスプレイのフレーム） |
+| `interval` 入力 | あり | **なし** — rAF に周期は無い |
+| `dt` 出力 | なし | **あり**（中断を跨ぐと `0`、下記参照） |
+| 非表示タブ | ~1Hz にスロットル | **完全停止** — `suspended` で顕在化 |
+| 向く用途 | ポーリング・カウントダウン・時計 | ゲームループ・アニメーション・毎フレーム計測 |
+
+## インストール
+
+```bash
+npm install @wcstack/raf
+```
+
+## クイックスタート
+
+### 1. 宣言的ゲームループ
+
+`<wcs-raf>` は DOM に接続されると自動でフレームループを開始します。`tick` / `dt` をバインドするか、event token でフレームを受けて 1 フレーム 1 ステップを回します:
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/raf/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      x: 0,
+      $eventTokens: ["frame"],
+      $on: {
+        frame: (state, e) => { state.x += 60 * (e.detail.dt / 1000); }, // 60px/s
+      },
+      get transform() { return `translateX(${this.x}px)`; },
+    };
+  </script>
+</wcs-state>
+
+<wcs-raf data-wcs="eventToken.tick: frame"></wcs-raf>
+<div class="box" data-wcs="style.transform: transform"></div>
+```
+
+`e.detail` は `{ count, elapsed, dt, timestamp }` を運びます — `dt` で積分すればフレームレート非依存の運動になります。
+
+### 2. 1 フレームだけ（rAF 一発呼びの宣言化）
+
+`once` は次の描画機会にちょうど 1 tick 発火して自動停止します:
+
+```html
+<wcs-raf once data-wcs="tick: afterNextPaint"></wcs-raf>
+```
+
+補足: 自動 start された `once` フレームは接続の約 1 フレーム後に一度だけ発火し、再発火しません。state 自体を非同期ロードする構成（`<wcs-state src="...">` 等）ではバインディングの attach がこの唯一の tick より遅れ、永久に取りこぼす可能性があります。その構成では `manual` にして state 準備後にコマンド / trigger で起動するか、state をインラインにしてください（同一タスク内の attach は必ず間に合います）。
+
+### 3. 有限フレーム
+
+`repeat="N"` は N フレームで停止します（`running` が `false` になります）。
+
+## 属性 / 入力
+
+| 属性 | 型 | 既定 | 説明 |
+| --------- | ------- | ------- | ------------ |
+| `once`    | boolean | `false` | 1 フレームだけ発火して停止。`repeat="1"` の糖衣。 |
+| `repeat`  | number  | `0`     | N フレームで停止（`0` = 無制限）。`once` より優先。 |
+| `manual`  | boolean | `false` | 接続時に自動 start しない。コマンド / trigger で開始。 |
+
+`<wcs-timer>` から意図的に削除したもの: `interval`（rAF に周期は無い）と `immediate`（初回フレームがすでに「次の描画機会」であり、それより早い意味のある時点が存在しない）。
+
+## 観測可能プロパティ（出力）
+
+| プロパティ | イベント | 説明 |
+| ----------- | ------------------------- | ------------ |
+| `tick`      | `wcs-raf:tick`            | フレームカウンタ。毎発火で増加（`reset` で 0）。 |
+| `elapsed`   | `wcs-raf:tick`            | 最後の reset からの**アクティブ**時間（Σdt、ms）。非表示・ポーズ期間は加算されない。粒度はフレーム単位。 |
+| `dt`        | `wcs-raf:tick`            | 直前フレームとの差分（ms）。**`start()` / `resume()` / visibility 中断の直後の初回フレームは `0`** — 中断を跨いだ値は観測者に届かない。上限クランプは無し: 遅いフレームの扱いはドメイン判断（物理ループなら自前の `Math.min(dt, …)`）。 |
+| `running`   | `wcs-raf:running-changed` | 開始済みの**意図**。非表示タブでフレームが届かなくても `true` のまま。 |
+| `suspended` | `wcs-raf:suspended-changed` | 配送の**実態**。`running` かつ非表示タブで `true`（rAF はスロットルでなく完全停止）。desired/actual の分離は `@wcstack/wakelock` の `active`/`held` と同型。 |
+
+`tick` / `elapsed` / `dt` は単一の `wcs-raf:tick` イベントからの派生です（`detail = { count, elapsed, dt, timestamp }`。`timestamp` はフレームの `DOMHighResTimeStamp`、`reset()` 通知では `0`）。`tick` は同値ガード無しで毎フレーム発火、`running` / `suspended` は同値ガード付きです。
+
+## コマンド
+
+| コマンド | 説明 |
+| --------- | ----------------------------------------------------------------------- |
+| `start`   | フレームループ開始（実行中は no-op）。 |
+| `stop`    | 停止。`tick` / `elapsed` は保持。 |
+| `reset`   | 停止して `tick` / `elapsed` / `dt` を `0` に。 |
+| `pause`   | 値と有限 run の残数を保持したまま中断。 |
+| `resume`  | `pause` から再開。直後の初回フレームは `dt = 0`。 |
+
+state からの起動は command-token プロトコルで:
+
+```html
+<wcs-raf manual data-wcs="command.start: $command.beginLoop"></wcs-raf>
+```
+
+## DOM トリガー（オプション）
+
+`autoTrigger`（既定 on）が有効なら、`data-raftarget="<id>"` を持つ要素のクリックで対象 `<wcs-raf>` の `start()` が呼ばれます。マッチしたクリックは `event.preventDefault()` されます — デフォルトアクションも活かしたい要素（実リンク・submit ボタン等）には `data-raftarget` を付けないでください。
+
+```html
+<button data-raftarget="loop">Start</button>
+<wcs-raf id="loop" manual data-wcs="eventToken.tick: frame"></wcs-raf>
+```
+
+## `:state()` による CSS スタイリング
+
+`<wcs-raf>` は 2 つの boolean 出力状態を CustomStateSet に反映します:
+
+| 状態 | オンになる条件 |
+|-------|---------|
+| `running` | `wcs-raf:running-changed` が `true` で発火（`false` でクリア） |
+| `suspended` | `wcs-raf:suspended-changed` が `true` で発火（`false` でクリア） |
+
+```css
+wcs-raf:state(running) ~ .indicator { color: green; }
+wcs-raf:state(suspended) ~ .indicator { color: orange; } /* タブ非表示でループ枯渇 */
+```
+
+対応: Chrome/Edge 125+、Safari 17.4+、Firefox 126+。非対応環境では状態が付かないだけで動作は継続します（graceful degradation / never-throw）。`debug-states` 属性は DevTools 用に `data-wcs-state-*` 属性をミラーします（デバッグ補助のみ — CSS は `:state()` に書くこと）。
+
+## 注意と制約
+
+- **非表示タブで rAF は完全停止します**（`setInterval` の ~1Hz スロットルと違う点）。`running` は意図を、`suspended` は実態を報告し、`elapsed` はアクティブ時間のみを数え、復帰後の初回フレームは `dt = 0` — dt 積分する利用側がテレポートを見ることはありません。
+- **`error` 面はありません。** rAF に恒常的な失敗モードは無く、rAF の無い環境（SSR プリパス、worker）では `start()` が silent no-op になります（never-throw）。
+- **SSR**: サーバーレンダリングするマークアップでは `manual` を推奨 — 自動開始したループは DOM エミュレーション環境でもフレームを予約し続けます。
+- プラットフォーム API は呼び出し時に解決され（`globalThis.requestAnimationFrame`）、テスト用に `RafCore` へスケジューラを注入できます。
+
+## ヘッドレス利用（`RafCore`）
+
+```typescript
+import { RafCore } from "@wcstack/raf";
+
+const core = new RafCore();
+core.addEventListener("wcs-raf:tick", (e) => {
+  console.log((e as CustomEvent).detail); // { count, elapsed, dt, timestamp }
+});
+core.observe();  // visibilitychange を購読（`suspended` と hidden 跨ぎの dt=0 正規化の両方を駆動）
+core.start();
+// 後で:
+core.dispose();
+```
+
+## 設定
+
+```javascript
+import { bootstrapRaf } from "@wcstack/raf";
+
+bootstrapRaf({
+  autoTrigger: true,               // data-raftarget クリック起動（既定: true）
+  triggerAttribute: "data-raftarget",
+  tagNames: { raf: "wcs-raf" },
+});
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,177 @@
+# @wcstack/raf
+
+`@wcstack/raf` is a headless requestAnimationFrame component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns the browser's rendering opportunities into reactive state — `@wcstack/timer`'s sibling with the time source swapped from a period (`setInterval`) to the frame (`requestAnimationFrame`).
+
+With `@wcstack/state`, `<wcs-raf>` can be bound directly through path contracts:
+
+- **input surface**: `once`, `repeat`, `manual`, `trigger`
+- **output state surface**: `tick`, `elapsed`, `dt`, `running`, `suspended`
+- **commands**: `start`, `stop`, `reset`, `pause`, `resume`
+
+This means a game loop or animation driver can be expressed declaratively in HTML, without writing `requestAnimationFrame` re-registration, dt bookkeeping, or teardown glue in your UI layer.
+
+## Why this exists — and when to prefer it over `wcs-timer`
+
+`<wcs-timer interval="16">` can drive a game loop, but `setInterval` is not aligned to the display's refresh, and consumers must measure their own frame delta. `<wcs-raf>` ticks on the browser's actual rendering opportunity and ships the delta as a first-class output.
+
+| | `<wcs-timer>` | `<wcs-raf>` |
+|---|---|---|
+| Time source | `setInterval` (a period you choose) | `requestAnimationFrame` (the display's frame) |
+| `interval` input | yes | **no** — rAF has no period |
+| `dt` output | no | **yes** (`0` across interruptions, see below) |
+| Hidden tab | throttled (~1Hz) | **fully stopped** — surfaced via `suspended` |
+| Use for | polling, countdowns, clocks | game loops, animation, per-frame measurement |
+
+## Install
+
+```bash
+npm install @wcstack/raf
+```
+
+## Quick Start
+
+### 1. A declarative game loop
+
+When `<wcs-raf>` is connected to the DOM, it automatically starts a frame loop. Bind `tick` / `dt` to state paths — or receive the frame as an event token and run one physics step per frame:
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/raf/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      x: 0,
+      $eventTokens: ["frame"],
+      $on: {
+        frame: (state, e) => { state.x += 60 * (e.detail.dt / 1000); }, // 60px/s
+      },
+      get transform() { return `translateX(${this.x}px)`; },
+    };
+  </script>
+</wcs-state>
+
+<wcs-raf data-wcs="eventToken.tick: frame"></wcs-raf>
+<div class="box" data-wcs="style.transform: transform"></div>
+```
+
+`e.detail` carries `{ count, elapsed, dt, timestamp }` — integrate against `dt` and the motion speed is frame-rate independent.
+
+### 2. One frame (`requestAnimationFrame`-once equivalent)
+
+`once` fires exactly one tick on the next rendering opportunity, then auto-stops — the declarative form of a single rAF call:
+
+```html
+<wcs-raf once data-wcs="tick: afterNextPaint"></wcs-raf>
+```
+
+Note: the auto-started `once` frame fires about one frame after connect, exactly once — it is never re-fired. If the state itself loads asynchronously (e.g. `<wcs-state src="...">`), its binding may attach after that single tick and miss it permanently. In that setup use `manual` and start via a command / trigger once the state is ready, or keep the state inline (same-task attach is always in time).
+
+### 3. Bounded frames
+
+`repeat="N"` fires `N` frames and then stops (`running` becomes `false`).
+
+## Attributes / Inputs
+
+| Attribute | Type    | Default | Description |
+| --------- | ------- | ------- | ------------ |
+| `once`    | boolean | `false` | Fire a single frame, then stop. Sugar for `repeat="1"`. |
+| `repeat`  | number  | `0`     | Stop after N frames (`0` = unlimited). Takes precedence over `once`. |
+| `manual`  | boolean | `false` | Do not auto-start on connect; start via command / trigger. |
+
+Deliberately absent vs `<wcs-timer>`: `interval` (rAF has no period) and `immediate` (the first frame already **is** the next rendering opportunity — no earlier meaningful moment exists).
+
+## Observable Properties (outputs)
+
+| Property    | Event                     | Description |
+| ----------- | ------------------------- | ------------ |
+| `tick`      | `wcs-raf:tick`            | Frame counter, increments on every fire (reset to 0 on `reset`). |
+| `elapsed`   | `wcs-raf:tick`            | Accumulated **active** milliseconds (Σdt) since the last reset — hidden/paused periods contribute nothing. Frame-granular: between frames the getter returns the value as of the last tick. |
+| `dt`        | `wcs-raf:tick`            | Delta to the previous frame in ms. **`0` on the first frame after `start()` / `resume()` / a visibility interruption** — a value spanning an interruption never reaches observers. No upper clamp: how to treat a slow frame is your domain decision (a physics loop typically applies its own `Math.min(dt, …)`). |
+| `running`   | `wcs-raf:running-changed` | The started **intent**: `true` from `start` until `stop`/`pause`/bounded completion. Stays `true` in a hidden tab even though no frames arrive. |
+| `suspended` | `wcs-raf:suspended-changed` | The delivery **actuality**: `true` while `running` in a hidden tab (rAF is fully stopped there — not throttled). The desired/actual split mirrors `@wcstack/wakelock`'s `active`/`held`. |
+
+`tick` / `elapsed` / `dt` all derive from the single `wcs-raf:tick` event (`detail = { count, elapsed, dt, timestamp }`; `timestamp` is the frame's `DOMHighResTimeStamp`, `0` for the `reset()` notification). `tick` fires every frame with no equality guard; `running` / `suspended` are equality-guarded.
+
+## Commands
+
+| Command   | Description |
+| --------- | ----------------------------------------------------------------------- |
+| `start`   | Begin the frame loop (no-op if already running). |
+| `stop`    | Stop; `tick` / `elapsed` are retained. |
+| `reset`   | Stop and reset `tick` / `elapsed` / `dt` to `0`. |
+| `pause`   | Suspend the loop, preserving values and the bounded-run remainder. |
+| `resume`  | Continue from a `pause`; the first frame after it reports `dt = 0`. |
+
+State-driven invocation uses the command-token protocol:
+
+```html
+<wcs-raf manual data-wcs="command.start: $command.beginLoop"></wcs-raf>
+```
+
+## Optional DOM Triggering
+
+If `autoTrigger` is enabled (default), clicking an element carrying `data-raftarget="<id>"` calls `start()` on the referenced `<wcs-raf>`. A matched click calls `event.preventDefault()` — do not put `data-raftarget` on an element whose default action you also want.
+
+```html
+<button data-raftarget="loop">Start</button>
+<wcs-raf id="loop" manual data-wcs="eventToken.tick: frame"></wcs-raf>
+```
+
+## CSS styling with `:state()`
+
+`<wcs-raf>` reflects two boolean output states onto its
+[`ElementInternals` `CustomStateSet`](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet):
+
+| State | On when |
+|-------|---------|
+| `running` | `wcs-raf:running-changed` fires with `true` (cleared on `false`) |
+| `suspended` | `wcs-raf:suspended-changed` fires with `true` (cleared on `false`) |
+
+```css
+wcs-raf:state(running) ~ .indicator { color: green; }
+wcs-raf:state(suspended) ~ .indicator { color: orange; } /* tab hidden, loop starved */
+```
+
+**Browser support** (`:state(x)` syntax): Chrome/Edge 125+, Safari 17.4+, Firefox 126+. In older browsers the states are simply never set — `<wcs-raf>` itself keeps working (graceful degradation, never-throw). The `debug-states` attribute mirrors changes onto `data-wcs-state-*` attributes for DevTools inspection (debug aid only — style against `:state()`).
+
+## Notes & limitations
+
+- **Hidden tabs stop rAF completely** (unlike `setInterval`'s ~1Hz throttle). `running` keeps reporting the intent; `suspended` reports the reality; `elapsed` counts only active time; and the first frame after the tab becomes visible again reports `dt = 0`, so a dt-integrating consumer never sees a teleport.
+- **No `error` surface.** rAF has no persistent failure mode; on a platform without it (SSR pre-pass, worker), `start()` is a silent no-op (never-throw).
+- **SSR**: prefer `manual` in server-rendered markup — an auto-started loop keeps scheduling frames in DOM-emulating renderers.
+- The platform API is resolved at call time (`globalThis.requestAnimationFrame`), and a scheduler can be injected into `RafCore` for testing.
+
+## Headless usage (`RafCore`)
+
+```typescript
+import { RafCore } from "@wcstack/raf";
+
+const core = new RafCore();
+core.addEventListener("wcs-raf:tick", (e) => {
+  console.log((e as CustomEvent).detail); // { count, elapsed, dt, timestamp }
+});
+core.observe();  // subscribes visibilitychange (drives `suspended` AND the dt=0 normalization across hidden gaps)
+core.start();
+// later:
+core.dispose();
+```
+
+## Configuration
+
+```javascript
+import { bootstrapRaf } from "@wcstack/raf";
+
+bootstrapRaf({
+  autoTrigger: true,               // data-raftarget click triggering (default: true)
+  triggerAttribute: "data-raftarget",
+  tagNames: { raf: "wcs-raf" },
+});
+```
+
+## License
+
+MIT

package/dist/auto.js

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

package/dist/auto.min.js

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

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+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 raf: string;
+}
+interface IWritableTagNames {
+    raf?: string;
+}
+interface IConfig {
+    readonly autoTrigger: boolean;
+    readonly triggerAttribute: string;
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    autoTrigger?: boolean;
+    triggerAttribute?: string;
+    tagNames?: IWritableTagNames;
+}
+
+/**
+ * Payload carried by the `wcs-raf:tick` event.
+ * `count` is the number of frames fired since the last reset; `elapsed` is the
+ * accumulated ACTIVE milliseconds (Σdt — interruptions contribute nothing);
+ * `dt` is the delta to the previous frame within a continuous run, `0` on the
+ * first frame after start / resume / a visibility interruption; `timestamp` is
+ * the frame's `DOMHighResTimeStamp` (`0` for the reset() notification, which
+ * is not a frame).
+ */
+interface WcsRafTickDetail {
+    count: number;
+    elapsed: number;
+    dt: number;
+    timestamp: number;
+}
+/**
+ * Value types for RafCore (headless) — the observable state properties.
+ * Use with `bind()` from a wc-bindable binding core for compile-time type checking.
+ */
+interface WcsRafCoreValues {
+    tick: number;
+    elapsed: number;
+    dt: number;
+    running: boolean;
+    suspended: boolean;
+}
+/**
+ * Value types for the Shell (`<wcs-raf>`) — identical observable surface to
+ * the Core, plus the DOM-driven `trigger` command-property.
+ */
+interface WcsRafValues extends WcsRafCoreValues {
+    trigger: boolean;
+}
+interface WcsRafInputs {
+    once: boolean;
+    repeat: number;
+    manual: boolean;
+    trigger: boolean;
+}
+interface WcsRafCoreCommands {
+    start(options?: {
+        repeat?: number;
+    }): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+}
+interface WcsRafCommands {
+    start(): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+}
+
+declare function bootstrapRaf(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+interface RafStartOptions {
+    repeat?: number;
+}
+/**
+ * Injectable frame scheduler. The default resolves
+ * `globalThis.requestAnimationFrame` / `cancelAnimationFrame` AT CALL TIME
+ * (async-io-node-guidelines §3.7); tests inject a fake that pumps frames with
+ * explicit timestamps (the `dt` contract is timestamp-derived, so tests must
+ * control the clock, not just the callback order).
+ *
+ * Contract: `request()` MUST return a non-null handle. The core uses `null`
+ * as its internal "not armed" sentinel, so a scheduler returning literal
+ * `null` would silently corrupt the handle bookkeeping (re-entrancy guards
+ * and cancel tracking). Native rAF returns a long, so this only concerns
+ * custom scheduler injections — return a number, object, or any other
+ * non-nullish token.
+ */
+interface RafScheduler {
+    request(callback: (timestamp: number) => void): unknown;
+    cancel(handle: unknown): void;
+}
+/**
+ * Headless requestAnimationFrame primitive — `TimerCore`'s sibling with the
+ * time source swapped from `setInterval` (a period) to rAF (the browser's
+ * rendering opportunity). Exposed through the wc-bindable protocol: it streams
+ * `tick` (frame counter), `elapsed` (accumulated ACTIVE milliseconds), `dt`
+ * (delta to the previous frame) and the `running` / `suspended` pair, and is
+ * driven by the `start` / `stop` / `reset` / `pause` / `resume` commands.
+ *
+ * `tick` / `elapsed` / `dt` are all surfaced via the single `wcs-raf:tick`
+ * event (read through getters, mirroring how FetchCore exposes value/status
+ * from one `wcs-fetch:response` event).
+ *
+ * Contracts specific to this node (docs/raf-tag-design.md):
+ *
+ * - **dt describes continuous running only.** The first frame after `start()`,
+ *   `resume()`, or a visibility interruption reports `dt = 0` — a value that
+ *   spans an interruption never reaches observers. Like `suspended`, the
+ *   visibility boundary is only detected once observe() has subscribed to
+ *   `visibilitychange`; a headless setup that skips observe() will see the
+ *   raw spanning delta on the first frame after a hidden gap. There is
+ *   deliberately NO upper clamp: how to treat a slow frame is the consumer's
+ *   domain decision.
+ * - **elapsed is Σdt (active time).** Because interruption-spanning deltas are
+ *   normalized to 0, summing dt yields exactly the time frames were actually
+ *   being delivered — no separate segment bookkeeping is needed, and hidden /
+ *   paused periods contribute nothing. Granularity is one frame: between
+ *   frames the getter returns the value as of the last tick.
+ * - **running / suspended are a desired/actual pair** (the wakelock split): in
+ *   a hidden tab the browser delivers no frames at all, so `running` (the
+ *   started intent) stays true while `suspended` reports that delivery is
+ *   actually stopped. `suspended` is only meaningful after `observe()` has
+ *   subscribed to `visibilitychange`; without a document it stays false.
+ * - **No `error` surface.** rAF has no persistent failure mode; on a platform
+ *   without it, `start()` is a silent no-op (never-throw, resize precedent).
+ */
+declare class RafCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _injectedScheduler;
+    private _handle;
+    private _globalScheduler;
+    private _gen;
+    private _ready;
+    private _tick;
+    private _dt;
+    private _elapsed;
+    private _running;
+    private _suspended;
+    private _paused;
+    private _lastTs;
+    private _repeat;
+    private _runStartTick;
+    private _visibilityDoc;
+    constructor(target?: EventTarget, scheduler?: RafScheduler);
+    get tick(): number;
+    get elapsed(): number;
+    get dt(): number;
+    get running(): boolean;
+    get suspended(): boolean;
+    get ready(): Promise<void>;
+    observe(): Promise<void>;
+    dispose(): void;
+    private _dispatchTick;
+    private _setRunning;
+    private _setSuspended;
+    private _updateSuspended;
+    start(options?: RafStartOptions): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+    private _frame;
+    private _onVisibilityChange;
+    private _resolveScheduler;
+    private _requestFrame;
+    private _clearHandle;
+}
+
+declare class Raf extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    static wcBindable: IWcBindable;
+    private _core;
+    private _trigger;
+    private _connectedCallbackPromise;
+    private _internals;
+    constructor();
+    get debugStates(): string[];
+    private _initInternals;
+    private _wireStates;
+    get connectedCallbackPromise(): Promise<void>;
+    get once(): boolean;
+    set once(value: boolean);
+    get repeat(): number;
+    set repeat(value: number);
+    get manual(): boolean;
+    set manual(value: boolean);
+    get tick(): number;
+    get elapsed(): number;
+    get dt(): number;
+    get running(): boolean;
+    get suspended(): boolean;
+    get trigger(): boolean;
+    set trigger(value: boolean);
+    start(): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+
+export { RafCore, Raf as WcsRaf, bootstrapRaf, getConfig };
+export type { IWritableConfig, IWritableTagNames, RafScheduler, RafStartOptions, WcsRafCommands, WcsRafCoreCommands, WcsRafCoreValues, WcsRafInputs, WcsRafTickDetail, WcsRafValues };