@kubohiroya/turbowarp-bubble 0.13.5 → 0.15.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.
package/README.ja.md CHANGED
@@ -1,10 +1,12 @@
1
1
  # TurboWarp Bubble
2
2
 
3
- [English](README.md) | **日本語**
3
+ <img src="assets/block-icon.svg" alt="" width="48" height="48">
4
+
5
+ [English](README.md) | 日本語
4
6
 
5
7
  `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
6
8
 
7
- 現在のリリースはBubble 0.13.5です。既定の描画経路はSVG Text 0.10.1を使うskin非依存のSVG overlayです。TurboWarpですべての機能を使う場合、現在の推奨組み合わせはAsset Cache 0.3.2、Async Input 0.8.1、Runtime Expression 0.6.1です。Asset Cacheへの移行については[0.13.0のリリースノート](docs/release-notes-0.13.0.md)、再利用可能な名前付きclose policyについては[0.10.0のリリースノート](docs/release-notes-0.10.0.md)、組み込み`say`/`think` styleについては[0.9.0のリリースノート](docs/release-notes-0.9.0.md)を参照してください。
9
+ 現在のリリースはBubble 0.15.0です。既定の描画経路はSVG Text 0.12.0を使うskin非依存のSVG overlayです。TurboWarpですべての機能を使う場合、現在の推奨組み合わせはAsset Cache 0.5.0、Async Input 0.10.0、Runtime Expression 0.8.0です。Asset Cacheへの移行については[0.13.0のリリースノート](docs/release-notes-0.13.0.md)、再利用可能な名前付きclose policyについては[0.10.0のリリースノート](docs/release-notes-0.10.0.md)、組み込み`say`/`think` styleについては[0.9.0のリリースノート](docs/release-notes-0.9.0.md)を参照してください。
8
10
 
9
11
  ## READMEの読み方
10
12
 
@@ -71,13 +73,13 @@ flowchart TB
71
73
  extension -."optional".-> input
72
74
  ```
73
75
 
74
- この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.10.1`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。standalone SVG Text 0.10.1が既にロードされている場合は、その公開`getLayoutCapability()`を利用し、project blockで定義済みのfont、色、size、alignmentを維持します。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Cache、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
76
+ この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.12.0`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。standalone SVG Text 0.12.0が既にロードされている場合は、その公開`getLayoutCapability()`を利用し、project blockで定義済みのfont、色、size、alignmentを維持します。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Cache、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
75
77
 
76
78
  ### 描画方式(SVGオーバーレイが既定)
77
79
 
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.10.1のhost-neutral layoutを使います。この既定経路ではBubbleの表示、text更新、style更新、animationのために`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばず、Bubble由来の処理はscratch-renderの`SVGSkin`/`Silhouette`経路へ入りません。`"scratch-render"`は互換性とロールバックのため明示指定時だけ使用します。
80
+ `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.12.0のhost-neutral layoutを使います。この既定経路ではBubbleの表示、text更新、style更新、animationのために`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばず、Bubble由来の処理はscratch-renderの`SVGSkin`/`Silhouette`経路へ入りません。`"scratch-render"`は互換性とロールバックのため明示指定時だけ使用します。
79
81
 
80
- TurboWarpでstock Asset Cache 0.3.2をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetcache.getDOMImageCapability()`を呼び、Asset Cacheブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Cacheを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
82
+ TurboWarpでstock Asset Cache 0.5.0をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetcache.getDOMImageCapability()`を呼び、Asset Cacheブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Cacheを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
81
83
 
82
84
  ```ts
83
85
  import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-cache/composition";
@@ -107,9 +109,9 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
107
109
  });
