@kubohiroya/turbowarp-bubble 0.7.0 → 0.9.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
@@ -1,61 +1,65 @@
1
1
  # TurboWarp Bubble
2
2
 
3
- `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
3
+ **English** | [日本語](README_ja.md)
4
4
 
5
- ## READMEの読み方
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
- 利用環境を先に決めると、必要な部分だけを読めます。
7
+ The current release is Bubble 0.9.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.8.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. See the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles and TurboWarp-compatible basic bubbles.
8
8
 
9
- 1. TurboWarpでブロックを使う場合は、後述の[TurboWarp機能拡張](#turbowarp機能拡張)と[提供ブロック](#提供ブロック)を確認します。
10
- 2. 独自Webアプリやhostから使う場合は、[Composition API](#composition-api)と[Styleと表示](#styleと表示)を確認します。
11
- 3. 表示単位、改行、外形、portrait、animationの仕様を知りたい場合は、[概念と表示仕様](#概念と表示仕様)を参照します。
12
- 4. Scratch公式エディターでの利用可否は、[Scratchとの互換性](#scratchとの互換性)に記載しています。
9
+ ## How to read this README
13
10
 
14
- ## 機能の全体像
11
+ Choose your environment first so that you only need to read the relevant sections.
15
12
 
16
- Bubbleは、文字を描くText provider、吹き出しの外形と配置を管理するBubble layer、画像・音声を解決する任意のAsset capabilityを組み合わせます。これにより、TurboWarpの機能拡張としても、アプリのhostから呼び出すcompositionとしても同じ表示モデルを利用できます。
13
+ 1. To use blocks in TurboWarp, see [TurboWarp extension](#turbowarp-extension) and [Available blocks](#available-blocks).
14
+ 2. To use Bubble from a custom web application or host, see [Composition API](#composition-api) and [Styles and display](#styles-and-display).
15
+ 3. For the specifications of reveal units, line wrapping, shapes, portraits, and animations, see [Concepts and display specifications](#concepts-and-display-specifications).
16
+ 4. See [Scratch compatibility](#scratch-compatibility) for availability in the official Scratch editor.
17
+
18
+ ## Feature overview
19
+
20
+ Bubble combines a Text provider that draws text, a Bubble layer that manages the bubble outline and placement, and optional Asset capabilities that resolve images and audio. This lets the TurboWarp extension and compositions called by application hosts use the same display model.
17
21
 
18
22
  ```mermaid
19
23
  flowchart LR
20
- input[セリフ入力] --> reveal[表示単位の選択]
24
+ input[Dialogue input] --> reveal[Select reveal unit]
21
25
  reveal --> text[CHARACTER / WORD / LINE / BLOCK]
22
- text --> layout[改行・サイズ計算]
23
- layout --> body[Bubble外形・tail・placement]
24
- text --> voice[フルボイス/単位ごとの効果音]
25
- body --> portrait[portraitレイヤー]
26
- portrait --> blink[blink]
27
- portrait --> lipsync[lip-sync]
28
- body --> motion[表示開始・表示中・表示終了animation]
29
- body --> wait[continue待機]
30
- wait --> close[終了・resource解放]
26
+ text --> layout[Line wrapping and size calculation]
27
+ layout --> body[Bubble outline, tail, and placement]
28
+ text --> voice[Full voice and per-unit sound effects]
29
+ body --> portrait[Portrait layers]
30
+ portrait --> blink[Blink]
31
+ portrait --> lipsync[Lip-sync]
32
+ body --> motion[Show, active, and hide animations]
33
+ body --> wait[Wait for continue]
34
+ wait --> close[Close and release resources]
31
35
  ```
32
36
 
33
- このREADMEでは、現在公開している機能と、3層構成で接続する表示仕様を同じ用語で説明します。公開APIにまだ現れていない仕様は「実装状況」欄で明示しています。
37
+ The table below maps the 0.9.0 feature set to its public entry points. The standalone extension exposes 29 palette blocks generated from 31 definitions; two hidden legacy definitions keep previously saved styled say/think blocks working. The full visible list appears under [Available blocks](#available-blocks).
34
38
 
35
- | 領域 | このREADMEで説明する内容 | 現在の公開API |
36
- | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
37
- | 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(TurboWarpではSVG Text adapterを標準接続) |
38
- | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | 実装済み(`revealNext`/`revealAll`/`finish`、対応ブロック) |
39
- | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | 実装済み(Asset Manager capability) |
40
- | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | 実装済み |
41
- | 表示mode | `talking`/`awaiting-continue`/`idle` | 実装済み |
42
- | 表示開始・表示中・表示終了animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | 実装済み(`handle.animate`、style設定、対応ブロック) |
39
+ | Area | What this README covers | Public entry points |
40
+ | --------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
41
+ | Text rendering and wrapping | `BubbleTextCapability`, named styles, measured width, `maxWidth`, and UAX #14-compliant wrapping | `composition`, `turbowarp-adapter`, and extension blocks |
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 |
44
+ | Bubble outline | Visual styles such as `NORMAL`, placement, tail, offset, and scale | Composition API, TurboWarp adapter, and blocks |
45
+ | Display mode | `talking` / `awaiting-continue` / `idle` | `BubbleHandle.setAnimationMode()` and the matching block |
46
+ | Show, active, and hide animations | `fadeIn`, `floatIn`, `shake`, `animateBubbleShape`, and others | Style settings, `BubbleHandle.animate()`, and blocks |
43
47
 
44
- ## 概念と表示仕様
48
+ ## Concepts and display specifications
45
49
 
46
- ### 3層構成と責務
50
+ ### Three-layer architecture and responsibilities
47
51
 
48
- 依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。矢印は「利用する側」から「利用される側」へ向けています。
52
+ The dependency structure places the pure Bubble composition at the center, with the TurboWarp adapter and each provider around it. Arrows point from the consumer to the dependency it uses.
49
53
 
50
54
  ```mermaid
51
55
  flowchart TB
52
- core["Bubble core\n外形・配置・ライフサイクル・animation state"]
53
- contract["BubbleTextCapability\nhost-neutralな文字契約"]
54
- twAdapter["TurboWarp Bubble adapter\nrenderer / runtime / targetへの接続"]
55
- svgAdapter["SVG Text adapter\nTurboWarpの文字skin・計測"]
56
- assets["任意のImage / Audio capability\nportrait・lip-sync・音声"]
57
- input["任意のInput / Expression capability\n入力・待機条件"]
58
- host["独自Webアプリ / host"]
56
+ core["Bubble core\noutline, placement, lifecycle, and animation state"]
57
+ contract["BubbleTextCapability\nhost-neutral text contract"]
58
+ twAdapter["TurboWarp Bubble adapter\nconnects to renderer / runtime / target"]
59
+ svgAdapter["SVG Text 0.8 layout adapter\nrenderer-independent line layout and measurement"]
60
+ assets["Optional Image / Audio capabilities\nportrait, lip-sync, and audio"]
61
+ input["Optional Input / Expression capabilities\ninput and wait conditions"]
62
+ host["Custom web application / host"]
59
63
  extension["TurboWarp extension\nblocks / Scratch target"]
60
64
  core -->|"consumes"| contract
61
65
  svgAdapter -->|"implements"| contract
@@ -67,62 +71,115 @@ flowchart TB
67
71
  extension -."optional".-> input
