Hatch, connect, and ship with control.

01 · INSTALL

Add the published runtime to your host page.

This guide takes developers through a complete website integration. Install the exact 0.1.0 release so your code, examples, and diagnostics share one contract. The self-contained browser runtime runs directly in the host page.

npm install @peekling/runtime@0.1.0

02 · HATCH WITH ESM

Own one instance from start to finish.

Emit the required stylesheet through your bundler, create the instance, await readiness, and destroy it when the owning view ends. Keeping those four steps together makes startup failure and cleanup predictable.

import { hatch } from "@peekling/runtime"
import peeklingStyles from "@peekling/runtime/peekling.css?url"

let peek

try {
  peek = hatch({
    character: "peek",
    styles: { url: peeklingStyles }
  })

  await peek.ready
} catch (error) {
  console.error("Peekling startup failed", error)
}

export function unmountPeekling() {
  peek?.destroy()
}

character: "peek" resolves the exact published Peek Pack. It fetches a pinned manifest and one suitable atlas, then verifies both before rendering. Use packUrl when every character asset must stay on an origin you control.

03 · BROWSER AND HTML

Use the same engine in plain HTML.

The complete browser file exposes Peekling.hatch and registers <peekling-character> when those names are free. The standard CDN layout also discovers the sibling stylesheet and checks its released integrity value.

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.0/dist/peekling.min.js"
  integrity="sha384-iJtnL5uLVg+cNs8qk9f4hwjOyplSaORCqdss7xunkEfv9w1j5rUCkFqBcK1WslGW"
  crossorigin="anonymous"
></script>

<peekling-character character="peek"></peekling-character>

ESM applications keep browser globals and custom-element registration under application control. Call definePeeklingElement() to enable the declarative facade. Connection hatches one instance. Disconnection destroys it.

04 · CONFIGURATION

Choose a Pack, then describe the page.

Configuration belongs to the host application. The Pack supplies art, States, Capabilities, timing, and license data. The Plan says how that character may respond on this page.

const peek = hatch({
  character: "peek",
  styles: { url: peeklingStyles },
  position: "bottom-right",
  scale: 2,
  plan: {
    baseline: {
      channels: ["state"],
      state: { state: "idle" }
    },
    rules: [
      {
        id: "follow-pointer",
        when: { source: "browser", event: "pointer.move" },
        effect: {
          channels: ["motion", "state"],
          motion: {
            type: "follow-pointer",
            speed: 160,
            arrivalRadius: 24
          },
          state: { capability: "locomotion" }
        }
      },
      {
        id: "show-saved",
        when: { source: "application", event: "app.saved" },
        effect: {
          channels: ["state"],
          state: { state: "success" },
          until: { type: "duration", ms: 900 }
        }
      }
    ]
  }
})

character

A registered exact-version alias such as peek.

packUrl

An explicit immutable manifest URL, ideal for self-hosting.

pack

Inline validated Native or normalized Pack data.

position

bottom-left, bottom-right, center, or bounded CSS-pixel coordinates.

scale

An integer from 1 through 4. The Pack default applies when omitted.

05 · EVENTS AND OVERRIDES

Report facts. Borrow control briefly.

An Event is an immutable fact admitted through the same bounded queue as browser observations. An Override temporarily owns declared presentation channels, then releases them back to the unchanged Plan.

await peek.ready

const result = peek.emit("app.saved", {
  documentId: "draft-42"
})

if (!result.accepted) {
  console.warn(result.reason)
}

const greeting = peek.override({
  effect: {
    channels: ["state"],
    state: { state: "happy" }
  },
  until: { type: "duration", ms: 1200 }
})

console.log(await greeting.finished)

The queue holds 32 Events and rejects a new Event when full. Up to eight disjoint Overrides may be active. Overlapping Overrides reject unless the caller explicitly requests mode: "replace".

06 · LIFECYCLE

Make teardown as deliberate as hatch.

ready

Rejects if Pack, stylesheet, reference, integrity, or browser resource setup fails. Await it before relying on Pack-specific behavior.

finished

Always settles after cleanup with destroyed, pagehide, or failed.

pause() / resume()

Add and remove the host pause reason. Work resumes only after every suspension reason clears.

destroy()

Terminal and idempotent. It releases listeners, observers, timers, frames, roots, adapters, fetches, and object URLs owned by the instance.

Full navigation ends an instance through pagehide. For a client-side route change, destroy a direct hatch when its owning view unmounts. A disconnected Web Component performs that cleanup itself.

07 · SECURITY AND HOSTING

Allow four declared resources.

Peekling runs locally in the host page. Packs stay within a validated data and image schema that declares assets, frames, States, timing, movement mappings, licenses, and hashes. The host application owns its services and analytics.

• Peekling works with a strict CSP that keeps unsafe-inline and unsafe-eval disabled.
• Cross-origin modules and scripts using SRI need CORS. Peekling also needs CORS when it reads external styles or fetches manifests and atlases.
• Exact-version assets should use immutable caching. Byte changes require a new URL.
• Self-hosting is the clearest option for strict origin allowlists.

08 · VALIDATE AND DIAGNOSE

Catch authoring errors before the browser does.

Doctor validates bounded JSON Configuration, Plan data, and an optional Pack directly from the files and command-line values you provide. Its static checks cover accepted fields, limits, paths, and Pack references.

npm install --save-dev @peekling/cli@0.1.0

npx peekling doctor ./peekling.json \
  --pack ./character.json \
  --base-url https://example.com/app/ \
  --json

The production browser file uses compact stable diagnostic codes. Load the adjacent readable peekling.js while debugging, or run Doctor and @peekling/preflight for field paths and suggested fixes.

09 · PUBLIC REFERENCES

Go from guide to contract.

• Configuration, Plans, Events, Effects, and Overrides
• Execution ordering and lifecycle
• Browser compatibility, CSP, CORS, and hosting
• Troubleshooting by failure boundary
• Published runtime package