@kubohiroya/turbowarp-bubble 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,7 +4,7 @@
4
4
 
5
5
  `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
6
6
 
7
- 現在のリリースはBubble 0.9.0です。既定の描画経路はSVG Text 0.8.1を使うskin非依存のSVG overlayです。TurboWarpですべての機能を使う場合、現在の推奨組み合わせはAsset Manager 0.12.1、Async Input 0.4.0、Runtime Expression 0.4.0です。組み込み`say`/`think` styleとTurboWarp互換の基本Bubbleについては[0.9.0 release notes](docs/release-notes-0.9.0.md)を参照してください。
7
+ 現在のリリースはBubble 0.11.0です。既定の描画経路はSVG Text 0.8.1を使うskin非依存のSVG overlayです。TurboWarpですべての機能を使う場合、現在の推奨組み合わせはAsset Manager 0.13.0、Async Input 0.5.0、Runtime Expression 0.4.0です。READMEとversion整合検査については[0.11.0 release notes](docs/release-notes-0.11.0.md)、再利用可能な名前付きclose policyについては[0.10.0 release notes](docs/release-notes-0.10.0.md)、組み込み`say`/`think` styleについては[0.9.0 release notes](docs/release-notes-0.9.0.md)を参照してください。
8
8
 
9
9
  ## READMEの読み方
10
10
 
@@ -34,7 +34,7 @@ flowchart LR
34
34
  wait --> close[終了・resource解放]
35
35
  ```
36
36
 
