@fluritheme/grinch 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1 — 2026-11-14
+
+- Point the npm Homepage link to https://fluri.xyz/. The Grinch playground and documentation remain at grinch.fluri.xyz.
+- Keep the animation runtime unchanged.
+
+## 0.1.0 — 2026-11-14
+
+- Introduce an original animated green holiday visitor with articulated limbs, blinking, a gift sack and three entrance styles.
+- Add gift heists with approach, climb, reach, lift, stash and celebration phases.
+- Add object-aware hiding, peeking, pointer reactions, tap-to-catch, animated returns and a kindness mode.
+- Anchor gifts to document elements and support root clipping, nested scrolling and live layout changes.
+- Provide a typed controller, events, live tuning, reduced-motion support, pause, SSR-safe imports and complete cleanup.
+- Include a responsive playground, real runtime previews and framework integration examples.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluri contributors
+
+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,189 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# Grinch by Fluri
+
+**A little green. A little greed. A lot of personality.**
+
+A mischievous holiday visitor who sneaks around your website, steals presents, hides behind cards, and discovers a softer side of Christmas.
+
+[![npm version](https://grinch.fluri.xyz/npm-version.svg)](https://www.npmjs.com/package/@fluritheme/grinch)
+[![npm downloads](https://img.shields.io/npm/dm/%40fluritheme%2Fgrinch?color=c92c42&label=downloads)](https://www.npmjs.com/package/@fluritheme/grinch)
+[![MIT license](https://img.shields.io/badge/license-MIT-1f6544)](https://github.com/fluritheme/grinch/blob/main/LICENSE)
+
+[Live playground](https://grinch.fluri.xyz/) · [All Fluri themes](https://fluri.xyz/) · [Source](https://github.com/fluritheme/grinch)
+
+![Grinch's holiday heist playground](https://grinch.fluri.xyz/readme/playground.png)
+
+</div>
+
+## Meet your website's least innocent resident
+
+- **An actual little heist.** He approaches a present, reaches for it, lifts it, and puts it in his sack. Presents stay on their ledges until he picks them up.
+- **Real places to hide.** He ducks behind page objects, peeks out, then climbs back onto a ledge. The sack gets fuller with every successful theft.
+- **Catch him in the act.** Move the pointer close or tap him to startle him. A stolen present flies back to its original element.
+- **A change of heart.** Kindness mode warms his heart, returns the entire sack, and turns him into a friendly visitor.
+- **A proper entrance.** Sneak in from the side, descend on a white rope, or appear immediately.
+- **Your content stays yours.** Presents are illustrated props. Buttons, images, text and links are never stolen or rearranged.
+- **Small and considerate.** Zero runtime dependencies, no runtime network requests, bounded gift count, one Canvas, reduced-motion support, pause/resume and complete cleanup.
+
+![Stealing a present and discovering kindness](https://grinch.fluri.xyz/readme/routines.png)
+
+These previews come from the running package. The character and presents are original procedural vector artwork, rendered in Canvas.
+
+## Install
+
+Add a little holiday mischief to any website. No CSS import, API key or runtime network request. Try every behavior in the [playground](https://grinch.fluri.xyz/).
+
+```sh
+npm i @fluritheme/grinch
+```
+
+```ts
+import { createGrinch } from '@fluritheme/grinch';
+
+const visitor = createGrinch({
+  targets: '[data-grinch-gift]',
+});
+
+// When the page unmounts:
+visitor.destroy();
+```
+
+Mark a few elements with room above them for a tiny visitor and a present:
+
+```html
+<article data-grinch-gift data-grinch-object>A little room for holiday mischief.</article>
+```
+
+Without `targets`, the package uses `[data-grinch-gift]` elements first, then common cards and buttons. Use `[data-grinch-ignore]` on an element or ancestor to exclude it. `data-grinch-object` marks objects he can hide behind; the default object selector also recognizes cards, images, articles and buttons.
+
+## Try a different ending
+
+```ts
+visitor.steal(); // Start a heist when he is ready
+visitor.steal('#special-card'); // Choose a tracked gift
+visitor.shoo(); // Catch him and return one present
+visitor.returnGifts(); // Return the sack along animated arcs
+visitor.redeem(); // Return everything; switch to friendly
+visitor.wave(); // Say hello
+
+visitor.update({ size: 1.2, speed: 0.8, fearRadius: 120 });
+visitor.update({ mood: 'mischievous' }); // Allow mischief again
+visitor.pause();
+visitor.resume();
+visitor.refresh(); // Request a layout measurement
+```
+
+`steal()` returns `false` while he is busy, paused, in friendly mode, or respecting reduced motion. A selector must match a gift already tracked by this instance. Calls do not queue extra thefts.
+
+## React / Next.js
+
+Create the visitor after mounting, and return its cleanup. For Next.js, use a client component.
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { createGrinch } from '@fluritheme/grinch';
+
+export function HolidayVisitor() {
+  useEffect(() => {
+    const visitor = createGrinch({ targets: '[data-grinch-gift]' });
+    return () => visitor.destroy();
+  }, []);
+
+  return <article data-grinch-gift>Your holiday card</article>;
+}
+```
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createGrinch, type GrinchController } from '@fluritheme/grinch';
+
+let visitor: GrinchController | undefined;
+onMounted(() => {
+  visitor = createGrinch();
+});
+onUnmounted(() => visitor?.destroy());
+</script>
+
+<template>
+  <article data-grinch-gift>Your holiday card</article>
+</template>
+```
+
+## Keep him inside a section
+
+```ts
+const root = document.querySelector<HTMLElement>('#holiday-section')!;
+const visitor = createGrinch({ root, territory: 'root' });
+```
+
+This clips the scene to the root's rectangle and selects gifts from inside it. The default `territory: 'page'` allows movement around the document. Coordinates are anchored to the document, so scrolling does not attach the visitor to your viewport. Nested scrolling and moving gift anchors are measured too.
+
+## Options
+
+| Option        | Default               | Purpose                                  |
+| ------------- | --------------------- | ---------------------------------------- |
+| `root`        | `document`            | Element to search for gifts              |
+| `targets`     | Automatic             | CSS selector or array of elements        |
+| `territory`   | `'page'`              | `'page'` or `'root'`                     |
+| `objects`     | Common cards/elements | Selector for objects he can hide behind  |
+| `maxGifts`    | `5`                   | Maximum tracked presents, 1–12           |
+| `size`        | `1`                   | Character and present scale, 0.6–1.8     |
+| `mobileScale` | `0.85`                | Additional scale below 600px, 0.6–1      |
+| `speed`       | `1`                   | Movement multiplier, 0.25–2              |
+| `cooldown`    | `10`                  | Seconds between completed heists, 3–120  |
+| `fearRadius`  | `90`                  | Pointer reaction radius; `0` disables it |
+| `mood`        | `'mischievous'`       | Or `'friendly'` for a gentler visitor    |
+| `autoSteal`   | `true`                | Start heists automatically               |
+| `entrance`    | `'sneak'`             | `'sneak'`, `'rope'`, or `'appear'`       |
+| `motion`      | `'system'`            | `'system'`, `'full'`, or `'none'`        |
+| `observe`     | `true`                | Observe layout and content changes       |
+| `zIndex`      | `140`                 | Canvas stacking position                 |
+| `furColor`    | `'#79ad30'`           | Six-digit hex color                      |
+| `coatColor`   | `'#c92c42'`           | Six-digit hex color                      |
+| `controls`    | `false`               | Add an accessible visitor pause button   |
+
+`update()` accepts size, mobileScale, speed, cooldown, fearRadius, mood, autoSteal, furColor and coatColor. Configuration is validated before mounting; invalid values throw. The palette stays stable when he crosses dark or light content.
+
+## Events and state
+
+```ts
+const stop = visitor.on('gift:stolen', ({ giftId, totalStolen }) => {
+  console.log(giftId, totalStolen);
+});
+
+visitor.on('redeemed', () => console.log('A little kindness wins.'));
+const snapshot = visitor.getState();
+console.log(snapshot.phase, snapshot.stolen, snapshot.gifts);
+stop();
+```
+
+Events: `ready`, `phase`, `theft:start`, `gift:stolen`, `gift:returned`, `caught`, `redeemed`, `error`. `getState()` returns a copy with lifecycle, mood, phase, character coordinates, gift states, current stolen count, lifetime total and caught count. Coordinates are CSS pixels in the document; character coordinates describe his feet.
+
+## Motion, rendering and layout
+
+The default respects `prefers-reduced-motion`: a still resident, no automatic thefts. Hidden tabs stop animation. `pause()` freezes the routine while retaining layout measurements; `destroy()` removes the Canvas, controls, observers, event listeners and animation loop. Importing on the server is safe and does not create a browser instance.
+
+The Canvas ignores pointer events, so website controls remain clickable. Hosts can provide keyboard-accessible buttons calling `shoo()`, `redeem()` and `pause()`, as the playground does. Hiding uses the visible rectangles, rounded corners and 2D transforms of matching objects. It approximates browser stacking rather than reproducing arbitrary CSS masks, 3D transforms, shadow DOM or every stacking context. Give the character roughly 145 × `size` pixels of room above a ledge. Targets need a visible box at least 48px wide.
+
+Grinch can coexist with [Winter](https://winter.fluri.xyz/) or [Spider](https://spider.fluri.xyz/); each has its own controller. Keep active effects and gift counts modest on smaller devices.
+
+## Develop
+
+Node.js 22.12+ and pnpm 10.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm exec playwright install --with-deps
+pnpm check
+pnpm dev
+```
+
+The suite covers the heist and return state machine, configuration, SSR, cleanup, scrolling, mobile layout, host interactions and reduced motion across Chromium, Firefox, WebKit and iPhone-sized WebKit.
+
+MIT. Built by [František Gejdoš](https://fluri.xyz/founder/), founder of [Fluri](https://fluri.xyz/).

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { GrinchController, GrinchOptions } from './types.js';
+export type { Box, GiftState, GrinchController, GrinchEvent, GrinchEventData, GrinchMood, GrinchOptions, GrinchPhase, GrinchSnapshot, GrinchTuning, Point, } from './types.js';
+export { defaults } from './options.js';
+/** A decorative, page-aware visitor. The runtime performs no network requests and never moves host content. */
+export declare function createGrinch(input?: GrinchOptions): GrinchController;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,gBAAgB,EAGhB,aAAa,EAId,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,GAAG,EACH,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,UAAU,EACV,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,EACZ,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAWxC,+GAA+G;AAC/G,wBAAgB,YAAY,CAAC,KAAK,GAAE,aAAkB,GAAG,gBAAgB,CAsfxE"}