108
110
  ```
109
111
 
110
- `svgOverlayTextCapability`を省略し、standalone SVG Text 0.10.1がロード済みの場合、Bubbleはfrozenな`getLayoutCapability()`を取得し、SVG Text blockが更新する同じnamed-style registryを解決します。standaloneがない場合だけ、BubbleはSVG Text 0.10.1のlayout compositionを生成し、`default`および初めて参照されたtext-style名を背景透明の既定styleで初期化します。公開handoffがない古いstandaloneが存在する場合はproject styleを黙って置換せず`BUBBLE-RUNTIME-004`を返し、`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけscratch-renderへ戻ります。capabilityを明示注入すると両方の自動経路を置換できます。portrait等を使う場合、Bubble所有の`createAssetManagerSvgOverlayImageCapability()`がAsset Cacheの汎用DOM resourceをBubbleの画像契約へ変換します。依存方向はBubbleからAsset Cacheへの一方向であり、Asset CacheはBubbleの型やsecurity markerを参照しません。adapterは両者が許可するMIME typeだけを公開し、検証済みMIME type、intrinsic size、`blob:` URL、`release()`を引き継ぎ、Asset CacheがsanitizeしたSVGへBubble側のmetadataを付与します。Bubbleは任意SVG文字列を挿入せず、canonical bodyから`path`、`group`等の許可要素・属性だけを`createElementNS()`で再構築します。`script`、event handler、`foreignObject`、外部URLは受け付けません。overlay rootは`pointer-events: none`、`aria-hidden="true"`です。
112
+ `svgOverlayTextCapability`を省略し、standalone SVG Text 0.12.0がロード済みの場合、Bubbleはfrozenな`getLayoutCapability()`を取得し、SVG Text blockが更新する同じnamed-style registryを解決します。standaloneがない場合だけ、BubbleはSVG Text 0.12.0のlayout compositionを生成し、`default`および初めて参照されたtext-style名を背景透明の既定styleで初期化します。公開handoffがない古いstandaloneが存在する場合はproject styleを黙って置換せず`BUBBLE-RUNTIME-004`を返し、`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけscratch-renderへ戻ります。capabilityを明示注入すると両方の自動経路を置換できます。portrait等を使う場合、Bubble所有の`createAssetManagerSvgOverlayImageCapability()`がAsset Cacheの汎用DOM resourceをBubbleの画像契約へ変換します。依存方向はBubbleからAsset Cacheへの一方向であり、Asset CacheはBubbleの型やsecurity markerを参照しません。adapterは両者が許可するMIME typeだけを公開し、検証済みMIME type、intrinsic size、`blob:` URL、`release()`を引き継ぎ、Asset Cacheが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
113
 
112
- 既定文字providerは直接依存するSVG Text 0.10.1です。別にロードしたstock SVG Textのstyleを維持するには0.8.1の`getLayoutCapability()`が必要です。stock画像拡張同士の自動接続には`getDOMImageCapability()`を公開するAsset Cache 0.1.0以降が必要です。Composition APIから`resolveDOMImageResource()`を明示注入する低レベル経路はAsset Cache 0.1.0以降で利用できます。
114
+ 既定文字providerは直接依存するSVG Text 0.12.0です。別にロードしたstock SVG Textのstyleを維持するには0.8.1の`getLayoutCapability()`が必要です。stock画像拡張同士の自動接続には`getDOMImageCapability()`を公開するAsset Cache 0.1.0以降が必要です。Composition APIから`resolveDOMImageResource()`を明示注入する低レベル経路はAsset Cache 0.1.0以降で利用できます。
113
115
 
114
116
  SVG Text/Asset Cacheの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 Cache 0.1.0の公開capabilityも明示注入もない場合は`BUBBLE-RUNTIME-002`を返します。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ、overlay API非対応hostで`scratch-render`へ戻ります。
115
117
 
@@ -124,7 +126,7 @@ SVG Text/Asset Cacheのskin非依存契約は[turbowarp-svg-text#26](https://g
124
126
 
125
127
  stage native size変更ではrootの`viewBox`と全surfaceを更新し、fullscreenとhigh-DPIのCSS scalingはrendererの`scale` overlay modeへ委譲します。stop、project reload、target/clone破棄、composition disposeではlistener、DOM、capability所有resourceを解放し、最後のBubbleが閉じた時点で`removeOverlay(root)`を呼びます。
126
128
 
127
- 自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.10.1 named styleの行座標・角丸、許可属性、object URL解放を検証します。Web/Desktop/Packagerでのvisual parityとframe time/memoryのmanual gateは[SVG overlay release note](docs/release-notes-0.8.0.md)に記録します。
129
+ 自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.12.0 named styleの行座標・角丸、許可属性、object URL解放を検証します。Web/Desktop/Packagerでのvisual parityとframe time/memoryのmanual gateは[SVG overlay release note](docs/release-notes-0.8.0.md)に記録します。
128
130
 
129
131
  ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
130
132
 
@@ -213,7 +215,7 @@ Asset Cacheを音声providerとして接続すると、次の音声を同じ表
213
215
  | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
214
216
  | アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
215
217
 
216
- Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterはstandalone SVG Text 0.10.1があればnamed-style handoffを使い、なければ直接依存するlayout compositionをproviderとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Cacheを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Cacheを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
218
+ Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterはstandalone SVG Text 0.12.0があればnamed-style handoffを使い、なければ直接依存するlayout compositionをproviderとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Cacheを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Cacheを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
217
219
 
218
220
  ### 自動改行と禁則処理の基盤
219
221
 
@@ -292,7 +294,7 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
292
294
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
293
295
  ```
