@kubohiroya/turbowarp-bubble 0.11.0 → 0.13.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
@@ -4,7 +4,7 @@
4
4
 
5
5
  `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
6
6
 
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)を参照してください。
7
+ 現在のリリースはBubble 0.13.0です。既定の描画経路はSVG Text 0.10.0を使うskin非依存のSVG overlayです。TurboWarpですべての機能を使う場合、現在の推奨組み合わせはAsset Cache 0.1.0、Async Input 0.7.0、Runtime Expression 0.6.0です。Asset Cacheへの移行については[0.13.0 release notes](docs/release-notes-0.13.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
 
@@ -36,14 +36,14 @@ flowchart LR
36
36
 
37
37
  次の表は0.11.0の機能と公開entry pointの対応です。standalone機能拡張は33定義から31個のpaletteブロックを公開し、保存済みprojectの互換性のため旧styled say/think 2定義を非表示で維持します。表示される全ブロックは[提供ブロック](#提供ブロック)に掲載しています。
38
38
 
39
- | 領域 | このREADMEで説明する内容 | 公開entry point |
40
- | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
41
- | 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | `composition`、`turbowarp-adapter`、機能拡張ブロック |
42
- | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | `composition`、軽量な`reveal` entry、機能拡張ブロック |
43
- | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | Asset Managerを介したComposition APIと機能拡張ブロック |
44
- | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | Composition API、TurboWarp adapter、機能拡張ブロック |
45
- | 表示mode | `talking`/`awaiting-continue`/`idle` | `BubbleHandle.setAnimationMode()`と対応ブロック |
46
- | 表示開始・表示中・表示終了animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | style設定、`BubbleHandle.animate()`、機能拡張ブロック |
39
+ | 領域 | このREADMEで説明する内容 | 公開entry point |
40
+ | ----------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------- |
41
+ | 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | `composition`、`turbowarp-adapter`、機能拡張ブロック |
42
+ | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | `composition`、軽量な`reveal` entry、機能拡張ブロック |
43
+ | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | Asset Cacheを介したComposition APIと機能拡張ブロック |
44
+ | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | Composition API、TurboWarp adapter、機能拡張ブロック |
45
+ | 表示mode | `talking`/`awaiting-continue`/`idle` | `BubbleHandle.setAnimationMode()`と対応ブロック |
46
+ | 表示開始・表示中・表示終了animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | style設定、`BubbleHandle.animate()`、機能拡張ブロック |
47
47
 
48
48
  ## 概念と表示仕様
49
49
 
@@ -56,7 +56,7 @@ flowchart TB
56
56
  core["Bubble core\n外形・配置・ライフサイクル・animation state"]
57
57
  contract["BubbleTextCapability\nhost-neutralな文字契約"]
58
58
  twAdapter["TurboWarp Bubble adapter\nrenderer / runtime / targetへの接続"]
59
- svgAdapter["SVG Text 0.8 layout adapter\nrenderer非依存の行layout・計測"]
59
+ svgAdapter["SVG Text 0.10 layout adapter\nrenderer非依存の行layout・計測"]
60
60
  assets["任意のImage / Audio capability\nportrait・lip-sync・音声"]
61
61
  input["任意のInput / Expression capability\n入力・待機条件"]
62
62
  host["独自Webアプリ / host"]
@@ -71,16 +71,16 @@ flowchart TB
71
71
  extension -."optional".-> input
72
72
  ```
73
73
 
74
- この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.8.1`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。standalone SVG Text 0.8.1が既にロードされている場合は、その公開`getLayoutCapability()`を利用し、project blockで定義済みのfont、色、size、alignmentを維持します。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
74
+ この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.10.0`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。standalone SVG Text 0.10.0が既にロードされている場合は、その公開`getLayoutCapability()`を利用し、project blockで定義済みのfont、色、size、alignmentを維持します。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Cache、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
75
75
 
76
76
  ### 描画backend(SVG overlayが既定)
77
77
 
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"`は互換性とロールバックのため明示指定時だけ使用します。
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.0の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.13.0をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()`を呼び、Asset Managerブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Managerを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
80
+ TurboWarpでstock Asset Cache 0.1.0をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetcache.getDOMImageCapability()`を呼び、Asset Cacheブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Cacheを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
81
81
 