68
72
  ```
69
73
 
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は対応機能を使う場合だけ接続します。
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.
75
+
76
+ ### Rendering backend (SVG overlay by default)
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.
79
+
80
+ When the stock Asset Manager 0.12.1 extension is loaded before Bubble in TurboWarp, Bubble calls `runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()` the first time a portrait or another image feature is used. It then lazily connects to the same registry populated by Asset Manager blocks. Asset Manager is not loaded when only text is used. A Composition API host can inject capabilities explicitly as follows.
81
+
82
+ ```ts
83
+ import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
84
+ import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
85
+ import {
86
+ createAssetManagerSvgOverlayImageCapability,
87
+ createSvgTextOverlayTextCapability,
88
+ createTurboWarpBubbleComposition,
89
+ } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
90
+
91
+ const assets = createAssetManagerComposition();
92
+ const textLayouts = createSvgTextLayoutComposition();
93
+
94
+ textLayouts.defineStyle({
95
+ name: "dialogue-text",
96
+ alignment: "left",
97
+ backgroundColor: "transparent",
98
+ font: "Helvetica",
99
+ fontPercent: 100,
100
+ textColor: "#575e75",
101
+ });
102
+
103
+ const bubbles = createTurboWarpBubbleComposition(runtime, {
104
+ svgOverlayTextCapability: createSvgTextOverlayTextCapability(textLayouts),
105
+ svgOverlayImageCapability:
106
+ createAssetManagerSvgOverlayImageCapability(assets),
107
+ });
108
+ ```
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"`.
111
+
112
+ The default text provider is the directly depended-on SVG Text 0.8.1. Preserving styles from a separately loaded stock SVG Text extension requires its 0.8.1 `getLayoutCapability()`. Automatic image connection between stock extensions requires Asset Manager 0.12.1 or later, which exposes `getDOMImageCapability()`. The lower-level path that explicitly injects `resolveDOMImageResource()` from the Composition API is available with Asset Manager 0.12.0 or later.
113
+
114
+ The skin-independent contracts for SVG Text and Asset Manager are published in [turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26), [turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103), and the stock registry handoff in [turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106). Bubble uses only public upstream APIs and never substitutes private-field access or extraction from skins. Selecting `svg-overlay` on a host without the overlay API returns `BUBBLE-RUNTIME-004`. Using images without either Asset Manager 0.12.1's public capability or an explicitly injected capability returns `BUBBLE-RUNTIME-002`. Bubble falls back to `scratch-render` on a host without the overlay API only when `svgOverlayUnsupportedBehavior: "fallback"` is explicitly specified.
71
115
 
72
- ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
116
+ | Host / capture method | `scratch-render` | `svg-overlay` |
117
+ | ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------- |
118
+ | TurboWarp Web / Desktop | Supported | Supported when the overlay API and the public capabilities described above are available |
119
+ | TurboWarp Packager / player HTML | Supported | Supported under the same conditions when the packaged DOM can retain the overlay root |
120
+ | Host without `renderer.addOverlay` | Supported | Explicit error by default; fallback only when configured |
121
+ | OS screenshot / screen recording | Included | Included in the final browser composite |
122
+ | `renderer.canvas.toDataURL()` / `toBlob()` | Included | Not included in the raw WebGL canvas |
123
+ | `renderer.canvas.captureStream()` | Included | Not included in the raw WebGL stream |
73
124
 
74
- セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
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.
75
126
 
76
- 仕様上の綴りは`CHARACTER`です(`charactor`ではありません)。`BLOCK`は、改行を含む複数行を一つの表示単位として扱う名前で、ここでいうblockはScratchのblockではありません。
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).
128
+
129
+ ### Progressive reveal units (CHARACTER / WORD / LINE / BLOCK)
130
+
131
+ Instead of only showing the entire line at once, Bubble can progressively add content one selected unit at a time. `CHARACTER` means a displayed grapheme cluster, not a morphological token, so combining characters and emoji are not split in the middle.
132
+
133
+ The spelling in the specification is `CHARACTER`, not `charactor`. `BLOCK` treats multiple lines, including line breaks, as one reveal unit; block here does not mean a Scratch block.
77
134
 
78
135
  ```mermaid
79
136
  flowchart LR
80
- source["全文: 私の/名前は/中野/です"] --> mode{"表示単位"}
137
+ source["Full text: 私の/名前は/中野/です"] --> mode{"Reveal unit"}
81
138
  mode -->|CHARACTER| c["私 → 私の → 私の/ → …"]
82
139
  mode -->|WORD| w["私の → 私の/名前は → …"]
83
- mode -->|LINE| l["1行ずつ追加"]
84
- mode -->|BLOCK| b["複数行/段落をまとめて追加"]
85
- delimiter["任意の区切り文字集合<br/>例: スラッシュ、空白、縦線"] -.-> w
86
- visibility{"区切り文字の表示"} -->|visible| shown["区切り文字も描画"]
87
- visibility -->|invisible| hidden["区切り文字を隠して描画"]
140
+ mode -->|LINE| l["Add one line at a time"]
141
+ mode -->|BLOCK| b["Add multiple lines / a paragraph at once"]
142
+ delimiter["Arbitrary delimiter set<br/>for example: slash, space, or vertical bar"] -.-> w
143
+ visibility{"Show delimiters"} -->|visible| shown["Render delimiters"]
144
+ visibility -->|invisible| hidden["Hide delimiters"]
88
145
  delimiter --> visibility
89
146
  ```
90
147
 
91
- ### WORDの区切り文字
148
+ ### WORD delimiters
92
149
 
93
- 日本語の形態素解析は行いません。`WORD`は空白で区切る言語、または利用者が区切りを埋め込める言語を対象にします。例えば`私の/名前は/中野/です`を入力し、`/`をWORD delimiterにして不可視にすれば、`私の`→`名前は`→`中野`→`です`の順で表示できます。区切り文字を可視にすれば、スラッシュを演出として残せます。
150
+ Bubble does not perform Japanese morphological analysis. `WORD` is intended for languages separated by spaces or languages in which the user can insert delimiters. For example, enter `私の/名前は/中野/です`, set `/` as an invisible WORD delimiter, and the units appear in the order `私の` → `名前は` → `中野` → `です`. Making the delimiter visible preserves the slashes as part of the presentation.
94
151
 
95
- 区切り文字は単一文字に限定せず、任意の文字集合として指定します。delimiter自体を表示単位に含めるか、取り除いてからText providerへ渡すかを選べるようにします。
152
+ Delimiters are not limited to one character; they can be specified as an arbitrary character set. You can choose whether to include each delimiter in the reveal unit or remove it before passing the text to the Text provider.
96
153
 
97
- ### DYNAMICとRESERVED
154
+ ### DYNAMIC and RESERVED
98
155
 
99
- 逐次表示中の吹き出しサイズは、次の2方式を選べるようにします。
156
+ Two bubble-sizing strategies are available during progressive reveal.
100
157
 
101
158
  ```mermaid
102
159
  sequenceDiagram
103
160
  participant Host as Host
104
161
  participant Bubble as Bubble surface
105
162
  participant Text as Text provider
106
- Host->>Text: 全文をmeasure
163
+ Host->>Text: Measure the full text
107
164
  alt RESERVED
108
- Text-->>Bubble: 最終幅・最終行数
109
- Bubble->>Bubble: 最終サイズを先に確保
110
- loop 表示単位ごと
111
- Host->>Text: 可視範囲を更新
112
- Text-->>Bubble: 文字だけ更新
165
+ Text-->>Bubble: Final width and line count
166
+ Bubble->>Bubble: Reserve final size in advance
167
+ loop For each reveal unit
168
+ Host->>Text: Update visible range
169
+ Text-->>Bubble: Update text only
113
170
  end
114
171
  else DYNAMIC
115
- loop 表示単位ごと
116
- Host->>Text: 可視範囲を更新
117
- Text-->>Bubble: 現在の幅・行数
118
- Bubble->>Bubble: 外形とplacementを再計算
172
+ loop For each reveal unit
173
+ Host->>Text: Update visible range
174
+ Text-->>Bubble: Current width and line count
175
+ Bubble->>Bubble: Recalculate outline and placement
119
176
  end
120
177
  end
121
178
  ```
122
179
 
