@next2d/builder 0.1.6 → 0.1.8

package/templates/xbox/src/bindings/webgpu/WebGPUCommon.h

@@ -15,6 +15,7 @@
 #include <v8.h>
 
 #include "v8/V8Util.h"
+#include "v8/WeakHandle.h"
 
 #include <memory>
 #include <string>
@@ -27,13 +28,8 @@ struct Holder {
     T handle;
 };
 
-template <typename T>
-void ReleaseHolder(const v8::WeakCallbackInfo<Holder<T>>& info)
-{
-    delete info.GetParameter();
-}
-
 // wgpu ハンドル T を、指定 ObjectTemplate から生成したオブジェクトにラップする。
+// GC 時の解放は AttachWeak (第一パスで Global を Reset する規約に準拠) に委ねる。
 template <typename T>
 v8::Local<v8::Object> Wrap(v8::Isolate* isolate,
                            v8::Local<v8::ObjectTemplate> tmpl,
@@ -43,8 +39,7 @@ v8::Local<v8::Object> Wrap(v8::Isolate* isolate,
     v8::Local<v8::Object> obj = tmpl->NewInstance(ctx).ToLocalChecked();
     auto* holder = new Holder<T>{std::move(handle)};
     obj->SetInternalField(0, v8::External::New(isolate, holder));
-    auto* global = new v8::Global<v8::Object>(isolate, obj);
-    global->SetWeak(holder, ReleaseHolder<T>, v8::WeakCallbackType::kParameter);
+    v8util::AttachWeak(isolate, obj, holder);
     return obj;
 }
 

package/templates/xbox/src/gpu/DawnContext.cpp

@@ -1,7 +1,6 @@
 #include "DawnContext.h"
 
 #include <Windows.h>
-#include <dawn/native/DawnNative.h>
 #include <iostream>
 
 namespace next2d {
@@ -114,12 +113,13 @@ bool DawnContext::AcquireDevice()
         return false;
     }
 
-    // surface の優先フォーマットを取得
+    // surface の優先フォーマットと CopySrc 可否 (デバッグ読み戻し用) を取得
     wgpu::SurfaceCapabilities caps = {};
     surface_.GetCapabilities(adapter_, &caps);
     if (caps.formatCount > 0) {
         format_ = caps.formats[0];
     }
+    can_copy_src_ = (caps.usages & wgpu::TextureUsage::CopySrc) == wgpu::TextureUsage::CopySrc;
 
     Configure(width_, height_);
     return true;
@@ -138,26 +138,113 @@ void DawnContext::Configure(uint32_t width, uint32_t height)
     config.device      = device_;
     config.format      = format_;
     config.usage       = wgpu::TextureUsage::RenderAttachment;
+    if (can_copy_src_) {
+        // 黒画面デバッグ用の surface 読み戻し (DebugProbeSurface) を可能にする
+        config.usage |= wgpu::TextureUsage::CopySrc;
+    }
     config.width       = width_;
     config.height      = height_;
     config.presentMode = wgpu::PresentMode::Fifo;
     config.alphaMode   = wgpu::CompositeAlphaMode::Opaque;
 
     surface_.Configure(&config);
+    configured_ = true;
 }
 
 wgpu::Texture DawnContext::GetCurrentTexture()
 {
+    if (!configured_) {
+        return nullptr;
+    }
     wgpu::SurfaceTexture surface_texture = {};
     surface_.GetCurrentTexture(&surface_texture);
+    frame_texture_acquired_ = true;
+    current_texture_ = surface_texture.texture;
     return surface_texture.texture;
 }
 
