lilgotchi 0.0.0-stage → 3.0.2

package/dist/design/games/release-checklist.md

@@ -0,0 +1,52 @@
+# Games release checklist
+
+## Release order
+
+1. 1.2.1 fixes looking left and right in the guessing game. Keep its rules and rewards.
+2. 2.0 adds Get, Bump, Heading, Memory, Flag, Sprint and Hoops, alongside the guessing game.
+
+Taylor approved both releases on November 9, 2026. Merge the patch first, then release 2.0.
+
+## Review each game
+
+Check the instructions, controls, score, win, loss, quit and replay. Test the same timing with different frame sizes. Repeated input cannot score twice. A finished or abandoned run cannot change a later run.
+
+Look at all four families, from baby through elder. Direction changes must be visible. Keep the whole pet, ball, opponent and effects inside the display. Use the full current pet, with enough room for the game around it.
+
+Check touch and keyboard controls on mobile and desktop. Keep buttons large. Show sound cues visually. Check reduced motion, focus, spoken instructions and paused playback.
+
+## Shared behavior
+
+A new run charges energy once. A win gives at most one happiness heart. A loss or quit gives none. Keep the guessing game's existing rules in its patch.
+
+Closing the drawer or hiding the page pauses a new game. Returning offers Resume or Quit. Changing family, death or Vacation cancels it. Reloading does not restore unfinished games. No hidden timers, surprise losses or rewards after leaving.
+
+Eggs, sleeping, sick, dead, hungry and vacation pets follow the existing play restrictions. The picker explains why play is unavailable.
+
+## Evidence
+
+Each implementation PR needs passing tests and screenshots of its actual changed screens. Timing games also need a short browser recording. Run the full suite and build after integration. Check the built package includes every game module.
+
+Record remaining gaps honestly before calling 2.0 ready. The wider device catalog stays in the research backlog.
+
+## 2.0 review
+
+The integrated suite passes 233 tests. The build checks local imports and assets in the package. All 44 compact identities are tested across game scenes and both motion modes.
+
+Mobile browser checks exercised all seven games through start, controls, pause and return. Desktop review covered the picker, Bump, Memory and Sprint. The final Sprint screenshot includes lane labels and steady running feedback.
+
+Unverified checks: physical phone playtesting, human screen reader and sound checks, longer balance sessions and short timing recordings. Browser control checks do not prove every game feels balanced on a real phone. Taylor approved release with these gaps recorded.
+
+## Followup checks
+
+Ran 3,000 seeded model sessions with delayed observations and limited input rates. These are simulated players, not human playtests. Uneven Sprint taps exposed a dropped input problem. One buffered tap fixes it without beating the steady running speed cap. Bump and Heading now offer a slower pace.
+
+Keyboard checks covered Tab, Shift Tab, arrow input, Escape, closing and reopening a paused round. Starting a game exposed a focus trap gap, now fixed and tested. Audio tests cover cue frequencies, duration, gain, mute, suspension, delayed notes and unavailable audio hardware.
+
+No physical phone was connected. Audio listening and a human screen reader session remain unverified. The browser tools do not expose video recording. The timing simulations and screenshots are not substitutes for those checks.
+
+## Game polish in review
+
+Check full pet art in the 32 by 24 game field, clear Flag waiting cues, Memory answer feedback and Hoops shots through the rim. Heading must contact the visible head rather than a generic box. Replay must start a fresh run and reward it only once.
+
+The model checks cover every current pet sprite in Heading, moving head collisions, Flag timing, paused Memory answers and Hoops rim crossings. Browser review of the integrated changes is still required. Do not treat model tests as a playtest.

package/dist/design/games/sprint.md

