3d-spinner 0.9.0 → 0.9.2

package/README.md

@@ -1,12 +1,13 @@
-# 3d-spinner
+# 3d-spinner and beyond
 
 [![tests](https://img.shields.io/github/actions/workflow/status/runelaang/3d-spinner/ci.yml?label=tests&logo=github)](https://github.com/runelaang/3d-spinner/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/3d-spinner?logo=npm)](https://www.npmjs.com/package/3d-spinner)
 [![license](https://img.shields.io/github/license/runelaang/3d-spinner)](LICENSE)
 
 A zero-dependency 3D spinner, loader, and progress indicator for the browser. It renders to a
-canvas and ships as ES modules split across separate import paths, so a consumer loads only the
-animation, motion path, and rendering backend they actually use - nothing else is pulled in.
+canvas and ships primarily as ES modules split across separate import paths, so a consumer loads
+only the animation, motion path, and rendering backend they actually use - nothing else is pulled
+in. CommonJS and a browser-global build are also published; see [Module formats](#module-formats).
 
 ## Install
 
@@ -145,6 +146,24 @@ do not use is never fetched.
 new SpinAnimation({ backend: "webgl" }); // "canvas2d" (default), "webgl", or "webgpu"
 ```
 
+Renderer-specific features can look different between Canvas 2D, WebGL, and WebGPU. In
+particular, transparent shapes are an approximate visual effect rather than a pixel-identical
+cross-renderer result.
+
+Use `transparency.mode` to choose visible-front-face transparency or a two-pass transparent-solid
+effect. Opacity defaults to `0.35` for one-sided rendering. Two-sided rendering defaults to
+front `0.56` and back `0.84`.
+
+```js
+new SpinAnimation({
+  backend: "webgl",
+  transparency: { mode: "two-sided", opacity: 0.6 }, // front 0.6, back 0.4
+});
+```
+
+For two-sided rendering, explicit `frontOpacity` and `backOpacity` values override the shorthand
+for their respective sides.
+
 ## The engine
 
 The renderer is a small, self-contained 3D engine, exported on its own in case you want it
@@ -157,17 +176,39 @@ directly:
 
 Each has no dependencies of its own.
 
-## Module format
+## Module formats
 
-ES modules only, for the browser. Use a bundler or native `<script type="module">`; the engine
-draws to a canvas, so there is no server-side rendering. ES modules do not load over `file://`,
-so serve the page over HTTP rather than opening the file directly.
+Every example above is **ES modules** - the primary, tree-shakeable format. Use a bundler or native `<script type="module">`; the engine draws to a canvas, so
+there is no server-side rendering. ES modules do not load over `file://`, so serve the page over
+HTTP rather than opening the file directly.
+
+Two other formats are published for cases where ESM isn't an option:
+
+**CommonJS** (`require`), for older Node tooling:
+
+```js
+const { createSpinner } = require("3d-spinner");
+const { SpinAnimation } = require("3d-spinner/animations/spin");
+```
+
+**Browser global** (IIFE), for a plain `<script>` tag with no bundler or module loader. This build
+bundles the whole public API onto one `window.Spinner3D` object:
+
+```html
+<script src="https://unpkg.com/3d-spinner"></script>
+<script>
+  const spinner = Spinner3D.createSpinner(document.getElementById("app"), {
+    type: "indeterminate",
+    animation: new Spinner3D.SpinAnimation(),
+  });
+</script>
+```
 
 ## Development
 
 ```sh
 npm install
-npm run build   # compile src/ to dist/ (ESM + type declarations)
+npm run build   # compile src/ to dist/ (ESM + type declarations, CJS, and a browser-global build)
 npm test        # build, then run the unit tests
 npm run dev     # serve this folder; open /examples/index.html
 ```

package/dist/animations/object-motion.d.ts

@@ -1,5 +1,5 @@
 import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
-import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+import { type Backend, type Mesh, type Transparency } from "../engines/little-3d-engine/little-3d-engine.js";
 import type { MotionController } from "../motion/controller.js";
 import { type ObjectMotionTransitionConfig } from "../motion/transitions.js";
 /** Which local axis the object's nose points down, used to correct a model that moves backwards or sideways. */
@@ -31,6 +31,8 @@ export interface ObjectMotionOptions {
     color?: string;
     /** Rendering backend. Default `"canvas2d"`. */
     backend?: Backend;
+    /** Optional one-sided or two-sided mesh transparency. */
+    transparency?: Transparency;
     /** Uniform object size after centering. Default `1`. */
     size?: number;
     /** The object's nose axis. Set this to correct a model that moves backwards or sideways. Default `"+x"`. */
@@ -65,6 +67,7 @@ export declare class ObjectMotionAnimation implements SpinnerAnimation {
     private readonly mesh;
     private readonly motion;
     private readonly backend?;
+    private readonly transparency?;
     private readonly labelText?;
     private readonly tailCount;
     private readonly tailGap;

package/dist/animations/object-motion.js

@@ -159,6 +159,7 @@ export class ObjectMotionAnimation {
         this.mesh = applyColor(facing, options.color ?? "#cbd5e1");
         this.motion = options.motion;
         this.backend = options.backend;
+        this.transparency = options.transparency;
         this.labelText = options.label;
         this.tailCount = Math.max(0, Math.floor(options.tail?.count ?? 0));
         this.tailGap = Math.max(0, options.tail?.gapMs ?? 0);
@@ -186,7 +187,7 @@ export class ObjectMotionAnimation {
             camera: { position: { x: 0, y: 0, z: 3 } },
         });
         for (let i = 0; i <= this.tailCount; i++) {
-            this.handles.push(engine.add(this.mesh));
+            this.handles.push(engine.add(this.mesh, { transparency: this.transparency }));
             this.banks.push(0);
             this.headings.push({ x: 1, y: 0, z: 0 });
         }

package/dist/animations/spin.d.ts

@@ -1,5 +1,5 @@
 import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
-import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+import { type Backend, type Mesh, type Transparency } from "../engines/little-3d-engine/little-3d-engine.js";
 import { type ProgressAnimationOptions } from "../progress-animation.js";
 export interface SpinAnimationOptions {
     /** Shape to spin: a mesh, or a factory that returns one. Default: a cube. */
@@ -12,6 +12,8 @@ export interface SpinAnimationOptions {
     spinY?: number;
     /** Rendering backend. Default `"canvas2d"`. */
     backend?: Backend;
+    /** Optional one-sided or two-sided mesh transparency. */
+    transparency?: Transparency;
     /**
      * Enable the start/end pop and progress-driven scale, with an optional overlay
      * label. Omit to spin at constant size with no progress reaction.
@@ -31,6 +33,7 @@ export declare class SpinAnimation implements SpinnerAnimation {
     private readonly spinX;
     private readonly spinY;
     private readonly backend?;
+    private readonly transparency?;
     private readonly progress?;
     private exited;
     constructor(options?: SpinAnimationOptions);

package/dist/animations/spin.js

@@ -36,6 +36,7 @@ export class SpinAnimation {
         this.spinX = options.spinX ?? 0.0007;
         this.spinY = options.spinY ?? 0.0011;
         this.backend = options.backend;
+        this.transparency = options.transparency;
         this.progress = options.progressAnimation
             ? new ProgressAnimation(options.progressAnimation)
             : undefined;
@@ -46,7 +47,7 @@ export class SpinAnimation {
             backend: this.backend,
             camera: { position: { x: 0, y: 0, z: 2.8 } },
         });
-        this.handle = engine.add(this.mesh);
+        this.handle = engine.add(this.mesh, { transparency: this.transparency });
         this.engine = engine;
         engine.mount(target).catch((error) => {
             target.textContent = error instanceof Error ? error.message : String(error);