ホストクロームバインディング

パッケージ所有ルートのドキュメントヘッダーやホームヒーローにホスト側のコンテンツを注入する。単一のchromeBindingsモジュール経由で届けられます。

プロジェクトで packageOwnedRoutes: true を設定すると、@takazudo/zudo-doc がドキュメントルートを自前で注入し、プロジェクト側はほぼ空の pages/ ディレクトリだけを持つことになります。これは便利な反面、通常であればプロジェクト固有のレンダリングを差し込むホストファイルが失われます。ホストクロームバインディングはそれを取り戻すための継ぎ目です。型付けされた小さなスロット群（ChromeHostBindings）を通じて、コンポーネントをエジェクトすることなく、パッケージ所有のクロームにホスト独自のコンテンツやコーラブルを注入できます。

このページでは、2つのコンテンツ注入用の継ぎ目 — docContentHeaderExtras と homeExtras — に加え、それらのバインディングを注入ルートへ届ける配信チャネルである settings.chromeBindingsModule を扱います。

ChromeHostBindings 型

ここで説明する継ぎ目はすべて ChromeHostBindings インターフェースのフィールドで、@takazudo/zudo-doc/factory-context からエクスポートされています。

import type { ChromeHostBindings } from "@takazudo/zudo-doc/factory-context";

すべてのフィールドは任意です。省略したスロットは、継ぎ目導入前の挙動をバイト単位で再現するパッケージデフォルトにフォールバックするため、部分的なバインディングオブジェクトでも常に安全です。

ChromeHostBindings は、クローム自身の呼び出し地点が内部で必要とする広い構造的な形状で各スロットを型付けします。実際の狭い型を持つコンポーネントやコーラブルをそのまま直接代入する — あるいは代入をコンパイル可能にするために as／as unknown as キャストに頼る — と、本当に重要なチェック、すなわち「渡した値がクロームから渡されるプロパティを実際に受け取れるかどうか」が消えてしまいます。代わりに @takazudo/zudo-doc/chrome-bindings からエクスポートされる defineChromeBindings でバインディングを組み立ててください。その入力型 ChromeBindingsInput は、各スロットの実際の呼び出し地点が渡す正確なプロパティや引数を宣言しているため、クロームが決して渡さないプロパティをコンポーネントが要求している場合はコンパイルエラーになります（#2674 のドリフト検出チェック）。広い ChromeHostBindings 形状は、あなたが気にする必要のない内部の単一のワイドニングステップによって生成されます。

配信チャネル: chromeBindingsModule

packageOwnedRoutes: true ではクロームがパッケージ内部で組み立てられるため、バインディングを渡すためのホスト側の呼び出し地点が存在しません。プラグインがルートへ渡すルートコンテキストはシリアライズ可能なデータのみ（settings、translations、タグ語彙）を運ぶため、関数やコンポーネントを運ぶことはできません。このチャネルはその制約を回避します。コーラブルそのものをシリアライズするのではなく、それらをエクスポートするモジュールへのパスをシリアライズするのです。

zudoDoc() 設定の chromeBindingsModule に、defineChromeBindings で組み立てた名前付き chromeBindings エクスポートを持つモジュールを指すプロジェクトルート相対パスを設定します。

export default defineConfig(
  zudoDoc({
    // packageOwnedRoutes はデフォルトで true
    chromeBindingsModule: "./src/chrome-bindings.tsx",
  }),
);

import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";

export const chromeBindings = defineChromeBindings({
  // ...ここに各継ぎ目を記述（後述）
});

ビルド時にルートプラグインが chromeBindings を再エクスポートする仮想モジュールを登録し、注入されたクロームシムがそれをクロームファクトリへスプレッドします。文字列パスはシリアライズ可能なので、「ルートコンテキストはデータのみ」というルールは依然として保たれます — 異なるのはローダーのソースだけです。

既存スロットの「取り残し」も解消する

docContentHeaderExtras と homeExtras は新しい継ぎ目ですが、ChromeHostBindings にはこのチャネルが存在する以前から、注入ルートへ届く手段がなかったスロットがいくつかありました — それらはスタブのデフォルトのまま黙って据え置かれていました。chromeBindingsModule はそれらをまとめて解消します。

つまり、docContentHeaderExtras のために作成するモジュールは、たとえば以前はホスト所有ルートでしか機能しなかったカスタムフロントマターレンダラーを登録する場所でもあります。

docContentHeaderExtras — コンテンツヘッダーへの注入

docContentHeaderExtras は、ドキュメントのコンテンツヘッダー内、ページの <h1> とメタ情報ブロックの間に追加コンテンツを描画します。これはページエントリを受け取ってレンダリング可能な出力を返すレンダラーであり、プロパティから再導出するのではなく、現在のページのフロントマターを自然にキーとして扱えます。

docContentHeaderExtras?: (args: {
  entry: DocPageEntry;
  slug: string;
  locale: string;
  isFallback?: boolean;
  version?: string;
}) => unknown;

よくある用途は、カスタムフロントマターフィールドから導出するティアバッジです。フロントマターで tier: core または tier: opt-in を宣言するページに対して次のように書けます。

import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";

export const chromeBindings = defineChromeBindings({
  docContentHeaderExtras: ({ entry }) => {
    const tier = entry.data.tier;
    if (tier !== "core" && tier !== "opt-in") return null;
    const label = tier === "core" ? "Core" : "Opt-in";
    const tone = tier === "core" ? "bg-accent text-bg" : "bg-surface text-fg";
    return (
      <span
        class={`inline-block px-hsp-sm py-vsp-2xs text-caption rounded-full ${tone}`}
      >
        {label}
      </span>
    );
  },
});