+// 提示直前の surface 中央行を読み戻し、非黒ピクセル数をログする (黒画面調査用)。
+// CI では目視できないため、これが「画面に何が出ているか」の唯一の証拠になる。
+void DawnContext::DebugProbeSurface()
+{
+    if (!can_copy_src_ || !current_texture_ || width_ == 0) {
+        std::cerr << "[GPU] surface probe unavailable (CopySrc="
+                  << (can_copy_src_ ? "yes" : "no") << ")" << std::endl;
+        return;
+    }
+
+    const uint32_t row_bytes = width_ * 4;
+    wgpu::BufferDescriptor buf_desc = {};
+    buf_desc.size  = (row_bytes + 3) & ~3u;
+    buf_desc.usage = wgpu::BufferUsage::CopyDst | wgpu::BufferUsage::MapRead;
+    wgpu::Buffer buffer = device_.CreateBuffer(&buf_desc);
+
+    wgpu::TexelCopyTextureInfo src = {};
+    src.texture = current_texture_;
+    src.origin  = { 0, height_ / 2, 0 };
+
+    wgpu::TexelCopyBufferInfo dst = {};
+    dst.buffer = buffer;
+    dst.layout.offset = 0;
+    dst.layout.bytesPerRow = wgpu::kCopyStrideUndefined;   // 1 行コピーでは不要
+
+    wgpu::Extent3D extent = { width_, 1, 1 };
+
+    wgpu::CommandEncoder encoder = device_.CreateCommandEncoder();
+    encoder.CopyTextureToBuffer(&src, &dst, &extent);
+    wgpu::CommandBuffer commands = encoder.Finish();
+    device_.GetQueue().Submit(1, &commands);
+
+    bool done = false;
+    wgpu::Future future = buffer.MapAsync(wgpu::MapMode::Read, 0, buf_desc.size,
+        wgpu::CallbackMode::AllowProcessEvents,
+        [&done](wgpu::MapAsyncStatus, wgpu::StringView) { done = true; });
+    // GPU 完了待ちは TimedWaitAny で行う (ProcessEvents の空スピンでは
+    // GPU がフレーム描画中のとき完了前にループ上限へ達する)
+    instance_.WaitAny(future, 2'000'000'000);   // 2s
+    if (!done) {
+        std::cerr << "[GPU] surface probe: map timeout" << std::endl;
+        return;
+    }
+
+    const auto* px = static_cast<const uint8_t*>(buffer.GetConstMappedRange(0, buf_desc.size));
+    uint32_t non_black = 0;
+    for (uint32_t x = 0; px && x < width_; ++x) {
+        const uint8_t* p = px + static_cast<size_t>(x) * 4;
+        if (p[0] || p[1] || p[2]) {
+            ++non_black;
+        }
+    }
+    std::cerr << "[GPU] surface probe (present #" << present_count_
+              << "): non-black " << non_black << "/" << width_ << " px";
+    if (px && width_ > 1) {
+        const uint8_t* c = px + static_cast<size_t>(width_ / 2) * 4;
+        std::cerr << ", center=(" << +c[0] << "," << +c[1] << "," << +c[2] << "," << +c[3] << ")";
+    }
+    std::cerr << std::endl;
+    buffer.Unmap();
+}
+
 void DawnContext::Present()
 {
-    if (surface_) {
+    // 提示するのは「未構成でない」かつ「今フレーム GetCurrentTexture 済み」のときのみ。
+    // 取得なしで Present すると Dawn の検証エラーになる (描画しないフレームは提示しない)。
+    if (surface_ && configured_ && frame_texture_acquired_) {
+        ++present_count_;
+        if (present_count_ <= 3 || present_count_ == 60 || present_count_ % 300 == 0) {
+            DebugProbeSurface();
+        }
         surface_.Present();
+    } else {
+        ++present_skipped_;
+        if (present_skipped_ <= 3 || present_skipped_ % 300 == 0) {
+            std::cerr << "[GPU] present skipped #" << present_skipped_
+                      << " (configured=" << configured_
+                      << " acquired=" << frame_texture_acquired_ << ")" << std::endl;
+        }
     }
+    frame_texture_acquired_ = false;
+    current_texture_ = nullptr;
 }
 
 void DawnContext::Tick()

package/templates/xbox/src/gpu/DawnContext.h

@@ -36,6 +36,9 @@ public:
     // 提示する。
     void Present();
 
+    // 提示直前の surface 中央行を読み戻して非黒ピクセル数をログする (黒画面調査用)。
+    void DebugProbeSurface();
+
     // Dawn の非同期イベント(コールバック)を進める。毎フレーム呼ぶ。
     void Tick();
 
@@ -59,6 +62,21 @@ private:
     HWND     hwnd_   = nullptr;
     uint32_t width_  = 0;
     uint32_t height_ = 0;
+
+    // surface が Configure 済みか。未構成のまま Present すると Dawn の
+    // 検証エラーが毎フレーム出るため、Present/GetCurrentTexture をゲートする。
+    bool     configured_ = false;
+
+    // 今フレーム GetCurrentTexture が呼ばれたか。呼ばれていないフレームで
+    // Present すると Dawn の検証エラーになるため、Present をゲートする
+    // (アプリが描画しないフレームは提示しない)。
+    bool     frame_texture_acquired_ = false;
+
+    // デバッグ用: surface の CopySrc 可否 / 今フレームのテクスチャ / 提示統計
+    bool          can_copy_src_ = false;
+    wgpu::Texture current_texture_ = nullptr;
+    uint64_t      present_count_ = 0;
+    uint64_t      present_skipped_ = 0;
 };
 
 } // namespace next2d

