@kubohiroya/turbowarp-bubble 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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.10.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.10.0 release notes](docs/release-notes-0.10.0.md) for reusable named close policies and the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles.
8
8
 
9
- 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.10.0 feature set to its public entry points. The standalone extension exposes 31 palette blocks generated from 33 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準拠の改行 | 実装済み(SVG Text 0.8.0のhost-neutral layoutを標準接続) |
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 0.8 layout adapter\nrenderer非依存の行layout・計測"]
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,11 +71,13 @@ flowchart TB
67
71
  extension -."optional".-> input
68
72
  ```
69
73
 
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は対応機能を使う場合だけ接続します。
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)
71
77
 
72
- ### 描画backend(SVG overlayが既定)
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.
73
79
 
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"`は互換性とロールバックのため明示指定時だけ使用します。
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.
75
81
 
76
82
  ```ts
77
83
  import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
@@ -101,79 +107,79 @@ const bubbles = createTurboWarpBubbleComposition(runtime, {
101
107
  });
102
108
  ```
103
109
 
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"`です。
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"`.
105
111
 
106
- 既定文字providerは直接依存するSVG Text 0.8.0です。画像adapterには`resolveDOMImageResource()`を公開するAsset Manager 0.12.0以降が必要です。
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.
107
113
 
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`へ戻ります。
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.
109
115
 
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には含まれない |
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 |
118
124
 
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)`を呼びます。
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.
120
126
 
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)に記録します。
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).
122
128
 
123
- ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
129
+ ### Progressive reveal units (CHARACTER / WORD / LINE / BLOCK)
124
130
 
125
- セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
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.
126
132
 
127
- 仕様上の綴りは`CHARACTER`です(`charactor`ではありません)。`BLOCK`は、改行を含む複数行を一つの表示単位として扱う名前で、ここでいうblockはScratchのblockではありません。
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.
128
134
 
129
135
  ```mermaid
130
136
  flowchart LR
131
- source["全文: 私の/名前は/中野/です"] --> mode{"表示単位"}
137
+ source["Full text: 私の/名前は/中野/です"] --> mode{"Reveal unit"}
132
138
  mode -->|CHARACTER| c["私 → 私の → 私の/ → …"]
133
139
  mode -->|WORD| w["私の → 私の/名前は → …"]
134
- mode -->|LINE| l["1行ずつ追加"]
135
- mode -->|BLOCK| b["複数行/段落をまとめて追加"]
136
- delimiter["任意の区切り文字集合<br/>例: スラッシュ、空白、縦線"] -.-> w
137
- visibility{"区切り文字の表示"} -->|visible| shown["区切り文字も描画"]
138
- 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"]
139
145
  delimiter --> visibility
140
146
  ```
141
147
 
142
- ### WORDの区切り文字
148
+ ### WORD delimiters
143
149
 
144
- 日本語の形態素解析は行いません。`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.
145
151
 
146
- 区切り文字は単一文字に限定せず、任意の文字集合として指定します。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.
147
153
 
148
- ### DYNAMICとRESERVED
154
+ ### DYNAMIC and RESERVED
149
155
 
150
- 逐次表示中の吹き出しサイズは、次の2方式を選べるようにします。
156
+ Two bubble-sizing strategies are available during progressive reveal.
151
157
 
152
158
  ```mermaid
153
159
  sequenceDiagram
154
160
  participant Host as Host
155
161
  participant Bubble as Bubble surface
156
162
  participant Text as Text provider
157
- Host->>Text: 全文をmeasure
163
+ Host->>Text: Measure the full text
158
164
  alt RESERVED
159
- Text-->>Bubble: 最終幅・最終行数
160
- Bubble->>Bubble: 最終サイズを先に確保
161
- loop 表示単位ごと
162
- Host->>Text: 可視範囲を更新
163
- 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
164
170
  end
165
171
  else DYNAMIC
166
- loop 表示単位ごと
167
- Host->>Text: 可視範囲を更新
168
- Text-->>Bubble: 現在の幅・行数
169
- 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
170
176
  end
171
177
  end
172
178
  ```
173
179
 
174
- `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.
175
181
 
176
- 逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
182
+ To reveal all remaining units before entering the waiting state, use a finish operation with an explicit reveal unit.
177
183
 