82
82
  ```ts
83
- import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
83
+ import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-cache/composition";
84
84
  import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
85
85
  import {
86
86
  createAssetManagerSvgOverlayImageCapability,
@@ -107,11 +107,11 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
107
107
  });
108
108
  ```
109
109
 
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"`です。
110
+ `svgOverlayTextCapability`を省略し、standalone SVG Text 0.10.0がロード済みの場合、Bubbleはfrozenな`getLayoutCapability()`を取得し、SVG Text blockが更新する同じnamed-style registryを解決します。standaloneがない場合だけ、BubbleはSVG Text 0.10.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
111
 
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以降で利用できます。
112
+ 既定文字providerは直接依存するSVG Text 0.10.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
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.13.0の公開capabilityも明示注入もない場合は`BUBBLE-RUNTIME-002`を返します。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ、overlay API非対応hostで`scratch-render`へ戻ります。
114
+ 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
115
 
116
116
  | host/取得方法 | `scratch-render` | `svg-overlay` |
117
117
  | ----------------------------------------- | ---------------- | ------------------------------------------------------ |
@@ -124,7 +124,7 @@ SVG Text/Asset Managerのskin非依存契約は[turbowarp-svg-text#26](https:/
124
124
 
125
125
  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
126
 
127
- 自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.8.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)に記録します。
127
+ 自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.10.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
128
 
129
129
  ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
130
130
 
@@ -193,7 +193,7 @@ finish [CHARACTER / WORD / LINE / BLOCK]
193
193
 
194
194
  `finish`は公開Composition APIの`handle.finish({ unit, condition, timeoutSeconds })`と、TurboWarpの`finish [UNIT] ...`ブロックで利用できます。これは逐次表示を最後まで進め、条件成立またはtimeoutで音声と待機状態を確定します。
195
195
 
196
- Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
196
+ Asset Cacheを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
197
197
 
198
198
  - 表示開始時のフルボイス
199
199
  - `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
@@ -205,7 +205,7 @@ Asset Managerを音声providerとして接続すると、次の音声を同じ
205
205
 
206
206
  | パッケージ | 責務 |
207
207
  | ------------------------------------------ | ------------------------------------------------------------------------------ |
208
- | `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
208
+ | `@kubohiroya/turbowarp-asset-cache` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
209
209
  | Bubble core(`composition`) | `BubbleTextCapability`契約、吹き出しsurface、配置、逐次表示、animation |
210
210
  | `@kubohiroya/turbowarp-svg-text` | 0.8.1のhost-neutralなplain/ruby layout、stock named-style handoff、文字幅計測 |
211
211
  | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
@@ -213,7 +213,7 @@ Asset Managerを音声providerとして接続すると、次の音声を同じ
213
213
  | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
214
214
  | アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
215
215
 
216
- Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterはstandalone SVG Text 0.8.1があればnamed-style handoffを使い、なければ直接依存するlayout compositionをproviderとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Managerを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
216
+ Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterはstandalone SVG Text 0.10.0があればnamed-style handoffを使い、なければ直接依存するlayout compositionをproviderとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Cacheを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Cacheを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
217
217
 
218
218
  ### 自動改行と禁則処理の基盤
219
219
 
@@ -286,20 +286,20 @@ 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.13.0、Async Input 0.5.0、Runtime Expression 0.4.0です。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身が利用するSVG Text dependencyは0.8.1に固定されます。
289
+ SVG Text 0.10.0は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールは不要です。standalone SVG Text 0.10.0を先に読み込むことは任意ですが、読み込むとproject blockで定義したstyleを公開handoff経由で再利用します。Bubbleが宣言するoptional peer dependencyの範囲はAsset Cacheが`>=0.1.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`のままです。現在公開中の推奨版はAsset Cache 0.1.0、Async Input 0.7.0、Runtime Expression 0.6.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
 
293
- 画像portrait、lip-sync、continue indicator、または音声アセットを使う場合はAsset Managerを追加します。`finish [UNIT] ...`ブロックにはRuntime Expressionが必要です。統合待機ブロック`wait with this bubble ...`にはAsync InputとRuntime Expressionの両方が必要です。
293
+ 画像portrait、lip-sync、continue indicator、または音声アセットを使う場合はAsset Cacheを追加します。`finish [UNIT] ...`ブロックにはRuntime Expressionが必要です。統合待機ブロック`wait with this bubble ...`にはAsync InputとRuntime Expressionの両方が必要です。
294
294
 