123
- `RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。いずれもBubble外形のanimationやportraitレイヤーとは独立したレイアウト方針です。Composition APIではstyleの`reveal`、`handle.revealNext()`、`handle.revealAll()`が分割・タイミングの接続点になり、`intervalSeconds`を指定した自動送りにも対応します。
180
+ `RESERVED` keeps the outline more stable during reveal, while `DYNAMIC` avoids extra whitespace in short lines. `DYNAMIC` is the default layout. In `normalizeBubbleReveal` and the Composition API, the default `intervalSeconds` is `0`, which disables automatic advance; the extension block starts with `0.05` in its seconds field. Both layouts are independent of bubble-outline animations and portrait layers. The style's `reveal`, `handle.revealNext()`, and `handle.revealAll()` are the integration points for splitting and timing; a positive `intervalSeconds` enables automatic advance.
124
181
 
125
- 逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
182
+ To reveal all remaining units before entering the waiting state, use a finish operation with an explicit reveal unit.
126
183
 
127
184
  ```text
128
185
  finish [CHARACTER / WORD / LINE / BLOCK]
@@ -130,39 +187,39 @@ finish [CHARACTER / WORD / LINE / BLOCK]
130
187
  or timeout after [TIMEOUT] seconds
131
188
  ```
132
189
 
133
- `CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または表示終了animationを開始します。Composition APIでは`handle.finish({ unit, condition, timeoutSeconds })`、手続き型拡張では`finish [UNIT] ...`ブロックを使います。
190
+ When `CONDITION` becomes true, Bubble reveals every remaining unit. If it does not become true, the same completion process begins after `TIMEOUT` seconds. Set `TIMEOUT` to `0` for no time limit. On completion, Bubble can move to `awaiting-continue`, or the host can start `close` or the hide animation. Use `handle.finish({ unit, condition, timeoutSeconds })` in the Composition API or the `finish [UNIT] ...` block in the procedural extension. The block requires Runtime Expression; Async Input is needed as well only when input events update variables used by the condition.
134
191
 
135
- ### 音声と表示単位
192
+ ### Audio and reveal units
136
193
 
137
- `finish`は公開Composition APIの`handle.finish({ unit, condition, timeoutSeconds })`と、TurboWarpの`finish [UNIT] ...`ブロックで利用できます。これは逐次表示を最後まで進め、条件成立またはtimeoutで音声と待機状態を確定します。
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.
138
195
 
139
- Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
196
+ When Asset Manager is connected as the audio provider, the following audio can share the same display lifecycle:
140
197
 
141
- - 表示開始時のフルボイス
142
- - `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
143
- - 表示終了、continue待機、timeoutの通知音
198
+ - Full voice playback when display starts
199
+ - A sound effect each time one `CHARACTER`, `WORD`, `LINE`, or `BLOCK` unit is revealed
200
+ - A finish cue after the Composition API's `finish` condition succeeds or its timeout expires
144
201
 
145
- 表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声assetを再生する経路です。音声がない場合でも、文字表示・portrait・Bubble外形は独立して利用できます。
202
+ Per-unit effects play named audio assets; they do not synthesize the displayed string as speech. TurboWarp blocks expose voice and per-unit reveal sounds; `audio.finish` is currently a Composition API setting. Text, portraits, and the Bubble outline remain independently usable when no audio is provided.
146
203
 
147
- ### パッケージ境界
204
+ ### Package boundaries
148
205
 
149
- | パッケージ | 責務 |
150
- | ------------------------------------------ | ------------------------------------------------------------------------------ |
151
- | `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
152
- | Bubble core(`composition`) | `BubbleTextCapability`契約、吹き出しsurface、配置、逐次表示、animation |
153
- | `@kubohiroya/turbowarp-svg-text` | `BubbleTextCapability`をTurboWarpの文字style・SVG skin・計測へ接続するadapter |
154
- | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
155
- | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
156
- | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
157
- | アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
206
+ | Package | Responsibility |
207
+ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
208
+ | `@kubohiroya/turbowarp-asset-manager` | Connect optional Image / Audio capabilities to TurboWarp assets (image resolution and audio playback) |
209
+ | Bubble core (`composition`) | `BubbleTextCapability` contract, bubble surfaces, placement, progressive reveal, and animation |
210
+ | `@kubohiroya/turbowarp-svg-text` | Host-neutral plain / ruby layout, stock named-style handoff, and text-width measurement in version 0.8.1 |
211
+ | `@kubohiroya/turbowarp-async-input` | Reflect key and tap input in Temporary Variables runtime variables |
212
+ | `@kubohiroya/turbowarp-runtime-expression` | Safely evaluate wait conditions that refer to runtime variables |
213
+ | `@kubohiroya/turbowarp-bubble` | Bubble surfaces, placement, progressive reveal, say / think, expression layers, animation, and input waiting |
214
+ | Application / host | Convert application-specific input to Composition API calls as needed |
158
215
 
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を使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
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.
160
217
 
161
- ### 自動改行と禁則処理の基盤
218
+ ### Automatic wrapping and line-breaking rules
162
219
 
163
- Bubbleの任意`maxWidth`による自動改行では、`@cto.af/linebreak`を利用してUnicode UAX #14準拠の改行可能位置を求めます。依存は`LineBreakProvider` interfaceの内側へ閉じ込め、実際のフォントで測った幅から、上限内に収まる最も後ろの候補をBubble側で選びます。
220
+ For automatic wrapping with the optional `maxWidth`, Bubble uses `@cto.af/linebreak` to find Unicode UAX #14-compliant line-break opportunities. The dependency is contained behind the `LineBreakProvider` interface. Bubble measures text using the actual font and selects the last candidate that fits within the limit.
164
221
 
165
- `UnicodeLineBreakProvider`はUAX #14の候補を`Intl.Segmenter`の書記素境界で絞るため、句読点や小書き仮名の禁則に加え、結合文字や絵文字の途中分割も避けます。明示改行は維持し、URLなど分割可能な候補がない文字列だけを書記素境界でfallback分割します。
222
+ `UnicodeLineBreakProvider` restricts UAX #14 candidates to grapheme boundaries reported by `Intl.Segmenter`. In addition to applying line-start and line-end restrictions for punctuation and small kana, this prevents splitting combining characters or emoji. Explicit line breaks are preserved. Only strings with no valid break candidate, such as some URLs, fall back to splitting at grapheme boundaries.
166
223
 
167
224
  ```ts
168
225
  import { wrapText } from "@kubohiroya/turbowarp-bubble/composition";
@@ -174,23 +231,23 @@ const layout = wrapText({
174
231
  });
175
232
  ```
176
233
 
177
- Composition APIのBubble styleへ`maxWidth`と任意の`textLocale`を渡すと、Text capabilityの`measureText`を使ってこの`wrapText`基盤が実際の表示文字列を自動改行します。SVG Textまたはhost側のText capabilityが`measureText`を提供しない場合、`maxWidth`を使った表示は明示的なcapabilityエラーになります。
234
+ Passing `maxWidth` and an optional `textLocale` in a Composition API Bubble style makes this `wrapText` foundation wrap the actual displayed string using the Text capability's `measureText`. If SVG Text or a host-provided Text capability does not provide `measureText`, displaying content with `maxWidth` produces an explicit capability error.
178
235
 
179
- ![maxWidthの違いによる自動改行と、日本語禁則処理の例](docs/assets/width-linebreak-guide.svg)
236
+ ![Automatic wrapping at different maxWidth values with Japanese line-breaking rules](docs/assets/width-linebreak-guide.svg)
180
237
 
181
- 図の各行はproductionの`wrapText`を直接呼んだ結果です。図版専用の手作業改行は使っていません。
238
+ Every line in the figure is produced by calling the production `wrapText` implementation directly; the illustration does not use manually inserted line breaks.
182
239
 
183
- ### Bubble visual styleの形状
240
+ ### Bubble visual-style shapes
184
241
 
185
- 形状候補は`NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`です。
242
+ The available shapes are `NORMAL`, `THINKING`, `DREAMING`, `YELLING`, `OFF_PANEL`, `WAVY`, `WHISPERING`, `ANNOUNCEMENT`, `NARRATION`, and `NO_BUBBLE`.
186
243
 