178
184
  ```text
179
185
  finish [CHARACTER / WORD / LINE / BLOCK]
@@ -181,39 +187,39 @@ finish [CHARACTER / WORD / LINE / BLOCK]
181
187
  or timeout after [TIMEOUT] seconds
182
188
  ```
183
189
 
184
- `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.
185
191
 
186
- ### 音声と表示単位
192
+ ### Audio and reveal units
187
193
 
188
- `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.
189
195
 
190
- Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
196
+ When Asset Manager is connected as the audio provider, the following audio can share the same display lifecycle:
191
197
 
192
- - 表示開始時のフルボイス
193
- - `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
194
- - 表示終了、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
195
201
 
196
- 表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声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.
197
203
 
198
- ### パッケージ境界
204
+ ### Package boundaries
199
205
 
200
- | パッケージ | 責務 |
201
- | ------------------------------------------ | ------------------------------------------------------------------------------ |
202
- | `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
203
- | Bubble core(`composition`) | `BubbleTextCapability`契約、吹き出しsurface、配置、逐次表示、animation |
204
- | `@kubohiroya/turbowarp-svg-text` | 0.8.0のhost-neutralなplain/ruby layoutと文字幅計測 |
205
- | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
206
- | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
207
- | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
208
- | アプリ/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 |
209
215
 
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を使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
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.
211
217
 
212
- ### 自動改行と禁則処理の基盤
218
+ ### Automatic wrapping and line-breaking rules
213
219
 
214
- 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.
215
221
 
216
- `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.
217
223
 
218
224
  ```ts
219
225
  import { wrapText } from "@kubohiroya/turbowarp-bubble/composition";
@@ -225,23 +231,23 @@ const layout = wrapText({
225
231
  });
226
232
  ```
227
233
 
228
- 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.
229
235
 
230
- ![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)
231
237
 
232
- 図の各行は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.
233
239
 
234
- ### Bubble visual styleの形状
240
+ ### Bubble visual-style shapes
235
241
 
236
- 形状候補は`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`.
237
243
 
238
- ![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)
239
245
 
240
- この図は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.
241
247
 
242
- 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.
243
249
 
244
- 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.
245
251
 
246
252
  ```ts
