# API overview

Import Canvas components, signals, animation, events, layout, focus, and the
generic render-layer lifecycle from `@pibbl/core`. Optional official packages add
thin Three.js integration, Canvas particle effects, physics, and visualization:

```ts
import { Rectangle, Text, pibbl, defineRenderLayer } from "@pibbl/core";
import { defineThreeLayer } from "@pibbl/three";
import { Particles2D } from "@pibbl/core/particles";
import { PhysicsWorld2D } from "@pibbl/core/physics/2d";
import { Axis, LineSeries, LinearScale } from "@pibbl/core/viz";
```

Package source paths and `lib/*` paths are not supported.

## Authoring

Use automatic JSX with `@pibbl/core/jsx-runtime`, or use
[`createElement`](/reference/functions/create-element/) for the equivalent explicit
form. `Fragment` is the explicit fragment value; JSX shorthand is usually more
readable, while `Fragment` is useful when a fragment needs a key.

- [Components](/reference/components/absolute/) draw, compose, lay out, and add focus
  policy.
- [Functions](/reference/functions/pibbl/) mount scenes and define paths, animation,
  measurement, render layers, particles, and geometry.
- [Hooks](/reference/hooks/use-canvas-context/) own component state, lifecycle,
  interaction, paths, layout, playback, particles, and 2D physics handles.
- Type pages group the props, events, filters, layout, signals, animation, and
  package-specific contracts used by those values.

## External render layers and Three.js

[`defineRenderLayer`](/reference/functions/define-render-layer/) creates one
composited external-raster component with explicit create, update, resize,
render, interaction, and dispose callbacks.

`@pibbl/three` adds only
[`defineThreeLayer`](/reference/functions/define-three-layer/) and its
[Three integration types](/reference/types/three/). Applications use ordinary
`three` and `three/addons/*` APIs for scenes, cameras, geometry, materials,
lights, loaders, controls, animation mixers, post-processing, and exporters.
Pibbl owns the surrounding Canvas composition, scheduler, hit arbitration, focus,
and teardown; it does not mirror Three as Pibbl JSX components.

## Particle effects

`@pibbl/core/particles` adds
[`Particles2D`](/reference/components/particles-2d/),
[`useParticleSystem`](/reference/hooks/use-particle-system/),
[`defineParticleEffect2D`](/reference/functions/define-particle-effect-2d/), and the
direct [particle descriptor functions](/reference/functions/particle-descriptors/).
See the grouped [particle types](/reference/types/particles/) and
[particle effects guide](/guides/particle-effects/).

## Physics

`@pibbl/core/physics/2d` provides the Pibbl-scheduled 2D runtime, components, body
handles, commands, events, and queries. Pure geometry is available from
`@pibbl/core/physics/2d/geometry`.

There is no root `@pibbl/core/physics` barrel and no independent physics clock.

## Visualization

`@pibbl/core/viz` provides allocation-relative
[Scale providers](/reference/components/scale/), [`Axis`](/reference/components/axis/),
[`LineSeries`](/reference/components/line-series/),
[`PointSeries`](/reference/components/point-series/),
[`PlotSeries`](/reference/components/plot-series/),
[`ScaleAdjust`](/reference/components/scale-adjust/), and
[`useLinearScale`](/reference/hooks/use-scale/).

Compose inspection with [`HoverData`](/reference/components/hover-data/),
[`HoverCard`](/reference/components/hover-card/),
[`AnchoredLayout`](/reference/components/anchored-layout/),
[`defineSeries`](/reference/functions/define-series/),
[`closestPoint`](/reference/functions/closest-point/),
[`closestX`](/reference/functions/closest-x/),
[`interpolateX`](/reference/functions/interpolate-x/), and
[`linearInterpolation`](/reference/functions/linear-interpolation/). Plain snapshot
helpers [`nearestPoint`](/reference/functions/nearest-point/) and
[`nearestDomainValue`](/reference/functions/nearest-domain-value/) are also
available.

## Compiler entries

`@pibbl/core/jsx-runtime` exports `Fragment`, `jsx`, and `jsxs`; its local `JSX`
namespace exports `Element`, `ElementType`, `ElementChildrenAttribute`,
`IntrinsicAttributes`, `IntrinsicElements`, and `LibraryManagedAttributes`.
`Element` is the branded `PibblElement`; `ElementType` is a synchronous Pibbl
component; `ElementChildrenAttribute` names `children`; `IntrinsicAttributes`
admits a string or numeric `key`; `IntrinsicElements` is empty; and
`LibraryManagedAttributes` maps primitive values to their specified-style input.

