@ranjeet_/digital-pet 0.2.0

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Digital Pet 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.

package/README.md

@@ -0,0 +1,283 @@
+# Digital Pet for the Web
+
+`@ranjeet_/digital-pet` is a framework-neutral Web Component that adds an
+animated companion to any website. The default pet is Shiro, a golden retriever,
+but the displayed name is customizable.
+
+## Features
+
+- Switchable 2D illustrated and 3D WebGL views
+- Golden-retriever coat, feathering, flexible tail, balls, and fetch animation
+- Sit, walk, run, jump, down, sleep, roll over, handshake, hi-five, salute,
+  namaste, speak, quiet, fetch, feed, treat, and surprise commands
+- Optional barking sound with volume controls
+- Cursor awareness, drag interaction, autonomous behavior, and corner naps
+- Small, normal, large, and extra-large sizes saved in `localStorage`
+- Accessible controls, Shadow DOM style isolation, reduced motion, and print handling
+- Works with plain HTML, React, Next.js, Vue, Nuxt, Angular, Svelte, SvelteKit,
+  Astro, and other frameworks that support Custom Elements
+
+## Install
+
+```bash
+npm install @ranjeet_/digital-pet
+```
+
+Import the package once in browser code:
+
+```js
+import "@ranjeet_/digital-pet";
+```
+
+Then render the custom element:
+
+```html
+<digital-pet
+  name="Shiro"
+  size="normal"
+  renderer="3d"
+  controls="true"
+  sound="false"
+></digital-pet>
+```
+
+## Direct Script
+
+Use the hosted ES module without a package manager:
+
+```html
+<script
+  type="module"
+  src="https://ranjeet447.github.io/digital-pet/downloads/digital-pet-v0.2.0.js"
+></script>
+
+<digital-pet renderer="3d" controls="true"></digital-pet>
+```
+
+Use the versioned URL in production so a later release cannot change behavior
+without an intentional update. `digital-pet.js` is also published as a moving
+alias for demos and users who explicitly want the latest version.
+
+## Frameworks
+
+### React and Next.js
+
+Load Digital Pet in a client component because it uses browser APIs:
+
+```tsx
+"use client";
+
+import { createElement, useEffect } from "react";
+
+export function DigitalPet() {
+  useEffect(() => {
+    void import("@ranjeet_/digital-pet");
+  }, []);
+
+  return createElement("digital-pet", {
+    name: "Shiro",
+    renderer: "3d",
+    controls: "true",
+    sound: "false",
+  });
+}
+```
+
+Render this component once in the root layout. `createElement` avoids requiring
+custom JSX type declarations.
+
+### Vue
+
+```vue
+<script setup>
+import "@ranjeet_/digital-pet";
+</script>
+
+<template>
+  <digital-pet renderer="3d" controls="true" />
+</template>
+```
+
+If Vue reports an unresolved component warning, configure the compiler:
+
+```js
+// vite.config.js
+vue({
+  template: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === "digital-pet",
+    },
+  },
+});
+```
+
+### Nuxt
+
+Create `plugins/digital-pet.client.ts`:
+
+```ts
+import "@ranjeet_/digital-pet";
+
+export default defineNuxtPlugin(() => {});
+```
+
+Add the Vue custom-element configuration in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === "digital-pet",
+    },
+  },
+});
+```
+
+### Angular
+
+Import the package in `main.ts`:
+
+```ts
+import "@ranjeet_/digital-pet";
+```
+
+Allow the Custom Element in the component:
+
+```ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+
+@Component({
+  selector: "app-root",
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<digital-pet renderer="3d" controls="true"></digital-pet>`,
+})
+export class AppComponent {}
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { onMount } from "svelte";
+
+  onMount(() => import("@ranjeet_/digital-pet"));
+</script>
+
+<digital-pet renderer="3d" controls="true"></digital-pet>
+```
+
+### SvelteKit
+
+Use the same component and import it inside `onMount`, or disable SSR for the
+small wrapper component that renders `<digital-pet>`.
+
+### Astro
+
+```astro
+<digital-pet renderer="3d" controls="true"></digital-pet>
+
+<script>
+  import "@ranjeet_/digital-pet";
+</script>
+```
+
+The Custom Element upgrades in the browser; no framework hydration directive is
+required.
+
+## JavaScript API
+
+```js
+import { mountDigitalPet } from "@ranjeet_/digital-pet";
+
+const shiro = mountDigitalPet({
+  name: "Shiro",
+  size: "normal",
+  renderer: "3d",
+  controls: true,
+  cursorInteraction: true,
+  sound: false,
+  volume: 0.65,
+  startCorner: "bottom-right",
+});
+
+shiro.command("sit");
+shiro.command("fetch");
+shiro.command("feed");
+shiro.command("treat");
+shiro.command("sleep");
+shiro.setSize("large");
+shiro.setRenderer("2d");
+shiro.bringToPointer();
+shiro.bringTo(500, 600);
+shiro.hide();
+shiro.show();
+```
+
+Commands:
+
+```text
+sit, walk, run, jump, down, sleep, roll-over, handshake, hi-five,
+salute, namaste, speak, quiet, fetch, feed, treat, surprise
+```
+
+Attributes:
+
+| Attribute | Values | Default |
+| --- | --- | --- |
+| `name` | any non-empty name | `Shiro` |
+| `size` | `small`, `normal`, `large`, `extra-large` | saved value or `normal` |
+| `remember-size` | `true`, `false` | `true` |
+| `controls` | `true`, `false` | `true` |
+| `renderer` | `2d`, `3d`, `auto` | `auto` |
+| `sound` | `true`, `false` | `false` |
+| `volume` | number from `0` to `1` | `0.65` |
+| `cursor-interaction` | `true`, `false` | `true` |
+| `start-corner` | `bottom-left`, `bottom-right` | `bottom-right` |
+| `z-index` | any valid integer | `2147483000` |
+
+Events:
+
+```js
+shiro.addEventListener("digital-pet-command", (event) => {
+  console.log(event.detail.command);
+});
+
+shiro.addEventListener("digital-pet-size-change", (event) => {
+  console.log(event.detail.size);
+});
+
+shiro.addEventListener("digital-pet-renderer-change", (event) => {
+  console.log(event.detail.renderer);
+});
+
+shiro.addEventListener("digital-pet-care", (event) => {
+  console.log(event.detail.action, event.detail.hunger);
+});
+
+shiro.addEventListener("digital-pet-name-change", (event) => {
+  console.log(event.detail.name);
+});
+
+shiro.addEventListener("digital-pet-visibility-change", (event) => {
+  console.log(event.detail.visible);
+});
+```
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run build
+python3 -m http.server 4173 -d .
+```
+
+Open `http://localhost:4173/demo/`.
+
+## Publishing
+
+1. Update the version in `package.json`.
+2. Run `npm run check`, `npm run build`, and `npm pack --dry-run`.
+3. Authenticate with npm.
+4. Run `npm publish --access public`.

package/assets/README.md

@@ -0,0 +1,10 @@
+# Sound Asset
+
+`bark-cute.mp3` is used for optional Digital Pet bark effects.
+
+- Source: [Barking Dog Cute Sound](https://pixabay.com/sound-effects/nature-barking-dog-cute-sound-463192/)
+- Provider: Pixabay
+- License: [Pixabay Content License](https://pixabay.com/service/license-summary/)
+
+The application keeps sounds disabled by default. Users must enable them through
+the pet controls or the `sound="true"` attribute.

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+export declare const DIGITAL_PET_COMMANDS: readonly ["sit", "walk", "run", "jump", "down", "sleep", "roll-over", "handshake", "hi-five", "salute", "namaste", "speak", "quiet", "fetch", "feed", "treat", "surprise"];
+export declare const DIGITAL_PET_SIZES: readonly ["small", "normal", "large", "extra-large"];
+export declare const DIGITAL_PET_RENDERERS: readonly ["2d", "3d"];
+export type DigitalPetCommand = (typeof DIGITAL_PET_COMMANDS)[number];
+export type DigitalPetSize = (typeof DIGITAL_PET_SIZES)[number];
+export type DigitalPetRenderer = (typeof DIGITAL_PET_RENDERERS)[number];
+export interface DigitalPetOptions {
+    name?: string;
+    controls?: boolean;
+    cursorInteraction?: boolean;
+    sound?: boolean;
+    volume?: number;
+    renderer?: "auto" | DigitalPetRenderer;
+    size?: DigitalPetSize;
+    zIndex?: number;
+    startCorner?: "bottom-left" | "bottom-right";
+}
+export declare class DigitalPetElement extends HTMLElement {
+    static readonly tagName = "digital-pet";
+    static get observedAttributes(): string[];
+    private canvas;
+    private readonly fallbackCanvas;
+    private readonly webglCanvas;
+    private readonly context;
+    private readonly launcher;
+    private readonly panel;
+    private readonly commandsContainer;
+    private readonly sizesContainer;
+    private readonly reducedMotion;
+    private readonly barkAudio;
+    private threeRenderer;
+    private animationFrame;
+    private lastFrame;
+    private nextDecisionAt;
+    private behaviorStartedAt;
+    private behaviorEndsAt;
+    private behavior;
+    private sizeValue;
+    private position;
+    private targetX;
+    private direction;
+    private facingScale;
+    private horizontalVelocity;
+    private renderedBounce;
+    private pointer;
+    private pointerMovedAt;
+    private dragging;
+    private dragOffset;
+    private dragStart;
+    private didDrag;
+    private ballColor;
+    private visible;
+    private connected;
+    private resizeObserver;
+    private soundEnabled;
+    private volume;
+    private rendererValue;
+    private hunger;
+    private lastHungerUpdate;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    command(command: DigitalPetCommand): void;
+    randomTrick(): void;
+    setSize(size: DigitalPetSize, persist?: boolean): void;
+    setRenderer(renderer: DigitalPetRenderer): void;
+    bringToPointer(): void;
+    bringTo(x: number, y: number): void;
+    show(): void;
+    hide(): void;
+    get isVisible(): boolean;
+    private get displayWidth();
+    private get displayHeight();
+    private get cursorInteractionEnabled();
+    private get petName();
+    private updatePetName;
+    private dispatchCareEvent;
+    private dispatchVisibilityChange;
+    private playBark;
+    private requireElement;
+    private renderControlButtons;
+    private bindControls;
+    private openPanel;
+    private closePanel;
+    private readInitialSize;
+    private placeInStartCorner;
+    private applyCanvasSize;
+    private initializeRenderer;
+    private dispatchRendererChange;
+    private syncRendererControls;
+    private syncSoundControls;
+    private syncSizeButtons;
+    private readonly handleGlobalPointerMove;
+    private readonly handlePointerDown;
+    private readonly handleCanvasPointerMove;
+    private readonly handlePointerUp;
+    private readonly handleResize;
+    private readonly handleVisibilityChange;
+    private readonly handleReducedMotionChange;
+    private readonly tick;
+    private update;
+    private updateCursorReaction;
+    private updateMovement;
+    private updateChase;
+    private chooseAutonomousBehavior;
+    private startMoving;
+    private setBehavior;
+    private setTimedBehavior;
+    private moveToNearestCorner;
+    private clampPosition;
+    private say;
+    private draw;
+    private bodyBounce;
+    private bodyLean;
+    private wagAngle;
+    private get behaviorProgress();
+    private applyTrickTransform;
+    private drawStandingShiro;
+    private drawLyingShiro;
+    private drawRollingShiro;
+    private drawSittingShiro;
+    private drawHead;
+    private get mouthOpen();
+    private legOffset;
+    private drawPlumeTail;
+    private drawChestRuff;
+    private drawFeatheredLeg;
+    private drawRaisedPaw;
+    private drawNamastePaws;
+    private drawEar;
+    private drawFaceDetails;
+    private drawEarFeathering;
+    private drawFurTufts;
+    private drawEye;
+    private drawClosedEye;
+    private drawSoundLines;
+    private drawFetchBall;
+    private drawRestingBalls;
+    private drawBall;
+    private drawShadow;
+}
+export declare function defineDigitalPet(tagName?: string): void;
+export declare function mountDigitalPet(options?: DigitalPetOptions): DigitalPetElement;
+declare global {
+    interface HTMLElementTagNameMap {
+        "digital-pet": DigitalPetElement;
+    }
+}
+//# 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":"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"}