# Sprite types

## SpriteFrame

Opaque immutable handle with a stable name and original logical width/height. Its sheet owns image data.

## SpriteRectangle

Source pixel rectangle with x, y, width, and height.

## SpriteFrameData

Normalized adapter record: name, optional page, packed rectangle, original size, trim offset, and rotation flag.

## SpriteAnimationFrameData

Normalized frame name and positive duration in milliseconds.

## SpriteSheetData

Adapter result containing relative image URLs, frame records, and optional named timed clips.

## SpriteSheetFormat

Explicit parser object with `parse(unknown)` returning normalized sheet data.

## SpriteSheet

Shared decoded images exposed through readonly frame and animation maps, with idempotent disposal.

## SpriteGrid

Positive integer frameWidth/frameHeight and optional nonnegative integer margin/spacing, measured in pixels.

## SpriteProps

Frame, sampling, normalized anchor, flipX/flipY, and ordinary drawing event props. Declared primitive inputs accept signals.

## SpriteStyle

Logical width, height, opacity, and ordinary Pibbl system style. Default size is the frame’s original untrimmed size.

## API details from source

<span id="api-SpriteProps"></span>

### SpriteProps

Drawing inputs; frame also accepts a signal through Pibbl's declared primitive inputs. See SpriteFrame.

```ts
interface SpriteProps extends ImageProps
```

