@kubohiroya/turbowarp-svg-text 0.2.0 → 0.3.0

package/README.md

@@ -15,7 +15,7 @@ See the [English guide](https://kubohiroya.github.io/turbowarp-svg-text/) or [Ja
 - Immediately update visible bubbles and SVG text when a style is redefined or the stage size changes.
 - Keep legacy size-based say/think opcodes hidden but executable for saved-project compatibility.
 
-Animation is not included in version 0.1.0.
+Animation is not included in this release.
 
 ## Blocks
 
@@ -42,7 +42,7 @@ Defines or replaces a named style. `ALIGN` accepts `left`, `center`, or `right`.
 | `up-left`          | `northwest`       |
 | `up-up-left`       | `north-northwest` |
 
-Direction input is trimmed and case-insensitive. Existing eight-way values keep their original positions.
+Direction input is trimmed and case-insensitive. Direction is measured from the actor center to the bubble body center. Changing the bubble width or height does not change the requested angle, although stage-edge clamping can move the bubble when necessary.
 
 `DIRECTION` also accepts any number from `0` through `360` and uses Scratch sprite direction semantics: `0` is up, `90` is right, `180` is down, `270` is left, and `360` is up again. Values between the named directions are placed continuously without rounding to the nearest of the sixteen menu positions. Values outside this range fall back to the initial `up-right` direction.
 
@@ -82,7 +82,7 @@ Style sizes are clamped to 1–1000. A blank or non-finite value uses 100.
 Load the following URL as a TurboWarp custom extension and allow it to run unsandboxed:
 
 ```text
-https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.1.0/dist/svg-text.js
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.3.0/dist/svg-text.js
 ```
 
 ```text
@@ -91,6 +91,32 @@ say [Once upon a time...\nIn a village by the sea...] with style [narration]
 set this sprite text [Act One\nUrashima Taro] with style [narration]
 ```
 
+### Composition API
+
+Composite runtimes can import `@kubohiroya/turbowarp-svg-text/composition` without registering the
+Standalone extension or adding blocks. The caller supplies one TurboWarp runtime and explicit
+targets.
+
+```js
+import { createSvgTextComposition } from "@kubohiroya/turbowarp-svg-text/composition";
+
+const svgText = createSvgTextComposition({ runtime: Scratch.vm.runtime });
+svgText.defineStyle({
+  name: "title",
+  alignment: "center",
+  backgroundColor: "#112233",
+  direction: "up",
+  font: "Noto Sans JP",
+  fontPercent: 150,
+  textColor: "#ffffff",
+});
+svgText.setText({ target, text: "The End", styleName: "title" });
+```
+
+Each composition owns its styles and the SVG skins it applies. Use `releaseTarget(target)` when a
+target leaves the composition, or call the idempotent finalizer `releaseAll()` to destroy every
+owned skin. Mutating methods reject calls after `releaseAll()`.
+
 ## Development
 
 ```bash

package/dist/composition.js

@@ -0,0 +1,918 @@
+var block_definitions_default = {
+	extensionName: "SVG Text",
+	blocks: [
+		{
+			"opcode": "defineStyle",
+			"blockType": "COMMAND",
+			"text": "define text style [STYLE] background [BACKGROUND] text [TEXT_COLOR] font [FONT] size [SIZE] align [ALIGN] bubble direction [DIRECTION]",
+			"description": "Defines or replaces a named responsive text style. Bubble direction is measured from the actor center to the bubble body center and accepts names, compass aliases, or Scratch-style degrees from 0 to 360.",
+			"arguments": {
+				"STYLE": {
+					"type": "STRING",
+					"defaultValue": "default"
+				},
+				"BACKGROUND": {
+					"type": "COLOR",
+					"defaultValue": "#ffffff"
+				},
+				"TEXT_COLOR": {
+					"type": "COLOR",
+					"defaultValue": "#575e75"
+				},
+				"FONT": {
+					"type": "STRING",
+					"defaultValue": "Helvetica"
+				},
+				"SIZE": {
+					"type": "NUMBER",
+					"defaultValue": 100
+				},
+				"ALIGN": {
+					"type": "STRING",
+					"defaultValue": "left",
+					"menu": "alignment"
+				},
+				"DIRECTION": {
+					"type": "STRING",
+					"defaultValue": "up-right",
+					"menu": "direction"
+				}
+			}
+		},
+		{
+			"opcode": "setText",
+			"blockType": "COMMAND",
+			"text": "set this sprite text [TEXT] with style [STYLE]",
+			"description": "Replaces this sprite's skin with responsive styled SVG text.",
+			"arguments": {
+				"TEXT": {
+					"type": "STRING",
+					"defaultValue": "Title\\nSubtitle"
+				},
+				"STYLE": {
+					"type": "STRING",
+					"defaultValue": "default"
+				}
+			}
+		},
+		{
+			"opcode": "sayWithStyle",
+			"blockType": "COMMAND",
+			"text": "say [MESSAGE] with style [STYLE]",
+			"description": "Shows a responsive say bubble using a named style.",
+			"arguments": {
+				"MESSAGE": {
+					"type": "STRING",
+					"defaultValue": "Hello!\\nHow are you?"
+				},
+				"STYLE": {
+					"type": "STRING",
+					"defaultValue": "default"
+				}
+			}
+		},
+		{
+			"opcode": "thinkWithStyle",
+			"blockType": "COMMAND",
+			"text": "think [MESSAGE] with style [STYLE]",
+			"description": "Shows a responsive think bubble using a named style.",
+			"arguments": {
+				"MESSAGE": {
+					"type": "STRING",
+					"defaultValue": "Hmm...\\nI wonder."
+				},
+				"STYLE": {
+					"type": "STRING",
+					"defaultValue": "default"
+				}
+			}
+		},
+		{
+			"opcode": "say",
+			"blockType": "COMMAND",
+			"text": "say [MESSAGE] with font size [SIZE]",
+			"description": "Legacy size-based say bubble kept for saved-project compatibility.",
+			"hideFromPalette": true,
+			"arguments": {
+				"MESSAGE": {
+					"type": "STRING",
+					"defaultValue": "Hello!\\nHow are you?"
+				},
+				"SIZE": {
+					"type": "NUMBER",
+					"defaultValue": 100
+				}
+			}
+		},
+		{
+			"opcode": "think",
+			"blockType": "COMMAND",
+			"text": "think [MESSAGE] with font size [SIZE]",
+			"description": "Legacy size-based think bubble kept for saved-project compatibility.",
+			"hideFromPalette": true,
+			"arguments": {
+				"MESSAGE": {
+					"type": "STRING",
+					"defaultValue": "Hmm...\\nI wonder."
+				},
+				"SIZE": {
+					"type": "NUMBER",
+					"defaultValue": 100
+				}
+			}
+		}
+	],
+	menus: {
+		"alignment": {
+			"acceptReporters": true,
+			"items": [
+				"left",
+				"center",
+				"right"
+			]
+		},
+		"direction": {
+			"acceptReporters": true,
+			"items": [
+				"up",
+				"up-up-right",
+				"up-right",
+				"right-up-right",
+				"right",
+				"right-down-right",
+				"down-right",
+				"down-down-right",
+				"down",
+				"down-down-left",
+				"down-left",
+				"left-down-left",
+				"left",
+				"left-up-left",
+				"up-left",
+				"up-up-left"
+			]
+		}
+	}
+};
+//#endregion
+//#region src/config.ts
+var extensionConfig = {
+	id: "kubohiroyasvgtext",
+	slug: "svg-text",
+	name: "SVG Text",
+	description: "Responsive named-style bubbles and SVG text actors for TurboWarp.",
+	author: "Hiroya Kubo",
+	license: "MPL-2.0",
+	unsandboxed: true
+};
+//#endregion
+//#region src/extension.ts
+var bubbleDirections = [
+	"up",
+	"up-up-right",
+	"up-right",
+	"right-up-right",
+	"right",
+	"right-down-right",
+	"down-right",
+	"down-down-right",
+	"down",
+	"down-down-left",
+	"down-left",
+	"left-down-left",
+	"left",
+	"left-up-left",
+	"up-left",
+	"up-up-left"
+];
+var bubbleDirectionAliases = /* @__PURE__ */ new Map([
+	["east", "right"],
+	["east-northeast", "right-up-right"],
+	["east-southeast", "right-down-right"],
+	["north", "up"],
+	["northeast", "up-right"],
+	["north-northeast", "up-up-right"],
+	["northwest", "up-left"],
+	["north-northwest", "up-up-left"],
+	["south", "down"],
+	["southeast", "down-right"],
+	["south-southeast", "down-down-right"],
+	["southwest", "down-left"],
+	["south-southwest", "down-down-left"],
+	["west", "left"],
+	["west-northwest", "left-up-left"],
+	["west-southwest", "left-down-left"]
+]);
+var intermediateDirectionOffset = Math.SQRT2 - 1;
+var bubbleDirectionVectors = {
+	down: {
+		x: 0,
+		y: -1
+	},
+	"down-down-left": {
+		x: -intermediateDirectionOffset,
+		y: -1
+	},
+	"down-down-right": {
+		x: intermediateDirectionOffset,
+		y: -1
+	},
+	"down-left": {
+		x: -1,
+		y: -1
+	},
+	"down-right": {
+		x: 1,
+		y: -1
+	},
+	left: {
+		x: -1,
+		y: 0
+	},
+	"left-down-left": {
+		x: -1,
+		y: -intermediateDirectionOffset
+	},
+	"left-up-left": {
+		x: -1,
+		y: intermediateDirectionOffset
+	},
+	right: {
+		x: 1,
+		y: 0
+	},
+	"right-down-right": {
+		x: 1,
+		y: -intermediateDirectionOffset
+	},
+	"right-up-right": {
+		x: 1,
+		y: intermediateDirectionOffset
+	},
+	up: {
+		x: 0,
+		y: 1
+	},
+	"up-left": {
+		x: -1,
+		y: 1
+	},
+	"up-right": {
+		x: 1,
+		y: 1
+	},
+	"up-up-left": {
+		x: -intermediateDirectionOffset,
+		y: 1
+	},
+	"up-up-right": {
+		x: intermediateDirectionOffset,
+		y: 1
+	}
+};
+function normalizeVectorComponent(value) {
+	if (Math.abs(value) < 1e-12) return 0;
+	if (Math.abs(1 - Math.abs(value)) < 1e-12) return Math.sign(value);
+	return value;
+}
+function directionVector(direction) {
+	if (typeof direction === "string") return bubbleDirectionVectors[direction];
+	const radians = direction * Math.PI / 180;
+	const rawX = Math.sin(radians);
+	const rawY = Math.cos(radians);
+	return {
+		x: normalizeVectorComponent(rawX),
+		y: normalizeVectorComponent(rawY)
+	};
+}
+var blockDefinitions = block_definitions_default.blocks;
+var definitionMenus = block_definitions_default.menus;
+var EXTENSION_DOCS_URI = "https://kubohiroya.github.io/turbowarp-svg-text/";
+var bubbleStateKey = "Scratch.looks";
+var defaultStyleName$1 = "default";
+var defaultFontPercent = 100;
+var minimumFontPercent = 1;
+var maximumFontPercent = 1e3;
+var maximumFontNameLength = 128;
+var baseStageWidth = 480;
+var baseStageHeight = 360;
+var baseStyle = {
+	maxLineWidth: 170,
+	minWidth: 50,
+	strokeWidth: 4,
+	padding: 10,
+	cornerRadius: 16,
+	tailHeight: 12,
+	fontSize: 14,
+	fontHeightRatio: .9,
+	lineHeight: 16
+};
+var actorStyle = {
+	minimumWidth: 1,
+	padding: 12,
+	cornerRadius: 8
+};
+var initialDefaultStyle = {
+	alignment: "left",
+	backgroundColor: "#ffffff",
+	direction: "up-right",
+	font: "Helvetica",
+	fontPercent: defaultFontPercent,
+	textColor: "#575e75"
+};
+var SvgTextExtension = class {
+	constructor(runtime = Scratch.vm?.runtime, options = {}) {
+		this.styles = /* @__PURE__ */ new Map([[defaultStyleName$1, initialDefaultStyle]]);
+		this.activeStyles = /* @__PURE__ */ new WeakMap();
+		this.textActors = /* @__PURE__ */ new Map();
+		this.pendingStyles = /* @__PURE__ */ new WeakMap();
+		this.alignedSkins = /* @__PURE__ */ new WeakSet();
+		this.targetPositionHooks = /* @__PURE__ */ new WeakMap();
+		if (!runtime) throw new Error("SVG Text requires the TurboWarp VM.");
+		this.runtime = runtime;
+		this.castToString = options.castToString ?? Scratch.Cast.toString;
+		this.handleSayOrThink = this.handleSayOrThink.bind(this);
+		this.handleStageSizeChanged = this.handleStageSizeChanged.bind(this);
+		if (options.listenForRuntimeEvents ?? true) {
+			this.runtime.on("SAY", this.handleSayOrThink);
+			this.runtime.on("STAGE_SIZE_CHANGED", this.handleStageSizeChanged);
+		}
+	}
+	getInfo() {
+		return {
+			id: extensionConfig.id,
+			name: Scratch.translate(block_definitions_default.extensionName),
+			docsURI: EXTENSION_DOCS_URI,
+			color1: "#9966ff",
+			blocks: blockDefinitions.map((block) => this.toScratchBlock(block)),
+			menus: definitionMenus
+		};
+	}
+	defineStyle(args) {
+		const styleName = this.normalizeStyleName(args.STYLE);
+		const definition = {
+			alignment: this.normalizeAlignment(args.ALIGN),
+			backgroundColor: this.normalizeColor(args.BACKGROUND, initialDefaultStyle.backgroundColor),
+			direction: this.normalizeDirection(args.DIRECTION),
+			font: this.normalizeFont(args.FONT),
+			fontPercent: this.normalizeFontPercent(args.SIZE),
+			textColor: this.normalizeColor(args.TEXT_COLOR, initialDefaultStyle.textColor)
+		};
+		this.styles.set(styleName, definition);
+		this.restyleVisibleBubbles(styleName, definition);
+		this.restyleTextActors(styleName);
+	}
+	setText(args, util) {
+		const selection = this.resolveStyle(args.STYLE);
+		this.applyTextActor(util.target, this.normalizeMessage(args.TEXT), selection);
+	}
+	releaseTextActor(target) {
+		const state = this.textActors.get(target);
+		if (!state) return false;
+		this.textActors.delete(target);
+		this.runtime.renderer?.destroySkin?.(state.skinId);
+		this.runtime.requestRedraw?.();
+		return true;
+	}
+	sayWithStyle(args, util) {
+		this.showStyledBubble("say", args, util);
+	}
+	thinkWithStyle(args, util) {
+		this.showStyledBubble("think", args, util);
+	}
+	say(args, util) {
+		this.showLegacyBubble("say", args, util);
+	}
+	think(args, util) {
+		this.showLegacyBubble("think", args, util);
+	}
+	toScratchBlock(block) {
+		return {
+			opcode: block.opcode,
+			blockType: Scratch.BlockType[block.blockType],
+			text: Scratch.translate(block.text),
+			hideFromPalette: block.hideFromPalette ?? false,
+			arguments: Object.fromEntries(Object.entries(block.arguments).map(([name, argument]) => [name, {
+				type: Scratch.ArgumentType[argument.type],
+				defaultValue: argument.defaultValue,
+				...argument.menu === void 0 ? {} : { menu: argument.menu }
+			}]))
+		};
+	}
+	normalizeStyleName(value) {
+		return this.castToString(value).trim() || defaultStyleName$1;
+	}
+	normalizeFontPercent(value) {
+		if (typeof value === "string" && value.trim() === "") return defaultFontPercent;
+		const numericValue = Number(value);
+		if (!Number.isFinite(numericValue)) return defaultFontPercent;
+		return Math.min(maximumFontPercent, Math.max(minimumFontPercent, numericValue));
+	}
+	normalizeMessage(value) {
+		return this.castToString(value).replace(/\\r\\n|\\n|\\r/gu, "\n");
+	}
+	normalizeAlignment(value) {
+		const alignment = this.castToString(value).trim().toLowerCase();
+		if (alignment === "center" || alignment === "right") return alignment;
+		return "left";
+	}
+	normalizeDirection(value) {
+		const direction = this.castToString(value).trim().toLowerCase();
+		if (bubbleDirections.includes(direction)) return direction;
+		const alias = bubbleDirectionAliases.get(direction);
+		if (alias) return alias;
+		if (direction !== "") {
+			const degrees = Number(direction);
+			if (Number.isFinite(degrees) && degrees >= 0 && degrees <= 360) return degrees === 360 ? 0 : degrees;
+		}
+		return initialDefaultStyle.direction;
+	}
+	normalizeColor(value, fallback) {
+		const color = this.castToString(value).trim();
+		if (color === "") return fallback;
+		if (/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/iu.test(color)) return color;
+		if (globalThis.CSS?.supports?.("color", color)) return color;
+		return fallback;
+	}
+	normalizeFont(value) {
+		const font = this.castToString(value).trim();
+		const hasUnsafeCharacter = [...font].some((character) => {
+			const codePoint = character.codePointAt(0) ?? 0;
+			return codePoint <= 31 || codePoint === 127 || ",;{}".includes(character);
+		});
+		if (font === "" || font.length > maximumFontNameLength || hasUnsafeCharacter) return initialDefaultStyle.font;
+		return font;
+	}
+	getStageScale() {
+		const nativeSize = this.runtime.renderer?.getNativeSize?.();
+		if (!Array.isArray(nativeSize) || nativeSize.length < 2) return 1;
+		const width = Number(nativeSize[0]);
+		const height = Number(nativeSize[1]);
+		if (!(width > 0) || !(height > 0)) return 1;
+		return Math.min(width / baseStageWidth, height / baseStageHeight);
+	}
+	createRenderStyle(definition) {
+		const stageScale = this.getStageScale();
+		const fontScale = stageScale * (definition.fontPercent / defaultFontPercent);
+		return {
+			maxLineWidth: baseStyle.maxLineWidth * stageScale,
+			minWidth: baseStyle.minWidth * stageScale,
+			strokeWidth: baseStyle.strokeWidth * stageScale,
+			padding: baseStyle.padding * stageScale,
+			cornerRadius: baseStyle.cornerRadius * stageScale,
+			tailHeight: baseStyle.tailHeight * stageScale,
+			font: definition.font,
+			fontSize: baseStyle.fontSize * fontScale,
+			fontHeightRatio: baseStyle.fontHeightRatio,
+			lineHeight: baseStyle.lineHeight * fontScale,
+			bubbleFill: definition.backgroundColor,
+			textFill: definition.textColor,
+			textAlign: definition.alignment
+		};
+	}
+	createTextActorSvg(text, definition) {
+		const stageScale = this.getStageScale();
+		const fontScale = stageScale * (definition.fontPercent / defaultFontPercent);
+		const fontSize = baseStyle.fontSize * fontScale;
+		const lineHeight = baseStyle.lineHeight * fontScale;
+		const padding = actorStyle.padding * stageScale;
+		const cornerRadius = actorStyle.cornerRadius * stageScale;
+		const lines = text.split("\n");
+		const contentWidth = Math.max(actorStyle.minimumWidth, ...lines.map((line) => this.measureTextWidth(line, fontSize)));
+		const width = Math.max(1, Math.ceil(contentWidth + padding * 2));
+		const height = Math.max(1, Math.ceil(lineHeight * lines.length + padding * 2));
+		const alignment = definition.alignment;
+		const textAnchor = alignment === "center" ? "middle" : alignment === "right" ? "end" : "start";
+		const x = alignment === "center" ? width / 2 : alignment === "right" ? width - padding : padding;
+		const title = this.escapeXml(text);
+		const tspans = lines.map((line, index) => {
+			const y = padding + fontSize + lineHeight * index;
+			return `<tspan x="${this.formatSvgNumber(x)}" y="${this.formatSvgNumber(y)}">${this.escapeXml(line)}</tspan>`;
+		}).join("");
+		return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img"><title>${title}</title><rect width="${width}" height="${height}" rx="${this.formatSvgNumber(cornerRadius)}" fill="${this.escapeXml(definition.backgroundColor)}"/><text xml:space="preserve" fill="${this.escapeXml(definition.textColor)}" font-family="${this.escapeXml(definition.font)}" font-size="${this.formatSvgNumber(fontSize)}" text-anchor="${textAnchor}">${tspans}</text></svg>`;
+	}
+	measureTextWidth(text, fontSize) {
+		let units = 0;
+		for (const character of text) {
+			if (/\p{Mark}/u.test(character)) continue;
+			if (/\s/u.test(character)) {
+				units += .35;
+				continue;
+			}
+			const codePoint = character.codePointAt(0) ?? 0;
+			units += codePoint <= 127 ? .62 : 1;
+		}
+		return units * fontSize;
+	}
+	escapeXml(value) {
+		return value.replace(/[&<>"']/gu, (character) => {
+			switch (character) {
+				case "&": return "&amp;";
+				case "<": return "&lt;";
+				case ">": return "&gt;";
+				case "\"": return "&quot;";
+				default: return "&apos;";
+			}
+		});
+	}
+	formatSvgNumber(value) {
+		return String(Math.round(value * 1e3) / 1e3);
+	}
+	applyTextActor(target, text, selection) {
+		const renderer = this.runtime.renderer;
+		if (typeof target.drawableID !== "number" || typeof renderer?.createSVGSkin !== "function" || typeof renderer.updateDrawableSkinId !== "function") throw new Error("SVG Text requires SVG skin APIs from TurboWarp.");
+		const skinId = renderer.createSVGSkin(this.createTextActorSvg(text, selection.definition));
+		if (!Number.isInteger(skinId) || skinId < 0) throw new Error("TurboWarp did not create an SVG text skin.");
+		try {
+			renderer.updateDrawableSkinId(target.drawableID, skinId);
+		} catch (error) {
+			renderer.destroySkin?.(skinId);
+			throw error;
+		}
+		const previous = this.textActors.get(target);
+		this.textActors.set(target, {
+			skinId,
+			styleName: selection.styleName ?? defaultStyleName$1,
+			text
+		});
+		if (previous && previous.skinId !== skinId) renderer.destroySkin?.(previous.skinId);
+		this.runtime.requestRedraw?.();
+	}
+	resolveStyle(value) {
+		const requestedName = this.normalizeStyleName(value);
+		const definition = this.styles.get(requestedName);
+		if (definition) return {
+			definition,
+			styleName: requestedName
+		};
+		return {
+			definition: this.styles.get(defaultStyleName$1) ?? initialDefaultStyle,
+			styleName: defaultStyleName$1
+		};
+	}
+	getBubbleState(target) {
+		const state = target.getCustomState?.(bubbleStateKey);
+		if (!state || typeof state !== "object") return null;
+		return state;
+	}
+	getTextBubbleSkin(skinId) {
+		const skins = this.runtime.renderer?._allSkins;
+		if (!skins) return null;
+		return (skins instanceof Map ? skins.get(skinId) : skins[skinId]) ?? null;
+	}
+	installAlignmentRenderer(skin) {
+		if (this.alignedSkins.has(skin)) return;
+		const originalRender = skin._renderTextBubble;
+		if (typeof originalRender !== "function") return;
+		skin._renderTextBubble = function renderAlignedTextBubble(scale) {
+			const style = this._style;
+			const alignment = style?.textAlign;
+			const textFill = style?.textFill;
+			if (!style || alignment !== "center" && alignment !== "right" || typeof textFill !== "string") {
+				originalRender.call(this, scale);
+				return;
+			}
+			style.textFill = "transparent";
+			try {
+				originalRender.call(this, scale);
+			} finally {
+				style.textFill = textFill;
+			}
+			const context = this._canvas?.getContext("2d");
+			const lines = this._lines;
+			const width = this._textAreaSize?.width;
+			const padding = style.padding;
+			const lineHeight = style.lineHeight;
+			const fontHeightRatio = style.fontHeightRatio;
+			const fontSize = style.fontSize;
+			if (!context || !lines || typeof width !== "number" || typeof padding !== "number" || typeof lineHeight !== "number" || typeof fontHeightRatio !== "number" || typeof fontSize !== "number") return;
+			context.save();
+			context.fillStyle = textFill;
+			context.textAlign = alignment;
+			const x = alignment === "center" ? width / 2 : width - padding;
+			for (let lineNumber = 0; lineNumber < lines.length; lineNumber += 1) {
+				const line = lines[lineNumber];
+				if (line === void 0) continue;
+				context.fillText(line, x, padding + lineHeight * lineNumber + fontHeightRatio * fontSize);
+			}
+			context.restore();
+		};
+		this.alignedSkins.add(skin);
+	}
+	installTargetPositionHook(target) {
+		const currentHook = target.onTargetVisualChange;
+		if (currentHook === this.targetPositionHooks.get(target)) return;
+		const originalHook = typeof currentHook === "function" ? currentHook : void 0;
+		const positionHook = (changedTarget) => {
+			originalHook?.(changedTarget);
+			this.positionBubble(target);
+		};
+		this.targetPositionHooks.set(target, positionHook);
+		target.onTargetVisualChange = positionHook;
+	}
+	positionBubble(target) {
+		if (target.visible === false) return;
+		const bubbleState = this.getBubbleState(target);
+		const renderer = this.runtime.renderer;
+		if (!bubbleState || typeof bubbleState.drawableId !== "number" || typeof renderer?.getCurrentSkinSize !== "function" || typeof renderer.updateDrawablePosition !== "function") return;
+		const size = renderer.getCurrentSkinSize(bubbleState.drawableId);
+		if (!Array.isArray(size) || size.length < 2) return;
+		const bubbleWidth = Number(size[0]);
+		const bubbleHeight = Number(size[1]);
+		if (!(bubbleWidth > 0) || !(bubbleHeight > 0)) return;
+		let targetBounds;
+		try {
+			targetBounds = target.getBoundsForBubble?.() ?? {
+				bottom: target.y ?? 0,
+				left: target.x ?? 0,
+				right: target.x ?? 0,
+				top: target.y ?? 0
+			};
+		} catch {
+			targetBounds = {
+				bottom: target.y ?? 0,
+				left: target.x ?? 0,
+				right: target.x ?? 0,
+				top: target.y ?? 0
+			};
+		}
+		const nativeSize = renderer.getNativeSize?.();
+		if (!Array.isArray(nativeSize) || nativeSize.length < 2) return;
+		const stageWidth = Number(nativeSize[0]);
+		const stageHeight = Number(nativeSize[1]);
+		if (!(stageWidth > 0) || !(stageHeight > 0)) return;
+		const direction = this.activeStyles.get(target)?.definition.direction ?? initialDefaultStyle.direction;
+		const centerX = (targetBounds.left + targetBounds.right) / 2;
+		const centerY = (targetBounds.top + targetBounds.bottom) / 2;
+		const gap = baseStyle.tailHeight * this.getStageScale();
+		const centeredBubbleX = centerX - bubbleWidth / 2;
+		const centeredBubbleY = centerY + bubbleHeight / 2;
+		const leftBubbleX = targetBounds.left - gap - bubbleWidth;
+		const rightBubbleX = targetBounds.right + gap;
+		const upperBubbleY = targetBounds.top + gap + bubbleHeight;
+		const lowerBubbleY = targetBounds.bottom - gap;
+		const vector = directionVector(direction);
+		const horizontalDistance = vector.x < 0 ? centeredBubbleX - leftBubbleX : rightBubbleX - centeredBubbleX;
+		const verticalDistance = vector.y < 0 ? centeredBubbleY - lowerBubbleY : upperBubbleY - centeredBubbleY;
+		const placementScale = Math.min(vector.x === 0 ? Number.POSITIVE_INFINITY : horizontalDistance / Math.abs(vector.x), vector.y === 0 ? Number.POSITIVE_INFINITY : verticalDistance / Math.abs(vector.y));
+		let x = centeredBubbleX + vector.x * placementScale;
+		let y = centeredBubbleY + vector.y * placementScale;
+		if (vector.x > 0 && !bubbleState.onSpriteRight) {
+			bubbleState.onSpriteRight = true;
+			this.updateTextSkin(bubbleState);
+		} else if (vector.x < 0 && bubbleState.onSpriteRight) {
+			bubbleState.onSpriteRight = false;
+			this.updateTextSkin(bubbleState);
+		}
+		const stageLeft = -stageWidth / 2;
+		const stageRight = stageWidth / 2;
+		const stageTop = stageHeight / 2;
+		const stageBottom = -stageHeight / 2;
+		x = this.clampPosition(x, stageLeft, stageRight - bubbleWidth);
+		y = this.clampPosition(y, stageBottom + bubbleHeight, stageTop);
+		renderer.updateDrawablePosition(bubbleState.drawableId, [x, y]);
+	}
+	updateTextSkin(bubbleState) {
+		if (typeof bubbleState.skinId !== "number") return;
+		this.runtime.renderer?.updateTextSkin?.(bubbleState.skinId, bubbleState.type, bubbleState.text, bubbleState.onSpriteRight, [0, 0]);
+	}
+	clampPosition(value, minimum, maximum) {
+		if (maximum < minimum) return minimum;
+		return Math.min(maximum, Math.max(minimum, value));
+	}
+	applyBubbleStyle(target, type, text, selection) {
+		const bubbleState = this.getBubbleState(target);
+		if (!bubbleState || typeof bubbleState.skinId !== "number") return;
+		const normalizedText = this.normalizeMessage(text);
+		if (bubbleState.text !== normalizedText) {
+			bubbleState.text = normalizedText;
+			this.runtime.renderer?.updateTextSkin?.(bubbleState.skinId, type, normalizedText, bubbleState.onSpriteRight, [0, 0]);
+		}
+		const skin = this.getTextBubbleSkin(bubbleState.skinId);
+		if (typeof skin?.setStyle === "function") {
+			this.installAlignmentRenderer(skin);
+			skin.setStyle(this.createRenderStyle(selection.definition));
+		}
+		this.installTargetPositionHook(target);
+		target.onTargetVisualChange?.(target);
+		this.runtime.requestRedraw?.();
+	}
+	handleSayOrThink(target, type, text) {
+		const selection = this.pendingStyles.get(target) ?? this.resolveStyle(defaultStyleName$1);
+		this.pendingStyles.delete(target);
+		const normalizedText = this.normalizeMessage(this.getBubbleState(target)?.text ?? text);
+		if (normalizedText === "") {
+			this.activeStyles.delete(target);
+			return;
+		}
+		this.activeStyles.set(target, selection);
+		this.applyBubbleStyle(target, type, normalizedText, selection);
+	}
+	handleStageSizeChanged() {
+		for (const target of this.runtime.targets ?? []) {
+			const bubbleState = this.getBubbleState(target);
+			if (!bubbleState?.text) continue;
+			const selection = this.activeStyles.get(target) ?? this.resolveStyle(defaultStyleName$1);
+			this.applyBubbleStyle(target, bubbleState.type, bubbleState.text, selection);
+		}
+		for (const [target, state] of [...this.textActors]) this.applyTextActor(target, state.text, this.resolveStyle(state.styleName));
+	}
+	restyleVisibleBubbles(styleName, definition) {
+		for (const target of this.runtime.targets ?? []) {
+			const selection = this.activeStyles.get(target);
+			const bubbleState = this.getBubbleState(target);
+			if (selection?.styleName !== styleName || !bubbleState?.text) continue;
+			const nextSelection = {
+				definition,
+				styleName
+			};
+			this.activeStyles.set(target, nextSelection);
+			this.applyBubbleStyle(target, bubbleState.type, bubbleState.text, nextSelection);
+		}
+	}
+	restyleTextActors(styleName) {
+		const definition = this.styles.get(styleName);
+		if (!definition) return;
+		for (const [target, state] of [...this.textActors]) {
+			if (state.styleName !== styleName) continue;
+			this.applyTextActor(target, state.text, {
+				definition,
+				styleName
+			});
+		}
+	}
+	showStyledBubble(type, args, util) {
+		this.showBubble(type, args.MESSAGE, this.resolveStyle(args.STYLE), util);
+	}
+	showLegacyBubble(type, args, util) {
+		const defaultDefinition = this.styles.get(defaultStyleName$1) ?? initialDefaultStyle;
+		this.showBubble(type, args.MESSAGE, {
+			definition: {
+				...defaultDefinition,
+				fontPercent: this.normalizeFontPercent(args.SIZE)
+			},
+			styleName: null
+		}, util);
+	}
+	showBubble(type, messageValue, selection, util) {
+		const message = this.normalizeMessage(messageValue);
+		this.pendingStyles.set(util.target, selection);
+		try {
+			this.runtime.emit("SAY", util.target, type, message);
+		} finally {
+			this.pendingStyles.delete(util.target);
+		}
+	}
+};
+//#endregion
+//#region src/composition.ts
+var defaultStyleName = "default";
+var directions = /* @__PURE__ */ new Set([
+	"up",
+	"up-up-right",
+	"up-right",
+	"right-up-right",
+	"right",
+	"right-down-right",
+	"down-right",
+	"down-down-right",
+	"down",
+	"down-down-left",
+	"down-left",
+	"left-down-left",
+	"left",
+	"left-up-left",
+	"up-left",
+	"up-up-left"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function compositionError(code, message) {
+	const error = new Error(message);
+	Object.defineProperty(error, "code", { value: code });
+	return error;
+}
+function requireExactKeys(value, required, optional, label) {
+	const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+	if (required.some((key) => !Object.prototype.hasOwnProperty.call(value, key)) || Object.keys(value).some((key) => !allowed.has(key))) throw compositionError("SVG-TEXT-COMPOSITION-001", `${label} has missing or unknown properties.`);
+}
+function requireName(value, label) {
+	if (typeof value !== "string" || value.trim().length === 0) throw compositionError("SVG-TEXT-COMPOSITION-001", `${label} must be a non-empty string.`);
+	return value.trim();
+}
+function validateRuntime(value) {
+	if (!isRecord(value) || !isRecord(value.renderer)) throw new TypeError("SVG Text composition runtime must provide a renderer.");
+	const renderer = value.renderer;
+	const methods = [
+		"createSVGSkin",
+		"destroySkin",
+		"updateDrawableSkinId"
+	];
+	if (methods.some((method) => typeof renderer[method] !== "function")) throw new TypeError(`SVG Text composition renderer must provide ${methods.join(", ")}.`);
+	if (value.requestRedraw !== void 0 && typeof value.requestRedraw !== "function") throw new TypeError("SVG Text composition requestRedraw must be a function.");
+	return value;
+}
+function validateTarget(value) {
+	if (!isRecord(value) || typeof value.drawableID !== "number" || !Number.isInteger(value.drawableID) || value.drawableID < 0) throw compositionError("SVG-TEXT-COMPOSITION-002", "SVG Text target must provide a non-negative integer drawableID.");
+	return value;
+}
+function validateOptionalString(value, label) {
+	if (value !== void 0 && (typeof value !== "string" || value.length === 0)) throw compositionError("SVG-TEXT-COMPOSITION-001", `${label} must be a non-empty string when provided.`);
+}
+function validateStyle(value) {
+	if (!isRecord(value)) throw compositionError("SVG-TEXT-COMPOSITION-001", "SVG Text style must be an object.");
+	requireExactKeys(value, ["name"], [
+		"alignment",
+		"backgroundColor",
+		"direction",
+		"font",
+		"fontPercent",
+		"textColor"
+	], "SVG Text style");
+	const name = requireName(value.name, "SVG Text style name");
+	if (value.alignment !== void 0 && value.alignment !== "left" && value.alignment !== "center" && value.alignment !== "right") throw compositionError("SVG-TEXT-COMPOSITION-001", "SVG Text alignment is invalid.");
+	validateOptionalString(value.backgroundColor, "SVG Text backgroundColor");
+	validateOptionalString(value.font, "SVG Text font");
+	validateOptionalString(value.textColor, "SVG Text textColor");
+	if (value.fontPercent !== void 0 && (typeof value.fontPercent !== "number" || !Number.isFinite(value.fontPercent) || value.fontPercent < 1 || value.fontPercent > 1e3)) throw compositionError("SVG-TEXT-COMPOSITION-001", "SVG Text fontPercent must be a finite number from 1 to 1000.");
+	if (value.direction !== void 0) {
+		if (!(typeof value.direction === "string" && directions.has(value.direction) || typeof value.direction === "number" && Number.isFinite(value.direction) && value.direction >= 0 && value.direction <= 360)) throw compositionError("SVG-TEXT-COMPOSITION-001", "SVG Text direction is invalid.");
+	}
+	return {
+		...value,
+		name
+	};
+}
+function createSvgTextComposition(options) {
+	if (!isRecord(options)) throw new TypeError("SVG Text composition options must be an object.");
+	const extension = new SvgTextExtension(validateRuntime(options.runtime), {
+		castToString: (value) => String(value),
+		listenForRuntimeEvents: false
+	});
+	const styles = /* @__PURE__ */ new Set([defaultStyleName]);
+	const targets = /* @__PURE__ */ new Set();
+	let disposed = false;
+	function ensureActive() {
+		if (disposed) throw compositionError("SVG-TEXT-COMPOSITION-004", "SVG Text composition has been released.");
+	}
+	return Object.freeze({
+		defineStyle(input) {
+			ensureActive();
+			const style = validateStyle(input);
+			extension.defineStyle({
+				ALIGN: style.alignment ?? "",
+				BACKGROUND: style.backgroundColor ?? "",
+				DIRECTION: style.direction ?? "",
+				FONT: style.font ?? "",
+				SIZE: style.fontPercent ?? "",
+				STYLE: style.name,
+				TEXT_COLOR: style.textColor ?? ""
+			});
+			styles.add(style.name);
+		},
+		setText(input) {
+			ensureActive();
+			if (!isRecord(input)) throw compositionError("SVG-TEXT-COMPOSITION-001", "SVG Text actor input is invalid.");
+			requireExactKeys(input, [
+				"styleName",
+				"target",
+				"text"
+			], [], "SVG Text actor input");
+			const target = validateTarget(input.target);
+			const styleName = requireName(input.styleName, "SVG Text styleName");
+			if (!styles.has(styleName)) throw compositionError("SVG-TEXT-COMPOSITION-003", `SVG Text style is not defined: ${styleName}`);
+			if (typeof input.text !== "string") throw compositionError("SVG-TEXT-COMPOSITION-001", "SVG Text text must be a string.");
+			extension.setText({
+				STYLE: styleName,
+				TEXT: input.text
+			}, { target });
+			targets.add(target);
+		},
+		releaseTarget(value) {
+			ensureActive();
+			const target = validateTarget(value);
+			if (!targets.delete(target)) throw compositionError("SVG-TEXT-COMPOSITION-005", "SVG Text target is not owned by this composition.");
+			if (!extension.releaseTextActor(target)) throw compositionError("SVG-TEXT-COMPOSITION-005", "SVG Text target ownership is inconsistent.");
+		},
+		releaseAll() {
+			if (disposed) return;
+			disposed = true;
+			const errors = [];
+			for (const target of targets) try {
+				extension.releaseTextActor(target);
+			} catch (error) {
+				errors.push(error);
+			}
+			targets.clear();
+			styles.clear();
+			if (errors.length > 0) {
+				const error = compositionError("SVG-TEXT-COMPOSITION-006", "SVG Text composition failed to release one or more skins.");
+				Object.defineProperty(error, "errors", { value: Object.freeze([...errors]) });
+				throw error;
+			}
+		}
+	});
+}
+//#endregion
+export { createSvgTextComposition };

package/dist/svg-text.js

@@ -24,7 +24,7 @@
   			"opcode": "defineStyle",
   			"blockType": "COMMAND",
   			"text": "define text style [STYLE] background [BACKGROUND] text [TEXT_COLOR] font [FONT] size [SIZE] align [ALIGN] bubble direction [DIRECTION]",
-  			"description": "Defines or replaces a named responsive text style. Bubble direction accepts names, compass aliases, or Scratch-style degrees from 0 to 360.",
+  			"description": "Defines or replaces a named responsive text style. Bubble direction is measured from the actor center to the bubble body center and accepts names, compass aliases, or Scratch-style degrees from 0 to 360.",
   			"arguments": {
   				"STYLE": {
   					"type": "STRING",
@@ -329,7 +329,7 @@
   	textColor: "#575e75"
   };
   var SvgTextExtension = class {
-  	constructor(runtime = Scratch.vm?.runtime) {
+  	constructor(runtime = Scratch.vm?.runtime, options = {}) {
   		this.styles = /* @__PURE__ */ new Map([[defaultStyleName, initialDefaultStyle]]);
   		this.activeStyles = /* @__PURE__ */ new WeakMap();
   		this.textActors = /* @__PURE__ */ new Map();
@@ -338,10 +338,13 @@
   		this.targetPositionHooks = /* @__PURE__ */ new WeakMap();
   		if (!runtime) throw new Error("SVG Text requires the TurboWarp VM.");
   		this.runtime = runtime;
+  		this.castToString = options.castToString ?? Scratch.Cast.toString;
   		this.handleSayOrThink = this.handleSayOrThink.bind(this);
   		this.handleStageSizeChanged = this.handleStageSizeChanged.bind(this);
-  		this.runtime.on("SAY", this.handleSayOrThink);
-  		this.runtime.on("STAGE_SIZE_CHANGED", this.handleStageSizeChanged);
+  		if (options.listenForRuntimeEvents ?? true) {
+  			this.runtime.on("SAY", this.handleSayOrThink);
+  			this.runtime.on("STAGE_SIZE_CHANGED", this.handleStageSizeChanged);
+  		}
   	}
   	getInfo() {
   		return {
@@ -371,6 +374,14 @@
   		const selection = this.resolveStyle(args.STYLE);
   		this.applyTextActor(util.target, this.normalizeMessage(args.TEXT), selection);
   	}
+  	releaseTextActor(target) {
+  		const state = this.textActors.get(target);
+  		if (!state) return false;
+  		this.textActors.delete(target);
+  		this.runtime.renderer?.destroySkin?.(state.skinId);
+  		this.runtime.requestRedraw?.();
+  		return true;
+  	}
   	sayWithStyle(args, util) {
   		this.showStyledBubble("say", args, util);
   	}
@@ -397,7 +408,7 @@
   		};
   	}
   	normalizeStyleName(value) {
-  		return Scratch.Cast.toString(value).trim() || defaultStyleName;
+  		return this.castToString(value).trim() || defaultStyleName;
   	}
   	normalizeFontPercent(value) {
   		if (typeof value === "string" && value.trim() === "") return defaultFontPercent;
@@ -406,15 +417,15 @@
   		return Math.min(maximumFontPercent, Math.max(minimumFontPercent, numericValue));
   	}
   	normalizeMessage(value) {
-  		return Scratch.Cast.toString(value).replace(/\\r\\n|\\n|\\r/gu, "\n");
+  		return this.castToString(value).replace(/\\r\\n|\\n|\\r/gu, "\n");
   	}
   	normalizeAlignment(value) {
-  		const alignment = Scratch.Cast.toString(value).trim().toLowerCase();
+  		const alignment = this.castToString(value).trim().toLowerCase();
   		if (alignment === "center" || alignment === "right") return alignment;
   		return "left";
   	}
   	normalizeDirection(value) {
-  		const direction = Scratch.Cast.toString(value).trim().toLowerCase();
+  		const direction = this.castToString(value).trim().toLowerCase();
   		if (bubbleDirections.includes(direction)) return direction;
   		const alias = bubbleDirectionAliases.get(direction);
   		if (alias) return alias;
@@ -425,14 +436,14 @@
   		return initialDefaultStyle.direction;
   	}
   	normalizeColor(value, fallback) {
-  		const color = Scratch.Cast.toString(value).trim();
+  		const color = this.castToString(value).trim();
   		if (color === "") return fallback;
   		if (/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/iu.test(color)) return color;
   		if (globalThis.CSS?.supports?.("color", color)) return color;
   		return fallback;
   	}
   	normalizeFont(value) {
-  		const font = Scratch.Cast.toString(value).trim();
+  		const font = this.castToString(value).trim();
   		const hasUnsafeCharacter = [...font].some((character) => {
   			const codePoint = character.codePointAt(0) ?? 0;
   			return codePoint <= 31 || codePoint === 127 || ",;{}".includes(character);
@@ -519,7 +530,7 @@
   		const renderer = this.runtime.renderer;
   		if (typeof target.drawableID !== "number" || typeof renderer?.createSVGSkin !== "function" || typeof renderer.updateDrawableSkinId !== "function") throw new Error("SVG Text requires SVG skin APIs from TurboWarp.");
   		const skinId = renderer.createSVGSkin(this.createTextActorSvg(text, selection.definition));
-  		if (typeof skinId !== "number") throw new Error("TurboWarp did not create an SVG text skin.");
+  		if (!Number.isInteger(skinId) || skinId < 0) throw new Error("TurboWarp did not create an SVG text skin.");
   		try {
   			renderer.updateDrawableSkinId(target.drawableID, skinId);
   		} catch (error) {
@@ -651,9 +662,9 @@
   		const vector = directionVector(direction);
   		const horizontalDistance = vector.x < 0 ? centeredBubbleX - leftBubbleX : rightBubbleX - centeredBubbleX;
   		const verticalDistance = vector.y < 0 ? centeredBubbleY - lowerBubbleY : upperBubbleY - centeredBubbleY;
-  		const numericDirectionScale = typeof direction === "number" ? Math.min(vector.x === 0 ? Number.POSITIVE_INFINITY : horizontalDistance / Math.abs(vector.x), vector.y === 0 ? Number.POSITIVE_INFINITY : verticalDistance / Math.abs(vector.y)) : null;
-  		let x = centeredBubbleX + vector.x * (numericDirectionScale ?? horizontalDistance);
-  		let y = centeredBubbleY + vector.y * (numericDirectionScale ?? verticalDistance);
+  		const placementScale = Math.min(vector.x === 0 ? Number.POSITIVE_INFINITY : horizontalDistance / Math.abs(vector.x), vector.y === 0 ? Number.POSITIVE_INFINITY : verticalDistance / Math.abs(vector.y));
+  		let x = centeredBubbleX + vector.x * placementScale;
+  		let y = centeredBubbleY + vector.y * placementScale;
   		if (vector.x > 0 && !bubbleState.onSpriteRight) {
   			bubbleState.onSpriteRight = true;
   			this.updateTextSkin(bubbleState);

package/dist/types/composition.d.ts

@@ -0,0 +1,39 @@
+export type SvgTextAlignment = "center" | "left" | "right";
+export type SvgTextDirection = "up" | "up-up-right" | "up-right" | "right-up-right" | "right" | "right-down-right" | "down-right" | "down-down-right" | "down" | "down-down-left" | "down-left" | "left-down-left" | "left" | "left-up-left" | "up-left" | "up-up-left" | number;
+export interface SvgTextStyleInput {
+    name: string;
+    alignment?: SvgTextAlignment;
+    backgroundColor?: string;
+    direction?: SvgTextDirection;
+    font?: string;
+    fontPercent?: number;
+    textColor?: string;
+}
+export interface SvgTextTarget {
+    drawableID: number;
+}
+export interface SvgTextActorInput {
+    styleName: string;
+    target: SvgTextTarget;
+    text: string;
+}
+export interface SvgTextCompositionRenderer {
+    createSVGSkin(svg: string): number;
+    destroySkin(skinId: number): void;
+    getNativeSize?(): unknown;
+    updateDrawableSkinId(drawableId: number, skinId: number): void;
+}
+export interface SvgTextCompositionRuntime {
+    renderer: SvgTextCompositionRenderer;
+    requestRedraw?(): void;
+}
+export interface SvgTextComposition {
+    defineStyle(input: SvgTextStyleInput): void;
+    releaseAll(): void;
+    releaseTarget(target: SvgTextTarget): void;
+    setText(input: SvgTextActorInput): void;
+}
+export interface SvgTextCompositionOptions {
+    runtime: SvgTextCompositionRuntime;
+}
+export declare function createSvgTextComposition(options: SvgTextCompositionOptions): SvgTextComposition;

package/dist/types/config.d.ts

@@ -0,0 +1,9 @@
+export declare const extensionConfig: {
+    readonly id: "kubohiroyasvgtext";
+    readonly slug: "svg-text";
+    readonly name: "SVG Text";
+    readonly description: "Responsive named-style bubbles and SVG text actors for TurboWarp.";
+    readonly author: "Hiroya Kubo";
+    readonly license: "MPL-2.0";
+    readonly unsandboxed: true;
+};

package/dist/types/extension.d.ts

@@ -0,0 +1,80 @@
+interface LegacyBubbleArguments {
+    MESSAGE: unknown;
+    SIZE: unknown;
+}
+interface StyledBubbleArguments {
+    MESSAGE: unknown;
+    STYLE: unknown;
+}
+interface TextActorArguments {
+    STYLE: unknown;
+    TEXT: unknown;
+}
+interface DefineStyleArguments {
+    ALIGN: unknown;
+    BACKGROUND: unknown;
+    DIRECTION: unknown;
+    FONT: unknown;
+    SIZE: unknown;
+    STYLE: unknown;
+    TEXT_COLOR: unknown;
+}
+interface BlockUtility {
+    target: TurboWarpTarget;
+}
+interface SvgTextExtensionOptions {
+    castToString?: (value: unknown) => string;
+    listenForRuntimeEvents?: boolean;
+}
+export declare const EXTENSION_DOCS_URI = "https://kubohiroya.github.io/turbowarp-svg-text/";
+export declare class SvgTextExtension implements TurboWarpExtension {
+    private readonly runtime;
+    private readonly castToString;
+    private readonly styles;
+    private readonly activeStyles;
+    private readonly textActors;
+    private readonly pendingStyles;
+    private readonly alignedSkins;
+    private readonly targetPositionHooks;
+    constructor(runtime?: any, options?: SvgTextExtensionOptions);
+    getInfo(): Record<string, unknown>;
+    defineStyle(args: DefineStyleArguments): void;
+    setText(args: TextActorArguments, util: BlockUtility): void;
+    releaseTextActor(target: TurboWarpTarget): boolean;
+    sayWithStyle(args: StyledBubbleArguments, util: BlockUtility): void;
+    thinkWithStyle(args: StyledBubbleArguments, util: BlockUtility): void;
+    say(args: LegacyBubbleArguments, util: BlockUtility): void;
+    think(args: LegacyBubbleArguments, util: BlockUtility): void;
+    private toScratchBlock;
+    private normalizeStyleName;
+    private normalizeFontPercent;
+    private normalizeMessage;
+    private normalizeAlignment;
+    private normalizeDirection;
+    private normalizeColor;
+    private normalizeFont;
+    private getStageScale;
+    private createRenderStyle;
+    private createTextActorSvg;
+    private measureTextWidth;
+    private escapeXml;
+    private formatSvgNumber;
+    private applyTextActor;
+    private resolveStyle;
+    private getBubbleState;
+    private getTextBubbleSkin;
+    private installAlignmentRenderer;
+    private installTargetPositionHook;
+    private positionBubble;
+    private updateTextSkin;
+    private clampPosition;
+    private applyBubbleStyle;
+    private handleSayOrThink;
+    private handleStageSizeChanged;
+    private restyleVisibleBubbles;
+    private restyleTextActors;
+    private showStyledBubble;
+    private showLegacyBubble;
+    private showBubble;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-svg-text",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Responsive named-style bubbles and SVG text actors for TurboWarp.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "type": "module",
@@ -13,6 +13,15 @@
   "bugs": {
     "url": "https://github.com/kubohiroya/turbowarp-svg-text/issues"
   },
+  "exports": {
+    ".": "./dist/svg-text.js",
+    "./composition": {
+      "types": "./dist/types/composition.d.ts",
+      "import": "./dist/composition.js"
+    },
+    "./dist/svg-text.js": "./dist/svg-text.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist/",
     "README.md",
@@ -25,6 +34,27 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "packageManager": "pnpm@11.18.0",
+  "scripts": {
+    "dev": "vite build --watch",
+    "typecheck": "tsc --noEmit",
+    "build": "pnpm build:extension && pnpm build:composition && pnpm build:types",
+    "build:extension": "vite build",
+    "build:composition": "vite build --config vite.composition.config.ts",
+    "build:types": "tsc --project tsconfig.build.json",
+    "composition:dist:check": "node scripts/check-composition-dist.mjs",
+    "types:composition:check": "tsc --project tsconfig.composition-consumer.json",
+    "lint": "eslint src tests scripts vite.config.ts eslint.config.mjs",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "test": "vitest run",
+    "docs:site:check": "node scripts/check-site.mjs",
+    "check:dist": "pnpm build && node scripts/check-dist.mjs",
+    "pack:check": "npm pack --dry-run --ignore-scripts",
+    "release:check": "pnpm publish --dry-run --access public",
+    "check": "pnpm typecheck && pnpm lint && pnpm format && pnpm test && pnpm docs:site:check && pnpm check:dist && pnpm composition:dist:check && pnpm types:composition:check && pnpm pack:check",
+    "prepack": "pnpm check"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@kubohiroya/vite-plugin-turbowarp-extension": "0.1.1",
@@ -45,19 +75,5 @@
     "text-actor",
     "named-styles",
     "multiline"
-  ],
-  "scripts": {
-    "dev": "vite build --watch",
-    "typecheck": "tsc --noEmit",
-    "build": "vite build",
-    "lint": "eslint src tests scripts vite.config.ts eslint.config.mjs",
-    "format": "prettier --check .",
-    "format:write": "prettier --write .",
-    "test": "vitest run",
-    "docs:site:check": "node scripts/check-site.mjs",
-    "check:dist": "pnpm build && node scripts/check-dist.mjs",
-    "pack:check": "npm pack --dry-run --ignore-scripts",
-    "release:check": "pnpm publish --dry-run --access public",
-    "check": "pnpm typecheck && pnpm lint && pnpm format && pnpm test && pnpm docs:site:check && pnpm check:dist && pnpm pack:check"
-  }
-}
+  ]
+}