187
- ![10種類のBubble visual styleを同じSVG rendererで比較する図](docs/assets/bubble-style-gallery.svg)
244
+ ![Ten Bubble visual styles compared using the same SVG renderer](docs/assets/bubble-style-gallery.svg)
188
245
 
189
- この図はBubble側の共有`renderBubbleSvg`から生成しています。三角形tailを持つ形状は、tail基部の2点を実際の本体border上から求め、[platener/jsclipper](https://github.com/platener/jsclipper)で本体polygonとtail三角形の和集合を作り、単一の外周pathだけを描画します。`THINKING`/`DREAMING`の丸trailは独立形状のままです。
246
+ This figure is generated with Bubble's shared `renderBubbleSvg`. For shapes with a triangular tail, the renderer finds the two tail-base points on the actual body border, unions the body polygon with the tail triangle using [platener/jsclipper](https://github.com/platener/jsclipper), and draws only the single resulting outline path. The round trails used by `THINKING` and `DREAMING` remain separate shapes.
190
247
 
191
- standalone機能拡張では、`set bubble visual style`ブロックで形状を選択できます。runtimeは共有`renderBubbleSvg`から本体用SVG skinを生成し、文字・表情より背面の専用drawableへ適用します。Actor相対ではActorを向くtailを生成し、背景相対ではtailを付けません。`NO_BUBBLE`では本体を非表示にして文字・表情などだけを表示します。`NEGATIVE`はfill colorとborder colorで表現できるため独立styleにせず、orientationとsegmentsも公開入力にしません。
248
+ In the standalone extension, select a shape with the `set bubble visual style` block. Both rendering backends use the shared `renderBubbleSvg`: the default overlay reconstructs its canonical SVG as allowlisted DOM elements, while explicit `scratch-render` mode applies an SVG skin to a dedicated drawable. In both cases the body stays behind the text and expressions. Actor-relative bubbles generate a tail pointing toward the Actor; background-relative bubbles have no tail. `NO_BUBBLE` hides the body and displays only the text, expressions, and other content. `NEGATIVE` can be represented using the fill and border colors, so it is not a separate style; orientation and segments are not exposed as inputs either.
192
249
 
193
- portraitは`left`/`right`/`top-left`/`top-right`/`bottom-left`/`bottom-right`へ配置し、portrait固有の`[x, y, zoom]`と角丸半径を指定できます。standalone機能拡張では`set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px ...`を使い、`none`でportrait全体を解除します。Composition APIでは次のようにstyleへ含めます。
250
+ A portrait can be placed at `left`, `right`, `top-left`, `top-right`, `bottom-left`, or `bottom-right`, with a portrait-specific `[x, y, zoom]` and corner radius. Placement defaults to `left`, the transform defaults to `[0, 0, 100]`, and corner radius defaults to `0`. Zoom must be greater than zero, and corner radius cannot be negative. In the standalone extension, use `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px ...`; select `none` to remove the entire portrait. In the Composition API, include it in the style as follows.
194
251
 
195
252
  ```ts
196
253
  portrait: {
@@ -201,23 +258,23 @@ portrait: {
201
258
  }
202
259
  ```
203
260
 
204
- 配布bundleに含まれる依存ライブラリのライセンスは、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)を参照してください。
261
+ See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the licenses of dependencies included in the distributed bundle.
205
262
 
206
- ## 利用方法
263
+ ## Usage
207
264
 
208
- ### インストール
265
+ ### Installation
209
266
 
210
267
  ```sh
211
268
  pnpm add @kubohiroya/turbowarp-bubble
212
269
  ```
213
270
 
214
- npmを使う場合は同じ依存を次のように追加します。
271
+ With npm, install the same dependency as follows.
215
272
 
216
273
  ```sh
217
274
  npm install @kubohiroya/turbowarp-bubble
218
275
  ```
219
276
 
220
- 逐次表示の正規化と文字列分割だけが必要な利用側は、Bubble composition全体を含めずに小さな`reveal` entryをimportできます。
277
+ Consumers that need only progressive-reveal normalization and string splitting can import the small `reveal` entry point without including the entire Bubble composition.
221
278
 
222
279
  ```ts
223
280
  import {
@@ -229,15 +286,11 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
229
286
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
230
287
  ```
231
288
 
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を追加します。
289
+ SVG Text 0.8.1 is included as a regular dependency and serves as the default skin-independent text provider. You do not need to install it separately. Loading the standalone SVG Text 0.8.1 extension first is optional, but doing so lets Bubble reuse styles defined by its project blocks through the public handoff. Bubble's declared optional peer ranges remain `>=0.7.0 <1` for Asset Manager and `>=0.3.0 <1` for both Async Input and Runtime Expression; the currently published and recommended extension versions are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. Even when a host injects a custom `svgOverlayTextCapability`, Bubble's own SVG Text dependency remains fixed at version 0.8.1.
235
290
 
236
- ```sh
237
- pnpm add @kubohiroya/turbowarp-svg-text
238
- ```
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.
239
292
 
240
- 画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
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.
241
294
 
242
295
  ```sh
243
296
  pnpm add @kubohiroya/turbowarp-asset-manager \
@@ -251,92 +304,119 @@ npm install @kubohiroya/turbowarp-asset-manager \
251
304
  @kubohiroya/turbowarp-runtime-expression
252
305
  ```
253
306
 
254
- ### TurboWarp機能拡張
307
+ ### TurboWarp extension
255
308
 
256
- ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
309
+ For instructions covering block assembly, preparation of expression variants, input waiting, clones, and troubleshooting, see the block manual ([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/)). It also includes an animation example covering `talking`, the transition to `awaiting-continue`, successful input, and `close`.
257
310
 
258
- #### TurboWarpでの導入
311
+ In the Kamishibai DSL 4.0 combined bundle, open this manual with the documentation button directly below the **Bubble** member heading. The bundled palette keeps the same style, placement, portrait, reveal, audio, wait, animation, clone, and cleanup behavior; its member namespace and Bubble icon identify the originating extension.
259
312
 
260
- TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget APIへ接続する**unsandboxedカスタム拡張機能**です。TurboWarp Editorでは、次の順で読み込みます。
313
+ #### Loading in TurboWarp
261
314
 
262
- 1. TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
263
- 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が接続されます。
315
+ TurboWarp Bubble's `dist/turbowarp-bubble.js` is an **unsandboxed custom extension** that connects to TurboWarp's renderer and target APIs. Load it in the TurboWarp Editor in this order:
268
316
 
269
- 最小構成はTemporary Variables、SVG Text、Bubbleです。Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define text style`、`define bubble style`、`say`または`think`の順でブロックを配置します。
317
+ 1. For the input-wait example, open your project in the TurboWarp Editor and add Temporary Variables from the extension library.
318
+ 2. Select “Custom Extension” and enable Run without sandbox.
319
+ 3. Load Asset Manager 0.12.1 if you use portraits, blinking, lip-sync, continue frames, or audio.
320
+ 4. Load Runtime Expression 0.4.0 for `finish [UNIT] ...`; load both Async Input 0.4.0 and Runtime Expression 0.4.0 for `wait with this bubble until condition ...`.
321
+ 5. Load Bubble 0.9.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
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.
270
324
 
271
325
  ```text
272
- # SVG Text(必須)
273
- https://unpkg.com/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js
326
+ # Add only when using portraits, blink, lip-sync, continue, or audio
327
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
274
328
 
275
- # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
276
- https://unpkg.com/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js
329
+ # Add Async Input for the integrated wait block
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
277
331
 
278
- # 条件待ちを使う場合だけ追加
279
- https://unpkg.com/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js
280
- https://unpkg.com/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js
332
+ # Add Runtime Expression for finish or the integrated wait block
333
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
281
334
 
