oneko 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 0xdhrv
+
+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,98 @@
-# Temporary Holding Version
+# oneko
 
-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.
+A tiny pixel cat that follows the pointer, naps when things are quiet, and shares cat-themed
+thoughts. The engine and all 24 coats ship in the package, so nothing loads from a CDN.
+
+[Playground](https://oneko.dhrv.pw) · [Studio](https://oneko.dhrv.pw/studio) ·
+[Documentation](https://oneko.dhrv.pw/docs)
+
+```bash
+npm install oneko
+```
+
+Every entry mounts one cat on `document.body` and takes the same options. See the
+[prop reference](https://oneko.dhrv.pw/docs#props).
+
+## React
+
+```tsx
+import Oneko from "oneko";
+
+export function CatLayer() {
+  return <Oneko skin="calico" bubbleText="treat inspection in progress" />;
+}
+```
+
+The entry is marked `"use client"`, so Next.js App Router can import it from a server component.
+
+## Vue
+
+```vue
+<script setup>
+import Oneko from "oneko/vue";
+</script>
+
+<template>
+  <Oneko skin="calico" :speed="12" @state-change="console.log" />
+</template>
+```
+
+## Svelte 5
+
+```svelte
+<script>
+  import Oneko from "oneko/svelte";
+</script>
+
+<Oneko skin="calico" />
+```
+
+## Solid
+
+```tsx
+import Oneko from "oneko/solid";
+
+export default function App() {
+  return <Oneko skin="calico" />;
+}
+```
+
+## Without a framework
+
+```ts
+import { createOneko } from "oneko/vanilla";
+
+const cat = createOneko({ skin: "tuxedo" });
+cat.update({ scale: 2 });
+cat.destroy();
+```
+
+Importing any entry during SSR has no DOM side effects. The cat mounts in the browser.
+
+## Skins
+
+`ONEKO_SKINS` lists the 24 coats with names and descriptions. The classic coat is inline; the
+others load in one chunk the first time a non-classic coat is used. Pass `spriteSrc` for your own
+256 × 128 sprite sheet.
+
+## Sounds
+
+Meows are off by default. The sound files ship in `oneko/cat-sounds/`. Copy them to a folder your
+site serves and point `soundBasePath` at it:
+
+```bash
+cp -r node_modules/oneko/dist/cat-sounds public/cat-sounds
+```
+
+```tsx
+<Oneko meow soundBasePath="/cat-sounds" />
+```
+
+## Hide toggle
+
+`setCatsHidden(true)` hides every cat and remembers the choice. `areCatsHidden()` and
+`onCatsHiddenChange()` let you build your own toggle.
+
+## License
+
+MIT. The sprite artwork belongs to its original creators; see `SKIN-CREDITS.md`.

package/SKIN-CREDITS.md

@@ -0,0 +1,61 @@
+# Pixel-art skins
+
+Oneko includes 24 sprite sheets: 12 original sheets and 12 generated variants. Each is a 256 × 128 PNG with an 8 × 4 grid of
+32-pixel frames, using the animation layout of [adryd325/oneko.js](https://github.com/adryd325/oneko.js).
+
+The 12 original sheets were sourced from [oneko-swift](https://github.com/oneko-swift/oneko-swift/tree/8cc42f0689c009ec53561d5022597fccd7469337/Resources)
+at revision `8cc42f0689c009ec53561d5022597fccd7469337`. Artwork belongs to its original creators;
+this project's MIT code license does not relicense the sprite art.
+
+| Skin ID                                                             | Credit / original source                                                                                                  |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `classic`                                                           | Masayuki Koba's original X11 oneko, via [adryd325/oneko.js](https://github.com/adryd325/oneko.js)                         |
+| `tora`                                                              | Original X11 bitmaps from [tie/oneko](https://github.com/tie/oneko), assembled with cat transparency masks by oneko-swift |
+| `catppuccin`                                                        | [k01e-01/catppuccineko](https://github.com/k01e-01/catppuccineko), MIT, using Catppuccin colors                           |
+| `maia`, `vaporwave`                                                 | [kyrie25/spicetify-oneko](https://github.com/kyrie25/spicetify-oneko)                                                     |
+| `black`, `gray`, `calico`, `ghost`, `silver`, `spirit`, `valentine` | Community art from the [Oneko Source Database](https://github.com/tallypaws/oneko_db), as credited by oneko-swift         |
+
+See the upstream [credits](https://github.com/oneko-swift/oneko-swift#credits) for provenance.
+
+## Use a skin
+
+```tsx
+<Oneko skin="calico" meow={false} />
+```
+
+Changing `skin` swaps the coat in place without resetting the cat's position or activity. Unknown
+skin IDs fall back to `classic`. `hueRotate` remains available for tinting; selecting a coat in the
+playground clears the tint to show the original art.
+
+`lib/oneko/skins.ts` is the typed catalog. `lib/oneko/skin-sheets.json` contains the bundled PNG bytes
+as data URLs, so the component and its previews work without third-party image requests. Sites with
+a Content Security Policy should allow `data:` in `img-src`. The 12 original sheets remain unmodified.
+
+To add a coat, preserve the original file and attribution, add its data URL and catalog entry, then
+run `pnpm test` and `pnpm run registry:build`. The skin tests decode every sheet and check that every
+animation frame contains visible pixels.
+
+## Your own sprite sheet
+
+Open **Appearance → Use your own sprite** in the studio (`/studio`) to download the classic sheet as a template and
+upload a PNG up to 256 KB. Use 256 × 128 pixels: 8 columns and 4 rows of 32 × 32 frames.
+Keep the template’s frame positions so walking, grooming, wall scratching, and naps match the
+animation. Transparent backgrounds work best. Preserve the original artwork credits when adapting it.
+
+Uploads stay in your browser and persist with your preferences. Selecting a built-in coat or
+resetting the cat removes the upload. The generated React example embeds the uploaded sheet;
+for a hosted asset, use `<Oneko spriteSrc="/my-sprite.png" />`. `spriteSrc` overrides `skin`
+and updates without resetting position. Omit it to return to the selected built-in coat.
+
+## Generated coat variants
+
+`ginger`, `sage`, `siamese`, `strawberry-milk`, `blue-frost`, `lavender`, `tuxedo`, `peach`, `honey`, `mocha`, `mint`, and `midnight-blue` were generated with
+the built-in image generation tool using Classic as a reference. Original artwork
+credits still apply. These variants reinterpret some pose details rather than
+preserving the original pixels exactly.
+
+Source artwork and prompts live in `output/skins/`. Run
+`node scripts/prepare-generated-skins.mjs` to prepare 256 × 128 PNGs with nearest-neighbor
+sampling and binary transparency and embed them in the catalog. Then run
+`pnpm run registry:build`. Every variant is available in the studio and exported
+React examples through its skin ID.

package/dist/adapter.d.ts

@@ -0,0 +1 @@
+export * from "./types/packages/oneko/src/adapter";

package/dist/adapter.js

@@ -0,0 +1,11 @@
+function createPropsUpdater(cat) {
+  let previous = {};
+  return (next) => {
+    const reset = Object.fromEntries(Object.keys(previous).map((key) => [key, void 0]));
+    cat.update({ ...reset, ...next });
+    previous = next;
+  };
+}
+export {
+  createPropsUpdater
+};

package/dist/cat-sounds/Cat_royal_ambient5.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Cat_royal_ambient6.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Cat_royal_death.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Cat_royal_hurt1.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Cat_royal_hurt2.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Cat_royal_hurt3.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Stray_cat_idle1.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Stray_cat_idle2.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Stray_cat_idle3.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".

package/dist/cat-sounds/Stray_cat_idle4.ogg

@@ -0,0 +1 @@
+Forbidden. Calls to this URL via the terminal are not allowed. To save the url contents to the container, open the url in the computer tool, right click anywhere, and click "Save As...".