@replayablejs/pixi 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,1106 @@
+import { t as applyContainerOptions } from "./apply-container-options-CloU_2Pk.js";
+import { playable } from "@replayablejs/runtime";
+import { AnimatedSprite, Assets, Container, Graphics, NineSliceSprite, Rectangle, SplitText, Sprite, Spritesheet, Text, Texture, Ticker, WebGLRenderer } from "pixi.js";
+import { getCanvasHost } from "@replayablejs/canvas";
+//#region src/integrations/register-pixi-devtools.ts
+/** Exposes a successfully initialized stage and renderer to Pixi DevTools in development. */
+function registerPixiDevtools(stage, renderer) {
+	if (!import.meta.env.DEV) return noop;
+	globalThis.__PIXI_STAGE__ = stage;
+	globalThis.__PIXI_RENDERER__ = renderer;
+	return unregister;
+	/** Releases only our references; an older instance must not clear a newer registration. */
+	function unregister() {
+		if (globalThis.__PIXI_STAGE__ === stage) Reflect.deleteProperty(globalThis, "__PIXI_STAGE__");
+		if (globalThis.__PIXI_RENDERER__ === renderer) Reflect.deleteProperty(globalThis, "__PIXI_RENDERER__");
+	}
+}
+/** Keeps lifecycle cleanup unconditional when production strips the DevTools branch. */
+function noop() {}
+//#endregion
+//#region src/lifecycle/cleanup-pixi-resources.ts
+/** Releases acquired resources in reverse order, even when individual cleanup fails. */
+function cleanupPixiResources(cleanups) {
+	const errors = collectCleanupErrors(cleanups);
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Pixi resource cleanup failed.");
+}
+/** Preserves the original setup failure alongside any rollback failures. */
+function failPixiSetup(cause, cleanups) {
+	const errors = collectCleanupErrors(cleanups);
+	if (errors.length === 0) throw cause;
+	throw new AggregateError([cause, ...errors], "Pixi setup and cleanup failed.", { cause });
+}
+/** Pops before calling so repeated cleanup never retries already released resources. */
+function collectCleanupErrors(cleanups) {
+	const errors = [];
+	let dispose = cleanups.pop();
+	while (dispose !== void 0) {
+		try {
+			dispose();
+		} catch (error) {
+			errors.push(error);
+		}
+		dispose = cleanups.pop();
+	}
+	return errors;
+}
+//#endregion
+//#region src/integrations/setup-pixi-integrations.ts
+/** Installs integrations in declaration order and cleans them up in reverse order. */
+function setupPixiIntegrations(integrations = []) {
+	const cleanups = [];
+	try {
+		for (const integration of integrations) cleanups.push(integration.setup());
+	} catch (error) {
+		failPixiSetup(error, cleanups);
+	}
+	return () => cleanupPixiResources(cleanups);
+}
+//#endregion
+//#region src/loader/configure-pixi-assets.ts
+/** Applies deterministic browser-loading behavior for playable assets. */
+function configurePixiAssets() {
+	Assets.setPreferences({
+		preferWorkers: false,
+		preferCreateImageBitmap: false
+	});
+}
+//#endregion
+//#region src/loader/load-pixi-atlas.ts
+/** Loads one generated Replayable atlas and registers its parsed Pixi spritesheet. */
+async function loadPixiAtlas(context) {
+	const { id, source } = context;
+	const [texture, data] = await Promise.all([Assets.load(source.image), loadSpritesheetData(id, source.json)]);
+	const spritesheet = new Spritesheet({
+		data,
+		texture
+	});
+	await spritesheet.parse();
+	Assets.cache.set(id, spritesheet);
+	return spritesheet;
+}
+/** Resolves either generated inline JSON or an emitted atlas JSON resource. */
+async function loadSpritesheetData(id, source) {
+	const data = typeof source === "string" ? await fetchSpritesheetData(id, source) : source;
+	if (!isSpritesheetData(data)) throw new Error(`Replayable atlas "${id}" contains invalid spritesheet data.`);
+	return data;
+}
+/** Fetches JSON only when the active asset mode emitted it as a resource URL. */
+async function fetchSpritesheetData(id, url) {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to load Replayable atlas "${id}" from ${url}.`);
+	return response.json();
+}
+/** Checks the required top-level shape before passing generated JSON to Pixi. */
+function isSpritesheetData(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return "frames" in value && "meta" in value;
+}
+//#endregion
+//#region src/loader/load-pixi-sprite.ts
+/** Loads one generated Replayable sprite into Pixi's texture cache. */
+async function loadPixiSprite(context) {
+	const { id, source } = context;
+	const texture = await Assets.load({
+		alias: id,
+		src: source.src
+	});
+	texture.source.resolution = source.scale;
+	texture.update();
+	return texture;
+}
+//#endregion
+//#region src/renderer/destroy-pixi-renderer.ts
+/**
+* Releases Pixi resources without forcibly losing a borrowed WebGL context.
+*
+* Pixi 8.20's GlContextSystem.destroy() calls its cached loseContext extension;
+* removeView:false only preserves the canvas element. There is no preserve-context
+* destroy option. Temporarily remove that entry from this renderer's own cache,
+* not from the shared WebGL context or the extension object another renderer uses.
+* Recheck this compatibility boundary when upgrading Pixi.
+*/
+function destroyPixiRenderer(renderer, ownsContext) {
+	const extensions = renderer.context?.extensions;
+	const loseContext = extensions?.loseContext;
+	if (!ownsContext && extensions !== void 0) delete extensions.loseContext;
+	try {
+		renderer.destroy({ removeView: false });
+	} finally {
+		if (!ownsContext && extensions !== void 0 && loseContext !== void 0) extensions.loseContext = loseContext;
+	}
+}
+//#endregion
+//#region src/renderer/create-pixi-renderer.ts
+/** Creates Pixi's renderer on Replayable's canvas and shared WebGL context. */
+async function createPixiRenderer(options) {
+	const canvasHost = getCanvasHost();
+	const sharedContext = resolveSharedContext(canvasHost.getSharedContext());
+	const ownsContext = sharedContext === null;
+	const cleanups = [];
+	if (ownsContext) cleanups.push(() => canvasHost.destroy());
+	try {
+		const renderer = new WebGLRenderer();
+		cleanups.push(() => destroyPixiRenderer(renderer, ownsContext));
+		await renderer.init({
+			antialias: options.antialias ?? false,
+			autoDensity: false,
+			backgroundAlpha: ownsContext ? 1 : 0,
+			backgroundColor: playable.config.backgroundColor,
+			canvas: canvasHost.getCanvas(),
+			clearBeforeRender: ownsContext,
+			context: sharedContext,
+			hello: false,
+			powerPreference: options.powerPreference ?? "high-performance",
+			preferWebGLVersion: 2,
+			useBackBuffer: options.useBackBuffer ?? false
+		});
+		if (ownsContext) canvasHost.setSharedContext(renderer.gl);
+		return {
+			renderer,
+			destroy: () => cleanupPixiResources(cleanups)
+		};
+	} catch (error) {
+		return failPixiSetup(error, cleanups);
+	}
+}
+/** Pixi 8 accepts only WebGL 2 when reusing an externally created context. */
+function resolveSharedContext(context) {
+	if (context === null || typeof WebGL2RenderingContext !== "undefined" && context instanceof WebGL2RenderingContext) return context;
+	throw new Error("Pixi requires the shared Replayable canvas context to use WebGL 2.");
+}
+//#endregion
+//#region src/renderer/start-pixi-rendering.ts
+const MILLISECONDS_PER_SECOND = 1e3;
+/** Connects Pixi's ticker and rendering to Replayable's lifecycle-aware frame loop. */
+function startPixiRendering(renderer, stage) {
+	const ticker = Ticker.shared;
+	let elapsedMilliseconds = 0;
+	ticker.autoStart = false;
+	ticker.stop();
+	ticker.lastTime = 0;
+	return playable.update.add(renderFrame);
+	/** Advances Pixi systems and renders the stage once for this Replayable frame. */
+	function renderFrame({ deltaSeconds }) {
+		elapsedMilliseconds += deltaSeconds * MILLISECONDS_PER_SECOND;
+		renderer.resetState();
+		ticker.update(elapsedMilliseconds);
+		renderer.render(stage);
+	}
+}
+//#endregion
+//#region src/renderer/synchronize-pixi-screen.ts
+/** Keeps Pixi's drawing buffer aligned with Replayable's screen. */
+function synchronizePixiScreen(renderer) {
+	const unsubscribe = playable.on("resize", applyScreen);
+	try {
+		if (playable.screen.frame !== void 0) applyScreen();
+	} catch (error) {
+		unsubscribe();
+		throw error;
+	}
+	return unsubscribe;
+	function applyScreen() {
+		const { frame, resolution } = playable.screen;
+		renderer.resolution = resolution;
+		renderer.resize(frame.width, frame.height);
+	}
+}
+//#endregion
+//#region src/create-pixi.ts
+/** Initializes Pixi around Replayable's assets, lifecycle, and shared canvas. */
+async function createPixi(options = {}) {
+	configurePixiAssets();
+	const cleanups = [];
+	try {
+		cleanups.push(playable.loader.register("atlases", loadPixiAtlas));
+		cleanups.push(playable.loader.register("sprites", loadPixiSprite));
+		cleanups.push(setupPixiIntegrations(options.integrations));
+		const { renderer, destroy } = await createPixiRenderer(options);
+		cleanups.push(destroy);
+		const stage = new Container();
+		cleanups.push(() => stage.destroy({ children: true }));
+		const stopScreenSynchronization = synchronizePixiScreen(renderer);
+		cleanups.push(stopScreenSynchronization);
+		const stopRendering = startPixiRendering(renderer, stage);
+		cleanups.push(stopRendering);
+		const unregisterDevtools = registerPixiDevtools(stage, renderer);
+		cleanups.push(unregisterDevtools);
+		return {
+			renderer,
+			stage,
+			destroy() {
+				cleanupPixiResources(cleanups);
+			}
+		};
+	} catch (error) {
+		return failPixiSetup(error, cleanups);
+	}
+}
+//#endregion
+//#region src/factories/create-button.ts
+/**
+* Wraps artwork in a stable hit target without choosing its visuals or action.
+* Children are non-interactive: the button owns completed taps for the whole artwork.
+* Bounds are captured once, including the content's initial transform. Later artwork
+* animations do not shrink the hit target or change the bounds consumed by layout.
+*
+* @example
+* const button = createButton({ content: artwork, onActivate: handleAction });
+* stage.addChild(button.container);
+* button.setEnabled(false);
+* // Disposing the button also destroys artwork, but not its shared textures.
+* button.destroy();
+*/
+function createButton(options) {
+	const container = new Container({ label: "button" });
+	const { content, onActivate } = options;
+	content.eventMode = "none";
+	container.addChild(content);
+	const bounds = container.getLocalBounds();
+	const buttonBounds = new Rectangle(bounds.x, bounds.y, bounds.width, bounds.height);
+	container.boundsArea = buttonBounds;
+	container.hitArea = buttonBounds;
+	let enabled = options.enabled ?? true;
+	setEnabled(enabled);
+	container.on("pointertap", handleTap);
+	return {
+		container,
+		setEnabled,
+		destroy
+	};
+	/** Keep the action in the trusted input call stack; never await or defer it. */
+	function handleTap(event) {
+		event.stopPropagation();
+		if (enabled) onActivate();
+	}
+	/** Change input policy only; the consumer owns visibility and disabled styling. */
+	function setEnabled(value) {
+		if (container.destroyed) return;
+		enabled = value;
+		container.eventMode = enabled ? "static" : "none";
+		container.cursor = enabled ? "pointer" : "default";
+	}
+	/** Retire input before destroying owned display objects, never shared textures. */
+	function destroy() {
+		if (container.destroyed) return;
+		setEnabled(false);
+		container.off("pointertap", handleTap);
+		container.destroy({ children: true });
+	}
+}
+//#endregion
+//#region src/factories/apply-display-object-options.ts
+const CENTER_ANCHOR = {
+	x: .5,
+	y: .5
+};
+/** Applies the defaults shared by every Replayable Pixi factory. */
+function applyDisplayObjectOptions(displayObject, options) {
+	applyContainerOptions(displayObject, options);
+	displayObject.anchor.copyFrom(options.anchor ?? CENTER_ANCHOR);
+}
+//#endregion
+//#region src/factories/create-animated-sprite.ts
+/** Creates an unattached animated sprite driven by Pixi's Replayable-managed ticker. */
+function createAnimatedSprite(options) {
+	const { animationSpeed = 1, autoPlay = false, frames, loop = false } = options;
+	if (frames.length === 0) throw new Error("Cannot create an animated sprite without texture frames.");
+	const textures = frames.map((frame) => typeof frame === "string" ? Texture.from(frame) : frame);
+	const sprite = new AnimatedSprite(textures);
+	applyDisplayObjectOptions(sprite, options);
+	sprite.animationSpeed = animationSpeed;
+	sprite.loop = loop;
+	if (autoPlay) sprite.play();
+	return sprite;
+}
+//#endregion
+//#region src/factories/create-nine-slice-sprite.ts
+/** Creates an unattached nine-slice sprite with explicitly named borders. */
+function createNineSliceSprite(options) {
+	const { bottomHeight, height, leftWidth, rightWidth, texture, topHeight, width } = options;
+	const sprite = new NineSliceSprite({
+		bottomHeight,
+		height,
+		leftWidth,
+		rightWidth,
+		texture: typeof texture === "string" ? Texture.from(texture) : texture,
+		topHeight,
+		width
+	});
+	applyDisplayObjectOptions(sprite, options);
+	return sprite;
+}
+//#endregion
+//#region src/factories/create-sprite.ts
+/** Creates an unattached Pixi sprite with Replayable's conventional defaults. */
+function createSprite(options = {}) {
+	const sprite = Sprite.from(options.texture ?? Texture.EMPTY);
+	applyDisplayObjectOptions(sprite, options);
+	if (options.tint !== void 0) sprite.tint = options.tint;
+	if (options.eventMode !== void 0) sprite.eventMode = options.eventMode;
+	return sprite;
+}
+//#endregion
+//#region src/factories/create-split-text.ts
+/**
+* Creates unattached split text with Pixi's native splitting options.
+* Unlike Text, SplitText is a container, so it has no shared anchor default.
+* With autoSplit: false, call split() explicitly before accessing the characters.
+* Fitting, localization, and character animation remain application concerns.
+*/
+function createSplitText(options) {
+	const textObject = new SplitText(options);
+	applyContainerOptions(textObject, options);
+	return textObject;
+}
+//#endregion
+//#region src/factories/create-text.ts
+/** Creates unattached Pixi canvas text while leaving content and layout to the application. */
+function createText(options) {
+	const textObject = new Text({
+		style: options.style,
+		text: options.text
+	});
+	applyDisplayObjectOptions(textObject, options);
+	return textObject;
+}
+//#endregion
+//#region src/layout/debug/resolve-content-bounds.ts
+/**
+* Measures the axis-aligned box produced by Replayable's applied placement.
+* Rotation and skew remain excluded because core layout deliberately fits the
+* attached object's untransformed local bounds.
+*
+* The object has already been laid out when this function runs. Adding its
+* position to both pivot-adjusted, scaled edges therefore reconstructs the
+* exact box used by core placement without adding debug output to core logic.
+* Measuring both edges preserves flipped objects whose scale is negative.
+*/
+function resolveContentBounds(content) {
+	const bounds = content.getLocalBounds();
+	const firstX = content.x + (bounds.x - content.pivot.x) * content.scale.x;
+	const secondX = content.x + (bounds.x + bounds.width - content.pivot.x) * content.scale.x;
+	const firstY = content.y + (bounds.y - content.pivot.y) * content.scale.y;
+	const secondY = content.y + (bounds.y + bounds.height - content.pivot.y) * content.scale.y;
+	return {
+		x: Math.min(firstX, secondX),
+		y: Math.min(firstY, secondY),
+		width: Math.abs(secondX - firstX),
+		height: Math.abs(secondY - firstY)
+	};
+}
+//#endregion
+//#region src/layout/debug/resolve-layout-debug-options.ts
+const allLabels = {
+	areas: true,
+	content: true,
+	layout: true
+};
+/** Canonical defaults shared by boolean shorthand and selective option objects. */
+const allDiagnostics = {
+	areaBounds: true,
+	contentBounds: true,
+	labels: allLabels,
+	layoutBounds: true
+};
+/**
+* Resolves the public debug shorthand into the complete internal configuration.
+*
+* `true` enables every diagnostic. An options object starts from the same set
+* and can selectively disable individual diagnostics. `false` and omission
+* both disable the overlay.
+*/
+function resolveLayoutDebugOptions(debug) {
+	if (debug === void 0 || debug === false) return;
+	if (debug === true) return allDiagnostics;
+	return {
+		...allDiagnostics,
+		...debug,
+		labels: resolveLabels(debug.labels)
+	};
+}
+/** Resolves the label shorthand independently from the other debug switches. */
+function resolveLabels(labels) {
+	if (labels === false) return {
+		areas: false,
+		content: false,
+		layout: false
+	};
+	if (labels === void 0 || labels === true) return allLabels;
+	return {
+		...allLabels,
+		...labels
+	};
+}
+//#endregion
+//#region src/layout/debug/create-debug-layout.ts
+/**
+* Wraps a layout with the development boundary used by diagnostics.
+*
+* Delegation remains intentionally transparent: successful operations keep
+* their normal behavior and failures escape unchanged. Diagnostic state
+* therefore changes only after a delegated mutation has completed.
+*/
+function createDebugLayout(layout, initialConfig, renderer) {
+	const attachments = /* @__PURE__ */ new Map();
+	let config = initialConfig;
+	let destroyed = false;
+	renderInspection();
+	return {
+		container: layout.container,
+		/** Delegates reads directly; the decorator never owns resolved area state. */
+		getArea(name) {
+			return layout.getArea(name);
+		},
+		/**
+		* Delegates attachment first, then mirrors ownership for diagnostics.
+		*
+		* This order is essential: if core validation or measurement throws, the
+		* debugger records nothing and emits no misleading redraw. The additional
+		* destruction listener updates the overlay when application code destroys
+		* attached content without calling `detach()`.
+		*/
+		attach(areaName, content) {
+			layout.attach(areaName, content);
+			/** Mirrors core cleanup and immediately removes the stale diagnostic box. */
+			const handleDestroyed = () => {
+				attachments.delete(content);
+				renderInspection();
+			};
+			content.once("destroyed", handleDestroyed);
+			attachments.set(content, {
+				areaName,
+				handleDestroyed
+			});
+			renderInspection();
+		},
+		/** Mirrors a new area name only after the core move has succeeded. */
+		move(content, areaName) {
+			layout.move(content, areaName);
+			const attachment = requireAttachment(content);
+			attachments.set(content, {
+				...attachment,
+				areaName
+			});
+			renderInspection();
+		},
+		/**
+		* Stops diagnostic tracking after core ownership is successfully released.
+		* The exact registered callback is removed to avoid retaining the decorator.
+		*/
+		detach(content) {
+			layout.detach(content);
+			const attachment = requireAttachment(content);
+			content.off("destroyed", attachment.handleDestroyed);
+			attachments.delete(content);
+			renderInspection();
+		},
+		/**
+		* Adopts new debug configuration only after the atomic core update succeeds.
+		* This keeps the drawn inspection synchronized with actual live transforms.
+		*/
+		update(nextConfig) {
+			layout.update(nextConfig);
+			config = nextConfig;
+			renderInspection();
+		},
+		/**
+		* Idempotently releases decorator listeners and renderer resources before
+		* delegating destruction to the core layout and its owned container.
+		*/
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			for (const [content, attachment] of attachments) content.off("destroyed", attachment.handleDestroyed);
+			attachments.clear();
+			renderer.destroy();
+			layout.destroy();
+		}
+	};
+	/**
+	* Resolves public debug shorthand and sends one complete renderer snapshot.
+	* `undefined` is an explicit request to remove the overlay. Content geometry
+	* is not measured when its corresponding diagnostic is disabled.
+	*/
+	function renderInspection() {
+		const options = resolveLayoutDebugOptions(config.debug);
+		if (options === void 0) {
+			renderer.render(void 0);
+			return;
+		}
+		renderer.render({
+			areas: Object.keys(config.areas).map((name) => inspectArea(name, options.contentBounds || options.labels.content)),
+			bounds: config.bounds,
+			options
+		});
+	}
+	/**
+	* Combines authoritative core area geometry with decorator-owned occupancy.
+	*
+	* Attached content is filtered in map insertion order, so multiple diagnostic
+	* boxes follow deterministic attachment order without exposing the map itself.
+	*/
+	function inspectArea(name, includeContentBounds) {
+		const area = layout.getArea(name);
+		if (area === void 0) throw new Error(`Debug layout could not inspect area "${name}".`);
+		const areaAttachments = [...attachments].filter(([, attachment]) => attachment.areaName === name);
+		return {
+			...area,
+			contentBounds: includeContentBounds ? areaAttachments.map(([content]) => resolveContentBounds(content)) : [],
+			occupied: areaAttachments.length > 0
+		};
+	}
+	/** Guards the invariant that every successful core attachment was mirrored. */
+	function requireAttachment(content) {
+		const attachment = attachments.get(content);
+		if (attachment === void 0) throw new Error("Debug layout lost track of attached content.");
+		return attachment;
+	}
+}
+//#endregion
+//#region src/layout/debug/create-layout-debug-renderer.ts
+const AREA_EMPTY_COLOR = "#f2b84b";
+const AREA_OCCUPIED_COLOR = "#54d17a";
+const CONTENT_BOUNDS_COLOR = "#ef5cdb";
+const LAYOUT_BOUNDS_COLOR = "#45d9ef";
+const LINE_WIDTH = 2;
+/**
+* Creates the visual half of layout diagnostics.
+*
+* This renderer knows nothing about layout mutations or attached content. It
+* simply redraws the latest read-only inspection supplied by the decorator.
+* The overlay is a single non-interactive, non-measurable child of the layout
+* container, so diagnostics share its coordinate space without affecting
+* pointer handling or bounds used by a parent layout.
+*/
+function createLayoutDebugRenderer(container) {
+	const overlay = new Container();
+	const outlines = new Graphics();
+	const labels = [];
+	overlay.eventMode = "none";
+	overlay.label = "Replayable layout debugger";
+	overlay.measurable = false;
+	overlay.addChild(outlines);
+	return {
+		destroy,
+		render
+	};
+	/**
+	* Replaces the complete overlay with one current inspection.
+	*
+	* Layout mutations are infrequent, so rebuilding labels is simpler and safer
+	* than reconciling display objects. Passing `undefined` removes the overlay
+	* entirely, leaving disabled diagnostics with no hidden scene-graph child.
+	*/
+	function render(inspection) {
+		clearOverlay();
+		if (inspection === void 0) {
+			if (overlay.parent === container) container.removeChild(overlay);
+			return;
+		}
+		const { areas, bounds, options } = inspection;
+		if (options.layoutBounds) drawBounds(bounds, LAYOUT_BOUNDS_COLOR);
+		if (options.labels.layout) drawLabel(bounds, LAYOUT_BOUNDS_COLOR);
+		for (const area of areas) {
+			if (options.areaBounds) drawBounds(area.bounds, area.occupied ? AREA_OCCUPIED_COLOR : AREA_EMPTY_COLOR);
+			if (options.contentBounds) for (const contentBounds of area.contentBounds) drawBounds(contentBounds, CONTENT_BOUNDS_COLOR);
+			if (options.labels.areas) drawLabel(area.bounds, area.occupied ? AREA_OCCUPIED_COLOR : AREA_EMPTY_COLOR);
+			if (options.labels.content) for (const contentBounds of area.contentBounds) drawLabel(contentBounds, CONTENT_BOUNDS_COLOR, "bottom-right");
+		}
+		container.addChild(overlay);
+	}
+	/**
+	* Releases text, geometry, and container resources owned by this renderer.
+	* The decorator guarantees this is called once before core layout destruction.
+	*/
+	function destroy() {
+		clearOverlay();
+		overlay.removeFromParent();
+		overlay.destroy({ children: true });
+	}
+	/** Clears retained vector commands and destroys labels from the previous redraw. */
+	function clearOverlay() {
+		outlines.clear();
+		for (const label of labels) label.destroy();
+		labels.length = 0;
+	}
+	/**
+	* Appends one pixel-aligned rectangle to the shared Graphics command list.
+	* `pixelLine` keeps diagnostic edges crisp across renderer resolutions.
+	*/
+	function drawBounds(bounds, color) {
+		outlines.rect(bounds.x, bounds.y, bounds.width, bounds.height).stroke({
+			color,
+			pixelLine: true,
+			width: LINE_WIDTH
+		});
+	}
+	/**
+	* Creates a compact label inside a diagnostic rectangle.
+	* The label reuses its rectangle's diagnostic color, while a dark stroke
+	* preserves readability over arbitrary playable artwork.
+	*/
+	function drawLabel(bounds, color, placement = "top-left") {
+		const { height, width, x, y } = bounds;
+		const label = new Text({
+			text: `${formatDimension(width)} × ${formatDimension(height)}`,
+			style: {
+				fill: color,
+				fontFamily: "monospace",
+				fontSize: 8,
+				stroke: {
+					color: "#000000",
+					width: 2
+				}
+			}
+		});
+		label.eventMode = "none";
+		if (placement === "bottom-right") {
+			label.anchor.set(1, 1);
+			label.position.set(x + width - 4, y + height - 3);
+		} else label.position.set(x + 4, y + 3);
+		labels.push(label);
+		overlay.addChild(label);
+	}
+}
+/** Keeps integer dimensions compact while making fractional pixels explicit. */
+function formatDimension(value) {
+	return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+//#endregion
+//#region src/layout/layout-content.ts
+/**
+* Resolves one content placement without mutating its live Pixi transform.
+*
+* Pixi local bounds may begin away from `(0, 0)`, and pivot moves the object's
+* transform origin independently from those bounds. This calculation first
+* determines the final scale, transforms both local edges around the pivot,
+* and finally derives the position that puts the resulting visual box at the
+* area's requested alignment and pixel offset.
+*
+* Rotation and skew are intentionally excluded. Applications that need those
+* transforms to participate in fitting should attach an untransformed parent
+* container and rotate or skew its child.
+*/
+function resolveContentLayout(content, area) {
+	const contentBounds = content.getLocalBounds();
+	const { scaleX, scaleY } = resolveScale(area.scale, area.bounds, contentBounds, content.scale.x, content.scale.y);
+	const firstX = (contentBounds.x - content.pivot.x) * scaleX;
+	const secondX = (contentBounds.x + contentBounds.width - content.pivot.x) * scaleX;
+	const firstY = (contentBounds.y - content.pivot.y) * scaleY;
+	const secondY = (contentBounds.y + contentBounds.height - content.pivot.y) * scaleY;
+	const minimumX = Math.min(firstX, secondX);
+	const minimumY = Math.min(firstY, secondY);
+	const contentWidth = Math.abs(secondX - firstX);
+	const contentHeight = Math.abs(secondY - firstY);
+	return {
+		x: resolveAlignedX(area.align, area.bounds, contentWidth) - minimumX + area.offset.x,
+		y: resolveAlignedY(area.align, area.bounds, contentHeight) - minimumY + area.offset.y,
+		scaleX,
+		scaleY
+	};
+}
+/**
+* Commits a previously resolved placement to Pixi.
+*
+* Resolution is separated from mutation so attach, move, and configuration
+* updates can validate every placement before changing live scene state. Scale
+* is applied before position only for conceptual consistency; both values were
+* fully calculated beforehand and neither setter is expected to fail.
+*/
+function applyContentLayout(content, layout) {
+	content.scale.set(layout.scaleX, layout.scaleY);
+	content.position.set(layout.x, layout.y);
+}
+/**
+* Resolves the final scale for one area's scaling policy.
+*
+* `none` preserves the object's authored scale, including negative values used
+* for flipping. Other modes derive positive scales from unscaled local bounds:
+* `fit` only shrinks, `contain` may shrink or grow while remaining entirely
+* visible, `cover` fills and may crop, and `stretch` scales each axis alone.
+*/
+function resolveScale(mode, area, content, currentScaleX, currentScaleY) {
+	if (mode === "none") return {
+		scaleX: currentScaleX,
+		scaleY: currentScaleY
+	};
+	if (content.width === 0 || content.height === 0) throw new Error(`Cannot apply layout scale mode "${mode}" to zero-sized content.`);
+	const widthScale = area.width / content.width;
+	const heightScale = area.height / content.height;
+	switch (mode) {
+		case "fit": {
+			const scale = Math.min(1, widthScale, heightScale);
+			return {
+				scaleX: scale,
+				scaleY: scale
+			};
+		}
+		case "contain": {
+			const scale = Math.min(widthScale, heightScale);
+			return {
+				scaleX: scale,
+				scaleY: scale
+			};
+		}
+		case "cover": {
+			const scale = Math.max(widthScale, heightScale);
+			return {
+				scaleX: scale,
+				scaleY: scale
+			};
+		}
+		case "stretch": return {
+			scaleX: widthScale,
+			scaleY: heightScale
+		};
+		default: throw new Error("Unknown layout scale mode.");
+	}
+}
+/** Places the scaled visual width against the horizontal component of alignment. */
+function resolveAlignedX(alignment, area, contentWidth) {
+	switch (alignment) {
+		case "top-left":
+		case "center-left":
+		case "bottom-left": return area.x;
+		case "top-center":
+		case "center":
+		case "bottom-center": return area.x + (area.width - contentWidth) / 2;
+		case "top-right":
+		case "center-right":
+		case "bottom-right": return area.x + area.width - contentWidth;
+		default: throw new Error("Unknown layout alignment.");
+	}
+}
+/** Places the scaled visual height against the vertical component of alignment. */
+function resolveAlignedY(alignment, area, contentHeight) {
+	switch (alignment) {
+		case "top-left":
+		case "top-center":
+		case "top-right": return area.y;
+		case "center-left":
+		case "center":
+		case "center-right": return area.y + (area.height - contentHeight) / 2;
+		case "bottom-left":
+		case "bottom-center":
+		case "bottom-right": return area.y + area.height - contentHeight;
+		default: throw new Error("Unknown layout alignment.");
+	}
+}
+//#endregion
+//#region src/layout/layout-values.ts
+/** Supported positions of content inside one resolved layout area. */
+const layoutAlignments = [
+	"top-left",
+	"top-center",
+	"top-right",
+	"center-left",
+	"center",
+	"center-right",
+	"bottom-left",
+	"bottom-center",
+	"bottom-right"
+];
+/** Supported ways to scale content relative to one resolved layout area. */
+const layoutScaleModes = [
+	"none",
+	"fit",
+	"contain",
+	"cover",
+	"stretch"
+];
+//#endregion
+//#region src/layout/resolve-layout.ts
+/** Shared read-only fallback copied into each resolved area's immutable offset. */
+const ZERO_OFFSET = {
+	x: 0,
+	y: 0
+};
+/**
+* Validates and resolves all authored areas into layout-local pixel coordinates.
+*
+* Area bounds are normalized fractions relative to `config.bounds`; the outer
+* layout bounds themselves are already expressed in pixels. Each result is a
+* newly frozen snapshot so consumers cannot mutate controller state through
+* `getArea()`. The returned map is replaced wholesale during layout updates.
+*/
+function resolveLayout(config) {
+	validateLayoutBounds(config.bounds);
+	const areas = /* @__PURE__ */ new Map();
+	for (const [name, area] of Object.entries(config.areas)) {
+		if (name.trim().length === 0) throw new Error("Layout area names must not be empty.");
+		areas.set(name, resolveLayoutArea(name, area, config.bounds));
+	}
+	return areas;
+}
+/**
+* Resolves one normalized area without applying its content offset.
+*
+* `bounds` describes the area's rectangle. `offset` belongs to content
+* placement inside that rectangle, so adding it here would incorrectly move
+* the debug rectangle and change what normalized area definitions mean.
+*/
+function resolveLayoutArea(name, config, layoutBounds) {
+	validateAreaBounds(name, config.bounds);
+	const offset = config.offset ?? ZERO_OFFSET;
+	validateFiniteNumber(offset.x, `Layout area "${name}" offset.x`);
+	validateFiniteNumber(offset.y, `Layout area "${name}" offset.y`);
+	validatePlacementValues(name, config);
+	return Object.freeze({
+		name,
+		bounds: Object.freeze({
+			x: layoutBounds.x + config.bounds.x * layoutBounds.width,
+			y: layoutBounds.y + config.bounds.y * layoutBounds.height,
+			width: config.bounds.width * layoutBounds.width,
+			height: config.bounds.height * layoutBounds.height
+		}),
+		align: config.align ?? "center",
+		scale: config.scale ?? "fit",
+		offset: Object.freeze({
+			x: offset.x,
+			y: offset.y
+		})
+	});
+}
+/** Rejects runtime strings outside the unions even when untyped JavaScript supplied them. */
+function validatePlacementValues(name, config) {
+	if (config.align !== void 0 && !layoutAlignments.includes(config.align)) throw new Error(`Layout area "${name}" has an unknown alignment: ${config.align}.`);
+	if (config.scale !== void 0 && !layoutScaleModes.includes(config.scale)) throw new Error(`Layout area "${name}" has an unknown scale mode: ${config.scale}.`);
+}
+/** Ensures the coordinate space itself can resolve normalized rectangles. */
+function validateLayoutBounds(bounds) {
+	validateBounds("Layout bounds", bounds);
+	if (bounds.width <= 0 || bounds.height <= 0) throw new Error("Layout bounds width and height must be greater than zero.");
+}
+/** Allows empty areas but rejects negative sizes that invert their geometry. */
+function validateAreaBounds(name, bounds) {
+	validateBounds(`Layout area "${name}" bounds`, bounds);
+	if (bounds.width < 0 || bounds.height < 0) throw new Error(`Layout area "${name}" width and height must not be negative.`);
+}
+/** Validates the four numeric components shared by layout and area rectangles. */
+function validateBounds(label, bounds) {
+	validateFiniteNumber(bounds.x, `${label}.x`);
+	validateFiniteNumber(bounds.y, `${label}.y`);
+	validateFiniteNumber(bounds.width, `${label}.width`);
+	validateFiniteNumber(bounds.height, `${label}.height`);
+}
+/** Rejects `NaN` and infinities before they can poison Pixi transforms. */
+function validateFiniteNumber(value, label) {
+	if (!Number.isFinite(value)) throw new Error(`${label} must be a finite number.`);
+}
+//#endregion
+//#region src/layout/create-layout.ts
+/**
+* Creates a named-area layout whose container can be mounted on any Pixi stage.
+*
+* @example Fitting rotated content through an explicit layout root
+* ```ts
+* const layoutRoot = new Container();
+* const image = createSprite({ texture: 'character' });
+*
+* image.rotation = Math.PI / 4;
+* layoutRoot.addChild(image);
+* layout.attach('character', layoutRoot);
+* ```
+*
+* The extra container is opt-in: ordinary untransformed content can be
+* attached directly without adding hidden nodes to the Pixi scene graph.
+*
+* Development builds transparently decorate the core controller with layout
+* diagnostics. `import.meta.env.DEV` is replaced at build time, allowing the
+* complete debugger branch to be removed from production playable bundles.
+*/
+function createLayout(config) {
+	const layout = createCoreLayout(config);
+	if (!import.meta.env.DEV) return layout;
+	return createDebugLayout(layout, config, createLayoutDebugRenderer(layout.container));
+}
+/**
+* Implements layout ownership and placement without development instrumentation.
+*
+* The controller owns one Pixi container and the transforms of every attached
+* object. It deliberately keeps content as direct children: applications do
+* not pay for an extra wrapper per area. The attachment map is authoritative
+* for ownership; the Pixi parent is checked as a separate invariant so manual
+* reparenting fails clearly instead of silently corrupting future updates.
+*/
+function createCoreLayout(config) {
+	const container = new Container();
+	const attachments = /* @__PURE__ */ new Map();
+	let areas = resolveLayout(config);
+	let destroyed = false;
+	return {
+		container,
+		/**
+		* Returns the currently resolved, immutable area snapshot.
+		*
+		* Coordinates are layout-local pixels, not normalized authoring values.
+		* Callers must request the area again after `update()` because the returned
+		* snapshot intentionally does not mutate in place.
+		*/
+		getArea(name) {
+			requireActive();
+			return areas.get(name);
+		},
+		/**
+		* Transfers placement ownership of one Pixi object to a named area.
+		*
+		* Every operation capable of failing runs before the scene graph or
+		* attachment map changes. The resolved transform is therefore committed
+		* only after validation and measurement succeed. Destroyed content removes
+		* its own bookkeeping entry through Pixi's `destroyed` event.
+		*/
+		attach(areaName, content) {
+			requireActive();
+			const area = requireArea(areaName);
+			if (attachments.has(content)) throw new Error("Content is already attached to this layout. Use move() instead.");
+			if (content.destroyed) throw new Error("Cannot attach destroyed content to a layout.");
+			assertNoParentCycle(content);
+			const contentLayout = resolveContentLayout(content, area);
+			container.addChild(content);
+			/** Forgets ownership when application code destroys content directly. */
+			const handleDestroyed = () => {
+				attachments.delete(content);
+			};
+			content.once("destroyed", handleDestroyed);
+			attachments.set(content, {
+				areaName,
+				handleDestroyed
+			});
+			applyContentLayout(content, contentLayout);
+		},
+		/**
+		* Reassigns managed content to another area without reparenting it.
+		*
+		* Measurement is completed before either the recorded area name or live
+		* transform changes, preserving the old valid placement if resolution
+		* throws—for example when scaled content has zero-sized local bounds.
+		*/
+		move(content, areaName) {
+			requireActive();
+			const attachment = requireAttachment(content);
+			const area = requireArea(areaName);
+			requireManagedParent(content);
+			const contentLayout = resolveContentLayout(content, area);
+			attachments.set(content, {
+				...attachment,
+				areaName
+			});
+			applyContentLayout(content, contentLayout);
+		},
+		/**
+		* Releases placement ownership and removes content from this container.
+		*
+		* Detach never destroys application content. The parent check makes the
+		* final removal tolerant of content already removed by Pixi destruction,
+		* while `requireAttachment` still rejects objects this layout never owned.
+		*/
+		detach(content) {
+			requireActive();
+			const attachment = requireAttachment(content);
+			content.off("destroyed", attachment.handleDestroyed);
+			attachments.delete(content);
+			if (content.parent === container) container.removeChild(content);
+		},
+		/**
+		* Atomically replaces bounds and areas, then relays out every attachment.
+		*
+		* Resolution and all content measurements are staged first. No current
+		* area or live transform changes unless the complete next configuration is
+		* valid for every attachment. Occupied areas cannot disappear because that
+		* would leave their content without a deterministic destination.
+		*/
+		update(nextConfig) {
+			requireActive();
+			const nextAreas = resolveLayout(nextConfig);
+			const nextContentLayouts = /* @__PURE__ */ new Map();
+			for (const [content, { areaName }] of attachments) {
+				requireManagedParent(content);
+				const area = nextAreas.get(areaName);
+				if (area === void 0) throw new Error(`Cannot remove occupied layout area "${areaName}".`);
+				nextContentLayouts.set(content, resolveContentLayout(content, area));
+			}
+			areas = nextAreas;
+			for (const [content, contentLayout] of nextContentLayouts) applyContentLayout(content, contentLayout);
+		},
+		/**
+		* Idempotently releases layout bookkeeping and destroys only its container.
+		*
+		* Attached application objects are detached, not destroyed. Their listeners
+		* are removed explicitly so they no longer retain this controller after its
+		* lifecycle ends.
+		*/
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			for (const [content, attachment] of attachments) {
+				content.off("destroyed", attachment.handleDestroyed);
+				if (content.parent === container) container.removeChild(content);
+			}
+			attachments.clear();
+			areas = /* @__PURE__ */ new Map();
+			container.destroy();
+		}
+	};
+	/** Guards every read and mutation whose state disappears during destruction. */
+	function requireActive() {
+		if (destroyed) throw new Error("Cannot use a destroyed Replayable layout.");
+	}
+	/** Resolves a required area while producing an error that names the authoring key. */
+	function requireArea(name) {
+		const area = areas.get(name);
+		if (area === void 0) throw new Error(`Layout area "${name}" does not exist.`);
+		return area;
+	}
+	/** Returns this layout's ownership record for content or rejects foreign content. */
+	function requireAttachment(content) {
+		const attachment = attachments.get(content);
+		if (attachment === void 0) throw new Error("Content is not attached to this layout.");
+		return attachment;
+	}
+	/**
+	* Detects manual scene-graph reparenting of managed content.
+	*
+	* Continuing after reparenting would update an object in another coordinate
+	* space, so failing is safer than producing a visually incorrect placement.
+	*/
+	function requireManagedParent(content) {
+		if (content.parent !== container) throw new Error("Attached layout content was reparented outside the layout container.");
+	}
+	/**
+	* Prevents Pixi from parenting the layout beneath its own descendant.
+	*
+	* Walking upward from the owned container catches both the container itself
+	* and any ancestor supplied as content, either of which would create a cycle.
+	*/
+	function assertNoParentCycle(content) {
+		let ancestor = container;
+		while (ancestor !== null) {
+			if (ancestor === content) throw new Error("Cannot attach the layout container or one of its ancestors.");
+			ancestor = ancestor.parent;
+		}
+	}
+}
+//#endregion
+//#region src/text/fit-text.ts
+/**
+* Uniformly fits text inside a box without enlarging beyond its authored size.
+* Replaces the object's scale using local bounds, so repeated fitting never
+* compounds a previous fit. Position, pivot, wrapping, and text remain unchanged.
+* Split manually managed SplitText before fitting, and fit before animating its
+* characters (or supply stable boundsArea). Empty bounds impose no constraint.
+*/
+function fitText(text, options) {
+	const { width, height } = options;
+	if (!Number.isFinite(width) || width <= 0 || height !== void 0 && (!Number.isFinite(height) || height <= 0)) throw new Error("Text fitting dimensions must be positive finite numbers.");
+	const bounds = text.getLocalBounds();
+	const widthScale = bounds.width > 0 ? width / bounds.width : 1;
+	const heightScale = height !== void 0 && bounds.height > 0 ? height / bounds.height : 1;
+	text.scale.set(Math.min(1, widthScale, heightScale));
+}
+//#endregion
+export { createAnimatedSprite, createButton, createLayout, createNineSliceSprite, createPixi, createSplitText, createSprite, createText, fitText };
+
+//# sourceMappingURL=index.js.map