Foundations

Read as Markdown

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 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 demonstrates HTML ownership and signal-driven texture messages. 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 c321a83. ALPHA — NOT FOR PRODUCTION USE.