@kubohiroya/turbowarp-bubble 0.8.0 → 0.10.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.
@@ -74,7 +74,7 @@
74
74
  </blockquote>
75
75
  <p><img src="../assets/block-quick-start.svg" alt="Next1とNext2を個別登録し、入力listenerを準備してBubble内蔵待機を使うブロック例"></p>
76
76
  <h2 id="requirements">1. 必要な拡張機能</h2>
77
- <p>入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.0のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。</p>
77
+ <p>入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.1のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime Expressionはconditionを使うBubble待機またはclose policyで必要です。timeoutだけのclose policyにはどちらも不要です。</p>
78
78
  <table>
79
79
  <thead>
80
80
  <tr>
@@ -100,16 +100,16 @@
100
100
  </tr>
101
101
  <tr>
102
102
  <td align="right">4</td>
103
- <td>Asset Manager 0.11.0</td>
104
- <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.11.0/dist/asset-manager.js</code></td>
103
+ <td>Asset Manager 0.12.1</td>
104
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js</code></td>
105
105
  </tr>
106
106
  <tr>
107
107
  <td align="right">5</td>
108
- <td>Bubble 0.8.0</td>
109
- <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.8.0/dist/turbowarp-bubble.js</code></td>
108
+ <td>Bubble 0.10.0</td>
109
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js</code></td>
110
110
  </tr>
111
111
  </tbody></table>
112
- <p>開発中のBubbleを試す場合は、このリポジトリの<code>dist/turbowarp-bubble.js</code>をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、待機開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。</p>
112
+ <p>開発中のBubbleを試す場合は、このリポジトリの<code>dist/turbowarp-bubble.js</code>をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、condition待機の開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。</p>
113
113
  <p>参考:</p>
114
114
  <ul>
115
115
  <li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/ja/">Asset Manager 日本語ガイド</a></li>
@@ -175,12 +175,22 @@ register resource [costume:Assets:Next2] as asset [Next2]
175
175
  </code></pre>