`@pibbl/core/jsx-dev-runtime` exports `Fragment` and `jsxDEV` plus the same local
`JSX` namespace. `jsxDEV` carries development-only filename, line, and column
metadata for diagnostics. These compiler-facing constructors are not normal
application APIs: use JSX or `createElement`, never call them directly.

`@pibbl/core/types` preserves the explicit type-only package entry. Most authors
can import types from `@pibbl/core` beside the corresponding runtime values.

## A small scene

```tsx
function Poster() {
  return (
    <>
      <Rectangle
        style={{ left: 24, top: 24, width: 240, height: 100, fill: "#164e9b" }}
      />
      <Text
        style={{
          left: 48,
          top: 78,
          fill: "white",
          font: "600 28px sans-serif",
        }}
      >
        Hello, Pibbl
      </Text>
    </>
  );
}

pibbl(document.querySelector("canvas")!, <Poster />);
```

Start with the [Getting started guide](/guides/configure-jsx/). Add an
ordinary Three scene with [Use Three.js inside Pibbl](/guides/three-js/),
then explore the
[Three.js instancing example](/playground/#/examples/three/three-instancing).

## State machines and sprites

- [Machine functions](/reference/functions/machines/) and [useMachine](/reference/hooks/use-machine/) coordinate general application state and owned work.
- [playAnimation](/reference/functions/play-animation/) integrates optional state-owned playback.
- [Sprite](/reference/components/sprite/) and [sprite sheets](/reference/functions/sprite-sheets/) draw shared atlas frames.
- [Machine types](/reference/types/machines/) and [sprite types](/reference/types/sprites/) describe their public contracts.

## API details from source

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

### Fragment

Compiler-visible fragment value. The renderer handles its descriptor directly.

```ts
Fragment: (props: FragmentProps) => PibblNodeInput
```

Related API: [Fragment](/reference/overview/), [PibblNodeInput](/reference/types/elements-components/#pibblnodeinput).

#### Parameters

- **`props`** — Children and optional fragment identity. See `FragmentProps`.

#### Returns

The fragment's children, preserving their order. See [PibblNodeInput](/reference/types/elements-components/#pibblnodeinput).

#### See also

[PibblNodeInput](/reference/types/elements-components/#pibblnodeinput)

[View source — packages/core/src/lib/element/fragment.ts:15](/source/packages/core/src/lib/element/fragment-ts/#L15)

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

### jsx



```ts
jsx: <P>(type: PibblElementType<P>, props: P, key?: PibblKey) => PibblElement<P>
```

Related API: [jsx](/reference/overview/), [PibblElementType](/reference/types/elements-components/#pibblelementtype), [PibblKey](/reference/types/elements-components/#pibblkey), [PibblElement](/reference/types/elements-components/#pibblelement).

#### Parameters

- **`type`** — Pibbl component or fragment emitted by the JSX compiler. See [PibblElementType](/reference/types/elements-components/#pibblelementtype).

- **`props`** — Compiler-generated props, including children.

- **`key`** — Optional reconciliation key supplied separately by the compiler. See [PibblKey](/reference/types/elements-components/#pibblkey).

#### Returns

A branded Pibbl element descriptor. See [PibblElement](/reference/types/elements-components/#pibblelement).

#### See also

[PibblElementType](/reference/types/elements-components/#pibblelementtype)

[PibblKey](/reference/types/elements-components/#pibblkey)

[PibblElement](/reference/types/elements-components/#pibblelement)

[View source — packages/core/src/lib/element/jsx-runtime.ts:23](/source/packages/core/src/lib/element/jsx-runtime-ts/#L23)

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

### jsxs



```ts
jsxs: <P>(type: PibblElementType<P>, props: P, key?: PibblKey) => PibblElement<P>
```

Related API: [jsxs](/reference/overview/), [PibblElementType](/reference/types/elements-components/#pibblelementtype), [PibblKey](/reference/types/elements-components/#pibblkey), [PibblElement](/reference/types/elements-components/#pibblelement).

#### Parameters

- **`type`** — Pibbl component or fragment emitted by the JSX compiler. See [PibblElementType](/reference/types/elements-components/#pibblelementtype).

- **`props`** — Compiler-generated props, including the static child list.

- **`key`** — Optional reconciliation key. See [PibblKey](/reference/types/elements-components/#pibblkey).

#### Returns

A branded Pibbl element descriptor. See [PibblElement](/reference/types/elements-components/#pibblelement).

#### See also

[PibblElementType](/reference/types/elements-components/#pibblelementtype)

[PibblKey](/reference/types/elements-components/#pibblkey)

[PibblElement](/reference/types/elements-components/#pibblelement)

[View source — packages/core/src/lib/element/jsx-runtime.ts:43](/source/packages/core/src/lib/element/jsx-runtime-ts/#L43)

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

### JSX

Compiler-facing Pibbl JSX types; authored elements use the branded Pibbl element protocol.

```ts
JSX: any
```

Related API: [JSX](/reference/overview/).

#### See also

[PibblElement](/reference/types/elements-components/#pibblelement)

[PibblElementType](/reference/types/elements-components/#pibblelementtype)

[PibblKey](/reference/types/elements-components/#pibblkey)

[PibblPrimitiveComponent](/reference/types/elements-components/#pibblprimitivecomponent)

[PrimitiveInputOf](/reference/types/styles/#primitiveinputof)

[View source — packages/core/src/jsx-runtime.ts:20](/source/packages/core/src/jsx-runtime-ts/#L20)

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

### jsxDEV



```ts
jsxDEV: <P>(type: PibblElementType<P>, props: P, key: PibblKey | undefined, _isStaticChildren: boolean, source: PibblElementSource | undefined, _self: unknown) => PibblElement<P>
```

Related API: [jsxDEV](/reference/overview/), [PibblElementType](/reference/types/elements-components/#pibblelementtype), [PibblKey](/reference/types/elements-components/#pibblkey), [PibblElement](/reference/types/elements-components/#pibblelement).

#### Parameters

- **`type`** — Pibbl component or fragment emitted by the JSX compiler. See [PibblElementType](/reference/types/elements-components/#pibblelementtype).

- **`props`** — Compiler-generated props, including children.

- **`key`** — Reconciliation key, if present. See [PibblKey](/reference/types/elements-components/#pibblkey).

- **`_isStaticChildren`** — Compiler compatibility flag; not used by Pibbl.

- **`source`** — Development source location for diagnostics. See `PibblElementSource`.

- **`_self`** — Compiler compatibility receiver; not used by Pibbl.

#### Returns

A branded Pibbl element descriptor with development source metadata. See
[PibblElement](/reference/types/elements-components/#pibblelement) .

#### See also

[PibblElementType](/reference/types/elements-components/#pibblelementtype)

[PibblKey](/reference/types/elements-components/#pibblkey)

`PibblElementSource`

[PibblElement](/reference/types/elements-components/#pibblelement)

[View source — packages/core/src/lib/element/jsx-runtime.ts:62](/source/packages/core/src/lib/element/jsx-runtime-ts/#L62)

<span id="api-JSX-jsxDevRuntime"></span>

### JSX (jsxDevRuntime)

Compiler-facing Pibbl JSX types; authored elements use the branded Pibbl element protocol.

```ts
JSX: any
```

Related API: [JSX](/reference/overview/).

#### See also

[PibblElement](/reference/types/elements-components/#pibblelement)

[PibblElementType](/reference/types/elements-components/#pibblelementtype)

[PibblKey](/reference/types/elements-components/#pibblkey)

[PibblPrimitiveComponent](/reference/types/elements-components/#pibblprimitivecomponent)

[PrimitiveInputOf](/reference/types/styles/#primitiveinputof)

[View source — packages/core/src/jsx-dev-runtime.ts:20](/source/packages/core/src/jsx-dev-runtime-ts/#L20)

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

- [Automatic JSX runtime](/minimal-examples/compiler/production/): The production compiler emits jsx and jsxs calls for component values and fragments. [Plain source](/minimal/compiler/production.ts)
- [Development JSX runtime](/minimal-examples/compiler/development/): The development compiler emits jsxDEV calls with source-location metadata. [Plain source](/minimal/compiler/development.ts)
## Documentation version

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