@kubohiroya/turbowarp-bubble 0.7.0 → 0.8.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.md CHANGED
@@ -34,7 +34,7 @@ flowchart LR
34
34
 
35
35
  | 領域 | このREADMEで説明する内容 | 現在の公開API |
36
36
  | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
37
- | 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(TurboWarpではSVG Text adapterを標準接続) |
37
+ | 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(SVG Text 0.8.0のhost-neutral layoutを標準接続) |
38
38
  | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | 実装済み(`revealNext`/`revealAll`/`finish`、対応ブロック) |
39
39
  | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | 実装済み(Asset Manager capability) |
40
40
  | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | 実装済み |
@@ -52,7 +52,7 @@ flowchart TB
52
52
  core["Bubble core\n外形・配置・ライフサイクル・animation state"]
53
53
  contract["BubbleTextCapability\nhost-neutralな文字契約"]
54
54
  twAdapter["TurboWarp Bubble adapter\nrenderer / runtime / targetへの接続"]
55
- svgAdapter["SVG Text adapter\nTurboWarpの文字skin・計測"]
55
+ svgAdapter["SVG Text 0.8 layout adapter\nrenderer非依存の行layout・計測"]
56
56
  assets["任意のImage / Audio capability\nportrait・lip-sync・音声"]
57
57
  input["任意のInput / Expression capability\n入力・待機条件"]
58
58
  host["独自Webアプリ / host"]
@@ -67,7 +67,58 @@ flowchart TB
67
67
  extension -."optional".-> input
68
68
  ```
69
69
 
70
- この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。`@kubohiroya/turbowarp-svg-text`は、その契約をTurboWarpのSVG skin・named style・文字幅計測へ接続するadapterです。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationは担当しません。TurboWarp adapterはSVG Text adapterを既定値として解決しますが、Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
70
+ この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.8.0`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
71
+
72
+ ### 描画backend(SVG overlayが既定)
73
+
74
+ `bubbleRenderBackend`を省略した場合の既定値は`"svg-overlay"`です。`renderer.addOverlay(root, "scale")`でstage canvas上に共有SVG rootを置き、body、tail、text、portrait、corner clip、continue indicatorをDOM要素として描画します。文字にはBubbleが内包するSVG Text 0.8.0のhost-neutral layoutを使います。この既定経路ではBubbleの表示、text更新、style更新、animationのために`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばず、Bubble由来の処理はscratch-renderの`SVGSkin`/`Silhouette`経路へ入りません。`"scratch-render"`は互換性とロールバックのため明示指定時だけ使用します。
75
+
76
+ ```ts
77
+ import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
78
+ import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
79
+ import {
80
+ createAssetManagerSvgOverlayImageCapability,
81
+ createSvgTextOverlayTextCapability,
82
+ createTurboWarpBubbleComposition,
83
+ } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
84
+
85
+ const assets = createAssetManagerComposition();
86
+ const textLayouts = createSvgTextLayoutComposition();
87
+
88
+ textLayouts.defineStyle({
89
+ name: "dialogue-text",
90
+ alignment: "left",
91
+ backgroundColor: "transparent",
92
+ font: "Helvetica",
93
+ fontPercent: 100,
94
+ textColor: "#575e75",
95
+ });
96
+
97
+ const bubbles = createTurboWarpBubbleComposition(runtime, {
98
+ svgOverlayTextCapability: createSvgTextOverlayTextCapability(textLayouts),
99
+ svgOverlayImageCapability:
100
+ createAssetManagerSvgOverlayImageCapability(assets),
101
+ });
102
+ ```
103
+
104
+ `svgOverlayTextCapability`を省略すると、BubbleはSVG Text 0.8.0のlayout compositionを生成します。`default`および初めて参照されたtext-style名は、Bubble内で背景透明のSVG Text既定styleとして初期化されます。上のようにcapabilityを明示すると、hostが定義したnamed styleへ置換できます。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"`です。
105
+
106
+ 既定文字providerは直接依存するSVG Text 0.8.0です。画像adapterには`resolveDOMImageResource()`を公開するAsset Manager 0.12.0以降が必要です。
107
+
108
+ 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)で公開済みです。Bubbleは上流の公開APIだけを利用し、private field参照やskinからの抽出では代替しません。必要な公開capabilityがないhostで`svg-overlay`を選ぶと`BUBBLE-RUNTIME-004`を返します。明示的に`svgOverlayUnsupportedBehavior: "fallback"`を指定した場合だけ`scratch-render`へ戻ります。
109
+
110
+ | host/取得方法 | `scratch-render` | `svg-overlay` |
111
+ | ----------------------------------------- | ---------------- | ------------------------------------------------------ |
112
+ | TurboWarp Web/Desktop | 対応 | overlay APIと上記公開capabilityがある構成で対応 |
113
+ | TurboWarp Packager/player HTML | 対応 | 同上。packaged DOMにoverlay rootを保持できる場合に対応 |
114
+ | `renderer.addOverlay`非対応host | 対応 | 既定は明示error。設定時だけfallback |
115
+ | OS screenshot/画面収録 | 表示される | 最終browser compositeに表示される |
116
+ | `renderer.canvas.toDataURL()`/`toBlob()` | 表示される | raw WebGL canvasには含まれない |
117
+ | `renderer.canvas.captureStream()` | 表示される | raw WebGL streamには含まれない |
118
+
119
+ 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)`を呼びます。
120
+
121
+ 自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.8.0の行座標・角丸、許可属性、object URL解放を検証します。Web/Desktop/Packagerでのvisual parityとframe time/memoryのmanual gateは[SVG overlay release note](docs/release-notes-0.8.0.md)に記録します。
71
122
 
72
123
  ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
73
124
 
@@ -150,13 +201,13 @@ Asset Managerを音声providerとして接続すると、次の音声を同じ
150
201
  | ------------------------------------------ | ------------------------------------------------------------------------------ |
151
202
  | `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