176
176
  <p>URL画像を使う場合は、<code>RESOURCE_ID</code>へHTTPS URLを指定します。Bubbleに設定できるのは、Asset Managerへ登録済みでMIME typeが<code>image/*</code>のアセットだけです。</p>
177
177
  <h2 id="text-style">3. 文字layout styleを選ぶ</h2>
178
- <p>standalone BubbleはSVG Text 0.8.0のlayout compositionを内包します。<code>default</code>または任意の名前を指定すると、初回参照時に背景透明のSVG Text既定styleとして初期化されます。</p>
178
+ <p>standalone BubbleはSVG Text 0.8.1のlayout compositionを内包し、2つのBubble styleを組み込みます。<code>say</code>はspeech本体とspeech tail、<code>think</code>はthought本体とround trailを持ち、本体とtail/trailの形は別項目ではなく1つのvisual styleとして選びます。短い<code>say [MESSAGE]</code>/<code>think [MESSAGE]</code>ブロックが対応styleを自動選択するため、基本経路にはstyle定義もstyle入力も不要です。どちらも予約text profile <code>default</code>、内容に追従するサイズ、14px Helvetica、右側優先・収まりに応じた左反転、block入力の330文字上限、空文字でのcloseを使います。4pxのSVG strokeを白いfillより先に描き、内側半分を隠すことで、見かけの輪郭をTurboWarp標準と同じ細さにします。それ以外のtext style名やstyle設定ブロックを使うとcustom profileになります。custom text styleは初回参照時に背景透明のSVG Text既定styleとして初期化されます。stock SVG Text 0.8.1をBubbleより先に別拡張として読み込んだprojectでは、Bubbleが公開<code>getLayoutCapability()</code>を使い、SVG Text blockで定義したnamed styleを維持します。handoffのない古いSVG Textがロード済みならstyleを黙って置換せず互換errorを返し、必要な場合だけ文書化済みscratch-render fallbackを選択します。</p>
179
179
  <pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
180
180
  </code></pre>
181
- <p>独自のfont、色、alignmentを使うアプリhostは、<code>createSvgTextLayoutComposition()</code>へstyleを定義し、<code>createSvgTextOverlayTextCapability()</code>でBubbleへ注入します。既定経路も同じ<code>layoutText()</code>を使い、SVG文字skinは生成しません。Bubbleの配置、tail、吹き出し外形はBubble側が担当します。</p>
181
+ <p>独自のfont、色、alignmentを使うアプリhostは、<code>createSvgTextLayoutComposition()</code>へstyleを定義し、<code>createSvgTextOverlayTextCapability()</code>でBubbleへ注入します。custom profileは同じ<code>layoutText()</code>を使い、既定overlay backendではSVG文字skinを生成しません。Bubbleの配置、tail、吹き出し外形はBubble側が担当します。</p>
182
182
  <h2 id="bubble-style">4. Bubble styleを定義する</h2>
183
- <p>まず、Bubble style名と文字layout style名を関連付けます。</p>
183
+ <p>基本Bubbleでは短いブロックをそのまま使います。組み込みBubble style <code>say</code>/<code>think</code>がそれぞれ自動選択されます。</p>
184
+ <pre><code class="language-text">say [こんにちは!]
185
+ think [うーん…]
186
+ </code></pre>
187
+ <h3>TurboWarp標準との比較</h3>
188
+ <p>次の画像は、1つのTurboWarp Editor projectで英語UIを使い、<code>Cat</code> spriteを<code>x=-80</code>、<code>y=0</code>、サイズ<code>80%</code>、Stageを白背景、入力を<code>Hello!</code>/<code>Hmm...</code>に揃えて撮影した実画面です。左列はTurboWarp標準の見た目ブロックです。右列は対応する組み込み<code>say</code>/<code>think</code> styleを使うBubbleの短い基本ブロックで、定義ブロックもsetterも使っていません。</p>
189
+ <p><img src="../assets/turbowarp-say-think-stage-comparison.png" alt="TurboWarp標準のsay・think吹き出しとBubble基本profileを同じStageで比較した実画面"></p>
190
+ <p>Stage図では、右側配置、内容に追従する本体、Actor側へ向くspeech tail/thought trailを同じ条件で確認できます。Bubbleは独立したSVG surfaceを描画しており、全4panelとも実際のTurboWarp Stageを切り出したものです。</p>
191
+ <p><img src="../assets/turbowarp-say-think-block-comparison.png" alt="TurboWarp標準のsay・thinkブロックと、設定不要のBubble基本say・thinkブロックおよび組み込みdefault profile値を比較したスクリーンショット"></p>
192
+ <p>ブロック図は設定不要の基本経路と、custom style用の統合表示ブロックを示します。短いブロックは対応する組み込みstyleを自動選択します。calloutでは不可分な本体+tail/trailの組、両styleが使う予約text profile <code>default</code>、共通のfont、行高、幅、padding、角丸、色、border描画順、配置を示します。named custom styleには<code>show [MESSAGE] with bubble style [STYLE]</code>を使います。旧styled say/think opcodeは保存済みproject互換用の非表示定義として残します。</p>
193
+ <p>次のsetterを使うと、意図的にcustom profileへ切り替わります。</p>
184
194
  <pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
185
195
  set bubble placement [up-right] for bubble style [hero-dialogue]
186
196
  set bubble distance [12] for bubble style [hero-dialogue]
@@ -192,7 +202,7 @@ set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
192
202
  <p><img src="../assets/placement-guide.svg" alt="Actor相対の16方向・角度指定と、背景相対の3配置を比較する図"></p>
193
203
  <p>Actor相対の16方向は、各方向をActor、Bubble外形、tail、文字を含む独立したミニシーンで示しています。三角形tailの基部2点は実際の本体border上にあり、本体polygonとのJSClipper union後の単一pathを描くため、接合部に内部border線は残りません。</p>
194
204
  <p>背景相対3図はStage外枠、安全領域、Bubble外形寸法、水平中央線、基準辺/中心を示します。外形はBubble側の共有<code>renderBubbleSvg</code>で生成しており、TurboWarp Editorで本体drawableを生成するrendererと同じです。</p>
195
- <p>Actor相対では、Actor中心からBubble全体の中心へ向かう方向を指定します。menuには次の16正規方向があります。</p>
205
+ <p>Actor相対placementはcustom profileへ適用され、Actor中心からBubble全体の中心へ向かう方向を指定します。未変更の基本profileはScratch標準の右側優先・自動左反転を使います。menuには次の16正規方向があります。</p>
196
206
  <pre><code class="language-text">up / up-up-right / up-right / right-up-right
197
207
  right / right-down-right / down-right / down-down-right
198
208
  down / down-down-left / down-left / left-down-left
@@ -271,7 +281,7 @@ set continue frames [Next1,Next2]
271
281
  set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
272
282
  set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
273
283
  set bubble voice [HeroVoice] for bubble style [hero-dialogue]
274
- say [海へ出発!] with bubble style [hero-dialogue]
284
+ show [海へ出発!] with bubble style [hero-dialogue]
275
285
  finish [CHARACTER] with condition [input == &quot;pressed&quot;] or timeout after [10] seconds
276
286
  </code></pre>
277
287
  <p><code>DYNAMIC</code>は表示単位ごとに吹き出しの大きさと配置を再計算し、<code>RESERVED</code>は最終的な文字量を先に計測して表示中の外形を予約します。<code>set bubble reveal sound</code>は単位ごと、<code>set bubble voice</code>は表示開始時にAsset Managerの名前付き音声を再生します。音声がなくても文字表示は利用できます。</p>
@@ -280,12 +290,18 @@ finish [CHARACTER] with condition [input == &quot;pressed&quot;] or timeout afte
280
290
  <pre><code class="language-text">set runtime variable [input] to []
281
291
  listen for key [Space] set runtime var [input] to [pressed]
282
292
  listen for touch on this sprite set runtime var [input] to [pressed]
283
- say [海へ出発!] with bubble style [hero-dialogue]
293
+ show [海へ出発!] with bubble style [hero-dialogue]
284
294
  wait with this bubble until condition [input == &quot;pressed&quot;] or timeout after [10] seconds
285
295
  close this bubble
286
296
  </code></pre>
287
297
  <p>まずTemporary Variablesで<code>input</code>を初期化してから、Async Inputのキー入力とタップのlistenerを登録します。Bubbleの待機ブロックは、<code>input == &quot;pressed&quot;</code>をRuntime Expressionへ委譲し、開始直後とVMの各フレームで評価します。待機中は自動的に<code>awaiting-continue</code>となり、口パクを停止して<code>set continue frames</code>の画像をループします。条件成立またはtimeout後は<code>idle</code>へ移り、次の<code>close this bubble</code>へ進みます。timeoutを<code>0</code>にすると時間制限なしです。</p>
288
298
  <p>次の待機に入る前に<code>input</code>を空文字へ戻してください。前回の<code>pressed</code>が残っていると、次の条件が直ちに成立します。別のBubble表示、close、対象targetの停止、projectの開始・停止、runtime破棄では、targetが所有する待機とlistener、timerをキャンセルして解放します。</p>
299
+ <p>同じ終了規則を再利用する場合は、名前付きBubble close policyを使います。triggerは<code>condition</code>、<code>timeout</code>、<code>condition-or-timeout</code>から明示的に選びます。policyの適用は定義をsnapshotし、成立まで待ち、Bubbleのhide animationと解放までを1つの待機commandとして実行します。</p>
300
+ <pre><code class="language-text">define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == &quot;pressed&quot;] timeout [10] seconds
301
+ show [海へ出発!] with bubble style [hero-dialogue]
302
+ wait and close this bubble using close policy [advance-or-timeout]
303
+ </code></pre>
304
+ <p>timeoutだけのpolicyは現在のanimation modeを変えず、入力用拡張を必要としません。conditionを含むpolicyは<code>awaiting-continue</code>へ移り、既存の統合待機と同じAsync Input/Runtime Expression設定を使います。待機中に同じ名前を再定義しても、変更は次回の適用から有効です。Bubbleの置換やlifecycle cleanupは待機中policyをcancelし、置換後のBubbleを閉じません。</p>
289
305
  <p>音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点で<code>awaiting-continue</code>へ切り替えます。</p>
290
306
  <p><img src="../assets/bubble-lifecycle.gif" alt="sayで口パクし、awaiting-continueでcontinue framesを動かし、入力成立後にBubbleを閉じるアニメーション"></p>
291
307
  <p>アニメーションGIFを再生できない環境では、次の比較図で各animation modeを確認できます。</p>
@@ -334,11 +350,11 @@ explode this bubble relative scale [1.15] count [2] ease [easeOut]
334
350
  animate bubble shape to [WAVY] speed [1] for [0.5] seconds
335
351
  </code></pre>
336
352
  <p>TurboWarp adapterはこれらをschedulerのフレームごとに進め、各フレームの進行率へ<code>ease</code>を適用します。<code>shake</code>は吹き出し全体を方向・回数付きで揺らし、<code>explode</code>はportraitと文字を含むsurface全体を拡大して元へ戻し、<code>animate bubble shape</code>は指定時間中に現在の外形から<code>THINKING</code>、<code>DREAMING</code>、<code>YELLING</code>、<code>WAVY</code>、<code>WHISPERING</code>などへcross-fadeします。仕様では、吹き出しが表示される時点を「表示開始」、隠れる時点を「表示終了」と呼びます。</p>
337
- <h2 id="reference">9. sayとthink</h2>
338
- <pre><code class="language-text">say [MESSAGE] with bubble style [STYLE]
339
- think [MESSAGE] with bubble style [STYLE]
353
+ <p>表示中のBubbleを消すときは<code>close this bubble</code>を使います。設定済みの表示終了animationを実行してから、Bubbleのtimerと描画resourceを解放します。<code>set bubble hide animation ...</code>は終了時の演出を設定するだけで、このブロック自体はBubbleを消しません。組み込み基本profileでは、<code>say</code>/<code>think</code>へ空文字を渡してもTurboWarp標準と同様にcloseします。closeは非表示instanceを保持せず表示を破棄するため、別の<code>hide</code>ブロックは公開しません。</p>
354
+ <h2 id="reference">9. named Bubble styleを表示する</h2>
355
+ <pre><code class="language-text">show [MESSAGE] with bubble style [STYLE]
340
356
  </code></pre>
341
- <p>どちらも同じvisual style、表情レイヤー、placement、animation mode制御を使えます。<code>say</code>/<code>think</code>だけで形状を固定せず、<code>set bubble visual style</code>で<code>NORMAL</code>、<code>THINKING</code>などを明示的に選びます。Composition APIのsurfaceには<code>say</code>/<code>think</code>のkindも渡されるため、独自hostではkindに応じた追加表現も可能です。</p>
357
+ <p>選択したBubble styleが、本体とtail/trailの形を一体で決め、text profile、表情レイヤー、placement、animation設定も保持します。<code>set bubble visual style</code>は<code>NORMAL</code>(speech本体+speech tail)や<code>THINKING</code>(thought本体+round trail)のような不可分の組を選ぶブロックで、tail形状だけを独立して指定する設定はありません。standalone extensionは、表示ブロックに競合し得る別の種類を選ばせず、そのstyleから内部描画kindを導きます。</p>
342
358
  <p>同じsprite、clone、またはStageで新しい<code>say</code>/<code>think</code>を実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。</p>
343
359
  <h2 id="troubleshooting">10. cloneで使う</h2>
344
360
  <p>Bubble styleの定義は拡張機能内で共有されますが、表示中のBubbleはsprite/cloneごとに所有されます。</p>
@@ -361,6 +377,10 @@ think [MESSAGE] with bubble style [STYLE]
361
377
  <td>Bubble styleを定義または再定義する</td>
362
378
  </tr>
363
379
  <tr>
380
+ <td><code>define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds</code></td>
381
+ <td>名前付きの終了条件を定義または置換する</td>
382
+ </tr>
383
+ <tr>
364
384
  <td><code>set bubble placement [PLACEMENT] for bubble style [STYLE]</code></td>
365
385
  <td>Actor相対方向・角度、または背景相対領域を設定する</td>
366
386
  </tr>
@@ -370,7 +390,7 @@ think [MESSAGE] with bubble style [STYLE]
370
390
  </tr>
371
391
  <tr>
372
392
  <td><code>set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]</code></td>
373
- <td>Bubble本体のSVG形状を10種類から設定する</td>
393
+ <td>不可分なSVG本体+tail/trailの組を10種類から設定する</td>
374
394
  </tr>
375
395
  <tr>
376
396
  <td><code>set bubble tail length [LENGTH] for bubble style [STYLE]</code></td>
@@ -445,12 +465,16 @@ think [MESSAGE] with bubble style [STYLE]
445
465
  <td>Bubble外形を時間経過で切り替える</td>
446
466
  </tr>
447
467
  <tr>
448
- <td><code>say [MESSAGE] with bubble style [STYLE]</code></td>
449
- <td><code>talking</code> modeでsay表示を開始・置換する</td>
468
+ <td><code>say [MESSAGE]</code></td>
469
+ <td>組み込み<code>say</code> styleのspeech本体+tailを表示する</td>
470
+ </tr>
471
+ <tr>
472
+ <td><code>think [MESSAGE]</code></td>
473
+ <td>組み込み<code>think</code> styleのthought本体+round trailを表示する</td>
450
474
  </tr>
451
475
  <tr>
452
- <td><code>think [MESSAGE] with bubble style [STYLE]</code></td>
453
- <td><code>talking</code> modeでthink表示を開始・置換する</td>
476
+ <td><code>show [MESSAGE] with bubble style [STYLE]</code></td>
477
+ <td>styleが持つ本体+tail/trailの一組を表示する</td>
454
478
  </tr>
455
479
  <tr>
456
480
  <td><code>set this bubble animation mode [MODE]</code></td>
@@ -461,6 +485,10 @@ think [MESSAGE] with bubble style [STYLE]
461
485
  <td>Runtime Expressionの条件成立またはtimeoutまで待つ</td>
462
486
  </tr>
463
487
  <tr>
488
+ <td><code>wait and close this bubble using close policy [POLICY]</code></td>
489
+ <td>policyをsnapshotし、成立を待ってBubbleを閉じる</td>
490
+ </tr>
491
+ <tr>
464
492
  <td><code>close this bubble</code></td>
465
493
  <td>自分のBubbleと所有resourceを解放する</td>
466
494
  </tr>
@@ -469,6 +497,7 @@ think [MESSAGE] with bubble style [STYLE]
469
497
  <td>Bubble実装versionを返す</td>
470
498
  </tr>
471
499
  </tbody></table>
500
+ <p>旧<code>say/think [MESSAGE] with bubble style [STYLE]</code> opcodeを使う保存済みprojectは引き続き動作しますが、この互換ブロック2個はpaletteに表示しません。新しいscriptでは統合<code>show</code>ブロックを使い、選択styleだけで本体とtail/trailの形を決めます。</p>
472
501
  <h2 id="regeneration">12. よくあるエラー</h2>
473
502
  <table>
474
503
  <thead>
@@ -479,7 +508,7 @@ think [MESSAGE] with bubble style [STYLE]
479
508
  </thead>
480
509
  <tbody><tr>
481
510
  <td>Asset Managerを要求するエラー</td>
482
- <td>画像・メディアアセットを使う前にAsset Manager 0.7.xを読み込む</td>
511
+ <td>画像・メディアアセットを使う前にAsset Manager 0.12.xを読み込む</td>
483
512
  </tr>
484
513
  <tr>
485
514
  <td>SVG overlay backendのエラー</td>
@@ -495,7 +524,11 @@ think [MESSAGE] with bubble style [STYLE]
495
524
  </tr>
496
525
  <tr>
497
526
  <td><code>bubble style is not defined</code></td>
498
- <td><code>define bubble style</code>を先に実行する。緑の旗の再実行時も再定義する</td>
527
+ <td>組み込みの短いsay/thinkを使うか、named custom styleを先に定義する</td>
528
+ </tr>
529
+ <tr>
530
+ <td><code>bubble close policy is not defined</code></td>
531
+ <td>名前付きclose policyを適用前に定義する</td>
499
532
  </tr>
500
533
  <tr>
501
534
  <td>image assetが未登録</td>
@@ -539,6 +572,7 @@ think [MESSAGE] with bubble style [STYLE]
539
572
  <p>Asset Managerへ登録したアセット自体はBubbleの所有物ではありません。不要になった登録画像をメモリから削除する場合は、Bubbleを閉じた後にAsset Managerの<code>delete asset [NAME] from memory</code>を使います。</p>
540
573
  <h2>14. マニュアル画像の再生成</h2>
541
574
  <p>図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickの<code>magick</code>コマンドが必要です。</p>
575
+ <p>2つの<code>turbowarp-say-think-*-comparison.png</code>はrenderer previewから生成した図ではなく、TurboWarp Editorの実画面です。第4章に記載した撮影条件を使い、<code>docs:render</code>では上書きしません。</p>
542
576
  <pre><code class="language-sh">pnpm docs:render
543
577
  pnpm docs:check
544
578
  </code></pre>
@@ -0,0 +1,50 @@
1
+ # 0.10.0: 名前付きBubble close policy
2
+
3
+ ## 概要
4
+
5
+ Bubble 0.10.0では、吹き出しを閉じる条件を再利用可能な名前付きpolicyとして定義し、表示後に名前で適用できる。
6
+
7
+ - `condition`、`timeout`、`condition-or-timeout`の3つのtriggerを明示的に選べる。
8
+ - `wait and close this bubble using close policy [POLICY]`は定義をsnapshotし、成立まで待ち、hide animationとresource解放までを実行する。
9
+ - timeoutだけのpolicyはAsync InputやRuntime Expressionを必要としない。
10
+ - conditionを含むpolicyは既存の統合待機と同じcapabilityを使い、待機中は`awaiting-continue` modeになる。
11
+ - Bubbleの置換、target/projectの停止、runtime破棄では待機をcancelし、置換後のBubbleを閉じない。
12
+
13
+ ## 追加ブロック
14
+
15
+ ```text
16
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
17
+ say [3秒後に閉じます。]
18
+ wait and close this bubble using close policy [three-seconds]
19
+ ```
20
+
21
+ キー入力やspriteへのタッチをRuntime Expressionのconditionとして登録した場合は、時間制限なしの`condition`、またはtimeoutとの先着になる`condition-or-timeout`を使える。
22
+
23
+ ```text
24
+ define bubble close policy [advance] trigger [condition] condition [input == "pressed"] timeout [0] seconds
25
+ say [キーを押すかspriteをタッチしてください。]
26
+ wait and close this bubble using close policy [advance]
27
+ ```
28
+
29
+ Bubble close policyは制御フローの設定であり、吹き出しの形やtail/trailを選ぶBubble styleとは別のregistryである。
30
+
31
+ ## 互換性
32
+
33
+ - 既存の`say`、`think`、`show ... with bubble style ...`、`wait with this bubble ...`、`close this bubble`の契約は維持する。
34
+ - 保存済みstyled say/thinkブロック向けの非表示opcodeも維持する。
35
+ - standalone manifestは33定義を持ち、paletteには31ブロックを表示する。
36
+ - Composition APIとTurboWarp adapterの既存entry pointに破壊的変更はない。
37
+
38
+ ## 検証
39
+
40
+ - `pnpm check`
41
+ - `pnpm release:check`
42
+ - TypeScript declarationとComposition API consumerのcompile成功。
43
+ - lifecycle cancel、定義snapshot、timeout、condition、先着triggerを自動testで検証。
44
+ - ドキュメントsource、Pages生成HTML、extension manifest、配布bundle、npm tarballを一括検証。
45
+
46
+ ## 更新とロールバック
47
+
48
+ extension URLまたはnpm dependencyを0.9.0から0.10.0へ更新する。名前付きclose policyを使わない既存projectは変更不要である。
49
+
50
+ 回帰が見つかった場合はextension URLまたはnpm dependencyを0.9.0へpinし、修正版0.10.x patchを公開する。公開済み0.10.0 packageをunpublishしたり、対応するGit tag/GitHub Releaseを削除したりしない。
@@ -6,13 +6,15 @@
6
6
  - `"scratch-render"`は明示指定できるrollback backendとして保持する。
7
7
  - `renderer.addOverlay(root, "scale")`上の共有SVG rootにBubble surfaceを描画する。
8
8
  - host-neutralな`svgOverlayTextCapability`と、解放可能な`svgOverlayImageCapability`を公開する。
9
- - SVG Text 0.8.0を通常dependencyとし、既定で`createSvgTextLayoutComposition().layoutText()`の行layoutを座標・角丸ごと変換する。
9
+ - SVG Text 0.8.1を通常dependencyとし、standalone拡張がない場合は`createSvgTextLayoutComposition().layoutText()`、ロード済みの場合は公開`getLayoutCapability()`から同じnamed-style registryの行layoutを変換する。
10
+ - handoffのない古いstandalone SVG Textが存在する場合、named styleを既定値へ黙って置換せず、明示errorまたは設定済みscratch-render fallbackを使う。
10
11
  - Bubble側の`createAssetManagerSvgOverlayImageCapability()`でAsset Managerの汎用DOM resourceを変換する。依存方向はBubbleからAsset Managerへの一方向を維持する。
12
+ - stock Asset Manager 0.12.1を別拡張として読み込んだ場合、Bubbleが公開`getDOMImageCapability()`を遅延取得し、Asset Managerブロックで登録された同じregistryへ自動接続する。
11
13
  - overlay API未対応hostは`BUBBLE-RUNTIME-004`を返す。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ既存backendへ戻る。
12
14
 
13
15
  ## 自動検証結果
14
16
 
15
- 2026-08-18時点のunit testでは、次を合格条件としている。
17
+ 2026-08-19時点のunit testでは、次を合格条件としている。
16
18
 
17
19
  - optionsを省略した既定経路でshow、text更新、shake、shape animationを行っても、Bubbleから`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばない(許容値: 0回)。
18
20
  - 2つのBubbleが1つのrootを共有し、最後のclose後に`removeOverlay()`を1回呼ぶ(許容値: 残存root 0、重複remove 0)。
@@ -21,20 +23,69 @@
21
23
  - capability所有のblob URLをreplacement/close時に各1回解放する。
22
24
  - renderer cleanupが失敗した場合も、残りのlistener、DOM、image leaseの解放を継続してerrorを集約する。
23
25
  - Asset Managerのsanitize済みSVG resourceをBubble側adapter経由で描画し、close時にleaseを1回解放する。
24
- - SVG Textのhost-neutral layoutをBubble側adapterで変換し、renderer skinを生成せず行座標を維持する。
26
+ - SVG Textのhost-neutral layoutをBubble側adapterで変換し、renderer skinを生成せず行座標を維持する。stock named styleの再定義後は、同じ公開handoffから次回layoutへ新しいfont、color、size、alignment、改行layoutを反映する。
27
+
28
+ ## Web smoke結果
29
+
30
+ 2026-08-20にcommit `9b01605`からbuildしたrelease候補の`dist/turbowarp-bubble.js`を、TurboWarp Webのカスタム拡張機能へtext入力し、unsandboxedで読み込んだ。Chrome/macOSで`define bubble style`、say/think、style/reveal/animation/closeの各blockを実行した結果は次のとおり。
31
+
32
+ - Bubble paletteが登録され、sprite上方に`NORMAL`のsay bubbleが表示された。
33
+ - `[data-bubble-render-backend="svg-overlay"]`は1個で、DOMへ接続済みだった。
34
+ - rootは`viewBox="0 0 480 360"`、属性上の幅・高さとCSS上の表示領域はいずれも480×360だった。
35
+ - `NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`の全10styleを表示した。`THINKING`はbody `path` 1個とtrail `circle` 2個、`DREAMING`は`circle` 3個、`NO_BUBBLE`はbodyを非表示にしてtextだけを維持した。
36
+ - short textの`THINKING`/`DREAMING`で固定Bezier制御点が自己交差する問題をこの確認で検出した。cloud bodyへ176×96の最小viewportと比例制御点によるclosed splineを導入し、修正版で滑らかな輪郭を再確認した。
37
+ - root内の`script`、`foreignObject`、inline event handlerは0個だった。
38
+ - 初回登録時に検出したTurboWarp VMの`Unexpected input recieved in replaceUnsafeChars`は、`color2`/`color3`の明示後のrelease候補bundleでは再現せず、extension登録から全smoke終了まで新規warning/errorは0件だった。
39
+ - revealを`CHARACTER`、0.05秒に設定したsayは`H`、`Hello`、`Hello!`の順に進み、Chromiumのreadback、`Silhouette.unlazy()`、`getImageData()`関連warningは0件だった。
40
+ - shake中はsurface transformが変化して終了時に基準位置へ戻り、shape animationは`NORMAL`から`WAVY`へ完了した。close後はrootが0個となり、再度sayするとroot 1個へ復帰した。
41
+
42
+ stageはnative 480×360、small表示240×180、fullscreen表示3152×2364、custom native 640×480で確認した。各表示でrootの属性と`viewBox`はnative sizeに一致し、CSS表示領域はhostの拡大縮小へ追随した。sprite相対配置に加え、Stage targetの`HEADER_LIKE`も640×480上端のsafe area内へ表示された。最後に480×360、sprite相対`NORMAL`へ戻した。
43
+
44
+ ## Desktop smoke結果
45
+
46
+ 2026-08-20にTurboWarp Desktop 1.16.0へ同じrelease候補をtext入力し、unsandboxedで読み込んだ。実アプリのsprite/Stage targetとVM primitiveを使って確認した結果は次のとおり。
47
+
48
+ - Bubble paletteと全28 primitiveが登録され、say/thinkと全10 visual styleが表示された。short textの`THINKING`は176×96・trail `circle` 2個、`DREAMING`は176×96・`circle` 3個だった。
49
+ - revealは`H`、`Hell`、`Hello!`の順に進んだ。shakeはsurface transformを変化させて基準位置へ戻り、shape animationは`NORMAL`から`WAVY`へ完了した。
50
+ - native 480×360、small表示240×180、fullscreen表示955×716、custom native 640×480でrootがstageへ追随した。sprite相対配置とStage targetの`HEADER_LIKE`を確認した。
51
+ - spriteとStageの2 surfaceを同時表示した後、Stageのcloseで1 surface、spriteのcloseでroot 0となった。
52
+ - 正しいstage sizeを設定して再実行した区間では、consoleのwarning/errorは0件だった。最後にstageを480×360へ戻し、root 0を確認した。
53
+
54
+ ## Packager smoke結果
55
+
56
+ 2026-08-20にTurboWarp Packager Standalone 3.13.0で、Bubble blockを含むDesktopプロジェクトからプレーンHTMLのpreviewを生成した。Packagerの高度な設定ではrelease候補のdata URLがcustom extensionとして検出され、cached copyの埋め込みが有効だった。生成playerではBubbleの全28 primitiveがロードされた。
57
+
58
+ - sayで全10 visual styleを表示し、明示したthinkでもshort `DREAMING`が176×96・trail `circle` 3個となった。short `THINKING`は176×96・`circle` 2個だった。
59
+ - revealは`H`、`Hel`、`Hello!`の順に進んだ。`zoomIn`はscale 0.01から1へ完了し、shakeは位置を変化させて基準位置へ戻り、shape animationは`WAVY`へ完了した。
60
+ - sprite相対配置に加え、Stage targetの`HEADER_LIKE`をnative 480×360のsafe area内で確認した。
61
+ - Bubble表示中にcanvasの`toDataURL()`はPNG data URLを返し、`captureStream()`はvideo trackを1本返した。Bubble rootはcanvasの子ではなく、隣接する`.scratch-render-overlays`内にあるため、両APIにBubbleが含まれない既知制約を確認した。
62
+ - show/replace/closeを100回実行した後、Bubble root、surface、overlay childは0で、runtime listener数の増分も0だった。
63
+ - 全smoke終了までconsoleのwarning/errorは0件だった。
64
+
65
+ ## deterministic benchmark結果
66
+
67
+ `pnpm benchmark:render-backends`は、happy-dom上の同一fake rendererと決定的schedulerを使い、`svg-overlay`とrollback用`scratch-render`を同じ入力で比較する。2026-08-20にNode.js v26.7.0/arm64 macOSで実行した代表値は次のとおり。
68
+
69
+ | workload | svg-overlay | scratch-render | 判定 |
70
+ | ---------------------------------------------- | ---------------------------------------- | ---------------------------------------- | ----------------------------------- |
71
+ | typewriter、1,000回 | 62.254 ms、skin/drawable生成0 | 8.720 ms、skin 1,002、drawable 2 | overlayのrenderer resource生成0 |
72
+ | shape/shake/zoom、各10秒・合計1,875 callback | callback超過0%、p95 0.352 ms | callback超過0%、p95 0.157 ms | 差0 percentage points、許容値+5以内 |
73
+ | show/text・style更新/close、100回 | DOM/listener/skin/drawable残存すべて0 | DOM/listener/skin/drawable残存すべて0 | lifecycle residual 0 |
74
+
75
+ このbenchmarkが測るのはJavaScript callbackのCPU時間、renderer API呼び出し数、明示resourceの解放である。実browserのlayout/paint/composite、GC後の保持heap、host固有のframe dropを代替しない。数値は環境と実行ごとに変動するため、release判定ではresource残存とpercentage-point基準を主要判定値とする。
25
76
 
26
77
  ## release前のmanual gate
27
78
 
28
- 上流の[turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26)で公開されたhost-neutral layoutを0.8.0の通常dependencyとして採用し、[turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103)のDOM image resourceは0.12.0対応adapterから任意注入する。既定値変更後も次のmanual gateをrelease前に実施し、実測値をこの表へ記録する。
79
+ 上流の[turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26)で公開されたhost-neutral layoutを0.8.0の通常dependencyとして採用する。[turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103)のDOM image resourceをBubble所有adapterで変換し、stock拡張間のhandoffには[turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106)で公開された0.12.1 APIを使う。既定値変更後も次のmanual gateをrelease前に実施し、実測値をこの表へ記録する。
29
80
 
30
- | 項目 | host | 許容基準 | 結果 |
31
- | -------------------------- | ------------------------------------ | --------------------------------------------------------- | ------ |
32
- | say/think、全visual style | Web、Desktop、Packager | reference screenshotの主要geometry差異なし | 未測定 |
33
- | actor/background配置 | native 480×360と変更size、fullscreen | stage外clip、tail方向、centerに回帰なし | 未測定 |
34
- | typewriter | 1,000 update | Chromium readback警告0、`Silhouette.unlazy()`増分0 | 未測定 |
35
- | shape/shake/zoom | 各10秒 | dropped frame率が既存backend比+5 percentage points以内 | 未測定 |
36
- | memory/lifecycle | show/replace/stopを100回 | close後のBubble DOM、object URL、animation、listener残存0 | 未測定 |
37
- | raw canvas capture | `toDataURL()`、`captureStream()` | Bubbleが含まれない既知制約を確認 | 未測定 |
81
+ | 項目 | host | 許容基準 | 結果 |
82
+ | -------------------------- | ------------------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
83
+ | say/think、全visual style | Web、Desktop、Packager | reference screenshotの主要geometry差異なし | 3 hostでsay/thinkと全10styleを確認。short cloudの最小寸法とtrail数も一致 |
84
+ | actor/background配置 | native 480×360と変更size、fullscreen | stage外clip、tail方向、centerに回帰なし | Web/Desktopで480×360、small、fullscreen、640×480、Packagerで480×360のactor/backgroundを確認 |
85
+ | typewriter | 1,000 update | Chromium readback警告0、`Silhouette.unlazy()`増分0 | harnessで1,000 updateとresource生成0。3 hostの実revealで関連warning 0 |
86
+ | shape/shake/zoom | 各10秒 | dropped frame率が既存backend比+5 percentage points以内 | harnessで各10秒・0%対0%、差0 points。Web/Desktopでshape/shake、Packagerでshape/shake/zoomをsmoke済み |
87
+ | memory/lifecycle | show/replace/stopを100回 | close後のBubble DOM、object URL、animation、listener残存0 | harnessの全resource残存0。Packager実hostの100回後にDOM、surface、overlay child、listener増分0 |
88
+ | raw canvas capture | `toDataURL()`、`captureStream()` | Bubbleが含まれない既知制約を確認 | Packagerで両APIの成功と、Bubble rootがcanvas外のsibling overlayにあることを確認 |
38
89
 
39
90
  ## capture制約
40
91
 
@@ -0,0 +1,47 @@
1
+ # 0.9.0: TurboWarp互換の組み込みsay/think style
2
+
3
+ ## 概要
4
+
5
+ Bubble 0.9.0では、設定不要の基本経路をTurboWarp標準の`say`/`think`ブロックへ揃え、named custom styleは種類指定が競合しない1つの表示ブロックから利用できるようにする。
6
+
7
+ - 組み込みBubble style `say`はspeech本体とspeech tailを持つ。
8
+ - 組み込みBubble style `think`はthought本体とround trailを持つ。
9
+ - 本体とtail/trailの形は不可分なvisual styleであり、tail形状だけを独立して指定する設定は持たない。
10
+ - 短い`say [MESSAGE]`/`think [MESSAGE]`ブロックが対応する組み込みstyleを自動選択する。
11
+ - 両組み込みstyleは予約SVG Text profile `default`を使う。
12
+ - named custom styleは`show [MESSAGE] with bubble style [STYLE]`で表示する。
13
+
14
+ ## TurboWarpとの外観互換
15
+
16
+ 基本profileは内容に追従するgeometry、14px Helvetica、16px line height、最大行幅170px、最小text幅50px、padding 10px、corner 16px、白いfill、Scratchのtext/outline色、右側優先・収まりに応じた左反転、block入力の330文字上限、空文字でのcloseを使う。
17
+
18
+ Scratch互換SVG本体は4px strokeを白いfillより先に描く。fillがstrokeの内側半分を覆うため、画面上に見える輪郭はTurboWarp標準と同じ細さになる。Actor相対のspeech tail/thought trailはActorの方向を指す。
19
+
20
+ 日英マニュアルには、実際のTurboWarp Editorで撮影したStage結果と対応コードブロックの比較図版を含める。
21
+
22
+ - [Stage比較](./assets/turbowarp-say-think-stage-comparison.png)
23
+ - [ブロック比較](./assets/turbowarp-say-think-block-comparison.png)
24
+
25
+ ## ブロック契約と互換性
26
+
27
+ standalone manifestは31定義を持ち、paletteには29ブロックを表示する。
28
+
29
+ - 表示opcode `say`、`think`、`showWithBubbleStyle`を追加する。
30
+ - 旧`sayWithBubbleStyle`/`thinkWithBubbleStyle` opcodeは以前のargument既定値を維持したまま実装を残し、paletteから非表示にする。
31
+ - いずれかの旧opcodeを使う保存済みprojectは引き続き動作する。
32
+ - quick-startとlifecycle図版は、named custom style用の表示される統合`show`ブロックを使う。
33
+ - Bubbleを消す操作は`close this bubble`とし、設定済みの表示終了animation後に所有resourceを解放する。`hide`という別ブロックは設けない。
34
+
35
+ ## 検証
36
+
37
+ - `pnpm check`
38
+ - TypeScript declarationとComposition API consumerのcompile成功。
39
+ - 14 test files/125 tests成功。
40
+ - ドキュメントsource、Pages生成HTML、extension manifest、配布bundle、npm tarballを一括検証。
41
+ - 公開Stage/ブロック比較画像のhashがrepository assetと一致。
42
+
43
+ ## 更新とロールバック
44
+
45
+ 保存済みstyled say/thinkブロックを移行せず、extension URLを0.8.0から0.9.0へ置き換えられる。新しいscriptでは、基本profileには短い組み込みブロック、named custom styleには統合`show`ブロックを使う。
46
+
47
+ 回帰が見つかった場合はextension URLまたはnpm dependencyを0.8.0へpinし、修正版0.9.x patchを公開する。公開済み0.9.0 packageをunpublishしたり、対応するGit tag/GitHub Releaseを削除したりしない。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-bubble",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "Composable say and think bubbles with portrait layers and animated continue indicators for TurboWarp.",
5
5
  "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
6
6
  "type": "module",
@@ -37,6 +37,7 @@
37
37
  "dist/",
38
38
  "docs/",
39
39
  "README.md",
40
+ "README_ja.md",
40
41
  "LICENSE",
41
42
  "THIRD_PARTY_NOTICES.md"
42
43
  ],
@@ -65,7 +66,7 @@
65
66
  },
66
67
  "devDependencies": {
67
68
  "@eslint/js": "^10.0.1",
68
- "@kubohiroya/turbowarp-asset-manager": "0.12.0",
69
+ "@kubohiroya/turbowarp-asset-manager": "0.12.1",
69
70
  "@kubohiroya/turbowarp-async-input": "0.3.0",
70
71
  "@kubohiroya/turbowarp-runtime-expression": "0.3.0",
71
72
  "@kubohiroya/vite-plugin-turbowarp-extension": "0.1.1",
@@ -93,7 +94,7 @@
93
94
  ],
94
95
  "dependencies": {
95
96
  "@cto.af/linebreak": "4.0.3",
96
- "@kubohiroya/turbowarp-svg-text": "0.8.0"
97
+ "@kubohiroya/turbowarp-svg-text": "0.8.1"
97
98
  },
98
99
  "scripts": {
99
100
  "typecheck": "tsc --noEmit",
@@ -111,6 +112,7 @@
111
112
  "docs:pages": "node scripts/render-pages.mjs",
112
113
  "docs:pages:check": "node scripts/render-pages.mjs --check",
113
114
  "docs:check": "node scripts/check-block-manual.mjs && pnpm docs:pages:check",
115
+ "benchmark:render-backends": "pnpm build && node --expose-gc scripts/benchmark-render-backends.mjs",
114
116
  "test": "vitest run",
115
117
  "check:dist": "pnpm build && node scripts/check-dist.mjs",
116
118
  "pack:check": "npm pack --dry-run --ignore-scripts",