Curious? Ask away.

Peekling is an open-source browser runtime for small, interactive animated characters. It gives a character a safe place to move, rest, react, and share bounded controls without taking over the page around it.

The runtime combines a data-only character Pack with one validated Plan. The Pack describes what the character can render. The Plan describes how the character responds to browser or application Events.

Peek is the first Peekling, a curious kitten and fox character with bright eyes, a paw-print bandana, and a gold-tipped tail. Peek is the starter character resolved by Peekling.hatch("peek").

Peek is one character in a wider world. Other Peeklings can have a different appearance, personality, animation, and way of moving. Visit the Peektionary for the official vocabulary.

A Peekling is its own character type. It accompanies people without asking to be fed, trained, or constantly attended to. Its job can be as simple as quietly existing beside the page.

A host can connect a Peekling to assistant replies, notifications, music, games, or other product moments. Those features belong to the host application. Peekling provides the bounded character response and presentation. The fuller idea lives in the Peekling philosophy.

A Peekling can render named States, move through supported motion effects, react to typed Events, and present safe host-owned controls in a bounded bubble. The exact result comes from the selected Pack and Plan.

The live demos include pointer following, autonomous routes, an install tour, a music player, an edit review, progress, a timer, and a game. Each example uses the same runtime instead of a separate animation mock.

The current runtime lives in modern web pages, including sites, documentation, dashboards, and browser-based applications. Any stack that serves JavaScript can use the browser API.

Desktop and browser-extension homes are in development. They will build on the same validated Pack and Plan model when their permissions, updates, accessibility, and release paths are ready.

The simplest browser setup is two HTML lines. Load an exact version of the browser bundle, then add a <peekling-character> element. The landing page keeps a copy-ready example in the install section.

Programmatic hosts can call Peekling.hatch(...). ESM users import hatch. Both paths create the same owned instance and use the same Configuration contract.

Plain HTML is enough. React, Vue, Svelte, Rails, Laravel, Django, and other stacks can all use the same browser API. A framework wrapper is an optional lifecycle convenience, not a second runtime.

The developer guide shows the browser bundle, ESM, Web Component, and teardown paths.

Use npm when the runtime belongs in an application build. Use a version-pinned CDN URL for a small plain HTML page. Self-host the browser file and Pack assets when your security, availability, or caching policy requires it.

Keep the version exact in every path. A pinned release makes the code, Pack contract, and support evidence inspectable instead of changing underneath a deployment.

Pass a registered character name such as peek, or provide an explicit validated Pack manifest URL. Configuration can place the character at a supported viewport preset or bounded pixel coordinates.

Character choice, render scale, source density policy, and starting position are presentation choices. They do not rewrite the Pack or Plan.

The owned instance exposes lifecycle methods for pause, resume, and destroy. Destroy removes observers, scheduled work, rendering, and owned surfaces. A Web Component owns that lifecycle automatically while it is connected.

Replace a character by destroying the old instance before hatching the next one. The website follows this rule so a character selection never creates duplicate hosts.

A Plan is the immutable decision model validated when a Peekling hatches. It contains a baseline and ordered Rules. Each Rule connects an approved Event condition to a channel-scoped Effect such as character State, motion, or surface data.

Simple and advanced use cases use the same model. A pointer follower is a small Plan. A host-driven music player uses more Events and presentation channels, but it does not introduce a second behavior engine.

A Plan is plain JSON with a small versioned schema. It has no expressions, scripts, hidden callbacks, or executable Pack logic. Most integrations start by copying a working example and changing a State, Event name, speed, or duration.

Validation reports unsupported fields and missing Pack capabilities before the character starts. The playground exposes the authoritative JSON beside live controls.

Yes, when the pinned runtime version and Plan support that motion. The website demonstrates bounded pointer following, bottom-edge patrol, viewport traversal, a custom SVG path, scroll reactions, and direct placement.

Motion is explicit. A pointer Plan can set speed and a stop radius. A route Plan describes its own bounded path. Scrolling can suspend pointer pursuit and select a falling or rising State before pointer movement resumes.

Yes. A configured content surface can hold host-owned buttons, status, text, progress, or other bounded UI. The host application still owns the music, timer, document, game, or business logic. It emits a named result when the character should react.