282
- # Bubble(必ず最後)
283
- https://unpkg.com/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js
335
+ # Bubble (always load last)
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js
284
337
  ```
285
338
 
286
- TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発中は、リポジトリをローカルHTTPサーバーで配信して`dist/turbowarp-bubble.js`を指定できます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。
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.
340
+
341
+ #### Scratch compatibility
287
342
 
288
- #### Scratchとの互換性
343
+ TurboWarp Bubble cannot be used directly as a custom extension in the official Scratch editor (Scratch 3.0). The official Scratch editor does not expose TurboWarp's unsandboxed extension, internal renderer, or target drawable APIs. Adding the URL from this README to a Scratch `.sb3` project does not register Bubble's blocks.
289
344
 
290
- Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカスタム拡張機能として直接利用することはできません。Scratch公式にはTurboWarpのunsandboxed拡張機能、renderer内部API、target drawable APIがないためです。Scratch向けの.sb3プロジェクトへこのREADMEのURLを追加しても、Bubbleのブロックは登録されません。
345
+ Support by environment is summarized below.
291
346
 
292
- 利用環境ごとの位置付けは次のとおりです。
347
+ | Environment | Usage | Support |
348
+ | --------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- |
349
+ | TurboWarp Editor | Load `dist/turbowarp-bubble.js` as an unsandboxed custom extension | Supported |
350
+ | TurboWarp Packager / compatible runtime | Load it in an environment that provides unsandboxed custom extensions and the renderer API | Supported (verify in each environment) |
351
+ | Official Scratch editor | Load it as an official or sandboxed extension | Not supported |
352
+ | Custom web application / host | Use the npm Composition API or TurboWarp adapter from JavaScript | Supported |
293
353
 
294
- | 環境 | 利用方法 | 対応 |
295
- | ------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
296
- | TurboWarp Editor | `dist/turbowarp-bubble.js`をunsandboxedカスタム拡張機能として読み込む | 対応 |
297
- | TurboWarp Packager/互換runtime | unsandboxedカスタム拡張機能とrenderer APIが利用できる構成で読み込む | 対応(環境ごとに確認が必要) |
298
- | Scratch公式エディター | 公式拡張機能またはサンドボックス拡張機能として読み込む | 非対応 |
299
- | 独自Webアプリ/ホスト | npmのcomposition APIまたはTurboWarp adapterをJavaScriptから利用する | 対応 |
354
+ To use Bubble in another Scratch-compatible runtime, that runtime must implement the same unsandboxed APIs and renderer contract as TurboWarp. In a custom web application, use `@kubohiroya/turbowarp-bubble/composition` or `@kubohiroya/turbowarp-bubble/turbowarp-adapter` instead of the TurboWarp block extension.
300
355
 
301
- Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
356
+ Bubble owns a display for each calling sprite, clone, or Stage. With the default backend, the SVG body, text, expression base, blink layer, lip-sync layer, and continue icon are created as layers in the shared overlay DOM, so you do not need to add layer sprites to the project. The Stage can display only styles that use background-relative placement.
302
357
 
303
- Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。SVG本体、文字、表情ベース、目パチ、口パク、次へアイコンのrenderer drawableは自動生成されるため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
358
+ #### Available blocks
304
359
 
305
- #### 提供ブロック
360
+ | Block | Behavior |
361
+ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
362
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Defines or replaces a Bubble style |
363
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Sets an Actor-relative direction/angle or background-relative region |
364
+ | `set portrait base [ASSET] for bubble style [STYLE]` | Sets the portrait base; an empty value removes the entire portrait |
365
+ | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | Sets portrait placement, local transform, and rounded corners |
366
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Sets the distance from Actor bounds to the tail tip |
367
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Selects one of ten inseparable SVG body + tail/trail pairs |
368
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Sets the nominal length from the body border to the tail tip |
369
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Sets the body offset and whole-Bubble scale |
370
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets blink frames and interval |
371
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets lip-sync frames and interval |
372
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets the animation shown in `awaiting-continue` |
373
+ | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | Configures CHARACTER/WORD/LINE/BLOCK progressive reveal |
374
+ | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | Configures WORD delimiters and their visibility |
375
+ | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | Sets the per-unit reveal sound |
376
+ | `set bubble voice [ASSET] for bubble style [STYLE]` | Sets full voice played when display starts |
377
+ | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | Reveals remaining units and waits for a condition or timeout |
378
+ | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configures the show animation |
379
+ | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configures the hide animation |
380
+ | `animate this bubble [MOTION]` | Plays a whole-Bubble animation |
381
+ | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shakes the complete Bubble surface |
382
+ | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Applies relative-scale cycles to the Bubble |
383
+ | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transitions the Bubble outline |
384
+ | `say [MESSAGE]` | Uses built-in style `say`: speech body and speech tail |
385
+ | `think [MESSAGE]` | Uses built-in style `think`: thought body and round trail |
386
+ | `show [MESSAGE] with bubble style [STYLE]` | Shows the body and tail/trail pair owned by the selected style |
387
+ | `set this bubble animation mode [MODE]` | Selects `talking`, `awaiting-continue`, or `idle` |
388
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Waits for a Runtime Expression condition or optional timeout |
389
+ | `close this bubble` | Releases this target's Bubble and owned resources |
390
+ | `Bubble version` | Returns the implementation version |
306
391
 
307
- | ブロック | 動作 |
308
- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
309
- | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義し、SVG Textで定義した文字style名を関連付ける |
310
- | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
311
- | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
312
- | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
313
- | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
314
- | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含むBubble全体の拡大率を設定する |
315
- | `set portrait base [ASSET] for bubble style [STYLE]` | 表情ベース画像を設定する。空文字でportrait全体を解除する |
316
- | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分を設定する。空リストで解除する |
317
- | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
318
- | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
319
- | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始または置換する |
320
- | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始または置換する |
321
- | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を切り替える |
322
- | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | 条件成立またはtimeoutまでBubbleを表示したまま待つ |
323
- | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
324
- | `Bubble version` | 実装versionを返す |
392
+ `ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and timeouts accept zero; a zero reveal interval disables automatic advance, while a zero timeout disables the time limit.
325
393
 
326
- `ASSETS`はAsset Managerへ登録済みの画像アセット名をカンマ区切りで指定します。アセット名自体にカンマは使用できません。すべての`SECONDS`は0より大きい秒数です。
394
+ 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.
327
395
 
