page-mascot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamran Ahmed <https://kamran.fyi>
+
+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

@@ -0,0 +1,91 @@
+<img src=".github/fox.png" width="160" alt="">
+
+# page-mascot
+
+A character for the top of your page. It follows the reader's cursor and blinks when they
+poke it. Fifty-two are already drawn. An agent skill draws new ones, or one that looks
+like you.
+
+## Install
+
+```bash
+npm i page-mascot
+```
+
+## Use one that is drawn
+
+Pick a character on the [demo page](https://koboyo.com/page-mascot) and download its two
+sheets into `public/mascots`, then point the component at them:
+
+```tsx
+import { Mascot } from 'page-mascot'
+
+<Mascot
+  directions="/mascots/fox-directions.webp"
+  reactions="/mascots/fox-reactions.webp"
+/>
+```
+
+The paths are whatever your app serves, so imported images work too.
+
+Or let an agent do it, once the skill below is installed:
+
+```
+/page-mascot put the fox on my page
+```
+
+## Draw your own
+
+Install the skill:
+
+```bash
+npx skills add nilbuild/page-mascot --skill page-mascot --global --yes
+```
+
+Then ask your agent:
+
+```
+/page-mascot a chibi otter with chocolate-brown fur
+/page-mascot make one that looks like me        [attach a photo]
+/page-mascot a chibi fox, in the riso style
+```
+
+It draws the nine directions and nine expressions, builds them into two aligned sheets,
+checks the character does not jump between them, and puts the component on your page, with
+the same two props as above.
+
+Drawing needs an image tool. Codex has one. Claude Code uses the OpenAI images API, so set
+`OPENAI_API_KEY` first. With neither, `skills/page-mascot/reference/prompts.md` has the
+prompts for making the sheets by hand in any chat UI.
+
+## Props
+
+| prop | default | |
+| --- | --- | --- |
+| `directions` | none | path to the directions sheet |
+| `reactions` | none | path to the reactions sheet |
+| `size` | `140` | px, square |
+| `label` | `'mascot'` | what a screen reader calls it |
+| `className` | | |
+
+Tracking switches off without a fine pointer, and the click squash honours
+`prefers-reduced-motion`.
+
+## How it works
+
+Each character is two 3×3 sprite sheets: nine head directions, and nine expressions.
+
+![the two sheets that make up one character](.github/sheets.png)
+
+The pointer's angle picks a cell on the directions sheet, with a dead zone so the head
+settles when the cursor is close. A click shows a cell from the reactions sheet for half a
+second. One `background-position` and no animation library.
+
+The same character can be drawn in six styles: colour, ink, sketch, riso, paper and pixel.
+Only the rendering changes, so the alignment holds.
+
+![the same fox drawn in six styles](.github/styles.png)
+
+## License
+
+MIT © [Kamran Ahmed](https://kamran.fyi)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Mascot } from './mascot.js';
+export type { MascotProps } from './mascot.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { Mascot } from './mascot.js';

package/dist/mascot.d.ts

@@ -0,0 +1,11 @@
+export type MascotProps = {
+    /** The 3x3 sheet of head directions. A served path, or an imported image. */
+    directions: string;
+    /** The 3x3 sheet of expressions. */
+    reactions: string;
+    size?: number;
+    className?: string;
+    /** What a screen reader calls it. */
+    label?: string;
+};
+export declare function Mascot(props: MascotProps): import("react").JSX.Element;

package/dist/mascot.js

@@ -0,0 +1,168 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+const DIRECTIONS = [
+    'up-left',
+    'up',
+    'up-right',
+    'left',
+    'center',
+    'right',
+    'down-left',
+    'down',
+    'down-right',
+];
+const REACTIONS = [
+    'blink',
+    'heart',
+    'sparkle',
+    'surprised',
+    'wink',
+    'bashful',
+    'sleepy',
+    'dizzy',
+    'delighted',
+];
+// Clockwise from the right, matching atan2 with y pointing down.
+const CLOCKWISE = [
+    'right',
+    'down-right',
+    'down',
+    'down-left',
+    'left',
+    'up-left',
+    'up',
+    'up-right',
+];
+const SECTOR = (Math.PI * 2) / CLOCKWISE.length;
+const HYSTERESIS = 0.12;
+const DEAD_ZONE = 70;
+const PAYOFFS = ['heart', 'sparkle', 'delighted'];
+const BOOP_PAYOFF = 120;
+const BOOP_END = 560;
+const SQUASH_MS = 420;
+const DIZZY_AFTER = 4;
+const DIZZY_WINDOW = 1600;
+const DIZZY_END = 1100;
+const SQUASH = [
+    { transform: 'scale(1, 1)', easing: 'ease-in' },
+    { transform: 'scale(1.10, 0.86)', offset: 0.18, easing: 'ease-out' },
+    { transform: 'scale(0.95, 1.08)', offset: 0.45, easing: 'ease-in-out' },
+    { transform: 'scale(1.03, 0.97)', offset: 0.72, easing: 'ease-in-out' },
+    { transform: 'scale(1, 1)' },
+];
+// background-size 300% makes each cell a clean 0/50/100% step on both axes.
+function cell(index) {
+    return { backgroundPosition: `${(index % 3) * 50}% ${Math.floor(index / 3) * 50}%` };
+}
+function wrap(angle) {
+    return Math.atan2(Math.sin(angle), Math.cos(angle));
+}
+const layer = {
+    position: 'absolute',
+    inset: 0,
+    backgroundSize: '300% 300%',
+    backgroundRepeat: 'no-repeat',
+};
+export function Mascot(props) {
+    const { directions, reactions, size = 140, className, label = 'mascot' } = props;
+    const buttonRef = useRef(null);
+    const squashRef = useRef(null);
+    const timersRef = useRef([]);
+    const boopsRef = useRef({ count: 0, at: 0 });
+    const [direction, setDirection] = useState('center');
+    const [reaction, setReaction] = useState(null);
+    useEffect(() => {
+        if (!window.matchMedia('(hover: hover) and (pointer: fine)').matches) {
+            return;
+        }
+        let sector = -1;
+        let pointer = null;
+        const aim = () => {
+            const button = buttonRef.current;
+            if (!button || !pointer) {
+                return;
+            }
+            const box = button.getBoundingClientRect();
+            const dx = pointer.x - (box.left + box.width / 2);
+            const dy = pointer.y - (box.top + box.height / 2);
+            if (Math.hypot(dx, dy) < DEAD_ZONE) {
+                sector = -1;
+                setDirection('center');
+                return;
+            }
+            // Hold the current sector until the pointer is well past its edge.
+            const angle = Math.atan2(dy, dx);
+            if (sector !== -1 && Math.abs(wrap(angle - sector * SECTOR)) < SECTOR / 2 + HYSTERESIS) {
+                return;
+            }
+            sector = (Math.round(angle / SECTOR) + CLOCKWISE.length) % CLOCKWISE.length;
+            setDirection(CLOCKWISE[sector]);
+        };
+        const onPointerMove = (event) => {
+            pointer = { x: event.clientX, y: event.clientY };
+            aim();
+        };
+        window.addEventListener('pointermove', onPointerMove, { passive: true });
+        window.addEventListener('scroll', aim, { passive: true });
+        return () => {
+            window.removeEventListener('pointermove', onPointerMove);
+            window.removeEventListener('scroll', aim);
+        };
+    }, []);
+    useEffect(() => {
+        return () => {
+            timersRef.current.forEach(window.clearTimeout);
+        };
+    }, []);
+    const boop = () => {
+        timersRef.current.forEach(window.clearTimeout);
+        timersRef.current = [];
+        const later = (ms, next) => {
+            timersRef.current.push(window.setTimeout(() => setReaction(next), ms));
+        };
+        const now = Date.now();
+        const boops = boopsRef.current;
+        boops.count = now - boops.at < DIZZY_WINDOW ? boops.count + 1 : 1;
+        boops.at = now;
+        if (boops.count >= DIZZY_AFTER) {
+            boops.count = 0;
+            setReaction('dizzy');
+            later(DIZZY_END, null);
+        }
+        else {
+            setReaction('blink');
+            later(BOOP_PAYOFF, PAYOFFS[(boops.count - 1) % PAYOFFS.length]);
+            later(BOOP_END, null);
+        }
+        if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+            return;
+        }
+        // Per-keyframe easing with the effect itself linear: an easing on the effect
+        // would reinterpret every offset and front-load the whole bounce.
+        squashRef.current?.animate(SQUASH, { duration: SQUASH_MS, easing: 'linear' });
+    };
+    // Inline styles so the file drops into any project without a CSS framework.
+    return (_jsx("button", { ref: buttonRef, type: "button", onClick: boop, "aria-label": `Boop the ${label}`, className: className, style: {
+            position: 'relative',
+            display: 'block',
+            flexShrink: 0,
+            width: size,
+            height: size,
+            padding: 0,
+            border: 0,
+            background: 'transparent',
+            appearance: 'none',
+            cursor: 'pointer',
+            userSelect: 'none',
+        }, children: _jsxs("span", { ref: squashRef, style: { position: 'relative', display: 'block', width: '100%', height: '100%', transformOrigin: '50% 78%' }, children: [_jsx("span", { style: {
+                        ...layer,
+                        backgroundImage: `url(${directions})`,
+                        ...cell(DIRECTIONS.indexOf(direction)),
+                        opacity: reaction ? 0 : 1,
+                    } }), _jsx("span", { style: {
+                        ...layer,
+                        backgroundImage: `url(${reactions})`,
+                        ...cell(REACTIONS.indexOf(reaction ?? 'blink')),
+                        opacity: reaction ? 1 : 0,
+                    } })] }) }));
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "page-mascot",
+  "version": "0.1.0",
+  "description": "A character for the top of your page that follows the reader's cursor and blinks when they poke it.",
+  "license": "MIT",
+  "author": "Kamran Ahmed",
+  "homepage": "https://koboyo.com/page-mascot",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nilbuild/page-mascot.git"
+  },
+  "keywords": ["mascot", "avatar", "react", "cursor", "sprite", "portfolio"],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.build.json && cp src/mascot.tsx skills/page-mascot/mascot.tsx",
+    "build:site": "npm run typecheck && vite build",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "oxlint",
+    "preview": "vite preview",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.1.0",
+    "oxlint": "^1.79.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~6.0.2",
+    "vite": "^8.2.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}