
Blockstudio7.5では、Blockstudioのファイル優先ワークフローをさらに充実させます。カスタムフィールドタイプ、ファイルベースのSite Editorテンプレート、ブロックアイランド、Storhのデータベースストレージ、論理的な検出ソース、組み合わせ可能なブロックタグ、デプロイとランタイムの処理経路の高速化が含まれます。

再利用可能なカスタムフィールドを使うと、既存フィールドのグループを一度定義して`type: "custom/{name}"`と共に再利用できます。カスタムフィールドタイプは別の課題を解決します。テーマやプラグインで名前空間付きの新しいフィールドタイプを登録し、独自のエディターコントロールを用意して、値を通常のBlockstudioデータとして保存できます。

要点は次のとおりです。

- **論理的な検出ソース**: ランタイムは、来歴情報とキャッシュ識別情報を含む、合成された論理テーマのインベントリを提供できます。その間、Blockstudioは検出、兄弟ファイルの解決、生成アセット、Canvas、Tailwindの動作を引き続き管理します。
- **PHPフィールド型レジストリ**: テーマやプラグインは、`bs_register_field_type()`を使う`acme/dimensions`や`blockstudio/field_types`フィルターなど、名前空間付きのフィールド型を登録できます。
- **エディターコントロールレジストリ**: カスタムエディタースクリプトは`window.blockstudio.registerFieldType()`を呼び出し、通常のBlockstudioフィールドUIで対応するReactコントロールを表示できます。
- **構造化値**: カスタムフィールドには、オブジェクト値をオプションフィールドの正規化に通して変換することなく、文字列、数値、真偽値、配列、オブジェクトを保存できます。
- **ストレージ対応**: 投稿メタデータやオプションベースのカスタムフィールドでは、オブジェクトや配列の値を含め、値の型とRESTスキーマを宣言できます。
- **ネイティブ連携**: カスタムフィールド型は、グループ、タブ、リピーター、再利用可能なカスタムフィールド、テンプレート、拡張テンプレートパスで使用できます。
- **Site Editorテンプレート**: テーマでは、`template.json`、`part.json`、Blockstudioのテンプレートファイルから`wp_template`と`wp_template_part`のソースを定義できます。
- **ブロックアイランド**: ブロックはまずキャッシュに安全なシェルを描画し、ページ読み込み後にリクエスト固有のフラグメントをハイドレートしたり、まとめて取得したりできます。
- **Storhデータベースストレージ**: `bs.db`では、uploads内のインデックス付きレコード別ファイルストアを使用でき、公開整数IDを維持したまま、WP-CLIを通じてJSONCからStorhへ移行できます。
- **パーサーとbsuiの改良**: マッピングされたリッチテキスト段落で必要なカスタムパーサー連携が減り、`InnerBlocks`ではトークン化された`allowedBlocks`を使えます。ネストされた`bs_render_block()`の出力はエディタープレビューでフロントエンドの描画と一致し、`bsui/button`にはアイコンと使いやすいスタイル設定フックが追加されました。
- **組み合わせ可能なブロックタグ**: プレフィックスタグは別のプレフィックスを経由して解決できます（`<theme-ui-input>`から`bsui/input`）。プレフィックスとエイリアスのタグは、ページコンテンツだけでなくブロックテンプレートの出力にも描画されます。
- **ホスト環境に安全なビルドキャッシュ**: ランタイムとエディターのキャッシュは、デフォルトでuploadsの外に保存されるようになりました。保存場所を設定でき、古いエントリーも削除されるため、長期間稼働するプロジェクトでキャッシュファイルが蓄積しません。
- **段階的なページ同期**: デプロイツールはページファイルの完全なインベントリを同期し、変更のない投稿をスキップして、変更内容を正確に報告できます。また、有効化後に検証済みのソース識別情報を保存できます。
- **ウォーム状態での高速描画**: 有効なランタイムキャッシュは検出前にハイドレートされ、同時に発生したコールドリクエストでは1つの結果だけがアトミックに公開されます。Tailwindはサイト規模のキャッシュと再利用可能なコンパイラー状態を保持します。
- **安全な一括描画**: エクスポーターは検出を再構築せずにドキュメント間でリクエスト単位の描画状態をリセットでき、ブロックの描画中にソース依存関係を収集できます。