37
- 次の表は0.9.0の機能と公開entry pointの対応です。standalone機能拡張は31定義から29個のpaletteブロックを公開し、保存済みprojectの互換性のため旧styled say/think 2定義を非表示で維持します。表示される全ブロックは[提供ブロック](#提供ブロック)に掲載しています。
37
+ 次の表は0.11.0の機能と公開entry pointの対応です。standalone機能拡張は33定義から31個のpaletteブロックを公開し、保存済みprojectの互換性のため旧styled say/think 2定義を非表示で維持します。表示される全ブロックは[提供ブロック](#提供ブロック)に掲載しています。
38
38
 
39
39
  | 領域 | このREADMEで説明する内容 | 公開entry point |
40
40
  | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
@@ -77,7 +77,7 @@ flowchart TB
77
77
 
78
78
  `bubbleRenderBackend`を省略した場合の既定値は`"svg-overlay"`です。`renderer.addOverlay(root, "scale")`でstage canvas上に共有SVG rootを置き、body、tail、text、portrait、corner clip、continue indicatorをDOM要素として描画します。文字にはstandalone拡張の共有named-style registry、またはBubble内包compositionから得るSVG Text 0.8.1のhost-neutral layoutを使います。この既定経路ではBubbleの表示、text更新、style更新、animationのために`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばず、Bubble由来の処理はscratch-renderの`SVGSkin`/`Silhouette`経路へ入りません。`"scratch-render"`は互換性とロールバックのため明示指定時だけ使用します。
79
79
 
80
- TurboWarpでstock Asset Manager 0.12.1をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()`を呼び、Asset Managerブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Managerを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
80
+ TurboWarpでstock Asset Manager 0.13.0をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()`を呼び、Asset Managerブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Managerを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
81
81
 
82
82
  ```ts
83
83
  import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
@@ -109,9 +109,9 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
109
109
 
110
110
  `svgOverlayTextCapability`を省略し、standalone SVG Text 0.8.1がロード済みの場合、Bubbleはfrozenな`getLayoutCapability()`を取得し、SVG Text blockが更新する同じnamed-style registryを解決します。standaloneがない場合だけ、BubbleはSVG Text 0.8.1のlayout compositionを生成し、`default`および初めて参照されたtext-style名を背景透明の既定styleで初期化します。公開handoffがない古いstandaloneが存在する場合はproject styleを黙って置換せず`BUBBLE-RUNTIME-004`を返し、`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけscratch-renderへ戻ります。capabilityを明示注入すると両方の自動経路を置換できます。portrait等を使う場合、Bubble所有の`createAssetManagerSvgOverlayImageCapability()`がAsset Managerの汎用DOM resourceをBubbleの画像契約へ変換します。依存方向はBubbleからAsset Managerへの一方向であり、Asset ManagerはBubbleの型やsecurity markerを参照しません。adapterは両者が許可するMIME typeだけを公開し、検証済みMIME type、intrinsic size、`blob:` URL、`release()`を引き継ぎ、Asset ManagerがsanitizeしたSVGへBubble側のmetadataを付与します。Bubbleは任意SVG文字列を挿入せず、canonical bodyから`path`、`group`等の許可要素・属性だけを`createElementNS()`で再構築します。`script`、event handler、`foreignObject`、外部URLは受け付けません。overlay rootは`pointer-events: none`、`aria-hidden="true"`です。
111
111
 
112
- 既定文字providerは直接依存するSVG Text 0.8.1です。別にロードしたstock SVG Textのstyleを維持するには0.8.1の`getLayoutCapability()`が必要です。stock画像拡張同士の自動接続には`getDOMImageCapability()`を公開するAsset Manager 0.12.1以降が必要です。Composition APIから`resolveDOMImageResource()`を明示注入する低レベル経路はAsset Manager 0.12.0以降で利用できます。
112
+ 既定文字providerは直接依存するSVG Text 0.8.1です。別にロードしたstock SVG Textのstyleを維持するには0.8.1の`getLayoutCapability()`が必要です。stock画像拡張同士の自動接続には`getDOMImageCapability()`を公開するAsset Manager 0.13.0以降が必要です。Composition APIから`resolveDOMImageResource()`を明示注入する低レベル経路はAsset Manager 0.12.0以降で利用できます。
113
113
 
114
- SVG Text/Asset Managerのskin非依存契約は[turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26)、[turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103)、stock registry handoffの[turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106)で公開済みです。Bubbleは上流の公開APIだけを利用し、private field参照やskinからの抽出では代替しません。overlay APIがないhostで`svg-overlay`を選ぶと`BUBBLE-RUNTIME-004`を返します。画像使用時にAsset Manager 0.12.1の公開capabilityも明示注入もない場合は`BUBBLE-RUNTIME-002`を返します。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ、overlay API非対応hostで`scratch-render`へ戻ります。
114
+ SVG Text/Asset Managerのskin非依存契約は[turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26)、[turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103)、stock registry handoffの[turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106)で公開済みです。Bubbleは上流の公開APIだけを利用し、private field参照やskinからの抽出では代替しません。overlay APIがないhostで`svg-overlay`を選ぶと`BUBBLE-RUNTIME-004`を返します。画像使用時にAsset Manager 0.13.0の公開capabilityも明示注入もない場合は`BUBBLE-RUNTIME-002`を返します。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ、overlay API非対応hostで`scratch-render`へ戻ります。
115
115
 
116
116
  | host/取得方法 | `scratch-render` | `svg-overlay` |
117
117
  | ----------------------------------------- | ---------------- | ------------------------------------------------------ |
@@ -286,7 +286,7 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
286
286
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
287
287
  ```
288
288
 
289
- SVG Text 0.8.1は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールは不要です。standalone SVG Text 0.8.1を先に読み込むことは任意ですが、読み込むとproject blockで定義したstyleを公開handoff経由で再利用します。Bubbleが宣言するoptional peer dependencyの範囲はAsset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`のままです。現在公開中の推奨版はAsset Manager 0.12.1、Async Input 0.4.0、Runtime Expression 0.4.0です。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身が利用するSVG Text dependencyは0.8.1に固定されます。
289
+ SVG Text 0.8.1は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールは不要です。standalone SVG Text 0.8.1を先に読み込むことは任意ですが、読み込むとproject blockで定義したstyleを公開handoff経由で再利用します。Bubbleが宣言するoptional peer dependencyの範囲はAsset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`のままです。現在公開中の推奨版はAsset Manager 0.13.0、Async Input 0.5.0、Runtime Expression 0.4.0です。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身が利用するSVG Text dependencyは0.8.1に固定されます。
290
290
 
291
291
  `bubbleRenderBackend: "scratch-render"`へrollbackした場合も、standalone SVG Text拡張が未ロードなら同じ0.8.1 dependencyからskin版providerを生成します。standalone SVG Text拡張が既にロードされているhostでは、互換性のためその既存providerを引き続き使用します。
292
292
 
@@ -316,24 +316,24 @@ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget
316
316
 
317
317
  1. 入力待ちの例を使う場合は、TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
318
318
  2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
319
- 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Manager 0.12.1を読み込みます。
320
- 4. `finish [UNIT] ...`にはRuntime Expression 0.4.0、`wait with this bubble until condition ...`にはAsync Input 0.4.0とRuntime Expression 0.4.0を読み込みます。
321
- 5. 最後にBubble 0.9.0を読み込みます。SVG Text 0.8.1のlayout providerはBubble bundleに含まれます。
319
+ 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Manager 0.13.0を読み込みます。
320
+ 4. `finish [UNIT] ...`にはRuntime Expression 0.4.0、conditionを使う待機またはclose policyにはAsync Input 0.5.0とRuntime Expression 0.4.0を読み込みます。timeoutだけのclose policyにはどちらも不要です。
321
+ 5. 最後にBubble 0.11.0を読み込みます。SVG Text 0.8.1のlayout providerはBubble bundleに含まれます。
322
322
 
323
323
  文字だけの最小構成はBubbleです。Temporary Variables、Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。Bubbleを読み込むと、基本の`say [MESSAGE]`/`think [MESSAGE]`ブロックはstyle定義なしですぐ使えます。それぞれ組み込みBubble style `say`/`think`を選び、各styleが本体形状とtail/trail形状を不可分な1つの外観として持ちます。どちらも予約text profile `default`を使います。named custom styleが必要な場合だけ`define bubble style`と`show [MESSAGE] with bubble style [STYLE]`を使います。それ以外のnamed text styleや、外形・配置・media・reveal・motionの明示設定はcustom profileになります。
324
324
 
325
325
  ```text
326
326
  # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
327
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
327
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js
328
328
 
329
- # 統合待機ブロックを使う場合はAsync Inputを追加
330
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
329
+ # conditionを使う統合待機またはclose policyでAsync Inputを追加
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.5.0/dist/async-input.js
331
331
 
332
- # finishまたは統合待機ブロックを使う場合はRuntime Expressionを追加
332
+ # finishまたはconditionを使う待機/close policyでRuntime Expressionを追加
333
333
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
334
334
 
335
335
  # Bubble(必ず最後)
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.0/dist/turbowarp-bubble.js
337
337
  ```
338
338
 
339
339
  TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発用URLをunsandboxedとして読み込むには、server originを正確に`http://localhost:8000/`とする必要があります。`127.0.0.1`、`0.0.0.0`、ほかのportにはこの例外が適用されません。リポジトリrootで`python3 -m http.server 8000`を実行し、`http://localhost:8000/dist/turbowarp-bubble.js`を読み込んでください。別の方法として、カスタム拡張機能のfileまたはtext入力を選び、**サンドボックスなしで実行する**を有効にできます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。host制約の詳細は[TurboWarpのunsandboxed拡張機能ドキュメント](https://docs.turbowarp.org/development/extensions/unsandboxed)を参照してください。
@@ -360,6 +360,7 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
360
360
  | ブロック | 動作 |
361
361
  | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
362
362
  | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または置換する |
363
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | 名前付きの終了条件を定義または置換する |
363
364
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
364
365
  | `set portrait base [ASSET] for bubble style [STYLE]` | portraitベースを設定する。空値でportrait全体を解除する |
365
366
  | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | portraitの配置、局所変形、角丸を設定する |
@@ -386,10 +387,25 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
386
387
  | `show [MESSAGE] with bubble style [STYLE]` | 選択styleが持つ本体+tail/trailの組を表示する |
387
388
  | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を選択する |
388
389
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立または任意timeoutまで待つ |
390
+ | `wait and close this bubble using close policy [POLICY]` | policyをsnapshotし、成立を待ってBubbleを閉じる |
389
391
  | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
390
392
  | `Bubble version` | 実装versionを返す |
391
393
 
392
- `ASSETS`はAsset Managerへ登録済みの名前をカンマ区切りで指定します。前後の空白は除去され、名前自体にカンマは使用できません。目パチと口パクは1フレーム以上、continue indicatorは2フレーム以上が必要で、空リストにすると設定を解除します。frame間隔は0より大きい有限値です。逐次表示間隔、animation時間、timeoutには0も指定でき、逐次表示間隔の0は自動送りを、timeoutの0は時間制限を無効にします。
394
+ Bubble close policyは制御フローの設定であり、見た目を表すBubble styleではありません。`condition`は時間制限なしで条件を待ち、`timeout`は正の秒数後に閉じ、`condition-or-timeout`は先に成立した方で閉じます。conditionは空にできず、有効なtimeoutは0より大きい値にします。
395
+
396
+ ```text
397
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
398
+ say [3秒後に閉じます。]
399
+ wait and close this bubble using close policy [three-seconds]
400
+
401
+ define bubble close policy [advance] trigger [condition] condition [input == "pressed"] timeout [0] seconds
402
+ say [キーを押すかspriteをタッチしてください。]
403
+ wait and close this bubble using close policy [advance]
404
+ ```
405
+
406
+ 適用ブロックは開始時に名前付き定義をsnapshotします。待機中に同名policyを置換しても、その変更は次回の適用から有効です。timeoutだけのpolicyは現在のanimation modeを維持し、入力用拡張を必要としません。conditionを含むpolicyは`awaiting-continue`へ移り、既存の内蔵待機と同じくAsync InputとRuntime Expressionを使います。成立後は設定済みhide animationを実行してBubbleを解放します。Bubbleの置換、targetやprojectの停止、runtime破棄では待機中policyをcancelし、置換後のBubbleを閉じません。
407
+
408
+ `ASSETS`はAsset Managerへ登録済みの名前をカンマ区切りで指定します。前後の空白は除去され、名前自体にカンマは使用できません。目パチと口パクは1フレーム以上、continue indicatorは2フレーム以上が必要で、空リストにすると設定を解除します。frame間隔は0より大きい有限値です。逐次表示間隔、animation時間、従来のwait timeoutには0も指定でき、逐次表示間隔の0は自動送りを、従来のtimeoutの0は時間制限を無効にします。close policyで明示的に選ぶtimeoutは0より大きい値にします。
393
409
 
394
410
  Bubbleには2つの組み込みBubble styleがあります。`say`はspeech本体とspeech tail、`think`はthought本体とround trailを持ち、本体とtail/trailは個別指定ではなく1つのvisual styleとして選びます。対応する短いブロックが各styleを自動選択するため、style定義ブロックもstyle入力も不要です。どちらも予約text profile `default`を使い、14px Helvetica、line height 16px、最大行幅170px、最小文字領域幅50px、padding 10px、corner radius 16px、白い本体、Scratch標準の文字色・border色で描画します。SVGの4px strokeを先に描き、その内側半分を白いfillで覆うことで、TurboWarp標準と同じ細い見かけの輪郭にします。Actor右側を優先し、右に収まらず左に収まる場合だけ反転します。Actor boundsへの追従、Stage上端・左右端のfence、数値block入力の整形、330文字上限、空文字でのcloseも標準`say`/`think`に揃えます。
395
411
 
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # TurboWarp Bubble
2
2
 
3
- **English** | [日本語](README_ja.md)
3
+ **English** | [日本語](README.ja.md)
4
4
 
5
5
  `@kubohiroya/turbowarp-bubble` is an unsandboxed extension that manages TurboWarp `say` and `think` displays as separate text, character-expression, and input-waiting indicator layers. It also provides a composition API for using the same features directly from applications.
6
6
 
7
- The current release is Bubble 0.9.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.8.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. See the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles and TurboWarp-compatible basic bubbles.
7
+ The current release is Bubble 0.11.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.8.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Manager 0.13.0, Async Input 0.5.0, and Runtime Expression 0.4.0. See the [0.11.0 release notes](docs/release-notes-0.11.0.md) for README and version consistency checks, the [0.10.0 release notes](docs/release-notes-0.10.0.md) for reusable named close policies, and the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles.
8
8
 
9
9
  ## How to read this README
10
10
 
@@ -34,7 +34,7 @@ flowchart LR
34
34
  wait --> close[Close and release resources]
35
35
  ```
36
36
 
37
- The table below maps the 0.9.0 feature set to its public entry points. The standalone extension exposes 29 palette blocks generated from 31 definitions; two hidden legacy definitions keep previously saved styled say/think blocks working. The full visible list appears under [Available blocks](#available-blocks).
37
+ The table below maps the 0.11.0 feature set to its public entry points. The standalone extension exposes 31 palette blocks generated from 33 definitions; two hidden legacy definitions keep previously saved styled say/think blocks working. The full visible list appears under [Available blocks](#available-blocks).
38
38
 
39
39
  | Area | What this README covers | Public entry points |
40
40
  | --------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
@@ -77,7 +77,7 @@ In this architecture, Bubble core refers only to the host-neutral `BubbleTextCap
77
77
 
78
78
  The default value of `bubbleRenderBackend` is `"svg-overlay"`. Bubble places a shared SVG root over the stage canvas with `renderer.addOverlay(root, "scale")`, then renders the body, tail, text, portrait, corner clip, and continue indicator as DOM elements. Text uses host-neutral SVG Text 0.8.1 layout data, either from the loaded standalone extension's shared named-style registry or from Bubble's bundled fallback composition. On this default path, Bubble does not call `createDrawable()`, `createSVGSkin()`, or `createBitmapSkin()` to show bubbles, update text or styles, or run animations, so Bubble-originated work never enters scratch-render's `SVGSkin` / `Silhouette` path. `"scratch-render"` is used only when explicitly selected for compatibility or rollback.
79
79
 
80
- When the stock Asset Manager 0.12.1 extension is loaded before Bubble in TurboWarp, Bubble calls `runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()` the first time a portrait or another image feature is used. It then lazily connects to the same registry populated by Asset Manager blocks. Asset Manager is not loaded when only text is used. A Composition API host can inject capabilities explicitly as follows.
80
+ When the stock Asset Manager 0.13.0 extension is loaded before Bubble in TurboWarp, Bubble calls `runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()` the first time a portrait or another image feature is used. It then lazily connects to the same registry populated by Asset Manager blocks. Asset Manager is not loaded when only text is used. A Composition API host can inject capabilities explicitly as follows.
81
81
 
82
82
  ```ts
83
83
  import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
@@ -109,9 +109,9 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
109
109
 
110
110
  When `svgOverlayTextCapability` is omitted and standalone SVG Text 0.8.1 is loaded, Bubble obtains its frozen `getLayoutCapability()` and resolves the exact named-style registry populated by SVG Text blocks. If standalone SVG Text is absent, Bubble creates its own SVG Text 0.8.1 layout composition and initializes `default` and each first-referenced text-style name with transparent-background defaults. If an older standalone extension is present without the public handoff, Bubble reports `BUBBLE-RUNTIME-004` instead of silently replacing project styles; explicit `svgOverlayUnsupportedBehavior: "fallback"` selects scratch-render. Supplying a capability directly overrides both automatic paths. For portraits and similar features, Bubble's `createAssetManagerSvgOverlayImageCapability()` converts generic Asset Manager DOM resources into Bubble's image contract. The dependency points one way, from Bubble to Asset Manager; Asset Manager does not refer to Bubble types or security markers. The adapter exposes only MIME types allowed by both packages, carries across the validated MIME type, intrinsic size, `blob:` URL, and `release()`, and adds Bubble metadata to sanitized SVG from Asset Manager. Bubble never inserts arbitrary SVG strings. It reconstructs only allowed elements and attributes, such as `path` and `group`, from the canonical body by using `createElementNS()`. It rejects `script`, event handlers, `foreignObject`, and external URLs. The overlay root uses `pointer-events: none` and `aria-hidden="true"`.
111
111
 
112
- The default text provider is the directly depended-on SVG Text 0.8.1. Preserving styles from a separately loaded stock SVG Text extension requires its 0.8.1 `getLayoutCapability()`. Automatic image connection between stock extensions requires Asset Manager 0.12.1 or later, which exposes `getDOMImageCapability()`. The lower-level path that explicitly injects `resolveDOMImageResource()` from the Composition API is available with Asset Manager 0.12.0 or later.
112
+ The default text provider is the directly depended-on SVG Text 0.8.1. Preserving styles from a separately loaded stock SVG Text extension requires its 0.8.1 `getLayoutCapability()`. Automatic image connection between stock extensions requires Asset Manager 0.13.0 or later, which exposes `getDOMImageCapability()`. The lower-level path that explicitly injects `resolveDOMImageResource()` from the Composition API is available with Asset Manager 0.12.0 or later.
113
113
 
114
- The skin-independent contracts for SVG Text and Asset Manager are published in [turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26), [turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103), and the stock registry handoff in [turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106). Bubble uses only public upstream APIs and never substitutes private-field access or extraction from skins. Selecting `svg-overlay` on a host without the overlay API returns `BUBBLE-RUNTIME-004`. Using images without either Asset Manager 0.12.1's public capability or an explicitly injected capability returns `BUBBLE-RUNTIME-002`. Bubble falls back to `scratch-render` on a host without the overlay API only when `svgOverlayUnsupportedBehavior: "fallback"` is explicitly specified.
114
+ The skin-independent contracts for SVG Text and Asset Manager are published in [turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26), [turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103), and the stock registry handoff in [turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106). Bubble uses only public upstream APIs and never substitutes private-field access or extraction from skins. Selecting `svg-overlay` on a host without the overlay API returns `BUBBLE-RUNTIME-004`. Using images without either Asset Manager 0.13.0's public capability or an explicitly injected capability returns `BUBBLE-RUNTIME-002`. Bubble falls back to `scratch-render` on a host without the overlay API only when `svgOverlayUnsupportedBehavior: "fallback"` is explicitly specified.
115
115
 
116
116
  | Host / capture method | `scratch-render` | `svg-overlay` |
117
117
  | ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------- |
@@ -286,7 +286,7 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
286
286
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
287
287
  ```
288
288
 
289
- SVG Text 0.8.1 is included as a regular dependency and serves as the default skin-independent text provider. You do not need to install it separately. Loading the standalone SVG Text 0.8.1 extension first is optional, but doing so lets Bubble reuse styles defined by its project blocks through the public handoff. Bubble's declared optional peer ranges remain `>=0.7.0 <1` for Asset Manager and `>=0.3.0 <1` for both Async Input and Runtime Expression; the currently published and recommended extension versions are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. Even when a host injects a custom `svgOverlayTextCapability`, Bubble's own SVG Text dependency remains fixed at version 0.8.1.
289
+ SVG Text 0.8.1 is included as a regular dependency and serves as the default skin-independent text provider. You do not need to install it separately. Loading the standalone SVG Text 0.8.1 extension first is optional, but doing so lets Bubble reuse styles defined by its project blocks through the public handoff. Bubble's declared optional peer ranges remain `>=0.7.0 <1` for Asset Manager and `>=0.3.0 <1` for both Async Input and Runtime Expression; the currently published and recommended extension versions are Asset Manager 0.13.0, Async Input 0.5.0, and Runtime Expression 0.4.0. Even when a host injects a custom `svgOverlayTextCapability`, Bubble's own SVG Text dependency remains fixed at version 0.8.1.
290
290
 
291
291
  After rolling back to `bubbleRenderBackend: "scratch-render"`, Bubble creates a skin-based provider from the same 0.8.1 dependency if the standalone SVG Text extension is not loaded. On a host where the standalone SVG Text extension is already loaded, Bubble continues using that existing provider for compatibility.
292
292
 
@@ -316,24 +316,24 @@ TurboWarp Bubble's `dist/turbowarp-bubble.js` is an **unsandboxed custom extensi
316
316
 
317
317
  1. For the input-wait example, open your project in the TurboWarp Editor and add Temporary Variables from the extension library.
318
318
  2. Select “Custom Extension” and enable Run without sandbox.
319
- 3. Load Asset Manager 0.12.1 if you use portraits, blinking, lip-sync, continue frames, or audio.
320
- 4. Load Runtime Expression 0.4.0 for `finish [UNIT] ...`; load both Async Input 0.4.0 and Runtime Expression 0.4.0 for `wait with this bubble until condition ...`.
321
- 5. Load Bubble 0.9.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
319
+ 3. Load Asset Manager 0.13.0 if you use portraits, blinking, lip-sync, continue frames, or audio.
320
+ 4. Load Runtime Expression 0.4.0 for `finish [UNIT] ...`; load both Async Input 0.5.0 and Runtime Expression 0.4.0 for condition-based waits and close policies. A timeout-only close policy needs neither extension.
321
+ 5. Load Bubble 0.11.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
322
322
 
323
323
  Bubble alone is the minimum configuration for text-only use. Temporary Variables, Asset Manager, Async Input, and Runtime Expression can be omitted when you do not use the features they support. After loading Bubble, its basic `say [MESSAGE]` and `think [MESSAGE]` blocks work immediately without a style definition. They select the built-in Bubble styles `say` and `think`, respectively. Each style binds its body shape and tail/trail shape as one visual choice, and both use the reserved text profile `default`. Use `define bubble style` and `show [MESSAGE] with bubble style [STYLE]` only when you need a named custom style. Other named text styles and every explicit body, placement, media, reveal, or motion setting select the custom profile.
324
324
 
325
325
  ```text
326
326
  # Add only when using portraits, blink, lip-sync, continue, or audio
327
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
327
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js
328
328
 
329
- # Add Async Input for the integrated wait block
330
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
329
+ # Add Async Input for integrated condition waits and close policies
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.5.0/dist/async-input.js
331
331
 
332
- # Add Runtime Expression for finish or the integrated wait block
332
+ # Add Runtime Expression for finish or condition-based waits and close policies
333
333
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
334
334
 
335
335
  # Bubble (always load last)
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.0/dist/turbowarp-bubble.js
337
337
  ```
338
338
 
339
339
  TurboWarp custom extensions load JavaScript from URLs, so a network connection is required the first time they are loaded. For an unsandboxed development URL, TurboWarp requires the server origin to be exactly `http://localhost:8000/`; `127.0.0.1`, `0.0.0.0`, and other ports do not receive this exception. From the repository root, run `python3 -m http.server 8000`, then load `http://localhost:8000/dist/turbowarp-bubble.js`. Alternatively, choose the custom-extension file or text input and enable **Run extension without sandbox**. The extension does not work when opened directly with `file://` or when run as a sandboxed extension. See [TurboWarp's unsandboxed extension documentation](https://docs.turbowarp.org/development/extensions/unsandboxed) for the host restrictions.
@@ -360,6 +360,7 @@ Bubble owns a display for each calling sprite, clone, or Stage. With the default
360
360
  | Block | Behavior |
361
361
  | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
362
362
  | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Defines or replaces a Bubble style |
363
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | Defines or replaces a named closing condition |
363
364
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Sets an Actor-relative direction/angle or background-relative region |
364
365
  | `set portrait base [ASSET] for bubble style [STYLE]` | Sets the portrait base; an empty value removes the entire portrait |
365
366
  | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | Sets portrait placement, local transform, and rounded corners |
@@ -386,10 +387,25 @@ Bubble owns a display for each calling sprite, clone, or Stage. With the default
386
387
  | `show [MESSAGE] with bubble style [STYLE]` | Shows the body and tail/trail pair owned by the selected style |
387
388
  | `set this bubble animation mode [MODE]` | Selects `talking`, `awaiting-continue`, or `idle` |
388
389
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Waits for a Runtime Expression condition or optional timeout |
390
+ | `wait and close this bubble using close policy [POLICY]` | Snapshots a policy, waits for it, and closes the Bubble |
389
391
  | `close this bubble` | Releases this target's Bubble and owned resources |
390
392
  | `Bubble version` | Returns the implementation version |
391
393
 
392
- `ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and timeouts accept zero; a zero reveal interval disables automatic advance, while a zero timeout disables the time limit.
394
+ A Bubble close policy is control-flow configuration, not a visual Bubble style. `condition` waits without a time limit, `timeout` closes after a positive number of seconds, and `condition-or-timeout` closes when either trigger happens first. A condition must be non-empty, and an enabled timeout must be greater than zero.
395
+
396
+ ```text
397
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
398
+ say [This closes after three seconds.]
399
+ wait and close this bubble using close policy [three-seconds]
400
+
401
+ define bubble close policy [advance] trigger [condition] condition [input == "pressed"] timeout [0] seconds
402
+ say [Press a key or touch the sprite.]
403
+ wait and close this bubble using close policy [advance]
404
+ ```
405
+
406
+ The apply block snapshots the named definition when it starts. Replacing the same policy while it is waiting therefore affects only later applications. Timeout-only policies leave the Bubble in its current animation mode and require no input extension. Policies with a condition enter `awaiting-continue` and use Async Input plus Runtime Expression in the same way as the integrated wait block. Completion runs the configured hide animation and releases the Bubble. Replacing the Bubble, stopping its target or the project, or disposing the runtime cancels the pending policy without closing a replacement Bubble.
407
+
408
+ `ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and the legacy wait timeout accept zero; a zero reveal interval disables automatic advance, while a zero legacy timeout disables the time limit. A timeout selected explicitly by a close policy must be greater than zero.
393
409
 
394
410
  Bubble provides two built-in Bubble styles. `say` owns the speech body and speech tail; `think` owns the thought body and round trail. The body and tail/trail are one visual-style choice rather than independently selected properties. The matching short block selects each style automatically, so neither a style-definition block nor a style input is required. Both styles use the reserved text profile `default`: 14px Helvetica, 16px line height, a 170px maximum line width, 50px minimum text width, 10px padding, 16px corners, a white fill, and Scratch text/stroke colors. The 4px SVG stroke is painted before the white fill, which covers its inner half and leaves the same thin visible outline as TurboWarp's standard bubble. The profile starts on the Actor's right, flips to the left only when that side fits, follows Actor bounds, fences the Stage top and sides, formats numeric block inputs like Scratch, limits text to 330 characters, and closes on an empty block input.
395
411
 
@@ -37,6 +37,29 @@
37
37
  "blockType": "COMMAND",
38
38
  "arguments": []
39
39
  },
40
+ {
41
+ "opcode": "defineBubbleClosePolicy",
42
+ "blockType": "COMMAND",
43
+ "arguments": [
44
+ {
45
+ "id": "CONDITION",
46
+ "type": "STRING"
47
+ },
48
+ {
49
+ "id": "POLICY",
50
+ "type": "STRING"
51
+ },
52
+ {
53
+ "id": "TIMEOUT",
54
+ "type": "NUMBER"
55
+ },
56
+ {
57
+ "id": "TRIGGER",
58
+ "type": "STRING",
59
+ "menu": "closePolicyTrigger"
60
+ }
61
+ ]
62
+ },
40
63
  {
41
64
  "opcode": "defineBubbleStyle",
42
65
  "blockType": "COMMAND",
@@ -474,6 +497,16 @@
474
497
  }
475
498
  ]
476
499
  },
500
+ {
501
+ "opcode": "waitAndCloseBubbleWithPolicy",
502
+ "blockType": "COMMAND",
503
+ "arguments": [
504
+ {
505
+ "id": "POLICY",
506
+ "type": "STRING"
507
+ }
508
+ ]
509
+ },
477
510
  {
478
511
  "opcode": "waitForBubbleContinue",
479
512
  "blockType": "COMMAND",
@@ -498,6 +531,10 @@
498
531
  "id": "boolean",
499
532
  "acceptReporters": true
500
533
  },
534
+ {
535
+ "id": "closePolicyTrigger",
536
+ "acceptReporters": true
537
+ },
501
538
  {
502
539
  "id": "ease",
503
540
  "acceptReporters": true
@@ -5610,7 +5610,7 @@ function Fa(e) {
5610
5610
  return typeof e == "object" && !!e && !Array.isArray(e);
5611
5611
  }
5612
5612
  function Ia(e) {
5613
- if (!Fa(e) || typeof e.setText != "function" || typeof e.releaseTextActor != "function") throw TypeError("TurboWarp SVG Text adapter requires setText and releaseTextActor.");
5613
+ if (!Fa(e) || typeof e.setText != "function" || typeof e.releaseTextActor != "function") throw TypeError("TurboWarp-SVG-Text adapter requires setText and releaseTextActor.");
5614
5614
  return e;
5615
5615
  }
5616
5616
  function La(e) {
@@ -5665,7 +5665,7 @@ function Va(e) {
5665
5665
  t.releaseTextActor(e);
5666
5666
  },
5667
5667
  measureText({ styleName: e, text: n }) {
5668
- if (typeof t.measureText != "function") throw Error("TurboWarp SVG Text does not provide text measurement.");
5668
+ if (typeof t.measureText != "function") throw Error("TurboWarp-SVG-Text does not provide text measurement.");
5669
5669
  return t.measureText(e, n);
5670
5670
  }
5671
5671
  });
@@ -5709,7 +5709,7 @@ function Ua(e) {
5709
5709
  });