294
296
 
295
- SVG Text 0.10.1は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールは不要です。standalone SVG Text 0.10.1を先に読み込むと、project blockで定義したstyleを公開handoff経由で再利用します。今回のoptional peerはAsset Cache 0.3.2、Async Input 0.8.1、Runtime Expression 0.6.1にそれぞれexact固定します。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身のSVG Text dependencyは0.10.1固定です。Asset Cache 0.1.0はAPI導入履歴の基準であり、今回その旧package版を依存解決に許容する意味ではありません。
297
+ SVG Text 0.12.0は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールは不要です。standalone SVG Text 0.12.0を先に読み込むと、project blockで定義したstyleを公開handoff経由で再利用します。今回のoptional peerはAsset Cache 0.5.0、Async Input 0.10.0、Runtime Expression 0.8.0以降の互換範囲を指定します。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身のSVG Text dependencyは0.12.0以降の互換範囲です。Asset Cache 0.1.0はAPI導入履歴の基準であり、今回その旧package版を依存解決に許容する意味ではありません。
296
298
 
297
299
  `bubbleRenderBackend: "scratch-render"`へrollbackした場合も、standalone SVG Text拡張が未ロードなら同じ0.8.1 dependencyからskin版providerを生成します。standalone SVG Text拡張が既にロードされているhostでは、互換性のためその既存providerを引き続き使用します。
298
300
 
@@ -322,24 +324,24 @@ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget
322
324
 
323
325
  1. 入力待ちの例を使う場合は、TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
324
326
  2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
325
- 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Cache 0.3.2を読み込みます。
326
- 4. `finish [UNIT] ...`にはRuntime Expression 0.6.1、conditionを使う待機またはclose policyにはAsync Input 0.8.1とRuntime Expression 0.6.1を読み込みます。timeoutだけのclose policyにはどちらも不要です。
327
- 5. 最後にBubble 0.13.5を読み込みます。SVG Text 0.10.1のlayout providerはBubble bundleに含まれます。
327
+ 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Cache 0.5.0を読み込みます。
328
+ 4. `finish [UNIT] ...`にはRuntime Expression 0.8.0、conditionを使う待機またはclose policyにはAsync Input 0.10.0とRuntime Expression 0.8.0を読み込みます。timeoutだけのclose policyにはどちらも不要です。
329
+ 5. 最後にBubble 0.15.0を読み込みます。SVG Text 0.12.0のlayout providerはBubble bundleに含まれます。
328
330
 
329
331
  文字だけの最小構成はBubbleです。Temporary Variables、Asset Cache、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になります。
330
332
 