295
295
  ```sh
296
- pnpm add @kubohiroya/turbowarp-asset-manager \
296
+ pnpm add @kubohiroya/turbowarp-asset-cache \
297
297
  @kubohiroya/turbowarp-async-input \
298
298
  @kubohiroya/turbowarp-runtime-expression
299
299
  ```
300
300
 
301
301
  ```sh
302
- npm install @kubohiroya/turbowarp-asset-manager \
302
+ npm install @kubohiroya/turbowarp-asset-cache \
303
303
  @kubohiroya/turbowarp-async-input \
304
304
  @kubohiroya/turbowarp-runtime-expression
305
305
  ```
@@ -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.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に含まれます。
319
+ 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Cache 0.1.0を読み込みます。
320
+ 4. `finish [UNIT] ...`にはRuntime Expression 0.6.0、conditionを使う待機またはclose policyにはAsync Input 0.7.0とRuntime Expression 0.6.0を読み込みます。timeoutだけのclose policyにはどちらも不要です。
321
+ 5. 最後にBubble 0.13.0を読み込みます。SVG Text 0.10.0のlayout providerはBubble bundleに含まれます。
322
322
 
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になります。
323
+ 文字だけの最小構成は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になります。
324
324
 
325
325
  ```text
326
326
  # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
327
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js
327
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.1.0/dist/asset-cache.js
328
328
 
329
329
  # conditionを使う統合待機またはclose policyでAsync Inputを追加
330
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.5.0/dist/async-input.js
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.7.0/dist/async-input.js
331
331
 
332
332
  # finishまたはconditionを使う待機/close policyでRuntime Expressionを追加
333
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
333
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.6.0/dist/runtime-expression.js
334
334
 
335
335
  # Bubble(必ず最後)
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.0/dist/turbowarp-bubble.js
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.13.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)を参照してください。
@@ -405,7 +405,7 @@ wait and close this bubble using close policy [advance]
405
405
 
406
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
407
 
408
- `ASSETS`はAsset Managerへ登録済みの名前をカンマ区切りで指定します。前後の空白は除去され、名前自体にカンマは使用できません。目パチと口パクは1フレーム以上、continue indicatorは2フレーム以上が必要で、空リストにすると設定を解除します。frame間隔は0より大きい有限値です。逐次表示間隔、animation時間、従来のwait timeoutには0も指定でき、逐次表示間隔の0は自動送りを、従来のtimeoutの0は時間制限を無効にします。close policyで明示的に選ぶtimeoutは0より大きい値にします。
408
+ `ASSETS`はAsset Cacheへ登録済みの名前をカンマ区切りで指定します。前後の空白は除去され、名前自体にカンマは使用できません。目パチと口パクは1フレーム以上、continue indicatorは2フレーム以上が必要で、空リストにすると設定を解除します。frame間隔は0より大きい有限値です。逐次表示間隔、animation時間、従来のwait timeoutには0も指定でき、逐次表示間隔の0は自動送りを、従来のtimeoutの0は時間制限を無効にします。close policyで明示的に選ぶtimeoutは0より大きい値にします。
409
409
 
410
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`に揃えます。
411
411
 
@@ -560,7 +560,7 @@ close this bubble
560
560
 
561
561
  ### Composition API
562
562
 
563
- TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではstandalone SVG Text 0.8.1があればnamed-style handoffを使い、なければ内包layout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
563
+ TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではstandalone SVG Text 0.10.0があればnamed-style handoffを使い、なければ内包layout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Cacheを追加でロードしてください。
564
564
 