152
203
  | Bubble core(`composition`) | `BubbleTextCapability`契約、吹き出しsurface、配置、逐次表示、animation |
153
- | `@kubohiroya/turbowarp-svg-text` | `BubbleTextCapability`をTurboWarpの文字style・SVG skin・計測へ接続するadapter |
204
+ | `@kubohiroya/turbowarp-svg-text` | 0.8.0のhost-neutralなplain/ruby layoutと文字幅計測 |
154
205
  | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
155
206
  | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
156
207
  | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
157
208
  | アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
158
209
 
159
- Bubbleは依存パッケージを再exportしません。Composition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterだけが`@kubohiroya/turbowarp-svg-text`を既定のadapterとして解決します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Managerを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
210
+ Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterは直接依存するSVG Text 0.8.0のlayout compositionを既定providerとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Managerを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
160
211
 
161
212
  ### 自動改行と禁則処理の基盤
162
213
 
@@ -229,13 +280,7 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
229
280
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
230
281
  ```
231
282
 
232
- 現在のpeer dependency範囲は、SVG Textが`>=0.4.0 <1`、Asset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`です。4つすべてoptional peer dependencyで、SVG TextはTurboWarp adapterの既定adapterを使う場合だけ必要です。別の`textCapability`を注入するhostはSVG Textをインストールする必要がありません。
233
-
234
- TurboWarp adapterの既定文字経路を使う場合は、SVG Textを追加します。
235
-
236
- ```sh
237
- pnpm add @kubohiroya/turbowarp-svg-text
238
- ```
283
+ SVG Text 0.8.0は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールしたり、standalone SVG Text拡張を先に読み込んだりする必要はありません。optional peer dependencyはAsset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`です。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身が利用する0.8.0 dependencyは固定されます。
239
284
 
240
285
  画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
241
286
 
@@ -261,17 +306,13 @@ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget
261
306
 
262
307
  1. TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
263
308
  2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
264
- 3. SVG Textを読み込みます。Bubbleの文字style定義と文字幅計測に必要です。
265
- 4. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Managerを読み込みます。
266
- 5. `wait with this bubble until condition ...`を使う場合はAsync InputとRuntime Expressionを読み込みます。
267
- 6. 最後にBubbleを読み込みます。依存拡張を先に読み込むと、対応するブロックとcapabilityが接続されます。
309
+ 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Managerを読み込みます。
310
+ 4. `wait with this bubble until condition ...`を使う場合はAsync InputとRuntime Expressionを読み込みます。
311
+ 5. 最後にBubbleを読み込みます。SVG Text 0.8.0のlayout providerはBubble bundleに含まれます。
268
312
 
269
- 最小構成はTemporary Variables、SVG Text、Bubbleです。Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define text style`、`define bubble style`、`say`または`think`の順でブロックを配置します。
313
+ 文字だけの最小構成はBubbleです。Temporary Variables、Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define bubble style`、`say`または`think`の順でブロックを配置します。text styleには`default`または任意の名前を指定でき、standalone既定providerでは背景透明のSVG Text既定値として初期化されます。
270
314
 
271
315
  ```text
