API overview

Read as Markdown

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:

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 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 draw, compose, lay out, and add focus policy.
Functions mount scenes and define paths, animation, measurement, render layers, particles, and geometry.
Hooks 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 creates one composited external-raster component with explicit create, update, resize, render, interaction, and dispose callbacks.

@pibbl/three adds only defineThreeLayer and its Three integration types. 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, useParticleSystem, defineParticleEffect2D, and the direct particle descriptor functions. See the grouped particle types and particle effects guide.

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, Axis, LineSeries, PointSeries, PlotSeries, ScaleAdjust, and useLinearScale.

Compose inspection with HoverData, HoverCard, AnchoredLayout, defineSeries, closestPoint, closestX, interpolateX, and linearInterpolation. Plain snapshot helpers nearestPoint and nearestDomainValue 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

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. Add an ordinary Three scene with Use Three.js inside Pibbl, then explore the Three.js instancing example.

State machines and sprites

Machine functions and useMachine coordinate general application state and owned work.
playAnimation integrates optional state-owned playback.
Sprite and sprite sheets draw shared atlas frames.
Machine types and sprite types describe their public contracts.

API details from source

Fragment

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

Fragment: (props: FragmentProps) => PibblNodeInput

Related API: Fragment, PibblNodeInput.

Parameters

props — Children and optional fragment identity. See FragmentProps.

Returns

The fragment’s children, preserving their order. See PibblNodeInput.

jsx

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

Related API: jsx, PibblElementType, PibblKey, PibblElement.

Parameters

type — Pibbl component or fragment emitted by the JSX compiler. See PibblElementType.
props — Compiler-generated props, including children.
key — Optional reconciliation key supplied separately by the compiler. See PibblKey.

Returns

A branded Pibbl element descriptor. See PibblElement.

jsxs

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

Related API: jsxs, PibblElementType, PibblKey, PibblElement.

Parameters

type — Pibbl component or fragment emitted by the JSX compiler. See PibblElementType.
props — Compiler-generated props, including the static child list.
key — Optional reconciliation key. See PibblKey.

Returns

A branded Pibbl element descriptor. See PibblElement.

JSX

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

JSX: any

Related API: JSX.

jsxDEV

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

Related API: jsxDEV, PibblElementType, PibblKey, PibblElement.

Parameters

type — Pibbl component or fragment emitted by the JSX compiler. See PibblElementType.
props — Compiler-generated props, including children.
key — Reconciliation key, if present. See 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 .

JSX (jsxDevRuntime)

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

JSX: any

Related API: JSX.

Implementation guidance for agents

Read the Authoring, signals, and lifecycle companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Automatic JSX runtime: The production compiler emits jsx and jsxs calls for component values and fragments. Plain source
Development JSX runtime: The development compiler emits jsxDEV calls with source-location metadata. Plain source

Documentation version

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

API overview

Authoring

External render layers and Three.js

Particle effects

Physics

Visualization

Compiler entries

A small scene

State machines and sprites

API details from source

Fragment

Parameters

Returns

See also

jsx

Parameters

Returns

See also

jsxs

Parameters

Returns

See also

JSX

See also

jsxDEV

Parameters

Returns

See also

JSX (jsxDevRuntime)

See also

Implementation guidance for agents

Complete minimal examples

Documentation version