The page and its contract #

The repository ships the app's TypeScript and Preact components (web/) and the page that embeds it, site/index.html, with its assets (site/assets/: the Nunito font, under the SIL Open Font License, included as OFL-nunito.txt; the web app manifest; and the app icons, drawn by node site/make-icons.mjs) and its service worker, site/sw.js. site/build.sh puts them together (see deployment.md). The page owns layout and look; the app owns behavior. Any other page can embed the pet if it provides the mount point, config and styles below.

The shipped page #

site/index.html is a complete, standalone page: a pastel "toy" device with the LCD, meters and care buttons, a panel with chat, diary, shelf and settings tabs, and three short notes that explain the pet and list build details. It hosts the app, model, runtime and font together, with an optional external Cloudflare Web Analytics beacon configured at build time. It uses a rounded font, follows prefers-color-scheme for light and dark, and is laid out for phones first (one column below 860 px, tested at 360 px). The notes are readable without JavaScript.

The brain download/upgrade notice spans the app above both the device and tabs, directly below the page header on mobile. It remains visible when switching tabs, with an accent border and a full-width button on small phones. The viewport requests no touch zoom; touch-action: pan-x pan-y on the root allows scrolling while suppressing pinch and double-tap zoom. Browser or accessibility settings may override the viewport request. Text stays selectable outside the game pad; its buttons suppress selection and touch callouts.

The hatch form suggests a pet name once when first shown during a visit. Deleting it leaves the field empty, including through download progress and other re-renders; a nonempty name is still required to hatch. When loading fails, a retry button appears beside the egg's error. It starts the brain again without resetting the egg, suggested/edited name or saved pet.

It is a template: @PLACEHOLDERS@ in it are replaced when it is built. site/build.sh fills them from site/release.json; test/dev-site.sh uses the same build for local previews. The page must be served at a URL ending in / with sw.js beside it, because it registers the worker by that relative URL and the worker's scope is the page's directory.

test/dev-site.sh fills them for local previews and fails if any are left. node test/contract.mjs fails if the app starts using an element id or config key that the page or this document does not cover.

Loading #

<div id="pet-root"></div>
<script type="application/json" id="pet-config">
  {"runtime": "/pet/runtime/transformers-4.3.1",
   "models":  "/pet/models/",
   "modelId": "tokenling-v6",
   "size":    97276118,
   "news":    "Dreams, gentler sleep, and a teen voice with fewer catchphrases.",
   "features": [],
   "older":   [],
   "sw":      "sw.js",
   "icon":    "/pet/assets/icon-192.png"}
</script>
<script type="module" src="/pet/app/<version>/main.js"></script>

main.js and brain.js must be served together under the hashed app directory. The main bundle includes Preact, all components/controllers, the renderer and prompt helpers; it starts brain.js as a module worker relative to itself. site/build.sh hashes the emitted bundles and maps, including dependencies, so a build never mixes versions. Keep app, model and runtime on the same origin.

The app adds the class pet-js to <html> once it has booted. Use it to keep the interactive area hidden when JavaScript is off while leaving the explanatory content visible.

Host elements and component ids #

The host provides only pet-root (an empty mount element) and pet-config (the JSON block). Components in web/components/ create and update all the ids below; embedding pages must not duplicate their markup. The ids remain useful for browser tests, labels and accessibility. CSS must keep [hidden] { display: none } winning over grid/flex rules.

Care buttons are act-feed, act-play, act-bath, act-pat, act-clean, act-meds, act-lights; the streamed diary uses diary-draft. With ?debug=1 (or #debug) in the URL it also adds a debug tab after the last tab (tab-debug, panel-debug, debug-age); see docs/testing.md.

Tabs #

Tab buttons are role="tab" with ids tab-chat, tab-diary, tab-shelf, tab-care, each with aria-controls naming panel-chat, panel-diary, panel-shelf or panel-care (role="tabpanel"); all panels except the first start hidden. The app handles clicks, arrow keys, aria-selected, tabindex and showing and hiding the panels.

Classes the app emits #

The page styles these; the app only applies them. All art is drawn by the app (the canvas and <img class="px-icon"> data URLs), so no image files are needed.

The canvas should keep a 3:2 aspect ratio and use image-rendering: pixelated. chat-log should scroll (the app keeps it scrolled to the newest line) and be exposed to assistive technology as a live region. The page is responsible for keyboard focus styles on the canvas, buttons and inputs. During catch, the app sets the canvas's touch-action to none for dragging and restores the page's style when the game ends. The pad uses touch-action: none and disables text selection so holding a direction stays a game input.

Brain features #

A brain can be trained for something older brains cannot do. List the feature's name in the config (features, and in each older entry that has it). In components, use brainHas(name) to set disabled/class/title props, with data-needs="name" for inspection. While an older brain without that feature runs, the component disables those controls, gives them the class needs-brain and a "needs the new brain" title, and the upgrade dialog lists what the new brain adds (FEATURE_TEXT in web/app/config.ts). Care actions are gated by ACT_NEEDS in web/app/config.ts. No feature is gated yet.

Installing, offline use and alerts #

The page links assets/manifest.webmanifest (name, colors, icons; its start_url and scope are ../, the page's directory) and an Apple touch icon, so browsers can install it as an app. The app registers sw.js, which keeps the page, the app modules and the runtime files the brain loaded for offline use, and shows alerts. See pet-simulation.md for the behavior.

Isolation and headers #

The brain runs best with cross-origin isolation, which lets the WebAssembly backend use threads. Serve the page and everything under the app's base path with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Cross-origin resources need appropriate CORS or CORP permission. Keep the app, model and runtime same-origin. The optional analytics beacon uses a module script and CORS; it must not require weakening isolation. The remaining server requirements are in deployment.md.

Explaining it to visitors #

The shipped page explains that the pet's decisions come from its brain, that the pet and its brain are stored in the visitor's browser, that the first download is about 97 MB and that pet data stays in the browser. Keep that on any page that embeds the app, readable without JavaScript. When page analytics is configured, disclose its traffic/performance reporting separately; do not claim that no information is sent. The beacon receives no pet names, conversations, diaries or saves from the app. See deployment.md for the optional analytics setting and verification.