331
333
  ```text
332
334
  # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
333
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.3.2/dist/asset-cache.js
335
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.5.0/dist/asset-cache.js
334
336
 
335
337
  # conditionを使う統合待機またはclose policyでAsync Inputを追加
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.8.1/dist/async-input.js
338
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.10.0/dist/async-input.js
337
339
 
338
340
  # finishまたはconditionを使う待機/close policyでRuntime Expressionを追加
339
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.6.1/dist/runtime-expression.js
341
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.8.0/dist/runtime-expression.js
340
342
 
341
343
  # Bubble(必ず最後)
342
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.13.5/dist/turbowarp-bubble.js
344
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.15.0/dist/turbowarp-bubble.js
343
345
  ```
344
346
 
345
347
  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)を参照してください。
@@ -566,7 +568,7 @@ close this bubble
566
568
 
567
569
  ### Composition API
568
570
 
569
- TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではstandalone SVG Text 0.10.1があればnamed-style handoffを使い、なければ内包layout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Cacheを追加でロードしてください。
571
+ TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではstandalone SVG Text 0.12.0があればnamed-style handoffを使い、なければ内包layout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Cacheを追加でロードしてください。
570
572
 
571
573
  ```ts
572
574
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -744,4 +746,4 @@ pnpm check
744
746
 
745
747
  ## 固定入力の編集
746
748
 
747
- 起動時の `blockEditorDialogs=1&blockEditorFixedInputs=1` でoptional GUI編集を有効にします(既定OFF)。[全ブロックの固定アンカーと保持規則](docs/ja/index.html#fixed-input-editing)を参照してください。Schema正本は `schemas/block-editor-fixed-inputs.schema.json` です。raw値・reporter・既存runtime/composition APIを維持します。共通エディターはGit commit `485f0e550e622235624b5e9176820161aeeba252` に固定したdev/type依存で、製品bundleへruntime importを追加しません。
749
+ 起動時の `blockEditorDialogs=1&blockEditorFixedInputs=1` でoptional GUI編集を有効にします(既定OFF)。[全ブロックの固定アンカーと保持規則](docs/ja/index.html#fixed-input-editing)を参照してください。Schema正本は `schemas/block-editor-fixed-inputs.schema.json` です。raw値・reporter・既存runtime/composition APIを維持します。共通エディターはlockfileでnpm版 `@kubohiroya/turbowarp-extension-data-editor@0.4.0` に固定したdev/type依存で、製品bundleへruntime importを追加しません。
package/README.md CHANGED
@@ -1,10 +1,12 @@
1
1
  # TurboWarp Bubble
2
2
 
3
- **English** | [日本語](README.ja.md)
3
+ <img src="assets/block-icon.svg" alt="" width="48" height="48">
4
+
5
+ English | [日本語](README.ja.md)
4
6
 
5
7
  `@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
8
 
7
- The current release is Bubble 0.13.5. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.10.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Cache 0.3.2, Async Input 0.8.1, and Runtime Expression 0.6.1. See the [0.13.0 release notes](docs/release-notes-0.13.0.md) for the Asset Cache migration, 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.
9
+ The current release is Bubble 0.15.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.12.0. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Cache 0.5.0, Async Input 0.10.0, and Runtime Expression 0.8.0. See the [0.13.0 release notes](docs/release-notes-0.13.0.md) for the Asset Cache migration, 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
10
 
9
11
  ## How to read this README
10
12
 
@@ -71,13 +73,13 @@ flowchart TB
71
73
  extension -."optional".-> input
