From 73a66e8407c5dafaf857973e5fda642e590a980b Mon Sep 17 00:00:00 2001
From: Will Eastcott <will@playcanvas.com>
Date: Tue, 27 Oct 2026 20:16:26 +0000
Subject: [PATCH 1/2] docs: track Web Components 0.28.1 - pc-wasm load failures
 and what time-scale 0 leaves running

- pc-wasm: a module that fails to load fires a non-bubbling `error`
  event once per element, logs the failure and still becomes ready,
  so the containing pc-app boots without it (library #534). Adds an
  Events section, rewrites the readiness prose and notes that a
  wrong-case `name` is the one failure that still hangs the app
- programmatic-access: drop failed loads from the never-ready list
  and describe pc-wasm readiness as "loaded or failed"
- pc-app: `time-scale="0"` does not pause scripts; they keep running
  with a `dt` of 0 (library #532)
- pc-asset: the capture-phase `error` listener also sees pc-wasm's
- Pin the live examples to @playcanvas/web-components 0.28.1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../web-components/programmatic-access.md     |  6 +--
 .../user-manual/web-components/tags/pc-app.md |  2 +-
 .../web-components/tags/pc-asset.md           |  2 +-
 .../web-components/tags/pc-wasm.md            | 37 ++++++++++++++-----
 .../web-components/programmatic-access.md     |  6 +--
 .../user-manual/web-components/tags/pc-app.md |  2 +-
 .../web-components/tags/pc-asset.md           |  2 +-
 .../web-components/tags/pc-wasm.md            | 18 +++++++--
 src/components/LiveExample/shell.js           |  2 +-
 9 files changed, 53 insertions(+), 24 deletions(-)

diff --git a/docs/user-manual/web-components/programmatic-access.md b/docs/user-manual/web-components/programmatic-access.md
index 3cc7d40f764..4dbd718d3c5 100644
--- a/docs/user-manual/web-components/programmatic-access.md
+++ b/docs/user-manual/web-components/programmatic-access.md
@@ -39,7 +39,7 @@ Keep that entry's URL identical to the library's `<script>` tag, or the page loa
 
 :::note[Elements That Never Become Ready]
 
-The promise never settles if the element cannot finish initializing — for example, a `<pc-script-instance>` that is not a direct child of `<pc-script>`, a [`<pc-node>`](./tags/pc-node.md) that cannot resolve its `name`, a [`<pc-model>`](./tags/pc-model.md) whose `asset` names no declared asset, a [`<pc-wasm>`](./tags/pc-wasm.md) without a `name` or whose module fails to load, or a [`<pc-app>`](./tags/pc-app.md) that could not create a graphics device (see its [`error` event](./tags/pc-app.md#events)). A component element with no `<pc-entity>`, `<pc-model>` or `<pc-node>` above it is the exception: it still becomes ready, but its `component` is `null`. In each of these cases, the console says what went wrong.
+The promise never settles if the element cannot finish initializing — for example, a `<pc-script-instance>` that is not a direct child of `<pc-script>`, a [`<pc-node>`](./tags/pc-node.md) that cannot resolve its `name`, a [`<pc-model>`](./tags/pc-model.md) whose `asset` names no declared asset, a [`<pc-wasm>`](./tags/pc-wasm.md) without a `name` or with one in the wrong case, or a [`<pc-app>`](./tags/pc-app.md) that could not create a graphics device (see its [`error` event](./tags/pc-app.md#events)). A component element with no `<pc-entity>`, `<pc-model>` or `<pc-node>` above it is the exception: it still becomes ready, but its `component` is `null`. In each of these cases, the console says what went wrong.
 
 An element *removed* from the document before it finished initializing does not become ready either — nothing is wrong, so nothing is reported, but an await on its `ready()` will not complete unless the element is put back, which carries the wait over to its next initialization. When teardown can race initialization (common with [cloned templates](templates.md)), race the await against your own teardown signal — see [Removing an Instance](templates.md#removing-an-instance).
 
@@ -128,10 +128,10 @@ const material = MaterialElement.get('gold'); // the material declared by <pc-ma
 
 `AssetElement.get` returns the registered [`Asset`](https://api.playcanvas.com/engine/classes/Asset.html), which may not have finished loading yet — check `asset.loaded`, or subscribe to its `load` event, before using `asset.resource`. A failed load also sets `loaded`, with no `resource`. Looking a `lazy` asset up this way does not start its load, so call `app.assets.load(asset)` if nothing else will.
 
-[`<pc-wasm>`](./tags/pc-wasm.md) initializes asynchronously like the elements above — it becomes ready once its module has loaded, so `whenReady('pc-wasm')` awaits the load. (`Basis` is the exception: it is ready as soon as its transcoder starts loading.) You will rarely need it: `<pc-app>` waits for every `<pc-wasm>` among its children before it creates its graphics device, so an app that is ready is an app whose modules have loaded. Awaiting the app is how you wait for Ammo:
+[`<pc-wasm>`](./tags/pc-wasm.md) initializes asynchronously like the elements above — it becomes ready once its module has loaded or failed to load, so `whenReady('pc-wasm')` awaits the load. (`Basis` is the exception: it is ready as soon as its transcoder starts loading.) Readiness does not mean success: a module that fails also fires an [`error` event](./tags/pc-wasm.md#events). You will rarely need it: `<pc-app>` waits for every `<pc-wasm>` among its children to settle before it creates its graphics device, so by the time the app is ready each module has loaded or reported its failure. Awaiting the app is how you wait for Ammo:
 
 ```javascript
-const { app } = await whenReady('pc-app'); // every <pc-wasm> has loaded by now
+const { app } = await whenReady('pc-app'); // every <pc-wasm> has loaded or failed by now
 ```
 
 One caveat sets `<pc-wasm>` apart: its readiness is sticky. WebAssembly modules configure engine-global state that never unloads, so removing and re-inserting the element neither resets its readiness nor loads the module again — see [Readiness](./tags/pc-wasm.md#readiness).
diff --git a/docs/user-manual/web-components/tags/pc-app.md b/docs/user-manual/web-components/tags/pc-app.md
index 177f2086ac5..b6ec7e527ac 100644
--- a/docs/user-manual/web-components/tags/pc-app.md
+++ b/docs/user-manual/web-components/tags/pc-app.md
@@ -28,7 +28,7 @@ The `<pc-app>` tag is the root element for your PlayCanvas application. It is us
 | `physics-time-scale` | Number | `"1"` | Scale on the time the physics simulation advances by each frame, applied on top of `time-scale`: below 1 is slow motion, above 1 speeds it up, and `"0"` pauses physics while the rest of the application keeps running — for a pause menu, say, that must stay interactive while the world stands still |
 | `picking` | Enum | `"auto"` | When the application picks the scene under the pointer to dispatch [pointer events](../pc-entity#events) on entity elements: `"auto"` \| `"always"` \| `"none"`. `auto` picks for an event type only while a listener for it is registered on an entity element or on [`<pc-scene>`](../pc-scene); `always` picks for every pointer event, which listeners the application cannot see need, such as one on the document or a framework's delegated handler like React's `onPointerMove`; `none` never picks, so entities receive no pointer events. Picking renders the scene again, which is why `auto` is the default. See [When Events Are Dispatched](../pc-entity#when-events-are-dispatched) |
 | `stencil-buffer` | Boolean | `"true"` | Whether the application allocates a stencil buffer |
-| `time-scale` | Number | `"1"` | Scale on the time the application advances by each frame. Scripts, animation and physics all advance by the scaled time, so below 1 is slow motion, above 1 speeds it up, and `"0"` pauses all three together while the scene keeps rendering. To slow down or pause physics alone, use `physics-time-scale` |
+| `time-scale` | Number | `"1"` | Scale on the time the application advances by each frame. Scripts, animation and physics all advance by the scaled time, so below 1 is slow motion, above 1 speeds it up, and `"0"` freezes everything that advances with time while the scene keeps rendering. It does not pause scripts: their `update` and `postUpdate` methods still run every frame with a `dt` of 0, so input handling, spawning and any other logic that is not multiplied by `dt` carries on — give gameplay code its own pause check. To slow down or pause physics alone, use `physics-time-scale` |
 | `with-credentials` | Boolean | `"false"` | Whether asset requests send credentials (cookies and HTTP authentication) to other origins, which the asset server must allow through CORS. The engine keeps this setting in an HTTP client shared by the whole page, so it applies to every `<pc-app>` on the page: an app that boots with it switches it on for all of them, and a later change on any app sets it for all of them |
 
 </div>
diff --git a/docs/user-manual/web-components/tags/pc-asset.md b/docs/user-manual/web-components/tags/pc-asset.md
index 4153609f00d..7cd5831e6a2 100644
--- a/docs/user-manual/web-components/tags/pc-asset.md
+++ b/docs/user-manual/web-components/tags/pc-asset.md
@@ -90,7 +90,7 @@ Listen to these events using [`addEventListener()`](https://developer.mozilla.or
 | `load` | Fired each time the asset finishes loading, including a `lazy` asset loaded later and any subsequent reloads. |
 | `error` | An [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent) fired when the asset fails to load, with the engine's error in `message`. |
 
-Neither event bubbles, so listen on the element itself — or use a capture-phase listener on `<pc-app>` to observe every asset it holds. The same listener also sees other elements' `error` events, such as [`<pc-model>`](../pc-model)'s and the app's own, so check the target:
+Neither event bubbles, so listen on the element itself — or use a capture-phase listener on `<pc-app>` to observe every asset it holds. The same listener also sees other elements' `error` events, such as [`<pc-model>`](../pc-model)'s, [`<pc-wasm>`](../pc-wasm)'s and the app's own, so check the target:
 
 ```javascript
 document.querySelector('pc-app').addEventListener('error', (event) => {
diff --git a/docs/user-manual/web-components/tags/pc-wasm.md b/docs/user-manual/web-components/tags/pc-wasm.md
index ef60e063587..a8198de3944 100644
--- a/docs/user-manual/web-components/tags/pc-wasm.md
+++ b/docs/user-manual/web-components/tags/pc-wasm.md
@@ -24,7 +24,7 @@ The `<pc-wasm>` tag loads a WebAssembly module the engine needs before the appli
 
 </div>
 
-The `name` is case-sensitive — the engine looks the module up by exact name. The modules consumed by the engine are `Ammo` (physics), `Basis` (texture transcoding) and `DracoDecoderModule` (mesh decompression).
+The `name` is case-sensitive — the engine looks the module up by exact name. The modules consumed by the engine are `Ammo` (physics), `Basis` (texture transcoding) and `DracoDecoderModule` (mesh decompression). Getting the case wrong is the one load failure the element cannot report: with `name="ammo"`, the engine throws a `TypeError` as the glue script loads, no `error` event fires, and neither the element nor its `<pc-app>` ever becomes ready.
 
 :::note[When these are read]
 
@@ -37,26 +37,43 @@ attributes before appending the element to the document.
 
 ## Readiness
 
-The element initializes asynchronously and becomes ready once its module has loaded: it fires the
-standard `ready` event and can be awaited with `whenReady('pc-wasm')` — see
+The element initializes asynchronously and becomes ready once its module has loaded or failed to
+load: it fires the standard `ready` event and can be awaited with `whenReady('pc-wasm')` — see
 [Programmatic Access](../programmatic-access.md). (`Basis` is the exception: it is ready as soon
-as its transcoder starts loading.) You will rarely need to, though: a `<pc-app>` waits for every
-`<pc-wasm>` among its children before creating its graphics device, so an app that is ready is an
-app whose modules have loaded. A `<pc-wasm>` nested any deeper still loads, but the app does not
-wait for it.
+as its transcoder starts loading.) Readiness means the load settled, not that it succeeded; a
+module that fails also fires [`error`](#events). You will rarely need to wait for the element,
+though: a `<pc-app>` waits for every `<pc-wasm>` among its children to settle before creating its
+graphics device, so by the time the app is ready each module has either loaded or reported its
+failure. A `<pc-wasm>` nested any deeper still loads, but the app does not wait for it.
 
 Readiness is deliberately sticky. A WebAssembly module configures engine-global state that never
 unloads, so removing the element does not return it to a pending state, and re-inserting it does
 not load the module again.
 
 A `<pc-wasm>` without a `name` logs a warning and never becomes ready — but it does not block
-the containing `<pc-app>` from booting. A module that fails to load, from a mistyped URL or a
-server that refuses it, is worse: the element never becomes ready and its `<pc-app>` never starts,
-with only a `failed to initialize module=...` error in the console to show for it.
+the containing `<pc-app>` from booting.
 
 Declare `Ammo` in the markup rather than adding it later. The engine looks for the physics module
 once, as the application starts, so an app that booted without it runs without physics.
 
+## Events
+
+Listen to this event using [`addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) or by assigning an event listener to the `oneventname` property of this interface.
+
+| Event | Description |
+| --- | --- |
+| `error` | An [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent) fired when the module fails to load — from a mistyped URL, say, or a server that refuses it — with the engine's error in `message`. It fires once per element, and the element still becomes ready. A `Basis` module never fires it. |
+
+The event does not bubble, so listen on the element itself or with a capture-phase listener on
+`<pc-app>`.
+
+A module that fails to load does not stop the application. The element logs
+`pc-wasm failed to load module '<name>' - <error>` to the console, and the containing `<pc-app>`
+boots without the module — a failed `Ammo` leaves the app running without physics. The engine
+never tries to load a failed module again, so every `<pc-wasm>` for that module fails with it: one
+already waiting when the load fails, and one added later, in a second `<pc-app>` say, which fails
+straight away.
+
 ## Example
 
 Loading the `Ammo` physics module. The box only falls because the module is declared — the app waits for it before booting, so physics is ready when the scene starts. Try removing the `<pc-wasm>` tag and re-running:
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/programmatic-access.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/programmatic-access.md
index 75fd7a3cddd..9d180c88cd8 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/programmatic-access.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/programmatic-access.md
@@ -39,7 +39,7 @@ PlayCanvas Web Components を使えば、HTML だけでリッチな 3D シーン
 
 :::note[準備完了にならない要素]
 
-要素が初期化を完了できない場合、Promiseは決して解決されません。たとえば、`<pc-script>` の直接の子ではない `<pc-script-instance>`、`name` を解決できない [`<pc-node>`](./tags/pc-node.md)、`asset` が宣言されたどのアセットも指していない [`<pc-model>`](./tags/pc-model.md)、`name` がないかモジュールの読み込みに失敗した [`<pc-wasm>`](./tags/pc-wasm.md)、グラフィックスデバイスを作成できなかった [`<pc-app>`](./tags/pc-app.md)（その [`error` イベント](./tags/pc-app.md#events)を参照）などです。例外は、上に `<pc-entity>`・`<pc-model>`・`<pc-node>` のいずれもないコンポーネント要素で、この場合はready状態にはなりますが、`component` は `null` になります。これらのいずれの場合も、何が問題だったかがコンソールに出力されます。
+要素が初期化を完了できない場合、Promiseは決して解決されません。たとえば、`<pc-script>` の直接の子ではない `<pc-script-instance>`、`name` を解決できない [`<pc-node>`](./tags/pc-node.md)、`asset` が宣言されたどのアセットも指していない [`<pc-model>`](./tags/pc-model.md)、`name` がないか、その大文字と小文字が誤っている [`<pc-wasm>`](./tags/pc-wasm.md)、グラフィックスデバイスを作成できなかった [`<pc-app>`](./tags/pc-app.md)（その [`error` イベント](./tags/pc-app.md#events)を参照）などです。例外は、上に `<pc-entity>`・`<pc-model>`・`<pc-node>` のいずれもないコンポーネント要素で、この場合はready状態にはなりますが、`component` は `null` になります。これらのいずれの場合も、何が問題だったかがコンソールに出力されます。
 
 初期化が完了する前にドキュメントから*削除された*要素も、ready状態にはなりません — 何も問題は起きていないので何も報告されませんが、要素が元に戻されない限り、その `ready()` に対するawaitは完了しません。元に戻された場合、待機は次の初期化に引き継がれます。破棄が初期化と競合しうる場合（[クローンされたテンプレート](templates.md)ではよくあることです）は、awaitを自分自身の破棄シグナルと競争させてください — [インスタンスを削除する](templates.md#removing-an-instance)を参照してください。
 
@@ -128,10 +128,10 @@ const material = MaterialElement.get('gold'); // <pc-material id="gold"> が宣
 
 `AssetElement.get` は登録済みの [`Asset`](https://api.playcanvas.com/engine/classes/Asset.html) を返しますが、読み込みが完了していない場合があります。`asset.resource` を使用する前に、`asset.loaded` を確認するか、`load` イベントを購読してください。読み込みに失敗した場合も `loaded` は設定され、`resource` はありません。`lazy` のアセットをこの方法で取得しても読み込みは始まらないため、他に読み込むものがなければ `app.assets.load(asset)` を呼び出してください。
 
-[`<pc-wasm>`](./tags/pc-wasm.md) は、上記の要素と同じく非同期に初期化されます。モジュールの読み込みが完了するとready状態になるため、`whenReady('pc-wasm')` で読み込みを待機できます（例外は `Basis` で、トランスコーダーの読み込みが始まった時点でready状態になります）。とはいえ、これが必要になることはほとんどありません。`<pc-app>` は、自身の子要素であるすべての `<pc-wasm>` を待ってからグラフィックスデバイスを作成するため、準備完了したアプリとは、モジュールの読み込みが完了したアプリです。Ammoを待つ方法は、アプリを待つことです。
+[`<pc-wasm>`](./tags/pc-wasm.md) は、上記の要素と同じく非同期に初期化されます。モジュールの読み込みが完了するか失敗するとready状態になるため、`whenReady('pc-wasm')` で読み込みを待機できます（例外は `Basis` で、トランスコーダーの読み込みが始まった時点でready状態になります）。ready状態は成功を意味しません。失敗したモジュールは [`error` イベント](./tags/pc-wasm.md#events)も発生させます。とはいえ、これが必要になることはほとんどありません。`<pc-app>` は、自身の子要素であるすべての `<pc-wasm>` の読み込みが決着するのを待ってからグラフィックスデバイスを作成するため、アプリが準備完了した時点で、各モジュールは読み込みを完了しているか、失敗を報告しています。Ammoを待つ方法は、アプリを待つことです。
 
 ```javascript
-const { app } = await whenReady('pc-app'); // この時点ですべての <pc-wasm> は読み込み済みです
+const { app } = await whenReady('pc-app'); // この時点ですべての <pc-wasm> の読み込みは完了または失敗しています
 ```
 
 1つだけ `<pc-wasm>` に特有の注意点があります。そのready状態は固定（スティッキー）です。WebAssemblyモジュールは決してアンロードされないエンジングローバルな状態を構成するため、要素を削除して再挿入してもready状態はリセットされず、モジュールが再読み込みされることもありません。[準備完了](./tags/pc-wasm.md#readiness)を参照してください。
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-app.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-app.md
index f58585c1416..c8000bdd32a 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-app.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-app.md
@@ -28,7 +28,7 @@ description: "pc-app要素のリファレンス: PlayCanvasのApplicationを初
 | `physics-time-scale` | Number | `"1"` | 物理シミュレーションが毎フレーム進める時間に掛かる倍率で、`time-scale`に重ねて適用されます。1未満はスローモーション、1を超えると高速になり、`"0"`はアプリケーションの他の部分を動かしたまま物理を一時停止します。たとえば、ゲームの世界を止めたまま操作できる状態を保つ必要があるポーズメニューに使えます |
 | `picking` | Enum | `"auto"` | エンティティ要素で[ポインターイベント](../pc-entity#events)をディスパッチするために、アプリケーションがポインターの下のシーンをいつピッキングするか: `"auto"` \| `"always"` \| `"none"`。`auto`は、あるイベントの種類のリスナーがエンティティ要素または[`<pc-scene>`](../pc-scene)に登録されている間だけ、その種類についてピッキングします。`always`はすべてのポインターイベントでピッキングします。ドキュメント上のリスナーや、Reactの`onPointerMove`のようなフレームワークの委譲ハンドラーなど、アプリケーションが認識できないリスナーにはこれが必要です。`none`はピッキングを一切行わないため、エンティティはポインターイベントを受け取りません。ピッキングではシーンをもう一度レンダリングするため、`auto`がデフォルトになっています。[イベントがディスパッチされるタイミング](../pc-entity#when-events-are-dispatched)を参照 |
 | `stencil-buffer` | Boolean | `"true"` | アプリケーションがステンシルバッファを割り当てるかどうか |
-| `time-scale` | Number | `"1"` | アプリケーションが毎フレーム進める時間に掛かる倍率。スクリプト、アニメーション、物理はすべてこの倍率を掛けた時間で進むため、1未満はスローモーション、1を超えると高速になり、`"0"`はシーンの描画を続けたまま3つすべてをまとめて一時停止します。物理だけを遅くしたり一時停止したりするには`physics-time-scale`を使用してください |
+| `time-scale` | Number | `"1"` | アプリケーションが毎フレーム進める時間に掛かる倍率。スクリプト、アニメーション、物理はすべてこの倍率を掛けた時間で進むため、1未満はスローモーション、1を超えると高速になり、`"0"`はシーンの描画を続けたまま、時間とともに進むものをすべて止めます。ただし、スクリプトは一時停止しません。スクリプトの`update`メソッドと`postUpdate`メソッドは毎フレーム`dt`が0のまま呼び出され続けるため、入力処理、オブジェクトの生成など、`dt`を掛けていない処理はそのまま続きます。ゲームプレイのコードには独自の一時停止チェックを設けてください。物理だけを遅くしたり一時停止したりするには`physics-time-scale`を使用してください |
 | `with-credentials` | Boolean | `"false"` | アセットのリクエストが他のオリジンに資格情報（CookieとHTTP認証）を送信するかどうか。アセットサーバー側でCORSにより許可されている必要があります。エンジンはこの設定をページ全体で共有されるHTTPクライアントに保持するため、ページ上のすべての`<pc-app>`に適用されます。この属性を付けて起動したアプリはすべてのアプリケーションで有効にし、その後いずれかのアプリで変更すると、すべてのアプリケーションに対して設定されます |
 
 </div>
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-asset.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-asset.md
index 44256679f73..4357e1d55b8 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-asset.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-asset.md
@@ -90,7 +90,7 @@ description: "pc-asset要素のリファレンス: URLで読み込むアセッ
 | `load` | アセットの読み込みが完了するたびに発生します。後から読み込まれる`lazy`アセットや、その後の再読み込みも含みます。 |
 | `error` | アセットの読み込みが失敗したときに発生する[`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent)で、エンジンのエラーが`message`に入ります。 |
 
-どちらのイベントもバブリングしないため、要素自身でリッスンしてください。あるいは、`<pc-app>`が保持するすべてのアセットを監視するには、`<pc-app>`でキャプチャフェーズのリスナーを使用します。同じリスナーは[`<pc-model>`](../pc-model)やアプリ自身のものなど、他の要素の`error`イベントも受け取るため、ターゲットを確認してください。
+どちらのイベントもバブリングしないため、要素自身でリッスンしてください。あるいは、`<pc-app>`が保持するすべてのアセットを監視するには、`<pc-app>`でキャプチャフェーズのリスナーを使用します。同じリスナーは[`<pc-model>`](../pc-model)、[`<pc-wasm>`](../pc-wasm)、アプリ自身のものなど、他の要素の`error`イベントも受け取るため、ターゲットを確認してください。
 
 ```javascript
 document.querySelector('pc-app').addEventListener('error', (event) => {
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md
index 064f78a5cbf..68fb2e7fa8a 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md
@@ -24,7 +24,7 @@ description: "pc-wasm要素のリファレンス: glue・wasm・fallbackのパ
 
 </div>
 
-`name`は大文字と小文字が区別されます — エンジンは正確な名前でモジュールを検索します。エンジンが使用するモジュールは`Ammo`（物理）、`Basis`（テクスチャトランスコード）、`DracoDecoderModule`（メッシュ展開）です。
+`name`は大文字と小文字が区別されます — エンジンは正確な名前でモジュールを検索します。エンジンが使用するモジュールは`Ammo`（物理）、`Basis`（テクスチャトランスコード）、`DracoDecoderModule`（メッシュ展開）です。大文字と小文字の誤りは、要素が報告できない唯一の読み込み失敗です。`name="ammo"`とすると、glueスクリプトの読み込み時にエンジンが`TypeError`をスローし、`error`イベントは発生せず、要素もその`<pc-app>`も決してready状態になりません。
 
 :::note[属性が読み取られるタイミング]
 
@@ -34,14 +34,26 @@ description: "pc-wasm要素のリファレンス: glue・wasm・fallbackのパ
 
 ## 準備完了 {#readiness}
 
-この要素は非同期に初期化され、モジュールの読み込みが完了するとready状態になります。標準の`ready`イベントを発生させ、`whenReady('pc-wasm')`で待機できます（[プログラムによるアクセス](../programmatic-access.md)を参照）。（例外は`Basis`で、トランスコーダーの読み込みが始まった時点でready状態になります。）ただし、直接待機する必要はほとんどありません。`<pc-app>`は、グラフィックスデバイスを作成する前に、子要素であるすべての`<pc-wasm>`を待機するため、準備完了したアプリとは、モジュールの読み込みが完了したアプリだからです。それより深くネストされた`<pc-wasm>`も読み込まれますが、アプリはそれを待ちません。
+この要素は非同期に初期化され、モジュールの読み込みが完了するか失敗するとready状態になります。標準の`ready`イベントを発生させ、`whenReady('pc-wasm')`で待機できます（[プログラムによるアクセス](../programmatic-access.md)を参照）。（例外は`Basis`で、トランスコーダーの読み込みが始まった時点でready状態になります。）ready状態は読み込みが決着したことを意味し、成功したことを意味するわけではありません。失敗したモジュールは[`error`](#events)も発生させます。ただし、要素を直接待機する必要はほとんどありません。`<pc-app>`は、グラフィックスデバイスを作成する前に、子要素であるすべての`<pc-wasm>`の読み込みが決着するのを待機するため、アプリが準備完了した時点で、各モジュールは読み込みを完了しているか、失敗を報告しているからです。それより深くネストされた`<pc-wasm>`も読み込まれますが、アプリはそれを待ちません。
 
 準備完了状態は意図的に固定されています。WebAssemblyモジュールは決してアンロードされないエンジングローバルな状態を構成するため、要素を削除してもpending状態には戻らず、再挿入してもモジュールが再読み込みされることはありません。
 
-`name`のない`<pc-wasm>`は警告をログに出力し、決してready状態になりません — ただし、包含する`<pc-app>`の起動は妨げません。URLの誤りやサーバーの拒否によってモジュールの読み込みに失敗した場合はさらに深刻です。要素は決してready状態にならず、その`<pc-app>`も起動せず、コンソールに`failed to initialize module=...`というエラーが出るだけです。
+`name`のない`<pc-wasm>`は警告をログに出力し、決してready状態になりません — ただし、包含する`<pc-app>`の起動は妨げません。
 
 `Ammo`は後から追加するのではなく、マークアップで宣言してください。エンジンが物理モジュールを探すのはアプリケーションの起動時の一度だけなので、それなしで起動したアプリは物理なしで動作します。
 
+## イベント {#events}
+
+このイベントは、[`addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)を使用するか、このインターフェースの`oneventname`プロパティにイベントリスナーを割り当てることでリッスンできます。
+
+| イベント | 説明 |
+| --- | --- |
+| `error` | モジュールの読み込みが失敗したとき（URLの誤りやサーバーの拒否など）に発生する[`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent)で、エンジンのエラーが`message`に入ります。要素ごとに一度だけ発生し、要素はそれでもready状態になります。`Basis`モジュールでは発生しません。 |
+
+このイベントはバブリングしないため、要素自身でリッスンするか、`<pc-app>`でキャプチャフェーズのリスナーを使用してください。
+
+読み込みに失敗したモジュールがあっても、アプリケーションは止まりません。要素はコンソールに`pc-wasm failed to load module '<name>' - <error>`を出力し、包含する`<pc-app>`はそのモジュールなしで起動します。`Ammo`が失敗した場合、アプリは物理なしで動作します。エンジンは失敗したモジュールを二度と読み込もうとしないため、そのモジュールを読み込むすべての`<pc-wasm>`が一緒に失敗します。読み込みが失敗した時点ですでに待機していたものも、後から追加されたもの（たとえば2つ目の`<pc-app>`の中のもの）も同様で、後者はただちに失敗します。
+
 ## 例 {#example}
 
 `Ammo` 物理モジュールの読み込みです。ボックスが落下するのはモジュールが宣言されているからです — アプリはモジュールを待ってから起動するため、シーン開始時には物理が使用可能になっています。`<pc-wasm>` タグを削除して再実行してみましょう:
diff --git a/src/components/LiveExample/shell.js b/src/components/LiveExample/shell.js
index 65b9647e44d..e465e7ccc47 100644
--- a/src/components/LiveExample/shell.js
+++ b/src/components/LiveExample/shell.js
@@ -6,7 +6,7 @@
 // a new @playcanvas/web-components release (the engine version should match
 // the library's dev-pinned engine).
 export const ENGINE_VERSION = '2.23.0';
-export const PWC_VERSION = '0.28.0';
+export const PWC_VERSION = '0.28.1';
 
 // The Vite version that Engine examples opened in StackBlitz install, matching
 // the create-playcanvas starters.

From 5a3377876cf8c3964a4c0488b48e0daee1d61219 Mon Sep 17 00:00:00 2001
From: Will Eastcott <will@playcanvas.com>
Date: Tue, 27 Oct 2026 20:26:13 +0000
Subject: [PATCH 2/2] docs: make pc-wasm module access conditional on a
 successful load

The JavaScript Interface paragraph still said a ready element means an
instantiated module. Since 0.28.1 a failed load also makes the element
ready, while `Ammo` stays undefined and `WasmModule.getInstance` never
calls back, so code that needs a module has to handle the `error`
outcome instead of waiting on `getInstance`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/user-manual/web-components/tags/pc-wasm.md                 | 2 +-
 .../current/user-manual/web-components/tags/pc-wasm.md          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/user-manual/web-components/tags/pc-wasm.md b/docs/user-manual/web-components/tags/pc-wasm.md
index a8198de3944..a75661bf36e 100644
--- a/docs/user-manual/web-components/tags/pc-wasm.md
+++ b/docs/user-manual/web-components/tags/pc-wasm.md
@@ -107,7 +107,7 @@ Loading the `Ammo` physics module. The box only falls because the module is decl
 
 You can programmatically create and manipulate `<pc-wasm>` elements using the [WasmElement API](https://api.playcanvas.com/web-components/classes/WasmElement.html).
 
-The element exposes no engine object of its own. Once it is ready the module has been instantiated through the engine's `WasmModule` under its `name` (`Basis` goes through the engine's Basis initializer instead). Ammo's glue script defines the global `Ammo`, so scripts can use it directly; reach other modules through `WasmModule.getInstance(name, callback)`.
+The element exposes no engine object of its own. A module that loads is instantiated through the engine's `WasmModule` under its `name` (`Basis` goes through the engine's Basis initializer instead). Ammo's glue script defines the global `Ammo`, so scripts can use it directly; reach other modules through `WasmModule.getInstance(name, callback)`. Both depend on the load succeeding, which readiness does not tell you: after a failed load the element is still ready, but `Ammo` stays undefined and `getInstance` never calls its callback. Code that needs a module must handle that outcome — listen for the element's [`error`](#events) event and carry on without the module, running without physics for a failed `Ammo`, rather than wait on `getInstance`.
 
 ## See Also
 
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md
index 68fb2e7fa8a..cd4ee51e27b 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/web-components/tags/pc-wasm.md
@@ -87,7 +87,7 @@ description: "pc-wasm要素のリファレンス: glue・wasm・fallbackのパ
 
 [WasmElement API](https://api.playcanvas.com/web-components/classes/WasmElement.html)を使用して、`<pc-wasm>`要素をプログラムで作成および操作できます。
 
-この要素はエンジンオブジェクトを公開しません。準備が完了した時点で、モジュールは`name`の下でエンジンの`WasmModule`を通じてインスタンス化されています（`Basis`だけはエンジンのBasis初期化処理を通ります）。Ammoのglueスクリプトはグローバルの`Ammo`を定義するため、スクリプトから直接利用できます。その他のモジュールには`WasmModule.getInstance(name, callback)`でアクセスしてください。
+この要素はエンジンオブジェクトを公開しません。読み込みに成功したモジュールは、`name`の下でエンジンの`WasmModule`を通じてインスタンス化されます（`Basis`だけはエンジンのBasis初期化処理を通ります）。Ammoのglueスクリプトはグローバルの`Ammo`を定義するため、スクリプトから直接利用できます。その他のモジュールには`WasmModule.getInstance(name, callback)`でアクセスしてください。どちらも読み込みが成功していることが前提ですが、ready状態からはそれがわかりません。読み込みに失敗しても要素はready状態になりますが、`Ammo`は未定義のままで、`getInstance`はコールバックを決して呼び出しません。モジュールを必要とするコードは、この結果に対処する必要があります。`getInstance`を待ち続けるのではなく、要素の[`error`](#events)イベントをリッスンし、モジュールなしで処理を続けてください。`Ammo`が失敗した場合は、物理なしで動作させます。
 
 ## 関連項目 {#see-also}