# Foundations

## One mount, one owner

Call `pibbl` after the canvas exists. Keep the controller in the host's lifecycle and call `dispose()` before removing its surface. Hook-owned resources such as textures are released with their components. Application listeners, observers, and external resources also need explicit owners.

## Signals and scheduling

Signals are synchronous values. A component that reads `.get()` becomes a consumer; writes schedule the relevant Pibbl work. Declared signal-aware primitive inputs may receive signals directly. Writes are forbidden during component evaluation. Use events for user-driven writes and `useReaction` for an imperative response after a successful render.

Pibbl owns scheduling for rendering, textures, animation, and physics. The button recipe never starts `requestAnimationFrame`. Keep one mounted identity through hover and focus changes.

## Logical size and pixels

A fixed viewport uses logical coordinates independently of its displayed size. A responsive viewport makes one logical unit equal one CSS content-box pixel. Read `useLayoutBox()` inside a component when drawing must fill the current allocation. CSS owns the outer canvas dimensions; backing pixel density is separate.

Texture resolution controls simulation/raster cost. Stretching a small simulation into a larger display is an intentional tradeoff. Do not resize the simulation for every minor CSS change by default.

## Composition boundaries

Source order is Canvas paint order. `Group` applies transforms and styles, `Clip` limits paint, and `Layer` is an explicit retained bitmap boundary. Filters capture a receiving primitive and descendants; they change pixels but not layout, hit geometry, or focus bounds.

Native HTML is not Canvas paint. In an HTML application, position a decorative canvas behind native content with CSS. In a Pibbl-centered application, [HtmlBox](/reference/html-box/) requires an explicit overlay and stays above Canvas paint. Neither path captures live DOM into a texture.

`defineRenderLayer` flattens one external renderer into one bitmap boundary. The official `@pibbl/three` adapter uses ordinary Three scenes and application-owned resources. Canvas primitives cannot be interleaved between individual Three objects.

## Try the boundaries

The [button recipe](/guides/native-button/) demonstrates HTML ownership and signal-driven texture messages. [Stirred Ink](/examples/stirred-ink/) demonstrates an explicit bridge between physics and texture coordinates. Start with these complete sources before combining more systems.

## Documentation version

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