72
74
  ```
73
75
 
74
- In this architecture, Bubble core refers only to the host-neutral `BubbleTextCapability` contract. By default, the TurboWarp adapter calls `createSvgTextLayoutComposition().layoutText()` from its direct dependency, `@kubohiroya/turbowarp-svg-text@0.10.1`, to obtain line layout and text widths without creating SVG skins. When the standalone SVG Text 0.10.1 extension is already loaded, Bubble instead adapts its public `getLayoutCapability()` so styles defined by project blocks retain their font, color, size, and alignment. The bubble outline, tail, portrait placement, and show and hide animations are outside SVG Text's responsibilities. A Composition API host can inject a different implementation as `textCapability`. Image resolution, audio playback, input, and condition evaluation are also separated into capabilities; Asset Cache, Async Input, and Runtime Expression are connected only when their corresponding features are used.
76
+ In this architecture, Bubble core refers only to the host-neutral `BubbleTextCapability` contract. By default, the TurboWarp adapter calls `createSvgTextLayoutComposition().layoutText()` from its direct dependency, `@kubohiroya/turbowarp-svg-text@0.12.0`, to obtain line layout and text widths without creating SVG skins. When the standalone SVG Text 0.12.0 extension is already loaded, Bubble instead adapts its public `getLayoutCapability()` so styles defined by project blocks retain their font, color, size, and alignment. The bubble outline, tail, portrait placement, and show and hide animations are outside SVG Text's responsibilities. A Composition API host can inject a different implementation as `textCapability`. Image resolution, audio playback, input, and condition evaluation are also separated into capabilities; Asset Cache, Async Input, and Runtime Expression are connected only when their corresponding features are used.
75
77
 
76
78
  ### Rendering backend (SVG overlay by default)
77
79
 
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.10.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.
80
+ 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.12.0 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
81
 
80
- When the stock Asset Cache 0.3.2 extension is loaded before Bubble in TurboWarp, Bubble calls `runtime.ext_kubohiroyaassetcache.getDOMImageCapability()` the first time a portrait or another image feature is used. It then lazily connects to the same registry populated by Asset Cache blocks. Asset Cache is not loaded when only text is used. A Composition API host can inject capabilities explicitly as follows.
82
+ When the stock Asset Cache 0.5.0 extension is loaded before Bubble in TurboWarp, Bubble calls `runtime.ext_kubohiroyaassetcache.getDOMImageCapability()` the first time a portrait or another image feature is used. It then lazily connects to the same registry populated by Asset Cache blocks. Asset Cache is not loaded when only text is used. A Composition API host can inject capabilities explicitly as follows.
81
83
 
82
84
  ```ts
83
85
  import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-cache/composition";
@@ -107,9 +109,9 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
107
109
  });
108
110
  ```
109
111
 
110
- When `svgOverlayTextCapability` is omitted and standalone SVG Text 0.10.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.10.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 Cache DOM resources into Bubble's image contract. The dependency points one way, from Bubble to Asset Cache; Asset Cache 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 Cache. 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"`.
112
+ When `svgOverlayTextCapability` is omitted and standalone SVG Text 0.12.0 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.12.0 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 Cache DOM resources into Bubble's image contract. The dependency points one way, from Bubble to Asset Cache; Asset Cache 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 Cache. 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
113
 
112
- The default text provider is the directly depended-on SVG Text 0.10.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 Cache 0.1.0 or later, which exposes `getDOMImageCapability()`. The lower-level path that explicitly injects `resolveDOMImageResource()` from the Composition API is available with Asset Cache 0.1.0 or later.
114
+ The default text provider is the directly depended-on SVG Text 0.12.0. Preserving styles from a separately loaded stock SVG Text extension requires its 0.8.1 `getLayoutCapability()`. Automatic image connection between stock extensions requires Asset Cache 0.1.0 or later, which exposes `getDOMImageCapability()`. The lower-level path that explicitly injects `resolveDOMImageResource()` from the Composition API is available with Asset Cache 0.1.0 or later.
113
115
 
114
116
  The skin-independent contracts for SVG Text and Asset Cache 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 Cache 0.1.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
117
 
