0.2.1

0.2.1のリリースノート。

リリース日: 2026-06-11

メンテナンスリリースです。プロジェクト全体のレビュー 2 巡分、エージェント発見の堅牢化修正バッチ、zfb 0.1.0-next.38 エンジンバンプ、開発体験の修正をまとめています。@takazudo/zudo-doc、@takazudo/zudo-doc-history-server、create-zudo-doc はロックステップで同時リリースされます。

0.2.0 利用者の移行

create-zudo-doc で生成した下流サイトを保守している場合、0.2.0 から 0.2.1 への移行は単なるバージョンバンプ以上のものになります。テンプレートの配線が相互に絡み合う形で進化しており、本リリースに同梱される zfb 0.1.0-next.38 エンジンバンプが、以前から存在していたアイランドのハイドレーションの欠落を表面化させます。このセクションでは、実際の 3 件の利用者アップグレードで遭遇した内容をまとめ、移行を 1 回でやり切れるようにします。

新しいアイランド警告は、すでに死んでいたアイランドを暴き出す

zfb 0.1.0-next.38 はアイランドマーカーのレジストリ警告を追加します (zfb #984 / #990)。0.2.0 時代の配線では、出力されているのに未登録のマーカーごとに最大 7 件の警告が突然現れます: ThemeToggle、Toc、MobileToc、Sidebar、DocHistory、ImageEnlarge、AiChatModal。これらのアイランドはサーバーレンダリングは正しく行われますが、ハイドレートされません。アイランドレジストリの登録数が、ページが出力するマーカーに足りていないためです。ビルドはそれでも 0 で終了します。

0.2.1 のテンプレート変更は 1 波としてまとめて取り込む

pnpm check:template-drift を実行します。0.2.0 ベースラインでは、相互に絡み合う一式全体 — 最後にどのテンプレート世代を同期したかにより、おおよそ 17〜31 ファイル — がフラグされます。内訳:

• #2010 — doc ルートの統合（新しい _doc-page-renderer / _doc-route-entries モジュール）

• #2030 — nav-data の重複排除（新しい _nav-data-prep モジュール）

• #2012 — bare な theme-toggle サブパスエクスポート

• #2016 — docs-schema の抽出（単一の zod ソース）

• #2022, #2024, #2037 — バージョン付きページのメタデータ、search-index / llms-txt の重複排除、zdtp 状態の保持

これらの変更は互いを参照し合うため、部分的な取り込みは死んだ接続コードを残します。まとめて同期してください。

ひとつの実地データ点 (zudolab/zudo-css-wisdom#103): フル取り込みでは 31 ファイルと 4 つの新規モジュールが 1 波でクリーンに同期できました。唯一のビルド破損は、src/config/i18n.ts に新たに期待される getLocaleConfig エクスポートでした — このファイルをカスタマイズしている場合は、そのエクスポートを追加してください。

next.38 ではスキャナーから見える ThemeToggle シムを残す

0.2.1 テンプレートを取り込むと、next.38 では ThemeToggle が新たに死にます。0.2.1 の _header-with-defaults.tsx は、ローカルの src/components/theme-toggle.tsx コピーから import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle"（npm dist）へ切り替えます。next.38 のアイランドスキャナーは node_modules パッケージ内のアイランドを登録しないため (zfb #999)、テンプレートを同期した利用者は「6 個が死、ThemeToggle は動作」から「7 個が死」へ移ります。

下記のフォワード修正を含む zfb リリースに上がるまでの回避策: ローカルにスキャナーから見えるパススルーのシムを残し、ヘッダーのインポートをそれに向けます。displayName を固定したローカルのラッパーコンポーネントにしてください — export { ThemeToggle } from … という単なる再エクスポートでは、next.38 スキャナーに登録対象のローカルバインディングを与えられず、トグルは死んだままになります。

// src/components/theme-toggle.tsx
"use client";
import type { ComponentProps } from "preact";
import { ThemeToggle as PackageThemeToggle } from "@takazudo/zudo-doc/theme-toggle";

// Local wrapper (not a bare re-export) so the next.38 island scanner sees a
// component binding it can register; displayName names the island marker.
export function ThemeToggle(props: ComponentProps<typeof PackageThemeToggle>) {
  return <PackageThemeToggle {...props} />;
}
ThemeToggle.displayName = "ThemeToggle";

残った 3 つのレイアウトアイランドのシムを同期する (#2061)

リリース済みの next.38 では、zudo-doc ≤ 0.2.2 の利用者は依然として 3 つの死んだレイアウトアイランドを見ます: docs ページの Toc と MobileToc、そして hide_sidebar ページの空データ Sidebar です。これらは少なくとも 0.2.0 以降、静かに死んでいました。

PR #2061 は、スキャナーから見える Toc / MobileToc シムと、hide_sidebar ページでの空フラグメント sidebarOverride により、テンプレート利用者向けにこれを修正します。該当ファイルを手動で同期するか、デフォルトでそれらを同梱する次の create-zudo-doc リリースを待ってください。

不要になったローカルモジュールを削除する

0.2.1 は、パッケージ側が所有するようになったいくつかのモジュールのローカルコピーの同梱をやめました。テンプレートを同期すると、古いフルのローカル実装は参照されなくなります — 削除してください: rehype プラグイン、hast-utils、url-utils、docs-source-map、use-active-heading、sidebar-resizer、doc-history util です。（差し替えられた theme-toggle / Toc のコピーを含め、zudo-css-wisdom のアップグレードでは 13 ファイルを削除しました。）

フォワード修正: zfb 0.1.0-next.39

上記のスキャナー可視シムはすべて、next.38 スキャナーのための暫定的な負債です。zfb 0.1.0-next.39（2026-06-12 リリース、0.2.1 と 0.2.2 がともに next.38 に対して出荷された後）は、npm dist パッケージ向けの "use client" アイランドスキャンを追加します (zfb #999 / PR #1001): node_modules 内の通常のパッケージにあるアイランドが、そのパッケージの exports マップを通じて解決され、登録・ハイドレートされます。

テンプレートページを使わずに（スキャフォルドなしで）パッケージから直接 DocLayoutWithDefaults をレンダリングしている利用者は、テンプレートシムでは一切癒されません — その経路には zfb next.39 以降が必要です。

機能

• AI チャットエンドポイントのオプショナルな HMAC IP ハッシュ化。 Cloudflare シークレット IP_HASH_SECRET を設定すると、レートリミットと監査ログのキーがソルトなし SHA-256 ではなく HMAC-SHA-256(ip) から導出され、IPv4 全列挙によるハッシュ逆引きを防ぎます。シークレット未設定時の挙動は従来どおりで、オプショナルかつ非破壊的です (#2038)。

• HTML Preview の sandbox prop が設定可能に。 プレビュー iframe の sandbox 属性をハードコードではなく呼び出し側ごとに設定できるようになりました (#2035)。

• テーマトグル: bare サブパスとインスタンス間同期。 @takazudo/zudo-doc がテーマトグルを bare サブパスエクスポートとして提供し、インスタンス間の状態同期と shiki peer dependency を備えました (#2012)。

• pages/ と plugins/ の型チェックカバレッジ。 ホストのファイルルーティング pages/ と 6 つの zfb エンジンプラグイン全部が型チェック対象になり（check:pages、check:plugins は @ts-check JSDoc + checkJs）、b4push と CI の両方に組み込まれました (#2018)。

バグ修正

• zfb エンジンを 0.1.0-next.38 にバンプし、警告ゼロのビルドに。 ホストとジェネレーターのピンを 0.1.0-next.35 から更新。壊れていた階層アンカー 2 件を修正し、e2e フィクスチャツリーをホストバンドラーの走査から除外し（next.38 で実動化した imageDimensions がフィクスチャの画像参照をホストの public/ に対して stat してしまうため）、linkValidation / imageDimensions のドキュメントを新挙動に合わせて書き直しました — no-op だった allowExternal オプションは上流で削除され、imageDimensions は実際に width/height を注入するようになりました (#2045)。

• デザイントークンパネルの状態がカラースキーム切り替え後も保持されるように。 テーマトグルが zdtp の調整状態を消さなくなり、スキームごとの shikiTheme が toZdtpColorSchemes 変換を通過しても保持されます (#2037)。

• AI チャット履歴の信頼ポリシーを堅牢化・文書化。 user/assistant ロールの厳格なホワイトリスト、エントリ数とエントリ長の上限、紛れ込んだフィールドの除去、偽装 assistant ターンの残余リスクに関する判断記録を追加しました (#2036)。

• バージョン付きページのメタデータの正確性。 /v/ ページで古いメタ情報・タグチップを非表示にし、EN フォールバックのメタ情報パリティを回復し、タグ URL セグメントをすべての出力箇所でパーセントエンコードし、ソース表示リンクが .mdx 決め打ちではなく記録されたソース拡張子を使うようにしました (#2022)。

• サイドバーとナビゲーションの修正。 ルートの docs インデックスノードが sidebar-tree への委譲を通過しても保持され (#2030)、セクションに属さないページはフルナビツリーにフォールバックし、トグルでサイドバーを隠したときにコンテンツが正しく中央寄せされます (#2002)。

• ジェネレーターの入力検証。 create-zudo-doc が文字列でないプリセット projectName を文法チェックの前に拒否するようになり、使われていないテンプレートプラグインを削除し、プロジェクト名検証を一元化しました (#2013)。

• doc-history-server の堅牢化。 不正なパーセントエンコードのスラッグはサーバーをクラッシュさせず HTTP 400 を返し、getDocHistory は async エイリアスとしてエクスポートされ続け、サーバーはデフォルトで localhost にバインドします (#2011)。

• テーマトグルアイランドのハイドレーション。 コンパイル済みアイランドが named export を使うことで実際にハイドレートされるようになりました (#2012)。

• 開発サーバー: ポート固定とウォッチャーループの修正。 pnpm dev がポート 4321 を固定し（EADDRINUSE で即時失敗）、.claude/ ウォッチャーがシンボリックリンクのフィードバックループを起こさなくなりました (#2044)。

• プロジェクト全体レビュー 2 巡。 多数の小さな正確性修正: 空スラッグの falsy 判定箇所、フック順序の問題、ヘッダートグルモード、テンプレート i18n、8 件の小修正バッチ、Locale リテラルユニオンの型衛生、ai-chat ルートハンドラーのフィクスチャテストなど (#2008, #2020, #2025, #2034)。

パフォーマンス

• クライアントハイドレーションと検索。 SidebarToggle のハイドレーションを when=visible でゲートし、サイドバーのノードコンポーネントをメモ化し、検索インデックスのフィールドをロード時に一度だけ小文字化するようにしました。

• ビルド時メモ化。 タグマップ、フッターのタグリスト、md-plugins のソースマップをメモ化し、check:links の dist 走査を 1 パスに統合しました。

セキュリティ

• shell-quote のアドバイザリを解決。 推移的依存の shell-quote を >=1.8.4 にオーバーライドしました (GHSA-w7jw-789q-3m8p)。

• .npmrc の trust policy を強化 — any から no-downgrade へ。理由はインラインで文書化されています (#2039)。

その他の変更

• ホスト全体の統合・整理。 ナビツリービルダーを sidebar-tree パッケージへ重複排除して有界 LRU キャッシュ化 (#2030)、サイドバーリサイザーを単一の正準実装へ統合 (#2029)、4 つの doc キャッチオールルートを 1 モジュールに共通化 (#2010)、useModalDialog フックで 4 系統のダイアログ配線を置換、ai-chat エンドポイントを責務別モジュールに分割、search-index/llms-txt ユーティリティを重複排除して frontmatter の slug オーバーライドを尊重 (#2024)、docs frontmatter の zod スキーマを単一ソース化 (#2016)、未使用のルート依存 7 件を削除しました。

• CI: wrangler を 4.98.0 にピン。 本番デプロイにおける Cloudflare /subdomain API の失敗（エラー 10013）は Cloudflare サポートで対応中です (#2007)。失敗は Cloudflare 側であり、アップロードは成功しコンテンツはデプロイされています。

• ドキュメント。 古くなっていた公開前開発ワークフローの README セクションを差し替え (#2005)、利用側の Tailwind safelist インポートを文書化しました。