Related API: [SpriteProps](/reference/types/sprites/#spriteprops), [ImageProps](/reference/types/elements-components/#imageprops).

[View source — packages/core/src/features/sprites/sprite.ts:8](/source/packages/core/src/features/sprites/sprite-ts/#L8)

#### Properties and methods

<span id="api-SpriteProps-frame"></span>
<details>
<summary>frame</summary>


```ts
readonly frame: SpriteFrame
```

Related API: [SpriteFrame](/reference/types/sprites/#spriteframe).

Atlas frame to draw; its sheet must remain undisposed.

[View source — packages/core/src/features/sprites/sprite.ts:9](/source/packages/core/src/features/sprites/sprite-ts/#L9)

</details>

<span id="api-SpriteProps-sampling"></span>
<details>
<summary>sampling (optional)</summary>


```ts
readonly sampling?: "linear" | "nearest" | undefined
```

Image interpolation; defaults to linear.

[View source — packages/core/src/features/sprites/sprite.ts:10](/source/packages/core/src/features/sprites/sprite-ts/#L10)

</details>

<span id="api-SpriteProps-anchor"></span>
<details>
<summary>anchor (optional)</summary>


```ts
readonly anchor?: Readonly<{ x: number; y: number; }> | undefined
```

Normalized origin within the original frame, defaulting to the top-left.

[View source — packages/core/src/features/sprites/sprite.ts:11](/source/packages/core/src/features/sprites/sprite-ts/#L11)

</details>

<span id="api-SpriteProps-flipX"></span>
<details>
<summary>flipX (optional)</summary>


```ts
readonly flipX?: boolean | undefined
```

Mirror the frame horizontally.

[View source — packages/core/src/features/sprites/sprite.ts:12](/source/packages/core/src/features/sprites/sprite-ts/#L12)

</details>

<span id="api-SpriteProps-flipY"></span>
<details>
<summary>flipY (optional)</summary>


```ts
readonly flipY?: boolean | undefined
```

Mirror the frame vertically.

[View source — packages/core/src/features/sprites/sprite.ts:13](/source/packages/core/src/features/sprites/sprite-ts/#L13)

</details>

<span id="api-SpriteProps-pointerEvents"></span>
<details>
<summary>pointerEvents (optional)</summary>


```ts
readonly pointerEvents?: PibblPointerEvents | undefined
```

Related API: [PibblPointerEvents](/reference/types/events/#pibblpointerevents).

Whether this content participates in pointer targeting. See PibblPointerEvents.

[View source — packages/core/src/lib/events/types.ts:126](/source/packages/core/src/lib/events/types-ts/#L126)

</details>

<span id="api-SpriteProps-keyboardFocusable"></span>
<details>
<summary>keyboardFocusable (optional)</summary>


```ts
readonly keyboardFocusable?: boolean | undefined
```

Whether the target may receive keyboard focus. See PibblEventFocusOptions.

[View source — packages/core/src/lib/events/types.ts:137](/source/packages/core/src/lib/events/types-ts/#L137)

</details>

<span id="api-SpriteProps-keyboardNavigationBounds"></span>
<details>
<summary>keyboardNavigationBounds (optional)</summary>


```ts
readonly keyboardNavigationBounds?: Readonly<LayoutBox> | undefined
```

Related API: [LayoutBox](/reference/types/layout/#layoutbox).

Logical rectangle used for directional keyboard navigation. See LayoutBox.

[View source — packages/core/src/lib/events/types.ts:139](/source/packages/core/src/lib/events/types-ts/#L139)

</details>

<span id="api-SpriteProps-physics"></span>
<details>
<summary>physics (optional)</summary>


```ts
readonly physics?: PibblPhysicsAttachment2D | undefined
```

Related API: [PibblPhysicsAttachment2D](/reference/types/physics-2d/#pibblphysicsattachment2d).



[View source — packages/core/src/features/physics/lib/2d/types.ts:321](/source/packages/core/src/features/physics/lib/2d/types-ts/#L321)

</details>

<span id="api-SpriteStyle"></span>

### SpriteStyle

Logical size overrides; omitted dimensions use the original untrimmed frame size. See SpriteFrame.

```ts
interface SpriteStyle extends SystemStyle
```

Related API: [SpriteStyle](/reference/types/sprites/#spritestyle), [SystemStyle](/reference/types/styles/#systemstyle).

[View source — packages/core/src/features/sprites/sprite.ts:16](/source/packages/core/src/features/sprites/sprite-ts/#L16)

#### Properties and methods

<span id="api-SpriteStyle-width"></span>
<details>
<summary>width (optional)</summary>


```ts
readonly width?: number | undefined
```



[View source — packages/core/src/features/sprites/sprite.ts:16](/source/packages/core/src/features/sprites/sprite-ts/#L16)

</details>

<span id="api-SpriteStyle-height"></span>
<details>
<summary>height (optional)</summary>


```ts
readonly height?: number | undefined
```



[View source — packages/core/src/features/sprites/sprite.ts:16](/source/packages/core/src/features/sprites/sprite-ts/#L16)

</details>

<span id="api-SpriteStyle-opacity"></span>
<details>
<summary>opacity (optional)</summary>


```ts
readonly opacity?: number | undefined
```

Related API: [opacity](/reference/types/filters/#opacity).



[View source — packages/core/src/features/sprites/sprite.ts:16](/source/packages/core/src/features/sprites/sprite-ts/#L16)

</details>

<span id="api-SpriteStyle-transition"></span>
<details>
<summary>transition (optional)</summary>


```ts
transition?: PibblTransitionBinding | undefined
```

Related API: [PibblTransitionBinding](/reference/hooks/use-visibility-transition/).

Visibility-transition binding applied to this primitive and its captured descendants. See SystemStyle.

[View source — packages/core/src/lib/types.ts:69](/source/packages/core/src/lib/types-ts/#L69)

</details>

<span id="api-SpriteStyle-custom"></span>
<details>
<summary>custom (optional)</summary>


```ts
custom?: unknown
```

Application-defined style payload passed through the runtime. See SystemStyle.

[View source — packages/core/src/lib/types.ts:71](/source/packages/core/src/lib/types-ts/#L71)

</details>

<span id="api-SpriteStyle-filter"></span>
<details>
<summary>filter (optional)</summary>


```ts
filter?: PibblFilter | readonly PibblFilter[] | undefined
```

Related API: [PibblFilter](/reference/types/filters/#pibblfilter).

Ordered pixel-only filters applied to the receiving primitive and its descendants. See
PibblFilter.

[View source — packages/core/src/lib/types.ts:76](/source/packages/core/src/lib/types-ts/#L76)

</details>

<span id="api-SpriteSheet"></span>

### SpriteSheet

Shared decoded atlas and immutable frames/clips. Dispose after all consumers unmount. See SpriteFrame.

```ts
interface SpriteSheet
```

Related API: [SpriteSheet](/reference/types/sprites/#spritesheet).

[View source — packages/core/src/features/sprites/loader.ts:4](/source/packages/core/src/features/sprites/loader-ts/#L4)

#### Properties and methods

<span id="api-SpriteSheet-frames"></span>
<details>
<summary>frames</summary>


```ts
readonly frames: Readonly<Record<string | number, SpriteFrame>>
```

Related API: [SpriteFrame](/reference/types/sprites/#spriteframe).

Frames indexed by atlas name or numeric grid index.

[View source — packages/core/src/features/sprites/loader.ts:5](/source/packages/core/src/features/sprites/loader-ts/#L5)

</details>

<span id="api-SpriteSheet-animations"></span>
<details>
<summary>animations</summary>


```ts
readonly animations: Readonly<Record<string, PibblAnimationDefinition<SpriteFrame>>>
```

Related API: [PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition), [SpriteFrame](/reference/types/sprites/#spriteframe).

Named, seekable animation definitions from the atlas.

[View source — packages/core/src/features/sprites/loader.ts:6](/source/packages/core/src/features/sprites/loader-ts/#L6)

</details>

<span id="api-SpriteSheet-dispose"></span>
<details>
<summary>dispose</summary>


```ts
readonly dispose: () => void
```

Release decoded images; unmount every consumer before calling.

[View source — packages/core/src/features/sprites/loader.ts:7](/source/packages/core/src/features/sprites/loader-ts/#L7)

</details>

<span id="api-SpriteGrid"></span>

### SpriteGrid

Dimensions of a regular grid, in image pixels. See SpriteFrame.

```ts
interface SpriteGrid
```

Related API: [SpriteGrid](/reference/types/sprites/#spritegrid).

[View source — packages/core/src/features/sprites/loader.ts:10](/source/packages/core/src/features/sprites/loader-ts/#L10)

#### Properties and methods

<span id="api-SpriteGrid-frameWidth"></span>
<details>
<summary>frameWidth</summary>


```ts
readonly frameWidth: number
```



[View source — packages/core/src/features/sprites/loader.ts:10](/source/packages/core/src/features/sprites/loader-ts/#L10)

</details>

<span id="api-SpriteGrid-frameHeight"></span>
<details>
<summary>frameHeight</summary>


```ts
readonly frameHeight: number
```



[View source — packages/core/src/features/sprites/loader.ts:10](/source/packages/core/src/features/sprites/loader-ts/#L10)

</details>

<span id="api-SpriteGrid-margin"></span>
<details>
<summary>margin (optional)</summary>


```ts
readonly margin?: number | undefined
```



[View source — packages/core/src/features/sprites/loader.ts:10](/source/packages/core/src/features/sprites/loader-ts/#L10)

</details>

<span id="api-SpriteGrid-spacing"></span>
<details>
<summary>spacing (optional)</summary>


```ts
readonly spacing?: number | undefined
```



[View source — packages/core/src/features/sprites/loader.ts:10](/source/packages/core/src/features/sprites/loader-ts/#L10)

</details>

<span id="api-SpriteFrame"></span>

### SpriteFrame

Immutable atlas frame. Obtain frames from loadSpriteSheet; images belong to the sheet. See SpriteFrame.

```ts
class SpriteFrame
```

Related API: [SpriteFrame](/reference/types/sprites/#spriteframe).

[View source — packages/core/src/features/sprites/model.ts:32](/source/packages/core/src/features/sprites/model-ts/#L32)

#### Properties and methods

<span id="api-SpriteFrame-width"></span>
<details>
<summary>width</summary>


```ts
readonly width: number
```

Original logical frame width, before transparent borders were trimmed.

##### Returns

Width in logical pixels.

[View source — packages/core/src/features/sprites/model.ts:37](/source/packages/core/src/features/sprites/model-ts/#L37)

</details>

<span id="api-SpriteFrame-height"></span>
<details>
<summary>height</summary>


```ts
readonly height: number
```

Original logical frame height, before transparent borders were trimmed.

##### Returns

Height in logical pixels.

[View source — packages/core/src/features/sprites/model.ts:41](/source/packages/core/src/features/sprites/model-ts/#L41)

</details>

<span id="api-SpriteFrame-name"></span>
<details>
<summary>name</summary>


```ts
readonly name: string
```

Stable name supplied by the atlas or numeric grid index.

##### Returns

The frame name.

[View source — packages/core/src/features/sprites/model.ts:45](/source/packages/core/src/features/sprites/model-ts/#L45)

</details>

<span id="api-SpriteRectangle"></span>

### SpriteRectangle

Pixel rectangle within an atlas page or original frame. See SpriteFrame.

```ts
interface SpriteRectangle
```

Related API: [SpriteRectangle](/reference/types/sprites/#spriterectangle).

[View source — packages/core/src/features/sprites/model.ts:5](/source/packages/core/src/features/sprites/model-ts/#L5)

#### Properties and methods

<span id="api-SpriteRectangle-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: number
```



[View source — packages/core/src/features/sprites/model.ts:5](/source/packages/core/src/features/sprites/model-ts/#L5)

</details>

<span id="api-SpriteRectangle-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: number
```



[View source — packages/core/src/features/sprites/model.ts:5](/source/packages/core/src/features/sprites/model-ts/#L5)

</details>

<span id="api-SpriteRectangle-width"></span>
<details>
<summary>width</summary>


```ts
readonly width: number
```



[View source — packages/core/src/features/sprites/model.ts:5](/source/packages/core/src/features/sprites/model-ts/#L5)

</details>

<span id="api-SpriteRectangle-height"></span>
<details>
<summary>height</summary>


```ts
readonly height: number
```



[View source — packages/core/src/features/sprites/model.ts:5](/source/packages/core/src/features/sprites/model-ts/#L5)

</details>

<span id="api-SpriteFrameData"></span>

### SpriteFrameData

Normalized frame information returned by a format adapter. See SpriteFrame.

```ts
interface SpriteFrameData
```

Related API: [SpriteFrameData](/reference/types/sprites/#spriteframedata).

[View source — packages/core/src/features/sprites/model.ts:7](/source/packages/core/src/features/sprites/model-ts/#L7)

#### Properties and methods

<span id="api-SpriteFrameData-name"></span>
<details>
<summary>name</summary>


```ts
readonly name: string
```

Unique frame name in this sheet.

[View source — packages/core/src/features/sprites/model.ts:8](/source/packages/core/src/features/sprites/model-ts/#L8)

</details>

<span id="api-SpriteFrameData-page"></span>
<details>
<summary>page (optional)</summary>


```ts
readonly page?: number | undefined
```

Zero-based atlas page index; defaults to zero.

[View source — packages/core/src/features/sprites/model.ts:9](/source/packages/core/src/features/sprites/model-ts/#L9)

</details>

<span id="api-SpriteFrameData-rect"></span>
<details>
<summary>rect</summary>


```ts
readonly rect: SpriteRectangle
```

Related API: [SpriteRectangle](/reference/types/sprites/#spriterectangle).

Packed rectangle within the atlas page.

[View source — packages/core/src/features/sprites/model.ts:10](/source/packages/core/src/features/sprites/model-ts/#L10)

</details>

<span id="api-SpriteFrameData-sourceSize"></span>
<details>
<summary>sourceSize (optional)</summary>


```ts
readonly sourceSize?: Readonly<{ width: number; height: number; }> | undefined
```

Original frame dimensions before trimming.

[View source — packages/core/src/features/sprites/model.ts:11](/source/packages/core/src/features/sprites/model-ts/#L11)

</details>

<span id="api-SpriteFrameData-trim"></span>
<details>
<summary>trim (optional)</summary>


```ts
readonly trim?: Readonly<{ x: number; y: number; }> | undefined
```

Trimmed content offset within the original frame.

[View source — packages/core/src/features/sprites/model.ts:12](/source/packages/core/src/features/sprites/model-ts/#L12)

</details>

<span id="api-SpriteFrameData-rotated"></span>
<details>
<summary>rotated (optional)</summary>


```ts
readonly rotated?: boolean | undefined
```

Whether the packed rectangle is rotated clockwise.

[View source — packages/core/src/features/sprites/model.ts:13](/source/packages/core/src/features/sprites/model-ts/#L13)

</details>

<span id="api-SpriteAnimationFrameData"></span>

### SpriteAnimationFrameData

One normalized timed frame reference. Durations are milliseconds. See SpriteFrame.

```ts
interface SpriteAnimationFrameData
```

Related API: [SpriteAnimationFrameData](/reference/types/sprites/#spriteanimationframedata).

[View source — packages/core/src/features/sprites/model.ts:16](/source/packages/core/src/features/sprites/model-ts/#L16)

#### Properties and methods

<span id="api-SpriteAnimationFrameData-frame"></span>
<details>
<summary>frame</summary>


```ts
readonly frame: string
```



[View source — packages/core/src/features/sprites/model.ts:16](/source/packages/core/src/features/sprites/model-ts/#L16)

</details>

<span id="api-SpriteAnimationFrameData-duration"></span>
<details>
<summary>duration</summary>


```ts
readonly duration: number
```



[View source — packages/core/src/features/sprites/model.ts:16](/source/packages/core/src/features/sprites/model-ts/#L16)

</details>

<span id="api-SpriteSheetData"></span>

### SpriteSheetData

Adapter result. Image paths resolve relative to the metadata URL. See SpriteFrame.

```ts
interface SpriteSheetData
```

Related API: [SpriteSheetData](/reference/types/sprites/#spritesheetdata).

[View source — packages/core/src/features/sprites/model.ts:18](/source/packages/core/src/features/sprites/model-ts/#L18)

#### Properties and methods

<span id="api-SpriteSheetData-images"></span>
<details>
<summary>images</summary>


```ts
readonly images: readonly string[]
```

Atlas image URLs, relative to the metadata URL.

[View source — packages/core/src/features/sprites/model.ts:19](/source/packages/core/src/features/sprites/model-ts/#L19)

</details>

<span id="api-SpriteSheetData-frames"></span>
<details>
<summary>frames</summary>


```ts
readonly frames: readonly SpriteFrameData[]
```

Related API: [SpriteFrameData](/reference/types/sprites/#spriteframedata).

Normalized frame records for this sheet.

[View source — packages/core/src/features/sprites/model.ts:20](/source/packages/core/src/features/sprites/model-ts/#L20)

</details>

<span id="api-SpriteSheetData-animations"></span>
<details>
<summary>animations (optional)</summary>


```ts
readonly animations?: Readonly<Record<string, readonly SpriteAnimationFrameData[]>> | undefined
```

Related API: [SpriteAnimationFrameData](/reference/types/sprites/#spriteanimationframedata).

Named sequences of timed frame references.

[View source — packages/core/src/features/sprites/model.ts:21](/source/packages/core/src/features/sprites/model-ts/#L21)

</details>

<span id="api-SpriteSheetFormat"></span>

### SpriteSheetFormat

Import adapter; loaders invoke this directly without a format registry. See SpriteFrame.

```ts
interface SpriteSheetFormat
```

Related API: [SpriteSheetFormat](/reference/types/sprites/#spritesheetformat).

[View source — packages/core/src/features/sprites/model.ts:24](/source/packages/core/src/features/sprites/model-ts/#L24)

#### Properties and methods

<span id="api-SpriteSheetFormat-parse"></span>
<details>
<summary>parse</summary>


```ts
readonly parse: (data: unknown) => SpriteSheetData
```

Related API: [SpriteSheetData](/reference/types/sprites/#spritesheetdata).



[View source — packages/core/src/features/sprites/model.ts:27](/source/packages/core/src/features/sprites/model-ts/#L27)

</details>

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Animated sprite atlas](/minimal-examples/sprites/atlas/): Generate a two-frame atlas, animate a shared sheet, and dispose it after unmounting. [Plain source](/minimal/sprites/atlas.tsx)
- [Sprite format adapters](/minimal-examples/sprites/formats/): Compare normalized Aseprite, TexturePacker, and application-owned atlas metadata. [Plain source](/minimal/sprites/formats.ts)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.