5710
5710
  }
5711
5711
  function Wa(e) {
5712
- if (!Fa(e) || typeof e.getLayoutCapability != "function") throw TypeError("TurboWarp SVG Text overlay adapter requires SVG Text 0.8.1 getLayoutCapability().");
5712
+ if (!Fa(e) || typeof e.getLayoutCapability != "function") throw TypeError("TurboWarp-SVG-Text overlay adapter requires SVG Text 0.8.1 getLayoutCapability().");
5713
5713
  return Ua(e.getLayoutCapability());
5714
5714
  }
5715
5715
  //#endregion
@@ -6930,7 +6930,7 @@ function ss(e, t = {}) {
6930
6930
  },
6931
6931
  async playSound(e, t = {}) {
6932
6932
  let n = f(), r = t.untilDone ? n?.playSoundUntilDone : n?.playSound;
6933
- if (typeof r != "function") throw new $("BUBBLE-RUNTIME-002", "TurboWarp Asset Manager does not provide audio playback.");
6933
+ if (typeof r != "function") throw new $("BUBBLE-RUNTIME-002", "TurboWarp-Asset-Manager does not provide audio playback.");
6934
6934
  await r.call(n, { NAME: e });
6935
6935
  }
6936
6936
  }, v = u === "svg-overlay" ? Do(r, c) : void 0;