565
565
  ```ts
566
566
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -578,7 +578,7 @@ import {
578
578
  type BubbleTextCapability,
579
579
  } from "@kubohiroya/turbowarp-bubble/composition";
580
580
 
581
- // These are host-owned capabilities. They may be backed by Asset Manager,
581
+ // These are host-owned capabilities. They may be backed by Asset Cache,
582
582
  // another asset service, or local application code.
583
583
  declare const imageResolver: BubbleImageCapability;
584
584
  declare const textCapability: BubbleTextCapability;
@@ -593,7 +593,7 @@ const bubbles = createBubbleComposition({
593
593
 
594
594
  `declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleTextCapability`(文字layout/描画・計測・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。`@kubohiroya/turbowarp-svg-text/composition`を使う場合は、skinを使うhostなら`createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))`、SVG overlayなら`createSvgTextOverlayTextCapability(createSvgTextLayoutComposition())`で変換します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
595
595
 
596
- テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、`audio.voice`、`audio.reveal`、`audio.finish`によるフルボイス、表示単位ごとの効果音、完了音を登録・再生するメディア経路です。TurboWarp adapterはstock Asset Managerへ遅延接続し、低レベルComposition APIのhostは独自の`audio` capabilityを注入できます。
596
+ テキストだけを表示する場合は、Asset Cacheのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Cacheは画像だけでなく、`audio.voice`、`audio.reveal`、`audio.finish`によるフルボイス、表示単位ごとの効果音、完了音を登録・再生するメディア経路です。TurboWarp adapterはstock Asset Cacheへ遅延接続し、低レベルComposition APIのhostは独自の`audio` capabilityを注入できます。
597
597
 
598
598
  `createSurface`が返すsurfaceは、次のtargetを持ちます。
599
599
 
@@ -691,6 +691,34 @@ await bubble.finish({
691
691
  await bubble.close();
692
692
  ```
693
693
 
694
+ ### content runによるルビ表示
695
+
696
+ `show()`と`handle.setText()`は、文字列に加えてcontent runの並びを受け取ります。ホスト側のDSLが本文へ書いたルビ(ふりがな)を、そのまま吹き出しへ渡せます。
697
+
698
+ ```ts
699
+ await bubbles.show({
700
+ actor,
701
+ actorKey: "hero",
702
+ kind: "say",
703
+ styleName: "dialogue",
704
+ text: [
705
+ { type: "text", text: "私は " },
706
+ { type: "ruby", base: "中野", reading: "なかの" },
707
+ { type: "text", text: " です" },
708
+ ],
709
+ reveal: { unit: "CHARACTER", intervalSeconds: 0.05 },
710
+ });
711
+ ```
712
+
713
+ runは`{ type: "text", text }`または`{ type: "ruby", base, reading }`で、`@kubohiroya/turbowarp-svg-text`の`SvgTextContentRun`と同じ形です。そのため`createSvgTextCompositionCapability`はrunsを変換せずそのまま渡します。
714
+
715
+ 互換性と失敗時の扱いは次のとおりです。
716
+
717
+ - `text: string`の経路は変更していません。文字列、およびrubyを含まないrunsは、これまでどおりtext capabilityの`setText`と既存の折り返し・計測を使います。
718
+ - rubyのrunは`CHARACTER`/`WORD`/`LINE`/`BLOCK`のいずれのreveal unitでも1単位として扱うため、`中野`がreadingを伴わずに現れることはありません。
719
+ - rubyの描画には`setRichText`を実装したtext capabilityが必要です。未実装のcapabilityへrubyのrunsが渡された場合、baseだけを黙って描くのではなく`BUBBLE-COMPOSITION-007`で明示的に失敗します。
720
+ - capabilityは`measureRichText`と`splitRichText`も実装できます。`splitRichText`があるときはrevealの分割をcapabilityへ委譲し、無いときはBubbleが分割してrubyのrunを分割せずに保ちます。
721
+
694
722
  返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、text capability target、surfaceを解放します。composition間で状態は共有しません。
695
723
 
696
724
  ## ライセンスとソースコード
package/README.md CHANGED
@@ -4,7 +4,7 @@
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.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.
7
+ The current release is Bubble 0.13.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.10.0. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Cache 0.1.0, Async Input 0.7.0, and Runtime Expression 0.6.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
8
 
9
9
  ## How to read this README
10
10
 
@@ -40,7 +40,7 @@ The table below maps the 0.11.0 feature set to its public entry points. The stan
40
40
  | --------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
41
41
  | Text rendering and wrapping | `BubbleTextCapability`, named styles, measured width, `maxWidth`, and UAX #14-compliant wrapping | `composition`, `turbowarp-adapter`, and extension blocks |
42
42
  | Progressive reveal | `CHARACTER` / `WORD` / `LINE` / `BLOCK`, delimiters, per-unit sound effects, and finish conditions | `composition`, lightweight `reveal` entry, and blocks |
43
- | Portrait | Independent base-image, `blink`, and `lip-sync` layers | Composition API and blocks through Asset Manager |
43
+ | Portrait | Independent base-image, `blink`, and `lip-sync` layers | Composition API and blocks through Asset Cache |
44
44
  | Bubble outline | Visual styles such as `NORMAL`, placement, tail, offset, and scale | Composition API, TurboWarp adapter, and blocks |