328
- visual styleを設定しない場合は`NORMAL`です。本体drawableは文字・表情より背面に生成され、close、対象停止、runtime破棄時にSVG skinとともに解放されます。
396
+ ##### TurboWarp standard comparison
397
+
398
+ The following screenshots were captured from the same TurboWarp Editor project with the English UI, a `Cat` sprite at `x=-80`, `y=0`, size `80%`, a white Stage, and matching `Hello!` / `Hmm...` inputs. The left column runs TurboWarp's standard Looks blocks. The right column runs Bubble's basic blocks with their matching built-in `say` / `think` styles; no definition or setter block is used.
399
+
400
+ ![TurboWarp standard say and think bubbles compared on the Stage with Bubble's basic profile](docs/assets/turbowarp-say-think-stage-comparison.png)
401
+
402
+ The Stage comparison shows the right-side placement, content-sized body, and the speech tail or thought trail pointing back toward the Actor in each implementation. Bubble draws an independent SVG surface, so the screenshot is the visual reference for its renderer output rather than a reused image of TurboWarp's native bubble.
403
+
404
+ ![TurboWarp standard say and think blocks compared with Bubble's no-setup basic say and think blocks and the built-in default profile values](docs/assets/turbowarp-say-think-block-comparison.png)
405
+
406
+ The block comparison shows the no-setup basic path and the unified custom-style block. Bubble's short `say` and `think` blocks automatically use the matching built-in styles; the callout shows each inseparable body-plus-tail/trail pair, maps both to the reserved text profile `default`, and lists the shared metrics. Named custom styles use `show [MESSAGE] with bubble style [STYLE]`, so the display operation does not select a second, potentially conflicting kind. The former styled say/think opcodes remain hidden compatibility definitions for saved projects.
407
+
408
+ Any explicit style-setting block—or a text style name other than `default`—selects the existing custom profile. Within that profile the omitted visual style is `NORMAL` and the omitted placement is `up-right`; explicit visual styles, placement, distance, tail length, offsets, portrait, continue indicator, reveal, audio, and motion retain their existing behavior. With the default `svg-overlay` backend, the selected body is an SVG DOM layer in the shared overlay root. Explicit `scratch-render` mode instead uses an SVG skin and renderer drawable. Closing or replacing a Bubble, stopping its target, or disposing the runtime releases whichever resources the selected backend owns.
329
409
 
330
410
  #### Placement
331
411
 
332
- `PLACEMENT`はActor相対と背景相対の二系統です。省略時は`up-right`です。
412
+ `PLACEMENT` configures the custom profile and has two families: Actor-relative and background-relative. Once placement or another style option is explicitly configured, the custom-profile default is `up-right`. The untouched basic profile instead uses Scratch's right-first, fit-dependent left flip.
333
413
 
334
- - Actor相対:16の正規方向名、そのcompass alias、またはScratch方向と同じ0〜360度。`0`は上、`90`は右、`180`は下、`270`は左で、`360`は`0`へ正規化します。任意角度は16方向へ丸めません。
335
- - 背景相対:`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`。Stage安全領域の上部、中央、下部へ水平中央揃えで置き、Actor位置・bounds・可視性には依存しません。
414
+ - Actor-relative: one of 16 canonical direction names, a compass alias, or an angle from 0 to 360 degrees following Scratch directions. `0` is up, `90` is right, `180` is down, `270` is left, and `360` is normalized to `0`. Arbitrary angles are not rounded to one of the 16 named directions.
415
+ - Background-relative: `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE`. These center the Bubble horizontally at the top, center, or bottom of the Stage safe area and do not depend on the Actor's position, bounds, or visibility.
336
416
 
337
- Actor相対の正規方向名は次の16個です。別名は大文字小文字を区別せず、正規名へ変換されます。
417
+ The 16 canonical Actor-relative direction names are listed below. Aliases are case-insensitive and are converted to their canonical names.
338
418
 
339
- | 正規名 | compass alias | 正規名 | compass alias |
419
+ | Canonical name | Compass alias | Canonical name | Compass alias |
340
420
  | ------------------ | ----------------- | ---------------- | ----------------- |
341
421
  | `up` | `north` | `down` | `south` |
342
422
  | `up-up-right` | `north-northeast` | `down-down-left` | `south-southwest` |
@@ -347,28 +427,28 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
347
427
  | `down-right` | `southeast` | `up-left` | `northwest` |
348
428
  | `down-down-right` | `south-southeast` | `up-up-left` | `north-northwest` |
349
429
 
350
- ![Actor相対の16方向・角度指定と、背景相対の3配置を比較する図](docs/assets/placement-guide.svg)
430
+ ![The 16 Actor-relative directions and angles compared with the three background-relative placements](docs/assets/placement-guide.svg)
351
431
 
352
- 図中の16方向は、それぞれActor、実際のBubble外形、tail、文字を含む表示例です。本体とtailはJSClipperのunionによる単一pathなので、接合部に内部border線はありません。背景相対3図はStage外枠、安全領域、外形寸法、水平中央線、基準辺/中心を示します。図とTurboWarp Editorの本体drawableは、どちらも共有`renderBubbleSvg`から生成します。
432
+ Each of the 16 directions in the figure shows an Actor, the actual Bubble outline, its tail, and its text. The body and tail form one path through a JSClipper union, so there is no internal border line at the join. The three background-relative examples show the Stage border, safe area, outline dimensions, horizontal centerline, and reference edge or center. Both the figure and the rendered body in the TurboWarp Editor are generated from the shared `renderBubbleSvg`.
353
433
 
354
- ![Actor相対のdistance、tail length、offset、scaleを比較する図](docs/assets/actor-transform-guide.svg)
434
+ ![Actor-relative distance, tail length, offset, and scale compared](docs/assets/actor-transform-guide.svg)
355
435
 
356
- Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box。rendererの`getBoundsForBubble()`が返す上下左右)からtail先端までで、既定値は`12`です。`tail length`は通常位置における本体borderからtail先端までで、既定値は`18`です。
436
+ Actor-relative `distance` runs from the Actor's Stage-coordinate AABB (the axis-aligned bounding box represented by the top, bottom, left, and right values returned by the renderer's `getBoundsForBubble()`) to the tail tip. Its default is `12`. `tail length` runs from the body border at the normal position to the tail tip. Its default is `18`.
357
437
 
358
- `offset x/y/scale`の既定値は`[0, 0, 100]`です。xは右、yは上が正です。scaleはBubble外形だけでなく、SVG Textの文字(フォントサイズ)、表情画像、次へアイコン、内部余白へ一体で適用します。scaleだけを変えた場合は、拡大量の半径分だけ本体中心をActorから離し、Actor側の間隔を維持します。その後x/y offsetを加え、固定したtail先端へ向けてtailを再生成するため、offset後の実長は`tail length`から変化し得ます。Stage端では全体が画面内に収まるようクランプします。これら3設定は背景相対placementでは無視します。
438
+ The default `offset x/y/scale` is `[0, 0, 100]`. Positive x points right, and positive y points up. Scale applies as one transformation to the Bubble outline, SVG Text content and font size, expression images, continue icon, and inner padding. When only scale changes, Bubble moves the body center away from the Actor by the radius of the size increase, preserving the Actor-side gap. It then applies the x/y offset and regenerates the tail toward its fixed tip, so the resulting length after the offset can differ from `tail length`. At Stage edges, the full Bubble is clamped to remain onscreen. These three settings are ignored for background-relative placement.
359
439
 
360
- #### Portraitとblink / lip-sync
440
+ #### Portrait, blink, and lip-sync
361
441
 
362
- portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
442
+ A portrait is a set of layered, pre-aligned transparent images. Prepare the base and variant images with the same canvas size and center point to update only the eyes and mouth without redrawing the face.
363
443
 
364
444
  ```mermaid
365
445
  flowchart TB
366
446
  bubble[Bubble surface]
367
447
  body[Bubble body / text]
368
- base[portraitBase\n顔・髪・輪郭]
369
- blink[portraitBlink\n目パチ差分]
370
- lipsync[portraitLipSync\n口パク差分]
371
- continue[continueIndicator\n次へアイコン]
448
+ base[portraitBase\nface, hair, and outline]
449
+ blink[portraitBlink\nblink variant]
450
+ lipsync[portraitLipSync\nlip-sync variant]
451
+ continue[continueIndicator\nnext icon]
372
452
  bubble --> body
373
453
  bubble --> base
374
454
  base --> blink
@@ -376,85 +456,95 @@ flowchart TB
376
456
  bubble --> continue
377
457
  ```
378
458
 
379
- | レイヤー | 表示中の動作 | 設定ブロック/API |
459
+ | Layer | Behavior while displayed | Configuration block / API |
380
460
  | ------------------- | ------------------------------------------------------ | ------------------------------------------- |
381
- | `portraitBase` | 常時表示するベース画像 | `set portrait base` / `portrait.base` |
382
- | `portraitBlink` | `talking`、`awaiting-continue`、`idle`のすべてでループ | `set blink frames` / `portrait.blink` |
383
- | `portraitLipSync` | `talking`中だけループし、待機時は停止・非表示 | `set lip-sync frames` / `portrait.lipSync` |
384
- | `continueIndicator` | `awaiting-continue`中だけループ | `set continue frames` / `continueIndicator` |
461
+ | `portraitBase` | Base image that remains visible | `set portrait base` / `portrait.base` |
462
+ | `portraitBlink` | Loops in `talking`, `awaiting-continue`, and `idle` | `set blink frames` / `portrait.blink` |
463
+ | `portraitLipSync` | Loops only in `talking`; stops and hides while waiting | `set lip-sync frames` / `portrait.lipSync` |
464
+ | `continueIndicator` | Loops only in `awaiting-continue` | `set continue frames` / `continueIndicator` |
385
465
 
