# useKeyboard

Fluxlay デスクトップアプリからストリーミングされる **グローバル** キーボードイベントをサブスクライブします。ゲーム的な操作の壁紙に便利です。

ユーザーがデスクトップ上のどこで入力しても全イベントが壁紙に届きます（特定のウィンドウに絞られません）。**他アプリへの入力もすべて流れる** ため、壁紙はキーロガー扱いされ得る前提で利用してください。

## permissions 宣言が必須

このフックを使うには `fluxlay.yaml` で `keyboard` permission を宣言する必要があります。未宣言のまま購読すると backend が HTTP 403 を返し、イベントは一切届きません。

```yaml title="fluxlay.yaml"
schemaVersion: 1
name: My Wallpaper
slug: my-wallpaper
version: 1.0.0
permissions:
  - keyboard
```

permissions 全体の意味は [`manifest`](/ja/studio/developer/reference/cli/manifest.md#permissions) を参照してください。

## インポート

```tsx
import { useKeyboard } from "@fluxlay/react";
```

## シグネチャ

```tsx
function useKeyboard(handlers: KeyboardHandlers): void;

interface KeyboardHandlers {
  onKeyDown?: (event: KeyEvent) => void;
  onKeyUp?: (event: KeyEvent) => void;
}
```

## 使い方

```tsx
import { useKeyboard } from "@fluxlay/react";

function Wallpaper() {
  useKeyboard({
    onKeyDown: event => {
      console.log("down", event.code, event.modifiers, event.repeat);
    },
    onKeyUp: event => {
      console.log("up", event.code);
    }
  });
  return <div />;
}
```

## KeyEvent の型

| プロパティ  | 型             | 説明                                                                                                                                                            |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | `string`       | 物理キー識別子。Web `KeyboardEvent.code` に準拠（例: `"KeyA"`、`"Space"`、`"Digit1"`、`"ArrowLeft"`、`"ShiftLeft"`）。マッピング不能なキーは `"Unidentified"`。 |
| `pressed`   | `boolean`      | `true` で押下、`false` で解放。                                                                                                                                 |
| `repeat`    | `boolean`      | OS が auto-repeat と報告したか。Windows では low-level hook がフラグを出さないため、押下中キー集合を追跡して導出。                                              |
| `modifiers` | `KeyModifiers` | イベント発生時の修飾キー状態。                                                                                                                                  |

### KeyModifiers

| プロパティ | 型        | 説明                                    |
| ---------- | --------- | --------------------------------------- |
| `shift`    | `boolean` | Shift キー。                            |
| `control`  | `boolean` | Control キー。                          |
| `alt`      | `boolean` | Alt / Option キー。                     |
| `meta`     | `boolean` | macOS の Command / Windows のロゴキー。 |

## プラットフォーム要件

- **macOS**: ユーザーが Fluxlay に「入力監視」権限を付与している必要があります（システム設定 → プライバシーとセキュリティ → 入力監視）。
- **Windows**: グローバルフックがアンチウィルスに警告されることがあります。また、より高い整合性レベルで起動されたプロセス（管理者として実行されたアプリ等）に向けて入力されたキーは UIPI により届きません。