package/templates/xbox/src/main.cpp

@@ -4,8 +4,11 @@
 // bootstrap.js とアプリ本体(ESM)の読み込み -> ゲームループ、という流れ。
 #include <Windows.h>
 #include <windowsx.h>
+#include <timeapi.h>
 #include <XGameRuntime.h>
 
+#pragma comment(lib, "winmm.lib")
+
 #include "HostContext.h"
 #include "AssetLoader.h"
 #include "EventLoop.h"
@@ -190,6 +193,18 @@ HWND CreateHostWindow(HINSTANCE instance, int width, int height)
     wc.lpszClassName = L"Next2DXboxHostWindow";
     RegisterClassExW(&wc);
 
+    // ウィンドウが画面(作業領域)より大きいと画面外にはみ出し、提示が
+    // 見切れる/非等倍でスケールされて歪む (CI の低解像度ディスプレイで
+    // 1920x1080 ウィンドウ → 描画が縦長になっていた)。作業領域に収まるよう
+    // クランプする。実機コンソールでは作業領域=全画面のため 1920x1080 のまま。
+    RECT wa = {};
+    if (SystemParametersInfoW(SPI_GETWORKAREA, 0, &wa, 0)) {
+        const int maxW = wa.right - wa.left;
+        const int maxH = wa.bottom - wa.top;
+        if (maxW > 0 && width  > maxW) { width  = maxW; }
+        if (maxH > 0 && height > maxH) { height = maxH; }
+    }
+
     // コンソールでは全画面相当。PC(GDK) 検証ではウィンドウ。
     const DWORD style = WS_OVERLAPPEDWINDOW | WS_VISIBLE;
     return CreateWindowExW(
@@ -202,14 +217,27 @@ HWND CreateHostWindow(HINSTANCE instance, int width, int height)
 
 int WINAPI wWinMain(HINSTANCE instance, HINSTANCE, PWSTR cmd_line, int)
 {
+    // Sleep() の分解能を 1ms に上げる (フレームペーシング用。既定 15.6ms では
+    // 60Hz を刻めない)
+    timeBeginPeriod(1);
+
     // --selftest: アプリの代わりに js/selftest.js を実行し、全バインディングを
     // 実機/PC(GDK) 上で検証して終了する (テスト完了で自動終了)。
     const bool selftest = cmd_line && wcsstr(cmd_line, L"--selftest") != nullptr;
 
-    // 1. GDK ランタイム初期化
-    if (FAILED(XGameRuntimeInitialize())) {
+    // 1. GDK ランタイム初期化。
+    // デスクトップでは Gaming Services 未導入の環境 (CI ランナー等) でも
+    // 起動できるよう、失敗を警告に留めて続行する (本ホストは XUser 等を未使用)。
+    // コンソールでは必須のため失敗したら終了する。
+    bool xgame_initialized = SUCCEEDED(XGameRuntimeInitialize());
+    if (!xgame_initialized) {
+#if NEXT2D_XBOX_CONSOLE
         std::cerr << "XGameRuntimeInitialize failed" << std::endl;
         return 1;
+#else
+        std::cerr << "warning: XGameRuntimeInitialize failed (Gaming Services not installed?)"
+                  << " - continuing on desktop" << std::endl;
+#endif
     }
 
     const fs::path exe_dir = ExeDir();
@@ -230,6 +258,22 @@ int WINAPI wWinMain(HINSTANCE instance, HINSTANCE, PWSTR cmd_line, int)
         return 1;
     }
 
+    // ウィンドウは要求サイズより小さく作られ得る (作業領域クランプ / DPI /
+    // CI の低解像度ディスプレイ)。surface・canvas・screen は全て viewport_* から
+    // 派生するため、ここで「実クライアント矩形」を採用して一致させる。これを
+    // 怠ると surface(1920x1080) を実ウィンドウ(例 1024x768)へ非等倍提示して
+    // 画面が縦長に歪む。V8 バインディング設置(screen/innerWidth/dpr)と
+    // Dawn 初期化の前に確定させる必要がある。
+    {
+        RECT rc = {};
+        if (GetClientRect(hwnd, &rc) && rc.right > 0 && rc.bottom > 0) {
+            host.viewport_width  = rc.right;
+            host.viewport_height = rc.bottom;
+        }
+        std::cerr << "[Win] client rect: " << host.viewport_width
+                  << "x" << host.viewport_height << std::endl;
+    }
+
     // 4. V8 プロセス初期化 + Isolate/Context + バインディング
     V8Runtime::InitializeProcess(nullptr);
     V8Runtime runtime;
@@ -255,7 +299,11 @@ int WINAPI wWinMain(HINSTANCE instance, HINSTANCE, PWSTR cmd_line, int)
     host.workers = &workers;
     g_dawn = &dawn;
 
-    dawn.Initialize(hwnd, host.viewport_width, host.viewport_height);
+    // GPU 無し環境 (CI 等) では Dawn 初期化に失敗し得るが、CPU 側の機能と
+    // selftest は動かせるため続行する (Present 等は内部でゲートされる)
+    if (!dawn.Initialize(hwnd, host.viewport_width, host.viewport_height)) {
+        std::cerr << "warning: Dawn initialization failed - continuing without GPU" << std::endl;
+    }
     gamepad.Initialize();
     audio.Initialize();
 
@@ -300,9 +348,12 @@ int WINAPI wWinMain(HINSTANCE instance, HINSTANCE, PWSTR cmd_line, int)
     }
 
     // 7. ゲームループ
-    v8::Isolate::Scope isolate_scope(runtime.isolate());
     MSG msg = {};
     int exit_code = 0;
+    // Isolate::Scope はループ内に限定する。Enter されたままの isolate を
+    // Dispose すると V8 の fatal (Disposing the isolate that is entered) になる。
+    {
+    v8::Isolate::Scope isolate_scope(runtime.isolate());
     while (g_running) {
         // Win32 メッセージ
         while (PeekMessage(&msg, nullptr, 0, 0, PM_REMOVE)) {
@@ -347,6 +398,27 @@ int WINAPI wWinMain(HINSTANCE instance, HINSTANCE, PWSTR cmd_line, int)
         // 提示
         dawn.Present();
 
+        // フレームペーシング: ブラウザの rAF 同様 ~60Hz に揃える。
+        // Present はスキップ時にブロックしないため、これが無いとループが
+        // 数万回転/秒で空回りし、rAF 前提のゲーム/Tween のタイミングが崩れる。
+        {
+            const double frame_ms = event_loop.Now() - now;
+            if (frame_ms < 15.0) {
+                Sleep(static_cast<DWORD>(15.0 - frame_ms));
+            }
+        }
+
+        // 診断: ループ統計 (5 秒毎)
+        {
+            static uint64_t iteration = 0;
+            ++iteration;
+            if (iteration % 300 == 0) {
+                std::cerr << "[Loop] it=" << iteration
+                          << " rAF=" << event_loop.PendingAnimationFrameCount()
+                          << " timers=" << event_loop.PendingTimerCount() << std::endl;
+            }
+        }
+
         // selftest 完了検知: selftest.js が globalThis.__selftestExitCode を設定したら終了
         if (selftest) {
             v8::Local<v8::Value> code;
@@ -359,10 +431,20 @@ int WINAPI wWinMain(HINSTANCE instance, HINSTANCE, PWSTR cmd_line, int)
         }
     }
 
-    // 8. 後始末
+    }
+
+    // 8. 後始末: v8::Global を保持するものは Isolate 破棄前に必ず明示解放する。
+    //    (スタック変数はスコープ終了 = runtime.Dispose() の後に巻き戻されるため、
+    //     デストラクタ任せにすると破棄済み Isolate への Global::Reset で fail-fast する)
+    workers.Shutdown();      // WorkerInstance の Global<Context> / EventLoop
+    event_loop.Shutdown();   // main の setTimeout/rAF コールバック (Global<Function>)
+    ShutdownAudioEvents();
+    ShutdownWebGPU();
     host.main_canvas.Reset();
     runtime.Dispose();
     V8Runtime::ShutdownProcess();
-    XGameRuntimeUninitialize();
+    if (xgame_initialized) {
+        XGameRuntimeUninitialize();
+    }
     return exit_code;
 }

package/templates/xbox/src/platform/AudioEngine.cpp

@@ -41,6 +41,10 @@ AudioVoice::~AudioVoice()
 
 void AudioVoice::Start(bool loop)
 {
+    // 音声デバイスが無い環境 (CI 等) でも「再生開始→即終了」として扱えるよう、
+    // voice_ の有無に関わらず開始状態は記録する (IsFinished が ended 発火を導く)。
+    started_ = true;
+    looping_ = loop;
     if (!voice_) {
         return;
     }
@@ -51,8 +55,6 @@ void AudioVoice::Start(bool loop)
     buf.LoopCount = loop ? XAUDIO2_LOOP_INFINITE : 0;
     voice_->SubmitSourceBuffer(&buf);
     voice_->Start(0);
-    started_ = true;
-    looping_ = loop;
 }
 
 void AudioVoice::Stop()
@@ -66,9 +68,13 @@ void AudioVoice::Stop()
 
 bool AudioVoice::IsFinished() const
 {
-    if (!voice_ || !started_ || looping_) {
+    if (!started_ || looping_) {
         return false;
     }
+    if (!voice_) {
+        // 実ボイスが無い (音声デバイス無し) 場合は開始と同時に終了扱い。
+        return true;
+    }
     XAUDIO2_VOICE_STATE state = {};
     voice_->GetState(&state);
     return state.BuffersQueued == 0;

package/templates/xbox/src/v8/V8Runtime.cpp

@@ -43,15 +43,26 @@ V8Runtime::~V8Runtime()
 void V8Runtime::InitializeProcess(const char* exec_path)
 {
     // Xbox(GDK) / Nintendo Switch のリテール環境は動的コード生成(JIT)を禁止する。
-    // V8 を jitless (Ignition インタプリタのみ・TurboFan/Sparkplug/RWXページ無し) で動かす。
-    // WebAssembly も JIT を要するため無効化する。
-    v8::V8::SetFlagsFromString("--jitless --no-expose-wasm --no-opt");
+    // - JS: --jitless (Ignition インタプリタのみ・RWX ページ無し)
+    // - WebAssembly: --wasm-jitless (DrumBrake = V8 の wasm インタープリタ。
+    //   prebuilt V8 r2 は v8_enable_drumbrake=true でビルドされている)
+    v8::V8::SetFlagsFromString("--jitless --wasm-jitless");
 
     v8::V8::InitializeICUDefaultLocation(exec_path);
     v8::V8::InitializeExternalStartupData(exec_path);
     platform_ = v8::platform::NewDefaultPlatform();
     v8::V8::InitializePlatform(platform_.get());
     v8::V8::Initialize();
+
+    // WebAssembly (DrumBrake) はメモリ境界検査を guard page + trap handler で行うため、
+    // embedder が trap handler を有効化する必要がある (d8/Chrome も起動時に行う)。
+    // 未設定のまま wasm を実行するとインタープリタ初期化で fail-fast する。
+    // コンソール実機で VEH が使えない場合は、V8 を v8_drumbrake_bounds_checks=true
+    // (明示境界チェック) でビルドし直すこと。
+    if (!v8::V8::EnableWebAssemblyTrapHandler(true)) {
+        std::cerr << "warning: EnableWebAssemblyTrapHandler failed"
+                  << " - WebAssembly may not work" << std::endl;
+    }
 }
 
 void V8Runtime::ShutdownProcess()
@@ -75,6 +86,35 @@ bool V8Runtime::Initialize(HostContext* host)
     // 例外時に未処理を潰さないよう、明示的に MicrotasksPolicy を制御する
     isolate_->SetMicrotasksPolicy(v8::MicrotasksPolicy::kExplicit);
 
+    // 未処理の Promise 拒否を stderr へ報告する。framework の boot は async のため、
+    // この報告が無いと例外がどこにも出ずゲームが無音で停止する (実際に発生した)。
+    isolate_->SetPromiseRejectCallback([](v8::PromiseRejectMessage message) {
+        if (message.GetEvent() != v8::kPromiseRejectWithNoHandler) {
+            return;   // 後からハンドラが付く分などは報告しない
+        }
+        v8::Isolate* isolate = v8::Isolate::GetCurrent();
+        v8::HandleScope hs(isolate);
+        v8::Local<v8::Value> value = message.GetValue();
+        std::string text = "(no value)";
+        std::string stack;
+        if (!value.IsEmpty()) {
+            text = v8util::ToStdString(isolate, value);
+            v8::Local<v8::Context> ctx = isolate->GetCurrentContext();
+            if (!ctx.IsEmpty() && value->IsObject()) {
+                v8::Local<v8::Value> s;
+                if (value.As<v8::Object>()
+                        ->Get(ctx, v8util::Str(isolate, "stack")).ToLocal(&s) &&
+                    s->IsString()) {
+                    stack = v8util::ToStdString(isolate, s);
+                }
+            }
+        }
+        std::cerr << "[V8] Unhandled promise rejection: " << text << std::endl;
+        if (!stack.empty() && stack != text) {
+            std::cerr << stack << std::endl;
+        }
+    });
+
     v8::Isolate::Scope isolate_scope(isolate_);
     v8::HandleScope handle_scope(isolate_);
 
@@ -148,12 +188,37 @@ v8::MaybeLocal<v8::Module> V8Runtime::LoadModule(const std::string& path,
         return cached->second.Get(isolate_);
     }
 
-    const std::string source = ReadTextFile(abs);
+    std::string source = ReadTextFile(abs);
     if (source.empty() && !fs::exists(abs)) {
         v8util::ThrowTypeError(isolate_, "Module not found: " + abs);
         return v8::MaybeLocal<v8::Module>();
     }
 
+    // «診断» Tween(Job) の凍結調査: app.js の Job 更新コードへトレースを注入する。
+    // rAF が 2 本 (ticker + 1 Job) のまま描画が止まる現象の currentTime/duration の
+    // 実値を観測する。パターン不一致なら無変更 (ログのみ)。
+    if (source.find("(e.currentTime=(t-e.startTime)/1e3,") != std::string::npos) {
+        const auto patch = [&source](const std::string& from, const std::string& to) {
+            const auto pos = source.find(from);
+            if (pos != std::string::npos) {
+                source.replace(pos, from.size(), to);
+            } else {
+                std::cerr << "[V8] job trace patch not applied: "
+                          << from.substr(0, 40) << std::endl;
+            }
+        };
+        patch("(e.currentTime=(t-e.startTime)/1e3,",
+              "(e.currentTime=(t-e.startTime)/1e3,"
+              "((globalThis.__jt=(globalThis.__jt||0)+1)<=60||globalThis.__jt%600===0)&&"
+              "console.info(\"[jobtrace] #\"+globalThis.__jt,"
+              "\"ct=\"+e.currentTime.toFixed(3),\"dur=\"+e.duration,"
+              "\"t=\"+t.toFixed(1),\"st=\"+e.startTime.toFixed(1)),");
+        patch("e.currentTime>=e.duration?(",
+              "e.currentTime>=e.duration?("
+              "console.info(\"[jobtrace] COMPLETE dur=\"+e.duration),");
+        std::cerr << "[V8] job trace patch applied to " << abs << std::endl;
+    }
+
     v8::Local<v8::String> src = v8util::Str(isolate_, source);
 
     v8::ScriptOrigin origin(

package/templates/xbox/src/v8/V8Util.h

@@ -2,6 +2,7 @@
 #pragma once
 
 #include <v8.h>
+#include <iostream>
 #include <string>
 #include <string_view>
 
@@ -53,4 +54,32 @@ inline void ThrowTypeError(v8::Isolate* isolate, std::string_view message)
     isolate->ThrowException(v8::Exception::TypeError(Str(isolate, message)));
 }
 
+// TryCatch が例外を保持していれば stderr へ報告する。
+// rAF / タイマー / onmessage / イベントリスナーのコールバックは TryCatch で
+// 保護されるが、報告しないと例外が無音で消えて原因究明が不可能になる
+// (レンダラ worker が毎フレーム throw していても黒画面にしか見えない)。
+inline void ReportCaught(v8::Isolate* isolate, v8::TryCatch* tc, const char* where)
+{
+    if (!tc->HasCaught()) {
+        return;
+    }
+    v8::HandleScope hs(isolate);
+    v8::Local<v8::Context> ctx = isolate->GetCurrentContext();
+    const std::string text = ToStdString(isolate, tc->Exception());
+    std::cerr << "[JS] exception in " << where << ": " << text << std::endl;
+    v8::Local<v8::Value> stack;
+    if (!ctx.IsEmpty() && tc->StackTrace(ctx).ToLocal(&stack)) {
+        const std::string s = ToStdString(isolate, stack);
+        if (!s.empty() && s != text) {
+            std::cerr << s << std::endl;
+        }
+    }
+    v8::Local<v8::Message> message = tc->Message();
+    if (!message.IsEmpty() && !ctx.IsEmpty()) {
+        std::cerr << "  at "
+                  << ToStdString(isolate, message->GetScriptOrigin().ResourceName())
+                  << ":" << message->GetLineNumber(ctx).FromMaybe(0) << std::endl;
+    }
+}
+
 } // namespace next2d::v8util

package/templates/xbox/src/v8/WeakHandle.h

@@ -0,0 +1,45 @@
+// SetWeak (GC 連動の解放) の正しい運用ヘルパー。
+//
+// V8 の規約では、第一パスの weak callback 内で対応する v8::Global を必ず
+// Reset しなければならない。違反すると GC 時に fatal
+// 「Check failed: Handle not reset in first callback.」で落ちる。
+// payload と Global を束ねて所有し、GC で Reset + delete の両方を行う。
+#pragma once
+
+#include <v8.h>
+
+namespace next2d::v8util {
+
+template <typename T>
+class WeakHandle {
+public:
+    static void Attach(v8::Isolate* isolate, v8::Local<v8::Object> obj, T* payload)
+    {
+        auto* w = new WeakHandle<T>(payload);
+        w->handle_.Reset(isolate, obj);
+        w->handle_.SetWeak(w, &WeakHandle::OnGC, v8::WeakCallbackType::kParameter);
+    }
+
+private:
+    explicit WeakHandle(T* payload) : payload_(payload) {}
+
+    static void OnGC(const v8::WeakCallbackInfo<WeakHandle<T>>& info)
+    {
+        WeakHandle<T>* w = info.GetParameter();
+        w->handle_.Reset();   // 第一パスでの Reset (V8 の必須要件)
+        delete w->payload_;
+        delete w;
+    }
+
+    v8::Global<v8::Object> handle_;
+    T* payload_;
+};
+
+// オブジェクトが GC されたときに `delete payload` する弱参照を張る。
+template <typename T>
+inline void AttachWeak(v8::Isolate* isolate, v8::Local<v8::Object> obj, T* payload)
+{
+    WeakHandle<T>::Attach(isolate, obj, payload);
+}
+
+} // namespace next2d::v8util