247
253
  portrait: {
@@ -252,23 +258,23 @@ portrait: {
252
258
  }
253
259
  ```
254
260
 
255
- 配布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.
256
262
 
257
- ## 利用方法
263
+ ## Usage
258
264
 
259
- ### インストール
265
+ ### Installation
260
266
 
261
267
  ```sh
262
268
  pnpm add @kubohiroya/turbowarp-bubble
263
269
  ```
264
270
 
265
- npmを使う場合は同じ依存を次のように追加します。
271
+ With npm, install the same dependency as follows.
266
272
 
267
273
  ```sh
268
274
  npm install @kubohiroya/turbowarp-bubble
269
275
  ```
270
276
 
271
- 逐次表示の正規化と文字列分割だけが必要な利用側は、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.
272
278
 
273
279
  ```ts
274
280
  import {
@@ -280,9 +286,11 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
280
286
  const chunks = splitBubbleText("A👩‍🚀B", reveal);
281
287
  ```
282
288
 
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は固定されます。
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.
284
290
 
285
- 画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
291
+ After rolling back to `bubbleRenderBackend: "scratch-render"`, Bubble creates a skin-based provider from the same 0.8.1 dependency if the standalone SVG Text extension is not loaded. On a host where the standalone SVG Text extension is already loaded, Bubble continues using that existing provider for compatibility.
292
+
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.
286
294
 
287
295
  ```sh
288
296
  pnpm add @kubohiroya/turbowarp-asset-manager \
@@ -296,88 +304,135 @@ npm install @kubohiroya/turbowarp-asset-manager \
296
304
  @kubohiroya/turbowarp-runtime-expression
297
305
  ```
298
306
 
299
- ### TurboWarp機能拡張
307
+ ### TurboWarp extension
308
+
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`.
300
310
 
301
- ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
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.
302
312
 
303
- #### TurboWarpでの導入
313
+ #### Loading in TurboWarp
304
314
 
305
- TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget APIへ接続する**unsandboxedカスタム拡張機能**です。TurboWarp Editorでは、次の順で読み込みます。
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:
306
316
 
307
- 1. TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
308
- 2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
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に含まれます。
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 condition-based waits and close policies. A timeout-only close policy needs neither extension.
321
+ 5. Load Bubble 0.10.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
312
322
 
313
- 文字だけの最小構成はBubbleです。Temporary Variables、Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define bubble style`、`say`または`think`の順でブロックを配置します。text styleには`default`または任意の名前を指定でき、standalone既定providerでは背景透明のSVG Text既定値として初期化されます。
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.
314
324
 
315
325
  ```text
316
- # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
317
- https://unpkg.com/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.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
328
+
329
+ # Add Async Input for integrated condition waits and close policies
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
318
331
 
319
- # 条件待ちを使う場合だけ追加
320
- https://unpkg.com/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js
321
- https://unpkg.com/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js
332
+ # Add Runtime Expression for finish or condition-based waits and close policies
333
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
322
334
 
323
- # Bubble(必ず最後)
324
- https://unpkg.com/@kubohiroya/turbowarp-bubble@0.8.0/dist/turbowarp-bubble.js
335
+ # Bubble (always load last)
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js
325
337
  ```
326
338
 
327
- 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
342
+
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.
344
+
345
+ Support by environment is summarized below.
346
+
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 |
353
+
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.
355
+
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.
357
+
358
+ #### Available blocks
359
+
360
+ | Block | Behavior |
361
+ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
362
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Defines or replaces a Bubble style |
363
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | Defines or replaces a named closing condition |
364
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Sets an Actor-relative direction/angle or background-relative region |
365
+ | `set portrait base [ASSET] for bubble style [STYLE]` | Sets the portrait base; an empty value removes the entire portrait |
366
+ | `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 |
367
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Sets the distance from Actor bounds to the tail tip |
368
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Selects one of ten inseparable SVG body + tail/trail pairs |
369
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Sets the nominal length from the body border to the tail tip |
370
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Sets the body offset and whole-Bubble scale |
371
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets blink frames and interval |
372
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets lip-sync frames and interval |
373
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets the animation shown in `awaiting-continue` |
374
+ | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | Configures CHARACTER/WORD/LINE/BLOCK progressive reveal |
375
+ | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | Configures WORD delimiters and their visibility |
376
+ | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | Sets the per-unit reveal sound |
377
+ | `set bubble voice [ASSET] for bubble style [STYLE]` | Sets full voice played when display starts |
378
+ | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | Reveals remaining units and waits for a condition or timeout |
379
+ | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configures the show animation |
380
+ | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configures the hide animation |
381
+ | `animate this bubble [MOTION]` | Plays a whole-Bubble animation |
382
+ | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shakes the complete Bubble surface |
383
+ | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Applies relative-scale cycles to the Bubble |
384
+ | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transitions the Bubble outline |
385
+ | `say [MESSAGE]` | Uses built-in style `say`: speech body and speech tail |
386
+ | `think [MESSAGE]` | Uses built-in style `think`: thought body and round trail |
387
+ | `show [MESSAGE] with bubble style [STYLE]` | Shows the body and tail/trail pair owned by the selected style |
388
+ | `set this bubble animation mode [MODE]` | Selects `talking`, `awaiting-continue`, or `idle` |
389
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Waits for a Runtime Expression condition or optional timeout |
390
+ | `wait and close this bubble using close policy [POLICY]` | Snapshots a policy, waits for it, and closes the Bubble |
391
+ | `close this bubble` | Releases this target's Bubble and owned resources |
392
+ | `Bubble version` | Returns the implementation version |
393
+
394
+ A Bubble close policy is control-flow configuration, not a visual Bubble style. `condition` waits without a time limit, `timeout` closes after a positive number of seconds, and `condition-or-timeout` closes when either trigger happens first. A condition must be non-empty, and an enabled timeout must be greater than zero.
328
395
 
329
- #### Scratchとの互換性
396
+ ```text
397
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
398
+ say [This closes after three seconds.]
399
+ wait and close this bubble using close policy [three-seconds]
400
+
401
+ define bubble close policy [advance] trigger [condition] condition [input == "pressed"] timeout [0] seconds
402
+ say [Press a key or touch the sprite.]
403
+ wait and close this bubble using close policy [advance]
404
+ ```
330
405
 
331
- Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカスタム拡張機能として直接利用することはできません。Scratch公式にはTurboWarpのunsandboxed拡張機能、renderer内部API、target drawable APIがないためです。Scratch向けの.sb3プロジェクトへこのREADMEのURLを追加しても、Bubbleのブロックは登録されません。
406
+ The apply block snapshots the named definition when it starts. Replacing the same policy while it is waiting therefore affects only later applications. Timeout-only policies leave the Bubble in its current animation mode and require no input extension. Policies with a condition enter `awaiting-continue` and use Async Input plus Runtime Expression in the same way as the integrated wait block. Completion runs the configured hide animation and releases the Bubble. Replacing the Bubble, stopping its target or the project, or disposing the runtime cancels the pending policy without closing a replacement Bubble.
332
407
 
333
- 利用環境ごとの位置付けは次のとおりです。
408
+ `ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and the legacy wait timeout accept zero; a zero reveal interval disables automatic advance, while a zero legacy timeout disables the time limit. A timeout selected explicitly by a close policy must be greater than zero.
334
409
 
335
- | 環境 | 利用方法 | 対応 |
336
- | ------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
337
- | TurboWarp Editor | `dist/turbowarp-bubble.js`をunsandboxedカスタム拡張機能として読み込む | 対応 |
338
- | TurboWarp Packager/互換runtime | unsandboxedカスタム拡張機能とrenderer APIが利用できる構成で読み込む | 対応(環境ごとに確認が必要) |
339
- | Scratch公式エディター | 公式拡張機能またはサンドボックス拡張機能として読み込む | 非対応 |
340
- | 独自Webアプリ/ホスト | npmのcomposition APIまたはTurboWarp adapterをJavaScriptから利用する | 対応 |
410
+ Bubble provides two built-in Bubble styles. `say` owns the speech body and speech tail; `think` owns the thought body and round trail. The body and tail/trail are one visual-style choice rather than independently selected properties. The matching short block selects each style automatically, so neither a style-definition block nor a style input is required. Both styles use the reserved text profile `default`: 14px Helvetica, 16px line height, a 170px maximum line width, 50px minimum text width, 10px padding, 16px corners, a white fill, and Scratch text/stroke colors. The 4px SVG stroke is painted before the white fill, which covers its inner half and leaves the same thin visible outline as TurboWarp's standard bubble. The profile starts on the Actor's right, flips to the left only when that side fits, follows Actor bounds, fences the Stage top and sides, formats numeric block inputs like Scratch, limits text to 330 characters, and closes on an empty block input.
341
411
 
342
- Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
412
+ ##### TurboWarp standard comparison
343
413
 
344
- Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。既定backendではSVG本体、文字、表情ベース、目パチ、口パク、次へアイコンを共有overlay DOM内のレイヤーとして生成するため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
414
+ 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.
345
415
 
346
- #### 提供ブロック
416
+ ![TurboWarp standard say and think bubbles compared on the Stage with Bubble's basic profile](docs/assets/turbowarp-say-think-stage-comparison.png)
347
417
 
348
- | ブロック | 動作 |
349
- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
350
- | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義し、文字layout style名を関連付ける |
351
- | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
352
- | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
353
- | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
354
- | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
355
- | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含むBubble全体の拡大率を設定する |
356
- | `set portrait base [ASSET] for bubble style [STYLE]` | 表情ベース画像を設定する。空文字でportrait全体を解除する |
357
- | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分を設定する。空リストで解除する |
358
- | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
359
- | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
360
- | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始または置換する |
361
- | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始または置換する |
362
- | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を切り替える |
363
- | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | 条件成立またはtimeoutまでBubbleを表示したまま待つ |
364
- | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
365
- | `Bubble version` | 実装versionを返す |
418
+ 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.
366
419
 
367
- `ASSETS`はAsset Managerへ登録済みの画像アセット名をカンマ区切りで指定します。アセット名自体にカンマは使用できません。すべての`SECONDS`は0より大きい秒数です。
420
+ ![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)
368
421
 
369
- visual styleを設定しない場合は`NORMAL`です。本体drawableは文字・表情より背面に生成され、close、対象停止、runtime破棄時にSVG skinとともに解放されます。
422
+ 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.
423
+
424
+ 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.
370
425
 
371
426
  #### Placement
372
427
 
373
- `PLACEMENT`はActor相対と背景相対の二系統です。省略時は`up-right`です。
428
+ `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.
374
429
 
375
- - Actor相対:16の正規方向名、そのcompass alias、またはScratch方向と同じ0〜360度。`0`は上、`90`は右、`180`は下、`270`は左で、`360`は`0`へ正規化します。任意角度は16方向へ丸めません。
376
- - 背景相対:`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`。Stage安全領域の上部、中央、下部へ水平中央揃えで置き、Actor位置・bounds・可視性には依存しません。
430
+ - 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.
431
+ - 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.
377
432
 
378
- Actor相対の正規方向名は次の16個です。別名は大文字小文字を区別せず、正規名へ変換されます。
433
+ The 16 canonical Actor-relative direction names are listed below. Aliases are case-insensitive and are converted to their canonical names.
379
434
 
380
- | 正規名 | compass alias | 正規名 | compass alias |
435
+ | Canonical name | Compass alias | Canonical name | Compass alias |
381
436
  | ------------------ | ----------------- | ---------------- | ----------------- |
382
437
  | `up` | `north` | `down` | `south` |
383
438
  | `up-up-right` | `north-northeast` | `down-down-left` | `south-southwest` |
@@ -388,28 +443,28 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
388
443
  | `down-right` | `southeast` | `up-left` | `northwest` |
389
444
  | `down-down-right` | `south-southeast` | `up-up-left` | `north-northwest` |
390
445
 
391
- ![Actor相対の16方向・角度指定と、背景相対の3配置を比較する図](docs/assets/placement-guide.svg)
446
+ ![The 16 Actor-relative directions and angles compared with the three background-relative placements](docs/assets/placement-guide.svg)
392
447
 
393
- 図中の16方向は、それぞれActor、実際のBubble外形、tail、文字を含む表示例です。本体とtailはJSClipperのunionによる単一pathなので、接合部に内部border線はありません。背景相対3図はStage外枠、安全領域、外形寸法、水平中央線、基準辺/中心を示します。図とTurboWarp Editorの本体drawableは、どちらも共有`renderBubbleSvg`から生成します。
448
+ 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`.
394
449
 
395
- ![Actor相対のdistance、tail length、offset、scaleを比較する図](docs/assets/actor-transform-guide.svg)
450
+ ![Actor-relative distance, tail length, offset, and scale compared](docs/assets/actor-transform-guide.svg)
396
451
 
397
- Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box。rendererの`getBoundsForBubble()`が返す上下左右)からtail先端までで、既定値は`12`です。`tail length`は通常位置における本体borderからtail先端までで、既定値は`18`です。
452
+ 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`.
398
453
 
399
- `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では無視します。
454
+ 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.
400
455
 
401
- #### Portraitとblink / lip-sync
456
+ #### Portrait, blink, and lip-sync
402
457
 
403
- portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
458
+ 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.
404
459
 
405
460
  ```mermaid
406
461
  flowchart TB
407
462
  bubble[Bubble surface]
408
463
  body[Bubble body / text]
409
- base[portraitBase\n顔・髪・輪郭]
410
- blink[portraitBlink\n目パチ差分]
411
- lipsync[portraitLipSync\n口パク差分]
412
- continue[continueIndicator\n次へアイコン]
464
+ base[portraitBase\nface, hair, and outline]
465
+ blink[portraitBlink\nblink variant]
466
+ lipsync[portraitLipSync\nlip-sync variant]
467
+ continue[continueIndicator\nnext icon]
413
468
  bubble --> body
414
469
  bubble --> base
415
470
  base --> blink
@@ -417,60 +472,62 @@ flowchart TB
417
472
  bubble --> continue
418
473
  ```
419
474
 
420
- | レイヤー | 表示中の動作 | 設定ブロック/API |
475
+ | Layer | Behavior while displayed | Configuration block / API |
421
476
  | ------------------- | ------------------------------------------------------ | ------------------------------------------- |
422
- | `portraitBase` | 常時表示するベース画像 | `set portrait base` / `portrait.base` |
423
- | `portraitBlink` | `talking`、`awaiting-continue`、`idle`のすべてでループ | `set blink frames` / `portrait.blink` |
424
- | `portraitLipSync` | `talking`中だけループし、待機時は停止・非表示 | `set lip-sync frames` / `portrait.lipSync` |
425
- | `continueIndicator` | `awaiting-continue`中だけループ | `set continue frames` / `continueIndicator` |
477
+ | `portraitBase` | Base image that remains visible | `set portrait base` / `portrait.base` |
478
+ | `portraitBlink` | Loops in `talking`, `awaiting-continue`, and `idle` | `set blink frames` / `portrait.blink` |
479
+ | `portraitLipSync` | Loops only in `talking`; stops and hides while waiting | `set lip-sync frames` / `portrait.lipSync` |
480
+ | `continueIndicator` | Loops only in `awaiting-continue` | `set continue frames` / `continueIndicator` |
426
481
 
427
- 目パチと口パクは1枚の静止画でも利用できます。口パクのキーワードは、話す行為全体ではなく口元の表情差分を指定する意味で`lip-sync`に統一しています。`continue`は、入力待ちを表すアイコンのanimationであり、JavaScriptの`continue`文を実行する機能ではありません。
482
+ 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.
428
483
 
429
- ![portrait base、blink、lip-sync、continue indicatorを別レイヤーとして重ねる概念図](docs/assets/animation-mode-guide.svg)
484
+ ![Portrait base, blink, lip-sync, and continue indicator layered independently](docs/assets/animation-mode-guide.svg)
430
485
 
431
486
  #### Bubble animation
432
487
 
433
- Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
488
+ 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.
434
489
 
435
490
  ```mermaid
436
491
  flowchart LR
437
- start[表示開始] --> in[表示開始animation\nfadeIn / floatIn / zoomIn / riseUp]
438
- in --> visible[表示中]
439
- visible --> shake[shake\n方向・回数・ease]
440
- visible --> explode[explode\n相対サイズ・回数・ease]
441
- visible --> shape[animateBubbleShape\n速度・時間]
492
+ start[Show] --> in[Show animation\nfadeIn / floatIn / zoomIn / riseUp]
493
+ in --> visible[Visible]
494
+ visible --> shake[shake\ndirection, count, and ease]
495
+ visible --> explode[explode\nrelative size, count, and ease]
496
+ visible --> shape[animateBubbleShape\nspeed and duration]
442
497
  visible --> waiting[awaiting-continue]
443
- waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
444
- out --> released[close・resource解放]
498
+ waiting --> out[Hide animation\nfadeOut / floatOut / zoomOut / sink]
499
+ out --> released[Close and release resources]
445
500
  ```
446
501
 
447
- ##### 表示開始と表示終了
502
+ ##### Show and hide
503
+
504
+ 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.
448
505
 
449
- PowerPointの用語を参考にしつつ、Bubbleの仕様名は「表示開始animation」「表示終了animation」とします。表示開始には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。表示開始・表示終了animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、表示終了時には現在の外形を基準に終点を計算します。
506
+ 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.
450
507
 
451
- ##### 表示中の変形
508
+ ##### Transformations while visible
452
509
 
453
- - `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
454
- - `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
455
- - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
510
+ - `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.
511
+ - `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.
512
+ - `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.
456
513
 
457
- TurboWarp adapterは16ms単位のscheduler tickで各animationを進め、`ease`を各フレームの進行率へ適用します。`fadeIn`/`fadeOut`はrendererの`ghost`効果、`float`/`rise`/`sink`は位置、`zoom`/`explode`は倍率をText・portrait・Bubble本体へ同じように適用します。`shake`は指定回数の往復を行い、`explode`は拡大と復帰を繰り返します。`durationSeconds`を省略した`shake`/`explode`には、回数に応じた既定時間を使います。
514
+ 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.
458
515
 
459
- `animateBubbleShape`は、現在形状と指定形状を各フレームでcross-fadeするSVG body skinへ更新します。Textとportraitは再生成せず、外形だけを連続的に切り替えます。`speed`は指定時間内の形状遷移速度倍率です。
516
+ `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.
460
517
 
461
- animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとdrawableを先に解放します。`shake`には`ease`を指定でき、`explode`には`relativeScale`、`count`、`ease`、`animateBubbleShape`には`speed`と`durationSeconds`を指定できます。
518
+ 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`.
462
519
 
463
520
  #### Animation mode
464
521
 
465
- | mode | 目パチ | 口パク | continue frames |
466
- | ------------------- | ------ | ------------ | --------------- |
467
- | `talking` | 実行 | 実行 | 非表示 |
468
- | `awaiting-continue` | 実行 | 停止・非表示 | ループ実行 |
469
- | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
522
+ | Mode | Blink | Lip-sync | Continue frames |
523
+ | ------------------- | ------- | ------------------ | ------------------ |
524
+ | `talking` | Running | Running | Hidden |
525
+ | `awaiting-continue` | Running | Stopped and hidden | Looping |
526
+ | `idle` | Running | Stopped and hidden | Stopped and hidden |
470
527
 
471
- `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
528
+ 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.
472
529
 
473
- #### ブロック構成例
530
+ #### Block example
474
531
 
475
532
  ```text
476
533
  define bubble style [hero-dialogue] using text style [default]
@@ -480,22 +537,30 @@ set bubble visual style [NORMAL] for bubble style [hero-dialogue]
480
537
  set bubble tail length [18] for bubble style [hero-dialogue]
481
538
  set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
482
539
  set portrait base [HeroFace] for bubble style [hero-dialogue]
540
+ set portrait [top-left] offset x [-4] y [6] zoom [120] % corner radius [12] px for bubble style [hero-dialogue]
483
541
  set blink frames [HeroEyesOpen,HeroEyesClosed] every [0.4] seconds for bubble style [hero-dialogue]
484
542
  set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
485
543
  set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
544
+ set bubble reveal unit [WORD] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
545
+ set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
546
+ set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
547
+ set bubble voice [HeroVoice] for bubble style [hero-dialogue]
548
+ set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
549
+ set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
486
550
  set runtime variable [input] to []
487
551
  listen for key [Space] set runtime var [input] to [pressed]
488
552
  listen for touch on this sprite set runtime var [input] to [pressed]
489
- say [海へ出発!] with bubble style [hero-dialogue]
490
- wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
553
+ show [Set/sail!] with bubble style [hero-dialogue]
554
+ finish [WORD] with condition [input == "pressed"] or timeout after [10] seconds
555
+ shake this bubble direction [90] count [2] ease [easeInOut]
491
556
  close this bubble
492
557
  ```
493
558
 
494
- プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、overlay DOM、画像leaseを自動解放します。明示的に`scratch-render`を選んだ場合は、従来どおり所有するSVG skinとdrawableも解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
559
+ 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.
495
560
 
496
561
  ### Composition API
497
562
 
498
- TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではSVG Text 0.8.0のlayout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
563
+ Hosts that connect to a TurboWarp runtime renderer can use the public adapter. By default, it uses the SVG Text 0.8.1 named-style handoff when a standalone extension is loaded, otherwise its bundled layout composition, together with an SVG overlay. Load Asset Manager in addition only when using image portraits, lip-sync, continue indicators, or audio assets.
499
564
 
500
565
  ```ts
501
566
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -503,7 +568,7 @@ import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/t
503
568
  const bubbles = createTurboWarpBubbleComposition(runtime);
504
569
  ```
505
570
 
506
- 描画surfaceをhost側で実装する場合は、以下の低レベルComposition APIを利用します。
571
+ If the host implements the rendering surface, use the lower-level Composition API below.
507
572
 
508
573
  ```ts
509
574
  import {
@@ -526,23 +591,23 @@ const bubbles = createBubbleComposition({
526
591
  });
527
592
  ```
528
593
 
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)`を使えます。
594
+ The `declare` lines are type declarations that keep the example short. In a real host, implement and pass `BubbleTextCapability` (text layout, rendering, measurement, and release), `BubbleImageCapability` (image-name resolution), `BubbleAudioCapability` (audio playback), and `BubbleSurfaceFactory` (creation of targets for the outline, text, and portrait). When using `@kubohiroya/turbowarp-svg-text/composition`, adapt it with `createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))` for a skin-based host or `createSvgTextOverlayTextCapability(createSvgTextLayoutComposition())` for an SVG overlay. With a TurboWarp runtime, use `createTurboWarpBubbleComposition(runtime)` instead of implementing these pieces individually.
530
595
 
531
- テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
596
+ For text-only display, omit the Asset Manager import, `createAssetManagerComposition()`, and the `imageResolver` property. Asset Manager is a media path not only for images but also for registering and playing full voice clips, per-unit reveal sounds, and finish cues through `audio.voice`, `audio.reveal`, and `audio.finish`. The TurboWarp adapter connects the stock Asset Manager lazily; a lower-level Composition API host can instead inject its own `audio` capability.
532
597
 
533
- `createSurface`が返すsurfaceは、次のtargetを持ちます。
598
+ The surface returned by `createSurface` has the following targets.
534
599
 
535
- surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
600
+ 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.
536
601
 
537
- - `text`: `textCapability`が文字layoutを適用するtarget
538
- - `portraitBase`: キャラクター表情のベース画像target
539
- - `portraitBlink`: 目パチ差分target
540
- - `portraitLipSync`: 口パク差分target
541
- - `continueIndicator`: 「次へ」アイコンtarget
602
+ - `text`: Target to which `textCapability` applies text layout
603
+ - `portraitBase`: Target for the character-expression base image
604
+ - `portraitBlink`: Target for the blink variant
605
+ - `portraitLipSync`: Target for the lip-sync variant
606
+ - `continueIndicator`: Target for the “next” icon
542
607
 
543
- 画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
608
+ Image-layer target IDs must be distinct from one another. Targets for layers unused by the style can be omitted.
544
609
 
545
- #### Styleと表示
610
+ #### Styles and display
546
611
 
547
612
  ```ts
548
613
  bubbles.defineStyle({
@@ -577,6 +642,7 @@ bubbles.defineStyle({
577
642
  audio: {
578
643
  voice: "HeroVoice",
579
644
  reveal: "Typewriter",
645
+ finish: "Ready",
580
646
  },
581
647
  showAnimation: { name: "fadeIn", durationSeconds: 0.2 },
582
648
  hideAnimation: { name: "fadeOut", durationSeconds: 0.2 },
@@ -587,26 +653,26 @@ bubbles.defineStyle({
587
653
  textStyle: "dialogue-text",
588
654
  placement: "FOOTER_LIKE",
589
655
  maxWidth: 320,
590
- textLocale: "ja",
656
+ textLocale: "en",
591
657
  });
592
658
 
593
659
  const bubble = await bubbles.show({
594
660
  actor: heroTarget,
595
661
  actorKey: "Hero",
596
662
  kind: "say",
597
- text: "海へ出発!",
663
+ text: "Set sail!",
598
664
  styleName: "hero-dialogue",
599
665
  });
600
666
  ```
601
667
 
602
- `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-continue`へ変更します。
668
+ 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.”
603
669
 
604
670
  ```ts
605
671
  await bubble.setAnimationMode("awaiting-continue");
606
- // 口パクを停止して非表示にし、「次へ」アイコンをループ表示します。
672
+ // Stop and hide lip-sync, then loop the "next" icon.
607
673
 
608
674
  await bubble.setAnimationMode("idle");
609
- // 吹き出しを残したまま、口パクと「次へ」アイコンを停止します。
675
+ // Keep the Bubble visible, but stop lip-sync and the "next" icon.
610
676
 
611
677
  await bubble.revealNext();
612
678
  await bubble.revealAll();
@@ -625,19 +691,19 @@ await bubble.finish({
625
691
  await bubble.close();
626
692
  ```
627
693
 
628
- 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、text capability target、surfaceを解放します。composition間で状態は共有しません。
694
+ 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.
629
695
 
630
- ## ライセンスとソースコード
696
+ ## License and source code
631
697
 
632
- このパッケージの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から参照できます。
698
+ 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.
633
699
 
634
- 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
700
+ Copyright notices and license terms for third-party software incorporated into the distribution are collected in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
635
701
 
636
- ## 開発
702
+ ## Development
637
703
 
638
704
  ```sh
639
705
  pnpm install
640
706
  pnpm check
641
707
  ```
642
708
 
643
- `pnpm check`は型検査、lint、format、単体テスト、配布物検査、外部consumer型検査、npm pack dry-runを実行します。
709
+ `pnpm check` runs type checking, linting, formatting, unit tests, distribution inspection, external-consumer type checking, and an npm pack dry run.