# Guides

## Foundations

[Mounts, signals, sizing, and composition](/guides/foundations/) explains what Pibbl owns, how updates reach the canvas, and where HTML and external renderers stop participating in Canvas composition. Begin with [Start](/start/) if you have not mounted a scene.

## HTML integration recipes

[Add Pibbl to your site](/guides/add-to-your-site/) helps choose an ownership direction. The first complete recipe is a [native HTML button with a reaction-diffusion background](/guides/native-button/). It preserves native interaction and includes fallback and teardown.

## Advanced composition

[Text outlines and multi-path bending](/guides/text-geometry/) explains `@pibbl/text`, editable glyph outlines, and envelope mapping between multiple paths. Try the [Text gallery](/catalogs/text/) or its [full-page envelope playground](/experience/text-envelope/).

[Stirred Ink](/examples/stirred-ink/) connects 2D physics motion to a living texture through an explicit coordinate bridge. Its companion explains what to change and what the effect does not simulate.

The library below includes the existing public guides and multi-step tutorials. New plasma, image-reveal, and store-hero integration recipes remain unimplemented; their concepts are in the design kit roadmap.

## Guide library

- [Author without JSX](/guides/author-without-jsx/): Use createElement for the complete Pibbl authoring API without JSX syntax.
- [Understand components, props, and children](/guides/components-props-and-children/): Compose synchronous Pibbl components with clear props, recursive children, fragments, lists, and stable keys.
- [Compose and lay out scenes](/guides/compose-and-layout/): Arrange Canvas scenes with composition boundaries, declared-box layout, transforms, clips, and layers.
- [Configure JSX](/guides/configure-jsx/): Configure Pibbl's automatic JSX runtime in TypeScript, Vite, esbuild, Babel, and JavaScript.
- [Create custom components and primitives](/guides/custom-components-and-primitives/): Choose ordinary composites, direct Canvas painting, definePrimitive, or an external renderer layer.
- [Compose data visualizations](/guides/data-visualization/): Build allocated, signal-driven line plots with the official @pibbl/core/viz primitives.
- [Add focus and keyboard navigation](/guides/focus-and-keyboard/): Add logical focus, keyboard activation, and directional navigation while keeping Canvas as the native focus host.
- [Troubleshoot JSX](/guides/jsx-troubleshooting/): Diagnose compiler configuration, foreign-runtime, child, and style errors in Pibbl JSX projects.
- [Coordinate animations with machines](/guides/machine-animation/): Let state entry own playback and state exit cancel it while sprite frames remain ordinary signals.
- [Move, resize, and rotate components](/guides/manipulation/): Bind a writable box signal to explicit handles for drag, resize, rotation, snapping, and cancellation.
- [Migrate to one Pibbl package](/guides/package-migration/): Replace first-party feature packages with subpath imports from core.
- [Create particle effects](/guides/particle-effects/): Build deterministic Canvas celebrations with fixed-capacity particle components.
- [Compose and test 2D physics](/guides/physics-2d/): Build reusable local physics worlds, keep one pose owner, and verify them through public observations and a manual test clock.
- [Procedural textures](/guides/procedural-textures/): Create living ink, seeded materials, backgrounds, repeating fills, and artwork reveals.
- [Integrate with React](/guides/react-integration/): Keep React and Pibbl runtimes separate while mounting a Pibbl scene safely inside a React host.
- [Responsive local styles](/guides/responsive-styles/): Adapt a reusable component to its allocated width and height with typed local style rules.
- [Use signals and animation](/guides/signals-and-animation/): Drive signal-valued inputs, computed barriers, transitions, and component-owned animation through Pibbl's shared scheduler.
- [Draw and animate sprites](/guides/sprites/): Load grids or packed atlases, share image resources, and animate frame signals through normal playback.
- [Manage state and lifecycle](/guides/state-and-lifecycle/): Use signals, computed barriers, reactions, stable values, hook identity, and exact cleanup.
- [Coordinate work with state machines](/guides/state-machines/): Model events, context, loading flows, and cancelable work with signal-backed machine actors.
- [Style and draw](/guides/style-and-draw/): Use Pibbl's closed local style language for drawing, filters, shapes, and declared geometry.
- [Use Three.js inside Pibbl](/guides/three-js/): Mount an ordinary Three.js scene in Canvas paint order while Pibbl owns scheduling, composition, events, focus, and cleanup.

## Step-by-step tutorials

- [Create the Canvas scene](/guides/tutorials/diagram-editor/canvas-scene/)
- [Connect two nodes](/guides/tutorials/diagram-editor/connect-nodes/)
- [Drag nodes safely](/guides/tutorials/diagram-editor/dragging/)
- [Build the editor chrome](/guides/tutorials/diagram-editor/editor-chrome/)
- [Polish selection with filters](/guides/tutorials/diagram-editor/filters/)
- [Finish and harden the editor](/guides/tutorials/diagram-editor/finished-editor/)
- [Draw the first node](/guides/tutorials/diagram-editor/first-node/)
- [Learn the basics: Build a diagram editor](/guides/tutorials/diagram-editor/)
- [Add keyboard interaction](/guides/tutorials/diagram-editor/keyboard-interaction/)
- [Pan and zoom the workspace](/guides/tutorials/diagram-editor/pan-and-zoom/)
- [Extract a reusable node component](/guides/tutorials/diagram-editor/reusable-node/)
- [Select nodes with state](/guides/tutorials/diagram-editor/selection/)
- [Constrain the viewport](/guides/tutorials/diagram-editor/viewport-and-layer/)
## Documentation version

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