デフォルト: 未設定 → 何も描画されず、ヘッダー出力は継ぎ目導入前のヘッダーとバイト単位で同一になります。

homeExtras と HomePageView — ホームヒーローへの注入

homeExtras は、ホームヒーロー内、overview/GitHub のリンク行の後、ヒーローのテキストカラム内に追加コンテンツを描画します — 例えばサイト説明の下にブランドやソーシャルのリンクを置く用途です。

homeExtras?: (args: { locale: string }) => unknown;

export const chromeBindings = defineChromeBindings({
  homeExtras: ({ locale }) => (
    <p class="mt-vsp-sm text-small">
      <a
        href="https://example.com/blog"
        class="text-fg underline hover:text-accent"
      >
        Read the blog
      </a>
    </p>
  ),
});

優先順位: extras プロパティが勝つ

共有のホーム本体は HomePageView が組み立て、パッケージルートとホストページのどちらもこれを呼び出します。HomePageView は extras プロパティ — ホストページが直接渡す描画済みの値 — を受け取ります。両方が存在する場合はプロパティが勝ちます。

// HomePageView 内で次のように解決される:
extras ?? hostBindings.homeExtras?.({ locale })

この非対称性は意図的なものです。ホストページは手元に JSX（値）を持っている一方、注入/バインディング経路はレンダリング時に locale 文字列しか持たず、そこから自前でコンテンツを導出しなければなりません（レンダラー）。

/ ルートのトポロジー

/ にあるデフォルトホームは、ルートプラグインによって決して注入されません — zfb が / パターンを拒否するためです（アップストリーム Takazudo/zudo-front-builder#1227）。これにより、知っておくべき分岐が生じます。

• / ホームは常にホストの薄い pages/index.tsx アダプター経由で描画されるため、extras は HomePageView の extras プロパティ（またはホスト自身の createChrome 呼び出し）経由で届きます。

• 注入された /[locale] ホームは chromeBindingsModule を通じて hostBindings.homeExtras を読み取ります。

i18n サイトでは、バインディングモジュールで homeExtras を設定し、かつ pages/index.tsx の extras プロパティに同じコンテンツを渡すことが、デフォルトホームとロケールホームを一貫させる方法です。

Design Token Panel チャネル（designTokenPanelConfigModule）

Design Token Panel には独自のホストモジュールチャネルがあり、chromeBindingsModule とまったく同じ仕組みで動作します — 同じメカニクス、同じ「ファイルが無ければ大きな声で失敗する」挙動 — ただしクロームバインディングの代わりにパネルの設定ビルダーを運びます。

パネルは動作にホスト設定ファイルを必要としません。designTokenPanel: true にすると、注入された DesignTokenPanelBootstrap アイランドは、出荷済みのトークンマニフェストとバンドルされた Default Light / Default Dark スキームから導出されたパッケージデフォルトのビルダー（@takazudo/zudo-doc/design-token-panel-config）を使います。これがゼロコンフィグの経路です。

パネルを完全にカスタマイズするには、designTokenPanelConfigModule に、名前付きの buildDesignTokenPanelConfig(mode) をエクスポートするホストモジュールを指すプロジェクトルート相対パスを設定します:

import type { PanelConfig } from "@takazudo/zdtp";

type PanelMode = "light" | "dark";

export function buildDesignTokenPanelConfig(mode: PanelMode): PanelConfig {
  // モードスコープのパネル設定（spacing/font/size/color ティア）を返す
  // ...
}

ルートプラグインは3番目の仮想モジュール（virtual:zudo-doc-design-token-panel-config）を登録し、あなたのビルダーを re-export します。chromeBindingsModule と同様、設定を通じて移動するのはパスだけで、ビルダー自体はモジュールグラフ経由でインポートされます。

chromeBindingsModule との違いで知っておくべき点が2つあります:

• デフォルトは空オブジェクトではなくパッケージビルダーです。 設定が無い場合、ローダーはパッケージデフォルト（完全に動作するパネル）を re-export します — フォールバックすべき意味のある「空の」ビルダーは存在しません。

• スキャナー到達可能性がこのコントラクトの一部です。 実際の DesignTokenPanelBootstrap アイランドは（設定仮想モジュールを経由せず）パッケージのクロームによって静的にインポートされるため、常に zfb のアイランドスキャナーから到達可能です。チャネルを通じて移動するのはパネル設定のデータ（モードスコープのビルダー）だけであり、これがクロームバインディングのアイランドがハイドレートしない注入ルート上でも、カスタマイズされたパネルがハイドレートする理由です。

同じガード規則が適用されます: 明示的な空文字列、存在しないファイル、ディレクトリパスは、プラグインのセットアップ時に解決済みパスを明示して大きな声で失敗します。storagePrefix: "zudo-doc-tweak" はパッケージデフォルトで維持されるため、既存のユーザー保存は引き継がれます。

関連ページ

• zudo-docのカスタマイズ — 最小→拡張のはしご。chromeBindingsModule はその5段目

• フロントマタープレビュー — このチャネルが取り残しを解消する frontmatterRenderers スロット

• 設定 — zudoDoc() の完全なフィールドリファレンス

• Design Token Panel — このチャネルが設定するパネル UI