@@ -0,0 +1,21 @@
+# Sprint
+
+Included in 2.0. Follow the [shared game rules](README.md).
+
+The [Connection manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/) describes repeated button presses to race toward the finish.
+
+## Our version
+
+Race a computer opponent over a short course. Tap Run or press Space to advance. Cap accepted taps so rapid hardware repeats do not create an advantage. Choose Steady running before Start for an equally effective option. Its Run steadily button starts running and Stop running stops it.
+
+Start with a three second countdown. The course has 30 steps. Accept at most two steps per second in either mode. The opponent finishes 18 seconds after the countdown, or 20 seconds in slower mode. Reach the finish before the opponent to win. Show a countdown and ignore early input. Use a fixed opponent pace for the selected difficulty.
+
+## Screen and art
+
+Use the current pet in the upper lane and a distinct opponent in the lower lane. Put race progress below the display. Keep the screen still and move the runners, with a visible finish marker. Reduced motion uses fewer pose changes and no scrolling scenery.
+
+## Check it
+
+Test touch, keyboard and hold mode against the same finish threshold. Pause must stop both runners. Check ties explicitly and award a tied finish as a win. Never require uncomfortable tapping speed to finish.
+
+An early tap can queue one step at the next half second boundary. Extra taps cannot stack or beat steady running.

package/dist/docs/README.md