## 新機能

7.5では、検出、テンプレート、ストレージにわたる幅広い新機能が追加されました。

### 論理的な検出ソース

Blockstudioは通常、物理的なテーマディレクトリからファイルを検出します。7.5では、オーバーレイ、プレビュー、生成ファイル、リモートマウントなどからテーマを組み立てるランタイム向けに、より低レベルのソースAPIが追加されました。

統合側は最終的な論理ファイルツリーを提供でき、ブロック、フィールド、ページ、パターン、Site Editor、Canvas、アセット、Tailwindの動作はBlockstudioが引き続き管理します。

```php title="functions.php"
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => ['layer' => 'parent'],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => ['layer' => 'preview'],
                    ],
                ],
                'preview-fingerprint'
            ),
        ];
    },
    10,
    2
);
```

兄弟ファイルが異なる物理ルートにあっても、論理パスは安定して保たれます。ソースIDとフィンガープリントはランタイムおよびTailwindのキャッシュ識別情報に反映され、監視対象の入力によってキャッシュが無効化されます。また、生成ファイルを書き込める場所は来歴情報によって制御されます。通常のテーマでは、デフォルトのファイルシステムソースに変更はありません。

### ファイルベースのSite Editorテンプレート

ページとパターンでは、チームがコンテンツ構造をファイルで管理できます。7.5ではこの方式がSite Editor自体にも拡張されました。

```text
theme/
  templates/
    front-page/
      template.json
      index.php
  parts/
    header/
      part.json
      index.php
```

```json title="templates/front-page/template.json"
{
  "slug": "front-page",
  "title": "Front Page"
}
```

```php title="templates/front-page/index.php"
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <block name="core/post-content" />
  </main>
</div>
```

Blockstudioはページやパターンと同じパーサーでソースをコンパイルし、通常のSite EditorテンプレートまたはテンプレートパーツとしてWordPressに公開します。Site Editorにテンプレートが表示され、フロントエンドで描画でき、カスタマイズの管理は引き続きWordPressが担います。

最後の点が重要です。ファイルベースのテンプレートはソースのフォールバックです。ユーザーがSite Editorでテンプレートを保存すると、WordPressは通常の`wp_template`または`wp_template_part`のデータベースカスタマイズを作成し、そのバージョンが優先されます。カスタマイズをリセットすると、最新のファイルソースが再び表示されます。

### 段階的なページデプロイ

ファイルベースのページに、7.5でデプロイ同期APIが追加されました。7.6.2では、明示的なAPIと`wp bs pages sync`だけが同期の実行経路です。通常のリクエストでソースの変更が適用されることはありません。

```php
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);
```

この処理では、必要なページの完全なインベントリを検出し、コンテンツと同期エンジンのフィンガープリントを比較して、作成、更新、変更なし、削除、失敗の各ページを報告します。フィンガープリントが一致するページでは、投稿や投稿メタデータへの書き込みは行われません。管理対象のページが見つからない場合も、検出がエラーなく完了した後にのみ削除されます。

同期処理は決定的なソース識別情報を返しますが、デプロイの成功を記録することはありません。デプロイツールは、対応するファイルとルートが有効で検証済みになった後にのみ、その識別情報を保存します。通常のWP-CLIブートストラップでは、すべてのページを検出・同期せずに、キャッシュ済みのコレクション投稿タイプとリライトを登録します。

### ブロックアイランド

Blockstudioのブロックの多くはサーバー側で描画されます。WordPressには適した方式ですが、よくあるキャッシュ上の問題が生じます。パーソナライズされたブロックが1つあるだけで、ページ全体をキャッシュしにくくなることがあります。

