@kubohiroya/turbowarp-bubble 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ import { type BubbleSvgOverlayImageCapability } from "./svg-overlay-surface.js";
2
+ export interface AssetManagerDOMImageResource {
3
+ readonly height: number;
4
+ readonly mimeType: string;
5
+ readonly url: string;
6
+ readonly width: number;
7
+ release(): void;
8
+ }
9
+ export interface AssetManagerDOMImageCapability {
10
+ getMimeType(name: unknown): string;
11
+ isRegistered(name: unknown): boolean;
12
+ resolveDOMImageResource(name: unknown): Promise<AssetManagerDOMImageResource>;
13
+ }
14
+ /**
15
+ * Adapts Asset Manager's host-neutral DOM resource API to Bubble's SVG overlay contract.
16
+ * Asset Manager owns byte validation and SVG sanitization; Bubble owns its capability shape.
17
+ */
18
+ export declare function createAssetManagerSvgOverlayImageCapability(capabilityInput: AssetManagerDOMImageCapability): BubbleSvgOverlayImageCapability;
@@ -0,0 +1,8 @@
1
+ import type { BubbleMotionInput, BubbleScheduler } from "./composition.js";
2
+ export declare function clampMotionProgress(value: number): number;
3
+ export declare function easeMotionProgress(value: number, ease: BubbleMotionInput["ease"]): number;
4
+ /**
5
+ * Drive a motion with Bubble's scheduler so tests and non-browser hosts can
6
+ * provide deterministic time without requestAnimationFrame.
7
+ */
8
+ export declare function runMotionTimeline(scheduler: BubbleScheduler, durationSeconds: number, onFrame: (progress: number) => void): Promise<void>;
@@ -0,0 +1,97 @@
1
+ import { type BubbleImageCapability, type BubbleScheduler, type BubbleStyle, type BubbleSurface, type BubbleTextCapability } from "./composition.js";
2
+ export type BubbleRenderBackend = "scratch-render" | "svg-overlay";
3
+ export type BubbleOverlayUnsupportedBehavior = "error" | "fallback";
4
+ export declare const bubbleRenderBackends: readonly ["scratch-render", "svg-overlay"];
5
+ export declare const defaultBubbleRenderBackend: BubbleRenderBackend;
6
+ export declare const defaultBubbleOverlayUnsupportedBehavior: BubbleOverlayUnsupportedBehavior;
7
+ export interface BubbleSvgOverlayTextLine {
8
+ /** Optional baseline relative to the center of the text layout. */
9
+ readonly baseline?: number;
10
+ readonly text: string;
11
+ /** Optional x coordinate relative to the center of the text layout. */
12
+ readonly x?: number;
13
+ }
14
+ export interface BubbleSvgOverlayTextLayout {
15
+ readonly alignment: "center" | "left" | "right";
16
+ readonly backgroundColor?: string;
17
+ readonly backgroundCornerRadius?: number;
18
+ readonly fill: string;
19
+ readonly fontFamily: string;
20
+ readonly fontSize: number;
21
+ readonly fontStyle?: "normal" | "italic";
22
+ readonly fontWeight?: "normal" | "bold" | number;
23
+ readonly height: number;
24
+ readonly lineHeight: number;
25
+ readonly lines: readonly (string | BubbleSvgOverlayTextLine)[];
26
+ readonly preserveWhitespace?: boolean;
27
+ readonly width: number;
28
+ }
29
+ export interface BubbleSvgOverlayTextCapability {
30
+ layoutText(input: Readonly<{
31
+ nativeSize: Readonly<{
32
+ height: number;
33
+ width: number;
34
+ }>;
35
+ styleName: string;
36
+ text: string;
37
+ }>): BubbleSvgOverlayTextLayout;
38
+ measureText?(input: Readonly<{
39
+ nativeSize: Readonly<{
40
+ height: number;
41
+ width: number;
42
+ }>;
43
+ styleName: string;
44
+ text: string;
45
+ }>): number;
46
+ }
47
+ export interface BubbleSvgOverlayImageResource {
48
+ readonly height: number;
49
+ readonly mimeType: string;
50
+ /** A capability-owned blob URL or an approved raster data URL. */
51
+ readonly src: string;
52
+ /** Required when mimeType is image/svg+xml; the provider owns sanitizing bytes. */
53
+ readonly svgSecurity?: "sanitized";
54
+ readonly width: number;
55
+ /** Required for blob URLs and called on replacement and disposal. */
56
+ readonly release?: () => void | Promise<void>;
57
+ }
58
+ export interface BubbleSvgOverlayImageCapability {
59
+ getMimeType(name: unknown): string;
60
+ isRegistered(name: unknown): boolean;
61
+ resolveImage(name: unknown): BubbleSvgOverlayImageResource | Promise<BubbleSvgOverlayImageResource>;
62
+ }
63
+ export interface BubbleSvgOverlayRenderer {
64
+ addOverlay(element: Element, mode?: string): unknown;
65
+ getNativeSize(): unknown;
66
+ removeOverlay(element: Element): void;
67
+ on?(event: string, listener: (...args: unknown[]) => void): void;
68
+ off?(event: string, listener: (...args: unknown[]) => void): void;
69
+ }
70
+ export interface BubbleSvgOverlayActor {
71
+ readonly id: string;
72
+ readonly isStage: boolean;
73
+ readonly visible?: boolean;
74
+ readonly x?: number;
75
+ readonly y?: number;
76
+ getBoundsForBubble?(): {
77
+ readonly bottom: number;
78
+ readonly left: number;
79
+ readonly right: number;
80
+ readonly top: number;
81
+ };
82
+ onTargetVisualChange?: ((target?: BubbleSvgOverlayActor) => void) | null;
83
+ }
84
+ export interface BubbleSvgOverlaySurfaceManager {
85
+ readonly document: Document;
86
+ readonly renderer: BubbleSvgOverlayRenderer;
87
+ acquire(group: SVGGElement): void;
88
+ release(group: SVGGElement): void;
89
+ updateNativeSize(): Readonly<{
90
+ height: number;
91
+ width: number;
92
+ }>;
93
+ }
94
+ export declare function createSvgOverlayTextAdapter(capabilityInput: BubbleSvgOverlayTextCapability, renderer: Pick<BubbleSvgOverlayRenderer, "getNativeSize">): BubbleTextCapability;
95
+ export declare function createSvgOverlayImageAdapter(capabilityInput: BubbleSvgOverlayImageCapability): BubbleImageCapability;
96
+ export declare function createSvgOverlaySurfaceManager(renderer: BubbleSvgOverlayRenderer, documentInput: Document): BubbleSvgOverlaySurfaceManager;
97
+ export declare function createSvgOverlaySurface(manager: BubbleSvgOverlaySurfaceManager, actor: BubbleSvgOverlayActor, actorKey: string, style: BubbleStyle, scheduler: BubbleScheduler): BubbleSurface;
@@ -9,8 +9,8 @@ export type BubbleTextTarget = object;
9
9
  * Text rendering contract consumed by Bubble composition.
