lilgotchi 0.0.0-stage → 3.0.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taylor Dorsett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# <img src="https://raw.githubusercontent.com/TaylorOD/lilgotchi/main/widget/egg.svg" width="24" height="28" alt=""> lilgotchi
+
+A little pixel pet for your website. Feed it, play with it, and watch it grow.
+
+**[Meet lilgotchi](https://www.taylordorsett.com/lilgotchi/)** · **[Character guide](https://github.com/TaylorOD/lilgotchi/blob/main/docs/characters.md)** · **[Download](https://github.com/TaylorOD/lilgotchi/releases/latest)**
+
+<p align="center">
+  <a href="https://www.taylordorsett.com/lilgotchi/">
+    <img src="https://raw.githubusercontent.com/TaylorOD/lilgotchi/main/pr-screenshots/adult-margherita-readme.jpg" alt="Adult Margherita in the lilgotchi widget" width="320">
+  </a>
+</p>
+
+## Five little families
+
+| Family | Starts as |
+| --- | --- |
+| Slice | A ball of dough |
+| Cypunk | A binary egg |
+| Lilgotchi | Our little logo egg |
+| Gen 1 | The classic egg |
+| Gen 2 | The second generation egg |
+
+Every family starts small and follows its own growth paths. Each keeps a separate save. Gen 1 and Gen 2 include 26 characters across both generations, with source pixel artwork and regional hidden forms.
+
+Choose **Start pet** when you are ready. Opening the drawer or switching families does not start a new pet. Each family has its own handheld and screen colors in **Settings**, with a button to return to its defaults.
+
+Feed, play, clean up and settle down for a nap. Progress stays in your browser, with file backups in Settings.
+
+## Put one on your website
+
+```html
+<script defer src="https://www.taylordorsett.com/lilgotchi/releases/3.0.2/embed.js"></script>
+```
+
+That’s it. No account, backend or dependencies.
+
+Use the [setup tool](https://www.taylordorsett.com/lilgotchi/) to pick your pets and placement. The [install guide](https://github.com/TaylorOD/lilgotchi/blob/main/docs/install.md) covers hosting your own copy.
+
+## Install with npm
+
+```sh
+npm install lilgotchi
+```
+
+Copy the whole `node_modules/lilgotchi/dist` folder into your site's public assets, then load its `embed.js`. Keep the game pages, scripts and styles together. Installing the package alone does not add the widget to your page.
+
+[View on npm](https://www.npmjs.com/package/lilgotchi)
+
+## Eight ways to play
+
+Catch notes, bump an opponent, head a ball, repeat arrows, follow flags, race and shoot hoops. Or play the original guessing game. [See the games](https://github.com/TaylorOD/lilgotchi/blob/main/design/games/README.md).
+
+## Work on it
+
+```sh
+npm start
+npm test
+npm run build
+```
+
+Open [localhost:4176](http://localhost:4176). The build goes in `dist`.
+
+[Development](https://github.com/TaylorOD/lilgotchi/blob/main/docs/development.md) · [Care guide](https://github.com/TaylorOD/lilgotchi/blob/main/docs/care.md) · [Release notes](https://github.com/TaylorOD/lilgotchi/blob/main/docs/release-review.md)
+
+## License
+
+[MIT](https://github.com/TaylorOD/lilgotchi/blob/main/LICENSE.md) for the software. The Gen 1 and Gen 2 character artwork is third party material with separate ownership. Keep the license and [required notices](https://github.com/TaylorOD/lilgotchi/blob/main/pets/NOTICE.md) with redistributed copies.
+
+[Credits](https://github.com/TaylorOD/lilgotchi/blob/main/docs/credits.md)

package/dist/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taylor Dorsett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/README.md

@@ -0,0 +1,69 @@
+# <img src="https://raw.githubusercontent.com/TaylorOD/lilgotchi/main/widget/egg.svg" width="24" height="28" alt=""> lilgotchi
+
+A little pixel pet for your website. Feed it, play with it, and watch it grow.
+
+**[Meet lilgotchi](https://www.taylordorsett.com/lilgotchi/)** · **[Character guide](https://github.com/TaylorOD/lilgotchi/blob/main/docs/characters.md)** · **[Download](https://github.com/TaylorOD/lilgotchi/releases/latest)**
+
+<p align="center">
+  <a href="https://www.taylordorsett.com/lilgotchi/">
+    <img src="https://raw.githubusercontent.com/TaylorOD/lilgotchi/main/pr-screenshots/adult-margherita-readme.jpg" alt="Adult Margherita in the lilgotchi widget" width="320">
+  </a>
+</p>
+
+## Five little families
+
+| Family | Starts as |
+| --- | --- |
+| Slice | A ball of dough |
+| Cypunk | A binary egg |
+| Lilgotchi | Our little logo egg |
+| Gen 1 | The classic egg |
+| Gen 2 | The second generation egg |
+
+Every family starts small and follows its own growth paths. Each keeps a separate save. Gen 1 and Gen 2 include 26 characters across both generations, with source pixel artwork and regional hidden forms.
+
+Choose **Start pet** when you are ready. Opening the drawer or switching families does not start a new pet. Each family has its own handheld and screen colors in **Settings**, with a button to return to its defaults.
+
+Feed, play, clean up and settle down for a nap. Progress stays in your browser, with file backups in Settings.
+
+## Put one on your website
+
+```html
+<script defer src="https://www.taylordorsett.com/lilgotchi/releases/3.0.2/embed.js"></script>
+```
+
+That’s it. No account, backend or dependencies.
+
+Use the [setup tool](https://www.taylordorsett.com/lilgotchi/) to pick your pets and placement. The [install guide](https://github.com/TaylorOD/lilgotchi/blob/main/docs/install.md) covers hosting your own copy.
+
+## Install with npm
+
+```sh
+npm install lilgotchi
+```
+
+Copy the whole `node_modules/lilgotchi/dist` folder into your site's public assets, then load its `embed.js`. Keep the game pages, scripts and styles together. Installing the package alone does not add the widget to your page.
+
+[View on npm](https://www.npmjs.com/package/lilgotchi)
+
+## Eight ways to play
+
+Catch notes, bump an opponent, head a ball, repeat arrows, follow flags, race and shoot hoops. Or play the original guessing game. [See the games](https://github.com/TaylorOD/lilgotchi/blob/main/design/games/README.md).
+
+## Work on it
+
+```sh
+npm start
+npm test
+npm run build
+```
+
+Open [localhost:4176](http://localhost:4176). The build goes in `dist`.
+
+[Development](https://github.com/TaylorOD/lilgotchi/blob/main/docs/development.md) · [Care guide](https://github.com/TaylorOD/lilgotchi/blob/main/docs/care.md) · [Release notes](https://github.com/TaylorOD/lilgotchi/blob/main/docs/release-review.md)
+
+## License
+
+[MIT](https://github.com/TaylorOD/lilgotchi/blob/main/LICENSE.md) for the software. The Gen 1 and Gen 2 character artwork is third party material with separate ownership. Keep the license and [required notices](https://github.com/TaylorOD/lilgotchi/blob/main/pets/NOTICE.md) with redistributed copies.
+
+[Credits](https://github.com/TaylorOD/lilgotchi/blob/main/docs/credits.md)

package/dist/design/evolution/README.md

@@ -0,0 +1,7 @@
+# Family artwork
+
+Run `npm start` and open [the viewer](http://localhost:4176/design/evolution/). Pick a family and expression to see the game sprites.
+
+[Slice](slice.md) · [Cypunk](cypunk.md) · [Lilgotchi](lilgotchi.md)
+
+The [character guide](../../docs/characters.md) has the full family trees. The [sprite rules](../../docs/frame-contract.md) cover drawing and screen bounds.

package/dist/design/evolution/cypunk.js

@@ -0,0 +1,3 @@
+import { cyberpunkSprites as sprites, cyberpunkPalette as palette, cyberpunkNames as names } from '../../pets/cyberpunk-sprites.js';
+const stages={egg:'egg',babytchi:'baby',marutchi:'child',tamatchi:'teen',kuchitamatchi:'teen'};
+export const proposal={type:'Cypunk',palette,pets:Object.entries(sprites).map(([id,frames])=>({id,name:names[id],stage:stages[id]||'adult',frames}))};

package/dist/design/evolution/cypunk.md

@@ -0,0 +1,20 @@
+# Cypunk artwork
+
+Little robots with faces, hands and feet. Binary Seed reads 01. Sentinel uses the original Cypunk adult artwork. Matrix is green with small code lights on its body.
+
+| Original identity | Name | Shape and detail |
+| --- | --- | --- |
+| egg | Binary Seed | Rounded cyan seed carrying tiny binary marks |
+| babytchi | Bit | Small digital block with a face and two feet |
+| marutchi | Byte | Wider chip with an antenna and side contacts |
+| tamatchi | Compiler | Upright terminal character with a neat head and body |
+| kuchitamatchi | Syntax Error | Uneven terminal with detached magenta pixels |
+| mametchi | JavaScript | Cyan robot with yellow antenna tips, scarf, hands and feet |
+| ginjirotchi | Sentinel | The original Cypunk adult, with its exact sprite and expressions |
+| maskutchi | Matrix | Green robot with antennae, a face and falling torso lights |
+| kuchipatchi | 404 | Lost little robot with a bent magenta antenna and lowered arms |
+| nyorotchi | MissingNumber | Original asymmetric block creature with broken edges and magenta fragments |
+| tarakotchi | Blue Screen | Wide blue monitor companion with a face, arms and feet |
+| oyajitchi | Glitch Elder | Cyan elder made of separated chunks and magenta fragments |
+
+See the [family trees](../../docs/characters.md) for growth paths and the [sprite rules](../../docs/frame-contract.md) for sizes and expressions. The preview reads the same art as the game.

package/dist/design/evolution/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>lilgotchi evolution paths</title>
+<link rel="icon" type="image/svg+xml" href="../../widget/egg.svg">
+<link rel="stylesheet" href="preview.css">
+<main>
+  <a class="back-home" href="../../"><span aria-hidden="true">&larr;</span> back to main page</a>
+  <p class="guide-brand"><img src="../../widget/egg.svg" width="24" height="28" alt=""> lilgotchi</p>
+  <p class="eyebrow">character guide</p>
+  <h1>A whole little life.</h1>
+  <p>The character paths and artwork in lilgotchi.</p>
+  <nav aria-label="Pet type"><button data-type="slice" aria-pressed="true">Slice</button><button data-type="cypunk" aria-pressed="false">Cypunk</button><button data-type="lilgotchi" aria-pressed="false">Lilgotchi</button><button data-type="original" aria-pressed="false">Gen 1</button><button data-type="original2" aria-pressed="false">Gen 2</button></nav>
+  <label>Expression <select id="expression"><option value="idle1">Idle</option><option value="idle2">Moving</option><option value="happy">Happy</option><option value="sad">Sad</option><option value="eat">Eating</option><option value="sleep">Sleeping</option></select></label>
+  <section id="review" aria-live="polite"></section>
+  <p class="note">Paths follow the current game code. This is not a claim of exact original hardware accuracy. <a id="details" href="slice.md">Read the full pathways</a>.</p>
+</main>
+<script type="module" src="preview.js"></script>
+</html>

package/dist/design/evolution/lilgotchi.js

@@ -0,0 +1,3 @@
+import { lilgotchiSprites as sprites, lilgotchiPalette as palette, lilgotchiNames as names } from '../../pets/lilgotchi-sprites.js';
+const stages={egg:'egg',babytchi:'baby',marutchi:'child',tamatchi:'teen',kuchitamatchi:'teen'};
+export const proposal={type:'Lilgotchi',palette,pets:Object.entries(sprites).map(([id,frames])=>({id,name:names[id],stage:stages[id]||'adult',frames}))};

package/dist/design/evolution/lilgotchi.md

@@ -0,0 +1,20 @@
+# Lilgotchi artwork
+
+An egg that stays an egg. Different shells and markings give each adult its own look. Cracked Elder has a missing side piece and a crack running down from it.
+
+| Original identity | Proposed egg | Stage | Visual cue |
+| --- | --- | --- | --- |
+| egg | Little Egg | Egg | Small cream shell without eyes |
+| babytchi | Peep Egg | Baby | Small cream shell gains eyes |
+| marutchi | Growing Egg | Child | Taller cream shell |
+| tamatchi | Smooth Egg | Teen | Smooth cream shell with a highlight |
+| kuchitamatchi | Speckled Egg | Teen | Tan shell with a few spots |
+| mametchi | Duck Egg | Adult | Rounded pale green shell |
+| ginjirotchi | Quail Egg | Adult | Smaller tan shell with brown speckles |
+| maskutchi | Goose Egg | Adult | Tall white shell |
+| kuchipatchi | Jumbo Egg | Adult | Broad cream shell |
+| nyorotchi | Golden Egg | Adult | Gold shell with a diagonal shine |
+| tarakotchi | Century Egg | Adult | Dark teal shell and light eyes |
+| oyajitchi | Cracked Elder | Adult elder | White shell with a crack at the top |
+
+See the [family trees](../../docs/characters.md) for growth paths and the [sprite rules](../../docs/frame-contract.md) for sizes and expressions. The preview reads the same art as the game.

package/dist/design/evolution/preview.css

@@ -0,0 +1,3 @@
+:root{color-scheme:dark;font-family:system-ui,sans-serif;color:#eeeae0;background:#101619}*{box-sizing:border-box}body{margin:0;padding:32px}main{max-width:1050px;margin:auto}h1{font-size:44px;letter-spacing:-.04em;margin:4px 0 10px}h2{font-size:22px;margin:24px 0 12px}p{color:#b4c3c6;line-height:1.5;margin:8px 0}.eyebrow{color:#e3c58a;letter-spacing:.12em;text-transform:uppercase;font-size:12px}nav{display:flex;flex-wrap:wrap;gap:10px;margin:22px 0 16px}button,select{font:inherit;min-height:44px;border:1px solid #4c6068;border-radius:10px;background:#19252b;color:inherit;padding:10px 18px}button{cursor:pointer}button[aria-pressed=true]{background:#e3c58a;color:#162025;border-color:#e3c58a}label{font-size:13px;color:#b4c3c6}select{margin-left:12px;padding:8px 12px}.grid{display:grid;gap:12px}.growing{grid-template-columns:repeat(5,1fr)}.adults{grid-template-columns:repeat(3,1fr)}article{border:1px solid #35464b;border-radius:16px;padding:16px;background:#182126;text-align:center}article svg{width:84px;height:84px;display:block;margin:8px auto 12px;image-rendering:pixelated}h3{margin:8px 0;font-size:17px}.stage{font-size:11px;text-transform:uppercase;color:#e3c58a;letter-spacing:.08em}.route{font-size:12px;min-height:36px}.original{font-size:11px;color:#8fa5ad}.elder{display:flex;align-items:center;gap:24px;text-align:left}.elder svg{margin:0;width:84px;flex-shrink:0}.elder p{max-width:70ch}.note{font-size:12px;margin-top:24px}a{color:#9de4ce}button:focus-visible,select:focus-visible,a:focus-visible{outline:2px solid #9de4ce;outline-offset:3px}@media(max-width:600px){body{padding:22px 16px}h1{font-size:34px}.growing,.adults{grid-template-columns:repeat(2,minmax(0,1fr))}article{padding:12px}.elder{align-items:flex-start;gap:12px}nav{gap:8px}button{padding:10px 14px}}
+
+.back-home{display:inline-flex;align-items:center;gap:8px;min-height:44px;margin-bottom:18px;text-decoration:none;font-weight:650}.back-home:hover{text-decoration:underline}.guide-brand{display:flex;align-items:center;gap:8px;font-size:24px;font-weight:750;color:#eeeae0;margin:0 0 18px}.guide-brand img{image-rendering:pixelated;height:1em;width:auto}

package/dist/design/evolution/preview.js

@@ -0,0 +1,47 @@
+import {proposal as slice} from './slice.js';
+import {proposal as cypunk} from './cypunk.js';
+import {proposal as lilgotchi} from './lilgotchi.js';
+import {classicSprites} from '../../pets/classic-sprites.js';
+import {originalSprites} from '../../pets/original-sprites.js';
+import {p1Stages,p2Stages} from '../../pets/original-roster.js';
+const original={type:'Gen 1',palette:['','#b4ce83']};
+const original2={type:'Gen 2',palette:['','#b4ce83']};
+const proposals={original,original2,slice,cypunk,lilgotchi};
+let selected=new URLSearchParams(location.search).get('family')||'slice';
+if(!proposals[selected])selected='slice';
+const early=['90 second hatch','Baby','Child','0 or 1 care mistakes','2+ care mistakes'];
+const adultRoutes=[
+  'Smooth teen · ≤2 mistakes + 100% discipline',
+  'Smooth teen · ≤2 mistakes + 75–99% discipline',
+  'Smooth teen · ≤4 mistakes + ≥50% discipline, after earlier checks fail',
+  'Smooth teen · remaining ≥50% discipline. Rough teen · ≥75%',
+  'Smooth teen · 25–49% discipline. Rough teen · 50–74%',
+  'Smooth teen · below 25% discipline. Rough teen · below 50%',
+];
+function sprite(pet,palette,expression){
+  const frame=pet.frames[expression]||pet.frames.idle1;
+  return `<svg viewBox="-1 -1 ${frame[0].length+2} ${frame.length+2}" role="img" aria-label="${pet.name}" shape-rendering="crispEdges">${frame.flatMap((row,y)=>row.map((pixel,x)=>pixel?`<rect x="${x}" y="${y}" width="1" height="1" fill="${palette[pixel]}"/>`:'')).join('')}</svg>`;
+}
+function render(){
+  const {type,pets,palette}=proposals[selected];
+  const expression=document.querySelector('#expression').value;
+  if(selected==='original'||selected==='original2'){
+    const stages=selected==='original'?p1Stages:p2Stages;
+    const hidden=selected==='original'?['oyajitchi','bill']:['sekitoritchi','charitchi','zatchi'];
+    const sections=[['growing up',[...stages.egg,...stages.baby,...stages.child,...stages.teen]],['adults',stages.adult.filter(id=>!hidden.includes(id))],['hidden',hidden]];
+    document.querySelector('#review').innerHTML=`<h2>${type}: the full lineup</h2><p class="note">Gen 1 and Gen 2 source pixels, including regional characters. Both families use lilgotchi care timing and adapted growth paths.</p>`+sections.map(([stage,ids])=>`<h2>${stage[0].toUpperCase()+stage.slice(1)}</h2><div class="grid adults">${ids.map(id=>{
+      const pet={id,name:id==='egg'?'Egg':id[0].toUpperCase()+id.slice(1),frames:originalSprites[id]||classicSprites[id]};
+      return `<article><span class="stage">${Object.entries(stages).find(([,ids])=>ids.includes(id))[0]}</span>${sprite(pet,palette,expression)}<h3>${pet.name}</h3><span class="original">${id}</span></article>`;
+    }).join('')}</div>`).join('');
+    document.querySelector('#details').href='../../docs/characters.md';
+    document.querySelectorAll('[data-type]').forEach(button=>button.setAttribute('aria-pressed',String(button.dataset.type===selected)));
+    return;
+  }
+  function card(pet,route){return `<article><span class="stage">${pet.stage}</span>${sprite(pet,palette,expression)}<h3>${pet.name}</h3><p class="route">${route}</p><span class="original">${pet.id}</span></article>`;}
+  document.querySelector('#review').innerHTML=`<h2>${type}: growing up</h2><div class="grid growing">${pets.slice(0,5).map((pet,i)=>card(pet,early[i])).join('')}</div><h2>Six adult possibilities</h2><p class="note">“Smooth teen” is ${pets[3].name}. “Rough teen” is ${pets[4].name}. Conditions are checked in order.</p><div class="grid adults">${pets.slice(5,11).map((pet,i)=>card(pet,adultRoutes[i])).join('')}</div><h2>A special elder</h2><article class="elder">${sprite(pets[11],palette,expression)}<div><h3>${pets[7].name} → ${pets[11].name}</h3><p>Age 10 or older, alive and 100% discipline. A 5% chance each eligible simulation tick. Other adults do not take this path.</p><span class="original">maskutchi → oyajitchi</span></div></article>`;
+  document.querySelector('#details').href=selected==='original'?'../../docs/characters.md':`${selected}.md`;
+  document.querySelectorAll('[data-type]').forEach(button=>button.setAttribute('aria-pressed',String(button.dataset.type===selected)));
+}
+document.querySelectorAll('[data-type]').forEach(button=>button.addEventListener('click',()=>{selected=button.dataset.type;render();}));
+document.querySelector('#expression').addEventListener('change',render);
+render();

package/dist/design/evolution/slice.js

@@ -0,0 +1,3 @@
+import { sliceSprites as sprites, slicePalette as palette, sliceNames as names } from '../../pets/slice-sprites.js';
+const stages={egg:'egg',babytchi:'baby',marutchi:'child',tamatchi:'teen',kuchitamatchi:'teen'};
+export const proposal={type:'Slice',palette,pets:Object.entries(sprites).map(([id,frames])=>({id,name:names[id],stage:stages[id]||'adult',frames}))};

package/dist/design/evolution/slice.md

@@ -0,0 +1,14 @@
+# Slice artwork
+
+Dough grows into a little pizza. Keep the face clear and the toppings easy to see.
+
+| Original ID | Proposed pizza | Condition |
+| --- | --- | --- |
+| mametchi | Margherita | At most 2 care mistakes and 100% discipline |
+| ginjirotchi | Pepperoni | At most 2 care mistakes and 75% to 99% discipline |
+| maskutchi | BBQ Chicken | At most 4 care mistakes and at least 50% discipline, after the first two checks fail |
+| kuchipatchi | Meat Lovers | At least 50% discipline, after the earlier checks fail |
+| nyorotchi | Anchovy | 25% to 49% discipline |
+| tarakotchi | Pineapple | Below 25% discipline |
+
+See the [family trees](../../docs/characters.md) for growth paths and the [sprite rules](../../docs/frame-contract.md) for sizes and expressions. The preview reads the same art as the game.

package/dist/design/games/README.md

@@ -0,0 +1,52 @@
+# More games for lilgotchi
+
+2.0 adds seven games. The timing and scores are our rules, not a claim of exact hardware behavior.
+
+## The guessing game
+
+[Left and right](left-right.md) now shows a visible turn in both directions, including symmetrical characters. Its rules and rewards stay the same.
+
+## The 2.0 lineup
+
+| Game | What you do |
+| --- | --- |
+| [Get](get.md) | Catch notes and dodge poop |
+| [Bump](bump.md) | Stop a power meter and bump an opponent |
+| [Heading](heading.md) | Move under a ball and head it upward |
+| [Memory](memory.md) | Repeat a growing arrow sequence |
+| [Flag](flag.md) | Follow real cues and ignore fake ones |
+| [Sprint](sprint.md) | Tap or hold to race |
+| [Hoops](hoops.md) | Time basketball shots |
+
+The existing guessing game stays. Each new game has its own model and tests. They share controls, pause behavior and care rewards.
+
+This is the seven game Connection set, not every game from every Tamagotchi. The [catalog](catalog.md) keeps the wider research backlog separate.
+
+## Keep the widget small
+
+Play opens a game picker. Game names, instructions, score, progress, pause and exit sit outside the pixel display. Show one short instruction before Start. The display is for the pet and playfield.
+
+Use a 32 by 24 game field and integer pixels. Give each game up to three large touch controls below it, with matching keyboard controls. Do not put a tiny menu or text over the pet. Keep the same layout for all four families.
+
+Use the current pet and evolution. Draw new poses when needed. A symmetrical sprite flipped horizontally is not a visible turn. Keep eyes, toppings, antennae, cracks and readable symbols recognizable. Check the largest adult and elder forms before approving the layout.
+
+## Shared game rules
+
+The 2.0 contract:
+
+1. Keep the existing play restrictions for eggs, sleeping, sick, dead or vacation pets. Explain unavailable games beside their names. No new stage locks in the first batch.
+2. Pause the round when the drawer closes or the page hides. On return, offer Resume or Quit. No hidden timers, free points or automatic losses. Care time follows the existing game rules.
+3. End a run if the pet dies, starts vacation or changes family. Cancel old callbacks so they cannot affect the next pet.
+4. A win gives one happiness heart, capped at four, once per finished run. A loss or quit gives none. No coins, betting, inventory, new evolution rules or extra weight changes in this first batch. Settle the existing energy effect once per started run, not per tap.
+5. Keep an unfinished run in memory only. Reloading ends it without a reward. High scores are outside the first batch.
+6. Keep sound optional. Every sound cue needs a visible cue. Reduced motion removes decoration, not essential game feedback. Pause stays available. Announce instructions, results and discrete cues without reading every animation frame.
+
+## Review notes
+
+2.0 is released. The next polish pass keeps the full current pet in each game, adds room around the controls and makes the cues easier to follow. That pass is still in review. Physical phone playtesting, audio listening, human screen reader checks and longer balance sessions remain unverified. See the [review checklist](release-checklist.md).
+
+## Before shipping
+
+Verify input, collisions, scoring, pause, exit, repeat rewards and family switching. Test every hatched sprite against screen bounds. Review the actual games in desktop and mobile browsers, including touch targets, keyboard focus and muted play. Capture screenshots in each PR. For timing games, also review a short recording.
+
+Source for the seven Connection games: [Bandai's manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/). Their controls and objectives are references. The durations and win conditions in these docs are our starting balance choices.

package/dist/design/games/bump.md

@@ -0,0 +1,23 @@
+# Bump
+
+Included in 2.0. Follow the [shared game rules](README.md).
+
+Time a power meter to bump another pet over. The [Connection manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/) describes timing the press for maximum power.
+
+## Our version
+
+One Bump button stops a meter that moves up and down. Space does the same. Give a 1.5 second countdown before the meter starts. The meter times out after six seconds, losing that bout. Do not reward repeated tapping.
+
+Play three bouts. Each has a clearly marked target region. Stopping inside it wins the bout. Win two bouts to win the run. The inclusive target ranges are 60 to 85, 63 to 82 and 66 to 79 on the 0 to 100 meter. This is a timing challenge with no hidden random loss after a successful stop.
+
+## Screen and art
+
+Show the current pet and a local computer opponent facing each other. Put the meter, target marker and bout score below the display. Stop the meter, hold the result, then animate the bump. The loser lands safely inside the screen and gets back up.
+
+Two full size elders may not fit side by side in 32 pixels. Give this game purpose drawn compact poses, at most 12 pixels wide per pet, with room between them. Keep identity and expression. Do not squash runtime sprites to make them fit. No networking or second saved pet is needed.
+
+## Check it
+
+Test target edges, early presses, repeated taps, timeout and pause while the meter moves. Input timing must be based on elapsed time, not frame count. With reduced motion, use a short pose change instead of a fall. Verify both opponents remain visible.
+
+Slower pace doubles the meter cycle to 3.2 seconds. The target regions and six second timeout stay the same.

package/dist/design/games/catalog.md

@@ -0,0 +1,24 @@
+# Games still to cover
+
+Research todo. This is not a complete list of every Tamagotchi game.
+
+## Confirmed Connection set
+
+The [2024 Bandai manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/) lists Get, Bump, Flag, Heading, Memory, Sprint and Hoops. It also has connected play using Gotchi points and items. Those multiplayer activities need a separate design if we add them.
+
+## Older versions add more
+
+| Device | More names to research |
+| --- | --- |
+| Connection V4 | Jumping Rope, Mimic, Shape, Dance. Flag is already on our list. |
+| Connection V4.5 | Climb, Tug of War, Apple, Shapes, Manhole |
+
+These are catalog leads from the community's [V4 page](https://tamagotchi.fandom.com/wiki/Tamagotchi_Connection_Version_4) and [V4.5 page](https://tamagotchi.fandom.com/wiki/Tamagotchi_Connection_Version_4.5). Check the device manuals or captured gameplay before writing exact rules. Shape and Shapes may share a name without sharing a game.
+
+## The full catalog pass
+
+Work through Gen 1 and Gen 2 (P1 and P2), Connection V1 through V6 including V4.5 and V5.5, Japanese releases, later color devices, Nano releases and downloadable games. Track school, work, item and connected activities separately. Console, mobile and TamaTown games need an explicit scope decision before treating them as widget games.
+
+For each entry, record its device, region, game name, controls, objective and source. Mark reused mechanics so we do not add the same game twice under different names. Separate verified rules from our proposed timing, rewards and screen layout.
+
+Every selected game gets its own short design doc before implementation. The seven Connection designs are a starting set, not a claim that the wider catalog is finished.

package/dist/design/games/flag.md

@@ -0,0 +1,19 @@
+# Flag
+
+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/) has the pet raise flags to match arrows while ignoring imitation cues.
+
+## Our version
+
+Left and Right raise the matching flag. A Both button handles paired cues on touch. Keyboard players can use Space for Both. When the cue says Fake! Wait, leave all three buttons alone until the next cue. Waiting is the answer. Mark fake cues with a different shape, not color alone.
+
+Play 15 cues. Get 12 right to win. Start with a 900 ms preparation beat, then allow 2.4 seconds per cue and a 900 ms rest between cues. Slower mode gives four seconds per cue. No repeated tapping for extra points.
+
+## Screen and art
+
+Put the cue above the display. Draw the pet holding lowered, left, right or both flags inside it. Keep the score and response timer below. Flags must fit beside the widest pets. Use the same full pet shown in the care screen.
+
+## Check it
+
+Test every cue type, fake cues, input at timeout, held keys and pause. One cue has one result. Do not require simultaneous touch presses. Include a slower mode and spoken cue labels before approving accessibility.

package/dist/design/games/get.md

@@ -0,0 +1,21 @@
+# Get
+
+Included in 2.0. Follow the [shared game rules](README.md).
+
+Catch falling notes. Avoid poop. This is the objective in the [Connection manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/).
+
+## Our version
+
+Left and Right move the pet between three lanes. Use the arrow keys on a keyboard. Holding a direction moves with a capped repeat rate, never faster on a faster device.
+
+Run for 30 seconds. A note gives one point. Missing a note costs no life. Catching poop costs one of three lives. Finish with at least 12 notes and a life left to win. Falling speed increases in three gentle steps. These values need playtesting.
+
+## Screen and art
+
+Keep the pet at the bottom and the falling objects above it. Use small, distinct note and poop shapes. A hit triggers a brief happy or startled pose. The score, lives and remaining time go below the display.
+
+Use the actual pet's bounds for lanes and spawn timing. Leave enough vertical warning for the tallest sprite. Spawn only one object at a time in the first version. Never make a hazard unavoidable. If 32 by 16 is too cramped, revise this layout before implementation rather than hiding part of the pet.
+
+## Check it
+
+Test lane boundaries, notes versus poop, missed notes, last life, timeout and pause during a fall. A single collision can score only once. Compare touch and keyboard play, and inspect the largest pets at full scale.

package/dist/design/games/heading.md

@@ -0,0 +1,23 @@
+# Heading
+
+Included in 2.0. Follow the [shared game rules](README.md).
+
+Move under the ball and jump to head it back up. This follows the [Connection manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/).
+
+## Our version
+
+Use Left, Jump and Right below the display. Left and Right arrow keys move. Up or Space jumps. The pet can move while a jump is in progress, but cannot jump again until it lands.
+
+A successful header adds one point and sends the ball upward. Ten headers win. Three missed balls end the run. After a miss, give a one second countdown before the next ball. Slightly increase speed after every third header. Cap the run at 45 seconds.
+
+## Screen and art
+
+Show a small ball, the pet and a ground line. Score and misses sit below the display. Contact follows the occupied pixels in the upper half of the current pet. A rising head can meet a falling ball between frames.
+
+Use the full current pet in a 32 by 24 game field, with room for the ball and jump. Keep a bounded arc so the ball never clips at the top. New serves must be reachable from the pet's current position.
+
+## Check it
+
+Test edge headers, misses, movement during jumps, repeat input and pause midair. One contact gives one point. Collision results must match at slow and fast frame rates. Review jump timing on touch without requiring simultaneous tiny button presses.
+
+Slower pace runs movement at 60% speed and allows 75 seconds. The countdown and jump slow down with the ball. Scoring stays the same.

package/dist/design/games/hoops.md

@@ -0,0 +1,17 @@
+# Hoops
+
+Included in 2.0. Follow the [shared game rules](README.md).
+
+Time a shot into a basketball hoop, as described in the [Connection manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/).
+
+## Our version
+
+Shoot or Space stops an aim meter. Make the basket when the marker lands in its visible target. Play five shots and score three to win. Narrow the target slightly after each successful shot. Press Shoot once to start the meter, then again to take the shot. The meter travels out and back in 2.4 seconds, or four seconds in slower mode. The ball takes 900 ms to land. Target edges count as a hit.
+
+## Screen and art
+
+Pet on the left, hoop on the right, ball between them. Put the meter and shot count below the display. Keep the full current pet visible. A made shot crosses the rim from above, then drops through the net. Early shots fall short and late shots go past the rim. Keep misses inside the canvas too.
+
+## Check it
+
+The ball animation must agree with the meter result. Test target boundaries, repeated inputs, pause during aiming and pause during the ball arc. Do not award a basket twice when resuming. Reduced motion can show the release and landing poses without a full arc.

package/dist/design/games/left-right.md

@@ -0,0 +1,30 @@
+# Left and right
+
+Added in the patch before 2.0.
+
+## The fix
+
+The pet turns toward its answer before showing the happy or sad reaction. Direction text stays visible for the full reveal.
+
+## What should happen
+
+Show a neutral pet while waiting. After the player chooses, turn the pet toward the selected game direction. Hold that pose for roughly 700 ms, then show the happy or sad reaction for the rest of the existing 1,200 ms reveal. Keep the direction text visible throughout.
+
+Left and right mean the viewer's left and right. The pet turns toward its answer, even when the player guesses wrong. Never reveal the answer early.
+
+## Sprites
+
+Add explicit `lookLeft` and `lookRight` frames for every hatched identity in all four families. Give front facing pets an obvious eye, face or body turn. Keep markings such as 404 readable. A small move across the screen or a flipped symmetrical sprite does not count.
+
+Fit both poses in the existing 16 by 16 game canvas. Keep the whole pet visible. Review Gen 1, Gen 2, Slice, Cypunk and Lilgotchi from baby through elder.
+
+## Done when
+
+1. Both directions are obvious without reading the result text, including on symmetrical eggs and pizza faces.
+2. The shown direction always matches the result and scoring, for wins and losses.
+3. Five rounds, winning odds, rewards and weight changes stay as they are.
+4. Closing, restarting, switching pets or entering vacation cancels the pending reaction. Old callbacks cannot repaint a new run.
+5. Reduced motion still shows the directional pose. Text reports the answer for screen readers and muted play.
+6. Tests cover every directional frame, forced left and right outcomes, both result reactions and stale timers. Browser proof shows both turns at desktop and mobile sizes.
+
+[Game plan](README.md)

package/dist/design/games/memory.md

@@ -0,0 +1,21 @@
+# Memory
+
+Included in 2.0. Follow the [shared game rules](README.md).
+
+Watch arrows and repeat their order. The [Connection manual](https://www.bandai.com/amfile/file/download/file/242/product/1304058/) uses left, up and right.
+
+## Our version
+
+Show a sequence, then let the player repeat it with Left, Up and Right. Match those directions on the keyboard. Start with two arrows and add one each round. Complete five rounds to win. One wrong answer ends the run. No timer during the player's response.
+
+Show each cue for 600 ms with a 200 ms gap. Identical consecutive arrows still get a clear gap. Slower playback uses one second cues and 350 ms gaps. Select it before Start. The sequence stays fixed for the run. Show each entered direction for 450 ms. After a correct round, leave that last answer visible before starting the next sequence.
+
+## Screen and art
+
+The pet watches during playback and reacts to the player's answer. Put one large arrow at a time in a cue area above the display, with Watch or Your turn beside it. Do not cover the pet with the whole sequence. Put progress below the display.
+
+Directional labels and short tones are paired with the arrows. Announce each playback cue, then announce when input opens. Reduced motion uses static arrows with no flashing or bouncing.
+
+## Check it
+
+Ignore guesses during playback and ignore held key repeats. Test repeated directions, wrong answers, the fifth round and pause in both phases. Resuming interrupted playback restarts that sequence without changing it. Exiting cancels every queued cue.

package/dist/design/games/polish-review.md

@@ -0,0 +1,11 @@
+# Game polish review
+
+The game screen is now 32 by 24 pixels. It draws the current pet's full sprite and colors. Opponents stay separate.
+
+Finished games show Play again and Back to games. Input controls disappear after the result. Left and right uses the same screen shape and keeps an exit available. Mobile controls fit their columns.
+
+Heading checks the visible upper head pixels and accounts for the head rising during a jump. Hoops crosses the rim from above and falls through a visible net. Memory shows cue and answer poses. Flag gives a preparation beat, a longer response window and an X for waiting. Sprint shows red, yellow and green lights.
+
+254 tests pass. The build passes. Browser review used 390 and 320 pixel widths. It covered the picker, guessing result and replay, arcade replay, Memory cue and answer poses, raised flags, Sprint lights, a successful Heading contact and a made Hoops shot. Frozen review scenes use real game models with fixed time inputs. They are not full human playthroughs.
+
+Physical phone and longer human balance checks still need doing. These changes are in review, not deployed.