@@ -32,7 +81,9 @@
diff --git a/dev/index.html b/dev/index.html
index 614988b..29c36df 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -9,38 +9,73 @@
html, body {
width: 100%;
height: 100%;
+ min-height: 100vh;
+ min-height: 100dvh;
font-family: system-ui, -apple-system, sans-serif;
+ overflow: hidden;
}
+ html,
body {
background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
}
+ html.light,
body.light {
background: linear-gradient(135deg, #f0f0f0 0%, #e0e0e0 50%, #d0d0d0 100%);
}
#app {
+ position: fixed;
+ inset: 0;
width: 100%;
- height: 100%;
+ height: 100vh;
+ height: 100dvh;
}
.controls {
position: fixed;
top: 16px;
right: 16px;
z-index: 1000;
- background: rgba(0, 0, 0, 0.7);
+ width: min(282px, calc(100vw - 32px));
+ max-height: calc(100vh - 32px);
+ max-height: calc(100dvh - 32px);
+ overflow: auto;
+ background: rgba(6, 8, 18, 0.9);
+ backdrop-filter: blur(14px);
padding: 16px;
border-radius: 8px;
color: white;
font-size: 14px;
+ box-shadow: 0 16px 48px rgba(0, 0, 0, 0.32);
}
.controls label {
- display: block;
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) auto;
+ align-items: center;
+ gap: 8px;
margin-bottom: 8px;
}
+ .controls .checkbox-row {
+ grid-template-columns: auto minmax(0, 1fr);
+ justify-content: start;
+ }
+ .controls .range-row {
+ grid-template-columns: minmax(0, 1fr) minmax(118px, 1.2fr) auto;
+ }
.controls select, .controls input {
- margin-left: 8px;
padding: 4px 8px;
border-radius: 4px;
border: none;
+ min-width: 0;
+ }
+ .controls select {
+ max-width: 132px;
+ }
+ .controls input[type="range"] {
+ width: 100%;
+ }
+ .controls input[type="checkbox"] {
+ width: 14px;
+ height: 14px;
+ padding: 0;
}
.controls button {
margin-top: 8px;
@@ -51,15 +86,36 @@
color: white;
cursor: pointer;
}
+ .controls .button-row {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 8px;
+ }
+ .controls .button-row button {
+ margin-top: 0;
+ padding: 8px 10px;
+ }
+ .controls .status {
+ display: block;
+ margin-top: 8px;
+ min-height: 18px;
+ opacity: 0.75;
+ }
.controls button:hover {
background: #4a7de0;
}
+ .hide-controls .controls {
+ display: none;
+ }
/* Mobile responsive */
- @media (max-width: 480px) {
+ @media (max-width: 720px) {
.controls {
top: 8px;
- right: 8px;
left: 8px;
+ right: auto;
+ width: calc(100vw - 16px);
+ max-height: calc(100vh - 16px);
+ max-height: calc(100dvh - 16px);
padding: 12px;
font-size: 12px;
}
@@ -68,18 +124,22 @@
margin-bottom: 8px;
}
.controls label {
- display: flex;
- align-items: center;
- justify-content: space-between;
margin-bottom: 6px;
}
- .controls select, .controls input[type="range"] {
- max-width: 120px;
+ .controls select {
+ width: min(132px, 40vw);
+ max-width: 132px;
+ }
+ .controls .range-row {
+ grid-template-columns: minmax(0, 1fr) minmax(96px, 36vw) auto;
}
.controls button {
width: 100%;
padding: 10px;
}
+ .controls .button-row {
+ grid-template-columns: 1fr;
+ }
}
@@ -88,26 +148,47 @@
diff --git a/dev/main.ts b/dev/main.ts
index 8bff2d2..95c9d9b 100644
--- a/dev/main.ts
+++ b/dev/main.ts
@@ -1,11 +1,98 @@
import { mount, unmount } from 'svelte';
import App from './App.svelte';
+import type { MotionVector } from '../src/motion/DeviceMotion.js';
+import type { TinyVectorsDeviceMotionStatus } from '../src/svelte/types.js';
+
+interface DevAppHandle {
+ requestDeviceMotionPermission: () => Promise
;
+ calibrateDeviceMotion: (samples?: number) => void;
+ getDeviceMotionStatus: () => TinyVectorsDeviceMotionStatus;
+}
+
+interface DevWindow extends Window {
+ __tinyvectorsDeviceMotionStatus?: () => TinyVectorsDeviceMotionStatus | null;
+}
+
+const params = new URLSearchParams(window.location.search);
+const themes = ['tinyland', 'trans', 'pride'] as const;
+
+function booleanParam(name: string, fallback: boolean): boolean {
+ const value = params.get(name);
+ if (value === null) return fallback;
+ return !['0', 'false', 'off', 'no'].includes(value.toLowerCase());
+}
+
+function numberParam(name: string, fallback: number, min: number, max: number): number {
+ const value = Number(params.get(name));
+ if (!Number.isFinite(value)) return fallback;
+ return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function themeParam(): (typeof themes)[number] {
+ const value = params.get('theme');
+ return themes.includes(value as (typeof themes)[number]) ? (value as (typeof themes)[number]) : 'tinyland';
+}
+
+const initialDarkMode = booleanParam('dark', true);
+const showControls = booleanParam('controls', true);
+const devWindow = window as DevWindow;
+document.body.classList.toggle('dark', initialDarkMode);
+document.body.classList.toggle('light', !initialDarkMode);
+document.body.classList.toggle('hide-controls', !showControls);
+document.documentElement.classList.toggle('dark', initialDarkMode);
+document.documentElement.classList.toggle('light', !initialDarkMode);
+
+let app: (ReturnType & DevAppHandle) | null = null;
+
+function updateMotionStatus(text: string): void {
+ const motionStatus = document.getElementById('motion-status');
+ if (motionStatus) {
+ motionStatus.textContent = text;
+ }
+}
+
+function formatMotionSample(sample: MotionVector): string {
+ const x = sample.x.toFixed(2);
+ const y = sample.y.toFixed(2);
+ const z = sample.z.toFixed(2);
+ return `motion x ${x} y ${y} z ${z}`;
+}
+
+function createDeviceOrientationEvent(alpha: number, beta: number, gamma: number): Event {
+ if (typeof DeviceOrientationEvent === 'function') {
+ return new DeviceOrientationEvent('deviceorientation', {
+ alpha,
+ beta,
+ gamma,
+ absolute: false,
+ });
+ }
+
+ const event = new Event('deviceorientation');
+ Object.defineProperties(event, {
+ alpha: { value: alpha },
+ beta: { value: beta },
+ gamma: { value: gamma },
+ absolute: { value: false },
+ });
+ return event;
+}
+
+function spoofOrientation(alpha: number, beta: number, gamma: number): void {
+ window.dispatchEvent(createDeviceOrientationEvent(alpha, beta, gamma));
+}
-let app: ReturnType | null = null;
let currentProps = {
- theme: 'tinyland' as 'tinyland' | 'trans' | 'pride',
- blobCount: 12,
- animated: true,
+ theme: themeParam(),
+ blobCount: numberParam('blobs', 8, 4, 16),
+ animated: booleanParam('animated', true),
+ enableDeviceMotion: booleanParam('deviceMotion', true),
+ enableScrollPhysics: booleanParam('scrollPhysics', true),
+ enablePointerPhysics: booleanParam('pointerPhysics', true),
+ deviceMotionIdleResetMs: numberParam('motionIdleReset', 2000, 0, 10000),
+ onMotionSample(sample: MotionVector) {
+ updateMotionStatus(formatMotionSample(sample));
+ },
};
function mountApp() {
@@ -19,7 +106,8 @@ function mountApp() {
app = mount(App, {
target,
props: currentProps,
- });
+ }) as ReturnType & DevAppHandle;
+ devWindow.__tinyvectorsDeviceMotionStatus = () => app?.getDeviceMotionStatus() ?? null;
}
@@ -27,6 +115,9 @@ mountApp();
const themeSelect = document.getElementById('theme-select') as HTMLSelectElement;
+if (themeSelect) {
+ themeSelect.value = currentProps.theme;
+}
themeSelect?.addEventListener('change', () => {
currentProps.theme = themeSelect.value as 'tinyland' | 'trans' | 'pride';
mountApp();
@@ -35,6 +126,12 @@ themeSelect?.addEventListener('change', () => {
const blobCountSlider = document.getElementById('blob-count') as HTMLInputElement;
const blobCountValue = document.getElementById('blob-count-value');
+if (blobCountSlider) {
+ blobCountSlider.value = String(currentProps.blobCount);
+}
+if (blobCountValue) {
+ blobCountValue.textContent = String(currentProps.blobCount);
+}
blobCountSlider?.addEventListener('input', () => {
currentProps.blobCount = parseInt(blobCountSlider.value, 10);
if (blobCountValue) {
@@ -47,19 +144,74 @@ blobCountSlider?.addEventListener('change', () => {
const darkModeCheckbox = document.getElementById('dark-mode') as HTMLInputElement;
+if (darkModeCheckbox) {
+ darkModeCheckbox.checked = initialDarkMode;
+}
darkModeCheckbox?.addEventListener('change', () => {
document.body.classList.toggle('dark', darkModeCheckbox.checked);
document.body.classList.toggle('light', !darkModeCheckbox.checked);
document.documentElement.classList.toggle('dark', darkModeCheckbox.checked);
+ document.documentElement.classList.toggle('light', !darkModeCheckbox.checked);
});
const animatedCheckbox = document.getElementById('animated') as HTMLInputElement;
+if (animatedCheckbox) {
+ animatedCheckbox.checked = currentProps.animated;
+}
animatedCheckbox?.addEventListener('change', () => {
currentProps.animated = animatedCheckbox.checked;
mountApp();
});
+const deviceMotionCheckbox = document.getElementById('device-motion') as HTMLInputElement;
+if (deviceMotionCheckbox) {
+ deviceMotionCheckbox.checked = currentProps.enableDeviceMotion;
+}
+deviceMotionCheckbox?.addEventListener('change', () => {
+ currentProps.enableDeviceMotion = deviceMotionCheckbox.checked;
+ mountApp();
+});
+
+const scrollPhysicsCheckbox = document.getElementById('scroll-physics') as HTMLInputElement;
+if (scrollPhysicsCheckbox) {
+ scrollPhysicsCheckbox.checked = currentProps.enableScrollPhysics;
+}
+scrollPhysicsCheckbox?.addEventListener('change', () => {
+ currentProps.enableScrollPhysics = scrollPhysicsCheckbox.checked;
+ mountApp();
+});
+
+const pointerPhysicsCheckbox = document.getElementById('pointer-physics') as HTMLInputElement;
+if (pointerPhysicsCheckbox) {
+ pointerPhysicsCheckbox.checked = currentProps.enablePointerPhysics;
+}
+pointerPhysicsCheckbox?.addEventListener('change', () => {
+ currentProps.enablePointerPhysics = pointerPhysicsCheckbox.checked;
+ mountApp();
+});
+
+const requestMotionBtn = document.getElementById('request-motion-btn');
+requestMotionBtn?.addEventListener('click', async () => {
+ const granted = (await app?.requestDeviceMotionPermission()) ?? false;
+ updateMotionStatus(granted ? 'motion granted; waiting for sample' : 'motion unavailable');
+});
+
+const calibrateMotionBtn = document.getElementById('calibrate-motion-btn');
+calibrateMotionBtn?.addEventListener('click', () => {
+ app?.calibrateDeviceMotion(10);
+ updateMotionStatus('calibration queued');
+});
+
+const spoofTiltBtn = document.getElementById('spoof-tilt-btn');
+spoofTiltBtn?.addEventListener('click', () => {
+ spoofOrientation(120, 35, -45);
+});
+
+const neutralTiltBtn = document.getElementById('neutral-tilt-btn');
+neutralTiltBtn?.addEventListener('click', () => {
+ spoofOrientation(0, 0, 0);
+});
const reloadBtn = document.getElementById('reload-btn');
reloadBtn?.addEventListener('click', () => {
diff --git a/docs/physics-feel-contract.md b/docs/physics-feel-contract.md
new file mode 100644
index 0000000..316ed25
--- /dev/null
+++ b/docs/physics-feel-contract.md
@@ -0,0 +1,61 @@
+# TinyVectors Physics Feel Contract
+
+TinyVectors is an expressive background system for Svelte and SvelteKit apps, not a physics demo. The animation should feel alive before any user input happens. Device motion, pointer movement, and scrolling should bias that ambient motion instead of taking control of it.
+
+This document is the local source of truth for the field-based interaction work tracked in Linear `TIN-853` and GitHub #40.
+
+## Product Intent
+
+- Pleasant by default: idle blobs drift, breathe, and deform subtly.
+- App-safe: the component stays SSR-safe, reduced-motion aware, listener-clean, and small enough for background use.
+- Stylable: gel/fluid is a visual language exposed through themes, colors, opacity, and restrained renderer controls.
+- Performant: interaction work must preserve the package's bundle budget and avoid heavyweight simulation dependencies.
+
+## Interaction Model
+
+Every input should become a small field sampled by the blob physics loop:
+
+- Ambient field: always on, low-frequency, bounded motion. This is the baseline feel.
+- Gravity field: slow directional bias from device orientation. It should make blobs lean or pool, not fall like marbles.
+- Pointer field: local soft influence around the pointer. Nearby blobs should react more than distant blobs.
+- Scroll field: transient impulse or stickiness that decays. It should not create permanent acceleration.
+- Wall field: bounds should keep the background composed without hard visual snaps.
+- Input liveness: real sensor and pointer IO should auto-enable only when available. If device-orientation events go quiet, the tab is hidden, pointer input is canceled, the pointer leaves the viewport, or the window blurs, the field must return to neutral instead of preserving stale input.
+
+Fields may combine, but input fields must not erase the ambient field. If a field makes the background look frozen, jittery, or overly coherent, it violates the contract.
+
+## Non-Goals
+
+- Do not revive the Phase A XSPH, soft-wall, and Gaussian anti-clustering rewrite as-is.
+- Do not ship coefficient-only tuning without a contract and browser/demo validation.
+- Do not introduce a heavyweight fluid solver.
+- Do not make the background capture pointer events.
+
+## Test Strategy
+
+Tests should describe perceptual behavior in tolerant terms:
+
+- idle drift is present and bounded;
+- gravity creates directional bias without overpowering all motion;
+- pointer influence is local and distance-weighted;
+- scroll effects decay;
+- listener lifecycle stays clean;
+- bundle size stays within the configured gate.
+
+Avoid tests that lock exact coefficients, frame-by-frame positions, or one-off screenshot pixels unless the assertion is about a real compatibility contract.
+
+## Current Status
+
+- Gravity/device-orientation is routed through `InteractionField.directionalBiasField()` and cached as a bounded force outside the per-blob hot path.
+- The browser probe verifies synthetic and CDP orientation events preserve the expected motion signs, change blob geometry, and return to neutral on idle or reduced motion.
+- Pointer IO currently updates the physics pointer anchor, velocity, and per-blob `mouseDistance`; it does not apply a standalone pointer force yet.
+- Scroll still uses the restored pre-Phase-A path and can use the pointer anchor for sticky attraction. Route pointer and scroll through fields only after preserving the current feel and bundle headroom.
+
+## Implementation Slices
+
+1. Keep PR #39 on the restored pre-Phase-A physics and renderer baseline while retaining the motion harness, lifecycle, pointer, package, and CI work.
+2. Add pure field helpers and unit tests without changing runtime feel.
+3. Route gravity/device-orientation through the field helper while preserving ambient motion.
+4. Route pointer and scroll values through field helpers one input at a time.
+5. Add browser probes for directional bias, pointer locality, and scroll decay.
+6. Revisit renderer stylability after interaction feel is stable.
diff --git a/docs/release-flow.md b/docs/release-flow.md
new file mode 100644
index 0000000..3c72bf3
--- /dev/null
+++ b/docs/release-flow.md
@@ -0,0 +1,66 @@
+# Release Flow
+
+This repo publishes the npm package as the primary consumer artifact. Bazel exists here to produce and validate the same package shape used by downstream Bazel consumers.
+
+## Authority Chain
+
+1. `package.json` is the npm package authority for name, version, entry points, package manager, and publish config.
+2. `MODULE.bazel` mirrors the package version for Bzlmod consumers.
+3. `BUILD.bazel` builds the runtime package with Vite, emits declarations with `tsc`, and assembles `//:pkg` with `npm_package`.
+4. `.bazelversion` pins the Bazel runtime. Local Nix exposes `bazel` through Bazelisk so the dev shell follows that pin.
+5. `.github/workflows/ci.yml` and `.github/workflows/publish.yml` call the same pinned reusable package workflow.
+
+`pnpm run check:release-metadata` verifies these surfaces stay aligned before CI, Bazel, or npm publish steps run.
+
+## Local Verification
+
+Run the CI checks plus the local consumer check for the Bazel-built package:
+
+```bash
+pnpm run check:release-metadata
+pnpm run check
+pnpm run test
+pnpm run build
+pnpm run check:package
+pnpm run check:bundle-size
+nix develop . --command bazel build //:pkg //:package_consumer_check //:bundle_size_check //:typecheck //:test --verbose_failures
+pnpm run check:package-consumer
+npm pack --dry-run ./bazel-bin/pkg
+npm publish --dry-run --ignore-scripts --access public ./bazel-bin/pkg
+```
+
+`//:package_consumer_check` and `pnpm run check:package-consumer` both validate the Bazel-built package as an installed consumer would. The pnpm command expects `./bazel-bin/pkg` to exist. It links that package into a temporary consumer workspace with the Svelte peer dependency, verifies runtime subpath exports, and runs TypeScript against the packaged declarations.
+
+`pnpm run check:bundle-size` measures a realistic tree-shaken consumer import, `import { TinyVectors } from '@tummycrypt/tinyvectors'`, with Svelte externalized as a peer dependency. `//:bundle_size_check` runs the same measurement against the Bazel-built package artifact. The current gate is 12 KiB gzip and the target remains 11 KiB gzip, so the check reports target headroom or overage while leaving a small CI buffer.
+
+The bundle-size check also reports tracked runtime modules that enter that consumer bundle. `dist/core/InteractionField.js` is expected to appear once runtime physics routes an input through the field contract, and the gzip result is the source of truth for whether that cost is acceptable.
+
+`bazel query //...` should also work locally. `.bazelignore` excludes direnv, Nix, package-manager, and build-output directories so Bazel does not walk generated local artifacts.
+
+## Compatibility Notes
+
+The v0.3 branch currently keeps the renderer-private `--tv-blob-intensity` custom property used by the restored three-layer renderer. Do not document a migration to `--tvi`; that abbreviation was part of the reverted gel-rendering rewrite.
+
+## CI Flow
+
+Pull requests and pushes to `main` run `Verify`, which calls `tinyland-inc/ci-templates/.github/workflows/js-bazel-package.yml` at a pinned commit. The reusable workflow:
+
+- installs the configured pnpm and Node major;
+- runs metadata, typecheck, test, build, package, and bundle-size checks;
+- builds `//:pkg //:package_consumer_check //:bundle_size_check //:typecheck //:test` through Bazelisk;
+- validates the Bazel-built package with `npm pack --dry-run`;
+- validates npm publication with `npm publish --dry-run --ignore-scripts`.
+
+This means CI treats the Bazel package output as the release candidate, not the local `dist/` directory alone.
+
+## Publish Flow
+
+Tags matching `v*` run `Publish to npm`. The publish workflow reuses the same package workflow with `dry_run: false`, downloads the Bazel-built package artifact, and publishes that isolated artifact to npm.
+
+The workflow has `id-token: write` because npm provenance and trusted publishing both depend on OIDC-capable CI. The current reusable template still accepts `NPM_TOKEN`; moving fully to npm trusted publishing should happen in the shared template, not only in this repo.
+
+## FlakeHub Status
+
+The flake is currently a development environment only. It does not publish TinyVectors to FlakeHub and does not expose package outputs.
+
+If FlakeHub publication becomes useful, add it as a separate release surface with its own workflow and metadata checks. FlakeHub publication should use its trusted-platform publishing model rather than ad hoc local publishing.
diff --git a/flake.nix b/flake.nix
index c0e14ea..3657547 100644
--- a/flake.nix
+++ b/flake.nix
@@ -4,12 +4,25 @@
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
};
- outputs = { self, nixpkgs, flake-utils }:
- flake-utils.lib.eachDefaultSystem (system:
- let pkgs = nixpkgs.legacyPackages.${system}; in {
+ outputs =
+ {
+ self,
+ nixpkgs,
+ flake-utils,
+ }:
+ flake-utils.lib.eachDefaultSystem (
+ system:
+ let
+ pkgs = nixpkgs.legacyPackages.${system};
+ bazel = pkgs.writeShellScriptBin "bazel" ''
+ exec ${pkgs.bazelisk}/bin/bazelisk "$@"
+ '';
+ in
+ {
devShells.default = pkgs.mkShell {
buildInputs = [
- pkgs.bazel_8
+ bazel
+ pkgs.bazelisk
pkgs.nodejs_22
(pkgs.pnpm_9 or pkgs.pnpm)
];
@@ -17,10 +30,10 @@
echo "tinyvectors dev shell"
echo " node $(node --version)"
echo " pnpm $(pnpm --version)"
- echo " bazel $(bazel --version | head -n1)"
+ echo " bazel $(cat .bazelversion) via bazelisk"
'';
};
- formatter = pkgs.nixfmt-rfc-style;
+ formatter = pkgs.nixfmt;
}
);
}
diff --git a/package.json b/package.json
index 389cac7..6f679fb 100644
--- a/package.json
+++ b/package.json
@@ -67,19 +67,22 @@
"**/*.css"
],
"scripts": {
- "build": "vite build && tsc -p tsconfig.declarations.json",
+ "build": "vite build && node scripts/build-declarations.mjs",
"dev": "vite --config vite.dev.config.ts",
"dev:watch": "vite build --watch",
"check": "svelte-check --tsconfig ./tsconfig.json",
"check:release-metadata": "node scripts/check-release-metadata.mjs",
"check:package": "publint",
+ "check:bundle-size": "node scripts/check-bundle-size.mjs",
+ "check:package-consumer": "node scripts/check-package-consumer.mjs ./bazel-bin/pkg",
"test": "vitest run",
+ "test:browser:motion": "node scripts/probe-motion-cdp.mjs",
"test:watch": "vitest",
"test:pbt": "vitest run --testNamePattern='INVARIANT'",
- "prepublishOnly": "pnpm run check:release-metadata && pnpm run build && pnpm run check:package"
+ "prepublishOnly": "pnpm run check:release-metadata && pnpm run build && pnpm run check:package && pnpm run check:bundle-size"
},
"peerDependencies": {
- "svelte": "^5.0.0"
+ "svelte": ">=5.20.0"
},
"devDependencies": {
"@sveltejs/package": "^2.5.7",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 44f16ea..ef64141 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -597,8 +597,8 @@ packages:
resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
engines: {node: '>=12'}
- postcss@8.5.8:
- resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
+ postcss@8.5.12:
+ resolution: {integrity: sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA==}
engines: {node: ^10 || ^12 || >=14}
publint@0.2.12:
@@ -1217,7 +1217,7 @@ snapshots:
picomatch@4.0.4: {}
- postcss@8.5.8:
+ postcss@8.5.12:
dependencies:
nanoid: 3.3.11
picocolors: 1.1.1
@@ -1342,7 +1342,7 @@ snapshots:
esbuild: 0.25.12
fdir: 6.5.0(picomatch@4.0.4)
picomatch: 4.0.4
- postcss: 8.5.8
+ postcss: 8.5.12
rollup: 4.59.0
tinyglobby: 0.2.15
optionalDependencies:
diff --git a/scripts/build-declarations.mjs b/scripts/build-declarations.mjs
new file mode 100644
index 0000000..c28a673
--- /dev/null
+++ b/scripts/build-declarations.mjs
@@ -0,0 +1,14 @@
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const tscPath = require.resolve('typescript/lib/tsc.js');
+const result = spawnSync(process.execPath, [tscPath, '-p', 'tsconfig.declarations.json'], {
+ stdio: 'inherit',
+});
+
+if (result.status !== 0) {
+ process.exit(result.status ?? 1);
+}
+
+await import('./copy-svelte-declarations.mjs');
diff --git a/scripts/check-bundle-size.mjs b/scripts/check-bundle-size.mjs
new file mode 100644
index 0000000..7365b0d
--- /dev/null
+++ b/scripts/check-bundle-size.mjs
@@ -0,0 +1,119 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gzipSync } from 'node:zlib';
+import { build } from 'vite';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageRoot = resolve(process.cwd(), process.argv[2] ?? '.');
+const distEntry = resolve(packageRoot, 'dist/index.js');
+const targetGzipKiB = parsePositiveKiB('TINYVECTORS_TARGET_GZIP_KIB', 11);
+const maxGzipKiB = parsePositiveKiB('TINYVECTORS_MAX_GZIP_KIB', 12);
+const trackedConsumerModules = ['dist/core/InteractionField.js'];
+
+if (maxGzipKiB < targetGzipKiB) {
+ console.error(
+ 'TINYVECTORS_MAX_GZIP_KIB must be greater than or equal to TINYVECTORS_TARGET_GZIP_KIB',
+ );
+ process.exit(1);
+}
+
+if (!existsSync(distEntry)) {
+ console.error(`Bundle entry is missing: ${distEntry}`);
+ console.error('Run: pnpm run build');
+ process.exit(1);
+}
+
+const tempDir = await mkdtemp(join(tmpdir(), 'tinyvectors-bundle-size-'));
+
+try {
+ const entry = join(tempDir, 'consumer-entry.js');
+ await writeFile(
+ entry,
+ `
+import { TinyVectors } from ${JSON.stringify(distEntry)};
+console.log(TinyVectors);
+`.trimStart(),
+ );
+
+ const output = await build({
+ configFile: false,
+ logLevel: 'silent',
+ build: {
+ write: false,
+ minify: 'esbuild',
+ target: 'es2022',
+ rollupOptions: {
+ input: entry,
+ external: (id) => id === 'svelte' || id.startsWith('svelte/'),
+ output: {
+ format: 'es',
+ inlineDynamicImports: true,
+ },
+ },
+ },
+ });
+
+ const outputs = Array.isArray(output)
+ ? output.flatMap((bundle) => bundle.output)
+ : output.output;
+ const chunks = outputs.filter((item) => item.type === 'chunk');
+ const includedModules = new Set(
+ chunks.flatMap((chunk) =>
+ chunk.moduleIds.map((moduleId) => moduleId.replaceAll('\\', '/')),
+ ),
+ );
+ const trackedIncluded = trackedConsumerModules.filter((modulePath) =>
+ [...includedModules].some((moduleId) => moduleId.endsWith(`/${modulePath}`)),
+ );
+
+ const js = outputs
+ .filter((item) => item.type === 'chunk')
+ .map((item) => item.code)
+ .join('\n');
+ const rawKiB = js.length / 1024;
+ const gzipKiB = gzipSync(js).length / 1024;
+ const targetDelta = gzipKiB - targetGzipKiB;
+
+ console.log(
+ [
+ `bundle size check for ${relativeFromRepo(distEntry)}`,
+ `consumer import: { TinyVectors }`,
+ `raw ${rawKiB.toFixed(2)} KiB, gzip ${gzipKiB.toFixed(2)} KiB`,
+ `target ${targetGzipKiB.toFixed(2)} KiB, gate ${maxGzipKiB.toFixed(2)} KiB`,
+ targetDelta <= 0
+ ? `target headroom ${Math.abs(targetDelta).toFixed(2)} KiB`
+ : `target overage ${targetDelta.toFixed(2)} KiB`,
+ trackedIncluded.length > 0
+ ? `tracked modules included: ${trackedIncluded.join(', ')}`
+ : 'tracked modules included: none',
+ ].join('\n'),
+ );
+
+ if (gzipKiB > maxGzipKiB) {
+ console.error(
+ `Consumer bundle gzip ${gzipKiB.toFixed(2)} KiB exceeds ${maxGzipKiB.toFixed(2)} KiB gate`,
+ );
+ process.exit(1);
+ }
+} finally {
+ await rm(tempDir, { recursive: true, force: true });
+}
+
+function relativeFromRepo(path) {
+ return path.startsWith(`${repoRoot}/`) ? path.slice(repoRoot.length + 1) : path;
+}
+
+function parsePositiveKiB(envName, defaultValue) {
+ const rawValue = process.env[envName];
+ const value = rawValue == null ? defaultValue : Number(rawValue.trim());
+
+ if (!Number.isFinite(value) || value <= 0) {
+ console.error(`${envName} must be a positive number`);
+ process.exit(1);
+ }
+
+ return value;
+}
diff --git a/scripts/check-package-consumer.mjs b/scripts/check-package-consumer.mjs
new file mode 100644
index 0000000..b3a9784
--- /dev/null
+++ b/scripts/check-package-consumer.mjs
@@ -0,0 +1,163 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageDir = resolve(process.cwd(), process.argv[2] ?? './bazel-bin/pkg');
+const svelteDir = resolve(repoRoot, 'node_modules/svelte');
+const tscPath = require.resolve('typescript/lib/tsc.js');
+
+if (!existsSync(resolve(packageDir, 'package.json'))) {
+ console.error(`Package directory is missing package.json: ${packageDir}`);
+ console.error('Run: nix develop . --command bazel build //:pkg');
+ process.exit(1);
+}
+
+if (!existsSync(resolve(svelteDir, 'package.json'))) {
+ console.error(`Svelte peer dependency is missing: ${svelteDir}`);
+ console.error('Run: pnpm install');
+ process.exit(1);
+}
+
+const tempDir = await mkdtemp(join(tmpdir(), 'tinyvectors-consumer-'));
+
+try {
+ await mkdir(join(tempDir, 'node_modules/@tummycrypt'), { recursive: true });
+ await symlink(
+ packageDir,
+ join(tempDir, 'node_modules/@tummycrypt/tinyvectors'),
+ process.platform === 'win32' ? 'junction' : 'dir',
+ );
+ await symlink(
+ svelteDir,
+ join(tempDir, 'node_modules/svelte'),
+ process.platform === 'win32' ? 'junction' : 'dir',
+ );
+
+ await writeFile(
+ join(tempDir, 'consumer-runtime.mjs'),
+ `
+import * as root from '@tummycrypt/tinyvectors';
+import * as motion from '@tummycrypt/tinyvectors/motion';
+import * as core from '@tummycrypt/tinyvectors/core';
+import * as themes from '@tummycrypt/tinyvectors/themes';
+import * as svelteComponents from '@tummycrypt/tinyvectors/svelte';
+import { readFileSync } from 'node:fs';
+
+const cssUrl = import.meta.resolve('@tummycrypt/tinyvectors/themes/css');
+const css = readFileSync(new URL(cssUrl), 'utf8');
+const requiredRoot = ['BlobPhysics', 'DeviceMotion', 'TinyVectors', 'THEME_PRESETS'];
+const requiredMotion = ['DeviceMotion', 'ScrollHandler', 'mapClientPointToPhysics', 'createPointerPhysicsController'];
+const tinylandColors = root.THEME_PRESETS?.tinyland?.colors?.map((color) => color.color) ?? [];
+const missing = [
+ ...requiredRoot.filter((name) => !(name in root)).map((name) => \`root:\${name}\`),
+ ...requiredMotion.filter((name) => !(name in motion)).map((name) => \`motion:\${name}\`),
+ ...(!('BlobPhysics' in core) ? ['core:BlobPhysics'] : []),
+ ...(!('THEME_PRESETS' in themes) ? ['themes:THEME_PRESETS'] : []),
+ ...(tinylandColors.includes('rgba(139, 92, 246, 0.55)') ? [] : ['root:THEME_PRESETS.tinyland.colors']),
+ ...(themes.getThemePreset?.('tinyland') === themes.THEME_PRESETS?.tinyland ? [] : ['themes:getThemePreset']),
+ ...(!('TinyVectors' in svelteComponents) ? ['svelte:TinyVectors'] : []),
+ ...(!('BlobSVG' in svelteComponents) ? ['svelte:BlobSVG'] : []),
+ ...(css.includes('--vector-tinyland-purple') ? [] : ['themes/css:variables']),
+];
+
+if (missing.length > 0) {
+ throw new Error(\`Missing exports: \${missing.join(', ')}\`);
+}
+`.trimStart(),
+ );
+
+ await writeFile(
+ join(tempDir, 'consumer-types.ts'),
+ `
+import { BlobPhysics, DeviceMotion, TinyVectors, THEME_PRESETS } from '@tummycrypt/tinyvectors';
+import type { ScrollHandlerConfig as RootScrollHandlerConfig } from '@tummycrypt/tinyvectors';
+import type { ThemePreset, ThemePresetName } from '@tummycrypt/tinyvectors/core';
+import {
+\tScrollHandler,
+\tcreatePointerPhysicsController,
+\tmapClientPointToPhysics,
+\ttype MotionVector,
+\ttype PointerBounds,
+\ttype PointerCancelEventName,
+\ttype ScrollHandlerConfig,
+} from '@tummycrypt/tinyvectors/motion';
+import { getThemePreset } from '@tummycrypt/tinyvectors/themes';
+import {
+\tBlobSVG,
+\ttype BlobSVGProps,
+\ttype TinyVectorsDeviceMotionStatus,
+\ttype TinyVectorsProps,
+} from '@tummycrypt/tinyvectors/svelte';
+import type { ComponentProps } from 'svelte';
+
+const bounds: PointerBounds = { left: 0, top: 0, width: 100, height: 100 };
+const cancelEvent: PointerCancelEventName = 'pointercancel';
+const scrollConfig: ScrollHandlerConfig = { decayRate: 0.9, maxForces: 2 };
+const rootScrollConfig: RootScrollHandlerConfig = { maxForces: 0 };
+const scrollHandler = new ScrollHandler(scrollConfig);
+const point = mapClientPointToPhysics(50, 50, bounds);
+const sample: MotionVector = { x: 0, y: 0, z: 1 };
+const props: ComponentProps = { theme: 'tinyland', enableDeviceMotion: true };
+const explicitProps: TinyVectorsProps = props;
+const motionStatus: TinyVectorsDeviceMotionStatus = {
+\tenabled: true,
+\tsupported: true,
+\trequiresPermission: false,
+\tpermissionState: 'granted',
+\tactive: true,
+};
+const blobProps: BlobSVGProps = { blobs: [] };
+const themeName: ThemePresetName = 'tinyland';
+const themePreset: ThemePreset = THEME_PRESETS[themeName];
+const names = [BlobPhysics, DeviceMotion, TinyVectors, BlobSVG, ScrollHandler, createPointerPhysicsController, THEME_PRESETS, getThemePreset, scrollHandler, scrollConfig, rootScrollConfig, point, sample, explicitProps, motionStatus, blobProps, themePreset, cancelEvent];
+console.log(names.length);
+`.trimStart(),
+ );
+
+ await writeFile(
+ join(tempDir, 'tsconfig.json'),
+ `${JSON.stringify(
+ {
+ compilerOptions: {
+ target: 'ES2022',
+ module: 'NodeNext',
+ moduleResolution: 'NodeNext',
+ strict: true,
+ skipLibCheck: false,
+ noEmit: true,
+ },
+ include: ['consumer-types.ts'],
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+
+ run(process.execPath, ['consumer-runtime.mjs'], tempDir);
+ run(process.execPath, [tscPath, '-p', 'tsconfig.json'], tempDir);
+ console.log(`package consumer check passed for ${packageDir}`);
+} finally {
+ if (process.env.TINYVECTORS_KEEP_CONSUMER_CHECK !== '1') {
+ await rm(tempDir, { recursive: true, force: true });
+ } else {
+ console.log(`kept consumer check workspace: ${tempDir}`);
+ }
+}
+
+function run(command, args, cwd) {
+ const result = spawnSync(command, args, {
+ cwd,
+ stdio: 'inherit',
+ env: process.env,
+ });
+
+ if (result.status !== 0) {
+ process.exit(result.status ?? 1);
+ }
+}
diff --git a/scripts/check-release-metadata.mjs b/scripts/check-release-metadata.mjs
index 2c95fde..0032888 100644
--- a/scripts/check-release-metadata.mjs
+++ b/scripts/check-release-metadata.mjs
@@ -6,7 +6,33 @@ const read = (relativePath) =>
const packageJson = JSON.parse(read('../package.json'));
const moduleBazel = read('../MODULE.bazel');
const buildBazel = read('../BUILD.bazel');
+const ciWorkflow = read('../.github/workflows/ci.yml');
+const publishWorkflow = read('../.github/workflows/publish.yml');
const expectedPnpmVersion = packageJson.packageManager?.replace(/^pnpm@/, '');
+const expectedNodeMajor = packageJson.engines?.node?.match(/>=\s*(\d+)/)?.[1];
+const expectedBazelTargets =
+ '//:pkg //:package_consumer_check //:bundle_size_check //:typecheck //:test';
+const expectedPackageDir = './bazel-bin/pkg';
+const expectedPackageConsumerCommand = 'node scripts/check-package-consumer.mjs ./bazel-bin/pkg';
+const expectedPackageCheckCommand = 'pnpm run check:package && pnpm run check:bundle-size';
+const expectedPrepublishOnlyCommand =
+ 'pnpm run check:release-metadata && pnpm run build && pnpm run check:package && pnpm run check:bundle-size';
+const expectedSharedWorkflowInputs = {
+ runner_mode: 'hosted',
+ workspace_mode: 'isolated',
+ publish_mode: 'same_runner',
+ node_versions: `["${expectedNodeMajor}"]`,
+ publish_node_version: expectedNodeMajor,
+ pnpm_version: expectedPnpmVersion,
+ metadata_check_command: 'pnpm run check:release-metadata',
+ typecheck_command: 'pnpm run check',
+ unit_test_command: 'pnpm run test',
+ build_command: 'pnpm run build',
+ package_check_command: expectedPackageCheckCommand,
+ bazel_targets: expectedBazelTargets,
+ package_dir: expectedPackageDir,
+ npm_access: 'public',
+};
const extract = (source, pattern, label) => {
const match = source.match(pattern);
@@ -16,6 +42,24 @@ const extract = (source, pattern, label) => {
return match[1];
};
+const extractWorkflowValue = (source, key, label) => {
+ const rawValue = extract(source, new RegExp(`^\\s*${key}:\\s*(.+?)\\s*$`, 'm'), label).trim();
+ if (
+ (rawValue.startsWith("'") && rawValue.endsWith("'")) ||
+ (rawValue.startsWith('"') && rawValue.endsWith('"'))
+ ) {
+ return rawValue.slice(1, -1);
+ }
+ return rawValue;
+};
+
+const sharedPackageWorkflow = (source, label) =>
+ extract(
+ source,
+ /uses:\s*(tinyland-inc\/ci-templates\/\.github\/workflows\/js-bazel-package\.yml@[0-9a-f]{40})/,
+ label,
+ );
+
const checks = [
{
label: 'MODULE.bazel version',
@@ -49,10 +93,68 @@ const checks = [
actual: extract(moduleBazel, /pnpm_version = "([^"]+)"/, 'pnpm_version'),
expected: expectedPnpmVersion,
},
+ {
+ label: 'MODULE.bazel Node toolchain major',
+ actual: extract(moduleBazel, /node_version = "(\d+)\./, 'node_version'),
+ expected: expectedNodeMajor,
+ },
+ {
+ label: 'CI reusable package workflow',
+ actual: sharedPackageWorkflow(ciWorkflow, 'CI reusable workflow'),
+ expected: sharedPackageWorkflow(publishWorkflow, 'publish reusable workflow'),
+ },
+ {
+ label: 'package consumer check script',
+ actual: packageJson.scripts?.['check:package-consumer'],
+ expected: expectedPackageConsumerCommand,
+ },
+ {
+ label: 'bundle size check script',
+ actual: packageJson.scripts?.['check:bundle-size'],
+ expected: 'node scripts/check-bundle-size.mjs',
+ },
+ {
+ label: 'prepublishOnly script',
+ actual: packageJson.scripts?.prepublishOnly,
+ expected: expectedPrepublishOnlyCommand,
+ },
+ {
+ label: 'CI publish dry-run',
+ actual: extractWorkflowValue(ciWorkflow, 'dry_run', 'CI dry_run'),
+ expected: 'true',
+ },
+ {
+ label: 'tag publish dry-run',
+ actual: extractWorkflowValue(publishWorkflow, 'dry_run', 'publish dry_run'),
+ expected: 'false',
+ },
];
+for (const [key, expected] of Object.entries(expectedSharedWorkflowInputs)) {
+ checks.push(
+ {
+ label: `CI ${key}`,
+ actual: extractWorkflowValue(ciWorkflow, key, `CI ${key}`),
+ expected,
+ },
+ {
+ label: `publish ${key}`,
+ actual: extractWorkflowValue(publishWorkflow, key, `publish ${key}`),
+ expected,
+ },
+ );
+}
+
const failures = checks.filter((check) => check.actual !== check.expected);
+if (packageJson.publishConfig?.provenance && !/id-token:\s*write/.test(publishWorkflow)) {
+ failures.push({
+ label: 'publish workflow id-token permission',
+ actual: 'missing',
+ expected: 'write',
+ });
+}
+
if (failures.length > 0) {
for (const failure of failures) {
console.error(
diff --git a/scripts/copy-svelte-declarations.mjs b/scripts/copy-svelte-declarations.mjs
new file mode 100644
index 0000000..c14489e
--- /dev/null
+++ b/scripts/copy-svelte-declarations.mjs
@@ -0,0 +1,32 @@
+import { copyFile, mkdir, rm, writeFile } from 'node:fs/promises';
+
+const declarationPairs = [
+ ['BlobSVG.svelte.d.ts', 'BlobSVG.d.ts'],
+ ['TinyVectors.svelte.d.ts', 'TinyVectors.d.ts'],
+];
+const sourceDir = new URL('../src/svelte/', import.meta.url);
+const outputDir = new URL('../dist-types/svelte/', import.meta.url);
+
+await mkdir(outputDir, { recursive: true });
+
+await Promise.all(
+ declarationPairs.map(([sourceName, outputName]) =>
+ copyFile(new URL(sourceName, sourceDir), new URL(outputName, outputDir)),
+ ),
+);
+
+await writeFile(
+ new URL('index.d.ts', outputDir),
+ [
+ "export { default as TinyVectors, type TinyVectorsExports, type TinyVectorsProps } from './TinyVectors.js';",
+ "export type { TinyVectorsDeviceMotionStatus } from './types.js';",
+ "export { default as BlobSVG, type BlobSVGProps } from './BlobSVG.js';",
+ '',
+ ].join('\n'),
+);
+
+await Promise.all([
+ rm(new URL('index.d.ts.map', outputDir), { force: true }),
+ rm(new URL('BlobSVG.svelte.d.ts', outputDir), { force: true }),
+ rm(new URL('TinyVectors.svelte.d.ts', outputDir), { force: true }),
+]);
diff --git a/scripts/probe-motion-cdp.mjs b/scripts/probe-motion-cdp.mjs
new file mode 100644
index 0000000..4aaac0e
--- /dev/null
+++ b/scripts/probe-motion-cdp.mjs
@@ -0,0 +1,676 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const host = '127.0.0.1';
+const vitePort = Number(process.env.TINYVECTORS_VITE_PORT ?? 5176);
+const viteHmrPort = Number(process.env.TINYVECTORS_VITE_HMR_PORT ?? vitePort + 19000);
+const cdpPort = Number(process.env.TINYVECTORS_CDP_PORT ?? 9228);
+const chromePath = findChrome();
+
+if (!chromePath) {
+ console.error('Chrome executable not found. Set CHROME_PATH to run this probe.');
+ process.exit(1);
+}
+
+const children = new Set();
+
+process.on('exit', () => {
+ for (const child of children) {
+ child.kill('SIGTERM');
+ }
+});
+
+function spawnChild(command, args, options = {}) {
+ const child = spawn(command, args, {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ env: process.env,
+ ...options,
+ });
+ children.add(child);
+ child.once('exit', () => children.delete(child));
+ return child;
+}
+
+function findChrome() {
+ if (process.env.CHROME_PATH) return process.env.CHROME_PATH;
+
+ const candidates = [
+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+ '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+ 'google-chrome',
+ 'google-chrome-stable',
+ 'chromium',
+ 'chromium-browser',
+ ];
+
+ for (const candidate of candidates) {
+ if (candidate.startsWith('/')) {
+ const result = spawnSync('test', ['-x', candidate]);
+ if (result.status === 0) return candidate;
+ continue;
+ }
+
+ const result = spawnSync('command', ['-v', candidate], {
+ shell: true,
+ encoding: 'utf8',
+ });
+ if (result.status === 0 && result.stdout.trim()) {
+ return result.stdout.trim();
+ }
+ }
+
+ return null;
+}
+
+async function delay(ms) {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForFetch(url, timeoutMs = 15000) {
+ const started = Date.now();
+ let lastError;
+
+ while (Date.now() - started < timeoutMs) {
+ try {
+ const response = await fetch(url);
+ if (response.ok) return response;
+ lastError = new Error(`${response.status} ${response.statusText}`);
+ } catch (error) {
+ lastError = error;
+ }
+ await delay(100);
+ }
+
+ throw lastError ?? new Error(`Timed out waiting for ${url}`);
+}
+
+async function waitForJson(url, timeoutMs = 15000) {
+ const response = await waitForFetch(url, timeoutMs);
+ return await response.json();
+}
+
+async function terminateChildren() {
+ const exiting = [...children].map(
+ (child) =>
+ new Promise((resolve) => {
+ child.once('exit', resolve);
+ child.kill('SIGTERM');
+ setTimeout(resolve, 2000);
+ }),
+ );
+
+ await Promise.all(exiting);
+ children.clear();
+}
+
+async function removeDirectoryWithRetry(directory) {
+ for (let attempt = 0; attempt < 5; attempt++) {
+ try {
+ await rm(directory, { recursive: true, force: true });
+ return;
+ } catch (error) {
+ if (attempt === 4) throw error;
+ await delay(200);
+ }
+ }
+}
+
+class CdpClient {
+ constructor(url) {
+ this.nextId = 1;
+ this.pending = new Map();
+ this.ws = new WebSocket(url);
+ this.ready = new Promise((resolve, reject) => {
+ this.ws.addEventListener('open', resolve, { once: true });
+ this.ws.addEventListener('error', reject, { once: true });
+ });
+ this.ws.addEventListener('message', (event) => {
+ const message = JSON.parse(event.data);
+ if (!message.id || !this.pending.has(message.id)) return;
+
+ const pending = this.pending.get(message.id);
+ this.pending.delete(message.id);
+
+ if (message.error) {
+ pending.reject(new Error(`${message.error.code}: ${message.error.message}`));
+ } else {
+ pending.resolve(message.result ?? {});
+ }
+ });
+ }
+
+ async send(method, params = {}) {
+ await this.ready;
+
+ const id = this.nextId++;
+ this.ws.send(JSON.stringify({ id, method, params }));
+
+ return await new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ if (!this.pending.has(id)) return;
+ this.pending.delete(id);
+ reject(new Error(`Timed out waiting for ${method}`));
+ }, 10000);
+
+ this.pending.set(id, {
+ resolve(value) {
+ clearTimeout(timer);
+ resolve(value);
+ },
+ reject(error) {
+ clearTimeout(timer);
+ reject(error);
+ },
+ });
+ });
+ }
+
+ close() {
+ this.ws.close();
+ }
+}
+
+async function evaluate(client, expression) {
+ const result = await client.send('Runtime.evaluate', {
+ expression,
+ awaitPromise: true,
+ returnByValue: true,
+ });
+
+ if (result.exceptionDetails) {
+ throw new Error(JSON.stringify(result.exceptionDetails));
+ }
+
+ return result.result.value;
+}
+
+function assert(condition, message) {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+function parseMotionStatus(status) {
+ const match = /^motion x (-?\d+(?:\.\d+)?) y (-?\d+(?:\.\d+)?) z (-?\d+(?:\.\d+)?)$/.exec(status ?? '');
+ if (!match) return null;
+ return {
+ x: Number(match[1]),
+ y: Number(match[2]),
+ z: Number(match[3]),
+ };
+}
+
+let chromeProfile;
+let client;
+
+try {
+ const vite = spawnChild('pnpm', [
+ 'exec',
+ 'vite',
+ '--config',
+ 'vite.dev.config.ts',
+ '--host',
+ host,
+ '--port',
+ String(vitePort),
+ ], {
+ env: {
+ ...process.env,
+ CI: 'true',
+ TINYVECTORS_VITE_PORT: String(vitePort),
+ TINYVECTORS_VITE_HMR_PORT: String(viteHmrPort),
+ },
+ });
+
+ vite.stderr.on('data', (chunk) => {
+ process.stderr.write(chunk);
+ });
+
+ await waitForFetch(`http://${host}:${vitePort}/`);
+
+ chromeProfile = await mkdtemp(join(tmpdir(), 'tinyvectors-cdp-profile-'));
+ const chrome = spawnChild(chromePath, [
+ '--headless=new',
+ '--disable-gpu',
+ '--disable-dev-shm-usage',
+ '--no-first-run',
+ '--no-default-browser-check',
+ `--remote-debugging-address=${host}`,
+ `--remote-debugging-port=${cdpPort}`,
+ `--user-data-dir=${chromeProfile}`,
+ 'about:blank',
+ ]);
+
+ chrome.stderr.on('data', (chunk) => {
+ if (process.env.DEBUG_CHROME === 'true') {
+ process.stderr.write(chunk);
+ }
+ });
+
+ const version = await waitForJson(`http://${host}:${cdpPort}/json/version`);
+ const tabs = await waitForJson(`http://${host}:${cdpPort}/json/list`);
+ const page = tabs.find((tab) => tab.type === 'page') ?? tabs[0];
+
+ client = new CdpClient(page.webSocketDebuggerUrl);
+ await client.send('Runtime.enable');
+ await client.send('Page.enable');
+ await client.send('Page.addScriptToEvaluateOnNewDocument', {
+ source: `
+ window.__tinyvectorsEvents = [];
+ (() => {
+ const originalAddEventListener = EventTarget.prototype.addEventListener;
+ const originalRemoveEventListener = EventTarget.prototype.removeEventListener;
+ const listenerIds = new WeakMap();
+ const activeWindowListeners = new Map();
+ let nextListenerId = 1;
+
+ const listenerId = (listener) => {
+ if ((typeof listener !== 'function' && typeof listener !== 'object') || listener === null) {
+ return String(listener);
+ }
+ if (!listenerIds.has(listener)) {
+ listenerIds.set(listener, nextListenerId++);
+ }
+ return listenerIds.get(listener);
+ };
+
+ window.__tinyvectorsListenerLedger = {
+ snapshot() {
+ const counts = {};
+ for (const type of activeWindowListeners.values()) {
+ counts[type] = (counts[type] || 0) + 1;
+ }
+ return counts;
+ },
+ };
+
+ EventTarget.prototype.addEventListener = function(type, listener, options) {
+ if (this === window && listener) {
+ activeWindowListeners.set(type + ':' + listenerId(listener), type);
+ }
+ return originalAddEventListener.call(this, type, listener, options);
+ };
+
+ EventTarget.prototype.removeEventListener = function(type, listener, options) {
+ if (this === window && listener) {
+ activeWindowListeners.delete(type + ':' + listenerId(listener));
+ }
+ return originalRemoveEventListener.call(this, type, listener, options);
+ };
+
+ originalAddEventListener.call(window, 'deviceorientation', (event) => {
+ window.__tinyvectorsEvents.push({
+ type: 'deviceorientation',
+ alpha: event.alpha,
+ beta: event.beta,
+ gamma: event.gamma,
+ at: performance.now()
+ });
+ });
+ originalAddEventListener.call(window, 'devicemotion', (event) => {
+ const gravity = event.accelerationIncludingGravity;
+ window.__tinyvectorsEvents.push({
+ type: 'devicemotion',
+ x: gravity && gravity.x,
+ y: gravity && gravity.y,
+ z: gravity && gravity.z,
+ at: performance.now()
+ });
+ });
+ })();
+ `,
+ });
+
+ const disabledUrl = `http://${host}:${vitePort}/?controls=true&animated=true&deviceMotion=false&pointerPhysics=false&scrollPhysics=false&blobs=8&listenerProbe=1`;
+ await client.send('Page.navigate', { url: disabledUrl });
+ await delay(1000);
+
+ const disabledInitial = await evaluate(client, `({
+ motionStatus: window.__tinyvectorsDeviceMotionStatus?.() ?? null,
+ pathCount: document.querySelectorAll('path').length,
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+
+ assert(disabledInitial.pathCount > 0, 'TinyVectors did not render when IO features were disabled.');
+ assert(
+ disabledInitial.motionStatus?.enabled === false,
+ 'Disabled device motion page reported device motion enabled.',
+ );
+ assert(
+ disabledInitial.motionStatus?.active === false,
+ 'Disabled device motion page reported an active listener.',
+ );
+ assert(!disabledInitial.listeners.wheel, 'Wheel listener attached when scroll physics was disabled.');
+ assert(
+ !disabledInitial.listeners.pointermove,
+ 'Pointer listener attached when pointer physics was disabled.',
+ );
+ assert(
+ !disabledInitial.listeners.pointercancel,
+ 'Pointer cancel listener attached when pointer physics was disabled.',
+ );
+ assert(
+ !disabledInitial.listeners.deviceorientation,
+ 'Device orientation listener attached when device motion was disabled.',
+ );
+
+ const pageUrl = `http://${host}:${vitePort}/?controls=true&animated=true&deviceMotion=true&pointerPhysics=false&scrollPhysics=false&blobs=8&motionIdleReset=700`;
+ await client.send('Page.navigate', { url: pageUrl });
+ await delay(1500);
+
+ const initial = await evaluate(client, `({
+ secure: window.isSecureContext,
+ hasDeviceMotionEvent: 'DeviceMotionEvent' in window,
+ hasDeviceOrientationEvent: 'DeviceOrientationEvent' in window,
+ hasAccelerometer: 'Accelerometer' in window,
+ motionStatus: window.__tinyvectorsDeviceMotionStatus?.() ?? null,
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ pathCount: document.querySelectorAll('path').length,
+ firstPath: document.querySelector('path')?.getAttribute('d') ?? null,
+ events: window.__tinyvectorsEvents
+ })`);
+
+ assert(initial.secure, 'Page must be a secure context for device motion APIs.');
+ assert(initial.hasDeviceOrientationEvent, 'DeviceOrientationEvent is not exposed in Chrome.');
+ assert(initial.pathCount > 0, 'TinyVectors SVG paths were not rendered.');
+ assert(initial.motionStatus?.enabled === true, 'Device motion status did not report enabled.');
+ assert(initial.motionStatus?.supported === true, 'Device motion status did not report support.');
+ assert(
+ initial.motionStatus?.permissionState === 'granted',
+ `Device motion status did not report granted; got ${initial.motionStatus?.permissionState}.`,
+ );
+ assert(initial.motionStatus?.active === true, 'Device motion status did not report active listener.');
+
+ await client.send('Runtime.evaluate', {
+ expression: `document.getElementById('spoof-tilt-btn')?.click()`,
+ awaitPromise: true,
+ });
+ await delay(350);
+
+ const afterSpoof = await evaluate(client, `({
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ firstPath: document.querySelector('path')?.getAttribute('d') ?? null,
+ events: window.__tinyvectorsEvents
+ })`);
+
+ assert(
+ afterSpoof.status?.startsWith('motion x '),
+ `Synthetic orientation did not reach TinyVectors; status was ${afterSpoof.status}`,
+ );
+ assert(afterSpoof.events.length > initial.events.length, 'Synthetic orientation was not observed.');
+ assert(afterSpoof.firstPath !== initial.firstPath, 'Synthetic orientation did not change blob geometry.');
+ const syntheticMotion = parseMotionStatus(afterSpoof.status);
+ assert(syntheticMotion, `Synthetic orientation status was not parseable: ${afterSpoof.status}`);
+ assert(
+ syntheticMotion.x < 0 && syntheticMotion.y > 0,
+ `Synthetic orientation did not preserve expected direction; got ${afterSpoof.status}`,
+ );
+
+ await delay(550);
+ const afterIdleReset = await evaluate(client, `({
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ events: window.__tinyvectorsEvents
+ })`);
+
+ assert(
+ afterIdleReset.status === 'motion x 0.00 y 0.00 z 0.00',
+ `Device orientation idle reset did not neutralize motion; status was ${afterIdleReset.status}`,
+ );
+
+ await client.send('Emulation.setEmulatedMedia', {
+ features: [{ name: 'prefers-reduced-motion', value: 'reduce' }],
+ });
+ await delay(350);
+
+ const afterReducedMotion = await evaluate(client, `({
+ motionStatus: window.__tinyvectorsDeviceMotionStatus?.() ?? null,
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+
+ assert(
+ afterReducedMotion.status === 'motion x 0.00 y 0.00 z 0.00',
+ `Reduced motion did not neutralize active motion; status was ${afterReducedMotion.status}`,
+ );
+ assert(
+ afterReducedMotion.motionStatus?.active === false,
+ 'Reduced motion did not stop the device orientation listener.',
+ );
+ assert(
+ !afterReducedMotion.listeners.deviceorientation,
+ 'Device orientation listener leaked while reduced motion was enabled.',
+ );
+
+ await client.send('Emulation.setEmulatedMedia', {
+ features: [{ name: 'prefers-reduced-motion', value: 'no-preference' }],
+ });
+ await delay(350);
+
+ const afterReducedMotionRestore = await evaluate(client, `({
+ motionStatus: window.__tinyvectorsDeviceMotionStatus?.() ?? null,
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+
+ assert(
+ afterReducedMotionRestore.motionStatus?.active === true,
+ 'Device orientation listener did not restart after reduced motion was disabled.',
+ );
+ assert(
+ afterReducedMotionRestore.listeners.deviceorientation === 1,
+ `Expected one deviceorientation listener after reduced motion restore, got ${afterReducedMotionRestore.listeners.deviceorientation}.`,
+ );
+
+ await client.send('DeviceOrientation.setDeviceOrientationOverride', {
+ alpha: 180,
+ beta: 50,
+ gamma: -40,
+ });
+ await delay(350);
+
+ const afterCdpOrientation = await evaluate(client, `({
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ firstPath: document.querySelector('path')?.getAttribute('d') ?? null,
+ events: window.__tinyvectorsEvents
+ })`);
+
+ assert(
+ afterCdpOrientation.events.length > afterSpoof.events.length,
+ 'CDP device orientation override did not emit a page event.',
+ );
+ assert(
+ afterCdpOrientation.firstPath !== afterSpoof.firstPath,
+ 'CDP device orientation override did not change blob geometry.',
+ );
+ const cdpOrientationMotion = parseMotionStatus(afterCdpOrientation.status);
+ assert(
+ cdpOrientationMotion,
+ `CDP orientation status was not parseable: ${afterCdpOrientation.status}`,
+ );
+ assert(
+ cdpOrientationMotion.x < 0 && cdpOrientationMotion.y > 0,
+ `CDP orientation did not preserve expected direction; got ${afterCdpOrientation.status}`,
+ );
+
+ const listenerProbeUrl = `http://${host}:${vitePort}/?controls=true&animated=true&deviceMotion=true&pointerPhysics=true&scrollPhysics=true&blobs=8&listenerProbe=1`;
+ await client.send('Page.navigate', { url: listenerProbeUrl });
+ await delay(1500);
+
+ const listenerInitial = await evaluate(client, `({
+ pathCount: document.querySelectorAll('path').length,
+ bodyPathCount: document.querySelectorAll('svg g')[1]?.querySelectorAll('path').length ?? 0,
+ gradientCount: document.querySelectorAll('radialGradient').length,
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+
+ assert(listenerInitial.pathCount === 24, `Expected 24 SVG paths, got ${listenerInitial.pathCount}.`);
+ assert(listenerInitial.bodyPathCount === 8, `Expected 8 body paths, got ${listenerInitial.bodyPathCount}.`);
+ assert(
+ listenerInitial.gradientCount === 24,
+ `Expected 24 radial gradients, got ${listenerInitial.gradientCount}.`,
+ );
+ assert(
+ listenerInitial.listeners.wheel === 1,
+ `Expected one wheel listener, got ${listenerInitial.listeners.wheel}.`,
+ );
+ assert(
+ listenerInitial.listeners.pointermove === 1,
+ `Expected one pointermove listener, got ${listenerInitial.listeners.pointermove}.`,
+ );
+ assert(
+ listenerInitial.listeners.pointerout === 1,
+ `Expected one pointerout listener, got ${listenerInitial.listeners.pointerout}.`,
+ );
+ assert(
+ listenerInitial.listeners.pointercancel === 1,
+ `Expected one pointercancel listener, got ${listenerInitial.listeners.pointercancel}.`,
+ );
+ assert(
+ listenerInitial.listeners.blur === 1,
+ `Expected one blur listener, got ${listenerInitial.listeners.blur}.`,
+ );
+ assert(
+ listenerInitial.listeners.deviceorientation === 1,
+ `Expected one deviceorientation listener, got ${listenerInitial.listeners.deviceorientation}.`,
+ );
+
+ await client.send('Runtime.evaluate', {
+ expression: `document.getElementById('scroll-physics')?.click()`,
+ awaitPromise: true,
+ });
+ await delay(300);
+ const afterScrollOff = await evaluate(client, `({
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+ assert(!afterScrollOff.listeners.wheel, 'Wheel listener leaked after disabling scroll physics.');
+
+ await client.send('Runtime.evaluate', {
+ expression: `document.getElementById('pointer-physics')?.click()`,
+ awaitPromise: true,
+ });
+ await delay(300);
+ const afterPointerOff = await evaluate(client, `({
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+ assert(!afterPointerOff.listeners.pointermove, 'Pointer listener leaked after disabling pointer physics.');
+ assert(!afterPointerOff.listeners.pointerout, 'Pointer exit listener leaked after disabling pointer physics.');
+ assert(!afterPointerOff.listeners.pointercancel, 'Pointer cancel listener leaked after disabling pointer physics.');
+ assert(!afterPointerOff.listeners.blur, 'Pointer blur listener leaked after disabling pointer physics.');
+
+ await client.send('Runtime.evaluate', {
+ expression: `document.getElementById('device-motion')?.click()`,
+ awaitPromise: true,
+ });
+ await delay(300);
+ const afterDeviceMotionOff = await evaluate(client, `({
+ listeners: window.__tinyvectorsListenerLedger?.snapshot?.() ?? {}
+ })`);
+ assert(
+ !afterDeviceMotionOff.listeners.deviceorientation,
+ 'Device orientation listener leaked after disabling device motion.',
+ );
+
+ await client.send('Emulation.setSensorOverrideEnabled', {
+ type: 'accelerometer',
+ enabled: true,
+ metadata: { available: true, minimumFrequency: 1, maximumFrequency: 60 },
+ });
+ await client.send('Page.navigate', { url: `${pageUrl}&accelerometerProbe=1` });
+ await delay(1500);
+
+ const beforeCdpAccelerometer = await evaluate(client, `({
+ hasAccelerometer: 'Accelerometer' in window,
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ firstPath: document.querySelector('path')?.getAttribute('d') ?? null,
+ events: window.__tinyvectorsEvents
+ })`);
+
+ await client.send('Emulation.setSensorOverrideReadings', {
+ type: 'accelerometer',
+ reading: {
+ xyz: {
+ x: 4,
+ y: -3,
+ z: 9.80665,
+ },
+ },
+ });
+ await delay(1000);
+
+ const afterCdpAccelerometer = await evaluate(client, `({
+ status: document.getElementById('motion-status')?.textContent ?? null,
+ firstPath: document.querySelector('path')?.getAttribute('d') ?? null,
+ events: window.__tinyvectorsEvents
+ })`);
+
+ const cdpAccelerometerChanged =
+ afterCdpAccelerometer.firstPath !== beforeCdpAccelerometer.firstPath;
+
+ console.log(
+ JSON.stringify(
+ {
+ chrome: version.Browser,
+ pageUrl,
+ initial: {
+ secure: initial.secure,
+ hasDeviceMotionEvent: initial.hasDeviceMotionEvent,
+ hasDeviceOrientationEvent: initial.hasDeviceOrientationEvent,
+ hasAccelerometer: initial.hasAccelerometer,
+ motionStatus: initial.motionStatus,
+ pathCount: initial.pathCount,
+ },
+ disabledInitial: {
+ motionStatus: disabledInitial.motionStatus,
+ pathCount: disabledInitial.pathCount,
+ listeners: disabledInitial.listeners,
+ },
+ syntheticOrientation: {
+ status: afterSpoof.status,
+ motion: syntheticMotion,
+ events: afterSpoof.events.length,
+ pathChanged: afterSpoof.firstPath !== initial.firstPath,
+ idleResetStatus: afterIdleReset.status,
+ },
+ reducedMotion: {
+ status: afterReducedMotion.status,
+ activeAfterReduce: afterReducedMotion.motionStatus?.active,
+ listenersAfterReduce: afterReducedMotion.listeners,
+ activeAfterRestore: afterReducedMotionRestore.motionStatus?.active,
+ listenersAfterRestore: afterReducedMotionRestore.listeners,
+ },
+ cdpOrientation: {
+ status: afterCdpOrientation.status,
+ motion: cdpOrientationMotion,
+ events: afterCdpOrientation.events.length,
+ pathChanged: afterCdpOrientation.firstPath !== afterSpoof.firstPath,
+ lastEvent: afterCdpOrientation.events.at(-1),
+ },
+ cdpAccelerometer: {
+ hasAccelerometer: beforeCdpAccelerometer.hasAccelerometer,
+ status: afterCdpAccelerometer.status,
+ windowEvents: afterCdpAccelerometer.events.length,
+ pathChanged: cdpAccelerometerChanged,
+ note: 'TinyVectors uses DeviceOrientationEvent/TiltSource; raw accelerometer CDP is informational.',
+ },
+ listenerLifecycle: {
+ initial: listenerInitial.listeners,
+ afterScrollOff: afterScrollOff.listeners,
+ afterPointerOff: afterPointerOff.listeners,
+ afterDeviceMotionOff: afterDeviceMotionOff.listeners,
+ },
+ },
+ null,
+ 2,
+ ),
+ );
+} catch (error) {
+ console.error(error);
+ process.exitCode = 1;
+} finally {
+ client?.close();
+ await terminateChildren();
+ if (chromeProfile) {
+ await removeDirectoryWithRetry(chromeProfile);
+ }
+}
diff --git a/src/core/BlobPhysics.ts b/src/core/BlobPhysics.ts
index 5bb61bc..1f22e88 100644
--- a/src/core/BlobPhysics.ts
+++ b/src/core/BlobPhysics.ts
@@ -16,6 +16,10 @@ import type { ConvexBlob, GravityVector, TiltVector } from './types.js';
import { SpatialHash } from './SpatialHash.js';
import { GaussianKernel } from './GaussianKernel.js';
import { SpringSystem, DEFAULT_SPRING_CONFIG, type SpringConfig } from './SpringSystem.js';
+import { directionalBiasField } from './InteractionField.js';
+
+const ACCELEROMETER_STRENGTH = 0.0008;
+const ACCELEROMETER_MAX_FORCE = 0.003;
export interface BlobPhysicsConfig {
antiClusteringStrength: number;
@@ -33,7 +37,7 @@ export interface BlobPhysicsConfig {
springConfig: Partial;
}
-const DEFAULT_CONFIG: BlobPhysicsConfig = {
+export const DEFAULT_BLOB_PHYSICS_CONFIG: BlobPhysicsConfig = {
antiClusteringStrength: 0.15,
bounceDamping: 0.7,
deformationSpeed: 0.5,
@@ -61,6 +65,7 @@ export class BlobPhysics {
private gravity: GravityVector = { x: 0, y: 0 };
+ private gravityField: GravityVector = { x: 0, y: 0 };
private tilt: TiltVector = { x: 0, y: 0, z: 0 };
private scrollStickiness = 0;
@@ -72,15 +77,11 @@ export class BlobPhysics {
private spatialHash: SpatialHash;
private gaussianKernel: GaussianKernel;
private springSystem: SpringSystem;
-
- // Pre-allocated scratch buffers for hot-path passes (no per-frame allocation).
- private skinTensionScratch: Float32Array | null = null;
- private xsphDvX: Float32Array | null = null;
- private xsphDvY: Float32Array | null = null;
+ private controlRadiusScratch: number[] = [];
constructor(numBlobs: number, config: Partial = {}) {
this.numBlobs = numBlobs;
- this.config = { ...DEFAULT_CONFIG, ...config };
+ this.config = { ...DEFAULT_BLOB_PHYSICS_CONFIG, ...config };
this.spatialHash = new SpatialHash(60);
@@ -120,6 +121,11 @@ export class BlobPhysics {
setGravity(gravity: GravityVector): void {
this.gravity = gravity;
+ this.gravityField = directionalBiasField(
+ gravity,
+ ACCELEROMETER_STRENGTH,
+ ACCELEROMETER_MAX_FORCE,
+ );
}
@@ -159,70 +165,16 @@ export class BlobPhysics {
this.updateScreensaverPhysics(blob, deltaTime, time)
);
- // XSPH viscosity coupling — each blob's velocity drifts toward its
- // neighborhood-weighted velocity. This is what makes the swarm
- // behave as a fluid rather than 5 independent things; drag bleeds
- // absolute motion, XSPH bleeds *relative* motion between neighbors.
- // Macklin & Müller, Position Based Fluids, SIGGRAPH 2013.
- this.applyXSPHCoupling();
-
-
+
this.mouseVelX *= 0.96;
this.mouseVelY *= 0.96;
}
- private applyXSPHCoupling(): void {
- const blobs = this.blobs;
- const n = blobs.length;
- if (n < 2) return;
-
- if (!this.xsphDvX || !this.xsphDvY || this.xsphDvX.length < n) {
- this.xsphDvX = new Float32Array(n);
- this.xsphDvY = new Float32Array(n);
- }
- const dvX = this.xsphDvX;
- const dvY = this.xsphDvY;
- dvX.fill(0);
- dvY.fill(0);
-
- const eps = 0.4;
- const sigma = 80;
- const twoSigmaSq = 2 * sigma * sigma;
-
- for (let i = 0; i < n; i++) {
- const a = blobs[i];
- for (let j = i + 1; j < n; j++) {
- const b = blobs[j];
- const dx = b.currentX - a.currentX;
- const dy = b.currentY - a.currentY;
- const w = Math.exp(-(dx * dx + dy * dy) / twoSigmaSq);
- const dvx = w * (b.velocityX - a.velocityX);
- const dvy = w * (b.velocityY - a.velocityY);
- dvX[i] += dvx;
- dvY[i] += dvy;
- dvX[j] -= dvx;
- dvY[j] -= dvy;
- }
- }
-
- for (let i = 0; i < n; i++) {
- blobs[i].velocityX += eps * dvX[i];
- blobs[i].velocityY += eps * dvY[i];
- }
- }
-
- // Anti-clustering with Gaussian-falloff repulsion. The previous step-
- // function variant ((distance < requiredDistance) ? force : 0, plus
- // a separate sharp proximity multiplier at requiredDistance * 0.7)
- // produced a discontinuous force read as a "click" on near-contact.
- // exp(-r² / 2σ²) is C∞ smooth — force grows continuously, peaks at
- // zero distance, decays smoothly. Reuses the same Gaussian family as
- // the existing GaussianKernel.
private applyAntiClusteringWithSpatialHash(): void {
- const maxPersonalSpace = 60;
+ const maxPersonalSpace = 60;
for (const blob of this.blobs) {
const neighbors = this.spatialHash.queryNeighbors(blob, maxPersonalSpace);
@@ -231,45 +183,39 @@ export class BlobPhysics {
const dx = other.currentX - blob.currentX;
const dy = other.currentY - blob.currentY;
const distance = Math.sqrt(dx * dx + dy * dy);
- if (distance <= 0) continue;
- const requiredDistance = Math.max(
- blob.personalSpace || 50,
- other.personalSpace || 50
- );
- const sigma = requiredDistance * 0.5;
- const w = Math.exp(-(distance * distance) / (2 * sigma * sigma));
- const repulsionForce =
- w * 0.055 * (this.config.antiClusteringStrength / 0.15);
-
- const normalizedDx = dx / distance;
- const normalizedDy = dy / distance;
- const forceMultiplier = blob.repulsionStrength || 0.03;
-
- blob.velocityX -= normalizedDx * repulsionForce * forceMultiplier;
- blob.velocityY -= normalizedDy * repulsionForce * forceMultiplier;
-
- // Force is now Gaussian (continuous, applies at any range
- // inside the spatial-hash query). lastRepulsionTime stays
- // gated on the close-contact threshold because downstream
- // addEscapeVelocity uses it as a "blobs were just pushing
- // each other apart" event detector — not as a generic
- // "any neighbor contributed" flag. Decoupling is intentional.
- if (distance < requiredDistance) {
+ const requiredDistance = Math.max(blob.personalSpace || 50, other.personalSpace || 50);
+
+ if (distance < requiredDistance && distance > 0) {
+ const overlap = requiredDistance - distance;
+ const repulsionForce = (overlap / requiredDistance) * 0.055 * this.config.antiClusteringStrength / 0.15;
+
+ const normalizedDx = dx / distance;
+ const normalizedDy = dy / distance;
+
+ const forceMultiplier = blob.repulsionStrength || 0.03;
+ const proximityMultiplier = distance < requiredDistance * 0.7 ? 3.5 : 1.0;
+
+
+ blob.velocityX -= normalizedDx * repulsionForce * forceMultiplier * proximityMultiplier * 0.5;
+ blob.velocityY -= normalizedDy * repulsionForce * forceMultiplier * proximityMultiplier * 0.5;
+
blob.lastRepulsionTime = Date.now();
}
}
}
}
-
+
updateMousePosition(x: number, y: number): void {
- this.mouseVelX = x - this.lastMouseX;
- this.mouseVelY = y - this.lastMouseY;
- this.lastMouseX = this.mouseX;
- this.lastMouseY = this.mouseY;
+ const previousMouseX = this.mouseX;
+ const previousMouseY = this.mouseY;
+ this.mouseVelX = x - previousMouseX;
+ this.mouseVelY = y - previousMouseY;
+ this.lastMouseX = previousMouseX;
+ this.lastMouseY = previousMouseY;
this.mouseX = x;
this.mouseY = y;
}
@@ -460,9 +406,6 @@ export class BlobPhysics {
}
}
- // Fallback when useSpatialHash is false. Same Gaussian-falloff
- // repulsion as applyAntiClusteringWithSpatialHash, applied
- // pairwise in O(N²).
private applyEnhancedAntiClustering(): void {
for (let i = 0; i < this.blobs.length; i++) {
const blob1 = this.blobs[i];
@@ -473,29 +416,28 @@ export class BlobPhysics {
const dx = blob2.currentX - blob1.currentX;
const dy = blob2.currentY - blob1.currentY;
const distance = Math.sqrt(dx * dx + dy * dy);
- if (distance <= 0) continue;
- const requiredDistance = Math.max(
- blob1.personalSpace || 50,
- blob2.personalSpace || 50
- );
- const sigma = requiredDistance * 0.5;
- const w = Math.exp(-(distance * distance) / (2 * sigma * sigma));
- const repulsionForce =
- w * 0.055 * (this.config.antiClusteringStrength / 0.15);
+ const requiredDistance = Math.max(blob1.personalSpace || 50, blob2.personalSpace || 50);
- const normalizedDx = dx / distance;
- const normalizedDy = dy / distance;
- const force1Multiplier = blob1.repulsionStrength || 0.03;
- const force2Multiplier = blob2.repulsionStrength || 0.03;
+ if (distance < requiredDistance && distance > 0) {
+ const overlap = requiredDistance - distance;
+ const repulsionForce = (overlap / requiredDistance) * 0.055 * this.config.antiClusteringStrength / 0.15;
- blob1.velocityX -= normalizedDx * repulsionForce * force1Multiplier;
- blob1.velocityY -= normalizedDy * repulsionForce * force1Multiplier;
+ const normalizedDx = dx / distance;
+ const normalizedDy = dy / distance;
- blob2.velocityX += normalizedDx * repulsionForce * force2Multiplier;
- blob2.velocityY += normalizedDy * repulsionForce * force2Multiplier;
+ const force1Multiplier = blob1.repulsionStrength || 0.03;
+ const force2Multiplier = blob2.repulsionStrength || 0.03;
+
+
+ const proximityMultiplier = distance < requiredDistance * 0.7 ? 3.5 : 1.0;
+
+ blob1.velocityX -= normalizedDx * repulsionForce * force1Multiplier * proximityMultiplier;
+ blob1.velocityY -= normalizedDy * repulsionForce * force1Multiplier * proximityMultiplier;
+
+ blob2.velocityX += normalizedDx * repulsionForce * force2Multiplier * proximityMultiplier;
+ blob2.velocityY += normalizedDy * repulsionForce * force2Multiplier * proximityMultiplier;
- if (distance < requiredDistance) {
blob1.lastRepulsionTime = Date.now();
blob2.lastRepulsionTime = Date.now();
}
@@ -542,14 +484,8 @@ export class BlobPhysics {
}
private applyAccelerometerForces(blob: ConvexBlob): void {
- const accelerometerStrength = 0.0008;
- const maxForce = 0.003;
-
- const gravityX = Math.max(-maxForce, Math.min(maxForce, this.gravity.x * accelerometerStrength));
- const gravityY = Math.max(-maxForce, Math.min(maxForce, this.gravity.y * accelerometerStrength));
-
- blob.velocityX += gravityX;
- blob.velocityY += gravityY;
+ blob.velocityX += this.gravityField.x;
+ blob.velocityY += this.gravityField.y;
if (blob.controlPoints && (Math.abs(this.gravity.x) > 0.3 || Math.abs(this.gravity.y) > 0.3)) {
@@ -727,33 +663,36 @@ export class BlobPhysics {
});
}
- // Laplacian skin-tension pass on the perimeter ring.
- // r_i ← r_i + k · (0.5·(r_{i-1} + r_{i+1}) - r_i) is the discrete
- // surface-tension force on a closed control-point ring (Young-Laplace
- // pressure). Two-pass: read all targets first, then write — otherwise
- // we'd be smoothing against half-already-smoothed neighbors.
- // Plus a viscous radial-velocity bleed (Kelvin-Voigt dashpot half) so
- // energy dissipates with each correction rather than ringing as it
- // did with the previous spring-only model.
private smoothControlPoints(blob: ConvexBlob): void {
- const cp = blob.controlPoints;
- if (!cp || cp.length < 3) return;
- const n = cp.length;
- if (!this.skinTensionScratch || this.skinTensionScratch.length < n) {
- this.skinTensionScratch = new Float32Array(n);
- }
- const target = this.skinTensionScratch;
- const k = 0.15;
+ if (!blob.controlPoints || blob.controlPoints.length < 3) return;
- for (let i = 0; i < n; i++) {
- const prev = cp[(i - 1 + n) % n].radius;
- const next = cp[(i + 1) % n].radius;
- target[i] = 0.5 * (prev + next);
+ const controlPoints = blob.controlPoints;
+ const originalRadii = this.controlRadiusScratch;
+ const pointCount = controlPoints.length;
+
+ for (let i = 0; i < pointCount; i++) {
+ originalRadii[i] = controlPoints[i].radius;
}
- for (let i = 0; i < n; i++) {
- cp[i].radius += (target[i] - cp[i].radius) * k;
- const v = blob.controlVelocities?.[i];
- if (v) v.radialVelocity *= 1 - 0.5 * k;
+
+ for (let i = 0; i < pointCount; i++) {
+ const current = controlPoints[i];
+ const prevRadius = originalRadii[(i - 1 + pointCount) % pointCount];
+ const currentRadius = originalRadii[i];
+ const nextRadius = originalRadii[(i + 1) % pointCount];
+
+
+ const avgRadius = (prevRadius + currentRadius + nextRadius) / 3;
+ const smoothingFactor = 0.05;
+ current.radius = currentRadius * (1 - smoothingFactor) + avgRadius * smoothingFactor;
+
+
+ const minRadiusDiff = blob.size * 0.1;
+ const neighborRadius = (prevRadius + nextRadius) * 0.5;
+ const radiusDiff = current.radius - neighborRadius;
+ const excessRadiusDiff = Math.abs(radiusDiff) - minRadiusDiff;
+ if (excessRadiusDiff > 0) {
+ current.radius -= radiusDiff > 0 ? excessRadiusDiff * 0.5 : -excessRadiusDiff * 0.5;
+ }
}
}
@@ -767,55 +706,36 @@ export class BlobPhysics {
}
}
- // Soft-wall force: continuous penetration-based restoring force, no
- // specular reflection or position snap. Edges deform along the wall
- // (the blob "flattens") rather than bouncing — the gel cue.
private handleWallBouncing(blob: ConvexBlob): void {
const margin = blob.size * 0.8;
- const yMargin = margin * 1.5;
- const k = 0.08;
+ const damping = this.config.bounceDamping;
const currentTime = Date.now();
- const minX = this.PHYSICS_MIN + margin;
- const maxX = this.PHYSICS_MAX - margin;
- const minY = this.PHYSICS_MIN + yMargin;
- const maxY = this.PHYSICS_MAX - yMargin;
-
- const px =
- Math.max(0, minX - blob.currentX) - Math.max(0, blob.currentX - maxX);
- const py =
- Math.max(0, minY - blob.currentY) - Math.max(0, blob.currentY - maxY);
-
- if (px !== 0) blob.velocityX += k * px;
- if (py !== 0) blob.velocityY += k * py;
-
- // Hard outer clamp — far outside the soft band, snap back so the
- // blob can never escape the canvas under extreme dt or large
- // external forces. Records a bounce so existing time-since-bounce
- // logic continues to work.
- const hardMargin = blob.size * 0.2;
- const hardMinX = this.PHYSICS_MIN + hardMargin;
- const hardMaxX = this.PHYSICS_MAX - hardMargin;
- const hardMinY = this.PHYSICS_MIN + hardMargin;
- const hardMaxY = this.PHYSICS_MAX - hardMargin;
- const hardDamping = this.config.bounceDamping;
-
- if (blob.currentX < hardMinX) {
- blob.currentX = hardMinX;
- blob.velocityX = Math.abs(blob.velocityX) * hardDamping;
+
+ if (blob.currentX < this.PHYSICS_MIN + margin) {
+ blob.currentX = this.PHYSICS_MIN + margin;
+ blob.velocityX = Math.abs(blob.velocityX) * damping;
this.recordBounce(blob, currentTime);
- } else if (blob.currentX > hardMaxX) {
- blob.currentX = hardMaxX;
- blob.velocityX = -Math.abs(blob.velocityX) * hardDamping;
+ }
+
+
+ if (blob.currentX > this.PHYSICS_MAX - margin) {
+ blob.currentX = this.PHYSICS_MAX - margin;
+ blob.velocityX = -Math.abs(blob.velocityX) * damping;
this.recordBounce(blob, currentTime);
}
- if (blob.currentY < hardMinY) {
- blob.currentY = hardMinY;
- blob.velocityY = Math.abs(blob.velocityY) * hardDamping;
+
+
+ if (blob.currentY < this.PHYSICS_MIN + margin * 1.5) {
+ blob.currentY = this.PHYSICS_MIN + margin * 1.5;
+ blob.velocityY = Math.abs(blob.velocityY) * damping;
this.recordBounce(blob, currentTime);
- } else if (blob.currentY > hardMaxY) {
- blob.currentY = hardMaxY;
- blob.velocityY = -Math.abs(blob.velocityY) * hardDamping;
+ }
+
+
+ if (blob.currentY > this.PHYSICS_MAX - margin * 1.5) {
+ blob.currentY = this.PHYSICS_MAX - margin * 1.5;
+ blob.velocityY = -Math.abs(blob.velocityY) * damping;
this.recordBounce(blob, currentTime);
}
}
diff --git a/src/core/InteractionField.ts b/src/core/InteractionField.ts
new file mode 100644
index 0000000..62ec522
--- /dev/null
+++ b/src/core/InteractionField.ts
@@ -0,0 +1,89 @@
+export interface FieldVector {
+ x: number;
+ y: number;
+}
+
+export interface PointFieldOptions {
+ origin: FieldVector;
+ target: FieldVector;
+ radius: number;
+ strength: number;
+}
+
+const magnitude = (vector: FieldVector): number =>
+ Math.sqrt(vector.x * vector.x + vector.y * vector.y);
+
+export function clampFieldVector(vector: FieldVector, maxMagnitude = 1): FieldVector {
+ const max = Math.max(0, maxMagnitude);
+ const currentMagnitude = magnitude(vector);
+ if (max === 0 || currentMagnitude === 0) return { x: 0, y: 0 };
+ if (currentMagnitude <= max) return vector;
+
+ const scale = max / currentMagnitude;
+ return {
+ x: vector.x * scale,
+ y: vector.y * scale,
+ };
+}
+
+export function combineFieldVectors(
+ fields: FieldVector[],
+ maxMagnitude = 1,
+): FieldVector {
+ const total = fields.reduce(
+ (accumulator, field) => ({
+ x: accumulator.x + field.x,
+ y: accumulator.y + field.y,
+ }),
+ { x: 0, y: 0 },
+ );
+
+ return clampFieldVector(total, maxMagnitude);
+}
+
+export function directionalBiasField(
+ input: FieldVector,
+ strength: number,
+ maxMagnitude = 1,
+): FieldVector {
+ const max = Math.max(0, maxMagnitude);
+ const x = input.x * strength;
+ const y = input.y * strength;
+ const currentMagnitude = Math.sqrt(x * x + y * y);
+
+ if (max === 0 || currentMagnitude === 0) return { x: 0, y: 0 };
+ if (currentMagnitude <= max) return { x, y };
+
+ const scale = max / currentMagnitude;
+ return {
+ x: x * scale,
+ y: y * scale,
+ };
+}
+
+export function smoothDistanceFalloff(distance: number, radius: number): number {
+ const boundedDistance = Math.max(0, distance);
+ if (radius <= 0 || boundedDistance >= radius) return 0;
+
+ const normalized = 1 - boundedDistance / radius;
+ return normalized * normalized;
+}
+
+export function pointAttractorField({
+ origin,
+ target,
+ radius,
+ strength,
+}: PointFieldOptions): FieldVector {
+ const dx = target.x - origin.x;
+ const dy = target.y - origin.y;
+ const distance = Math.sqrt(dx * dx + dy * dy);
+ if (distance === 0) return { x: 0, y: 0 };
+
+ const falloff = smoothDistanceFalloff(distance, radius);
+ const scale = (falloff * strength) / distance;
+ return {
+ x: dx * scale,
+ y: dy * scale,
+ };
+}
diff --git a/src/core/index.ts b/src/core/index.ts
index 6dddcf9..c4264da 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -62,7 +62,7 @@ export type {
BlendMode,
ThemeColor,
ThemePreset,
-} from './schema.js';
+} from './theme-presets.js';
// — Render blob shapes —
export type {
@@ -88,11 +88,15 @@ export type {
// — Theme presets and config —
export {
- DEFAULT_CONFIG,
TRANS_THEME,
PRIDE_THEME,
TINYLAND_THEME,
HIGH_CONTRAST_THEME,
THEME_PRESETS,
+} from './theme-presets.js';
+export { THEME_PRESET_COLORS } from './theme-colors.js';
+
+export {
+ DEFAULT_CONFIG,
mergeConfig,
} from './schema.js';
diff --git a/src/core/schema.ts b/src/core/schema.ts
index 1de1ac2..6873d06 100644
--- a/src/core/schema.ts
+++ b/src/core/schema.ts
@@ -7,6 +7,17 @@
import type { ControlPoint, ControlPointVelocity, DeviceMotionData } from './types.js';
+import type {
+ BlendMode,
+ ThemeColor,
+ ThemePresetName,
+} from './theme-presets.js';
+export type {
+ BlendMode,
+ ThemeColor,
+ ThemePreset,
+ ThemePresetName,
+} from './theme-presets.js';
@@ -166,53 +177,16 @@ export interface FeatureFlags {
-export type ThemePresetName = 'tinyland' | 'trans' | 'pride' | 'high-contrast' | 'custom';
-export type BlendMode = 'multiply' | 'screen' | 'overlay' | 'soft-light' | 'normal';
-export interface ThemeColor {
-
- id: string;
-
- color: string;
-
- attractive: boolean;
-
- scrollAffinity: number;
-
- layer: 'background' | 'mid' | 'foreground';
-}
-
-
-
-
-export interface ThemePreset {
-
- name: ThemePresetName;
-
-
- label: string;
-
-
- colors: ThemeColor[];
-
-
- blendModeLight: BlendMode;
-
-
- blendModeDark: BlendMode;
-
-
- hasVectors: boolean;
-}
@@ -510,89 +484,14 @@ export const DEFAULT_CONFIG: TinyVectorsConfig = {
-export const TRANS_THEME: ThemePreset = {
- name: 'trans',
- label: 'Trans Pride',
- hasVectors: true,
- blendModeLight: 'multiply',
- blendModeDark: 'screen',
- colors: [
- { id: 'trans-blue', color: 'rgba(91, 206, 250, 0.60)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
- { id: 'trans-pink', color: 'rgba(245, 169, 184, 0.65)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
- { id: 'trans-white', color: 'rgba(242, 242, 245, 0.50)', attractive: false, scrollAffinity: 0.5, layer: 'mid' },
- { id: 'trans-sky-blue', color: 'rgba(170, 225, 250, 0.55)', attractive: false, scrollAffinity: 0.6, layer: 'mid' },
- { id: 'trans-powder-blue', color: 'rgba(160, 190, 255, 0.65)', attractive: true, scrollAffinity: 0.7, layer: 'foreground' },
- { id: 'trans-rose-pink', color: 'rgba(250, 200, 210, 0.55)', attractive: false, scrollAffinity: 0.6, layer: 'mid' },
- { id: 'trans-blush-pink', color: 'rgba(255, 160, 220, 0.65)', attractive: true, scrollAffinity: 0.7, layer: 'foreground' },
- { id: 'trans-lavender', color: 'rgba(220, 220, 255, 0.55)', attractive: false, scrollAffinity: 0.5, layer: 'background' },
- ],
-};
-
-
-
-
-export const PRIDE_THEME: ThemePreset = {
- name: 'pride',
- label: 'Pride Rainbow',
- hasVectors: true,
- blendModeLight: 'multiply',
- blendModeDark: 'screen',
- colors: [
- { id: 'pride-red', color: 'rgba(228, 3, 3, 0.55)', attractive: true, scrollAffinity: 0.9, layer: 'foreground' },
- { id: 'pride-orange', color: 'rgba(255, 140, 0, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
- { id: 'pride-yellow', color: 'rgba(255, 237, 0, 0.55)', attractive: false, scrollAffinity: 0.7, layer: 'mid' },
- { id: 'pride-green', color: 'rgba(0, 128, 38, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
- { id: 'pride-blue', color: 'rgba(36, 64, 142, 0.55)', attractive: true, scrollAffinity: 0.9, layer: 'foreground' },
- { id: 'pride-purple', color: 'rgba(115, 41, 130, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
- ],
-};
-
-
-
-
-export const TINYLAND_THEME: ThemePreset = {
- name: 'tinyland',
- label: 'Tinyland',
- hasVectors: true,
- blendModeLight: 'multiply',
- blendModeDark: 'screen',
- colors: [
- { id: 'tinyland-purple', color: 'rgba(139, 92, 246, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
- { id: 'tinyland-blue', color: 'rgba(59, 130, 246, 0.55)', attractive: true, scrollAffinity: 0.7, layer: 'foreground' },
- { id: 'tinyland-pink', color: 'rgba(236, 72, 153, 0.50)', attractive: true, scrollAffinity: 0.8, layer: 'mid' },
- { id: 'tinyland-white', color: 'rgba(242, 242, 245, 0.45)', attractive: false, scrollAffinity: 0.4, layer: 'background' },
- ],
-};
-
-
-
-
-export const HIGH_CONTRAST_THEME: ThemePreset = {
- name: 'high-contrast',
- label: 'High Contrast',
- hasVectors: false,
- blendModeLight: 'normal',
- blendModeDark: 'normal',
- colors: [],
-};
-
-
-
-
-export const THEME_PRESETS: Record = {
- tinyland: TINYLAND_THEME,
- trans: TRANS_THEME,
- pride: PRIDE_THEME,
- 'high-contrast': HIGH_CONTRAST_THEME,
- custom: {
- name: 'custom',
- label: 'Custom',
- hasVectors: true,
- blendModeLight: 'multiply',
- blendModeDark: 'screen',
- colors: [],
- },
-};
+export {
+ HIGH_CONTRAST_THEME,
+ PRIDE_THEME,
+ THEME_PRESETS,
+ TINYLAND_THEME,
+ TRANS_THEME,
+} from './theme-presets.js';
+export { THEME_PRESET_COLORS } from './theme-colors.js';
diff --git a/src/core/theme-colors.ts b/src/core/theme-colors.ts
new file mode 100644
index 0000000..46029c7
--- /dev/null
+++ b/src/core/theme-colors.ts
@@ -0,0 +1,30 @@
+import type { ThemePresetName } from './theme-presets.js';
+
+export const THEME_PRESET_COLORS: Record = {
+ tinyland: [
+ 'rgba(139,92,246,.55)',
+ 'rgba(59,130,246,.55)',
+ 'rgba(236,72,153,.50)',
+ 'rgba(242,242,245,.45)',
+ ],
+ trans: [
+ 'rgba(91,206,250,.60)',
+ 'rgba(245,169,184,.65)',
+ 'rgba(242,242,245,.50)',
+ 'rgba(170,225,250,.55)',
+ 'rgba(160,190,255,.65)',
+ 'rgba(250,200,210,.55)',
+ 'rgba(255,160,220,.65)',
+ 'rgba(220,220,255,.55)',
+ ],
+ pride: [
+ 'rgba(228,3,3,.55)',
+ 'rgba(255,140,0,.55)',
+ 'rgba(255,237,0,.55)',
+ 'rgba(0,128,38,.55)',
+ 'rgba(36,64,142,.55)',
+ 'rgba(115,41,130,.55)',
+ ],
+ 'high-contrast': [],
+ custom: [],
+};
diff --git a/src/core/theme-presets.ts b/src/core/theme-presets.ts
new file mode 100644
index 0000000..02be596
--- /dev/null
+++ b/src/core/theme-presets.ts
@@ -0,0 +1,92 @@
+export type ThemePresetName = 'tinyland' | 'trans' | 'pride' | 'high-contrast' | 'custom';
+
+export type BlendMode = 'multiply' | 'screen' | 'overlay' | 'soft-light' | 'normal';
+
+export interface ThemeColor {
+ id: string;
+ color: string;
+ attractive: boolean;
+ scrollAffinity: number;
+ layer: 'background' | 'mid' | 'foreground';
+}
+
+export interface ThemePreset {
+ name: ThemePresetName;
+ label: string;
+ colors: ThemeColor[];
+ blendModeLight: BlendMode;
+ blendModeDark: BlendMode;
+ hasVectors: boolean;
+}
+
+export const TRANS_THEME: ThemePreset = {
+ name: 'trans',
+ label: 'Trans Pride',
+ hasVectors: true,
+ blendModeLight: 'multiply',
+ blendModeDark: 'screen',
+ colors: [
+ { id: 'trans-blue', color: 'rgba(91, 206, 250, 0.60)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
+ { id: 'trans-pink', color: 'rgba(245, 169, 184, 0.65)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
+ { id: 'trans-white', color: 'rgba(242, 242, 245, 0.50)', attractive: false, scrollAffinity: 0.5, layer: 'mid' },
+ { id: 'trans-sky-blue', color: 'rgba(170, 225, 250, 0.55)', attractive: false, scrollAffinity: 0.6, layer: 'mid' },
+ { id: 'trans-powder-blue', color: 'rgba(160, 190, 255, 0.65)', attractive: true, scrollAffinity: 0.7, layer: 'foreground' },
+ { id: 'trans-rose-pink', color: 'rgba(250, 200, 210, 0.55)', attractive: false, scrollAffinity: 0.6, layer: 'mid' },
+ { id: 'trans-blush-pink', color: 'rgba(255, 160, 220, 0.65)', attractive: true, scrollAffinity: 0.7, layer: 'foreground' },
+ { id: 'trans-lavender', color: 'rgba(220, 220, 255, 0.55)', attractive: false, scrollAffinity: 0.5, layer: 'background' },
+ ],
+};
+
+export const PRIDE_THEME: ThemePreset = {
+ name: 'pride',
+ label: 'Pride Rainbow',
+ hasVectors: true,
+ blendModeLight: 'multiply',
+ blendModeDark: 'screen',
+ colors: [
+ { id: 'pride-red', color: 'rgba(228, 3, 3, 0.55)', attractive: true, scrollAffinity: 0.9, layer: 'foreground' },
+ { id: 'pride-orange', color: 'rgba(255, 140, 0, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
+ { id: 'pride-yellow', color: 'rgba(255, 237, 0, 0.55)', attractive: false, scrollAffinity: 0.7, layer: 'mid' },
+ { id: 'pride-green', color: 'rgba(0, 128, 38, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
+ { id: 'pride-blue', color: 'rgba(36, 64, 142, 0.55)', attractive: true, scrollAffinity: 0.9, layer: 'foreground' },
+ { id: 'pride-purple', color: 'rgba(115, 41, 130, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
+ ],
+};
+
+export const TINYLAND_THEME: ThemePreset = {
+ name: 'tinyland',
+ label: 'Tinyland',
+ hasVectors: true,
+ blendModeLight: 'multiply',
+ blendModeDark: 'screen',
+ colors: [
+ { id: 'tinyland-purple', color: 'rgba(139, 92, 246, 0.55)', attractive: true, scrollAffinity: 0.8, layer: 'foreground' },
+ { id: 'tinyland-blue', color: 'rgba(59, 130, 246, 0.55)', attractive: true, scrollAffinity: 0.7, layer: 'foreground' },
+ { id: 'tinyland-pink', color: 'rgba(236, 72, 153, 0.50)', attractive: true, scrollAffinity: 0.8, layer: 'mid' },
+ { id: 'tinyland-white', color: 'rgba(242, 242, 245, 0.45)', attractive: false, scrollAffinity: 0.4, layer: 'background' },
+ ],
+};
+
+export const HIGH_CONTRAST_THEME: ThemePreset = {
+ name: 'high-contrast',
+ label: 'High Contrast',
+ hasVectors: false,
+ blendModeLight: 'normal',
+ blendModeDark: 'normal',
+ colors: [],
+};
+
+export const THEME_PRESETS: Record = {
+ tinyland: TINYLAND_THEME,
+ trans: TRANS_THEME,
+ pride: PRIDE_THEME,
+ 'high-contrast': HIGH_CONTRAST_THEME,
+ custom: {
+ name: 'custom',
+ label: 'Custom',
+ hasVectors: true,
+ blendModeLight: 'multiply',
+ blendModeDark: 'screen',
+ colors: [],
+ },
+};
diff --git a/src/index.ts b/src/index.ts
index 0578c05..9bbf0fb 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,30 +1,109 @@
+// Curated public package root. Keep this explicit so the npm surface stays
+// reviewable and tree-shake-friendly.
-
-
-
-
-
-export * from './core/index.js';
-
-
-export * from './motion/index.js';
-
-
-export * from './themes/index.js';
-
-
-export * from './svelte/index.js';
-
+export {
+ BlobPhysics,
+ generateSmoothBlobPath,
+ generateSmoothBlobPathSync,
+ preInitPathGenerator,
+ SpringSystem,
+ DEFAULT_SPRING_CONFIG,
+ computePolygonArea,
+ computeCircularity,
+ enforceAreaConservation,
+ createControlPointVelocities,
+ GaussianKernel,
+ SpatialHash,
+ browser,
+ isBrowser,
+ TRANS_THEME,
+ PRIDE_THEME,
+ TINYLAND_THEME,
+ HIGH_CONTRAST_THEME,
+ THEME_PRESETS,
+ THEME_PRESET_COLORS,
+ DEFAULT_CONFIG,
+ mergeConfig,
+} from './core/index.js';
export type {
+ BlobPhysicsConfig,
+ SpringConfig,
+ GelControlPoint,
+ ControlPoint,
+ ControlPointVelocity,
+ ConvexBlob,
+ ColorDefinition,
+ DeviceMotionData,
+ GravityVector,
+ TiltVector,
TinyVectorsConfig,
CoreConfig,
PhysicsConfig,
RenderingConfig,
ThemeConfig,
FeatureFlags,
- RenderBlob,
+ TinyVectorsConfigOverride,
+ DeepPartial,
+ ThemePresetName,
+ BlendMode,
ThemeColor,
ThemePreset,
- ThemePresetName,
-} from './core/schema.js';
+ BlobCore,
+ RenderBlob,
+ PhysicsBlob,
+ ScrollData,
+ PointerData,
+ TinyVectorsEventType,
+ TinyVectorsEventHandler,
+ TinyVectorsEvent,
+ FrameEventData,
+ ThemeChangeEventData,
+} from './core/index.js';
+
+export {
+ DeviceMotion,
+ mapClientPointToPhysics,
+ createPointerPhysicsController,
+ detectPointerPhysicsCapability,
+ getLatestPointerEvent,
+ ScrollHandler,
+} from './motion/index.js';
+
+export type {
+ DeviceMotionCallback,
+ DeviceMotionOptions,
+ DeviceMotionPermissionState,
+ MotionVector,
+ PhysicsPoint,
+ PhysicsRange,
+ PointerBounds,
+ PointerCapabilityEnvironment,
+ PointerCancelEventName,
+ PointerExitEventName,
+ PointerExitLikeEvent,
+ PointerLifecycleEventName,
+ PointerLikeEvent,
+ PointerMoveEventName,
+ PointerPhysicsController,
+ PointerPhysicsControllerOptions,
+ PointerPhysicsEventTarget,
+ ScrollHandlerConfig,
+ PullForce,
+} from './motion/index.js';
+
+export {
+ getThemePreset,
+ generateThemeCSS,
+ isDarkMode,
+ watchDarkMode,
+} from './themes/index.js';
+
+export {
+ TinyVectors,
+ BlobSVG,
+} from './svelte/index.js';
+
+export type {
+ TinyVectorsDeviceMotionStatus,
+} from './svelte/index.js';
diff --git a/src/motion/DeviceMotion.ts b/src/motion/DeviceMotion.ts
index c627f5d..70ef5ef 100644
--- a/src/motion/DeviceMotion.ts
+++ b/src/motion/DeviceMotion.ts
@@ -1,28 +1,55 @@
import { OneEuro } from './OneEuro.js';
-export type DeviceMotionCallback = (data: {
+export interface MotionVector {
x: number;
y: number;
z: number;
-}) => void;
+}
+
+export type DeviceMotionCallback = (data: MotionVector) => void;
+
+export type DeviceMotionPermissionState =
+ | 'unknown'
+ | 'unsupported'
+ | 'insecure'
+ | 'prompt'
+ | 'granted'
+ | 'denied';
export interface DeviceMotionOptions {
/** One-Euro min cutoff (Hz). Lower = smoother at rest. Default 0.5. */
oneEuroMinCutoff?: number;
- /** One-Euro speed-responsiveness. Default 0.01 (low for ambient). */
+ /** One-Euro speed responsiveness. Default 0.01 for ambient backgrounds. */
oneEuroBeta?: number;
/** One-Euro speed-estimate cutoff (Hz). Default 1.0. */
oneEuroDCutoff?: number;
- /** Slow continuous baseline EMA. Default 0.0008 (~30 s τ). */
+ /** Slow continuous baseline EMA. Default 0.0008, roughly 30 s tau. */
baselineAlpha?: number;
- /** Discard events for the first N ms after first sample. Default 250. */
+ /** Discard events for the first N ms after listener startup. Default 250. */
warmupMs?: number;
- /** Suppress output when |beta| exceeds this. Default 120°. */
+ /** Suppress output when |beta| exceeds this. Default 120 degrees. */
faceDownThreshold?: number;
- /** Reset filter/baseline if event gap exceeds this. Default 2000 ms. */
+ /** Reset filters if event gap exceeds this. Default 2000 ms. */
staleEventMs?: number;
- /** Degrees mapped to ±1. Default 45 (matches casual tilt range). */
+ /** Emit neutral output if events stop for this long. Default 2000 ms. */
+ idleResetMs?: number;
+ /** Degrees mapped to +/-1. Default 45, matching casual tilt range. */
range?: number;
+ /** Manual calibration sample count used by calibrate(). Default 8. */
+ calibrationSamples?: number;
+ /** Values smaller than this are treated as rest-state noise. Default 0.015. */
+ deadZone?: number;
+}
+
+interface MotionWindow {
+ DeviceOrientationEvent?: {
+ requestPermission?: () => Promise<'granted' | 'denied'>;
+ };
+}
+
+interface LegacyMediaQueryList {
+ addListener?: (listener: () => void) => void;
+ removeListener?: (listener: () => void) => void;
}
const DEFAULTS = {
@@ -33,17 +60,15 @@ const DEFAULTS = {
warmupMs: 250,
faceDownThreshold: 120,
staleEventMs: 2000,
+ idleResetMs: 2000,
range: 45,
+ calibrationSamples: 8,
+ deadZone: 0.015,
} satisfies Required;
-// Convert raw (beta, gamma) → screen-aligned (sx, sy) given
-// screen.orientation.angle. sx is "left-right tilt felt by the user",
-// sy is "front-back tilt felt by the user". Pure for unit tests.
-export function remapToScreen(
- beta: number,
- gamma: number,
- angle: number
-): [number, number] {
+// Convert raw (beta, gamma) to screen-aligned tilt. sx is left/right
+// tilt as felt by the user; sy is front/back tilt as felt by the user.
+export function remapToScreen(beta: number, gamma: number, angle: number): [number, number] {
switch (angle) {
case 90:
return [beta, -gamma];
@@ -57,205 +82,392 @@ export function remapToScreen(
}
}
-function clamp(v: number, lo: number, hi: number): number {
- return v < lo ? lo : v > hi ? hi : v;
+function clamp(value: number, min = -1, max = 1): number {
+ return Math.max(min, Math.min(max, value));
+}
+
+function applyDeadZone(value: number, deadZone: number): number {
+ return Math.abs(value) < deadZone ? 0 : value;
}
-type OrientationPermission = () => Promise;
-function getPermissionApi(): OrientationPermission | null {
- if (typeof DeviceOrientationEvent === 'undefined') return null;
- const fn = (
- DeviceOrientationEvent as unknown as { requestPermission?: OrientationPermission }
- ).requestPermission;
- return typeof fn === 'function' ? fn : null;
+function getPermissionApi(): (() => Promise<'granted' | 'denied'>) | null {
+ if (typeof window === 'undefined') return null;
+ const constructor = (window as unknown as MotionWindow).DeviceOrientationEvent;
+ const requestPermission = constructor?.requestPermission;
+ return typeof requestPermission === 'function' ? requestPermission.bind(constructor) : null;
+}
+
+export function getDeviceMotionCapabilityState(): DeviceMotionPermissionState {
+ if (typeof window === 'undefined') return 'unsupported';
+ if (!window.isSecureContext) return 'insecure';
+ return 'DeviceOrientationEvent' in window ? 'unknown' : 'unsupported';
+}
+
+export function isDeviceMotionPermissionRequired(): boolean {
+ return getPermissionApi() !== null;
+}
+
+function getScreenOrientationAngle(): number {
+ if (typeof screen === 'undefined') return 0;
+ return screen.orientation?.angle ?? 0;
+}
+
+function addMediaQueryChangeListener(mql: MediaQueryList, listener: () => void): void {
+ if (typeof mql.addEventListener === 'function') {
+ mql.addEventListener('change', listener);
+ return;
+ }
+
+ (mql as LegacyMediaQueryList).addListener?.(listener);
+}
+
+function removeMediaQueryChangeListener(mql: MediaQueryList, listener: () => void): void {
+ if (typeof mql.removeEventListener === 'function') {
+ mql.removeEventListener('change', listener);
+ return;
+ }
+
+ (mql as LegacyMediaQueryList).removeListener?.(listener);
}
-// Replaces the previous raw-acceleration DeviceMotion implementation.
-// Listens to DeviceOrientationEvent (OS-fused, low-noise) instead of
-// DeviceMotionEvent.accelerationIncludingGravity. Filters with One-Euro
-// for an ambient-feel adaptive low-pass; subtracts a slow baseline so
-// resting pose (cable bias, pocket lean) is absorbed without killing
-// gravity feel. Honors prefers-reduced-motion as a hard disable.
export class DeviceMotion {
- private callback: DeviceMotionCallback;
- private opts: Required;
+ private readonly callback: DeviceMotionCallback;
+ private readonly opts: Required;
+ private readonly filterX: OneEuro;
+ private readonly filterY: OneEuro;
+ private permissionState: DeviceMotionPermissionState = 'unknown';
private isListening = false;
private disposed = false;
- private filterX: OneEuro;
- private filterY: OneEuro;
+ private listenerStartedAt = 0;
+ private lastEventAt = 0;
private baseX = 0;
private baseY = 0;
- private firstEventAt = 0;
- private lastEventAt = 0;
- private boundOrientation: ((e: DeviceOrientationEvent) => void) | null = null;
+ private lastScreen: { x: number; y: number } | null = null;
+ private calibrationRemaining = 0;
+ private calibrationTargetSamples = 0;
+ private calibrationTotalX = 0;
+ private calibrationTotalY = 0;
+ private boundOrientation: ((event: DeviceOrientationEvent) => void) | null = null;
private boundVisibility: (() => void) | null = null;
private reducedMotionMql: MediaQueryList | null = null;
private reducedMotionListener: (() => void) | null = null;
+ private blockedByReducedMotion = false;
+ private idleResetTimer: ReturnType | null = null;
constructor(callback: DeviceMotionCallback, options: DeviceMotionOptions = {}) {
this.callback = callback;
this.opts = { ...DEFAULTS, ...options };
- const eu = {
+ const params = {
minCutoff: this.opts.oneEuroMinCutoff,
beta: this.opts.oneEuroBeta,
dCutoff: this.opts.oneEuroDCutoff,
};
- this.filterX = new OneEuro(eu);
- this.filterY = new OneEuro(eu);
+ this.filterX = new OneEuro(params);
+ this.filterY = new OneEuro(params);
}
- async initialize(): Promise {
- if (this.disposed) return;
- if (typeof window === 'undefined') return;
- if (!window.isSecureContext) {
- console.warn('DeviceMotion APIs require a secure context (HTTPS)');
- return;
+ async initialize(): Promise {
+ if (!this.detectSupport()) return false;
+ this.observeReducedMotion();
+
+ if (this.prefersReducedMotion()) {
+ this.blockedByReducedMotion = true;
+ this.permissionState = 'denied';
+ this.stopListening();
+ return false;
+ }
+
+ if (getPermissionApi()) {
+ this.permissionState = 'prompt';
+ return false;
}
- if (!('DeviceOrientationEvent' in window)) {
- console.log('DeviceOrientationEvent not supported');
+
+ this.permissionState = 'granted';
+ this.startListening();
+ return true;
+ }
+
+ async requestPermission(): Promise {
+ if (!this.detectSupport()) return false;
+ this.observeReducedMotion();
+
+ if (this.prefersReducedMotion()) {
+ this.blockedByReducedMotion = true;
+ this.permissionState = 'denied';
+ this.stopListening();
+ return false;
+ }
+
+ const requestPermission = getPermissionApi();
+ if (requestPermission) {
+ this.permissionState = 'prompt';
+ try {
+ this.permissionState = await requestPermission();
+ } catch {
+ this.permissionState = 'denied';
+ }
+ } else {
+ this.permissionState = 'granted';
+ }
+
+ if (this.disposed) {
+ this.stopListening();
+ return false;
+ }
+
+ if (this.prefersReducedMotion()) {
+ this.blockedByReducedMotion = true;
+ this.stopListening();
+ this.resetFilterState();
+ this.emitNeutral();
+ return false;
+ }
+
+ if (this.permissionState !== 'granted') {
+ this.stopListening();
+ return false;
+ }
+
+ this.startListening();
+ return true;
+ }
+
+ /**
+ * Re-zero tilt from the next N orientation samples. Calibration samples are
+ * consumed for the baseline only; normal output resumes on the following event.
+ */
+ calibrate(samples = this.opts.calibrationSamples): void {
+ const sampleCount = Math.max(0, Math.floor(samples));
+ this.resetFilterState({ resetWarmup: false });
+
+ if (sampleCount === 0) {
+ if (this.lastScreen) {
+ this.baseX = this.lastScreen.x;
+ this.baseY = this.lastScreen.y;
+ }
+ this.calibrationRemaining = 0;
return;
}
- // prefers-reduced-motion is a hard disable. Subscribe to changes so
- // we honor a runtime toggle (Apple users can flip this from Control
- // Center) — but never auto-listen until explicitly initialized.
- this.reducedMotionMql =
- window.matchMedia?.('(prefers-reduced-motion: reduce)') ?? null;
+ this.calibrationRemaining = sampleCount;
+ this.calibrationTargetSamples = sampleCount;
+ this.calibrationTotalX = 0;
+ this.calibrationTotalY = 0;
+ }
+
+ getPermissionState(): DeviceMotionPermissionState {
+ return this.permissionState;
+ }
+
+ isActive(): boolean {
+ return this.isListening;
+ }
+
+ cleanup(): void {
+ this.disposed = true;
+ this.stopListening();
+
+ if (this.reducedMotionMql && this.reducedMotionListener) {
+ removeMediaQueryChangeListener(this.reducedMotionMql, this.reducedMotionListener);
+ }
+ this.reducedMotionMql = null;
+ this.reducedMotionListener = null;
+ this.blockedByReducedMotion = false;
+ this.resetFilterState();
+ }
+
+ private detectSupport(): boolean {
+ if (this.disposed) return false;
+
+ const capabilityState = getDeviceMotionCapabilityState();
+ if (capabilityState !== 'unknown') {
+ this.permissionState = capabilityState;
+ return false;
+ }
+
+ return true;
+ }
+
+ private observeReducedMotion(): void {
+ if (this.reducedMotionMql || typeof window === 'undefined') return;
+
+ this.reducedMotionMql = window.matchMedia?.('(prefers-reduced-motion: reduce)') ?? null;
this.reducedMotionListener = () => {
if (this.disposed || !this.reducedMotionMql) return;
- if (this.reducedMotionMql.matches && this.isListening) {
+
+ if (this.reducedMotionMql.matches) {
+ this.blockedByReducedMotion = true;
this.stopListening();
- } else if (!this.reducedMotionMql.matches && !this.isListening) {
- // Re-engage if user disabled reduced-motion mid-session.
- // requestPermission() handles the no-API case internally.
- // Guard against post-cleanup resolution: iOS may have a
- // permission prompt open when cleanup() fires.
- void this.requestPermission().then((ok) => {
- if (ok && !this.disposed) this.startListening();
- });
+ this.resetFilterState();
+ this.emitNeutral();
+ return;
}
- };
- this.reducedMotionMql?.addEventListener('change', this.reducedMotionListener);
- if (this.reducedMotionMql?.matches) return;
+ if (this.blockedByReducedMotion) {
+ this.blockedByReducedMotion = false;
+ if (this.permissionState === 'granted' || !getPermissionApi()) {
+ this.permissionState = 'granted';
+ this.startListening();
+ return;
+ }
+ this.permissionState = 'prompt';
+ return;
+ }
- const ok = await this.requestPermission();
- if (ok && !this.disposed) this.startListening();
+ if (this.permissionState === 'granted') {
+ this.startListening();
+ }
+ };
+ if (this.reducedMotionMql) {
+ addMediaQueryChangeListener(this.reducedMotionMql, this.reducedMotionListener);
+ }
}
- async requestPermission(): Promise {
- const api = getPermissionApi();
- if (!api) return true;
- try {
- const r = await api();
- return r === 'granted';
- } catch (err) {
- console.error('Error requesting device orientation permission:', err);
- return false;
- }
+ private prefersReducedMotion(): boolean {
+ return this.reducedMotionMql?.matches ?? false;
}
private startListening(): void {
- if (this.isListening) return;
- this.boundOrientation = (e: DeviceOrientationEvent) => this.handle(e);
- window.addEventListener('deviceorientation', this.boundOrientation, {
- passive: true,
- } as AddEventListenerOptions);
+ if (this.disposed || this.isListening || typeof window === 'undefined') return;
+
+ this.boundOrientation = (event: DeviceOrientationEvent) => this.handleOrientation(event);
+ window.addEventListener('deviceorientation', this.boundOrientation, { passive: true });
this.boundVisibility = () => {
- if (document.hidden) this.resetFilterState();
+ if (document.hidden) {
+ this.resetFilterState();
+ this.emitNeutral();
+ }
};
document.addEventListener('visibilitychange', this.boundVisibility);
+ this.listenerStartedAt = this.now();
+ this.lastEventAt = 0;
this.isListening = true;
+ this.armIdleReset();
}
private stopListening(): void {
if (!this.isListening) return;
+ this.clearIdleReset();
+
if (this.boundOrientation) {
window.removeEventListener('deviceorientation', this.boundOrientation);
this.boundOrientation = null;
}
+
if (this.boundVisibility) {
document.removeEventListener('visibilitychange', this.boundVisibility);
this.boundVisibility = null;
}
- this.isListening = false;
- }
- private resetFilterState(): void {
- this.filterX.reset();
- this.filterY.reset();
- this.firstEventAt = 0;
- this.lastEventAt = 0;
+ this.isListening = false;
}
- private handle(event: DeviceOrientationEvent): void {
- if (event.beta == null || event.gamma == null) return;
-
- const now =
- typeof performance !== 'undefined' ? performance.now() : Date.now();
+ private handleOrientation(event: DeviceOrientationEvent): void {
+ if (this.disposed || event.beta == null || event.gamma == null) return;
- if (this.firstEventAt === 0) this.firstEventAt = now;
- if (now - this.firstEventAt < this.opts.warmupMs) return;
+ const now = this.now();
+ if (now - this.listenerStartedAt < this.opts.warmupMs) return;
- if (
- this.lastEventAt > 0 &&
- now - this.lastEventAt > this.opts.staleEventMs
- ) {
+ if (this.lastEventAt > 0 && now - this.lastEventAt > this.opts.staleEventMs) {
this.resetFilterState();
- this.firstEventAt = now;
+ this.listenerStartedAt = now;
this.lastEventAt = now;
+ this.emitNeutral();
+ this.armIdleReset();
return;
}
this.lastEventAt = now;
- // Face-down or upside-down: emit zero rather than wild values.
if (Math.abs(event.beta) > this.opts.faceDownThreshold) {
- this.callback({ x: 0, y: 0, z: 0 });
+ this.emitNeutral();
+ this.armIdleReset();
return;
}
- const angle =
- (typeof screen !== 'undefined' && screen.orientation?.angle) || 0;
- const [sx, sy] = remapToScreen(event.beta, event.gamma, angle);
+ const [screenX, screenY] = remapToScreen(
+ event.beta,
+ event.gamma,
+ getScreenOrientationAngle(),
+ );
+ this.lastScreen = { x: screenX, y: screenY };
- // Slow continuous baseline absorbs cable bias / pocket lean over
- // ~30 s without killing gravity feel.
- const a = this.opts.baselineAlpha;
- this.baseX += a * (sx - this.baseX);
- this.baseY += a * (sy - this.baseY);
+ if (!this.consumeCalibrationSample(screenX, screenY)) {
+ this.armIdleReset();
+ return;
+ }
- const range = this.opts.range;
- const xRaw = (sx - this.baseX) / range;
- const yRaw = (sy - this.baseY) / range;
+ const alpha = this.opts.baselineAlpha;
+ this.baseX += alpha * (screenX - this.baseX);
+ this.baseY += alpha * (screenY - this.baseY);
+ const xRaw = (screenX - this.baseX) / this.opts.range;
+ const yRaw = (screenY - this.baseY) / this.opts.range;
const xFiltered = this.filterX.filter(xRaw, now);
const yFiltered = this.filterY.filter(yRaw, now);
this.callback({
- x: clamp(xFiltered, -1, 1),
- y: clamp(yFiltered, -1, 1),
+ x: applyDeadZone(clamp(xFiltered), this.opts.deadZone),
+ y: applyDeadZone(clamp(yFiltered), this.opts.deadZone),
z: 0,
});
+ this.armIdleReset();
}
- cleanup(): void {
- // Set disposed first so any in-flight requestPermission() promise
- // that resolves after cleanup() short-circuits before re-attaching
- // a deviceorientation listener (iOS keeps the permission prompt
- // open across tab navigation; the user can dismiss after the
- // component has unmounted).
- this.disposed = true;
- this.stopListening();
- if (this.reducedMotionMql && this.reducedMotionListener) {
- this.reducedMotionMql.removeEventListener(
- 'change',
- this.reducedMotionListener
- );
+ private consumeCalibrationSample(screenX: number, screenY: number): boolean {
+ if (this.calibrationRemaining <= 0) return true;
+
+ this.calibrationTotalX += screenX;
+ this.calibrationTotalY += screenY;
+ this.calibrationRemaining -= 1;
+
+ if (this.calibrationRemaining > 0) return false;
+
+ const sampleCount = Math.max(1, this.calibrationTargetSamples);
+ this.baseX = this.calibrationTotalX / sampleCount;
+ this.baseY = this.calibrationTotalY / sampleCount;
+ this.calibrationTotalX = 0;
+ this.calibrationTotalY = 0;
+ this.resetFilterState({ resetWarmup: false });
+ return false;
+ }
+
+ private resetFilterState({ resetWarmup = true } = {}): void {
+ this.filterX.reset();
+ this.filterY.reset();
+ if (resetWarmup) {
+ this.listenerStartedAt = this.now();
}
- this.reducedMotionMql = null;
- this.reducedMotionListener = null;
- this.resetFilterState();
+ this.lastEventAt = 0;
+ }
+
+ private emitNeutral(): void {
+ this.callback({ x: 0, y: 0, z: 0 });
+ }
+
+ private armIdleReset(): void {
+ this.clearIdleReset();
+ if (!this.isListening || this.opts.idleResetMs <= 0) return;
+
+ this.idleResetTimer = setTimeout(() => {
+ this.idleResetTimer = null;
+ if (this.disposed || !this.isListening) return;
+
+ this.resetFilterState({ resetWarmup: false });
+ this.emitNeutral();
+ }, this.opts.idleResetMs);
+
+ (this.idleResetTimer as { unref?: () => void }).unref?.();
+ }
+
+ private clearIdleReset(): void {
+ if (this.idleResetTimer === null) return;
+ clearTimeout(this.idleResetTimer);
+ this.idleResetTimer = null;
+ }
+
+ private now(): number {
+ return typeof performance !== 'undefined' ? performance.now() : Date.now();
}
}
diff --git a/src/motion/OneEuro.ts b/src/motion/OneEuro.ts
index da61364..d7b9348 100644
--- a/src/motion/OneEuro.ts
+++ b/src/motion/OneEuro.ts
@@ -31,7 +31,11 @@ export class OneEuro {
private prevX: number | undefined;
private prevT: number | undefined;
- constructor(private p: OneEuroParams) {}
+ constructor(private p: OneEuroParams) {
+ if (p.minCutoff <= 0 || p.dCutoff <= 0) {
+ throw new RangeError('OneEuro: minCutoff and dCutoff must be > 0');
+ }
+ }
/** Filter sample `x` at time `tMs` (milliseconds). */
filter(x: number, tMs: number): number {
@@ -40,6 +44,7 @@ export class OneEuro {
this.prevX = x;
return this.x.filter(x, 1);
}
+ // tMs must be monotonically non-decreasing; backward jumps clamp to 1 ms.
const dt = Math.max(1e-3, (tMs - this.prevT) / 1000);
const dxRaw = (x - this.prevX) / dt;
const dxHat = this.dx.filter(dxRaw, alpha(this.p.dCutoff, dt));
diff --git a/src/motion/PointerMapper.ts b/src/motion/PointerMapper.ts
new file mode 100644
index 0000000..adb48e3
--- /dev/null
+++ b/src/motion/PointerMapper.ts
@@ -0,0 +1,43 @@
+export interface PointerBounds {
+ left: number;
+ top: number;
+ width: number;
+ height: number;
+}
+
+export interface PhysicsPoint {
+ x: number;
+ y: number;
+}
+
+export interface PhysicsRange {
+ min: number;
+ max: number;
+}
+
+const DEFAULT_RANGE: PhysicsRange = { min: 0, max: 100 };
+
+const clamp01 = (value: number): number => Math.max(0, Math.min(1, value));
+
+export function mapClientPointToPhysics(
+ clientX: number,
+ clientY: number,
+ bounds: PointerBounds,
+ range: PhysicsRange = DEFAULT_RANGE,
+): PhysicsPoint {
+ if (bounds.width <= 0 || bounds.height <= 0) {
+ return {
+ x: (range.min + range.max) / 2,
+ y: (range.min + range.max) / 2,
+ };
+ }
+
+ const span = range.max - range.min;
+ const normalizedX = clamp01((clientX - bounds.left) / bounds.width);
+ const normalizedY = clamp01((clientY - bounds.top) / bounds.height);
+
+ return {
+ x: range.min + normalizedX * span,
+ y: range.min + normalizedY * span,
+ };
+}
diff --git a/src/motion/PointerPhysicsController.ts b/src/motion/PointerPhysicsController.ts
new file mode 100644
index 0000000..69a7e3b
--- /dev/null
+++ b/src/motion/PointerPhysicsController.ts
@@ -0,0 +1,173 @@
+import {
+ mapClientPointToPhysics,
+ type PhysicsPoint,
+ type PhysicsRange,
+ type PointerBounds,
+} from './PointerMapper.js';
+
+export type PointerMoveEventName = 'pointermove' | 'mousemove';
+export type PointerExitEventName = 'pointerout' | 'mouseout';
+export type PointerCancelEventName = 'pointercancel';
+export type PointerLifecycleEventName =
+ | PointerMoveEventName
+ | PointerExitEventName
+ | PointerCancelEventName
+ | 'blur';
+
+export interface PointerPhysicsEventTarget {
+ addEventListener(
+ type: PointerLifecycleEventName,
+ listener: EventListener,
+ options?: AddEventListenerOptions,
+ ): void;
+ removeEventListener(type: PointerLifecycleEventName, listener: EventListener): void;
+}
+
+export interface PointerLikeEvent {
+ clientX: number;
+ clientY: number;
+ getCoalescedEvents?: () => PointerLikeEvent[];
+}
+
+export interface PointerExitLikeEvent {
+ relatedTarget?: EventTarget | null;
+}
+
+export interface PointerPhysicsControllerOptions {
+ target: PointerPhysicsEventTarget;
+ getBounds: () => PointerBounds;
+ updatePosition: (position: PhysicsPoint) => void;
+ range?: PhysicsRange;
+ supportsPointerEvents?: boolean;
+ requestFrame?: (callback: FrameRequestCallback) => number;
+ cancelFrame?: (handle: number) => void;
+}
+
+export interface PointerCapabilityEnvironment {
+ PointerEvent?: unknown;
+ MouseEvent?: unknown;
+ navigator?: {
+ maxTouchPoints?: number;
+ };
+ matchMedia?: (query: string) => { matches: boolean };
+}
+
+export interface PointerPhysicsController {
+ readonly eventName: PointerMoveEventName;
+ readonly exitEventName: PointerExitEventName;
+ readonly cancelEventName: PointerCancelEventName | null;
+ flush(): void;
+ dispose(): void;
+}
+
+export function getLatestPointerEvent(event: PointerLikeEvent): PointerLikeEvent {
+ const coalesced =
+ typeof event.getCoalescedEvents === 'function' ? event.getCoalescedEvents() : [];
+ return coalesced.length > 0 ? coalesced[coalesced.length - 1] : event;
+}
+
+export function detectPointerPhysicsCapability(
+ environment: PointerCapabilityEnvironment = globalThis,
+): boolean {
+ if (typeof environment.PointerEvent !== 'undefined') return true;
+ if ((environment.navigator?.maxTouchPoints ?? 0) > 0) return true;
+ if (environment.matchMedia?.('(pointer: fine), (pointer: coarse)').matches) return true;
+ return typeof environment.MouseEvent !== 'undefined';
+}
+
+function getRangeCenter(range?: PhysicsRange): PhysicsPoint {
+ const center = range ? (range.min + range.max) / 2 : 50;
+ return { x: center, y: center };
+}
+
+export function createPointerPhysicsController(
+ options: PointerPhysicsControllerOptions,
+): PointerPhysicsController {
+ const requestFrame = options.requestFrame ?? requestAnimationFrame;
+ const cancelFrame = options.cancelFrame ?? cancelAnimationFrame;
+ const supportsPointerEvents =
+ options.supportsPointerEvents ?? typeof PointerEvent !== 'undefined';
+ const eventName: PointerMoveEventName = supportsPointerEvents ? 'pointermove' : 'mousemove';
+ const exitEventName: PointerExitEventName = supportsPointerEvents ? 'pointerout' : 'mouseout';
+ const cancelEventName: PointerCancelEventName | null = supportsPointerEvents
+ ? 'pointercancel'
+ : null;
+
+ let frame: number | null = null;
+ let pendingPosition: PhysicsPoint | null = null;
+ let disposed = false;
+
+ const flush = () => {
+ frame = null;
+ if (disposed || !pendingPosition) return;
+
+ options.updatePosition(pendingPosition);
+ pendingPosition = null;
+ };
+
+ const resetPosition = () => {
+ if (frame !== null) {
+ cancelFrame(frame);
+ frame = null;
+ }
+ pendingPosition = null;
+ options.updatePosition(getRangeCenter(options.range));
+ };
+
+ const handleMove: EventListener = (event) => {
+ if (disposed) return;
+
+ const pointerEvent = getLatestPointerEvent(event as unknown as PointerLikeEvent);
+ pendingPosition = mapClientPointToPhysics(
+ pointerEvent.clientX,
+ pointerEvent.clientY,
+ options.getBounds(),
+ options.range,
+ );
+
+ if (frame === null) {
+ frame = requestFrame(flush);
+ }
+ };
+
+ const handleExit: EventListener = (event) => {
+ if (disposed) return;
+ const exitEvent = event as unknown as PointerExitLikeEvent;
+ if (exitEvent.relatedTarget) return;
+ resetPosition();
+ };
+
+ const handleBlur: EventListener = () => {
+ if (disposed) return;
+ resetPosition();
+ };
+
+ options.target.addEventListener(eventName, handleMove, { passive: true });
+ options.target.addEventListener(exitEventName, handleExit, { passive: true });
+ if (cancelEventName) {
+ options.target.addEventListener(cancelEventName, handleBlur);
+ }
+ options.target.addEventListener('blur', handleBlur);
+
+ return {
+ eventName,
+ exitEventName,
+ cancelEventName,
+ flush,
+ dispose() {
+ if (disposed) return;
+ disposed = true;
+ options.target.removeEventListener(eventName, handleMove);
+ options.target.removeEventListener(exitEventName, handleExit);
+ if (cancelEventName) {
+ options.target.removeEventListener(cancelEventName, handleBlur);
+ }
+ options.target.removeEventListener('blur', handleBlur);
+ if (frame !== null) {
+ cancelFrame(frame);
+ frame = null;
+ }
+ pendingPosition = null;
+ },
+ };
+}
diff --git a/src/motion/ScrollHandler.ts b/src/motion/ScrollHandler.ts
index fb9c13b..3b3c389 100644
--- a/src/motion/ScrollHandler.ts
+++ b/src/motion/ScrollHandler.ts
@@ -1,11 +1,7 @@
-
-
-
-
-
-
export interface ScrollHandlerConfig {
+ /** Per-frame decay multiplier for scroll stickiness and velocity. Defaults to 0.92. */
decayRate?: number;
+ /** Maximum retained pull-force impulses. Defaults to 8, or 10 for explosive scrolls. Use 0 to keep scroll stickiness without retained pull forces. */
maxForces?: number;
}
@@ -23,13 +19,21 @@ export class ScrollHandler {
private scrollDirection = 0;
private pullForces: PullForce[] = [];
private peakVelocity = 0;
- private rafId: number | null = null;
+ private decayFrame: number | null = null;
+ private scrollEndTimer: ReturnType | null = null;
+ private disposed = false;
+ private maxForces: number | null = null;
constructor(config?: ScrollHandlerConfig) {
if (config?.decayRate) this.decayRate = config.decayRate;
+ if (typeof config?.maxForces === 'number') {
+ this.maxForces = Math.max(0, Math.floor(config.maxForces));
+ }
}
public handleScroll(event: WheelEvent): void {
+ if (this.disposed) return;
+
const currentTime = Date.now();
const deltaTime = currentTime - this.lastScrollTime;
@@ -68,9 +72,17 @@ export class ScrollHandler {
this.lastScrollTime = currentTime;
this.startDecay();
+ this.scheduleScrollEnd();
+ }
+
+ private scheduleScrollEnd(): void {
+ if (this.scrollEndTimer !== null) {
+ clearTimeout(this.scrollEndTimer);
+ }
- setTimeout(() => {
- if (currentTime - this.lastScrollTime >= 200) {
+ this.scrollEndTimer = setTimeout(() => {
+ this.scrollEndTimer = null;
+ if (Date.now() - this.lastScrollTime >= 200) {
this.isScrolling = false;
this.totalScrollDistance = 0;
this.peakVelocity = 0;
@@ -82,7 +94,7 @@ export class ScrollHandler {
speedStickiness: number,
distanceStickiness: number,
direction: number,
- explosive: boolean
+ explosive: boolean,
): void {
if (direction <= 0 || speedStickiness > 0.4 || distanceStickiness > 0.4 || explosive) {
let pullStrength = speedStickiness + distanceStickiness * 0.7;
@@ -101,24 +113,23 @@ export class ScrollHandler {
strength: pullStrength,
time: 0,
randomness: randomnessFactor,
- explosive: explosive,
+ explosive,
});
- if (this.pullForces.length > (explosive ? 10 : 8)) {
- this.pullForces.shift();
+ const maxForces = this.maxForces ?? (explosive ? 10 : 8);
+ if (this.pullForces.length > maxForces) {
+ this.pullForces.splice(0, this.pullForces.length - maxForces);
}
}
}
private startDecay(): void {
- // Cancel any in-flight decay so rapid handleScroll() calls don't
- // queue overlapping RAF callbacks.
- if (this.rafId !== null) {
- cancelAnimationFrame(this.rafId);
- this.rafId = null;
- }
+ if (this.decayFrame !== null) return;
const decay = () => {
+ this.decayFrame = null;
+ if (this.disposed) return;
+
this.stickiness *= this.decayRate;
this.scrollVelocity *= this.decayRate;
@@ -134,14 +145,13 @@ export class ScrollHandler {
}));
if (this.stickiness > 0.01 || this.pullForces.length > 0) {
- this.rafId = requestAnimationFrame(decay);
+ this.decayFrame = requestAnimationFrame(decay);
} else {
this.stickiness = 0;
this.scrollVelocity = 0;
- this.rafId = null;
}
};
- this.rafId = requestAnimationFrame(decay);
+ this.decayFrame = requestAnimationFrame(decay);
}
public getStickiness(): number {
@@ -171,4 +181,25 @@ export class ScrollHandler {
public getPeakVelocity(): number {
return this.peakVelocity;
}
+
+ public dispose(): void {
+ this.disposed = true;
+
+ if (this.decayFrame !== null) {
+ cancelAnimationFrame(this.decayFrame);
+ this.decayFrame = null;
+ }
+
+ if (this.scrollEndTimer !== null) {
+ clearTimeout(this.scrollEndTimer);
+ this.scrollEndTimer = null;
+ }
+
+ this.stickiness = 0;
+ this.scrollVelocity = 0;
+ this.totalScrollDistance = 0;
+ this.peakVelocity = 0;
+ this.isScrolling = false;
+ this.pullForces = [];
+ }
}
diff --git a/src/motion/index.ts b/src/motion/index.ts
index 5ded2ef..1e26e10 100644
--- a/src/motion/index.ts
+++ b/src/motion/index.ts
@@ -2,5 +2,32 @@
-export { DeviceMotion, type DeviceMotionCallback } from './DeviceMotion.js';
+export {
+ DeviceMotion,
+ type DeviceMotionCallback,
+ type DeviceMotionOptions,
+ type DeviceMotionPermissionState,
+ type MotionVector,
+} from './DeviceMotion.js';
+export {
+ mapClientPointToPhysics,
+ type PhysicsPoint,
+ type PhysicsRange,
+ type PointerBounds,
+} from './PointerMapper.js';
+export {
+ createPointerPhysicsController,
+ detectPointerPhysicsCapability,
+ getLatestPointerEvent,
+ type PointerCapabilityEnvironment,
+ type PointerCancelEventName,
+ type PointerExitEventName,
+ type PointerExitLikeEvent,
+ type PointerLifecycleEventName,
+ type PointerLikeEvent,
+ type PointerMoveEventName,
+ type PointerPhysicsController,
+ type PointerPhysicsControllerOptions,
+ type PointerPhysicsEventTarget,
+} from './PointerPhysicsController.js';
export { ScrollHandler, type ScrollHandlerConfig, type PullForce } from './ScrollHandler.js';
diff --git a/src/svelte/BlobSVG.svelte.d.ts b/src/svelte/BlobSVG.svelte.d.ts
new file mode 100644
index 0000000..4e9ee49
--- /dev/null
+++ b/src/svelte/BlobSVG.svelte.d.ts
@@ -0,0 +1,11 @@
+import type { Component } from 'svelte';
+import type { BlobPhysics } from '../core/BlobPhysics.js';
+import type { ConvexBlob } from '../core/types.js';
+
+export interface BlobSVGProps {
+ blobs?: ConvexBlob[];
+ physics?: BlobPhysics | null;
+}
+
+declare const BlobSVG: Component;
+export default BlobSVG;
diff --git a/src/svelte/TinyVectors.svelte b/src/svelte/TinyVectors.svelte
index c480f5f..8a70989 100644
--- a/src/svelte/TinyVectors.svelte
+++ b/src/svelte/TinyVectors.svelte
@@ -2,12 +2,24 @@
import { browser } from '../core/browser.js';
import { untrack } from 'svelte';
import { BlobPhysics, type BlobPhysicsConfig } from '../core/BlobPhysics.js';
- import { DeviceMotion } from '../motion/DeviceMotion.js';
+ import {
+ DeviceMotion,
+ getDeviceMotionCapabilityState,
+ isDeviceMotionPermissionRequired,
+ type MotionVector,
+ } from '../motion/DeviceMotion.js';
+ import {
+ createPointerPhysicsController,
+ detectPointerPhysicsCapability,
+ type PointerPhysicsController,
+ } from '../motion/PointerPhysicsController.js';
+ import type { PointerBounds } from '../motion/PointerMapper.js';
import { ScrollHandler } from '../motion/ScrollHandler.js';
- import { THEME_PRESETS, type ThemePresetName } from '../core/schema.js';
+ import { THEME_PRESET_COLORS } from '../core/theme-colors.js';
+ import type { ThemePresetName } from '../core/theme-presets.js';
+ import type { TinyVectorsDeviceMotionStatus } from './types.js';
import BlobSVG from './BlobSVG.svelte';
- // Props
interface Props {
/** Theme preset name */
theme?: ThemePresetName;
@@ -23,10 +35,20 @@
blobCount?: number;
/** Physics configuration */
physicsConfig?: Partial;
- /** Enable device motion (accelerometer) */
+ /** Enable device orientation based motion */
enableDeviceMotion?: boolean;
/** Enable scroll physics */
enableScrollPhysics?: boolean;
+ /** Enable pointer/mouse physics */
+ enablePointerPhysics?: boolean;
+ /** Scales normalized screen-aligned tilt vectors before applying them to physics. */
+ deviceMotionStrength?: number;
+ /** Samples used by calibrateDeviceMotion() when no explicit count is supplied. */
+ deviceMotionCalibrationSamples?: number;
+ /** Milliseconds before paused device-orientation IO resets to neutral. */
+ deviceMotionIdleResetMs?: number;
+ /** Optional diagnostics hook for browser/dev harnesses. */
+ onDeviceMotion?: (motionData: MotionVector) => void;
}
let {
@@ -39,101 +61,79 @@
physicsConfig = {},
enableDeviceMotion = true,
enableScrollPhysics = true,
+ enablePointerPhysics = true,
+ deviceMotionStrength = 0.8,
+ deviceMotionCalibrationSamples = 8,
+ deviceMotionIdleResetMs = 2000,
+ onDeviceMotion,
}: Props = $props();
- // State - use regular variables for non-reactive state
+ let containerElement: HTMLDivElement | undefined = $state(undefined);
let blobs = $state>([]);
let isReady = $state(false);
- let isMobileDevice = $state(false);
- let hasAccelerometerAccess = $state(false);
- // Internal handles that are passed into child components need to stay reactive.
let physics = $state(null);
let animationFrame: number | null = null;
let lastTime = 0;
let deviceMotion: DeviceMotion | null = null;
let scrollHandler: ScrollHandler | null = null;
- let gravityX = 0;
- let gravityY = 0;
- let tiltX = 0;
- let tiltY = 0;
- let tiltZ = 0;
+ let pointerController: PointerPhysicsController | null = null;
- // Get theme colors - use $derived.by for computed values
const themeColors = $derived.by(() => {
if (colors.length > 0) return colors;
- const preset = THEME_PRESETS[theme];
- if (!preset || !preset.hasVectors) return [];
- return preset.colors.map((c) => c.color);
+ return THEME_PRESET_COLORS[theme] ?? [];
});
- // Default physics config
- const defaultPhysicsConfig: BlobPhysicsConfig = {
- antiClusteringStrength: 0.15,
- bounceDamping: 0.7,
- deformationSpeed: 0.5,
- territoryStrength: 0.1,
- viscosity: 0.3,
- useSpatialHash: true,
- useGaussianSmoothing: true,
- useSpringSystem: true,
- springConfig: {},
+ const detectDeviceMotionCapability = (): boolean => {
+ return browser && getDeviceMotionCapabilityState() === 'unknown';
};
- // Detect mobile device
- const detectMobileDevice = (): boolean => {
- if (!browser) return false;
- const userAgent = navigator.userAgent.toLowerCase();
- const mobileKeywords = ['mobile', 'android', 'iphone', 'ipad', 'ipod', 'blackberry', 'windows phone'];
- const isMobileUserAgent = mobileKeywords.some((keyword) => userAgent.includes(keyword));
- const isMobileScreen = window.innerWidth <= 768 || window.innerHeight <= 768;
- const hasTouchScreen = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
- const hasOrientationAPI = 'DeviceOrientationEvent' in window;
- return (isMobileUserAgent || (isMobileScreen && hasTouchScreen)) && hasOrientationAPI;
- };
+ const createDeviceMotion = (): DeviceMotion =>
+ new DeviceMotion(handleDeviceMotion, {
+ calibrationSamples: deviceMotionCalibrationSamples,
+ deadZone: 0.015,
+ idleResetMs: deviceMotionIdleResetMs,
+ });
- // DeviceMotion now emits already-filtered, axis-remapped, screen-aligned
- // tilt vectors in [-1, 1] (One-Euro internally, slow baseline subtraction,
- // face-down suppression, screen.orientation remap). Pass through directly
- // — no extra EMA, no axis swap, no negation. The 0.8 magnitude scaler is
- // preserved so gravity strength matches the previous code's feel at the
- // physics layer.
- //
- // Y-gravity sign note: the previous handler computed gravityY = -beta,
- // which made forward-tilt drive gravity UP the screen (away from the
- // viewer). That was counter-intuitive — forward tilt should pull stuff
- // toward the viewer (positive screen-Y, downward). TiltSource emits
- // screen-aligned values directly, so we use motionData.y unchanged.
- // This is the intentional fix that the canonical consumer was working
- // around by setting enableDeviceMotion={false}.
- const handleDeviceMotion = (motionData: { x: number; y: number; z: number }) => {
- if (!hasAccelerometerAccess || !physics) return;
- tiltX = motionData.x;
- tiltY = motionData.y;
- tiltZ = motionData.z;
- gravityX = motionData.x * 0.8;
- gravityY = motionData.y * 0.8;
- physics.setGravity({ x: gravityX, y: gravityY });
- physics.setTilt({ x: tiltX, y: tiltY, z: tiltZ });
- };
+ const handleDeviceMotion = (motionData: MotionVector) => {
+ if (!physics) return;
- // Request accelerometer permission
- const requestAccelerometerPermission = async (): Promise => {
- if (!isMobileDevice || !deviceMotion) return;
+ onDeviceMotion?.(motionData);
- try {
- const hasPermission = await deviceMotion.requestPermission();
- hasAccelerometerAccess = hasPermission;
- if (hasPermission) {
- console.log('[TinyVectors] Accelerometer access granted');
- }
- } catch (error) {
- console.log('[TinyVectors] Could not request accelerometer permission:', error);
- hasAccelerometerAccess = false;
- }
+ // DeviceMotion emits screen-aligned tilt, so no old beta/gamma axis swap.
+ physics.setGravity({
+ x: motionData.x * deviceMotionStrength,
+ y: motionData.y * deviceMotionStrength,
+ });
+ physics.setTilt(motionData);
};
- // Handle scroll passively — never block native scrolling
+ export async function requestDeviceMotionPermission(): Promise {
+ if (!browser || !enableDeviceMotion || !physics || !detectDeviceMotionCapability()) return false;
+
+ deviceMotion ??= createDeviceMotion();
+
+ const hasPermission = await deviceMotion.requestPermission();
+ return hasPermission;
+ }
+
+ export function calibrateDeviceMotion(samples?: number): void {
+ deviceMotion?.calibrate(samples);
+ }
+
+ export function getDeviceMotionStatus(): TinyVectorsDeviceMotionStatus {
+ const capabilityState = getDeviceMotionCapabilityState();
+ const permissionState = deviceMotion?.getPermissionState() ?? capabilityState;
+
+ return {
+ enabled: enableDeviceMotion,
+ supported: capabilityState !== 'unsupported' && capabilityState !== 'insecure',
+ requiresPermission: browser && isDeviceMotionPermissionRequired(),
+ permissionState,
+ active: deviceMotion?.isActive() ?? false,
+ };
+ }
+
const handleScroll = (event: WheelEvent) => {
if (!scrollHandler || !physics) return;
scrollHandler.handleScroll(event);
@@ -141,14 +141,32 @@
physics.setScrollStickiness(stickiness);
};
- // Animation tick function - updates blobs state once per frame
+ const getPointerBounds = (): PointerBounds => {
+ const rect = containerElement?.getBoundingClientRect();
+
+ if (rect && rect.width > 0 && rect.height > 0) {
+ return {
+ left: rect.left,
+ top: rect.top,
+ width: rect.width,
+ height: rect.height,
+ };
+ }
+
+ return {
+ left: 0,
+ top: 0,
+ width: window.innerWidth || 1,
+ height: window.innerHeight || 1,
+ };
+ };
+
function tick(currentTime: number) {
const dt = Math.min((currentTime - lastTime) / 1000, 0.033);
lastTime = currentTime;
if (physics) {
physics.tick(dt, currentTime / 1000);
- // Update blobs state - this triggers re-render
blobs = physics.getBlobs(themeColors);
}
@@ -168,34 +186,37 @@
}
}
- // Single initialization effect
$effect(() => {
if (!browser || !shouldLoad) return;
- // Use untrack to prevent this effect from re-running on state changes
+ let disposed = false;
+ const deviceMotionEnabled = enableDeviceMotion;
+ const scrollPhysicsEnabled = enableScrollPhysics;
+ const pointerPhysicsEnabled = enablePointerPhysics;
+ let wheelListenerAttached = false;
+
untrack(() => {
- const config = { ...defaultPhysicsConfig, ...physicsConfig };
- physics = new BlobPhysics(blobCount, config);
+ // BlobPhysics owns base defaults; this component forwards caller overrides.
+ const currentPhysics = new BlobPhysics(blobCount, physicsConfig);
+ physics = currentPhysics;
+
+ currentPhysics.init().then(() => {
+ if (disposed || physics !== currentPhysics) return;
- physics.init().then(() => {
- // Detect mobile
- isMobileDevice = detectMobileDevice();
+ const hasDeviceMotionCapability = detectDeviceMotionCapability();
isReady = true;
- // Initialize device motion on mobile
- if (enableDeviceMotion && isMobileDevice) {
- deviceMotion = new DeviceMotion(handleDeviceMotion);
- deviceMotion.initialize().then(() => {
- setTimeout(requestAccelerometerPermission, 1000);
- });
+ if (deviceMotionEnabled && hasDeviceMotionCapability) {
+ if (!deviceMotion) {
+ deviceMotion = createDeviceMotion();
+ void deviceMotion.initialize();
+ }
}
- // Initialize scroll handler
- if (enableScrollPhysics) {
+ if (scrollPhysicsEnabled) {
scrollHandler = new ScrollHandler();
}
- // Start animation if enabled
if (animated) {
startAnimation();
} else if (physics) {
@@ -203,24 +224,45 @@
}
});
- // Set up scroll listener
- if (enableScrollPhysics) {
+ if (scrollPhysicsEnabled) {
window.addEventListener('wheel', handleScroll, { passive: true });
+ wheelListenerAttached = true;
+ }
+
+ if (pointerPhysicsEnabled) {
+ const hasPointerCapability = detectPointerPhysicsCapability(window);
+ if (hasPointerCapability) {
+ pointerController = createPointerPhysicsController({
+ target: window,
+ getBounds: getPointerBounds,
+ supportsPointerEvents: 'PointerEvent' in window,
+ updatePosition(position) {
+ physics?.updateMousePosition(position.x, position.y);
+ },
+ });
+ }
}
});
return () => {
+ disposed = true;
stopAnimation();
- if (enableScrollPhysics && browser) {
+ if (wheelListenerAttached) {
window.removeEventListener('wheel', handleScroll);
}
+ pointerController?.dispose();
+ pointerController = null;
deviceMotion?.cleanup();
+ deviceMotion = null;
+ scrollHandler?.dispose();
+ scrollHandler = null;
physics?.dispose();
physics = null;
+ isReady = false;
+ blobs = [];
};
});
- // Handle animated prop changes
$effect(() => {
if (!isReady) return;
@@ -234,7 +276,13 @@
{#if shouldLoad && themeColors.length > 0}
;
+ /** Enable device orientation based motion */
+ enableDeviceMotion?: boolean;
+ /** Enable scroll physics */
+ enableScrollPhysics?: boolean;
+ /** Enable pointer/mouse physics */
+ enablePointerPhysics?: boolean;
+ /** Scales normalized screen-aligned tilt vectors before applying them to physics. */
+ deviceMotionStrength?: number;
+ /** Samples used by calibrateDeviceMotion() when no explicit count is supplied. */
+ deviceMotionCalibrationSamples?: number;
+ /** Milliseconds before paused device-orientation IO resets to neutral. */
+ deviceMotionIdleResetMs?: number;
+ /** Optional diagnostics hook for browser/dev harnesses. */
+ onDeviceMotion?: (motionData: MotionVector) => void;
+}
+
+export interface TinyVectorsExports {
+ requestDeviceMotionPermission(): Promise
;
+ calibrateDeviceMotion(samples?: number): void;
+ getDeviceMotionStatus(): TinyVectorsDeviceMotionStatus;
+}
+
+declare const TinyVectors: Component;
+export default TinyVectors;
diff --git a/src/svelte/index.ts b/src/svelte/index.ts
index 1089ede..01c2ebb 100644
--- a/src/svelte/index.ts
+++ b/src/svelte/index.ts
@@ -4,6 +4,9 @@
export { default as TinyVectors } from './TinyVectors.svelte';
+export type {
+ TinyVectorsDeviceMotionStatus,
+} from './types.js';
export { default as BlobSVG } from './BlobSVG.svelte';
diff --git a/src/svelte/types.ts b/src/svelte/types.ts
new file mode 100644
index 0000000..6d14687
--- /dev/null
+++ b/src/svelte/types.ts
@@ -0,0 +1,9 @@
+import type { DeviceMotionPermissionState } from '../motion/DeviceMotion.js';
+
+export interface TinyVectorsDeviceMotionStatus {
+ enabled: boolean;
+ supported: boolean;
+ requiresPermission: boolean;
+ permissionState: DeviceMotionPermissionState;
+ active: boolean;
+}
diff --git a/src/themes/index.ts b/src/themes/index.ts
index 72068d4..46ead4d 100644
--- a/src/themes/index.ts
+++ b/src/themes/index.ts
@@ -2,7 +2,7 @@
-import { THEME_PRESETS, type ThemePreset } from '../core/schema.js';
+import { THEME_PRESETS, type ThemePreset } from '../core/theme-presets.js';
export {
THEME_PRESETS,
@@ -13,7 +13,7 @@ export {
type ThemePreset,
type ThemeColor,
type ThemePresetName,
-} from '../core/schema.js';
+} from '../core/theme-presets.js';
diff --git a/src/themes/vector-colors.css b/src/themes/vector-colors.css
index 0767214..1e48a02 100644
--- a/src/themes/vector-colors.css
+++ b/src/themes/vector-colors.css
@@ -3,13 +3,10 @@
*/
/* Per-blob intensity, registered so calc() in SVG stop-opacity is
- * interpolated as a number rather than a string. Set inline on each
- * from blob.intensity in BlobSVG.svelte; gradient
- * stops compute their actual opacity via calc(var(--tv-blob-intensity)
- * * ). Avoids ~60 reactive expressions per frame in
- * Svelte (one per stop-opacity arithmetic) — the inline style still
- * re-runs each frame, but only ~5 evaluations per frame total
- * (one per blob, not per stop).
+ * interpolated as a number rather than a string. BlobSVG.svelte sets
+ * --tv-blob-intensity inline on each ; gradient stops
+ * compute their actual opacity via calc(var(--tv-blob-intensity)
+ * * ).
*/
@property --tv-blob-intensity {
syntax: '';
diff --git a/tests/unit/core.test.ts b/tests/unit/core.test.ts
index efcc51c..5fa4b9d 100644
--- a/tests/unit/core.test.ts
+++ b/tests/unit/core.test.ts
@@ -16,6 +16,11 @@ import {
} from '../../src/core/PathGenerator.js';
import { SpatialHash } from '../../src/core/SpatialHash.js';
import { GaussianKernel } from '../../src/core/GaussianKernel.js';
+import {
+ BlobPhysics,
+ DEFAULT_BLOB_PHYSICS_CONFIG,
+ type BlobPhysicsConfig,
+} from '../../src/core/BlobPhysics.js';
import type { RenderBlob } from '../../src/core/schema.js';
import type { ConvexBlob, ControlPoint } from '../../src/core/types.js';
@@ -93,6 +98,24 @@ function createTestConvexBlob(x: number, y: number, size: number = 25): ConvexBl
};
}
+function smoothTestControlRadii(radii: number[]): number[] {
+ const blob = createTestConvexBlob(50, 50, 20);
+ blob.controlPoints?.forEach((point, index) => {
+ point.radius = radii[index];
+ point.baseRadius = radii[index];
+ point.targetRadius = radii[index];
+ });
+
+ const physics = new BlobPhysics(0);
+ (
+ physics as unknown as {
+ smoothControlPoints(blob: ConvexBlob): void;
+ }
+ ).smoothControlPoints(blob);
+
+ return blob.controlPoints?.map((point) => point.radius) ?? [];
+}
+
@@ -223,6 +246,125 @@ describe('PathGenerator', () => {
+describe('BlobPhysics', () => {
+ it('owns the TinyVectors default physics configuration', () => {
+ expect(DEFAULT_BLOB_PHYSICS_CONFIG).toEqual({
+ antiClusteringStrength: 0.15,
+ bounceDamping: 0.7,
+ deformationSpeed: 0.5,
+ territoryStrength: 0.1,
+ viscosity: 0.3,
+ useSpatialHash: true,
+ useGaussianSmoothing: true,
+ useSpringSystem: true,
+ springConfig: {},
+ });
+ });
+
+ it('merges caller overrides on top of internal defaults', () => {
+ const physics = new BlobPhysics(2, {
+ antiClusteringStrength: 0.25,
+ useSpatialHash: false,
+ });
+ const config = (physics as unknown as { config: BlobPhysicsConfig }).config;
+
+ expect(config).toEqual({
+ ...DEFAULT_BLOB_PHYSICS_CONFIG,
+ antiClusteringStrength: 0.25,
+ useSpatialHash: false,
+ });
+ });
+
+ it('smooths control points without start-index directional bias', () => {
+ const radii = [20, 40, 20, 10, 30, 20, 35, 15];
+ const rotatedRadii = [radii[radii.length - 1], ...radii.slice(0, -1)];
+ const expected = smoothTestControlRadii(radii);
+ const rotatedResult = smoothTestControlRadii(rotatedRadii);
+ const rotatedBack = [...rotatedResult.slice(1), rotatedResult[0]];
+
+ expect(rotatedBack).toHaveLength(expected.length);
+ for (let i = 0; i < expected.length; i++) {
+ expect(rotatedBack[i]).toBeCloseTo(expected[i], 10);
+ }
+ });
+
+ it('smooths control points without winding-order directional bias', () => {
+ const radii = [20, 40, 20, 10, 30, 20, 35, 15];
+ const mirroredRadii = [radii[0], ...radii.slice(1).reverse()];
+ const expected = smoothTestControlRadii(radii);
+ const mirroredResult = smoothTestControlRadii(mirroredRadii);
+ const mirroredBack = [mirroredResult[0], ...mirroredResult.slice(1).reverse()];
+
+ expect(mirroredBack).toHaveLength(expected.length);
+ for (let i = 0; i < expected.length; i++) {
+ expect(mirroredBack[i]).toBeCloseTo(expected[i], 10);
+ }
+ });
+
+ it('applies device gravity as a bounded directional field', () => {
+ const physics = new BlobPhysics(0);
+ const blob = createTestConvexBlob(50, 50, 20);
+ const applyAccelerometerForces = (
+ physics as unknown as {
+ applyAccelerometerForces(blob: ConvexBlob): void;
+ }
+ ).applyAccelerometerForces.bind(physics);
+
+ physics.setGravity({ x: 3, y: 4 });
+ applyAccelerometerForces(blob);
+
+ const magnitude = Math.sqrt(blob.velocityX * blob.velocityX + blob.velocityY * blob.velocityY);
+ expect(magnitude).toBeCloseTo(0.003);
+ expect(blob.velocityX).toBeGreaterThan(0);
+ expect(blob.velocityY).toBeGreaterThan(0);
+ expect(blob.velocityX / blob.velocityY).toBeCloseTo(3 / 4);
+ });
+
+ it('tracks pointer position and velocity without applying standalone pointer force', () => {
+ const physics = new BlobPhysics(0);
+ const blob = createTestConvexBlob(30, 50, 20);
+ const internals = physics as unknown as {
+ mouseX: number;
+ mouseY: number;
+ mouseVelX: number;
+ mouseVelY: number;
+ updateScreensaverPhysics(blob: ConvexBlob, deltaTime: number, time: number): void;
+ };
+
+ physics.updateMousePosition(75, 25);
+
+ expect(internals.mouseX).toBe(75);
+ expect(internals.mouseY).toBe(25);
+ expect(internals.mouseVelX).toBe(25);
+ expect(internals.mouseVelY).toBe(-25);
+
+ internals.updateScreensaverPhysics(blob, 0.016, 0);
+
+ expect(blob.mouseDistance).toBeCloseTo(Math.sqrt((30 - 75) ** 2 + (50 - 25) ** 2));
+ });
+
+ it('computes pointer velocity from the previous pointer anchor', () => {
+ const physics = new BlobPhysics(0);
+ const internals = physics as unknown as {
+ lastMouseX: number;
+ lastMouseY: number;
+ mouseVelX: number;
+ mouseVelY: number;
+ };
+
+ physics.updateMousePosition(75, 25);
+ physics.updateMousePosition(80, 20);
+
+ expect(internals.mouseVelX).toBe(5);
+ expect(internals.mouseVelY).toBe(-5);
+ expect(internals.lastMouseX).toBe(75);
+ expect(internals.lastMouseY).toBe(25);
+ });
+});
+
+
+
+
describe('SpatialHash', () => {
describe('constructor', () => {
it('should create with default cell size', () => {
diff --git a/tests/unit/device-motion.test.ts b/tests/unit/device-motion.test.ts
new file mode 100644
index 0000000..256b4fa
--- /dev/null
+++ b/tests/unit/device-motion.test.ts
@@ -0,0 +1,458 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ DeviceMotion,
+ getDeviceMotionCapabilityState,
+ isDeviceMotionPermissionRequired,
+} from '../../src/motion/DeviceMotion.js';
+
+type PermissionResponse = 'granted' | 'denied';
+
+interface MockMotionWindow extends Partial {
+ DeviceOrientationEvent?: { requestPermission?: () => Promise };
+}
+
+let now = 0;
+
+function createMotionEnvironment(options: {
+ secure?: boolean;
+ orientation?: boolean;
+ permission?: () => Promise;
+ reducedMotion?: boolean;
+ angle?: number;
+ legacyReducedMotionListener?: boolean;
+} = {}) {
+ const windowListeners = new Map>();
+ const documentListeners = new Map>();
+ const mqlListeners = new Set<() => void>();
+
+ const addWindowListener = vi.fn((type: string, listener: EventListenerOrEventListenerObject) => {
+ const listeners = windowListeners.get(type) ?? new Set();
+ listeners.add(listener);
+ windowListeners.set(type, listeners);
+ });
+ const removeWindowListener = vi.fn((type: string, listener: EventListenerOrEventListenerObject) => {
+ windowListeners.get(type)?.delete(listener);
+ });
+ const addDocumentListener = vi.fn((type: string, listener: EventListenerOrEventListenerObject) => {
+ const listeners = documentListeners.get(type) ?? new Set();
+ listeners.add(listener);
+ documentListeners.set(type, listeners);
+ });
+ const removeDocumentListener = vi.fn((type: string, listener: EventListenerOrEventListenerObject) => {
+ documentListeners.get(type)?.delete(listener);
+ });
+
+ const mql = {
+ matches: options.reducedMotion ?? false,
+ ...(options.legacyReducedMotionListener
+ ? {
+ addListener: vi.fn((listener: () => void) => {
+ mqlListeners.add(listener);
+ }),
+ removeListener: vi.fn((listener: () => void) => {
+ mqlListeners.delete(listener);
+ }),
+ }
+ : {
+ addEventListener: vi.fn((_type: string, listener: () => void) => {
+ mqlListeners.add(listener);
+ }),
+ removeEventListener: vi.fn((_type: string, listener: () => void) => {
+ mqlListeners.delete(listener);
+ }),
+ }),
+ };
+
+ const motionWindow: MockMotionWindow = {
+ isSecureContext: options.secure ?? true,
+ addEventListener: addWindowListener,
+ removeEventListener: removeWindowListener,
+ matchMedia: vi.fn(() => mql as unknown as MediaQueryList),
+ };
+ const motionDocument = {
+ hidden: false,
+ addEventListener: addDocumentListener,
+ removeEventListener: removeDocumentListener,
+ };
+
+ if (options.orientation ?? true) {
+ motionWindow.DeviceOrientationEvent = {};
+ if (options.permission) {
+ motionWindow.DeviceOrientationEvent.requestPermission = options.permission;
+ }
+ }
+
+ vi.stubGlobal('window', motionWindow);
+ vi.stubGlobal('document', motionDocument);
+ vi.stubGlobal('screen', {
+ orientation: {
+ angle: options.angle ?? 0,
+ },
+ });
+
+ const dispatchWindow = (type: string, event: unknown) => {
+ for (const listener of windowListeners.get(type) ?? []) {
+ if (typeof listener === 'function') {
+ listener(event as Event);
+ } else {
+ listener.handleEvent(event as Event);
+ }
+ }
+ };
+
+ return {
+ addDocumentListener,
+ addWindowListener,
+ dispatchDocument(type: string) {
+ for (const listener of documentListeners.get(type) ?? []) {
+ if (typeof listener === 'function') {
+ listener({ type } as Event);
+ } else {
+ listener.handleEvent({ type } as Event);
+ }
+ }
+ },
+ dispatchOrientation(beta: number, gamma: number, alpha: number | null = null) {
+ dispatchWindow('deviceorientation', { beta, gamma, alpha });
+ },
+ mql,
+ motionDocument,
+ motionWindow,
+ removeDocumentListener,
+ removeWindowListener,
+ dispatchReducedMotionChange() {
+ for (const listener of mqlListeners) {
+ listener();
+ }
+ },
+ };
+}
+
+beforeEach(() => {
+ now = 0;
+ vi.spyOn(performance, 'now').mockImplementation(() => now);
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+});
+
+describe('DeviceMotion', () => {
+ it('reports capability and permission requirement without creating a listener', () => {
+ const requestPermission = vi.fn().mockResolvedValue('granted' as const);
+ createMotionEnvironment({ permission: requestPermission });
+
+ expect(getDeviceMotionCapabilityState()).toBe('unknown');
+ expect(isDeviceMotionPermissionRequired()).toBe(true);
+ expect(requestPermission).not.toHaveBeenCalled();
+ });
+
+ it('reports insecure and unsupported capability states', () => {
+ createMotionEnvironment({ secure: false });
+ expect(getDeviceMotionCapabilityState()).toBe('insecure');
+
+ createMotionEnvironment({ orientation: false });
+ expect(getDeviceMotionCapabilityState()).toBe('unsupported');
+ expect(isDeviceMotionPermissionRequired()).toBe(false);
+ });
+
+ it('reports unsupported when initialized without a browser window', async () => {
+ const motion = new DeviceMotion(vi.fn());
+
+ await expect(motion.initialize()).resolves.toBe(false);
+
+ expect(motion.getPermissionState()).toBe('unsupported');
+ expect(motion.isActive()).toBe(false);
+ });
+
+ it('reports insecure contexts without starting listeners', async () => {
+ const env = createMotionEnvironment({ secure: false });
+ const motion = new DeviceMotion(vi.fn());
+
+ await expect(motion.initialize()).resolves.toBe(false);
+
+ expect(motion.getPermissionState()).toBe('insecure');
+ expect(env.addWindowListener).not.toHaveBeenCalled();
+ });
+
+ it('starts immediately when no permission API is required', async () => {
+ const env = createMotionEnvironment();
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 250,
+ });
+
+ await expect(motion.initialize()).resolves.toBe(true);
+ now = 300;
+ env.dispatchOrientation(22.5, -45);
+
+ expect(motion.getPermissionState()).toBe('granted');
+ expect(motion.isActive()).toBe(true);
+ expect(callback).toHaveBeenCalledWith({ x: -1, y: 0.5, z: 0 });
+ });
+
+ it('defers listener startup until explicit permission is granted', async () => {
+ const requestPermission = vi.fn().mockResolvedValue('granted' as const);
+ const env = createMotionEnvironment({ permission: requestPermission });
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 250,
+ });
+
+ await expect(motion.initialize()).resolves.toBe(false);
+
+ expect(motion.getPermissionState()).toBe('prompt');
+ expect(env.addWindowListener).not.toHaveBeenCalled();
+
+ await expect(motion.requestPermission()).resolves.toBe(true);
+ now = 300;
+ env.dispatchOrientation(45, 0);
+
+ expect(requestPermission).toHaveBeenCalledOnce();
+ expect(motion.getPermissionState()).toBe('granted');
+ expect(callback).toHaveBeenCalledWith({ x: 0, y: 1, z: 0 });
+ });
+
+ it('calls the permission API with DeviceOrientationEvent as receiver', async () => {
+ let receiver: unknown;
+ const requestPermission = vi.fn(function (this: unknown) {
+ receiver = this;
+ return Promise.resolve('granted' as const);
+ });
+ const env = createMotionEnvironment({ permission: requestPermission });
+ const motion = new DeviceMotion(vi.fn());
+
+ await expect(motion.requestPermission()).resolves.toBe(true);
+
+ expect(receiver).toBe(env.motionWindow.DeviceOrientationEvent);
+ });
+
+ it('does not restart listeners after cleanup resolves an in-flight permission request', async () => {
+ let resolvePermission: (value: PermissionResponse) => void = () => {};
+ const permission = new Promise((resolve) => {
+ resolvePermission = resolve;
+ });
+ const env = createMotionEnvironment({ permission: () => permission });
+ const motion = new DeviceMotion(vi.fn());
+
+ const request = motion.requestPermission();
+ motion.cleanup();
+ resolvePermission('granted');
+
+ await expect(request).resolves.toBe(false);
+ expect(env.addWindowListener).not.toHaveBeenCalled();
+ expect(motion.isActive()).toBe(false);
+ });
+
+ it('does not start listeners when reduced motion is enabled during a permission request', async () => {
+ let resolvePermission: (value: PermissionResponse) => void = () => {};
+ const permission = new Promise((resolve) => {
+ resolvePermission = resolve;
+ });
+ const env = createMotionEnvironment({ permission: () => permission });
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback);
+
+ const request = motion.requestPermission();
+ env.mql.matches = true;
+ env.dispatchReducedMotionChange();
+ resolvePermission('granted');
+
+ await expect(request).resolves.toBe(false);
+ expect(motion.isActive()).toBe(false);
+ expect(env.addWindowListener).not.toHaveBeenCalled();
+ expect(callback).toHaveBeenLastCalledWith({ x: 0, y: 0, z: 0 });
+
+ env.mql.matches = false;
+ env.dispatchReducedMotionChange();
+
+ expect(motion.getPermissionState()).toBe('granted');
+ expect(motion.isActive()).toBe(true);
+ expect(env.addWindowListener).toHaveBeenCalledWith('deviceorientation', expect.any(Function), {
+ passive: true,
+ });
+ });
+
+ it('calibrates against caller-requested samples', async () => {
+ const env = createMotionEnvironment();
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 0,
+ });
+
+ await motion.initialize();
+ motion.calibrate(1);
+
+ now = 10;
+ env.dispatchOrientation(10, 20);
+ now = 20;
+ env.dispatchOrientation(20, 30);
+
+ expect(callback).toHaveBeenCalledOnce();
+ expect(callback).toHaveBeenCalledWith({
+ x: (30 - 20) / 45,
+ y: (20 - 10) / 45,
+ z: 0,
+ });
+ });
+
+ it('does not re-arm warmup after calibration completes', async () => {
+ const env = createMotionEnvironment();
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 250,
+ });
+
+ await motion.initialize();
+ now = 300;
+ motion.calibrate(1);
+
+ env.dispatchOrientation(10, 20);
+ now = 301;
+ env.dispatchOrientation(20, 30);
+
+ expect(callback).toHaveBeenCalledOnce();
+ expect(callback).toHaveBeenCalledWith({
+ x: (30 - 20) / 45,
+ y: (20 - 10) / 45,
+ z: 0,
+ });
+ });
+
+ it('emits neutral motion when sensor events go idle', async () => {
+ vi.useFakeTimers();
+ const env = createMotionEnvironment();
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ idleResetMs: 100,
+ warmupMs: 0,
+ });
+
+ await motion.initialize();
+ now = 10;
+ env.dispatchOrientation(45, 0);
+ vi.advanceTimersByTime(99);
+
+ expect(callback).toHaveBeenCalledOnce();
+
+ vi.advanceTimersByTime(1);
+
+ expect(callback).toHaveBeenLastCalledWith({ x: 0, y: 0, z: 0 });
+ motion.cleanup();
+ });
+
+ it('neutralizes motion when the document is hidden', async () => {
+ const env = createMotionEnvironment();
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 0,
+ });
+
+ await motion.initialize();
+ now = 10;
+ env.dispatchOrientation(45, 0);
+ env.motionDocument.hidden = true;
+ env.dispatchDocument('visibilitychange');
+
+ expect(callback).toHaveBeenLastCalledWith({ x: 0, y: 0, z: 0 });
+ });
+
+ it('honors reduced motion as a hard disable', async () => {
+ const env = createMotionEnvironment({ reducedMotion: true });
+ const motion = new DeviceMotion(vi.fn());
+
+ await expect(motion.initialize()).resolves.toBe(false);
+ await expect(motion.requestPermission()).resolves.toBe(false);
+
+ expect(motion.getPermissionState()).toBe('denied');
+ expect(env.addWindowListener).not.toHaveBeenCalled();
+ });
+
+ it('neutralizes active motion when reduced motion is enabled', async () => {
+ const env = createMotionEnvironment();
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 0,
+ });
+
+ await expect(motion.initialize()).resolves.toBe(true);
+ now = 10;
+ env.dispatchOrientation(45, 0);
+ env.mql.matches = true;
+ env.dispatchReducedMotionChange();
+
+ expect(motion.isActive()).toBe(false);
+ expect(callback).toHaveBeenLastCalledWith({ x: 0, y: 0, z: 0 });
+ });
+
+ it('supports legacy reduced-motion media query listeners', async () => {
+ const env = createMotionEnvironment({ legacyReducedMotionListener: true });
+ const callback = vi.fn();
+ const motion = new DeviceMotion(callback, {
+ baselineAlpha: 0,
+ deadZone: 0,
+ warmupMs: 0,
+ });
+
+ await expect(motion.initialize()).resolves.toBe(true);
+ expect(env.mql.addListener).toHaveBeenCalledWith(expect.any(Function));
+
+ now = 10;
+ env.dispatchOrientation(45, 0);
+ env.mql.matches = true;
+ env.dispatchReducedMotionChange();
+
+ expect(motion.isActive()).toBe(false);
+ expect(callback).toHaveBeenLastCalledWith({ x: 0, y: 0, z: 0 });
+
+ motion.cleanup();
+ expect(env.mql.removeListener).toHaveBeenCalledWith(expect.any(Function));
+ });
+
+ it('restarts after reduced motion is disabled when no permission prompt is needed', async () => {
+ const env = createMotionEnvironment({ reducedMotion: true });
+ const motion = new DeviceMotion(vi.fn());
+
+ await expect(motion.initialize()).resolves.toBe(false);
+ env.mql.matches = false;
+ env.dispatchReducedMotionChange();
+
+ expect(motion.getPermissionState()).toBe('granted');
+ expect(motion.isActive()).toBe(true);
+ expect(env.addWindowListener).toHaveBeenCalledWith('deviceorientation', expect.any(Function), {
+ passive: true,
+ });
+ });
+
+ it('returns to prompt after reduced motion is disabled when permission is gated', async () => {
+ const requestPermission = vi.fn().mockResolvedValue('granted' as const);
+ const env = createMotionEnvironment({ permission: requestPermission, reducedMotion: true });
+ const motion = new DeviceMotion(vi.fn());
+
+ await expect(motion.initialize()).resolves.toBe(false);
+ env.mql.matches = false;
+ env.dispatchReducedMotionChange();
+
+ expect(motion.getPermissionState()).toBe('prompt');
+ expect(motion.isActive()).toBe(false);
+ expect(env.addWindowListener).not.toHaveBeenCalled();
+ expect(requestPermission).not.toHaveBeenCalled();
+ });
+});
diff --git a/tests/unit/interaction-field.test.ts b/tests/unit/interaction-field.test.ts
new file mode 100644
index 0000000..d17cb04
--- /dev/null
+++ b/tests/unit/interaction-field.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ clampFieldVector,
+ combineFieldVectors,
+ directionalBiasField,
+ pointAttractorField,
+ smoothDistanceFalloff,
+} from '../../src/core/InteractionField.js';
+
+const vectorMagnitude = ({ x, y }: { x: number; y: number }) =>
+ Math.sqrt(x * x + y * y);
+
+describe('InteractionField', () => {
+ it('clamps vectors without changing direction', () => {
+ const vector = clampFieldVector({ x: 3, y: 4 }, 2);
+
+ expect(vectorMagnitude(vector)).toBeCloseTo(2);
+ expect(vector.x / vector.y).toBeCloseTo(3 / 4);
+ });
+
+ it('turns zero-sized clamp bounds into a zero vector', () => {
+ expect(clampFieldVector({ x: 1, y: 1 }, 0)).toEqual({ x: 0, y: 0 });
+ expect(clampFieldVector({ x: 1, y: 1 }, -1)).toEqual({ x: 0, y: 0 });
+ });
+
+ it('combines fields under a maximum magnitude', () => {
+ const vector = combineFieldVectors(
+ [
+ { x: 0.8, y: 0 },
+ { x: 0.8, y: 0 },
+ ],
+ 1,
+ );
+
+ expect(vector).toEqual({ x: 1, y: 0 });
+ });
+
+ it('INVARIANT: combines empty and opposing fields to neutral', () => {
+ expect(combineFieldVectors([])).toEqual({ x: 0, y: 0 });
+ expect(
+ combineFieldVectors([
+ { x: 0.35, y: -0.2 },
+ { x: -0.35, y: 0.2 },
+ ]),
+ ).toEqual({ x: 0, y: 0 });
+ });
+
+ it('converts gravity-like input into a bounded directional bias', () => {
+ const vector = directionalBiasField({ x: 0.25, y: 1 }, 0.8, 0.5);
+
+ expect(vector.y).toBeGreaterThan(0);
+ expect(vectorMagnitude(vector)).toBeLessThanOrEqual(0.5);
+ });
+
+ it('INVARIANT: directional bias preserves direction when clamped', () => {
+ const vector = directionalBiasField({ x: 3, y: 4 }, 1, 1);
+
+ expect(vectorMagnitude(vector)).toBeCloseTo(1);
+ expect(vector.x / vector.y).toBeCloseTo(3 / 4);
+ });
+
+ it('uses smooth local falloff for point fields', () => {
+ const atCenter = smoothDistanceFalloff(-5, 50);
+ const near = smoothDistanceFalloff(10, 50);
+ const far = smoothDistanceFalloff(40, 50);
+ const outside = smoothDistanceFalloff(60, 50);
+
+ expect(atCenter).toBe(1);
+ expect(near).toBeGreaterThan(far);
+ expect(far).toBeGreaterThan(0);
+ expect(outside).toBe(0);
+ });
+
+ it('samples a soft pointer-style attraction toward the target', () => {
+ const near = pointAttractorField({
+ origin: { x: 40, y: 50 },
+ target: { x: 50, y: 50 },
+ radius: 30,
+ strength: 0.2,
+ });
+ const far = pointAttractorField({
+ origin: { x: 20, y: 50 },
+ target: { x: 50, y: 50 },
+ radius: 30,
+ strength: 0.2,
+ });
+
+ expect(near.x).toBeGreaterThan(0);
+ expect(Math.abs(near.y)).toBe(0);
+ expect(vectorMagnitude(near)).toBeGreaterThan(vectorMagnitude(far));
+ expect(far).toEqual({ x: 0, y: 0 });
+ });
+
+ it('INVARIANT: point fields stay bounded by strength and fall off with distance', () => {
+ const target = { x: 50, y: 50 };
+ const strength = 0.4;
+ const close = pointAttractorField({
+ origin: { x: 45, y: 50 },
+ target,
+ radius: 40,
+ strength,
+ });
+ const farther = pointAttractorField({
+ origin: { x: 30, y: 50 },
+ target,
+ radius: 40,
+ strength,
+ });
+
+ expect(vectorMagnitude(close)).toBeLessThanOrEqual(strength);
+ expect(vectorMagnitude(farther)).toBeLessThanOrEqual(strength);
+ expect(vectorMagnitude(close)).toBeGreaterThan(vectorMagnitude(farther));
+ });
+});
diff --git a/tests/unit/oneeuro.test.ts b/tests/unit/oneeuro.test.ts
index 587e294..2e52e57 100644
--- a/tests/unit/oneeuro.test.ts
+++ b/tests/unit/oneeuro.test.ts
@@ -50,4 +50,9 @@ describe('OneEuro', () => {
expect(() => f.filter(1, 100)).not.toThrow();
expect(Number.isFinite(f.filter(2, 100))).toBe(true);
});
+
+ it('rejects non-positive cutoff values', () => {
+ expect(() => new OneEuro({ minCutoff: 0, beta: 0, dCutoff: 1 })).toThrow(RangeError);
+ expect(() => new OneEuro({ minCutoff: 1, beta: 0, dCutoff: -1 })).toThrow(RangeError);
+ });
});
diff --git a/tests/unit/pointer-mapper.test.ts b/tests/unit/pointer-mapper.test.ts
new file mode 100644
index 0000000..283a1a1
--- /dev/null
+++ b/tests/unit/pointer-mapper.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { mapClientPointToPhysics } from '../../src/motion/PointerMapper.js';
+
+describe('mapClientPointToPhysics', () => {
+ const bounds = {
+ left: 10,
+ top: 20,
+ width: 200,
+ height: 100,
+ };
+
+ it('maps the center of a bounds rectangle into the center of physics space', () => {
+ expect(mapClientPointToPhysics(110, 70, bounds)).toEqual({ x: 50, y: 50 });
+ });
+
+ it('maps rectangle corners into the default 0..100 physics range', () => {
+ expect(mapClientPointToPhysics(10, 20, bounds)).toEqual({ x: 0, y: 0 });
+ expect(mapClientPointToPhysics(210, 120, bounds)).toEqual({ x: 100, y: 100 });
+ });
+
+ it('clamps points outside the rectangle', () => {
+ expect(mapClientPointToPhysics(-100, 200, bounds)).toEqual({ x: 0, y: 100 });
+ });
+
+ it('supports custom physics ranges', () => {
+ expect(mapClientPointToPhysics(110, 70, bounds, { min: -40, max: 140 })).toEqual({
+ x: 50,
+ y: 50,
+ });
+ expect(mapClientPointToPhysics(210, 120, bounds, { min: -40, max: 140 })).toEqual({
+ x: 140,
+ y: 140,
+ });
+ });
+
+ it('falls back to the center when bounds have no area', () => {
+ expect(mapClientPointToPhysics(100, 100, { ...bounds, width: 0 })).toEqual({
+ x: 50,
+ y: 50,
+ });
+ expect(
+ mapClientPointToPhysics(100, 100, { ...bounds, height: 0 }, { min: -40, max: 140 }),
+ ).toEqual({ x: 50, y: 50 });
+ });
+});
diff --git a/tests/unit/pointer-physics-controller.test.ts b/tests/unit/pointer-physics-controller.test.ts
new file mode 100644
index 0000000..100feb7
--- /dev/null
+++ b/tests/unit/pointer-physics-controller.test.ts
@@ -0,0 +1,322 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ createPointerPhysicsController,
+ detectPointerPhysicsCapability,
+ getLatestPointerEvent,
+ type PointerLifecycleEventName,
+ type PointerLikeEvent,
+} from '../../src/motion/PointerPhysicsController.js';
+
+type PointerTestEvent = Partial & { relatedTarget?: EventTarget | null };
+
+function createTarget() {
+ const listeners = new Map();
+ const addEventListener = vi.fn(
+ (
+ type: PointerLifecycleEventName,
+ listener: EventListener,
+ _options?: AddEventListenerOptions,
+ ) => {
+ listeners.set(type, listener);
+ },
+ );
+ const removeEventListener = vi.fn((type: PointerLifecycleEventName, listener: EventListener) => {
+ if (listeners.get(type) === listener) {
+ listeners.delete(type);
+ }
+ });
+
+ return {
+ addEventListener,
+ dispatch(type: PointerLifecycleEventName, event: PointerTestEvent = {}) {
+ listeners.get(type)?.(event as unknown as Event);
+ },
+ listeners,
+ removeEventListener,
+ };
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('getLatestPointerEvent', () => {
+ it('uses the newest coalesced event when present', () => {
+ const latest = { clientX: 30, clientY: 40 };
+ const event = {
+ clientX: 10,
+ clientY: 20,
+ getCoalescedEvents: () => [{ clientX: 20, clientY: 30 }, latest],
+ };
+
+ expect(getLatestPointerEvent(event)).toBe(latest);
+ });
+
+ it('falls back to the parent event without coalesced samples', () => {
+ const event = { clientX: 10, clientY: 20, getCoalescedEvents: () => [] };
+
+ expect(getLatestPointerEvent(event)).toBe(event);
+ });
+});
+
+describe('detectPointerPhysicsCapability', () => {
+ it('accepts pointer events as direct pointer IO support', () => {
+ expect(detectPointerPhysicsCapability({ PointerEvent: function PointerEvent() {} })).toBe(
+ true,
+ );
+ });
+
+ it('accepts touch points and pointer media queries', () => {
+ expect(detectPointerPhysicsCapability({ navigator: { maxTouchPoints: 1 } })).toBe(true);
+ expect(
+ detectPointerPhysicsCapability({
+ matchMedia: (query) => ({ matches: query.includes('pointer') }),
+ }),
+ ).toBe(true);
+ });
+
+ it('falls back to mouse IO and rejects environments without pointer input', () => {
+ expect(detectPointerPhysicsCapability({ MouseEvent: function MouseEvent() {} })).toBe(
+ true,
+ );
+ expect(detectPointerPhysicsCapability({})).toBe(false);
+ });
+});
+
+describe('createPointerPhysicsController', () => {
+ const bounds = {
+ left: 10,
+ top: 20,
+ width: 200,
+ height: 100,
+ };
+
+ it('registers pointermove when pointer events are supported', () => {
+ const target = createTarget();
+ const controller = createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: true,
+ requestFrame: vi.fn(),
+ cancelFrame: vi.fn(),
+ updatePosition: vi.fn(),
+ });
+
+ expect(controller.eventName).toBe('pointermove');
+ expect(controller.exitEventName).toBe('pointerout');
+ expect(controller.cancelEventName).toBe('pointercancel');
+ expect(target.addEventListener).toHaveBeenCalledWith(
+ 'pointermove',
+ expect.any(Function),
+ { passive: true },
+ );
+ expect(target.addEventListener).toHaveBeenCalledWith(
+ 'pointerout',
+ expect.any(Function),
+ { passive: true },
+ );
+ expect(target.addEventListener).toHaveBeenCalledWith('pointercancel', expect.any(Function));
+ expect(target.addEventListener).toHaveBeenCalledWith('blur', expect.any(Function));
+
+ controller.dispose();
+ });
+
+ it('falls back to mousemove when pointer events are unavailable', () => {
+ const target = createTarget();
+ const controller = createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: false,
+ requestFrame: vi.fn(),
+ cancelFrame: vi.fn(),
+ updatePosition: vi.fn(),
+ });
+
+ expect(controller.eventName).toBe('mousemove');
+ expect(controller.exitEventName).toBe('mouseout');
+ expect(controller.cancelEventName).toBeNull();
+ expect(target.addEventListener).toHaveBeenCalledWith(
+ 'mousemove',
+ expect.any(Function),
+ { passive: true },
+ );
+ expect(target.addEventListener).toHaveBeenCalledWith(
+ 'mouseout',
+ expect.any(Function),
+ { passive: true },
+ );
+
+ controller.dispose();
+ });
+
+ it('rAF-throttles pointer updates and maps the latest position', () => {
+ const target = createTarget();
+ const updatePosition = vi.fn();
+ const frameCallbacks: FrameRequestCallback[] = [];
+ const requestFrame = vi.fn((callback: FrameRequestCallback) => {
+ frameCallbacks.push(callback);
+ return frameCallbacks.length;
+ });
+
+ createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: true,
+ requestFrame,
+ cancelFrame: vi.fn(),
+ updatePosition,
+ });
+
+ target.dispatch('pointermove', { clientX: 60, clientY: 45 });
+ target.dispatch('pointermove', { clientX: 110, clientY: 70 });
+
+ expect(requestFrame).toHaveBeenCalledOnce();
+ expect(updatePosition).not.toHaveBeenCalled();
+
+ frameCallbacks[0](16);
+
+ expect(updatePosition).toHaveBeenCalledOnce();
+ expect(updatePosition).toHaveBeenCalledWith({ x: 50, y: 50 });
+ });
+
+ it('uses the latest coalesced pointer sample before flushing', () => {
+ const target = createTarget();
+ const updatePosition = vi.fn();
+ let frameCallback: FrameRequestCallback | undefined;
+
+ createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: true,
+ requestFrame(callback) {
+ frameCallback = callback;
+ return 1;
+ },
+ cancelFrame: vi.fn(),
+ updatePosition,
+ });
+
+ target.dispatch('pointermove', {
+ clientX: 0,
+ clientY: 0,
+ getCoalescedEvents: () => [
+ { clientX: 60, clientY: 45 },
+ { clientX: 210, clientY: 120 },
+ ],
+ });
+ frameCallback?.(16);
+
+ expect(updatePosition).toHaveBeenCalledWith({ x: 100, y: 100 });
+ });
+
+ it('resets stale pointer position when pointer IO leaves the viewport', () => {
+ const target = createTarget();
+ const cancelFrame = vi.fn();
+ const updatePosition = vi.fn();
+ const controller = createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ range: { min: -1, max: 1 },
+ supportsPointerEvents: true,
+ requestFrame: vi.fn(() => 42),
+ cancelFrame,
+ updatePosition,
+ });
+
+ target.dispatch('pointermove', { clientX: 110, clientY: 70 });
+ target.dispatch('pointerout', {
+ relatedTarget: null,
+ });
+
+ expect(cancelFrame).toHaveBeenCalledWith(42);
+ expect(updatePosition).toHaveBeenCalledWith({ x: 0, y: 0 });
+ expect(controller.exitEventName).toBe('pointerout');
+ });
+
+ it('resets stale pointer position when browser pointer IO is canceled', () => {
+ const target = createTarget();
+ const cancelFrame = vi.fn();
+ const updatePosition = vi.fn();
+ createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ range: { min: -1, max: 1 },
+ supportsPointerEvents: true,
+ requestFrame: vi.fn(() => 42),
+ cancelFrame,
+ updatePosition,
+ });
+
+ target.dispatch('pointermove', { clientX: 110, clientY: 70 });
+ target.dispatch('pointercancel');
+
+ expect(cancelFrame).toHaveBeenCalledWith(42);
+ expect(updatePosition).toHaveBeenCalledWith({ x: 0, y: 0 });
+ });
+
+ it('ignores pointerout transitions that stay inside the document', () => {
+ const target = createTarget();
+ const updatePosition = vi.fn();
+ createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: true,
+ requestFrame: vi.fn(),
+ cancelFrame: vi.fn(),
+ updatePosition,
+ });
+
+ target.dispatch('pointerout', {
+ relatedTarget: {} as EventTarget,
+ });
+
+ expect(updatePosition).not.toHaveBeenCalled();
+ });
+
+ it('resets stale pointer position on window blur', () => {
+ const target = createTarget();
+ const updatePosition = vi.fn();
+ createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: false,
+ requestFrame: vi.fn(),
+ cancelFrame: vi.fn(),
+ updatePosition,
+ });
+
+ target.dispatch('blur');
+
+ expect(updatePosition).toHaveBeenCalledWith({ x: 50, y: 50 });
+ });
+
+ it('removes listeners and cancels pending work during cleanup', () => {
+ const target = createTarget();
+ const cancelFrame = vi.fn();
+ const updatePosition = vi.fn();
+ let frameCallback: FrameRequestCallback | undefined;
+ const controller = createPointerPhysicsController({
+ target,
+ getBounds: () => bounds,
+ supportsPointerEvents: true,
+ requestFrame(callback) {
+ frameCallback = callback;
+ return 42;
+ },
+ cancelFrame,
+ updatePosition,
+ });
+
+ target.dispatch('pointermove', { clientX: 110, clientY: 70 });
+ controller.dispose();
+ frameCallback?.(16);
+
+ expect(cancelFrame).toHaveBeenCalledWith(42);
+ expect(target.removeEventListener).toHaveBeenCalledWith('pointermove', expect.any(Function));
+ expect(target.removeEventListener).toHaveBeenCalledWith('pointerout', expect.any(Function));
+ expect(target.removeEventListener).toHaveBeenCalledWith('pointercancel', expect.any(Function));
+ expect(target.removeEventListener).toHaveBeenCalledWith('blur', expect.any(Function));
+ expect(updatePosition).not.toHaveBeenCalled();
+ });
+});
diff --git a/tests/unit/scroll-handler.test.ts b/tests/unit/scroll-handler.test.ts
index 925727d..cb96910 100644
--- a/tests/unit/scroll-handler.test.ts
+++ b/tests/unit/scroll-handler.test.ts
@@ -1,70 +1,109 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
import { ScrollHandler } from '../../src/motion/ScrollHandler.js';
-describe('ScrollHandler RAF backpressure', () => {
- let nextId = 1;
- let scheduled: Map;
- let cancelled: Set;
+describe('ScrollHandler', () => {
+ const frameCallbacks: FrameRequestCallback[] = [];
beforeEach(() => {
- nextId = 1;
- scheduled = new Map();
- cancelled = new Set();
- vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
- const id = nextId++;
- scheduled.set(id, cb);
- return id;
- });
- vi.stubGlobal('cancelAnimationFrame', (id: number) => {
- cancelled.add(id);
- scheduled.delete(id);
- });
+ frameCallbacks.length = 0;
+ vi.useFakeTimers();
+ vi.setSystemTime(1_000);
+ vi.stubGlobal(
+ 'requestAnimationFrame',
+ vi.fn((callback: FrameRequestCallback) => {
+ frameCallbacks.push(callback);
+ return frameCallbacks.length;
+ }),
+ );
+ vi.stubGlobal('cancelAnimationFrame', vi.fn());
});
afterEach(() => {
+ vi.useRealTimers();
vi.unstubAllGlobals();
+ vi.restoreAllMocks();
});
- it('cancels in-flight decay before respawning under rapid scroll', () => {
- const h = new ScrollHandler();
- const fakeWheel = (deltaY: number) =>
- ({ deltaY } as unknown as WheelEvent);
+ it('converts wheel movement into stickiness and pull forces', () => {
+ const handler = new ScrollHandler();
- for (let i = 0; i < 50; i++) {
- h.handleScroll(fakeWheel(100));
- }
+ handler.handleScroll({ deltaY: 240 } as WheelEvent);
- // Exactly one active RAF after 50 rapid handleScroll() calls.
- expect(scheduled.size).toBe(1);
- // And 49 prior RAFs were cancelled.
- expect(cancelled.size).toBe(49);
+ expect(handler.isActivelyScrolling()).toBe(true);
+ expect(handler.getScrollDirection()).toBe(1);
+ expect(handler.getTotalScrollDistance()).toBe(240);
+ expect(handler.getStickiness()).toBeGreaterThan(0);
+ expect(handler.getPullForces().length).toBeGreaterThan(0);
});
- it('clears rafId when decay completes', () => {
- const h = new ScrollHandler();
- const fakeWheel = (deltaY: number) =>
- ({ deltaY } as unknown as WheelEvent);
-
- // One scroll event kicks off decay.
- h.handleScroll(fakeWheel(50));
- expect(scheduled.size).toBe(1);
-
- // Drain all scheduled callbacks until decay self-terminates.
- // `decay` re-schedules itself only while stickiness > 0.01 or pullForces > 0.
- // With decayRate 0.92, this exits within a few hundred frames.
- let safety = 1000;
- while (scheduled.size > 0 && safety-- > 0) {
- const [[id, cb]] = scheduled.entries();
- scheduled.delete(id);
- cb(performance.now());
+ it('resets active scroll state after the quiet window', () => {
+ const handler = new ScrollHandler();
+
+ handler.handleScroll({ deltaY: 120 } as WheelEvent);
+ vi.setSystemTime(1_201);
+ vi.advanceTimersByTime(200);
+
+ expect(handler.isActivelyScrolling()).toBe(false);
+ expect(handler.getTotalScrollDistance()).toBe(0);
+ expect(handler.getPeakVelocity()).toBe(0);
+ });
+
+ it('keeps a single decay loop active across repeated scroll events', () => {
+ const handler = new ScrollHandler();
+
+ handler.handleScroll({ deltaY: 120 } as WheelEvent);
+ handler.handleScroll({ deltaY: 140 } as WheelEvent);
+
+ expect(requestAnimationFrame).toHaveBeenCalledOnce();
+
+ frameCallbacks[0](16);
+
+ expect(requestAnimationFrame).toHaveBeenCalledTimes(2);
+ });
+
+ it('honors caller-configured pull-force caps', () => {
+ const handler = new ScrollHandler({ maxForces: 2 });
+
+ for (let i = 0; i < 5; i++) {
+ vi.setSystemTime(1_000 + i * 16);
+ handler.handleScroll({ deltaY: 240 } as WheelEvent);
}
- expect(scheduled.size).toBe(0);
-
- // A subsequent scroll should kick off a fresh decay (no cancel needed
- // because the previous loop exited cleanly).
- const cancelledBefore = cancelled.size;
- h.handleScroll(fakeWheel(50));
- expect(cancelled.size).toBe(cancelledBefore);
- expect(scheduled.size).toBe(1);
+
+ expect(handler.getPullForces()).toHaveLength(2);
+ });
+
+ it('allows callers to disable retained pull forces', () => {
+ const handler = new ScrollHandler({ maxForces: 0 });
+
+ handler.handleScroll({ deltaY: 240 } as WheelEvent);
+
+ expect(handler.getStickiness()).toBeGreaterThan(0);
+ expect(handler.getPullForces()).toEqual([]);
+ });
+
+ it('cleans up scheduled decay and scroll-end work', () => {
+ const clearTimeoutSpy = vi.spyOn(globalThis, 'clearTimeout');
+ const handler = new ScrollHandler();
+
+ handler.handleScroll({ deltaY: 120 } as WheelEvent);
+ handler.dispose();
+ frameCallbacks[0](16);
+
+ expect(cancelAnimationFrame).toHaveBeenCalledWith(1);
+ expect(clearTimeoutSpy).toHaveBeenCalled();
+ expect(handler.getStickiness()).toBe(0);
+ expect(handler.isActivelyScrolling()).toBe(false);
+ expect(handler.getPullForces()).toEqual([]);
+ });
+
+ it('ignores scroll events after disposal', () => {
+ const handler = new ScrollHandler();
+
+ handler.dispose();
+ handler.handleScroll({ deltaY: 120 } as WheelEvent);
+
+ expect(handler.getStickiness()).toBe(0);
+ expect(requestAnimationFrame).not.toHaveBeenCalled();
});
});
diff --git a/tests/unit/theme-presets.test.ts b/tests/unit/theme-presets.test.ts
new file mode 100644
index 0000000..63b21cd
--- /dev/null
+++ b/tests/unit/theme-presets.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ THEME_PRESETS,
+ type ThemePresetName,
+} from '../../src/core/theme-presets.js';
+import { THEME_PRESET_COLORS } from '../../src/core/theme-colors.js';
+import {
+ THEME_PRESET_COLORS as SCHEMA_THEME_PRESET_COLORS,
+ THEME_PRESETS as SCHEMA_THEME_PRESETS,
+} from '../../src/core/schema.js';
+
+describe('theme presets', () => {
+ it('keeps lightweight color presets aligned with full theme presets', () => {
+ const names = Object.keys(THEME_PRESETS) as ThemePresetName[];
+
+ expect(Object.keys(THEME_PRESET_COLORS).sort()).toEqual([...names].sort());
+
+ for (const name of names) {
+ expect(THEME_PRESET_COLORS[name]).toEqual(
+ THEME_PRESETS[name].colors.map((color) => compactRgba(color.color)),
+ );
+ }
+ });
+
+ it('preserves schema re-exports for the existing public surface', () => {
+ expect(SCHEMA_THEME_PRESETS).toBe(THEME_PRESETS);
+ expect(SCHEMA_THEME_PRESET_COLORS).toBe(THEME_PRESET_COLORS);
+ });
+});
+
+function compactRgba(color: string): string {
+ return color.replaceAll(' ', '').replace(',0.', ',.');
+}
diff --git a/vite.dev.config.ts b/vite.dev.config.ts
index 6256622..514c272 100644
--- a/vite.dev.config.ts
+++ b/vite.dev.config.ts
@@ -2,6 +2,9 @@ import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { resolve } from 'path';
+const devServerPort = Number(process.env.TINYVECTORS_VITE_PORT ?? 5175);
+const hmrPort = Number(process.env.TINYVECTORS_VITE_HMR_PORT ?? 24679);
+
export default defineConfig({
root: resolve(__dirname, 'dev'),
@@ -20,10 +23,10 @@ export default defineConfig({
},
server: {
- port: 5175,
- open: true,
+ port: devServerPort,
+ open: process.env.CI === 'true' ? false : true,
hmr: {
- port: 24679,
+ port: hmrPort,
},
},
});