45
45
  | Display mode | `talking` / `awaiting-continue` / `idle` | `BubbleHandle.setAnimationMode()` and the matching block |
46
46
  | Show, active, and hide animations | `fadeIn`, `floatIn`, `shake`, `animateBubbleShape`, and others | Style settings, `BubbleHandle.animate()`, and blocks |
@@ -56,7 +56,7 @@ flowchart TB
56
56
  core["Bubble core\noutline, placement, lifecycle, and animation state"]
57
57
  contract["BubbleTextCapability\nhost-neutral text contract"]
58
58
  twAdapter["TurboWarp Bubble adapter\nconnects to renderer / runtime / target"]
59
- svgAdapter["SVG Text 0.8 layout adapter\nrenderer-independent line layout and measurement"]
59
+ svgAdapter["SVG Text 0.10 layout adapter\nrenderer-independent line layout and measurement"]
60
60
  assets["Optional Image / Audio capabilities\nportrait, lip-sync, and audio"]
61
61
  input["Optional Input / Expression capabilities\ninput and wait conditions"]
62
62
  host["Custom web application / host"]
@@ -71,16 +71,16 @@ flowchart TB
71
71
  extension -."optional".-> input
72
72
  ```
73
73
 
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.8.1`, to obtain line layout and text widths without creating SVG skins. When the standalone SVG Text 0.8.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 Manager, Async Input, and Runtime Expression are connected only when their corresponding features are used.
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.0`, to obtain line layout and text widths without creating SVG skins. When the standalone SVG Text 0.10.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
75
 
76
76
  ### Rendering backend (SVG overlay by default)
77
77
 
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.
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.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
79
 
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.
80
+ When the stock Asset Cache 0.1.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
81
 
82
82
  ```ts
83
- import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
83
+ import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-cache/composition";
84
84
  import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
85
85
  import {
86
86
  createAssetManagerSvgOverlayImageCapability,
@@ -107,11 +107,11 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
107
107
  });
108
108
  ```
109
109
 
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"`.
110
+ When `svgOverlayTextCapability` is omitted and standalone SVG Text 0.10.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.10.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
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.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.
112
+ The default text provider is the directly depended-on SVG Text 0.10.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
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.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.
114
+ 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
115
 
116
116
  | Host / capture method | `scratch-render` | `svg-overlay` |
117
117
  | ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------- |
@@ -124,7 +124,7 @@ The skin-independent contracts for SVG Text and Asset Manager are published in [
124
124
 
125
125
  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
126
 
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.8.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).
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.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
128
 
129
129
  ### Progressive reveal units (CHARACTER / WORD / LINE / BLOCK)
130
130
 
@@ -193,7 +193,7 @@ When `CONDITION` becomes true, Bubble reveals every remaining unit. If it does n
193
193
 
194
194
  `finish` is available as `handle.finish({ unit, condition, timeoutSeconds })` in the public Composition API and as the TurboWarp `finish [UNIT] ...` block. It completes progressive reveal and settles the audio and waiting state when the condition succeeds or the timeout expires.
195
195
 
196
- When Asset Manager is connected as the audio provider, the following audio can share the same display lifecycle:
196
+ When Asset Cache is connected as the audio provider, the following audio can share the same display lifecycle:
197
197
 
198
198
  - Full voice playback when display starts
199
199
  - A sound effect each time one `CHARACTER`, `WORD`, `LINE`, or `BLOCK` unit is revealed
@@ -205,7 +205,7 @@ Per-unit effects play named audio assets; they do not synthesize the displayed s
205
205
 
206
206
  | Package | Responsibility |
207
207
  | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
208
- | `@kubohiroya/turbowarp-asset-manager` | Connect optional Image / Audio capabilities to TurboWarp assets (image resolution and audio playback) |
208
+ | `@kubohiroya/turbowarp-asset-cache` | Connect optional Image / Audio capabilities to TurboWarp assets (image resolution and audio playback) |
209
209
  | Bubble core (`composition`) | `BubbleTextCapability` contract, bubble surfaces, placement, progressive reveal, and animation |
210
210
  | `@kubohiroya/turbowarp-svg-text` | Host-neutral plain / ruby layout, stock named-style handoff, and text-width measurement in version 0.8.1 |