The surface is mounted inside an engine-owned boundary. Hosts receive an explicit mount instead of passing HTML strings into a parser. See the live music, edit review, progress, timer, and game examples in Demos.

Compatible runtime versions can enable one bounded direct character control for click, drag, and throw behavior. A click can toggle the owned bubble or emit a configured application Event. Dragging and throwing stay inside the runtime's viewport and lifecycle boundaries.

Direct manipulation is explicit Configuration. The normal visual layer remains passive, and the runtime does not cancel the page's scrolling, selection, context menu, or event propagation.

The DOM atlas renderer is the default. The current development line also provides an optional Canvas 2D renderer entry point for the character layer.

Canvas changes drawing, not the product model. Pack validation, Plan compilation, Events, physics, content, accessibility controls, and lifecycle remain shared. Plans and Packs do not need a Canvas-specific dialect.

A Pack is a folder containing a validated character.json manifest, one or more dense PNG atlases, and license information. The manifest names the character, States, timing, assets, and capabilities.

Packs describe what can be rendered. The host Plan decides when those capabilities are selected.

Native Packs are data and artwork only. They cannot carry scripts, callbacks, formulas, network hooks, or arbitrary HTML. The runtime validates manifest structure, state references, atlas geometry, timing, and declared motion data before rendering.

Product behavior remains in trusted host code. This keeps a downloadable character from gaining application privileges simply because its art was selected.

Yes. Start with original or properly licensed artwork, author named animation rows or frame folders, and let the Pack compiler produce the dense runtime atlas. Validate the result before hosting or publishing it.

The artist guide explains logical cells, direction mappings, timing, density variants, provenance, and quality checks.

A State points to explicit packed frame IDs and timing. Render scale controls the character's logical size. Source density controls how many source pixels are available for that logical frame. They are separate choices.

The loader selects one suitable declared atlas for device pixel ratio, render scale, host limits, and save-data policy. It does not fetch every density. A failed higher density can fall back to a validated lower one without changing character State or position.

Each Pack must carry its own license and provenance. The engine's Apache-2.0 license does not automatically grant rights to character artwork, names, logos, or other brand assets.

Read the license beside the exact Pack you want to use. Keep required attribution and notices, and publish only artwork you created or have permission to redistribute. The website Terms explain the same boundary for site source and official brand materials.

The runtime has no product telemetry, account, or required backend. A host chooses which approved browser observations and application Events enter its Plan. Runtime state stays bounded to the browser instance.

The public website stores functional preferences locally and uses Cloudflare for delivery plus GitHub's public API for the live star count. PostHog measures visits and site usability. The Privacy Policy lists those requests and retention practices.

The default visual renderer is pointer-transparent and isolated from page styles. Observers use passive listeners where appropriate, avoid focus capture, and never call preventDefault() or stop propagation.

When a host enables direct character interaction, one bounded control receives only that explicit input. Destroy removes the runtime's observers, rendering, scheduled work, and owned surfaces.

Yes. The shared rest control offers bounded temporary and site-local choices without an account or backend. Keyboard users and host API controls reach the same preference.

A site should also expose a normal Show again action. The visitor preference suspends live instances while the host remains responsible for their lifecycle.

Reduced motion selects a stable Pack tableau instead of a second animation system. The page keeps meaningful state and controls while removing decorative or spatial motion.

Configured controls use normal keyboard and focus semantics. The visual character stays outside the reading order unless an explicit accessible interaction control is enabled. Host content remains responsible for clear labels, status, and focus order.

The engine and website source are available under Apache-2.0 in their repositories. You can inspect, build, and self-host them subject to the license and notice files shipped with each repository.

Character art and official brand materials can have separate terms. Check every Pack license before reuse. The Terms and repository licensing files are the controlling references for their scope.

Current work focuses on a polished 0.1.5 browser runtime, richer official Packs, Canvas rendering, direct character interaction, documentation, and the public demos. Desktop and browser-extension products remain in development.

Start with the contributor guide, then choose the relevant repository under github.com/peekling. A focused issue, documentation fix, Pack improvement, or reproducible bug report is a useful first contribution.