Start

Read as Markdown

Choose Build with Pibbl for a Canvas-centered application or Add Pibbl to your site for a bounded effect in an HTML application.

Build with Pibbl

In a browser application with a module bundler, install the runtime:

npm install @pibbl/core

Match the installed package to the documentation version at the bottom of this page. This local preview documents the checkout, not a verified published release. For an exact local package, run corepack [email protected] --filter @pibbl/core build and corepack [email protected] --filter @pibbl/core pack --pack-destination /tmp/pibbl-pack, then install the resulting tarball in your application.

Add a host canvas and load your application module through your bundler:

<canvas id="scene" width="320" height="200" aria-label="A teal circle"></canvas>
<script type="module" src="/src/main.js"></script>

import { pibbl, createElement, Circle } from "@pibbl/core";

const canvas = document.querySelector("#scene");
const controller = pibbl(
  canvas,
  createElement(Circle, {
    style: { cx: 160, cy: 100, radius: 60, fill: "#267d7c" },
  }),
);

// Call when the owning route or component is removed:
// controller.dispose();

The result is a teal circle centered in a 320 by 200 logical surface. Inspect Circle or edit the working circle example.

Prefer JSX?

Configure your compiler with jsx: "react-jsx" and jsxImportSource: "@pibbl/core". A .tsx file may then pass <Circle style={{ cx: 160, cy: 100, radius: 60, fill: '#267d7c' }} /> to pibbl. React is not required. Keep Pibbl JSX compilation separate from your host framework’s JSX; plain createElement is useful at that boundary.

Add Pibbl to your site

HTML can continue to own navigation, text, forms, and accessibility. Place a decorative canvas behind one control and pass native state to Pibbl. Begin with the complete native-button recipe.

Browser and ownership basics

Mount only in a browser after the canvas exists. One live mount owns each canvas; keep the returned controller and dispose it before removing its host. Pibbl schedules updates. Do not add another animation loop for these examples.

The first scene uses Canvas 2D. The texture recipe also requires the browser capabilities used by Pibbl’s texture renderer, including WebAssembly and offscreen surfaces. Native HTML must remain usable if the enhancement cannot start. Foundations explains sizing, signals, and composition boundaries.

Continue learning

1. Configure JSX or author without JSX.
2. Write components, props, and children.
3. Manage state and lifecycle.
4. Draw and style, then compose and lay out scenes.
5. Animate signals or integrate with React when your application needs that boundary.

For agent-led implementation, use the agent reading workflow and choose one detailed topic before editing. Exact prop/type contracts are in the reference; complete compositions are in Examples.

Documentation version

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