> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# bricks-ctor

> BRICKS アプリケーションをコードとして構築する TypeScript SDK

**bricks-ctor** は、[BRICKS](https://bricks.tools) アプリケーションをコードとして定義・構築・デプロイできる TypeScript SDK です。ビジュアルエディタで作業する代わりに TypeScript を書くと、BRICKS ランタイムが理解できる設定にコンパイルされます。

<Info>
  bricks-ctor は**プレビュー版**です。API とツールは変更される可能性があります。
</Info>

## コードで書くメリット

* **型安全性** — TypeScript の完全サポートにより、コンパイル時にエラーを検出
* **バージョン管理** — Git で変更を追跡、差分をレビュー、チームで協力
* **AI 支援開発** — プロジェクトファイルを読み書きできる AI コーディングエージェントと協業
* **自動化** — CLI または GitHub Actions などの CI/CD パイプラインでデプロイ

## コアコンセプト

bricks-ctor アプリケーションは、組み合わせ可能なエンティティのツリーです。構成要素は以下のとおりです:

```
Application
└── Subspace(機能/画面コンテナ)
    ├── Canvas(ビュー/シーンレイアウト)
    │   └── Items(Brick または Subspace 参照の配置要素)
    ├── Brick(UI コンポーネント)
    ├── Generator(データ/IO プロバイダー)
    ├── Data(状態ストレージ)
    ├── Animation(ビジュアルエフェクト)
    └── Data Calculation(データ変換)
```

### Subspaces

Subspace は独立した機能単位で、画面や機能モジュールと考えてください。各 subspace は独自の brick、generator、data、canvas、animation を持ちます。アプリケーションのエントリーポイントは `rootSubspace` です。

### Canvases

Canvas はビューレイアウトを定義します。アイテム(brick または subspace 参照)を `frame` 座標(x、y、幅、高さ)でグリッドに配置します。Canvas はライフサイクルイベント(`firstEnter`、`enter`、`exit`)をサポートし、ナビゲーションのために相互に切り替え可能です。

### Bricks

Brick はビジュアル構築要素 — コンテンツを表示しインタラクションを処理する UI コンポーネントです。主な例:

| Brick               | 用途                                                  |
| ------------------- | --------------------------------------------------- |
| **Text**            | スタイル付きテキスト表示                                        |
| **TextInput**       | 編集可能なテキストフィールド                                      |
| **RichText**        | HTML コンテンツ、複数フォント、インライン画像に対応したリッチテキスト               |
| **Image**           | 画像表示                                                |
| **Video**           | ビデオ再生                                               |
| **VideoStreaming**  | RTSP / RTMP ライブ映像ストリーミング                            |
| **WebrtcStream**    | WebRTC 映像・音声ストリーム                                   |
| **GenerativeMedia** | AI が生成する画像と動画                                       |
| **WebView**         | Web コンテンツを埋め込み                                      |
| **Lottie**          | `.json` と `.dotlottie` のアニメーション、速度・ループ・フレーム範囲の制御に対応 |
| **Rive**            | `.riv` アニメーション、ステートマシン入力・テキストラン・アートボード切り替えに対応       |
| **Svg**             | SVG ベクターグラフィックス                                     |
| **Chart**           | データ可視化                                              |
| **Icon**            | FontAwesome 6 Pro アイコン                              |
| **QrCode**          | QR コード表示                                            |
| **Camera**          | カメラのライブフィード                                         |
| **Maps**            | マップ表示                                               |
| **Rect**            | 背景・枠線・影を持つコンテナ                                      |
| **Items**           | 配列データから生成するリスト/グリッド                                 |
| **Slideshow**       | トランジション効果付きの自動切り替えスライド                              |

Brick はスタイル付け、アニメーション、プレスイベント応答が可能で、プロパティをデータに動的にバインドできます。

### Generators

Generator は外部 I/O とデータ処理をすべて担当します。アプリを API、データベース、ハードウェア、AI モデルなどに接続します。各 generator は**アウトレット**(出力チャネル)を通じてデータに値を流し、**イベント**でアクションをトリガーします。

Generator のカテゴリー:

| カテゴリー        | 例                                                                |
| ------------ | ---------------------------------------------------------------- |
| **AI & LLM** | Assistant、LLM (GGML/OpenAI/Anthropic/ONNX)、Vector Store、Reranker |
| **音声**       | Text-to-Speech、Speech-to-Text、VAD、リアルタイム文字起こし                    |
| **ネットワーク**   | HTTP、WebSocket、GraphQL、MQTT、TCP、UDP、HTTP Server                  |
| **ストレージ**    | File、SQLite、Data Bank、Media Flow                                 |
| **ハードウェア**   | Bluetooth LE、シリアルポート、カメラ、キーボード                                   |
| **制御フロー**    | Tick(タイマー)、Alarm Clock、Step、Iterator、Watchdog                    |
| **その他**      | WebRTC、Web Crawler、MCP、サーマルプリンタ                                  |

### Data

Data ノードはアプリケーションの状態を保持します。型を持ち(string、number、boolean、array、object)、brick や generator のプロパティに**リンク**することでリアクティブ更新が可能です。Generator のアウトレットが値を出力すると、リンクされた data が更新され、そのデータにバインドされた brick が自動的に再レンダリングされます。

### Data Calculations

Data calculation はデータを変換する JavaScript 関数です。サンドボックス環境で実行され、25 種類以上の組込みライブラリ(lodash、moment、crypto など)が利用できます。フォーマット、パース、派生値の計算に使用します。

### Actions とイベント

Action はイベントによってトリガーされるコマンドです。Brick と generator はイベント(press、response、error、タイマーティック)を発生させ、canvas の切替、data の更新、generator のトリガー、animation の実行などの action に接続します。

## プロジェクト構成

bricks-ctor プロジェクトの構成は以下のとおりです:

```
my-app/
├── application.json              # アプリのメタデータ(名前、ID、ステージ)
├── package.json
├── tsconfig.json
├── app.ts                        # アプリケーションのエントリーポイント
├── root.ts                       # ルート subspace 定義
├── subspaces/
│   └── subspace-0/
│       ├── index.ts              # Subspace エクスポート
│       ├── bricks.ts             # Brick 定義
│       ├── canvases.ts           # Canvas レイアウト
│       ├── generators.ts         # Generator 設定
│       ├── data.ts               # Data 定義
│       ├── animations.ts         # Animation 設定
│       └── data-calc/            # Data calculation スクリプト
│           └── index.ts
├── automation-tests/             # E2E テスト定義
├── CLAUDE.md / AGENTS.md         # AI エージェント指示(任意)
└── .mcp.json                     # MCP サーバー設定(自動生成)
```

アプリのロジックはすべて TypeScript ファイルで定義します。`bun compile` を実行すると、BRICKS ランタイムが実行する JSON 設定にコンパイルされます。

## 次のステップ

<Card title="はじめる" icon="rocket" href="/ja/ctor-pkg/getting-started">
  環境を設定し、最初の bricks-ctor プロジェクトを作成します。
</Card>