# Texture resources

`defineTexture` from `@pibbl/core` creates a recipe factory. Recipes contain data;
`useTexture(recipe, options)` creates one persistent, mount-owned source that can
be passed directly to `style.fill` or `style.stroke`. Its `send(message)` method
queues typed, structured-cloneable data for the next Pibbl update. It may not run
during rendering. A static texture without a receiver accepts no messages.

`TextureDefinition<Config, State, Message>` supplies synchronous `create`,
`rasterize`, and optional `update`, `receive`, `advance`, and `dispose` callbacks.
`TextureContext` supplies the resource-owned `canvas`, optional `palette`,
`invalidate()` for changed output, and `requestFrame()` for continuing work.
`TextureFrame` supplies `delta` and `time` in milliseconds. No additional loop is
needed. Configurations and messages must be structured-cloneable data.

`TextureOptions` controls `resolution` and optional `palette`. Resolution defaults
to 256 by 160; dimensions are integers from 8 through 1024 with at most 262144
cells. Resizing resets implementation state. Palette changes preserve state.

`Texture<Message>` is a `TexturePaint` with `send` and `paint(placement)`.
`TexturePlacement` chooses `repeat` or `stretch`, logical `tileWidth`/`tileHeight`,
`offsetX`/`offsetY`, and `rotation` in degrees. Paint views share their owner's
pixels and lifetime. Sharing is supported within the owner's Pibbl tree. Disposal
releases the canvas and queued work; later sends are inert, and rendering a
disposed resource is an error. Owners must outlive consumers.

`TextureRecipe<Message>` is the opaque result of the recipe factory. Recreating
recipes with the same definition preserves the mounted resource. Changing the
definition requires a new keyed owner. Custom implementations receive changed
configuration through `update` and decide whether output needs regeneration.

## defineTexture

Creates the immutable recipe factory for a custom implementation.

## Texture

The typed resource handle accepted by fills and strokes.

## TextureContext

The owned raster and invalidation capabilities.

## TextureDefinition

The custom implementation lifecycle described above.

## TextureFrame

Pibbl-supplied time and delta in milliseconds.

## TextureOptions

Resource resolution and presentation palette.

## TexturePaint

An opaque resource-backed paint, optionally with per-use placement.

## TexturePlacement

Per-consumer repeat/stretch, tile size, offset, and rotation.

## TextureRecipe

A pure definition/configuration value consumed by the hook.

## useTexture

Owns one recipe instance at the current mounted hook slot.

## API details from source

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

### useTexture

Owns one persistent texture resource for the current mounted hook slot.

```ts
useTexture: <Message>(input: TextureRecipe<Message>, options?: TextureOptions) => Texture<Message>
```

