# pibbl

```ts
import { pibbl, Rectangle } from "@pibbl/core";
```

`pibbl(canvas, root, config?)` mounts a [`PibblNode`](/reference/types/elements-components/#pibblnode) on a [`Canvas`](/reference/types/canvas-runtime/#canvas) host and
returns a stable [`PibblController`](/reference/types/canvas-runtime/#pibblcontroller). A later call for the same canvas queues the
latest root and returns the same controller. The first mount owns the surface
configuration; call `dispose()` when the mount is no longer needed.

```tsx
const canvas = document.querySelector("canvas")!;
const controller = pibbl(
  canvas,
  <Rectangle style={{ width: 160, height: 80, fill: "#2563eb" }} />,
);
// Later: controller.dispose();
```

The optional [`PibblConfig`](/reference/types/canvas-runtime/#pibblconfig) selects the surface policy. Fixed surfaces capture the initial canvas viewport; `{ viewport: "responsive" }`
uses the CSS content box. See the [Getting started guide](/guides/configure-jsx/).

## API details from source

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

Mounts or updates a canvas render component on a given HTMLCanvasElement.
The first mount captures the surface configuration; later calls update only
the root element until that controller is disposed.

```ts
pibbl: (canvas: HTMLCanvasElement, element: PibblNode, config?: PibblConfig) => PibblController
```

Related API: [pibbl](/reference/functions/pibbl/), [PibblNode](/reference/types/elements-components/#pibblnode), [PibblConfig](/reference/types/canvas-runtime/#pibblconfig), [PibblController](/reference/types/canvas-runtime/#pibblcontroller).

### Parameters

- **`canvas`** — The canvas to render on

- **`element`** — The Pibbl element to render

- **`config`** — The mount lifetime, logical viewport, fit, and pixel density. See
[PibblConfig](/reference/types/canvas-runtime/#pibblconfig) .

### Returns

The stable [PibblController](/reference/types/canvas-runtime/#pibblcontroller) for this canvas; dispose it to release the mount.

### See also

[PibblNode](/reference/types/elements-components/#pibblnode)

[PibblConfig](/reference/types/canvas-runtime/#pibblconfig)

[PibblController](/reference/types/canvas-runtime/#pibblcontroller)

[View source — packages/core/src/lib/pibbl.ts:22](/source/packages/core/src/lib/pibbl-ts/#L22)

## 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

- [Mount, update, and dispose](/minimal-examples/lifecycle/mount/): Own one Pibbl root for a canvas and replace its content without creating another controller. [Plain source](/minimal/lifecycle/mount.tsx)
## Documentation version

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