Find the contract behind every behavior.

01 · RELEASE BOUNDARY

This map describes published 0.1.0.

The public contract is the exact npm release built from the annotated v0.1.0 source tag. Package exports, schema, declarations, runtime behavior, and release evidence must agree before a field can be described as part of that version.

02 · PUBLIC SURFACES

One runtime, three ways in.

hatch()

Named ESM export. Returns one owned instance with ready, finished, emit, override, pause, resume, and destroy.

Peekling.hatch()

The same creation contract in the complete browser file.

<peekling-character>

A lifecycle facade. Connection hatches and disconnection destroys.

The ESM root also exports site visibility helpers and explicit Web Component registration. Supported package subpaths are ., ./pack, ./preflight, ./browser, and ./peekling.css. These exports and subpaths define the complete public API.

03 · CONFIGURATION CONTRACT

Closed objects keep the boundary legible.

Serializable Configuration uses closed JSON objects. Static schema checks establish shape and lexical limits. Shared semantic validation then checks URLs, references, channel ownership, Pack Capabilities, and selected States.

Pack source

At least one of character, packUrl, or pack. Runtime precedence is inline Pack, explicit manifest, then registered alias.

Render bounds

scale is an integer from 1 through 4. density and maxDensity accept 1, 2, or 4.

Position

bottom-left, bottom-right, center, or finite coordinates from -100000 through 100000.

URLs

Same-origin relative paths or canonical, credential-free absolute HTTPS URLs with valid authority data.

JavaScript-only seams

Host mounts, loggers, diagnostic callbacks, and injected browser objects live on the runtime Configuration object. Pack and Plan remain serialized data.

A Native format-1 Pack is data only. It declares identity, SPDX license, metadata, PNG atlas candidates, States, optional Capabilities, timing, and hashes. Every Pack includes idle. Its closed schema contains character data, while the host owns Rules, callbacks, rendered HTML, and application services.

04 · PLAN CONTRACT

Immutable policy, bounded runtime state.

Plan

One baseline plus at most 64 declaration-ordered Rules.

Browser Events

pointer.click, pointer.move, document.visibility, window.focus, window.scroll, section.visibility, and page.lifecycle.

Channels

motion, state, and named surface:<id> channels. Each Effect lists every channel it owns.

Motion

Published 0.1.0 supports only follow-pointer. Speed is 1 through 1000, with a default of 160. Arrival radius is 0 through 1000.

Disposition

A competing named surface explicitly chooses update, replace, ignore, or interrupt.

Application Events use a 32-item FIFO queue. Payloads are immutable JSON-like own data up to 8 KiB, with bounded depth, strings, collections, and value count. A full queue preserves every accepted Event and returns a rejection for the incoming Event.

An Override uses the same Effect model and leaves the immutable Plan intact. It owns declared channels for its lifetime. The runtime permits at most eight active disjoint Overrides. Every lifetime has a one-hour ceiling or an earlier explicit release.

05 · RESOURCE AND SECURITY CONTRACT

Every fetched byte keeps a named boundary.

• Manifest and atlas requests have a 30-second deadline.
• Fetched Native manifests are limited to 64 KiB and Native atlas input to 4 MiB.
• Atlas dimensions are capped at 4096 by 4096 pixels.
• Every atlas candidate requires a lowercase SHA-256 declaration.
• Strict CSP uses external styles, registered event listeners, and static execution.
• The upstream runtime is telemetry-free and connectionless.

SRI, CSP, pinned URLs, CORS, and origin allowlists provide complementary layers of defense. Pair them with source provenance checks and provider review. Cross-origin assets also depend on correct browser policy and provider availability.

06 · LIFECYCLE AND ACCESSIBILITY

Park cleanly. Finish once.

• ready resolves after Pack, stylesheet, Plan, first State, and owned DOM are usable.
• finished always settles once after terminal cleanup.
• Host pause, hidden documents, and site dismissal compose as suspension reasons. Resume happens after the final reason clears.
• Reduced motion suppresses movement and renders a validated static tableau.
• pagehide ends the instance. SPA route changes require host teardown or Web Component disconnection.
• The sprite is pointer-transparent and aria-hidden. Accessible content uses a separate surface, while focus stays where the visitor placed it.

Closed Shadow DOM provides presentation encapsulation. Validation, trusted host code, and browser security policy provide the security boundary. Host-rendered mount failures stay contained to the affected surface where browser behavior permits.

07 · RELEASE EVIDENCE

Measured promises stay bounded.

The canonical release measurement combines the complete production browser file and required stylesheet. Under Node 22.14.0, npm 11.16.0, and Node zlib defaults, release 0.1.0 records 32,287 bytes gzip and 28,635 bytes Brotli. Both formats have a 32 KiB cap and a required 256-byte reserve.

Release browser coverage targets current evergreen Chromium, Firefox, and WebKit under the documented matrices. That evidence applies to the exact source, artifacts, browsers, machines, and scenarios tested. Each new host page, device, extension, and callback receives its own integration checks.

08 · CANONICAL PUBLIC REFERENCES

Follow the authority for the question.

• Versioned v0.1.0 engine source
• Serializable Configuration JSON Schema
• JavaScript-only extension reference
• Configuration and integration guide
• Execution and lifecycle contract
• Compatibility and hosting contract
• Published npm package
• Published jsDelivr browser artifact