ブロックアイランドは、この境界をブロック単位で切り分けます。

```json title="block.json"
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}
```

動的アイランドは、最初のレスポンスではキャッシュに安全なプレースホルダーだけを描画します。その後、ブラウザーはページ上で準備ができたすべての動的アイランドをまとめて1回のリクエストで送信し、Blockstudioは訪問者の実際のリクエストコンテキストで各フラグメントを描画します。

これにより、フルページキャッシュにページシェルを保存しつつ、カート数、アカウント操作、権限で制限されたUIなど、ユーザーごとに異なる部分は最新の状態に保てます。

```php title="placeholder.php"
<div class="cart-count-placeholder">Loading cart...</div>
```

```php title="index.php"
<div class="cart-count">
  <?php echo esc_html(acme_cart_count()); ?>
</div>
```

すでにキャッシュに安全なHTMLを描画し、フロントエンドのマウント通知だけが必要なブロックには、ハイドレーションアイランドを使います。

```json title="block.json"
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}
```

ハイドレーションアイランドはRESTリクエストを行いません。通常どおり描画され、フロントエンドで`blockstudio:island:hydrate`イベントを受け取ります。

動的アイランドは、プログラムによる描画経路でも使用できます。

```php
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);
```

ブロックタグでも使用できます。

```html
<bs:acme-cart-count product-id="42" />
```

エンドポイントの機能は意図的に限定されています。登録済みのBlockstudioブロックのうち、動的であり、動的アイランドとして明示的に指定されたものだけを描画します。属性はブロックスキーマとアイランドの許可リストに基づいてフィルタリングされ、各マーカーには、リクエストを処理するWordPressサイトが生成した署名が付与されます。

### Storhデータベースストレージ

Blockstudioのデータベースレイヤーはすでに、テーブル、SQLite、JSONC、投稿メタデータ、カスタム投稿タイプに対応しています。7.5では、安全性の高い並行書き込みとスキーマから生成されるインデックスを備えたファイルベースのストアを使いたい一方、ライブレコードをブロックのソースファイルの隣に保存したくないプロジェクト向けに、`storage: "storh"`が追加されました。

```php title="db.php"
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];
```

Storhのレコードはuploads内に保存されます。

```text
wp-content/uploads/blockstudio/db/my-theme-my-block/default/
```

公開されているAPIに変更はありません。`bs.db()`、REST、`Db::get()`は引き続き整数の`id`値を返します。内部では、BlockstudioがこれらのIDをStorhのUUIDv7ドキュメントIDに対応付けるため、既存のクライアントコードを変更する必要はありません。

宣言された各スキーマフィールドには等価フィルター用のインデックスが作成され、数値フィールドと日付形式のフィールドには範囲インデックスが作成されます。明示的な一意性のヒントも引き継がれます。JSONCのシードファイルから始めたプロジェクト向けに、新しいCLI移行ではソースファイルを残したまま、同等のStorhストアを書き込みます。

```bash
wp bs db migrate my-theme/app subscribers --to=storh
```

これにより、JSONCはシンプルでコミット可能なシード／設定形式として役割が明確になり、Storhは書き込み可能な本番データ向けの、より適したデフォルトのファイルバックエンドになります。

### パーサーとbsuiの改良

7.5では、ファイルベースのテンプレートやバンドルされたUIを活用するプロジェクトで役立つ、細かな機能も仕上げられました。

要素のマッピングで、一般的なリッチテキスト段落をカスタムビルダーなしで扱えるようになりました。`<p>`が登録済みの非コアBlockstudioブロックにマッピングされ、そのブロックにリッチテキスト属性`content`がある場合、単純な内部テキストがその属性にコピーされます。ネストされたタグやマッピングされた子要素は、引き続き内部ブロックとして解析されます。

`InnerBlocks`はテンプレート内のトークン化された`allowedBlocks`に対応しました。

```php title="index.php"
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />
```