Related API: [useTexture](/reference/types/texture-resources/#usetexture), [TextureRecipe](/reference/types/texture-resources/#texturerecipe), [TextureOptions](/reference/types/texture-resources/#textureoptions), [Texture](/reference/types/texture-resources/#texture).

#### Parameters

- **`input`** — Texture recipe to mount or update. See [TextureRecipe](/reference/types/texture-resources/#texturerecipe).

- **`options`** — Resolution and lifecycle options for the mounted texture. See
[TextureOptions](/reference/types/texture-resources/#textureoptions) .

#### Returns

A mount-owned texture handle for sending messages and creating paint placements. See
[Texture](/reference/types/texture-resources/#texture) .

#### See also

[TextureRecipe](/reference/types/texture-resources/#texturerecipe)

[TextureOptions](/reference/types/texture-resources/#textureoptions)

[Texture](/reference/types/texture-resources/#texture)

[View source — packages/core/src/lib/textures/texture.ts:565](/source/packages/core/src/lib/textures/texture-ts/#L565)

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

### defineTexture

Defines a pure recipe factory; resource allocation starts at useTexture.

```ts
defineTexture: <Config, State, Message = never>(definition: TextureDefinition<Config, State, Message>) => (config: Config) => TextureRecipe<Message>
```

Related API: [defineTexture](/reference/types/texture-resources/#definetexture), [TextureDefinition](/reference/types/texture-resources/#texturedefinition), [TextureRecipe](/reference/types/texture-resources/#texturerecipe).

#### Parameters

- **`definition`** — State creation, update, simulation, rasterization, and disposal callbacks.
See [TextureDefinition](/reference/types/texture-resources/#texturedefinition) .

#### Returns

A configuration-to-recipe factory; resources are allocated when a recipe is mounted.
See [TextureRecipe](/reference/types/texture-resources/#texturerecipe) .

#### See also

[TextureDefinition](/reference/types/texture-resources/#texturedefinition)

[TextureRecipe](/reference/types/texture-resources/#texturerecipe)

[View source — packages/core/src/lib/textures/texture.ts:179](/source/packages/core/src/lib/textures/texture-ts/#L179)

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

### Texture

A mount-owned texture handle that provides paint and accepts recipe messages.

```ts
interface Texture<Message = never> extends TexturePaint
```

Related API: [Texture](/reference/types/texture-resources/#texture), [TexturePaint](/reference/types/texture-resources/#texturepaint).

#### See also

[TexturePaint](/reference/types/texture-resources/#texturepaint)

[TexturePlacement](/reference/types/texture-resources/#textureplacement)

[useTexture](/reference/types/texture-resources/#usetexture)

[View source — packages/core/src/lib/textures/texture.ts:27](/source/packages/core/src/lib/textures/texture-ts/#L27)

#### Properties and methods

<span id="api-Texture-send"></span>
<details>
<summary>send</summary>


```ts
send: (message: Message) => void
```

Delivers a typed message to the mounted recipe instance. See Texture.

##### Parameters

- **`message`** — Message delivered to the texture definition's receive callback.

[View source — packages/core/src/lib/textures/texture.ts:32](/source/packages/core/src/lib/textures/texture-ts/#L32)

</details>

<span id="api-Texture-paint"></span>
<details>
<summary>paint</summary>


```ts
paint: (placement: TexturePlacement) => TexturePaint
```

Related API: [TexturePlacement](/reference/types/texture-resources/#textureplacement), [TexturePaint](/reference/types/texture-resources/#texturepaint).

Returns a paint view with the requested placement while retaining the same texture ownership.
See TexturePaint.

##### Parameters

- **`placement`** — Destination bounds and texture placement policy. See
[TexturePlacement](/reference/types/texture-resources/#textureplacement) .

##### Returns

A paint descriptor referencing this mounted texture. See [TexturePaint](/reference/types/texture-resources/#texturepaint).

[View source — packages/core/src/lib/textures/texture.ts:40](/source/packages/core/src/lib/textures/texture-ts/#L40)

</details>

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

### TexturePaint

Opaque paint value produced by a mounted texture owner.

```ts
interface TexturePaint
```

Related API: [TexturePaint](/reference/types/texture-resources/#texturepaint).

#### See also

[FillStyle](/reference/types/styles/#fillstyle)

[StrokeStyle](/reference/types/styles/#strokestyle)

[Texture](/reference/types/texture-resources/#texture)

[View source — packages/core/src/lib/textures/texture-protocol.ts:35](/source/packages/core/src/lib/textures/texture-protocol-ts/#L35)

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

### TextureRecipe

A reusable texture definition together with the options used to instantiate it.

```ts
interface TextureRecipe<Message = never>
```

Related API: [TextureRecipe](/reference/types/texture-resources/#texturerecipe).

#### See also

[defineTexture](/reference/types/texture-resources/#definetexture)

[useTexture](/reference/types/texture-resources/#usetexture)

[View source — packages/core/src/lib/textures/texture.ts:158](/source/packages/core/src/lib/textures/texture-ts/#L158)

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

### TextureDefinition

Lifecycle callbacks for creating, updating, painting, and disposing texture resources.

```ts
interface TextureDefinition<Config, State, Message = never>
```

Related API: [TextureDefinition](/reference/types/texture-resources/#texturedefinition).

#### See also

[TexturePlacement](/reference/types/texture-resources/#textureplacement)

[TextureContext](/reference/types/texture-resources/#texturecontext)

[TextureFrame](/reference/types/texture-resources/#textureframe)

[defineTexture](/reference/types/texture-resources/#definetexture)

[View source — packages/core/src/lib/textures/texture.ts:98](/source/packages/core/src/lib/textures/texture-ts/#L98)

#### Properties and methods

<span id="api-TextureDefinition-defaultPlacement"></span>
<details>
<summary>defaultPlacement (optional)</summary>


```ts
readonly defaultPlacement?: TexturePlacement | undefined
```

Related API: [TexturePlacement](/reference/types/texture-resources/#textureplacement).

Texture placement used when no paint-specific override is supplied. See
TexturePlacement.

[View source — packages/core/src/lib/textures/texture.ts:103](/source/packages/core/src/lib/textures/texture-ts/#L103)

</details>

<span id="api-TextureDefinition-create"></span>
<details>
<summary>create</summary>


```ts
create: (context: TextureContext, config: Readonly<Config>) => State
```

Related API: [TextureContext](/reference/types/texture-resources/#texturecontext).

Allocates state for a mounted texture recipe. See TextureDefinition.

##### Parameters

- **`context`** — Texture-owned drawing surface and scheduling services. See
[TextureContext](/reference/types/texture-resources/#texturecontext) .

- **`config`** — Initial recipe configuration.

##### Returns

State retained for this mounted texture lifetime.

[View source — packages/core/src/lib/textures/texture.ts:111](/source/packages/core/src/lib/textures/texture-ts/#L111)

</details>

<span id="api-TextureDefinition-update"></span>
<details>
<summary>update (optional)</summary>


```ts
update?: ((state: State, config: Readonly<Config>, context: TextureContext) => void) | undefined
```

Related API: [TextureContext](/reference/types/texture-resources/#texturecontext).

Updates existing state when the recipe configuration changes. See TextureDefinition.

##### Parameters

- **`state`** — State returned by create.

- **`config`** — Latest recipe configuration.

- **`context`** — Texture-owned drawing surface and scheduling services. See
[TextureContext](/reference/types/texture-resources/#texturecontext) .

[View source — packages/core/src/lib/textures/texture.ts:119](/source/packages/core/src/lib/textures/texture-ts/#L119)

</details>

<span id="api-TextureDefinition-receive"></span>
<details>
<summary>receive (optional)</summary>


```ts
receive?: ((state: State, message: Message, context: TextureContext) => void) | undefined
```

Related API: [TextureContext](/reference/types/texture-resources/#texturecontext).

Handles a typed application message for this recipe instance. See TextureDefinition.

##### Parameters

- **`state`** — State returned by create.

- **`message`** — Message sent through the mounted texture handle.

- **`context`** — Texture-owned drawing surface and scheduling services. See
[TextureContext](/reference/types/texture-resources/#texturecontext) .

[View source — packages/core/src/lib/textures/texture.ts:127](/source/packages/core/src/lib/textures/texture-ts/#L127)

</details>

<span id="api-TextureDefinition-advance"></span>
<details>
<summary>advance (optional)</summary>


```ts
advance?: ((state: State, frame: TextureFrame, context: TextureContext) => void) | undefined
```

Related API: [TextureFrame](/reference/types/texture-resources/#textureframe), [TextureContext](/reference/types/texture-resources/#texturecontext).

Advances simulation using the shared Pibbl frame timing. See TextureDefinition.

##### Parameters

- **`state`** — State returned by create.

- **`frame`** — Shared animation time and delta. See [TextureFrame](/reference/types/texture-resources/#textureframe).

- **`context`** — Texture-owned drawing surface and scheduling services. See
[TextureContext](/reference/types/texture-resources/#texturecontext) .

[View source — packages/core/src/lib/textures/texture.ts:135](/source/packages/core/src/lib/textures/texture-ts/#L135)

</details>

<span id="api-TextureDefinition-rasterize"></span>
<details>
<summary>rasterize</summary>


```ts
rasterize: (state: State, context: TextureContext) => void
```

Related API: [TextureContext](/reference/types/texture-resources/#texturecontext).

Draws current texture pixels into the owned offscreen surface. See TextureDefinition.

##### Parameters

- **`state`** — State returned by create.

- **`context`** — Texture-owned drawing surface and scheduling services. See
[TextureContext](/reference/types/texture-resources/#texturecontext) .

[View source — packages/core/src/lib/textures/texture.ts:142](/source/packages/core/src/lib/textures/texture-ts/#L142)

</details>

<span id="api-TextureDefinition-dispose"></span>
<details>
<summary>dispose (optional)</summary>


```ts
dispose?: ((state: State, context: TextureContext) => void) | undefined
```

Related API: [TextureContext](/reference/types/texture-resources/#texturecontext).

Releases state and resources when the mounted texture is disposed. See
TextureDefinition.

##### Parameters

- **`state`** — State returned by create.

- **`context`** — Texture-owned drawing surface and scheduling services. See
[TextureContext](/reference/types/texture-resources/#texturecontext) .

[View source — packages/core/src/lib/textures/texture.ts:150](/source/packages/core/src/lib/textures/texture-ts/#L150)

</details>

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

### TextureOptions

Resolution and runtime configuration for a mounted texture recipe.

```ts
interface TextureOptions
```

Related API: [TextureOptions](/reference/types/texture-resources/#textureoptions).

#### See also

[useTexture](/reference/types/texture-resources/#usetexture)

[View source — packages/core/src/lib/textures/texture.ts:47](/source/packages/core/src/lib/textures/texture-ts/#L47)

#### Properties and methods

<span id="api-TextureOptions-resolution"></span>
<details>
<summary>resolution (optional)</summary>


```ts
readonly resolution?: { readonly width: number; readonly height: number; } | undefined
```

Dimensions of the simulation or raster grid. See TextureOptions.

[View source — packages/core/src/lib/textures/texture.ts:49](/source/packages/core/src/lib/textures/texture-ts/#L49)

</details>

<span id="api-TextureOptions-palette"></span>
<details>
<summary>palette (optional)</summary>


```ts
readonly palette?: readonly string[] | undefined
```

Ordered colors used to present texture intensity. See TextureOptions.

[View source — packages/core/src/lib/textures/texture.ts:62](/source/packages/core/src/lib/textures/texture-ts/#L62)

</details>

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

### TexturePlacement

How a texture raster is positioned and scaled when used as paint.

```ts
interface TexturePlacement
```

Related API: [TexturePlacement](/reference/types/texture-resources/#textureplacement).

#### See also

[Texture](/reference/types/texture-resources/#texture)

[TextureDefinition](/reference/types/texture-resources/#texturedefinition)

[View source — packages/core/src/lib/textures/texture-protocol.ts:13](/source/packages/core/src/lib/textures/texture-protocol-ts/#L13)

#### Properties and methods

<span id="api-TexturePlacement-mode"></span>
<details>
<summary>mode (optional)</summary>


```ts
readonly mode?: "repeat" | "stretch" | undefined
```

Related API: [repeat](/reference/functions/repeat/).

Selects the supported mapping, placement, or result policy. See TexturePlacement.

[View source — packages/core/src/lib/textures/texture-protocol.ts:15](/source/packages/core/src/lib/textures/texture-protocol-ts/#L15)

</details>

<span id="api-TexturePlacement-tileWidth"></span>
<details>
<summary>tileWidth (optional)</summary>


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

Width of one texture tile in logical paint coordinates. See TexturePlacement.

[View source — packages/core/src/lib/textures/texture-protocol.ts:17](/source/packages/core/src/lib/textures/texture-protocol-ts/#L17)

</details>

<span id="api-TexturePlacement-tileHeight"></span>
<details>
<summary>tileHeight (optional)</summary>


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

Height of one texture tile in logical paint coordinates. See TexturePlacement.

[View source — packages/core/src/lib/textures/texture-protocol.ts:19](/source/packages/core/src/lib/textures/texture-protocol-ts/#L19)

</details>

<span id="api-TexturePlacement-offsetX"></span>
<details>
<summary>offsetX (optional)</summary>


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

Horizontal offset applied to the texture or shadow. See TexturePlacement.

[View source — packages/core/src/lib/textures/texture-protocol.ts:21](/source/packages/core/src/lib/textures/texture-protocol-ts/#L21)

</details>

<span id="api-TexturePlacement-offsetY"></span>
<details>
<summary>offsetY (optional)</summary>


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

Vertical offset applied to the texture or shadow. See TexturePlacement.

[View source — packages/core/src/lib/textures/texture-protocol.ts:23](/source/packages/core/src/lib/textures/texture-protocol-ts/#L23)

</details>

<span id="api-TexturePlacement-rotation"></span>
<details>
<summary>rotation (optional)</summary>


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

Rotation applied to the containing geometry. See TexturePlacement.

[View source — packages/core/src/lib/textures/texture-protocol.ts:25](/source/packages/core/src/lib/textures/texture-protocol-ts/#L25)

</details>

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

### TextureContext

Surface and invalidation facilities supplied to texture lifecycle callbacks.

```ts
interface TextureContext
```

Related API: [TextureContext](/reference/types/texture-resources/#texturecontext).

#### See also

[TextureDefinition](/reference/types/texture-resources/#texturedefinition)

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

#### Properties and methods

<span id="api-TextureContext-canvas"></span>
<details>
<summary>canvas</summary>


```ts
readonly canvas: OffscreenCanvas
```

Canvas surface associated with this resource or mount. See TextureContext.

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

</details>

<span id="api-TextureContext-palette"></span>
<details>
<summary>palette</summary>


```ts
readonly palette: readonly string[] | undefined
```

Ordered colors used to present texture intensity. See TextureContext.

[View source — packages/core/src/lib/textures/texture.ts:73](/source/packages/core/src/lib/textures/texture-ts/#L73)

</details>

<span id="api-TextureContext-invalidate"></span>
<details>
<summary>invalidate</summary>


```ts
invalidate: () => void
```

Marks the source pixels dirty and requests a Pibbl update.

[View source — packages/core/src/lib/textures/texture.ts:75](/source/packages/core/src/lib/textures/texture-ts/#L75)

</details>

<span id="api-TextureContext-requestFrame"></span>
<details>
<summary>requestFrame</summary>


```ts
requestFrame: () => void
```

Requests another Pibbl frame; implementations stop by not requesting again.

[View source — packages/core/src/lib/textures/texture.ts:77](/source/packages/core/src/lib/textures/texture-ts/#L77)

</details>

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

### TextureFrame

Shared logical time and elapsed milliseconds supplied while advancing a texture.

```ts
interface TextureFrame
```

Related API: [TextureFrame](/reference/types/texture-resources/#textureframe).

#### See also

[TextureDefinition](/reference/types/texture-resources/#texturedefinition)

[View source — packages/core/src/lib/textures/texture.ts:84](/source/packages/core/src/lib/textures/texture-ts/#L84)

#### Properties and methods

<span id="api-TextureFrame-delta"></span>
<details>
<summary>delta</summary>


```ts
readonly delta: number
```

Elapsed time since the preceding texture frame, in milliseconds. See TextureFrame.

[View source — packages/core/src/lib/textures/texture.ts:86](/source/packages/core/src/lib/textures/texture-ts/#L86)

</details>

<span id="api-TextureFrame-time"></span>
<details>
<summary>time</summary>


```ts
readonly time: number
```

Current shared logical time, in milliseconds. See TextureFrame.

[View source — packages/core/src/lib/textures/texture.ts:88](/source/packages/core/src/lib/textures/texture-ts/#L88)

</details>

## Implementation guidance for agents

Read the [Textures and reaction-diffusion companion](/agents/topics/textures/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Define and own a texture](/minimal-examples/lifecycle/texture/): Rasterize a small animated tile and send it a message from native HTML. [Plain source](/minimal/lifecycle/texture.tsx)
## Interactive examples

- [Plasma Globe](/examples/plasma-globe/) · [Full page](/experience/plasma-globe/)
- [Underwater scene](/examples/underwater/) · [Full page](/experience/underwater/)
- [Stirred Ink](/examples/stirred-ink/) · [Full page](/experience/stirred-ink/)
- [Rainy Window](/examples/rainy-window/) · [Full page](/experience/rainy-window/)
## Documentation version

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