272
- # SVG Text(必須)
273
- https://unpkg.com/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js
274
-
275
316
  # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
276
317
  https://unpkg.com/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js
277
318
 
@@ -280,7 +321,7 @@ https://unpkg.com/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js
280
321
  https://unpkg.com/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js
281
322
 
282
323
  # Bubble(必ず最後)
283
- https://unpkg.com/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js
324
+ https://unpkg.com/@kubohiroya/turbowarp-bubble@0.8.0/dist/turbowarp-bubble.js
284
325
  ```
285
326
 
286
327
  TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発中は、リポジトリをローカルHTTPサーバーで配信して`dist/turbowarp-bubble.js`を指定できます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。
@@ -300,13 +341,13 @@ Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカス
300
341
 
301
342
  Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
302
343
 
303
- Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。SVG本体、文字、表情ベース、目パチ、口パク、次へアイコンのrenderer drawableは自動生成されるため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
344
+ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。既定backendではSVG本体、文字、表情ベース、目パチ、口パク、次へアイコンを共有overlay DOM内のレイヤーとして生成するため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
304
345
 
305
346
  #### 提供ブロック
306
347
 
307
348
  | ブロック | 動作 |
308
349
  | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
309
- | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義し、SVG Textで定義した文字style名を関連付ける |
350
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義し、文字layout style名を関連付ける |
310
351
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
311
352
  | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
312
353
  | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
@@ -432,7 +473,7 @@ animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.
432
473
  #### ブロック構成例
433
474
 
434
475
  ```text
435
- define bubble style [hero-dialogue] using text style [dialogue-text]
476
+ define bubble style [hero-dialogue] using text style [default]
436
477
  set bubble placement [up-right] for bubble style [hero-dialogue]
437
478
  set bubble distance [12] for bubble style [hero-dialogue]
438
479
  set bubble visual style [NORMAL] for bubble style [hero-dialogue]
@@ -450,11 +491,11 @@ wait with this bubble until condition [input == "pressed"] or timeout after [10]
450
491
  close this bubble
451
492
  ```
452
493
 
453
- プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、SVG text skin、drawableを自動解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
494
+ プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、overlay DOM、画像leaseを自動解放します。明示的に`scratch-render`を選んだ場合は、従来どおり所有するSVG skinとdrawableも解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
454
495
 
455
496
  ### Composition API
456
497
 
457
- TurboWarp runtimeのrenderer、SVG Textへ直接接続するhostでは、公開adapterを利用できます。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
498
+ TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではSVG Text 0.8.0のlayout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
458
499
 
459
500
  ```ts
460
501
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -485,7 +526,7 @@ const bubbles = createBubbleComposition({
485
526
  });
486
527
  ```
487
528
 
488
- `declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleTextCapability`(文字skinの適用・計測・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。`@kubohiroya/turbowarp-svg-text/composition`を使う場合は、`createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))`で`textCapability`へ変換します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
529
+ `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)`を使えます。
489
530
 
490
531
  テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
491
532
 
@@ -493,7 +534,7 @@ const bubbles = createBubbleComposition({
493
534
 
494
535
  surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
495
536
 
496
- - `text`: `textCapability`が文字スキンを適用するtarget
537
+ - `text`: `textCapability`が文字layoutを適用するtarget
497
538
  - `portraitBase`: キャラクター表情のベース画像target
498
539
  - `portraitBlink`: 目パチ差分target
499
540
  - `portraitLipSync`: 口パク差分target
@@ -2,6 +2,16 @@
2
2
 
3
3
  The distributed JavaScript bundles include the following third-party software.
4
4
 
5
+ ## @kubohiroya/turbowarp-svg-text
6
+
7
+ Repository: https://github.com/kubohiroya/turbowarp-svg-text
8
+
9
+ Copyright (c) Hiroya Kubo
10
+
11
+ This component is distributed under the Mozilla Public License 2.0. Its
12
+ source code is available from the repository above. The license text is
13
+ available at https://www.mozilla.org/MPL/2.0/.
14
+
5
15
  ## jsclipper
6
16
 
7
17
  Repository: https://github.com/platener/jsclipper