plushies 0.1.0-alpha.0

package/dist/viewer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A drop-in viewer: one plushie on its own transparent canvas, with camera,
+ * resize handling, a render loop that only runs while something changes, a
+ * few tweens and an optional idle loop.
+ *
+ * All viewers on a page draw through one hidden WebGL context (per three
+ * module) and copy their pixels onto their own 2D canvas. Browsers cap live
+ * WebGL contexts at around 16, so this keeps a page of plushies working, and
+ * shaders and the environment map are built only once.
+ *
+ *   import * as THREE from 'three';
+ *   import {mountPlushie} from 'plushies/viewer';
+ *   const view = mountPlushie(document.querySelector('#hero'), THREE, {kind: 'heart', color: '#f47c9a', idle: true});
+ *   await view.hop();
+ */
+import { type Plushie, type PlushieOptions, type PlushiePose, type ThreeModule } from './index.js';
+/** The look a viewer builds its plushie from (the viewer brings its own renderer). */
+export type ViewerLook = Omit<PlushieOptions, 'renderer'>;
+export interface ViewerOptions extends ViewerLook, Partial<Omit<PlushiePose, 'width' | 'height' | 'pixelRatio'>> {
+    /** Blink, breathe and glance around on its own. (default: false) */
+    idle?: boolean;
+    /** Eyes follow the mouse pointer anywhere on the page. (default: false) */
+    followPointer?: boolean;
+    /** Cap for the device pixel ratio. (default: 2) */
+    maxPixelRatio?: number;
+}
+export type Easing = (t: number) => number;
+export declare const easeInOut: Easing;
+export declare const easeOut: Easing;
+export declare const easeIn: Easing;
+type Numeric = Exclude<keyof PlushiePose, 'color' | 'width' | 'height' | 'pixelRatio'>;
+export interface PlushieViewer {
+    /** The current plushie (replaced by `restyle`). */
+    readonly plushie: Plushie;
+    readonly canvas: HTMLCanvasElement;
+    /** The current look: the options given at mount, merged with every `restyle`. */
+    readonly options: Readonly<ViewerLook>;
+    /** Set pose values immediately. */
+    set(pose: Partial<PlushiePose>): void;
+    /** Tween numeric pose values. Resolves when done; a newer tween of the same key takes over. */
+    to(pose: Partial<Pick<PlushiePose, Numeric>>, seconds?: number, ease?: Easing): Promise<void>;
+    /** Point the eyes at x, y in −1..1 (y down). */
+    look(x: number, y?: number, seconds?: number): Promise<void>;
+    blink(seconds?: number): Promise<void>;
+    /** Anticipation squash, jump, landing squash, settle. `height` in pixels defaults to a fifth of the canvas height, at most 90. */
+    hop(height?: number, seconds?: number): Promise<void>;
+    /** Squeeze and spring back. */
+    squish(amount?: number, seconds?: number): Promise<void>;
+    /**
+     * Change the look (build-time options) in place, keeping the pose. `options`
+     * is merged into the current look; pass `undefined` for a key to reset it to
+     * its default. Fur length resets to the new fabric's unless given.
+     */
+    restyle(options: ViewerLook & Partial<Pick<PlushiePose, 'color' | 'fur'>>): void;
+    /**
+     * Halt everything where it is: running tweens, `hop`/`squish`/`blink`
+     * sequences and the current idle gesture. Their promises resolve; the idle
+     * loop (if on) carries on after its pause.
+     */
+    stop(): void;
+    /** Start or stop the idle loop (blink, breathe, glance). */
+    setIdle(on: boolean): void;
+    /** Start or stop following the pointer with the eyes. */
+    setFollowPointer(on: boolean): void;
+    /** Remove the canvas and free GPU resources. Pending promises resolve. Safe to call twice. */
+    dispose(): void;
+}
+/** Mount a plushie filling `container` (give the container a size). */
+export declare function mountPlushie(container: HTMLElement, three: ThreeModule, options?: ViewerOptions): PlushieViewer;
+export {};

package/dist/viewer.js