対応するトークンは`namespace/*`、`category:<slug>`、`@theme`です。エディターにテンプレートが渡される前にサーバー側で展開されるため、フロントエンドの描画経路に変更はありません。

プログラムによる埋め込みも、より予測しやすくなりました。`bs_render_block()`と`bs_block()`は、別のブロックのエディタープレビュー内から呼び出された場合でも、埋め込みブロックをフロントエンドで解決済みのHTMLとして描画するようになりました。そのため、ネストされたブロックによって、生の`<RichText />`や`<InnerBlocks />`の疑似コンポーネントがプレビューのマークアップに漏れません。

バンドルされたUI向けに、`bsui/button`では`icon`属性と`iconPosition`が使えるようになりました。バンドルされた`bsui/*`のインラインスタイルは`@layer bsui`のカスケードレイヤー内に出力されます。また、既存の`blockstudio/blocks/attributes`フィルターに加えて`blockstudio/ui/button/variants-style`を使い、ボタンのバリエーションを拡張できます。

ブロックタグの組み合わせ機能も強化されました。プレフィックスは別のプレフィックスを経由して解決できます。そのため、`ui`の名前空間プレフィックス上に`theme`のプロジェクトプレフィックスを持つ`<theme-ui-input />`は、`bsui/input`に解決されます。登録済みのプレフィックスとエイリアスのタグは、ページコンテンツだけでなくブロックテンプレートの出力にも描画されるため、テンプレート内で`bs_render_block()`を呼び出さずに直接出力できます。

`blockstudio/block_tags/builders`を通じて登録されたカスタムブロックビルダーも、タグとマッピングされた要素の解析で一貫して使用されます。その後も明示的なレンダラーフィルターが実行され、ビルダーを上書きできます。

### ウォームリクエストとエクスポートの高速化

ランタイムとエディターのキャッシュは、uploadsではなく`wp-content/blockstudio/cache`に保存されるようになりました。場所は`cache.path`または`blockstudio/cache/dir`で変更できます。これにより、uploads内のPHPペイロードをブロックするホストでも、永続キャッシュを利用できます。ランタイム、エディターアセット、Tailwindの各キャッシュは古いエントリーも自動的に削除するため、長期間稼働するプロジェクトでキャッシュファイルが際限なく蓄積しません。

フロントエンドのウォームリクエストでは、検出ソースを構築する前に有効なランタイムレジストリをハイドレートするようになりました。これにより、ソースの再帰的な検出、ブロックの構築、フィールドの解析、キャッシュキー生成のためのツリー走査の繰り返しが省かれます。本番環境とステージング環境では、検証済みの監視スナップショットをデフォルトで20秒間信頼します。一方、ローカル環境と開発環境では引き続きリクエストごとに確認します。

コールドキャッシュの作成はシングルフライト方式です。1つのリクエストがペイロードを構築してアトミックに公開し、並行するリクエストはその完了結果を待ちます。Tailwindはデフォルトで、コンパイル済みの最大1,000エントリーを30日間保持し、ウォーム状態のコンパイラー構築状態を再利用します。これにより、サイト規模のルートセットでも小さなキャッシュの入れ替わりが続きません。

長時間稼働するエクスポーターは、ドキュメント間で`Blockstudio\Batch_Render::reset()`を呼び出せます。これにより、検出を再構築せずに、リクエスト単位のカウンター、アセット、アイランド、レイアウト、Tailwindの生成状態をクリアできます。`blockstudio/render/dependencies`フィルターでは、依存関係グラフ用に各ブロックの描画で使用したテンプレートとアセットのパスを取得できます。

## 信頼性と互換性

今回のリリースでは、次の修正も行われました。