10
10
  *
11
11
  * Bubble owns placement, outer shape, portraits, reveal, and animation. A
12
- * text adapter owns text styles, SVG/text skin creation, measurement, and
13
- * target skin release.
12
+ * text adapter owns text styles, layout or rendering, measurement, and target
13
+ * resource release.
14
14
  */
15
15
  export interface BubbleTextCapability {
16
16
  setText(input: {
@@ -1,6 +1,9 @@
1
1
  import { type BubbleComposition, type BubbleCompositionOptions, type BubbleAudioCapability, type BubbleImageCapability, type BubbleScheduler, type BubbleTextCapability } from "./composition.js";
2
2
  import { type TurboWarpSvgTextExtension } from "./turbowarp-svg-text-adapter.js";
3
- export { createSvgTextCompositionCapability, createTurboWarpSvgTextCapability, type TurboWarpSvgTextExtension, } from "./turbowarp-svg-text-adapter.js";
3
+ export { createAssetManagerSvgOverlayImageCapability, type AssetManagerDOMImageCapability, type AssetManagerDOMImageResource, } from "./asset-manager-image-adapter.js";
4
+ export { createSvgTextCompositionCapability, createSvgTextOverlayTextCapability, createTurboWarpSvgTextCapability, type SvgTextLayoutCompositionLike, type TurboWarpSvgTextExtension, } from "./turbowarp-svg-text-adapter.js";
5
+ import { type BubbleOverlayUnsupportedBehavior, type BubbleRenderBackend, type BubbleSvgOverlayImageCapability, type BubbleSvgOverlayTextCapability } from "./svg-overlay-surface.js";
6
+ export { createSvgOverlayImageAdapter, createSvgOverlaySurface, createSvgOverlaySurfaceManager, createSvgOverlayTextAdapter, bubbleRenderBackends, defaultBubbleOverlayUnsupportedBehavior, defaultBubbleRenderBackend, type BubbleOverlayUnsupportedBehavior, type BubbleRenderBackend, type BubbleSvgOverlayActor, type BubbleSvgOverlayImageCapability, type BubbleSvgOverlayImageResource, type BubbleSvgOverlayRenderer, type BubbleSvgOverlaySurfaceManager, type BubbleSvgOverlayTextCapability, type BubbleSvgOverlayTextLine, type BubbleSvgOverlayTextLayout, } from "./svg-overlay-surface.js";
4
7
  export interface TurboWarpBubbleTarget {
5
8
  readonly id: string;
6
9
  readonly isStage: boolean;
@@ -30,6 +33,10 @@ export interface TurboWarpBubbleRenderer {
30
33
  /** Scratch/TurboWarp's ghost effect is used to implement fade motions. */
31
34
  updateDrawableEffect?(drawableId: number, effectName: string, value: number): void;
32
35
  setDrawableOrder?(drawableId: number, order: number, layerGroup: string, relative?: boolean): void;
36
+ addOverlay?(element: Element, mode?: string): unknown;
37
+ removeOverlay?(element: Element): void;
38
+ on?(event: string, listener: (...args: unknown[]) => void): void;
39
+ off?(event: string, listener: (...args: unknown[]) => void): void;
33
40
  }
34
41
  export interface TurboWarpAssetManagerExtension {
35
42
  isLoaded(args: Readonly<{
@@ -57,13 +64,23 @@ export interface TurboWarpBubbleRuntime {
57
64
  requestRedraw?(): void;
58
65
  }
59
66
  export interface TurboWarpBubbleCompositionOptions {
67
+ /** Defaults to the skin-free svg-overlay backend. */
68
+ readonly bubbleRenderBackend?: BubbleRenderBackend;
69
+ /** Defaults to error so the skin-free default never silently creates skins. */
70
+ readonly svgOverlayUnsupportedBehavior?: BubbleOverlayUnsupportedBehavior;
71
+ /** Host-neutral text layout supplied by turbowarp-svg-text or another host. */
72
+ readonly svgOverlayTextCapability?: BubbleSvgOverlayTextCapability;
73
+ /** Releasable DOM image resources supplied by Asset Manager or another host. */
74
+ readonly svgOverlayImageCapability?: BubbleSvgOverlayImageCapability;
75
+ /** Browser document override for packaged players and deterministic tests. */
76
+ readonly document?: Document;
60
77
  readonly imageResolver?: BubbleImageCapability;
61
78
  readonly audio?: BubbleAudioCapability;
62
79
  readonly textCapability?: BubbleTextCapability;
63
80
  readonly scheduler?: BubbleScheduler;
64
81
  readonly onAnimationError?: BubbleCompositionOptions["onAnimationError"];
65
82
  }
66
- export type BubbleRuntimeAdapterErrorCode = "BUBBLE-RUNTIME-001" | "BUBBLE-RUNTIME-002" | "BUBBLE-RUNTIME-003";
83
+ export type BubbleRuntimeAdapterErrorCode = "BUBBLE-RUNTIME-001" | "BUBBLE-RUNTIME-002" | "BUBBLE-RUNTIME-003" | "BUBBLE-RUNTIME-004";
67
84
  export declare class BubbleRuntimeAdapterError extends Error {
68
85
  readonly code: BubbleRuntimeAdapterErrorCode;
69
86
  constructor(code: BubbleRuntimeAdapterErrorCode, message: string);
@@ -1,4 +1,5 @@
1
1
  import type { BubbleTextCapability } from "./text-capability.js";
2
+ import type { BubbleSvgOverlayTextCapability } from "./svg-overlay-surface.js";
2
3
  export interface TurboWarpSvgTextExtension {
3
4
  setText(args: Readonly<{
4
5
  STYLE: unknown;
@@ -9,6 +10,34 @@ export interface TurboWarpSvgTextExtension {
9
10
  measureText?(styleName: unknown, text: unknown): number;
10
11
  releaseTextActor(target: unknown): boolean;
11
12
  }
13
+ interface SvgTextLayoutLineLike {
14
+ readonly baseline: number;
15
+ readonly text: string;
16
+ readonly width: number;
17
+ readonly x: number;
18
+ }
19
+ interface SvgTextLayoutLike {
20
+ readonly height: number;
21
+ readonly lines: readonly SvgTextLayoutLineLike[];
22
+ readonly preserveWhitespace: boolean;
23
+ readonly style: Readonly<{
24
+ alignment: "center" | "left" | "right";
25
+ backgroundColor: string;
26
+ cornerRadius: number;
27
+ font: string;
28
+ fontSize: number;
29
+ lineHeight: number;
30
+ textColor: string;
31
+ }>;
32
+ readonly width: number;
33
+ }
34
+ export interface SvgTextLayoutCompositionLike {
35
+ layoutText(input: Readonly<{
36
+ nativeSize: readonly [width: number, height: number];
37
+ styleName: string;
38
+ text: string;
39
+ }>): SvgTextLayoutLike;
40
+ }
12
41
  /**
13
42
  * Adapt the TurboWarp SVG Text extension to Bubble's host-neutral text
14
43
  * capability contract.
@@ -19,3 +48,9 @@ export declare function createTurboWarpSvgTextCapability(extensionInput: unknown
19
48
  * This helper keeps the core package independent from SVG Text's target type.
20
49
  */
21
50
  export declare function createSvgTextCompositionCapability(compositionInput: unknown): BubbleTextCapability;
51
+ /**
52
+ * Adapt SVG Text's host-neutral layout composition to Bubble's SVG overlay.
53
+ * The adapter preserves SVG Text's line coordinates without creating skins.
54
+ */
55
+ export declare function createSvgTextOverlayTextCapability(compositionInput: SvgTextLayoutCompositionLike): BubbleSvgOverlayTextCapability;
56
+ export {};
@@ -78,63 +78,38 @@
78
78
  <text x="312" y="302" class="small">Next2</text>
79
79
  <text x="443" y="302" class="small">次へアイコン 2枚目</text>
80
80
  </g></g>
81
- <g role="group" aria-label="SVG Textでdialogue-text styleを定義">
82
- <rect x="48" y="506" width="510" height="94" rx="12" fill="#9966ff" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
83
- <rect x="66" y="506" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
84
- <text x="65" y="533" class="block-text" style="font-size:12px">define text style</text>
85
- <rect x="198.47999999999996" y="514" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
86
- <text x="206.47999999999996" y="533" class="input-text" style="font-size:12px">dialogue-text</text>
87
- <text x="318.19999999999993" y="533" class="block-text" style="font-size:12px">background</text>
88
- <rect x="399.5999999999999" y="514" width="68.07999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
89
- <text x="407.5999999999999" y="533" class="input-text" style="font-size:12px">#fff4cc</text>
90
- <text x="65" y="558" class="block-text" style="font-size:12px">text</text>
91
- <rect x="101.75999999999999" y="539" width="68.07999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
92
- <text x="109.75999999999999" y="558" class="input-text" style="font-size:12px">#332200</text>
93
- <text x="176.83999999999997" y="558" class="block-text" style="font-size:12px">font</text>
94
- <rect x="213.59999999999997" y="539" width="105.27999999999999" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
95
- <text x="221.59999999999997" y="558" class="input-text" style="font-size:12px">Noto Sans JP</text>
96
- <text x="325.87999999999994" y="558" class="block-text" style="font-size:12px">size</text>
97
- <rect x="362.63999999999993" y="539" width="38.32" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
98
- <text x="370.63999999999993" y="558" class="input-text" style="font-size:12px">100</text>
99
- <text x="407.9599999999999" y="558" class="block-text" style="font-size:12px">align</text>
100
- <rect x="452.1599999999999" y="539" width="45.76" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
101
- <text x="460.1599999999999" y="558" class="input-text" style="font-size:12px">left</text>
102
- <text x="65" y="583" class="block-text" style="font-size:12px">bubble direction</text>
103
- <rect x="191.03999999999996" y="564" width="34" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
104
- <text x="199.03999999999996" y="583" class="input-text" style="font-size:12px">up</text>
105
- </g>
106
81
  <g role="group" aria-label="Bubble styleを定義">
107
- <rect x="48" y="612" width="510" height="50" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
108
- <rect x="66" y="612" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
109
- <text x="65" y="643" class="block-text" style="font-size:12px">define bubble style</text>
110
- <rect x="213.35999999999999" y="624" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
111
- <text x="221.35999999999999" y="643" class="input-text" style="font-size:12px">hero-dialogue</text>
112
- <text x="333.08" y="643" class="block-text" style="font-size:12px">using text style</text>
113
- <rect x="459.11999999999995" y="624" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
114
- <text x="467.11999999999995" y="643" class="input-text" style="font-size:12px">dialogue-text</text>
82
+ <rect x="48" y="506" width="510" height="50" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
83
+ <rect x="66" y="506" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
84
+ <text x="65" y="537" class="block-text" style="font-size:12px">define bubble style</text>
85
+ <rect x="213.35999999999999" y="518" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
86
+ <text x="221.35999999999999" y="537" class="input-text" style="font-size:12px">hero-dialogue</text>
87
+ <text x="333.08" y="537" class="block-text" style="font-size:12px">using text style</text>
88
+ <rect x="459.11999999999995" y="518" width="68.07999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
89
+ <text x="467.11999999999995" y="537" class="input-text" style="font-size:12px">default</text>
115
90
  </g>
116
91
  <g role="group" aria-label="Bubbleの配置を設定">
117
- <rect x="48" y="672" width="510" height="50" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
118
- <rect x="66" y="672" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
119
- <text x="65" y="703" class="block-text" style="font-size:12px">set bubble placement</text>
120
- <rect x="220.79999999999998" y="684" width="75.51999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
121
- <text x="228.79999999999998" y="703" class="input-text" style="font-size:12px">up-right</text>
122
- <text x="303.31999999999994" y="703" class="block-text" style="font-size:12px">for bubble style</text>
123
- <rect x="429.3599999999999" y="684" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
124
- <text x="437.3599999999999" y="703" class="input-text" style="font-size:12px">hero-dialogue</text>
92
+ <rect x="48" y="566" width="510" height="50" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
93
+ <rect x="66" y="566" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
94
+ <text x="65" y="597" class="block-text" style="font-size:12px">set bubble placement</text>
95
+ <rect x="220.79999999999998" y="578" width="75.51999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
96
+ <text x="228.79999999999998" y="597" class="input-text" style="font-size:12px">up-right</text>
97
+ <text x="303.31999999999994" y="597" class="block-text" style="font-size:12px">for bubble style</text>
98
+ <rect x="429.3599999999999" y="578" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
99
+ <text x="437.3599999999999" y="597" class="input-text" style="font-size:12px">hero-dialogue</text>
125
100
  </g>
126
101
  <g role="group" aria-label="表情ベースを設定">
127
- <rect x="48" y="732" width="510" height="50" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
128
- <rect x="66" y="732" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
129
- <text x="65" y="763" class="block-text" style="font-size:12px">set portrait base</text>
130
- <rect x="198.47999999999996" y="744" width="75.51999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
131
- <text x="206.47999999999996" y="763" class="input-text" style="font-size:12px">HeroFace</text>
132
- <text x="280.99999999999994" y="763" class="block-text" style="font-size:12px">for bubble style</text>
133
- <rect x="407.0399999999999" y="744" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
134
- <text x="415.0399999999999" y="763" class="input-text" style="font-size:12px">hero-dialogue</text>
135
- </g>
136
- <text x="52" y="804" class="body">続けて blink・lip-sync・continue のフレームを設定</text>
137
- <text x="52" y="832" class="small">目パチ 0.4秒 / 口パク 0.1秒 / 次へ 0.2秒</text>
102
+ <rect x="48" y="626" width="510" height="50" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
103
+ <rect x="66" y="626" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
104
+ <text x="65" y="657" class="block-text" style="font-size:12px">set portrait base</text>
105
+ <rect x="198.47999999999996" y="638" width="75.51999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
106
+ <text x="206.47999999999996" y="657" class="input-text" style="font-size:12px">HeroFace</text>
107
+ <text x="280.99999999999994" y="657" class="block-text" style="font-size:12px">for bubble style</text>
108
+ <rect x="407.0399999999999" y="638" width="112.71999999999998" height="25" rx="12.5" fill="#ffffff" fill-opacity="0.96"/>
109
+ <text x="415.0399999999999" y="657" class="input-text" style="font-size:12px">hero-dialogue</text>
110
+ </g>
111
+ <text x="52" y="698" class="body">続けて blink・lip-sync・continue のフレームを設定</text>
112
+ <text x="52" y="726" class="small">目パチ 0.4秒 / 口パク 0.1秒 / 次へ 0.2秒</text>
138
113
  <g role="group" aria-label="目パチフレームを設定">
139
114
  <rect x="640" y="150" width="510" height="70" rx="12" fill="#ff6680" stroke="#000000" stroke-opacity="0.14" stroke-width="2"/>
140
115
  <rect x="658" y="150" width="28" height="6" rx="3" fill="#000000" fill-opacity="0.18"/>
@@ -2,22 +2,23 @@
2
2
 
3
3
  このマニュアルでは、`turbowarp-bubble`をTurboWarpのカスタム拡張機能として使い、SVG本体、文字、キャラクター表情、目パチ、口パク、「次へ」アイコンを組み合わせたBubbleを表示します。
4
4
 
5
+ > **紙芝居DSL 4.0集約ランタイム:** 集約ランタイムのパレットで**Bubble**見出し直下のドキュメントボタンを押すと、このマニュアルを開けます。集約されたブロックも、ここで説明するstyle、配置、portrait、逐次表示、音声、待機、animation、clone、自動解放の動作を保ち、拡張機能別の名前空間とBubbleアイコンで由来を識別できます。
6
+
5
7
  ![Next1とNext2を個別登録し、入力listenerを準備してBubble内蔵待機を使うブロック例](./assets/block-quick-start.svg)
6
8
 
7
9
  ## 1. 必要な拡張機能
8
10
 
9
- 入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。Bubbleは文字Bubbleの既定`BubbleTextCapability` adapterとしてSVG Textを使います。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
11
+ 入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.0のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
10
12
 
11
13
  | 順番 | 拡張機能 | 読み込み先 |
12
14
  | ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
13
15
  | 1 | Temporary Variables | TurboWarpの拡張機能ライブラリから追加 |
14
- | 2 | Async Input 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js` |
15
- | 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
16
- | 4 | Asset Manager 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js` |
17
- | 5 | SVG Text 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js` |
18
- | 6 | Bubble 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js` |
16
+ | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
17
+ | 3 | Runtime Expression 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js` |
18
+ | 4 | Asset Manager 0.11.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.11.0/dist/asset-manager.js` |
19
+ | 5 | Bubble 0.8.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.8.0/dist/turbowarp-bubble.js` |
19
20
 
20
- 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。表示時に既定のSVG Text adapterが、画像・メディア機能の使用時にAsset Managerが、待機開始時にAsync InputかRuntime Expressionが見つからなければ、Bubbleは明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入でき、その場合SVG Textは不要です。
21
+ 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、待機開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。
21
22
 
22
23
  参考:
23
24
 
@@ -56,30 +57,22 @@ register resource [costume:Assets:Next2] as asset [Next2]
56
57
 
57
58
  URL画像を使う場合は、`RESOURCE_ID`へHTTPS URLを指定します。Bubbleに設定できるのは、Asset Managerへ登録済みでMIME typeが`image/*`のアセットだけです。
58
59
 
59
- ## 3. 文字styleを定義する
60
+ ## 3. 文字layout styleを選ぶ
60
61
 
61
- SVG Textで、Bubbleの文字部分に使う名前付きstyleを定義します。
62
+ standalone BubbleはSVG Text 0.8.0のlayout compositionを内包します。`default`または任意の名前を指定すると、初回参照時に背景透明のSVG Text既定styleとして初期化されます。
62
63
 
63
64
  ```text
64
- define text style [dialogue-text]
65
- background [#fff4cc]
66
- text [#332200]
67
- font [Noto Sans JP]
68
- size [100]
69
- align [left]
70
- bubble direction [up]
65
+ define bubble style [hero-dialogue] using text style [default]
71
66
  ```
72
67
 
73
- Bubbleは`dialogue-text`という名前を参照します。文字styleとBubble styleはruntime状態なので、通常は緑の旗が押されたときに毎回定義します。
74
-
75
- SVG Text 0.4.xは文字providerです。名前付き文字styleの定義、SVG文字skinの生成、文字幅の測定を担当します。Bubbleの配置は`set bubble placement`で設定し、tailや吹き出し外形はSVG Text providerの責務ではありません。
68
+ 独自のfont、色、alignmentを使うアプリhostは、`createSvgTextLayoutComposition()`へstyleを定義し、`createSvgTextOverlayTextCapability()`でBubbleへ注入します。既定経路も同じ`layoutText()`を使い、SVG文字skinは生成しません。Bubbleの配置、tail、吹き出し外形はBubble側が担当します。
76
69
 
77
70
  ## 4. Bubble styleを定義する
78
71
 
79
- まず、Bubble style名とSVG Textのstyle名を関連付けます。
72
+ まず、Bubble style名と文字layout style名を関連付けます。
80
73
 
81
74
  ```text
82
- define bubble style [hero-dialogue] using text style [dialogue-text]
75
+ define bubble style [hero-dialogue] using text style [default]
83
76
  set bubble placement [up-right] for bubble style [hero-dialogue]
84
77
  set bubble distance [12] for bubble style [hero-dialogue]
85
78
  set bubble visual style [NORMAL] for bubble style [hero-dialogue]
@@ -261,7 +254,7 @@ Bubble styleの定義は拡張機能内で共有されますが、表示中のBu
261
254
  2. 各clone自身から`say`または`think`を実行します。
262
255
  3. animation mode変更とcloseも、表示したのと同じcloneから実行します。
263
256
 
264
- cloneが停止・削除された場合は、そのtargetに属するtimer、SVG Text skin、drawableが自動解放されます。
257
+ cloneが停止・削除された場合は、そのtargetに属するtimer、overlay DOM、画像leaseが自動解放されます。明示的な`scratch-render`ではskinとdrawableも解放されます。
265
258
 
266
259
  ## 11. ブロック一覧
267
260
 
@@ -301,7 +294,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG
301
294
  | 状況 | 原因と対処 |
302
295
  | ---------------------------------- | ------------------------------------------------------------------------ |
303
296
  | Asset Managerを要求するエラー | 画像・メディアアセットを使う前にAsset Manager 0.7.xを読み込む |
304
- | 既定text adapterを要求するエラー | SVG Text 0.4.xをサンドボックスなしで読み込む |
297
+ | SVG overlay backendのエラー | `renderer.addOverlay()`対応hostを使うか`scratch-render`を明示する |
305
298
  | Async Inputを要求するエラー | Bubble待機より前にAsync Input 0.3.xをサンドボックスなしで読み込む |
306
299
  | Runtime Expressionを要求するエラー | Bubble待機より前にRuntime Expression 0.3.xをサンドボックスなしで読み込む |
307
300
  | `bubble style is not defined` | `define bubble style`を先に実行する。緑の旗の再実行時も再定義する |
@@ -315,7 +308,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG
315
308
 
316
309
  ## 13. 自動解放されるタイミング
317
310
 
318
- 次の場合、Bubbleが所有するtimer、text skin、renderer drawableは自動的に解放されます。
311
+ 次の場合、Bubbleが所有するtimer、overlay DOM、画像leaseは自動的に解放されます。`scratch-render`を明示した場合はtext skinとrenderer drawableも解放されます。
319
312
 
320
313
  - `close this bubble`
321
314
  - 同じsprite/cloneで次の`say`または`think`を実行したとき
@@ -2,22 +2,23 @@
2
2
 
3
3
  This manual explains how to use `turbowarp-bubble` as an unsandboxed TurboWarp custom extension. A Bubble combines an SVG body, text, a character portrait, blinking and lip-sync layers, and an animated continue indicator.
4
4
 
5
+ > **Kamishibai DSL 4.0 bundle:** In the combined runtime palette, click the documentation button directly below the **Bubble** member heading to open this manual. The bundled blocks keep the styles, placement, portrait, reveal, audio, wait, animation, clone, and cleanup behavior documented here; their member namespace and Bubble icon identify their origin.
6
+
5
7
  ![A quick-start block sequence that registers Next1 and Next2 separately, prepares input listeners, then uses Bubble's integrated wait](./assets/block-quick-start.svg)
6
8
 
7
9
  ## 1. Load the required extensions
8
10
 
9
- The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. Bubble uses SVG Text as its default `BubbleTextCapability` adapter for text bubbles. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
11
+ The complete input-wait example uses five extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. Bubble bundles the host-neutral SVG Text 0.8.0 layout provider and creates no text skin on its default SVG overlay. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
10
12
 
11
13
  | Order | Extension | URL |
12
14
  | ----: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
13
15
  | 1 | Temporary Variables | Add from the TurboWarp extension library |
14
- | 2 | Async Input 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js` |
15
- | 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
16
- | 4 | Asset Manager 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js` |
17
- | 5 | SVG Text 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js` |
18
- | 6 | Bubble 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js` |
16
+ | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
17
+ | 3 | Runtime Expression 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js` |
18
+ | 4 | Asset Manager 0.11.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.11.0/dist/asset-manager.js` |
19
+ | 5 | Bubble 0.8.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.8.0/dist/turbowarp-bubble.js` |
19
20
 
20
- To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if the default SVG Text adapter is missing when it displays a Bubble, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait. The lower-level Composition API can use another text capability and does not require SVG Text.
21
+ To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if the renderer lacks the default SVG overlay APIs, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait. The lower-level Composition API can inject another text capability.
21
22
 
22
23
  See also:
23
24
 
@@ -56,30 +57,22 @@ register resource [costume:Assets:Next2] as asset [Next2]
56
57
 
57
58
  For a remote image, pass its HTTPS URL as `RESOURCE_ID`. Bubble accepts only assets already registered with Asset Manager whose MIME type is `image/*`.
58
59
 
59
- ## 3. Define a text style
60
+ ## 3. Select a text layout style
60
61
 
61
- Use SVG Text to define the named style for the Bubble's text layer.
62
+ Standalone Bubble bundles the SVG Text 0.8.0 layout composition. `default`, or any other name, is initialized on first use with SVG Text defaults and a transparent background.
62
63
 
63
64
  ```text
64
- define text style [dialogue-text]
65
- background [#fff4cc]
66
- text [#332200]
67
- font [Noto Sans JP]
68
- size [100]
69
- align [left]
70
- bubble direction [up]
65
+ define bubble style [hero-dialogue] using text style [default]
71
66
  ```
72
67
 
73
- Bubble refers to this style as `dialogue-text`. Text and Bubble styles are runtime state, so normally define them again whenever the green flag is clicked.
74
-
75
- SVG Text 0.4.x is a text provider: it defines named text styles, creates SVG text skins, and measures text. Bubble placement is configured by `set bubble placement`; the SVG Text provider does not own Bubble direction, tail, or outer shape.
68
+ Application hosts that need custom fonts, colors, or alignment can define styles on `createSvgTextLayoutComposition()` and inject them through `createSvgTextOverlayTextCapability()`. The default uses the same `layoutText()` API and does not create an SVG text skin. Bubble owns placement, tail, and outer shape.
76
69
 
77
70
  ## 4. Define a Bubble style
78
71
 
79
- First associate a Bubble style name with an SVG Text style name.
72
+ First associate a Bubble style name with a text layout style name.
80
73
 
81
74
  ```text
82
- define bubble style [hero-dialogue] using text style [dialogue-text]
75
+ define bubble style [hero-dialogue] using text style [default]
83
76
  set bubble placement [up-right] for bubble style [hero-dialogue]
84
77
  set bubble distance [12] for bubble style [hero-dialogue]
85
78
  set bubble visual style [NORMAL] for bubble style [hero-dialogue]
@@ -261,7 +254,7 @@ Bubble style definitions are shared within the extension, but each sprite or clo
261
254
  2. Run `say` or `think` from each clone itself.
262
255
  3. Change the animation mode and close the Bubble from the same clone that displayed it.
263
256
 
264
- When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables owned by that target are released automatically.
257
+ When a clone stops or is deleted, its timers, overlay DOM, and image leases are released automatically. Explicit `scratch-render` mode also releases skins and drawables.
265
258
 
266
259
  ## 11. Block reference
267
260
 
@@ -298,24 +291,24 @@ When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables
298
291
 
299
292
  ## 12. Troubleshooting
300
293
 
301
- | Symptom | Cause and solution |
302
- | ------------------------------------ | --------------------------------------------------------------------------- |
303
- | Asset Manager required error | Load Asset Manager 0.7.x without sandbox before using image/media assets |
304
- | Default text adapter required error | Load SVG Text 0.4.x without sandbox |
305
- | Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
306
- | Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
307
- | `bubble style is not defined` | Run `define bubble style` first, including after restarting with green flag |
308
- | Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
309
- | Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
310
- | Only one continue frame | Supply at least two frames, or clear the setting |
311
- | Frame interval error | Use a finite `SECONDS` value greater than zero |
312
- | Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
313
- | Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
314
- | Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
294
+ | Symptom | Cause and solution |
295
+ | ------------------------------------ | ----------------------------------------------------------------------------- |
296
+ | Asset Manager required error | Load Asset Manager 0.7.x without sandbox before using image/media assets |
297
+ | SVG overlay backend error | Use a host with `renderer.addOverlay()` or explicitly select `scratch-render` |
298
+ | Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
299
+ | Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
300
+ | `bubble style is not defined` | Run `define bubble style` first, including after restarting with green flag |
301
+ | Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
302
+ | Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
303
+ | Only one continue frame | Supply at least two frames, or clear the setting |
304
+ | Frame interval error | Use a finite `SECONDS` value greater than zero |
305
+ | Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
306
+ | Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
307
+ | Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
315
308
 
316
309
  ## 13. Automatic cleanup
317
310
 
318
- Bubble automatically releases its owned timers, text skins, and renderer drawables when:
311
+ Bubble automatically releases its owned timers, overlay DOM, and image leases in the following cases. Explicit `scratch-render` mode also releases its text skins and renderer drawables.
319
312
 
320
313
  - `close this bubble` runs;
321
314
  - the same sprite or clone runs another `say` or `think`;