211
211
  | `@kubohiroya/turbowarp-async-input` | Reflect key and tap input in Temporary Variables runtime variables |
@@ -213,7 +213,7 @@ Per-unit effects play named audio assets; they do not synthesize the displayed s
213
213
  | `@kubohiroya/turbowarp-bubble` | Bubble surfaces, placement, progressive reveal, say / think, expression layers, animation, and input waiting |
214
214
  | Application / host | Convert application-specific input to Composition API calls as needed |
215
215
 
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.8.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 Manager lazily, while Composition API hosts can implement `imageResolver` and `audio` themselves. Features that use Asset Manager cover external media beyond images, including full voice clips, typewriter sounds, and per-line or per-paragraph effects.
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.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
217
 
218
218
  ### Automatic wrapping and line-breaking rules
219
219
 
@@ -286,20 +286,20 @@ 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.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.
289
+ SVG Text 0.10.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.10.0 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.1.0 <1` for Asset Cache and `>=0.3.0 <1` for both Async Input and Runtime Expression; the currently published and recommended extension versions are Asset Cache 0.1.0, Async Input 0.7.0, and Runtime Expression 0.6.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
 
293
- Add Asset Manager to use image portraits, lip-sync, continue indicators, or audio assets. The `finish [UNIT] ...` block requires Runtime Expression. The integrated `wait with this bubble ...` block requires both Async Input and Runtime Expression.
293
+ Add Asset Cache to use image portraits, lip-sync, continue indicators, or audio assets. The `finish [UNIT] ...` block requires Runtime Expression. The integrated `wait with this bubble ...` block requires both Async Input and Runtime Expression.
294
294
 
295
295
  ```sh
296
- pnpm add @kubohiroya/turbowarp-asset-manager \
296
+ pnpm add @kubohiroya/turbowarp-asset-cache \
297
297
  @kubohiroya/turbowarp-async-input \
298
298
  @kubohiroya/turbowarp-runtime-expression
299
299
  ```
300
300
 
301
301
  ```sh
302
- npm install @kubohiroya/turbowarp-asset-manager \
302
+ npm install @kubohiroya/turbowarp-asset-cache \
303
303
  @kubohiroya/turbowarp-async-input \
304
304
  @kubohiroya/turbowarp-runtime-expression
305
305
  ```
@@ -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.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.
319
+ 3. Load Asset Cache 0.1.0 if you use portraits, blinking, lip-sync, continue frames, or audio.
320
+ 4. Load Runtime Expression 0.6.0 for `finish [UNIT] ...`; load both Async Input 0.7.0 and Runtime Expression 0.6.0 for condition-based waits and close policies. A timeout-only close policy needs neither extension.
321
+ 5. Load Bubble 0.13.0 last. The SVG Text 0.10.0 layout provider is included in the Bubble bundle.
322
322
 
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.
323
+ 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.
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.13.0/dist/asset-manager.js
327
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.1.0/dist/asset-cache.js
328
328
 
329
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
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.7.0/dist/async-input.js
331
331
 
332
332
  # Add Runtime Expression for finish or condition-based waits and close policies
333
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
333
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.6.0/dist/runtime-expression.js
334
334
 
335
335
  # Bubble (always load last)
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.0/dist/turbowarp-bubble.js
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.13.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.
@@ -405,7 +405,7 @@ wait and close this bubble using close policy [advance]
405
405
 
406
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
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.
408
+ `ASSETS` is a comma-separated list of names registered with Asset Cache; 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.
409
409
 
410
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.
411
411
 
@@ -560,7 +560,7 @@ Bubble automatically releases its owned timers, overlay DOM, and image leases wh
560
560
 
561
561
  ### Composition API
562
562
 
563
- Hosts that connect to a TurboWarp runtime renderer can use the public adapter. By default, it uses the SVG Text 0.8.1 named-style handoff when a standalone extension is loaded, otherwise its bundled layout composition, together with an SVG overlay. Load Asset Manager in addition only when using image portraits, lip-sync, continue indicators, or audio assets.
563
+ Hosts that connect to a TurboWarp runtime renderer can use the public adapter. By default, it uses the SVG Text 0.10.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.
564
564
 
565
565
  ```ts
566
566
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -578,7 +578,7 @@ import {
578
578
  type BubbleTextCapability,
579
579
  } from "@kubohiroya/turbowarp-bubble/composition";
580
580
 