@@ -0,0 +1,14 @@
+# lilgotchi docs
+
+[Install it](install.md) on your website.
+
+[Meet the pets](characters.md) and see their full family trees.
+
+[Care for your pet](care.md), take a break or back up a save.
+
+[Work on the code](development.md) or [make new sprites](frame-contract.md).
+
+[Game guides](../design/games/README.md): controls, rules and the games still on our list.
+[Launcher plan](https://github.com/TaylorOD/lilgotchi/blob/main/design/launcher.md): bigger icons, the logo option and care counts.
+
+[Release notes](release-review.md) · [Credits](credits.md)

package/dist/docs/care.md

@@ -0,0 +1,51 @@
+# A little care goes a long way
+
+Choose a family and click Start pet when you’re ready. Opening the toggle or browsing families does not start a new pet. Eggs hatch in 90 seconds after you start them. Then it’s time for food, play and sleep.
+
+## The basics
+
+| Control | Use it for |
+| --- | --- |
+| Feed | Meals for hunger. Snacks help happiness, but don’t overdo them |
+| Play | Pick one of eight games to cheer your pet up |
+| Clean, Sleep or Wake | The third button changes with what your pet needs |
+| More care | Medicine, discipline, lights and detailed stats |
+| Settings | Help, Vacation, sound, backups and remembered pets |
+
+Use medicine when your pet is sick. It may need more than one dose. Discipline is for unnecessary calls or misbehavior.
+
+Turning the light off only darkens the screen. Sleep gives your pet a rest. The game also follows each character’s sleep schedule.
+
+## Games
+
+Choose Get, Bump, Heading, Memory, Flag, Sprint or Hoops alongside the guessing game. The [game guide](../design/games/README.md) covers the controls and goals.
+
+## Needs and growth
+
+Food and happiness show how satisfied your pet is. Sleep restores energy. Health summarizes wellbeing, but a full health meter doesn’t mean a sick pet can skip medicine.
+
+The care grade averages care over time. It starts after ten minutes and can be Perfect, Good, Normal or Bad. Care mistakes and discipline decide evolution, not the grade alone.
+
+Each family stays its own kind of pet. See the [full family trees](characters.md).
+
+## Taking a break
+
+Turn on **Vacation** in Settings to pause care and growth until you return.
+
+After an absence, the game catches up on at most eight hours. Closing just the drawer keeps care running while the page is open. It stays quiet.
+
+## Keep your pet
+
+Progress stays in this browser on this website. Clearing site data removes it. Use **Export save** in Settings to keep a backup, then **Import save** to restore it. Import shows the pet before you confirm replacement.
+
+If another tab has your pet open, close that tab and choose **Try again**. If storage is blocked, progress may last only for the current visit.
+
+Remembered pets keeps a small local history of pets that passed away. Exported saves contain the active pet, not that history.
+
+## Keep a pet inactive
+
+Pick the pet, open Settings and choose Make inactive. Its progress stays saved, but it stops growing and sending notifications. It stays in the selector. Choose Start pet when you want to return.
+
+## Make it yours
+
+Open **Settings** to choose the selected pet's **Handheld color** and **Screen color**. Switch families to set each pet separately. **Return to default colors** resets just that family. Gen 1 starts with a sage handheld and green screen. Gen 2 has its own blue palette. Colors stay in your browser and do not change the website around the game.

package/dist/docs/characters.md

@@ -0,0 +1,51 @@
+# Meet the pets
+
+Pick a family and raise it from an egg. Slice stays pizza, Cypunk stays digital, Lilgotchi stays an egg. Gen 1 and Gen 2 follow separate character paths.
+
+Each family has its own saved pet. Switching families doesn’t replace your progress.
+
+| Family | Starts as | ID |
+| --- | --- | --- |
+| Slice | Dough | `slice` |
+| Cypunk | Binary Seed | `cyberpunk` |
+| Lilgotchi | Little Egg | `lilgotchi` |
+| Gen 1 | Egg | `default` |
+| Gen 2 | Egg | `original2` |
+
+## The full lineups
+
+Each image shows the stages, adult branches and special elder. Open it to see the full size.
+
+### Slice
+
+![Slice stages and evolution paths](images/slice-family.jpg)
+
+### Cypunk
+
+![Cypunk stages and evolution paths](images/cypunk-family.jpg)
+
+### Lilgotchi
+
+![Lilgotchi stages and evolution paths](images/lilgotchi-family.jpg)
+
+### Gen 1
+
+Babytchi grows into Marutchi, then Tamatchi or Kuchitamatchi. Adults include Mametchi, Ginjirotchi, Maskutchi, Kuchipatchi, Nyorotchi and Tarakotchi. Maskutchi can become Oyajitchi or Bill.
+
+### Gen 2
+
+Shirobabytchi grows into Tonmarutchi, then Tongaritchi or Hashitamatchi. Adults include Mimitchi, Pochitchi, Nyatchi, Zuccitchi, Hashizoutchi, Kusatchi and Takotchi. Zuccitchi can become Sekitoritchi, Charitchi or Zatchi.
+
+Both generations use source pixels from [DemiumAjare's P1 and P2 sheets](https://www.spriters-resource.com/lcd_handhelds/tamagotchioriginalp1p2/). Regional variants are included together. These are adapted lilgotchi growth paths, not exact hardware emulation.
+
+## How they grow
+
+Eggs hatch in 90 seconds. Babies become children, then teens and adults. Care mistakes and discipline decide the path. All five families use the same care timing.
+
+The special elder path starts from BBQ Chicken, Matrix, Goose Egg, Maskutchi or Zuccitchi. At age 10 or older with full discipline, the pet has a 5% chance each eligible tick to become its elder. Gen 1 chooses Oyajitchi or Bill equally. Gen 2 chooses Sekitoritchi, Charitchi or Zatchi equally. Other adults don’t take that path.
+
+Gen 2 uses the same care thresholds as Gen 1. Tongaritchi takes the Mametchi equivalent path to Mimitchi, the Ginjirotchi equivalent path to Pochitchi or Nyatchi with equal chances, and the Maskutchi equivalent path to Zuccitchi. The remaining paths lead to Hashizoutchi, Kusatchi or Takotchi in place of Kuchipatchi, Nyorotchi or Tarakotchi.
+
+Spoiled Slice and Cracked Elder are special older forms. They don’t mean you neglected your pet.
+
+[Install guide](install.md) · [Care guide](care.md)

package/dist/docs/credits.md

@@ -0,0 +1,17 @@
+# Credits
+
+[lilgotchi website](https://www.taylordorsett.com/lilgotchi/)
+
+## Inspiration
+
+[Three Pet](https://github.com/ocinpp/three-pet)
+
+[Tamagochi](https://github.com/plateaukao/tamagochi)
+
+[Tamagotchi P1 Web](https://github.com/tonypan2/tamagotchi-p1-web)
+
+[Retro Tamagotchi Clone](https://github.com/oosuhada/retro-tamagotchi-clone)
+
+## License notices
+
+lilgotchi software is released under the [MIT license](../LICENSE.md). The Gen 1 and Gen 2 character sheets are by DemiumAjare on [The Spriters Resource](https://www.spriters-resource.com/lcd_handhelds/tamagotchioriginalp1p2/). Those third party assets retain their separate ownership and are not included in the MIT license. Redistribution must preserve the [required source notices](../pets/NOTICE.md).

package/dist/docs/development.md

@@ -0,0 +1,87 @@
+# Working on lilgotchi
+
+Node.js is all you need. There are no dependencies to install.
+
+```sh
+npm start
+npm test
+npm run build
+```
+
+Open [localhost:4176](http://localhost:4176). The build goes in `dist`. Keep that whole folder together when hosting it.
+
+## Where things live
+
+| Area | Files |
+| --- | --- |
+| Widget and drawer | `lilgotchi.js`, `widget/shell.css` |
+| Hosted script | `embed.js` |
+| Saves and backups | `widget/save-store.js`, `pets/storage.js` |
+| New game models | `pets/minigames/` |
+| Game rules | `pets/engine.js`, `pets/constants.js`, `pets/game.js` |
+| Time and wellbeing | `pets/clock.js`, `pets/away.js`, `pets/wellbeing.js` |
+| Drawing and movement | `pets/renderer.js`, `pets/layout.js`, `pets/presentation.js` |
+| Character art | `pets/*-sprites.js`, `pets/skins.js` |
+| Controls and screen | `pets/game.html`, `pets/embed.css`, `pets/custom-themes.css` |
+| Frame connection | `pets/boot.js` |
+
+The host owns saves. An isolated iframe runs the game. They talk through a private MessageChannel that checks the origin, frame and connection token. Keep save validation and ownership checks in place.
+
+## Custom element
+
+```html
+<script type="module" src="/assets/lilgotchi/lilgotchi.js"></script>
+<lil-gotchi character="slice" storage-key="site-pets"></lil-gotchi>
+```
+
+Use the [script settings](install.md) without `data-` on the element. Set them before adding it to the page.
+
+```js
+const pet = document.querySelector('lil-gotchi');
+await pet.open();
+await pet.setCharacter('cyberpunk');
+await pet.close();
+```
+
+Events are `lilgotchi:ready`, `lilgotchi:open`, `lilgotchi:close`, `lilgotchi:characterchange` and `lilgotchi:error`. The script emits `lilgotchi:loaderror` if loading fails.
+
+## Styling and hosting
+
+Shell variables are `--lilgotchi-surface`, `--lilgotchi-text`, `--lilgotchi-accent`, `--lilgotchi-spacing` and `--lilgotchi-z`. The launcher exposes `lil-gotchi::part(launcher)`. These don’t recolor the game inside its iframe.
+
+Serve modules with a JavaScript content type. If assets live on another origin, enable CORS and allow your site to frame the game. A content security policy needs the asset origin in `script-src`, `style-src` and `frame-src`. The game frame also uses inline styles. No game API connection is needed.
+
+## Saves
+
+Keep the storage key stable. Validate imported files before replacing progress. Damaged saves must stay recoverable. Web Locks allow one active writer per pet, with a lease fallback for older browsers.
+
+Closing the drawer saves and stops drawing and sound. Care continues until the page closes. Vacation pauses it. Removing the element releases its frame and save ownership.
+
+## Check and release
+
+Run `npm test`, then look at the changed screens on desktop and mobile. `/qa/` has fixed states and busy scenes. `/design/evolution/` shows every family and expression. `/qa/directions.html` compares every left and right pose. `/qa/guess.html?pet=pizza` runs the guessing game without saving. Add `direction=right` for a repeatable first answer or `hold=1` for a frozen reveal screenshot. Read the [sprite rules](frame-contract.md) before changing art.
+
+`npm run build` creates the static folder. `npm pack` creates the installable package. On Windows, `scripts/package-release.ps1` makes a zip from a clean, committed checkout.
+
+Publish the built zip and package with a GitHub tag. Keep published version folders unchanged. Check the hosted install after deployment.
+
+Current testing gaps are in the [release notes](release-review.md).
+
+## New games
+
+The games keep game models separate from the screen. Each factory returns `input(action)`, `advance(milliseconds)`, `snapshot()`, `pause()`, `resume()` and `quit()`. Models own their score and timing. They do not touch saves, DOM nodes or pet care.
+
+Snapshots expose the game ID, phase, pause state and result. Results are `win`, `loss`, `quit` or `null`. The host owns input, drawing and reward settlement. Calling advance while paused or after a result must not change the run.
+
+Use injected randomness for repeatable tests. Check boundary inputs, duplicate rewards, pause and large time steps. Run the complete test suite before reviewing the games in desktop and mobile browsers. The [release checklist](../design/games/release-checklist.md) tracks integration evidence. Keep any unverified checks listed when preparing a release.
+## Pull request previews
+
+Same repository PRs into `main` get a preview link in a comment. It updates on each push and disappears when the PR closes. Forks do not publish previews.
+
+Previews keep their own pet saves. They leave the live demo and your pets alone. Sample pages are excluded because they use shared test saves.
+
+## Publish to npm
+
+Update the package version, current install snippets and release notes together. Build and test, inspect `npm pack --dry-run`, then install the packed archive into a temporary project and check its complete `dist` folder.
+
+After the source PR is merged, publish the reviewed archive with `npm publish <archive.tgz> --access public`. npm may ask you to approve the publish in your browser. Verify `npm view lilgotchi version`, install that version from the registry, and check the package page before deploying its npm link. Publish the same archive and versioned static files with the GitHub release. Never replace an existing version.

package/dist/docs/frame-contract.md

@@ -0,0 +1,38 @@
+# Making sprites
+
+The screen is 32 by 16 pixels. Keep the whole pet on it, including toppings, antennae and effects.
+
+## Frames
+
+Sprites are rectangular arrays of palette numbers. Zero is transparent. Freeze the finished arrays and rows.
+
+Custom pets need an egg and all 11 character identities. Eggs use `idle1` and `idle2`. Hatched pets also need `happy`, `sad`, `eat` and `sleep`.
+
+Use a consistent canvas and foot position across expressions. Custom bodies are 12 by 12 pixels. Eggs are 12 by 10. The renderer allows bodies up to 16 by 12, but shared care effects need room too.
+
+The Gen 1 and Gen 2 source bodies may use up to 16 by 16 pixels. Keep their original pixels intact. Their full care scenes are covered by the same collision and clipping checks. Other families retain their existing size limits.
+
+Never crop a row or column to make movement fit.
+
+## Placement
+
+`frameInfo()` in `pets/layout.js` finds visible bounds. `placeFrame()` chooses the nearest safe position. `drawScene()` places the body and effects without overlaps.
+
+Keep positions on whole pixels. The hatch bar uses rows 12 through 14, so eggs stay above it. Clock, meters and labels belong outside the pet canvas.
+
+## Check it
+
+Run `npm test`. The bounds tests check every pet, expression and reaction, including a screen full of waste, sickness and attention marks.
+
+Then open `/qa/` and `/design/evolution/` in the browser. Look at the animation on desktop and mobile. Passing bounds tests doesn’t replace looking at the artwork.
+
+## Guessing game poses
+
+Every hatched character provides `lookLeft` and `lookRight`. Directions use the viewer's point of view. The face turns without flipping markings or moving the whole sprite. These frames fit within the 16 by 16 game canvas and work with reduced motion.
+
+## Small game portraits
+
+`pets/arcade-sprites.js` has separate 8 by 6 portraits for every hatched identity. These use each family's existing palette. They are drawn for the playfield, not scaled down at runtime.
+
+Get and Heading place the portrait at `x = center - 4`, `y = 10 - jump`. That leaves the top ten rows for falling objects. Keep collision coordinates aligned with those positions. `/qa/compact.html` shows all 44 portraits.
+The guessing game draws its full poses at eight screen pixels per sprite pixel. Other previews keep the default scale of four. The pet gets a 128 by 128 area, with smaller arrow buttons beside it so the layout fits narrow screens.

package/dist/docs/install.md

@@ -0,0 +1,41 @@
+# Add lilgotchi to your website
+
+Paste this into your HTML:
+
+```html
+<script defer src="https://www.taylordorsett.com/lilgotchi/releases/3.0.2/embed.js"></script>
+```
+
+That’s it. Slice opens first, all pets are available and sound starts off. Choose **Start pet** to begin. Browsing families does not start them. Your site needs to allow custom JavaScript.
+
+Want to pick the pets, launcher or corner? Use the [setup tool](https://www.taylordorsett.com/lilgotchi/).
+
+Change each pet's handheld and screen colors inside its **Settings**. Switch to another family to customize that pet separately. **Return to default colors** resets the selected family's colors. These choices stay in your browser. The E ink theme keeps its black and white look.
+
+## Host your own copy
+
+[Download the zip](https://github.com/TaylorOD/lilgotchi/releases/download/v3.0.2/lilgotchi-3.0.2.zip), extract the whole folder into your site, then point the script at it:
+
+```html
+<script defer src="/assets/lilgotchi/embed.js"></script>
+```
+
+Keep all the files together. Use the built zip, not GitHub’s source code download.
+
+## Install with npm
+
+The package is on [npm](https://www.npmjs.com/package/lilgotchi):
+
+```sh
+npm install lilgotchi
+```
+
+Copy the entire `node_modules/lilgotchi/dist` folder to your site as `/assets/lilgotchi`, then use the self hosted script above. The widget needs the game HTML, scripts and styles together. Installing the package alone does not add it to your page.
+
+For an exact version, use `npm install lilgotchi@3.0.2`. The GitHub release also includes the same npm tarball.
+
+## Saves
+
+Pets save in the visitor’s browser on your website. Settings has **Export save** and **Import save** for backups. There’s no account or automatic sync.
+
+For styling and JavaScript controls, see [development](development.md).

package/dist/docs/release-review.md

@@ -0,0 +1,47 @@
+# Release notes
+
+## 3.0.2
+
+Adds the public npm package and a package link beside GitHub. The character guide has a separate back link and logo, with Gen 1 and Gen 2 at the end of the family list.
+
+## 3.0.1
+
+The homepage uses one full width column, with setup instructions inside the settings box. Pet colors live in the game Settings and can be changed separately for each family. Gen 1 now starts with a sage handheld. Dropdown arrows have more room, and the Try again button is centered with space above the divider.
+
+## 3.0
+
+Gen 1 now uses the P1 source sprites. Gen 2 adds the P2 family with its own save. All 26 characters from the source collection are included, with regional and hidden forms using adapted growth paths.
+
+The 267 automated checks pass, including family saves, growth paths and sprite bounds. Browser review covered the character guide, hatching, feeding, family switching, a guessing game, the phone layout and a crowded adult screen. Version 3.0.0 was released with explicit Start pet controls, separate family colors and the curved keychain.
+
+## 2.0
+
+Seven new games: Get, Bump, Heading, Memory, Flag, Sprint and Hoops. The guessing game stays and now shows clear left and right poses.
+
+Release approved by Taylor on November 9, 2026. Automated checks cover the game rules, rewards, cancellation and pixel bounds. All seven games were exercised in a mobile browser, with a separate desktop review of the picker, Bump, Memory and Sprint. Physical device, screen reader, audio listening and longer balance sessions are still needed. See the [review checklist](../design/games/release-checklist.md).
+
+## 1.2
+
+Inactive pets keep their progress without growing or sending notifications. Slice has a lighter shell and display. The launcher is a little smaller, with an inset care badge.
+## 1.2.1
+
+The guessing game now shows the answer with a left or right pose before the result reaction. Every hatched pet has both poses. Round timing, odds and rewards stay the same. Closing or restarting a game cancels its pending reactions.
+
+Checked all four families in the browser and both answer directions at desktop and mobile sizes. The 156 automated checks pass. This patch was approved for release before 2.0.
+
+## 1.1
+
+A bigger pet button, a logo option and care counts across your started pets. Open the needs list to jump to the pet that needs you. Notifications can be turned off in the setup tool.
+
+
+## 1.0
+
+Four families. A little game for your website. Local saves, optional sound, Vacation and a one line install.
+
+The [character guide](characters.md) shows every stage, adult branch and special elder.
+
+[Download it](https://github.com/TaylorOD/lilgotchi/releases/latest) or [add it to your site](install.md).
+
+## Checked
+
+Automated checks cover care, evolution, saves, expressions and keeping pets inside the screen. The game was also checked in Chrome at desktop and mobile sizes.

package/dist/embed.js

@@ -0,0 +1,21 @@
+(() => {
+  const script = document.currentScript;
+  if (!script) return;
+  const loader = new URL('./lilgotchi.js', script.src).href;
+  const settings = ['character', 'characters', 'placement', 'appearance', 'storage-key', 'mode', 'muted', 'launcher', 'notifications', 'colors'];
+  const attributes = settings.filter(name => script.hasAttribute(`data-${name}`))
+    .map(name => [name, script.getAttribute(`data-${name}`)]);
+  const ready = document.readyState === 'loading'
+    ? new Promise(resolve => document.addEventListener('DOMContentLoaded', resolve, { once: true }))
+    : Promise.resolve();
+  Promise.all([import(loader), ready]).then(() => {
+    const pet = document.createElement('lil-gotchi');
+    for (const [name, value] of attributes) pet.setAttribute(name, value);
+    if (!pet.hasAttribute('character')) pet.setAttribute('character', 'slice');
+    if (pet.getAttribute('mode') === 'inline' && document.body.contains(script)) script.after(pet);
+    else document.body.append(pet);
+  }).catch(error => {
+    console.error('lilgotchi could not load', error);
+    script.dispatchEvent(new CustomEvent('lilgotchi:loaderror', { detail: { message: 'lilgotchi could not load' } }));
+  });
+})();

package/dist/examples/cross-origin.html

@@ -0,0 +1,7 @@
+<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>lilgotchi separate origin</title>
+<style>body{font:16px system-ui;background:#ebe6db;color:#202b2c;margin:24px}</style><h1>A widget from another origin</h1><p>Serve this page on localhost:4176. Its module and frame come from 127.0.0.1:4176. Saves belong to localhost.</p>
+<script type="module">
+const moduleUrl=new URL('../lilgotchi.js',location.href);
+moduleUrl.hostname='127.0.0.1';
+await import(moduleUrl.href);
+</script><lil-gotchi mode="inline" character="cyberpunk" storage-key="cross-origin"></lil-gotchi></html>

package/dist/examples/curated.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Choose your lilgotchi lineup</title>
+<style>body{margin:32px auto;padding:0 20px;max-width:720px;background:#101219;color:#ececf4;font:16px/1.6 system-ui}pre{white-space:pre-wrap;background:#20242c;padding:16px;border-radius:12px}</style>
+<h1>Your site, your lineup</h1>
+<p>This example offers just Gen 1, Slice and Cypunk. Leave out the characters setting, or use all, to offer the full lineup.</p>
+<pre>&lt;lil-gotchi characters="default,slice,cyberpunk" character="default"&gt;&lt;/lil-gotchi&gt;</pre>
+<script type="module" src="../lilgotchi.js"></script>
+<lil-gotchi characters="default,slice,cyberpunk" character="default" storage-key="curated-example" mode="inline"></lil-gotchi>
+</html>

package/dist/examples/duplicate.html

@@ -0,0 +1,3 @@
+<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>lilgotchi shared identity</title>
+<style>body{font:16px system-ui;background:#ebe6db;margin:24px}.examples{display:flex;gap:20px;flex-wrap:wrap}</style><h1>One pet, one active player</h1><p>Both widgets share a key. Only one may write progress. Remove the first widget or close its tab, then try again in the second.</p>
+<div class="examples"><lil-gotchi mode="inline" storage-key="shared-example"></lil-gotchi><lil-gotchi mode="inline" storage-key="shared-example"></lil-gotchi></div><script type="module" src="../lilgotchi.js"></script></html>

package/dist/examples/install.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>lilgotchi clean install</title>
+<style>body{font:18px system-ui;max-width:42rem;margin:10vh auto;padding:24px;line-height:1.6}</style>
+<h1>A little room for a pet</h1>
+<p>This plain page loads the widget from the copied release folder. Open the pet in the corner, then reload to check your progress.</p>
+<script type="module" src="../lilgotchi.js"></script>
+<lil-gotchi character="slice" storage-key="clean-install"></lil-gotchi>
+</html>

package/dist/examples/launcher-review.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Launcher review</title>
+<style>body{background:#101418;color:#eee;font:16px/1.6 system-ui;padding:100px 24px;max-width:650px;margin:auto}h1{font-size:26px}p{color:#bec9c6}</style>
+<h1>A little company</h1><p>Logo and pet launchers, with care counts across families. Open a button to see which pets need care. These sample pets have their own saves.</p>
+<script type="module">
+import '../lilgotchi.js';
+import { GameState } from '../pets/engine.js';
+import { SaveStore } from '../widget/save-store.js';
+for(const [index,placement] of ['bottom-right','bottom-left','top-right','top-left'].entries()){
+  const key=`launcher-polish-${index}`;const store=new SaveStore(key);
+  for(const family of ['slice','cyberpunk']){
+    if(!store.raw(family)&&await store.acquire(family)){
+      const state=new GameState();Object.assign(state,{stage:'adult',character:'mametchi',hunger:family==='slice'?0:4,happiness:family==='slice'?4:0,poopCount:family==='slice'?2:0});
+      store.save(family,state);store.release(family);
+    }
+  }
+  store.preference('introduced',true);store.dispose();
+  const pet=document.createElement('lil-gotchi');pet.setAttribute('storage-key',key);pet.setAttribute('character','slice');pet.setAttribute('placement',placement);
+  pet.setAttribute('launcher',index%2?'shell':'brand');pet.setAttribute('notifications',index===2?'off':'on');document.body.append(pet);
+}
+</script></html>
+

package/dist/examples/launchers.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>lilgotchi launchers</title>
+<style>body{background:#121619;color:#eef1ed;font:16px/1.5 system-ui;margin:32px}main{max-width:720px;margin:auto}.lineup{display:flex;flex-wrap:wrap;gap:28px}.lineup>div{display:grid;gap:12px;justify-items:center}lil-gotchi::part(launcher){position:relative;inset:auto}h1{font-size:28px}p{color:#bdc8be}</style></head>
+<body><main><h1>A little color for every pet</h1><p>Each launcher matches its egg shell. Open one to meet its pet.</p><div class="lineup">
+<div><span>Gen 1 egg</span><lil-gotchi character="default" storage-key="preview-original"></lil-gotchi></div>
+<div><span>Slice</span><lil-gotchi character="slice" storage-key="preview-slice"></lil-gotchi></div>
+<div><span>Cypunk</span><lil-gotchi character="cyberpunk" storage-key="preview-cypunk"></lil-gotchi></div>
+<div><span>Lilgotchi</span><lil-gotchi character="lilgotchi" storage-key="preview-lilgotchi"></lil-gotchi></div>
+<div><span>Without a shell</span><lil-gotchi character="lilgotchi" launcher="pet" storage-key="preview-no-shell"></lil-gotchi></div>
+</div></main><script type="module" src="../lilgotchi.js"></script></body></html>

package/dist/examples/nested/index.html

@@ -0,0 +1,6 @@
+<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>lilgotchi install examples</title>
+<style>body{font:16px system-ui;background:#ece7dc;color:#21292d;margin:24px}button{background:red!important;font-size:40px!important}canvas{border:20px solid red}h1{font-size:28px}.examples{display:flex;gap:20px;flex-wrap:wrap}a{color:#175b65}</style>
+<h1>Independent pets on a plain website</h1><p>Global button and canvas styles deliberately clash. The widgets stay isolated.</p>
+<div class="examples"><lil-gotchi mode="inline" character="default" storage-key="example-a"></lil-gotchi><lil-gotchi mode="inline" character="slice" storage-key="example-b"></lil-gotchi></div>
+<p><a href="../cross-origin.html">Separate origin example</a> · <a href="../duplicate.html">Shared identity example</a> · <a href="../../">Home</a></p>
+<script type="module" src="../../lilgotchi.js"></script></html>

package/dist/examples/one-line.html

@@ -0,0 +1,9 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>One line lilgotchi install</title>
+<style>body{font:16px system-ui;background:#ebe6db;color:#202b2c;margin:32px;line-height:1.6}main{max-width:560px}code{overflow-wrap:anywhere}</style>
+<main><h1>A little company</h1><p>This page adds lilgotchi with one script. Open the egg in the corner to meet your pet.</p><p>No custom element, stylesheet or setup code needed.</p></main>
+<script defer src="../embed.js" data-storage-key="one-line-example"></script>
+</html>