386
- 目パチと口パクは1枚の静止画でも利用できます。口パクのキーワードは、話す行為全体ではなく口元の表情差分を指定する意味で`lip-sync`に統一しています。`continue`は、入力待ちを表すアイコンのanimationであり、JavaScriptの`continue`文を実行する機能ではありません。
466
+ Blink and lip-sync can each use a single still image. The keyword `lip-sync` consistently means a mouth-expression variant, not the entire act of speaking. `continue` is an icon animation that represents waiting for input; it does not execute the JavaScript `continue` statement.
387
467
 
388
- ![portrait base、blink、lip-sync、continue indicatorを別レイヤーとして重ねる概念図](docs/assets/animation-mode-guide.svg)
468
+ ![Portrait base, blink, lip-sync, and continue indicator layered independently](docs/assets/animation-mode-guide.svg)
389
469
 
390
470
  #### Bubble animation
391
471
 
392
- Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
472
+ Bubble treats image-frame loops (blink, lip-sync, and continue) separately from transformations of the Bubble surface itself. The currently published `set this bubble animation mode` switches the behavior mode of the frame loops. Surface transformations form a general animation specification applied to the same surface.
393
473
 
394
474
  ```mermaid
395
475
  flowchart LR
396
- start[表示開始] --> in[表示開始animation\nfadeIn / floatIn / zoomIn / riseUp]
397
- in --> visible[表示中]
398
- visible --> shake[shake\n方向・回数・ease]
399
- visible --> explode[explode\n相対サイズ・回数・ease]
400
- visible --> shape[animateBubbleShape\n速度・時間]
476
+ start[Show] --> in[Show animation\nfadeIn / floatIn / zoomIn / riseUp]
477
+ in --> visible[Visible]
478
+ visible --> shake[shake\ndirection, count, and ease]
479
+ visible --> explode[explode\nrelative size, count, and ease]
480
+ visible --> shape[animateBubbleShape\nspeed and duration]
401
481
  visible --> waiting[awaiting-continue]
402
- waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
403
- out --> released[close・resource解放]
482
+ waiting --> out[Hide animation\nfadeOut / floatOut / zoomOut / sink]
483
+ out --> released[Close and release resources]
404
484
  ```
405
485
 
406
- ##### 表示開始と表示終了
486
+ ##### Show and hide
487
+
488
+ Following PowerPoint terminology as a reference, Bubble calls these “show animations” and “hide animations.” Show animations include `fadeIn`, `floatIn`, `zoomIn`, and `riseUp`; hide animations include `fadeOut`, `floatOut`, `zoomOut`, and `sink`. They are not restricted to `RESERVED`. They can also be applied to a Bubble whose displayed size changes under `DYNAMIC`; a hide animation calculates its endpoint from the current outline.
407
489
 
408
- PowerPointの用語を参考にしつつ、Bubbleの仕様名は「表示開始animation」「表示終了animation」とします。表示開始には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。表示開始・表示終了animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、表示終了時には現在の外形を基準に終点を計算します。
490
+ To remove a Bubble, run `close this bubble`. It applies the configured hide animation and then releases the display and its owned resources. The hide-animation setter configures the exit effect but does not hide anything by itself. The built-in `say` and `think` blocks also close on an empty message for TurboWarp compatibility. There is no separate `hide` block because the operation destroys the current display instead of retaining hidden state.
409
491
 
410
- ##### 表示中の変形
492
+ ##### Transformations while visible
411
493
 
412
- - `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
413
- - `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
414
- - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
494
+ - `shake + direction + count + ease`: Shakes the entire Bubble in the selected direction. `direction` can be horizontal, vertical, or diagonal; `count` is the number of round trips, and `ease` is the timing curve for each round trip.
495
+ - `explode + relativeScale + count + ease`: Repeatedly scales up and back down relative to the current size. The same relative transformation applies to the entire surface, including the portrait and Text.
496
+ - `animateBubbleShape + speed + duration`: Changes among outlines such as `THINKING`, `DREAMING`, `YELLING`, `WAVY`, and `WHISPERING` at the selected speed and for the selected duration. This separates changes to `visualStyle` from active surface animation.
415
497
 
416
- TurboWarp adapterは16ms単位のscheduler tickで各animationを進め、`ease`を各フレームの進行率へ適用します。`fadeIn`/`fadeOut`はrendererの`ghost`効果、`float`/`rise`/`sink`は位置、`zoom`/`explode`は倍率をText・portrait・Bubble本体へ同じように適用します。`shake`は指定回数の往復を行い、`explode`は拡大と復帰を繰り返します。`durationSeconds`を省略した`shake`/`explode`には、回数に応じた既定時間を使います。
498
+ The TurboWarp adapter advances each animation on scheduler ticks of up to 16 ms and applies `ease` to each frame's progress. The default SVG overlay changes the shared surface group's opacity and transform; explicit `scratch-render` mode maps the same motions to renderer effects, position, and scale. `shake` performs the requested number of round trips, while `explode` repeatedly enlarges and restores the Text, portrait, and body together. A `shake` or `explode` without `durationSeconds` uses a default duration based on its count.
417
499
 
418
- `animateBubbleShape`は、現在形状と指定形状を各フレームでcross-fadeするSVG body skinへ更新します。Textとportraitは再生成せず、外形だけを連続的に切り替えます。`speed`は指定時間内の形状遷移速度倍率です。
500
+ `animateBubbleShape` cross-fades the current and requested outlines generated by `renderBubbleSvg` on every frame. The overlay backend rebuilds only the allowlisted body elements, while `scratch-render` updates the body skin; neither path regenerates the Text or portrait. `speed` is the shape-transition speed multiplier within the selected duration.
419
501
 
420
- animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとdrawableを先に解放します。`shake`には`ease`を指定でき、`explode`には`relativeScale`、`count`、`ease`、`animateBubbleShape`には`speed`と`durationSeconds`を指定できます。
502
+ Animations integrate with the lifecycle of `show`, `handle.animate()`, `handle.setAnimationMode()`, `handle.updateStyle()`, and `handle.close()`. When a new Bubble replaces the same `actorKey`, the old animation timers and backend-owned rendering resources are released first. `shake` accepts `ease`; `explode` accepts `relativeScale`, `count`, and `ease`; and `animateBubbleShape` accepts `speed` and `durationSeconds`.
421
503
 
422
504
  #### Animation mode
423
505
 
424
- | mode | 目パチ | 口パク | continue frames |
425
- | ------------------- | ------ | ------------ | --------------- |
426
- | `talking` | 実行 | 実行 | 非表示 |
427
- | `awaiting-continue` | 実行 | 停止・非表示 | ループ実行 |
428
- | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
506
+ | Mode | Blink | Lip-sync | Continue frames |
507
+ | ------------------- | ------- | ------------------ | ------------------ |
508
+ | `talking` | Running | Running | Hidden |
509
+ | `awaiting-continue` | Running | Stopped and hidden | Looping |
510
+ | `idle` | Running | Stopped and hidden | Stopped and hidden |
429
511
 
430
- `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
512
+ The `say` and `think` blocks start displaying in `talking` mode and immediately proceed to the next block. `wait with this bubble ...` automatically moves to `awaiting-continue` and evaluates runtime variables updated by Async Input through Runtime Expression. When the condition succeeds or the timeout expires, it moves to `idle` and proceeds to the next block.
431
513
 
432
- #### ブロック構成例
514
+ #### Block example
433
515
 
434
516
  ```text