- `blockstudio/blocks/attributes`で変更されたフィールド定義が、エディタースキーマだけでなく描画時のオプション検証にも反映されるようになりました。型付きの数値および真偽値のオプションも一貫して解決されます。
- エディターのブロックラッパーでは、フロントエンドの描画と同じ生成クラスが使われます。また、新しい`blockstudio/editor/canvas/body_class`フィルターを使って、設定済みのフロントエンドのbodyクラスをCanvasにコピーできます。
- Content Syncでは、破壊的な書き込みの前にソースプラン全体を検証し、削除処理を設定済みのコンテンツセット内に限定します。また、ファイル書き込みの失敗を報告し、そのエンティティの同期状態を更新しません。
- シンボリックリンクされた有効なテーマまたは親テーマに含まれるComposerパッケージでも、公開テーマのURLからエディターアセットを解決できるようになりました。
- キー付きのファイルページでは、エディターが管理するBlockstudioフィールド値が保持されます。同期時に古いネスト形式のキー構造を移行し、数値の0も有効なキーとして扱います。
- 動的アイランドでは、リクエスト属性フィルターの実行前に署名を検証します。署名のないリクエストコンテキストは無視され、同一オリジンのログイン済み訪問者の状態が復元されます。また、匿名ユーザー間でユーザー別キャッシュが衝突する問題を防ぎます。
- 生のMarkdownページエンドポイントで、投稿の公開範囲とパスワード保護が適用されるようになりました。
- エディターコントロールで、空の条件、チェックボックスの一括切り替え値、非同期のオプション更新、動的な描画順序、リピーターのRichTextまたはWYSIWYG状態を、より確実に処理できるようになりました。

## カスタムフィールド型

前述のカスタムフィールド型について、さらに説明します。

### カスタムフィールド型が必要な理由

Blockstudioは標準機能だけでも便利に使えるべきですが、実際のプロジェクトでは、余白トークンの選択、デザインシステムのカラー役割、レスポンシブな寸法、アイコンソース、商品セレクター、構造化値に対応付ける編集コントロールなど、ドメイン固有のコントロールが必要になることがよくあります。

7.5より前は、そうしたプロジェクトでは複数の組み込みフィールドを組み合わせるか、エディターをフォークする必要がありました。7.5では、その中間となる正式な仕組みが導入されました。フィールドのライフサイクルはBlockstudioが管理し、コントロールはプロジェクト側で管理できます。

```php title="functions.php"
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});
```

```js title="fields/dimensions.js"
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});
```

これで、そのフィールドをネイティブフィールドと同じように`block.json`で使えます。

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "bottom"],
        "default": {
          "top": "md",
          "bottom": "md"
        }
      }
    ]
  }
}
```

### 通常のテンプレート値

保存された値は、ほかのBlockstudio属性と同様に、PHP、Twig、Bladeで利用できます。

```php title="index.php"
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>
```

同じオブジェクトパスは、拡張テンプレートでも使用できます。

```json title="extend.json"
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}
```

## 互換性に関する注意

既存の組み込みフィールド型に変更はありません。既存の`custom/{name}`再利用可能フィールドグループにも変更はありません。カスタムフィールド型の名前は小文字で、名前空間付きにする必要があります（例: `acme/dimensions`）。`custom/`と`blockstudio/`の名前空間は予約済みです。

PHPがフィールド型を登録しても、エディタースクリプトが対応するコントロールを登録していない場合、Blockstudioは保存済みの値を保持し、エディターに編集不可の通知を表示します。フィールド型がPHPに登録されていない場合、Blockstudioは生成されたWordPress属性にそのフィールド型を含めません。

## 7.5.1 メンテナンスアップデート

7.5.1では、複数選択の値を描画用に準備する際に発生していた、配列から文字列への変換に関する警告が解消されました。保存値と描画値はもともと正しかったものの、フィールドを描画するたびにデバッグログへ警告が出ることがありました。

付属の`blockstudio/phpstan`v0.1.7アップデートでは、PHP、Twig、Blade、および推定されたテンプレート属性の形式において、名前のないグループ内にネストされたフィールドも認識するようになりました。既存プロジェクトでは、`composer update blockstudio/phpstan`を使ってこのパッケージの修正を適用できます。
