DevTools

1 行の overlay、独立パネル、容量上限付きの構造化 Console で、レイアウト・ヒットテスト・描画・パフォーマンスの問題を素早く特定します。

ウィンドウ内インスペクター

開発中は overlay をルートにアタッチします。ホバーするとノードの rect を破線の枠で示し、サイズとコンポーネント名を表示します。overlay 自体は pass-through で、クリックやスクロールを横取りせず、ホバー時も描画レベルの更新だけを行い、再レイアウトは発生しません。

fn mountUi(cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node {
    const root = try mountProductUi(cx, scope);

    // Development only: hover highlight with size + component name.
    _ = try ui.devtools.overlay.attach(cx, scope, root, .{});
    return root;
}

overlay の状態は渡した scope に保持され、その Scope が破棄されると overlay も一緒に取り除かれます。製品ウィンドウで「この領域を占めているのは誰か」をすぐ確認するのに向いており、完全な診断には独立パネルを使います。どちらも実際の Node / Cx の状態を読み取るため、デバッグ用のミラーモデルを別途維持する必要はありません。

症状別の診断

DevTools パネル

Elements、Components、Console、Performance の完全なビューが必要なときは ui.devtools.mountPanel(cx, target, opts) を使います。パネルは自前の Cx を持ち、別の target Cx を観察します。MultiWindowApp で独立ウィンドウに置けば、製品 UI を隠しません。パネル使用中は target が生存している必要があります。

const std = @import("std");
const ui = @import("ui");
const zenit_app = @import("zenit_app");

// mountProductUi: your app's ordinary mount function (see above).
var g_target_cx: ?*ui.Cx = null;

fn mountDevTools(cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node {
    _ = scope;
    const target = g_target_cx orelse return error.TargetNotReady;
    return ui.devtools.mountPanel(cx, target, .{ .title = "My App DevTools" });
}

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    var application = zenit_app.MultiWindowApp.init(gpa.allocator(), .{});
    defer application.deinit();

    const product = try application.createWindowWith(.{
        .window = .{ .width = 900, .height = 640, .title = "My App" },
    }, mountProductUi);
    g_target_cx = product.cx;

    const tools = try application.createWindowWith(.{
        .window = .{ .width = 760, .height = 560, .title = "DevTools" },
    }, mountDevTools);
    _ = ui.devtools.setViewMode(tools.cx, "performance"); // optional start tab

    try application.run();
}

これがリポジトリの zig build devtools-probe の構成です。ui.devtools には setViewMode、setTreeFilter、setConsoleFilter などの関数もあり、プローブや E2E からパネルをプログラムで操作できます。

4 つのビューと 6 つの詳細タブ

Elements / Components の行を選択すると、Layout、Style、State、Events、Render、Trace を切り替えられます。Style の一部の値はライブ編集でき、Render / Trace では dirty になった理由と最近のイベントを確認できます。ツリー検索は tag、#id、コンポーネント名に対応します。ui.devtools.source_link を設定すると、コンポーネント行からエディタの定義箇所へ直接ジャンプできます。

Console ログ

各 ui.Cx はスレッドセーフで容量上限付きの Console を持ちます。1 回の呼び出しでターミナルに出力しつつ、DevTools や E2E harness 向けに構造化イベントとして保持でき、パネルを開く前に捕捉された履歴も表示されます。

const log = cx.console();

log.info("application ready", .{});
log.scoped("network").warn("retry {d}", .{attempt});

// Plain level methods don't record a call site; writeAt does.
log.writeAt(.err, @src(), "save failed: {s}", .{@errorName(err)});

レベルは debug、log、info、warn、err です。さらにブラウザの Console に対応する group / groupEnd、count、time / timeEnd、assert、trace、inspect、table もあります。

通常のレベルメソッドは呼び出し位置を記録しません。ログをクリックしてエディタへジャンプしたい場合は writeAt(level, @src(), …) を使い、ui.devtools.source_link.configure でソースルートとエディタコマンド（既定は code --goto）を設定します。

キャプチャの設定

const app = try zenit_app.App.init(allocator, .{
    .console = .{
        .terminal_level = .info, // null disables the terminal sink
        .capture_level = .debug, // null disables in-memory capture
        .max_entries = 10_000,
        .max_bytes = 8 * 1024 * 1024,
        .max_entry_bytes = 64 * 1024,
    },
});

console を渡さない場合、zenit_app はビルドモードに応じて既定値を選びます。

Console が対応するのはブラウザ Console のログ収集・閲覧機能であり、Zig / JavaScript の REPL ではありません。Group は現在インデントのみで、インタラクティブな折りたたみはできません。table は現在テキストとして出力されます。完全な API、スレッドとライフタイムの制約、harness の例はリポジトリの docs/CONSOLE.md を参照してください。

Performance：アイドルとフリーズの区別

Performance ビューは「直近 N 個の描画フレーム」を切り取って固まるわけではありません。100 ms の実時間バケットで target を継続的に観測します。バケットは 64 個、約 6.4 秒のローリングウィンドウで、FPS は直近 10 バケット（約 1 秒）の平均です。target が 0.7 秒以上新しいフレームを出さないと、読み値は FPS: 0 — idle (not rendering) と明示されます。これはフレームワークが省電力のため意図的に描画を止めている状態で、0 FPS のフリーズではありません。

テストの入口

zig build test-headless
zig build test-ui
zig build test-render
zig build hello-button

リリース前チェック

• ✓

  デバッグ UI をオフにする。inspector overlay を取り除くか、debug 用の設定で開発ビルドのときだけマウントします。

• ✓

  実ウィンドウで入力を検証する。キーボード、IME、クリップボード、VoiceOver。

• ✓

  ビルドゲートを実行する。headless、UI、render 関連のテスト step。

• ✓

  Console の方針を確認する。Release のターミナルレベルとキャプチャ設定が意図どおりで、ログに機密データが含まれていないこと。

• ✓

  バージョンを固定する。zenit の revision をロックし、対象の Zig バージョンを記録します。