@@ -124,7 +126,7 @@ The skin-independent contracts for SVG Text and Asset Cache are published in [tu
124
126
 
125
127
  When the stage's native size changes, Bubble updates the root `viewBox` and every surface. Fullscreen and high-DPI CSS scaling are delegated to the renderer's `scale` overlay mode. On stop, project reload, target or clone destruction, or composition disposal, Bubble releases listeners, DOM nodes, and capability-owned resources. It calls `removeOverlay(root)` when the last Bubble is closed.
126
128
 
127
- Automated regression tests verify that showing a Bubble, updating text, shaking it, and animating its shape with the default settings create zero Bubble-originated renderer skins or drawables. They also cover native-size updates, the shared root, upstream SVG Text 0.10.1 named-style coordinates and rounded corners, allowed attributes, and object URL release. The manual gates for visual parity and frame-time / memory behavior in Web, Desktop, and Packager are recorded in the [SVG overlay release notes](docs/release-notes-0.8.0.md).
129
+ Automated regression tests verify that showing a Bubble, updating text, shaking it, and animating its shape with the default settings create zero Bubble-originated renderer skins or drawables. They also cover native-size updates, the shared root, upstream SVG Text 0.12.0 named-style coordinates and rounded corners, allowed attributes, and object URL release. The manual gates for visual parity and frame-time / memory behavior in Web, Desktop, and Packager are recorded in the [SVG overlay release notes](docs/release-notes-0.8.0.md).
128
130
 
129
131
  ### Progressive reveal units (CHARACTER / WORD / LINE / BLOCK)
130
132
 
@@ -213,7 +215,7 @@ Per-unit effects play named audio assets; they do not synthesize the displayed s
213
215
  | `@kubohiroya/turbowarp-bubble` | Bubble surfaces, placement, progressive reveal, say / think, expression layers, animation, and input waiting |
214
216
  | Application / host | Convert application-specific input to Composition API calls as needed |
215
217
 
216
- Bubble does not re-export its dependencies. The lower-level Composition API requires `textCapability` as a contract and is not limited to SVG Text. The TurboWarp adapter uses the separately loaded SVG Text 0.10.1 named-style handoff when available, otherwise it creates the directly depended-on layout composition as its provider. Image, audio, input, and condition-evaluation capabilities are replaceable; the TurboWarp adapter connects Asset Cache lazily, while Composition API hosts can implement `imageResolver` and `audio` themselves. Features that use Asset Cache cover external media beyond images, including full voice clips, typewriter sounds, and per-line or per-paragraph effects.
218
+ Bubble does not re-export its dependencies. The lower-level Composition API requires `textCapability` as a contract and is not limited to SVG Text. The TurboWarp adapter uses the separately loaded SVG Text 0.12.0 named-style handoff when available, otherwise it creates the directly depended-on layout composition as its provider. Image, audio, input, and condition-evaluation capabilities are replaceable; the TurboWarp adapter connects Asset Cache lazily, while Composition API hosts can implement `imageResolver` and `audio` themselves. Features that use Asset Cache cover external media beyond images, including full voice clips, typewriter sounds, and per-line or per-paragraph effects.
217
219
 
218
220
  ### Automatic wrapping and line-breaking rules
219
221
 
@@ -292,7 +294,7 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
292
294
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
293
295
  ```
294
296
 
295
- SVG Text 0.10.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.10.1 extension first is optional, but doing so lets Bubble reuse styles defined by its project blocks through the public handoff. This release pins the optional peers exactly to Asset Cache 0.3.2, Async Input 0.8.1, and Runtime Expression 0.6.1. Bubble also pins its SVG Text dependency to 0.10.1 when a host injects a custom `svgOverlayTextCapability`. The historical Asset Cache 0.1.0 capability-introduction baseline does not permit resolving that old package version in this release.
297
+ SVG Text 0.12.0 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.12.0 extension first is optional, but doing so lets Bubble reuse styles defined by its project blocks through the public handoff. This release supports the optional peer ranges starting at Asset Cache 0.5.0, Async Input 0.10.0, and Runtime Expression 0.8.0. Bubble also retains its SVG Text dependency range starting at 0.12.0 when a host injects a custom `svgOverlayTextCapability`. The historical Asset Cache 0.1.0 capability-introduction baseline does not permit resolving that old package version in this release.
296
298
 
297
299
  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.
298
300
 
@@ -322,24 +324,24 @@ TurboWarp Bubble's `dist/turbowarp-bubble.js` is an **unsandboxed custom extensi
322
324
 
323
325
  1. For the input-wait example, open your project in the TurboWarp Editor and add Temporary Variables from the extension library.
324
326
  2. Select “Custom Extension” and enable Run without sandbox.
325
- 3. Load Asset Cache 0.3.2 if you use portraits, blinking, lip-sync, continue frames, or audio.
326
- 4. Load Runtime Expression 0.6.1 for `finish [UNIT] ...`; load both Async Input 0.8.1 and Runtime Expression 0.6.1 for condition-based waits and close policies. A timeout-only close policy needs neither extension.
327
- 5. Load Bubble 0.13.5 last. The SVG Text 0.10.1 layout provider is included in the Bubble bundle.
327
+ 3. Load Asset Cache 0.5.0 if you use portraits, blinking, lip-sync, continue frames, or audio.
328
+ 4. Load Runtime Expression 0.8.0 for `finish [UNIT] ...`; load both Async Input 0.10.0 and Runtime Expression 0.8.0 for condition-based waits and close policies. A timeout-only close policy needs neither extension.
329
+ 5. Load Bubble 0.15.0 last. The SVG Text 0.12.0 layout provider is included in the Bubble bundle.
328
330
 
329
331
  Bubble alone is the minimum configuration for text-only use. Temporary Variables, Asset Cache, 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.
330
332
 
331
333
  ```text
332
334
  # Add only when using portraits, blink, lip-sync, continue, or audio
333
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.3.2/dist/asset-cache.js
335
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.5.0/dist/asset-cache.js
334
336
 
335
337
  # Add Async Input for integrated condition waits and close policies
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.8.1/dist/async-input.js
338
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.10.0/dist/async-input.js
337
339
 
338
340
  # Add Runtime Expression for finish or condition-based waits and close policies
339
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.6.1/dist/runtime-expression.js
341
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.8.0/dist/runtime-expression.js
340
342
 
341
343
  # Bubble (always load last)
342
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.13.5/dist/turbowarp-bubble.js
344
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.15.0/dist/turbowarp-bubble.js
343
345
  ```
344
346
 
345
347
  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.
@@ -566,7 +568,7 @@ Bubble automatically releases its owned timers, overlay DOM, and image leases wh
566
568
 
567
569
  ### Composition API
568
570
 
569
- Hosts that connect to a TurboWarp runtime renderer can use the public adapter. By default, it uses the SVG Text 0.10.1 named-style handoff when a standalone extension is loaded, otherwise its bundled layout composition, together with an SVG overlay. Load Asset Cache in addition only when using image portraits, lip-sync, continue indicators, or audio assets.
571
+ Hosts that connect to a TurboWarp runtime renderer can use the public adapter. By default, it uses the SVG Text 0.12.0 named-style handoff when a standalone extension is loaded, otherwise its bundled layout composition, together with an SVG overlay. Load Asset Cache in addition only when using image portraits, lip-sync, continue indicators, or audio assets.
570
572
 
571
573
  ```ts
572
574
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -744,6 +746,6 @@ pnpm check
744
746
 
745
747
  ## Fixed input editing
746
748
 
747
- The optional GUI capability is enabled only by the startup flags `blockEditorDialogs=1&blockEditorFixedInputs=1` (default OFF). See the [block reference and editing rules](docs/index.html#fixed-input-editing). Canonical property Schemas live in `schemas/block-editor-fixed-inputs.schema.json`; unchanged raw values and reporter inputs are retained. The common editor is a development/type dependency pinned to commit `485f0e550e622235624b5e9176820161aeeba252`; no common runtime import is added to the extension or composition API.
749
+ The optional GUI capability is enabled only by the startup flags `blockEditorDialogs=1&blockEditorFixedInputs=1` (default OFF). See the [block reference and editing rules](docs/index.html#fixed-input-editing). Canonical property Schemas live in `schemas/block-editor-fixed-inputs.schema.json`; unchanged raw values and reporter inputs are retained. The common editor is a development/type dependency resolved to npm version `@kubohiroya/turbowarp-extension-data-editor@0.4.0` in the lockfile; no common runtime import is added to the extension or composition API.
748
750
 
749
751
  Run `BLOCK_EDITOR_GUI_ROOT=/absolute/path/to/scratch-gui pnpm test:fixed-inputs:native` after building for the explicit native Blockly/VM transaction checks. This command requires the real GUI vendor dependencies and fails rather than skips if they are unavailable. It is separate from `pnpm test` and from published Pages verification.
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><path d="M9 8h17a5 5 0 0 1 5 5v7a5 5 0 0 1-5 5H18l-7 5v-5H9a5 5 0 0 1-5-5v-7a5 5 0 0 1 5-5z" fill="#59C059"/><path d="M29 23h10a5 5 0 0 1 5 5v5a5 5 0 0 1-5 5h-6l-6 4v-4a5 5 0 0 1-3-5v-5a5 5 0 0 1 5-5z" fill="#4C97FF"/></svg>
@@ -103,7 +103,8 @@ var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescr
103
103
  description: "Responsive named-style SVG text actors for TurboWarp.",
104
104
  author: "Hiroya Kubo",
105
105
  license: "MPL-2.0",
106
- unsandboxed: !0
106
+ unsandboxed: !0,
107
+ blockIconURI: "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2048%2048%22%3E%3Ctext%20x%3D%2221%22%20y%3D%2238%22%20font-family%3D%22system-ui%2C%20sans-serif%22%20font-size%3D%2230%22%20font-weight%3D%22700%22%20text-anchor%3D%22middle%22%20fill%3D%22%234C97FF%22%3EA%3C%2Ftext%3E%3Cg%20fill%3D%22%2359C059%22%3E%3Ccircle%20cx%3D%2231%22%20cy%3D%2213%22%20r%3D%222.6%22%2F%3E%3Ccircle%20cx%3D%2239%22%20cy%3D%2213%22%20r%3D%222.6%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"
107
108
  }, f = u.$defs, p = "turbowarp-svg-text", m = {
108
109
  repository: p,
109
110
  path: "schemas/block-editor-fixed-inputs.schema.json"
@@ -493,7 +494,7 @@ function H(e) {
493
494
  function U(e) {
494
495
  return String(Math.round(e * 1e3) / 1e3);
495
496
  }
496
- var te = l.blocks, ne = l.menus, re = "https://kubohiroya.github.io/turbowarp-svg-text/", ie = "default", ae = 100, oe = 50, W = 1, se = 1, ce = 1e3, le = 10, ue = 100, de = 0, fe = 100, pe = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2064%2064%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22%23fff%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Cpath%20d%3D%22M13%2023V12h11M40%2012h11v11M13%2041v11h11M40%2052h11V41M22%2023h20M32%2023v23%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E", me = class {
497
+ var te = l.blocks, ne = l.menus, re = "https://kubohiroya.github.io/turbowarp-svg-text/", ie = "default", ae = 100, oe = 50, W = 1, se = 1, ce = 1e3, le = 10, ue = 100, de = 0, fe = 100, pe = d.blockIconURI, me = class {
497
498
  constructor(e = Scratch.vm?.runtime, t = {}) {
498
499
  if (this.styles = /* @__PURE__ */ new Map([[ie, j]]), this.textActors = /* @__PURE__ */ new Map(), !e) throw Error("SVG Text requires the TurboWarp VM.");
499
500
  this.runtime = e, this.castToString = t.castToString ?? Scratch.Cast.toString, (t.listenForRuntimeEvents ?? !0) && this.runtime.on("STAGE_SIZE_CHANGED", () => {