@replayablejs/pixi 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Replayable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @replayablejs/pixi
+
+Connect Pixi rendering, asset loaders and layout to the playable lifecycle.
+
+Part of [Replayable](https://github.com/replayablejs/replayable) **0.1.0-alpha.0**.
+APIs may change during the alpha series.
+
+## Install
+
+```sh
+pnpm add @replayablejs/pixi@0.1.0-alpha.0
+```
+
+## Public surface
+
+`createPixi`, `createButton`, sprite/text factories, `createLayout`, `fitText` and their types. Optional `/spine` entry: `createSpineIntegration`, `createSpine`, `CreateSpineOptions`.
+
+[Usage and reference](https://github.com/replayablejs/replayable/blob/main/docs/reference/pixi.md).
+The package manifest defines supported import paths; internal source files are not public APIs.
+
+## Development
+
+From the repository root, install with `pnpm install --frozen-lockfile` and build dependencies
+with `pnpm build`. Run `pnpm --filter @replayablejs/pixi test` for this package's tests.
+
+## Peer dependencies
+
+- `@esotericsoftware/spine-pixi-v8`: `~4.3.13` (optional)
+- `@replayablejs/runtime`: `workspace:*`
+- `pixi.js`: `^8.20.1`
+
+Workspace ranges are converted to package versions when packed.
+
+## License
+
+Original code is [MIT licensed](https://github.com/replayablejs/replayable/blob/main/LICENSE). Bundled third-party resources retain
+their accompanying license terms.

package/dist/apply-container-options-CloU_2Pk.js

@@ -0,0 +1,23 @@
+//#region src/factories/apply-container-options.ts
+const ZERO_POINT = {
+	x: 0,
+	y: 0
+};
+const UNIT_SCALE = {
+	x: 1,
+	y: 1
+};
+/** Applies the transform and visibility defaults shared by Pixi containers. */
+function applyContainerOptions(container, options) {
+	container.position.copyFrom(options.position ?? ZERO_POINT);
+	container.scale.copyFrom(options.scale ?? UNIT_SCALE);
+	container.pivot.copyFrom(options.pivot ?? ZERO_POINT);
+	container.rotation = options.rotation ?? 0;
+	container.alpha = options.alpha ?? 1;
+	container.visible = options.visible ?? true;
+	container.zIndex = options.zIndex ?? 0;
+}
+//#endregion
+export { applyContainerOptions as t };
+
+//# sourceMappingURL=apply-container-options-CloU_2Pk.js.map

package/dist/apply-container-options-CloU_2Pk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-container-options-CloU_2Pk.js","names":[],"sources":["../src/factories/apply-container-options.ts"],"sourcesContent":["import type { Container } from 'pixi.js';\n\nimport type { DisplayObjectOptions } from '#types/factories.js';\n\nconst ZERO_POINT = { x: 0, y: 0 };\nconst UNIT_SCALE = { x: 1, y: 1 };\n\n/** Applies the transform and visibility defaults shared by Pixi containers. */\nexport function applyContainerOptions(container: Container, options: DisplayObjectOptions): void {\n  container.position.copyFrom(options.position ?? ZERO_POINT);\n  container.scale.copyFrom(options.scale ?? UNIT_SCALE);\n  container.pivot.copyFrom(options.pivot ?? ZERO_POINT);\n  container.rotation = options.rotation ?? 0;\n  container.alpha = options.alpha ?? 1;\n  container.visible = options.visible ?? true;\n  container.zIndex = options.zIndex ?? 0;\n}\n"],"mappings":";AAIA,MAAM,aAAa;CAAE,GAAG;CAAG,GAAG;AAAE;AAChC,MAAM,aAAa;CAAE,GAAG;CAAG,GAAG;AAAE;;AAGhC,SAAgB,sBAAsB,WAAsB,SAAqC;CAC/F,UAAU,SAAS,SAAS,QAAQ,YAAY,UAAU;CAC1D,UAAU,MAAM,SAAS,QAAQ,SAAS,UAAU;CACpD,UAAU,MAAM,SAAS,QAAQ,SAAS,UAAU;CACpD,UAAU,WAAW,QAAQ,YAAY;CACzC,UAAU,QAAQ,QAAQ,SAAS;CACnC,UAAU,UAAU,QAAQ,WAAW;CACvC,UAAU,SAAS,QAAQ,UAAU;AACvC"}

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+import { a as CreateAnimatedSpriteOptions, c as CreateSpriteOptions, d as SpriteDisplayOptions, i as AnchorableDisplayObjectOptions, l as CreateTextOptions, n as PixiIntegration, o as CreateNineSliceSpriteOptions, r as ReplayablePixi, s as CreateSplitTextOptions, t as CreatePixiOptions, u as DisplayObjectOptions } from "./pixi-DXx3NI4T.js";
+import { AnimatedSprite, Container, NineSliceSprite, PointData, SplitText, Sprite, Text } from "pixi.js";
+//#region src/types/button.d.ts
+/** Button behavior around caller-created artwork; no automatic layout or animation. */
+interface CreateButtonOptions {
+  /** Ownership transfers to the button. Create and size the artwork before passing it. */
+  readonly content: Container;
+  /** Runs synchronously on a completed tap, after propagation has been stopped. */
+  readonly onActivate: () => void;
+  readonly enabled?: boolean;
+}
+/** A stable interaction container whose child artwork may animate independently. */
+interface ReplayableButton {
+  readonly container: Container;
+  /** Disabling leaves the button visible but non-interactive; it does not dim artwork. */
+  setEnabled(this: void, enabled: boolean): void;
+  /** Removes listeners and destroys owned artwork, retaining shared asset textures. */
+  destroy(this: void): void;
+}
+//#endregion
+//#region src/types/text.d.ts
+/** Available space in the text parent's local units, before parent/layout scaling. */
+interface FitTextOptions {
+  readonly width: number;
+  /** Omit when only horizontal fitting is needed. */
+  readonly height?: number;
+}
+//#endregion
+//#region src/types/layout.d.ts
+/** Alignment of laid-out content inside one named area. */
+type LayoutAlignment = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/** How laid-out content is scaled relative to its named area. */
+type LayoutScaleMode = 'none' | 'fit' | 'contain' | 'cover' | 'stretch';
+/**
+ * Axis-aligned rectangle.
+ *
+ * `LayoutConfig.bounds` and resolved areas use layout-local pixels. Authored
+ * `LayoutAreaConfig.bounds` uses normalized fractions relative to the outer
+ * layout rectangle.
+ */
+interface LayoutBounds {
+  /** Horizontal coordinate of the left edge. */
+  readonly x: number;
+  /** Vertical coordinate of the top edge. */
+  readonly y: number;
+  /** Horizontal extent; outer layout bounds require a positive value. */
+  readonly width: number;
+  /** Vertical extent; outer layout bounds require a positive value. */
+  readonly height: number;
+}
+/** Author-defined normalized bounds and placement behavior for one named area. */
+interface LayoutAreaConfig {
+  /** Position of scaled content inside the resolved area; defaults to `center`. */
+  readonly align?: LayoutAlignment;
+  /** Normalized rectangle resolved relative to the outer layout bounds. */
+  readonly bounds: LayoutBounds;
+  /** Final pixel adjustment applied to content after alignment. */
+  readonly offset?: PointData;
+  /** Scaling policy applied before content alignment; defaults to `fit`. */
+  readonly scale?: LayoutScaleMode;
+}
+/** Selects which diagnostic labels are visible during development. */
+interface LayoutDebugLabelOptions {
+  /** Shows dimensions for every resolved named area. */
+  readonly areas?: boolean;
+  /** Shows dimensions for every attached content box. */
+  readonly content?: boolean;
+  /** Shows the outer layout dimensions. */
+  readonly layout?: boolean;
+}
+/** Selects which development-only layout diagnostics are visible. */
+interface LayoutDebugOptions {
+  /** Shows green occupied and amber empty named-area rectangles. */
+  readonly areaBounds?: boolean;
+  /** Shows the magenta axis-aligned boxes used to place and scale content. */
+  readonly contentBounds?: boolean;
+  /** Enables every label or independently configures layout, area, and content labels. */
+  readonly labels?: boolean | LayoutDebugLabelOptions;
+  /** Shows the cyan outer layout rectangle. */
+  readonly layoutBounds?: boolean;
+}
+/** Complete named-area layout definition. */
+interface LayoutConfig {
+  /** Layout-local rectangle against which normalized areas are resolved. */
+  readonly bounds: LayoutBounds;
+  /** Enables all diagnostics or selectively configures them during development. */
+  readonly debug?: boolean | LayoutDebugOptions;
+  /** Named normalized regions to which application display objects can be attached. */
+  readonly areas: Readonly<Record<string, LayoutAreaConfig>>;
+}
+/** Read-only resolved placement of one named area in layout-local coordinates. */
+interface ResolvedLayoutArea {
+  /** Fully defaulted content alignment. */
+  readonly align: LayoutAlignment;
+  /** Area rectangle resolved into layout-local pixels. */
+  readonly bounds: LayoutBounds;
+  /** Stable authored key used by attach and move operations. */
+  readonly name: string;
+  /** Immutable pixel adjustment applied after alignment. */
+  readonly offset: Readonly<PointData>;
+  /** Fully defaulted scaling policy. */
+  readonly scale: LayoutScaleMode;
+}
+/** Controller returned by `createLayout()`. */
+interface ReplayableLayout {
+  /**
+   * Pixi container that the application adds to its chosen stage.
+   * Attached content remains a direct child; named areas are calculations, not
+   * additional scene-graph containers.
+   */
+  readonly container: Container;
+  /**
+   * Attaches content to a named area and immediately lays it out.
+   *
+   * The layout owns the attached object's position and, unless the area's
+   * scale mode is `none`, its scale. Automatic fitting measures local bounds;
+   * it does not include rotation or skew applied directly to the attached
+   * object. Put transformed content inside an untransformed application-owned
+   * container when those transforms must contribute to fitting.
+   * Throws for unknown areas, duplicate attachment, destroyed content, parent
+   * cycles, or content that cannot be measured for its scaling mode.
+   */
+  attach(areaName: string, content: Container): void;
+  /**
+   * Stops managing and removes attached content from the layout container.
+   * The content remains alive and can be attached elsewhere by the application.
+   */
+  detach(content: Container): void;
+  /**
+   * Returns an immutable resolved-area snapshot, or `undefined` when absent.
+   * Previously returned snapshots do not change after `update()`.
+   */
+  getArea(name: string): ResolvedLayoutArea | undefined;
+  /**
+   * Moves attached content to another named area without reparenting it.
+   * The operation is atomic: failure preserves its previous area and transform.
+   */
+  move(content: Container, areaName: string): void;
+  /**
+   * Atomically replaces the layout definition and recalculates all attachments.
+   * An occupied area cannot be removed until its content is detached or moved.
+   */
+  update(config: LayoutConfig): void;
+  /**
+   * Releases bookkeeping and destroys the owned container without destroying
+   * application content. Repeated calls are harmless.
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/create-pixi.d.ts
+/** Initializes Pixi around Replayable's assets, lifecycle, and shared canvas. */
+declare function createPixi(options?: CreatePixiOptions): Promise<ReplayablePixi>;
+//#endregion
+//#region src/factories/create-button.d.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();
+ */
+declare function createButton(options: CreateButtonOptions): ReplayableButton;
+//#endregion
+//#region src/factories/create-animated-sprite.d.ts
+/** Creates an unattached animated sprite driven by Pixi's Replayable-managed ticker. */
+declare function createAnimatedSprite(options: CreateAnimatedSpriteOptions): AnimatedSprite;
+//#endregion
+//#region src/factories/create-nine-slice-sprite.d.ts
+/** Creates an unattached nine-slice sprite with explicitly named borders. */
+declare function createNineSliceSprite(options: CreateNineSliceSpriteOptions): NineSliceSprite;
+//#endregion
+//#region src/factories/create-sprite.d.ts
+/** Creates an unattached Pixi sprite with Replayable's conventional defaults. */
+declare function createSprite(options?: CreateSpriteOptions): Sprite;
+//#endregion
+//#region src/factories/create-split-text.d.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.
+ */
+declare function createSplitText(options: CreateSplitTextOptions): SplitText;
+//#endregion
+//#region src/factories/create-text.d.ts
+/** Creates unattached Pixi canvas text while leaving content and layout to the application. */
+declare function createText(options: CreateTextOptions): Text;
+//#endregion
+//#region src/layout/create-layout.d.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.
+ */
+declare function createLayout(config: LayoutConfig): ReplayableLayout;
+//#endregion
+//#region src/text/fit-text.d.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.
+ */
+declare function fitText(text: Text | SplitText, options: FitTextOptions): void;
+//#endregion
+export { type AnchorableDisplayObjectOptions, type CreateAnimatedSpriteOptions, type CreateButtonOptions, type CreateNineSliceSpriteOptions, type CreatePixiOptions, type CreateSplitTextOptions, type CreateSpriteOptions, type CreateTextOptions, type DisplayObjectOptions, type FitTextOptions, type LayoutAlignment, type LayoutAreaConfig, type LayoutBounds, type LayoutConfig, type LayoutDebugLabelOptions, type LayoutDebugOptions, type LayoutScaleMode, type PixiIntegration, type ReplayableButton, type ReplayableLayout, type ReplayablePixi, type ResolvedLayoutArea, type SpriteDisplayOptions, createAnimatedSprite, createButton, createLayout, createNineSliceSprite, createPixi, createSplitText, createSprite, createText, fitText };
+//# sourceMappingURL=index.d.ts.map