435
- define bubble style [hero-dialogue] using text style [dialogue-text]
517
+ define bubble style [hero-dialogue] using text style [default]
436
518
  set bubble placement [up-right] for bubble style [hero-dialogue]
437
519
  set bubble distance [12] for bubble style [hero-dialogue]
438
520
  set bubble visual style [NORMAL] for bubble style [hero-dialogue]
439
521
  set bubble tail length [18] for bubble style [hero-dialogue]
440
522
  set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
441
523
  set portrait base [HeroFace] for bubble style [hero-dialogue]
524
+ set portrait [top-left] offset x [-4] y [6] zoom [120] % corner radius [12] px for bubble style [hero-dialogue]
442
525
  set blink frames [HeroEyesOpen,HeroEyesClosed] every [0.4] seconds for bubble style [hero-dialogue]
443
526
  set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
444
527
  set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
528
+ set bubble reveal unit [WORD] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
529
+ set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
530
+ set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
531
+ set bubble voice [HeroVoice] for bubble style [hero-dialogue]
532
+ set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
533
+ set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
445
534
  set runtime variable [input] to []
446
535
  listen for key [Space] set runtime var [input] to [pressed]
447
536
  listen for touch on this sprite set runtime var [input] to [pressed]
448
- say [海へ出発!] with bubble style [hero-dialogue]
449
- wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
537
+ show [Set/sail!] with bubble style [hero-dialogue]
538
+ finish [WORD] with condition [input == "pressed"] or timeout after [10] seconds
539
+ shake this bubble direction [90] count [2] ease [easeInOut]
450
540
  close this bubble
451
541
  ```
452
542
 
453
- プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、SVG text skin、drawableを自動解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
543
+ Bubble automatically releases its owned timers, overlay DOM, and image leases when the project starts or stops, a target sprite or clone stops, or the runtime is disposed. When `scratch-render` is explicitly selected, Bubble also releases its owned SVG skins and drawables as before. If a dependency extension has not been loaded, the returned error includes the required npm package name.
454
544
 
455
545
  ### Composition API
456
546
 
457
- TurboWarp runtimeのrenderer、SVG Textへ直接接続するhostでは、公開adapterを利用できます。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
547
+ 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.
458
548
 
459
549
  ```ts
460
550
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -462,7 +552,7 @@ import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/t
462
552
  const bubbles = createTurboWarpBubbleComposition(runtime);
463
553
  ```
464
554
 
465
- 描画surfaceをhost側で実装する場合は、以下の低レベルComposition APIを利用します。
555
+ If the host implements the rendering surface, use the lower-level Composition API below.
466
556
 
467
557
  ```ts
468
558
  import {
@@ -485,23 +575,23 @@ const bubbles = createBubbleComposition({
485
575
  });
486
576
  ```
487
577
 
488
- `declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleTextCapability`(文字skinの適用・計測・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。`@kubohiroya/turbowarp-svg-text/composition`を使う場合は、`createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))`で`textCapability`へ変換します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
578
+ 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.
489
579
 
490
- テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
580
+ 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.
491
581
 
492
- `createSurface`が返すsurfaceは、次のtargetを持ちます。
582
+ The surface returned by `createSurface` has the following targets.
493
583
 
494
- surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
584
+ The surface also implements `updateStyle(style)` so it can update the Bubble's position, shape, and size. To change the style of a displayed Bubble, call `updateStyle(style)` on the returned handle. If the updated style uses an image layer, the surface must have returned the corresponding target in advance.
495
585
 
496
- - `text`: `textCapability`が文字スキンを適用するtarget
497
- - `portraitBase`: キャラクター表情のベース画像target
498
- - `portraitBlink`: 目パチ差分target
499
- - `portraitLipSync`: 口パク差分target
500
- - `continueIndicator`: 「次へ」アイコンtarget
586
+ - `text`: Target to which `textCapability` applies text layout
587
+ - `portraitBase`: Target for the character-expression base image
588
+ - `portraitBlink`: Target for the blink variant
589
+ - `portraitLipSync`: Target for the lip-sync variant
590
+ - `continueIndicator`: Target for the “next” icon
501
591
 
502
- 画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
592
+ Image-layer target IDs must be distinct from one another. Targets for layers unused by the style can be omitted.
503
593
 
504
- #### Styleと表示
594
+ #### Styles and display
505
595
 
506
596
  ```ts
507
597
  bubbles.defineStyle({
@@ -536,6 +626,7 @@ bubbles.defineStyle({
536
626
  audio: {
537
627
  voice: "HeroVoice",
538
628
  reveal: "Typewriter",
629
+ finish: "Ready",
539
630
  },
540
631
  showAnimation: { name: "fadeIn", durationSeconds: 0.2 },
541
632
  hideAnimation: { name: "fadeOut", durationSeconds: 0.2 },
@@ -546,26 +637,26 @@ bubbles.defineStyle({
546
637
  textStyle: "dialogue-text",
547
638
  placement: "FOOTER_LIKE",
548
639
  maxWidth: 320,
549
- textLocale: "ja",
640
+ textLocale: "en",
550
641
  });
551
642
 
552
643
  const bubble = await bubbles.show({
553
644
  actor: heroTarget,
554
645
  actorKey: "Hero",
555
646
  kind: "say",
556
- text: "海へ出発!",
647
+ text: "Set sail!",
557
648
  styleName: "hero-dialogue",
558
649
  });
559
650
  ```
560
651
 
561
- `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-continue`へ変更します。
652
+ The initial animation mode for `show` is `talking`. Blink continues while the Bubble is displayed, and lip-sync runs. After the full text is visible, change the mode to `awaiting-continue` when the application begins waiting for the user to choose “next.”
562
653
 
563
654
  ```ts
564
655
  await bubble.setAnimationMode("awaiting-continue");
565
- // 口パクを停止して非表示にし、「次へ」アイコンをループ表示します。
656
+ // Stop and hide lip-sync, then loop the "next" icon.
566
657
 
567
658
  await bubble.setAnimationMode("idle");
568
- // 吹き出しを残したまま、口パクと「次へ」アイコンを停止します。
659
+ // Keep the Bubble visible, but stop lip-sync and the "next" icon.
569
660
 
570
661
  await bubble.revealNext();
571
662
  await bubble.revealAll();
@@ -584,19 +675,19 @@ await bubble.finish({
584
675
  await bubble.close();
585
676
  ```
586
677
 
587
- 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、text capability target、surfaceを解放します。composition間で状態は共有しません。
678
+ 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.
588
679
 
589
- ## ライセンスとソースコード
680
+ ## License and source code
590
681
 
591
- このパッケージのSource Code Formは[MPL-2.0](https://www.mozilla.org/MPL/2.0/)の条件で提供します。対応するソースコードは[GitHubリポジトリ](https://github.com/kubohiroya/turbowarp-bubble)から取得できます。npmおよびCDNで配布するJavaScript bundleに対応するソースコードも、このリポジトリの同じpackage versionから参照できます。
682
+ The Source Code Form of this package is provided under the terms of the [MPL-2.0](https://www.mozilla.org/MPL/2.0/). The corresponding source code is available from the [GitHub repository](https://github.com/kubohiroya/turbowarp-bubble). Source code corresponding to JavaScript bundles distributed through npm and CDNs can be found at the same package version in this repository.
592
683
 
593
- 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
684
+ Copyright notices and license terms for third-party software incorporated into the distribution are collected in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
594
685
 
595
- ## 開発
686
+ ## Development
596
687
 
597
688
  ```sh
598
689
  pnpm install
599
690
  pnpm check
600
691
  ```
601
692
 
602
- `pnpm check`は型検査、lint、format、単体テスト、配布物検査、外部consumer型検査、npm pack dry-runを実行します。
693
+ `pnpm check` runs type checking, linting, formatting, unit tests, distribution inspection, external-consumer type checking, and an npm pack dry run.