@@ -0,0 +1,393 @@
+// src/viewer.ts
+import {
+  createPlushie,
+  resetEnvironment
+} from "./index.js";
+var easeInOut = (t) => t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+var easeOut = (t) => 1 - (1 - t) ** 3;
+var easeIn = (t) => t * t;
+var SHARED = new WeakMap;
+function acquireRenderer(three) {
+  let shared = SHARED.get(three);
+  if (!shared) {
+    const renderer = new three.WebGLRenderer({ antialias: true, alpha: true, premultipliedAlpha: true });
+    renderer.setClearColor(0, 0);
+    renderer.setPixelRatio(1);
+    renderer.setSize(1, 1, false);
+    renderer.setScissorTest(true);
+    const created = { renderer, users: new Map, width: 1, height: 1 };
+    renderer.domElement.addEventListener("webglcontextlost", (event) => event.preventDefault());
+    renderer.domElement.addEventListener("webglcontextrestored", () => {
+      for (const user of created.users.values())
+        user.restore();
+    });
+    shared = created;
+    SHARED.set(three, shared);
+  }
+  return shared;
+}
+function releaseRenderer(three, shared, user) {
+  if (!shared.users.delete(user))
+    return;
+  if (shared.users.size > 0) {
+    fitBuffer(shared);
+    return;
+  }
+  SHARED.delete(three);
+  shared.renderer.dispose();
+  shared.renderer.forceContextLoss();
+}
+function fitBuffer(shared) {
+  let width = 1;
+  let height = 1;
+  for (const user of shared.users.values()) {
+    width = Math.max(width, user.width);
+    height = Math.max(height, user.height);
+  }
+  if (width * height < shared.width * shared.height * 0.5) {
+    shared.width = width;
+    shared.height = height;
+    shared.renderer.setSize(width, height, false);
+  }
+}
+function paint(shared, scene, camera, target, w, h) {
+  const { renderer } = shared;
+  if (w > shared.width || h > shared.height) {
+    shared.width = Math.max(w, shared.width);
+    shared.height = Math.max(h, shared.height);
+    renderer.setSize(shared.width, shared.height, false);
+  }
+  renderer.setViewport(0, 0, w, h);
+  renderer.setScissor(0, 0, w, h);
+  renderer.render(scene, camera);
+  target.clearRect(0, 0, w, h);
+  target.drawImage(renderer.domElement, 0, shared.height - h, w, h, 0, 0, w, h);
+}
+var NUMERIC = ["lookX", "lookY", "blink", "squash", "hop", "lean", "turn", "float", "fur"];
+var POSE_KEYS = [...NUMERIC, "color", "width", "height", "pixelRatio"];
+function mountPlushie(container, three, options = {}) {
+  const { idle = false, followPointer = false, maxPixelRatio = 2, ...rest } = options;
+  const look = { ...rest };
+  for (const key of POSE_KEYS)
+    delete look[key];
+  delete look.renderer;
+  const shared = acquireRenderer(three);
+  const { renderer } = shared;
+  const canvas = document.createElement("canvas");
+  const context = canvas.getContext("2d");
+  canvas.style.display = "block";
+  canvas.style.width = "100%";
+  canvas.style.height = "100%";
+  container.appendChild(canvas);
+  const user = { width: 1, height: 1, restore: () => restore() };
+  shared.users.set(user, user);
+  const scene = new three.Scene;
+  const world = new three.Group;
+  world.scale.setScalar(1 / 100);
+  scene.add(world);
+  const camera = new three.PerspectiveCamera;
+  const DISTANCE = 1600;
+  let plushie;
+  try {
+    plushie = createPlushie(three, { ...rest, renderer });
+  } catch (error) {
+    releaseRenderer(three, shared, user);
+    canvas.remove();
+    throw error;
+  }
+  world.add(plushie.object);
+  let width = 1;
+  let height = 1;
+  const resize = () => {
+    if (disposed)
+      return;
+    width = Math.max(1, container.clientWidth);
+    height = Math.max(1, container.clientHeight);
+    const ratio = Math.min(maxPixelRatio, window.devicePixelRatio || 1);
+    const w = Math.round(width * ratio);
+    const h = Math.round(height * ratio);
+    const pose = plushie.pose;
+    if (w === canvas.width && h === canvas.height && pose.pixelRatio === ratio && pose.width === width && pose.height === height)
+      return;
+    canvas.width = w;
+    canvas.height = h;
+    user.width = canvas.width;
+    user.height = canvas.height;
+    fitBuffer(shared);
+    camera.fov = 2 * Math.atan(height / 2 / DISTANCE) * 180 / Math.PI;
+    camera.aspect = width / height;
+    camera.near = 0.08;
+    camera.far = 1700;
+    camera.position.set(0, 0, DISTANCE / 100);
+    camera.lookAt(0, 0, 0);
+    camera.updateProjectionMatrix();
+    plushie.set({ width, height, pixelRatio: ratio });
+    invalidate();
+  };
+  const tweens = new Map;
+  let frame = 0;
+  let disposed = false;
+  let visible = true;
+  let stale = false;
+  let chainFrom = 0;
+  let chainLimit = 50;
+  let chaining = false;
+  let lastTick = 0;
+  let frameGap = 0;
+  let generation = 0;
+  const invalidate = () => {
+    if (!frame && !disposed)
+      frame = requestAnimationFrame(tick);
+  };
+  const tick = (now) => {
+    frame = 0;
+    const gap = lastTick ? now - lastTick : 0;
+    const next = {};
+    const finished = [];
+    for (const [key, t] of tweens) {
+      const u = t.seconds <= 0 ? 1 : Math.min(1, Math.max(0, (now - t.start) / 1000 / t.seconds));
+      next[key] = t.from + (t.to - t.from) * t.ease(u);
+      if (u >= 1) {
+        tweens.delete(key);
+        finished.push(t);
+      }
+    }
+    plushie.set(next);
+    if (visible)
+      paint(shared, scene, camera, context, canvas.width, canvas.height);
+    else
+      stale = true;
+    if (finished.length) {
+      chainFrom = Math.max(...finished.map((t) => t.start + t.seconds * 1000));
+      chainLimit = Math.min(500, Math.max(50, 2 * frameGap));
+      chaining = true;
+      setTimeout(() => chaining = false);
+      for (const t of finished)
+        t.done();
+    }
+    frameGap = tweens.size ? gap : 0;
+    lastTick = tweens.size ? now : 0;
+    if (tweens.size)
+      invalidate();
+  };
+  const settle = (key) => {
+    for (const [k, t] of tweens) {
+      if (key !== undefined && k !== key)
+        continue;
+      tweens.delete(k);
+      t.done();
+    }
+  };
+  const to = (pose, seconds = 0.4, ease = easeInOut) => {
+    if (disposed)
+      return Promise.resolve();
+    const now = performance.now();
+    const start = chaining && now - chainFrom <= chainLimit ? chainFrom : now;
+    const keys = Object.keys(pose).filter((k) => NUMERIC.includes(k) && Number.isFinite(pose[k]));
+    const done = Promise.all(keys.map((key) => new Promise((resolve) => {
+      settle(key);
+      tweens.set(key, {
+        from: plushie.pose[key],
+        to: pose[key],
+        start,
+        seconds: Number.isFinite(seconds) ? seconds : 0,
+        ease,
+        done: resolve
+      });
+    }))).then(() => {
+      return;
+    });
+    invalidate();
+    return done;
+  };
+  const wait = (seconds) => new Promise((r) => setTimeout(r, seconds * 1000));
+  const perform = async (steps) => {
+    const g = generation;
+    for (const step of steps) {
+      if (disposed || generation !== g)
+        return;
+      await step();
+    }
+  };
+  let idling = false;
+  let idleRun = 0;
+  const idleLoop = async (run) => {
+    const glances = [[-0.8, 0], [0.7, -0.3], [0, 0.2], [0.4, 0.5], [0, 0]];
+    const alive = () => !disposed && idleRun === run;
+    for (let i = 0;alive(); i++) {
+      const g = generation;
+      const going = () => alive() && generation === g;
+      await viewer.blink();
+      if (going())
+        await to({ squash: 0.08, float: 1.12 }, 1.1);
+      if (going())
+        await to({ squash: 0, float: 1 }, 1.1);
+      if (going() && performance.now() - pointerAt > 2000) {
+        const [x, y] = glances[i % glances.length];
+        await viewer.look(x, y, 0.4);
+      }
+      if (!alive())
+        break;
+      await wait(0.6 + i * 7 % 5 * 0.25);
+    }
+  };
+  const rebuild = () => {
+    const { fur, ...pose } = plushie.pose;
+    plushie.dispose();
+    plushie = createPlushie(three, { ...look, ...pose, fur, renderer });
+    world.add(plushie.object);
+    invalidate();
+  };
+  const restore = () => {
+    resetEnvironment(renderer);
+    rebuild();
+  };
+  const viewer = {
+    get plushie() {
+      return plushie;
+    },
+    canvas,
+    get options() {
+      return { ...look };
+    },
+    set(pose) {
+      if (disposed)
+        return;
+      for (const key of Object.keys(pose))
+        settle(key);
+      plushie.set(pose);
+      invalidate();
+    },
+    to,
+    look: (x, y = 0, seconds = 0.35) => to({ lookX: x, lookY: y }, seconds),
+    blink: (seconds = 0.22) => perform([() => to({ blink: 1 }, seconds * 0.45, easeIn), () => to({ blink: 0 }, seconds * 0.55, easeOut)]),
+    hop(jump, seconds = 1.1) {
+      const height2 = jump ?? Math.min(90, plushie.pose.height * 0.2);
+      return perform([
+        () => to({ squash: 0.45 }, seconds * 0.2, easeOut),
+        () => {
+          to({ squash: -0.35 }, seconds * 0.15, easeOut);
+          return to({ hop: height2 }, seconds * 0.3, easeOut);
+        },
+        () => {
+          to({ squash: 0 }, seconds * 0.2);
+          return to({ hop: 0 }, seconds * 0.25, easeIn);
+        },
+        () => to({ squash: 0.4 }, seconds * 0.08, easeOut),
+        () => to({ squash: 0 }, seconds * 0.22, easeOut)
+      ]);
+    },
+    squish: (amount = 0.6, seconds = 1) => perform([
+      () => to({ squash: amount, float: 1.25 }, seconds * 0.35, easeOut),
+      () => to({ squash: -amount * 0.3, float: 0.9 }, seconds * 0.25, easeInOut),
+      () => to({ squash: 0, float: 1 }, seconds * 0.4, easeOut)
+    ]),
+    restyle(change) {
+      if (disposed)
+        return;
+      const { fur, ...rest2 } = change;
+      delete rest2.renderer;
+      const posed = {};
+      for (const [key, value] of Object.entries(rest2)) {
+        if (POSE_KEYS.includes(key)) {
+          if (value !== undefined)
+            posed[key] = value;
+        } else if (value === undefined)
+          delete look[key];
+        else
+          look[key] = value;
+      }
+      for (const key of Object.keys(posed))
+        settle(key);
+      if (fur !== undefined || "fabric" in rest2)
+        settle("fur");
+      const { fur: _fur, ...pose } = plushie.pose;
+      plushie.dispose();
+      plushie = createPlushie(three, { ...look, ...pose, ...posed, ...fur !== undefined && { fur }, renderer });
+      world.add(plushie.object);
+      invalidate();
+    },
+    stop() {
+      generation++;
+      settle();
+    },
+    setIdle(on) {
+      if (disposed || on === idling)
+        return;
+      idling = on;
+      idleRun++;
+      if (on)
+        idleLoop(idleRun);
+    },
+    setFollowPointer(on) {
+      window.removeEventListener("pointermove", onPointer);
+      if (on && !disposed)
+        window.addEventListener("pointermove", onPointer);
+    },
+    dispose() {
+      if (disposed)
+        return;
+      disposed = true;
+      idling = false;
+      idleRun++;
+      if (frame)
+        cancelAnimationFrame(frame);
+      frame = 0;
+      observer.disconnect();
+      visibility?.disconnect();
+      unwatchRatio();
+      window.removeEventListener("pointermove", onPointer);
+      settle();
+      plushie.dispose();
+      releaseRenderer(three, shared, user);
+      canvas.remove();
+    }
+  };
+  const observer = new ResizeObserver(resize);
+  observer.observe(container);
+  resize();
+  if (container.clientWidth > 0 && container.clientHeight === 0 && getComputedStyle(container).display !== "none") {
+    console.warn("plushies: mountPlushie container has no height; give it one (the canvas fills it)");
+  }
+  const visibility = typeof IntersectionObserver === "undefined" ? null : new IntersectionObserver((entries) => {
+    visible = entries[entries.length - 1].isIntersecting;
+    if (visible && stale) {
+      stale = false;
+      invalidate();
+    }
+  });
+  visibility?.observe(canvas);
+  let ratioQuery = null;
+  const watchRatio = () => {
+    ratioQuery?.removeEventListener("change", onRatio);
+    ratioQuery = typeof matchMedia === "undefined" ? null : matchMedia(`(resolution: ${window.devicePixelRatio || 1}dppx)`);
+    ratioQuery?.addEventListener("change", onRatio);
+  };
+  const onRatio = () => {
+    resize();
+    watchRatio();
+  };
+  const unwatchRatio = () => ratioQuery?.removeEventListener("change", onRatio);
+  watchRatio();
+  let pointerAt = 0;
+  const onPointer = (event) => {
+    if (!visible)
+      return;
+    const box = canvas.getBoundingClientRect();
+    const x = (event.clientX - (box.left + box.width / 2)) / (window.innerWidth / 2);
+    const y = (event.clientY - (box.top + box.height / 2)) / (window.innerHeight / 2);
+    pointerAt = performance.now();
+    to({ lookX: Math.max(-1, Math.min(1, x)), lookY: Math.max(-1, Math.min(1, y)) }, 0.25, easeOut);
+  };
+  if (followPointer)
+    viewer.setFollowPointer(true);
+  if (idle)
+    viewer.setIdle(true);
+  return viewer;
+}
+export {
+  mountPlushie,
+  easeOut,
+  easeInOut,
+  easeIn
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "plushies",
+  "version": "0.1.0-alpha.0",
+  "description": "Soft 3D plush characters for three.js — 17 silhouettes, shell-textured fur, floating eyes, glasses and hats, squash & stretch.",
+  "license": "MIT",
+  "author": "Patrick Rathje",
+  "repository": {
+  "type": "git",
+  "url": "git+https://github.com/prathje/plushies.git",
+  "directory": "packages/plushies"
+},
+"homepage": "https://github.com/prathje/plushies/tree/main/packages/plushies#readme",
+"bugs": "https://github.com/prathje/plushies/issues",
+"type": "module",
+"main": "./dist/plushies.cjs",
+"module": "./dist/index.js",
+"types": "./dist/index.d.ts",
+"unpkg": "./dist/plushies.global.js",
+"jsdelivr": "./dist/plushies.global.js",
+"exports": {
+  ".": {
+  "types": "./dist/index.d.ts",
+  "import": "./dist/index.js",
+  "require": "./dist/plushies.cjs"
+},
+"./viewer": {
+"types": "./dist/viewer.d.ts",
+"import": "./dist/viewer.js"
+},
+"./bundled": {
+"types": "./dist/bundled.d.ts",
+"import": "./dist/plushies.bundled.js"
+},
+"./package.json": "./package.json"
+},
+"files": ["dist", "README.md", "LICENSE"],
+"sideEffects": ["./site/*.ts", "./src/global.ts"],
+"scripts": {
+  "build": "bun run build.ts",
+  "typecheck": "tsc -p tsconfig.json",
+  "test": "bun test test/unit",
+  "test:e2e": "bun test test/e2e",
+  "site:dev": "bun --port 4517 site/index.html",
+  "site:build": "bun run site/build.ts",
+  "check": "bun run typecheck && bun run test && bun run build && bun run site:build"
+},
+"peerDependencies": {
+"three": ">=0.160.0"
+},
+"devDependencies": {
+  "@types/bun": "^1.3.2",
+  "@types/three": "^0.186.0",
+  "playwright": "^1.55.0",
+  "three": "^0.186.0",
+  "typescript": "^5.9.3"
+},
+"keywords": ["three", "threejs", "character", "plush", "fur", "mascot", "3d", "webgl"]
+}