581
- // These are host-owned capabilities. They may be backed by Asset Manager,
581
+ // These are host-owned capabilities. They may be backed by Asset Cache,
582
582
  // another asset service, or local application code.
583
583
  declare const imageResolver: BubbleImageCapability;
584
584
  declare const textCapability: BubbleTextCapability;
@@ -593,7 +593,7 @@ const bubbles = createBubbleComposition({
593
593
 
594
594
  The `declare` lines are type declarations that keep the example short. In a real host, implement and pass `BubbleTextCapability` (text layout, rendering, measurement, and release), `BubbleImageCapability` (image-name resolution), `BubbleAudioCapability` (audio playback), and `BubbleSurfaceFactory` (creation of targets for the outline, text, and portrait). When using `@kubohiroya/turbowarp-svg-text/composition`, adapt it with `createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))` for a skin-based host or `createSvgTextOverlayTextCapability(createSvgTextLayoutComposition())` for an SVG overlay. With a TurboWarp runtime, use `createTurboWarpBubbleComposition(runtime)` instead of implementing these pieces individually.
595
595
 
596
- For text-only display, omit the Asset Manager import, `createAssetManagerComposition()`, and the `imageResolver` property. Asset Manager is a media path not only for images but also for registering and playing full voice clips, per-unit reveal sounds, and finish cues through `audio.voice`, `audio.reveal`, and `audio.finish`. The TurboWarp adapter connects the stock Asset Manager lazily; a lower-level Composition API host can instead inject its own `audio` capability.
596
+ For text-only display, omit the Asset Cache import, `createAssetManagerComposition()`, and the `imageResolver` property. Asset Cache is a media path not only for images but also for registering and playing full voice clips, per-unit reveal sounds, and finish cues through `audio.voice`, `audio.reveal`, and `audio.finish`. The TurboWarp adapter connects the stock Asset Cache lazily; a lower-level Composition API host can instead inject its own `audio` capability.
597
597
 
598
598
  The surface returned by `createSurface` has the following targets.
599
599
 
@@ -691,6 +691,34 @@ await bubble.finish({
691
691
  await bubble.close();
692
692
  ```
693
693
 
694
+ ### Ruby annotations with content runs
695
+
696
+ `show()` and `handle.setText()` accept either a plain string or a sequence of content runs, so a host DSL can carry ruby (furigana) into a bubble:
697
+
698
+ ```ts
699
+ await bubbles.show({
700
+ actor,
701
+ actorKey: "hero",
702
+ kind: "say",
703
+ styleName: "dialogue",
704
+ text: [
705
+ { type: "text", text: "私は " },
706
+ { type: "ruby", base: "中野", reading: "なかの" },
707
+ { type: "text", text: " です" },
708
+ ],
709
+ reveal: { unit: "CHARACTER", intervalSeconds: 0.05 },
710
+ });
711
+ ```
712
+
713
+ A run is `{ type: "text", text }` or `{ type: "ruby", base, reading }`, matching `SvgTextContentRun` from `@kubohiroya/turbowarp-svg-text`, so `createSvgTextCompositionCapability` forwards runs without converting them.
714
+
715
+ Compatibility and failure rules:
716
+
717
+ - The `text: string` path is unchanged. A string, or runs that contain no ruby, keep using `setText` on the text capability along with the existing wrapping and measurement.
718
+ - A ruby run is one whole reveal unit for `CHARACTER`, `WORD`, `LINE`, and `BLOCK`, so `中野` never appears without its reading.
719
+ - Rendering ruby requires a text capability that implements `setRichText`. When ruby runs reach a capability without it, Bubble raises `BUBBLE-COMPOSITION-007` rather than silently drawing the base text and dropping the author's reading.
720
+ - A capability may also implement `measureRichText` and `splitRichText`. When `splitRichText` is present, Bubble delegates reveal splitting to it; otherwise Bubble splits the runs itself and keeps each ruby run whole.
721
+
694
722
  The returned handle's `setText(text)` updates the body text on the same surface and can be used for progressive text display. `handle.updateStyle(style)` applies a style change immediately to a displayed Bubble. Showing a new Bubble with the same `actorKey` completely destroys and then replaces the previous Bubble. `releaseTarget`, `releaseAll`, and `dispose` also release owned timers, text-capability targets, and surfaces. State is not shared between compositions.
695
723
 
696
724
  ## License and source code