Define TinyVectors field-based feel contract

[Jesssullivan]

Problem

The Phase A gel-physics rewrite made the background feel over-engineered: too coherent under input, too noisy/flashy in rendering, and then too still after coefficient tuning. TinyVectors needs a product-level feel contract before more physics changes.

TinyVectors is an expressive Svelte/SvelteKit background system, not a physics demo. Inputs should bias an already-pleasant ambient flow; they should not seize control of the blobs.

Linear: TIN-853

Feel Contract

• Pleasant by default: idle blobs always drift/breathe subtly, never freeze and never jitter.
• Inputs are bias fields: device gravity, pointer, and scroll influence the existing flow instead of replacing it.
• Gravity is a slow directional bias: tilt should make blobs lean/pool/drift, not behave like marbles falling.
• Pointer is local and soft: nearby blobs should react more than distant blobs, with no event capture by the visual layer.
• Scroll is transient: scroll should create a decaying impulse/stickiness, not permanent acceleration.
• Gel/fluid is visual language: use low-cost inertia, soft repulsion/attraction, and shape deformation rather than a heavyweight fluid simulation.
• App-safe by default: SSR-safe, reduced-motion aware, listener-clean, no layout jank, and small enough for in-house SvelteKit backgrounds.

Scope

• Keep PR Integrate motion, pointer, gel, and package validation #39 on the restored pre-Phase-A physics/rendering baseline plus the useful harness/lifecycle/package work.
• Add repo-local architecture docs for the feel contract and field model.
• Introduce a small internal field/force seam that can be tested without changing visible behavior first.
• Add behavior tests in tolerant terms: idle drift bounded, gravity directional bias, pointer locality, scroll impulse decay, listener lifecycle, and bundle budget.
• Only then add direct pointer/gravity fields incrementally behind the existing public flags/config.

Non-Goals

• Do not revive the Phase A XSPH/soft-wall/Gaussian rewrite as-is.
• Do not ship a coefficient-only tuning patch without a contract and harness coverage.
• Do not introduce a large physics dependency or heavy fluid solver.

[Jesssullivan]

Implementation slice pushed to PR #39 as a1011eb (docs(physics): define field-based feel contract).

Included:

• docs/physics-feel-contract.md as the repo-local source of truth.
• README link to the feel contract.
• Internal pure src/core/InteractionField.ts helpers for bounded directional and point fields.
• Unit coverage for vector clamping, field combination, gravity-style directional bias, smooth local falloff, and pointer-style attraction.

The helper is intentionally not wired into BlobPhysics yet, so restored demo/runtime feel remains unchanged.

[Jesssullivan]

Follow-up cleanup pushed to PR #39:

• 5ebf1dd aligns release/docs truth after the renderer restore: removes stale Phase A wording and restores --tv-blob-intensity as the documented/registered renderer-private custom property.
• 300fc58 replaces top-level wildcard re-exports with an explicit package-root export list, matching the curated /core and /motion surfaces and making tree-shaking/public surface review clearer.

Validation remains green locally: check, test (156), build, check:package, check:bundle-size (10.26 KiB gzip), and test:browser:motion.

[Jesssullivan]

Additional hardening pushed to PR #39 as becf93d (test(bundle): guard inert field helper from consumer bundle).

pnpm run check:bundle-size now inspects Rollup chunk module IDs and fails if internal future-work modules are pulled into the { TinyVectors } consumer bundle. Current guarded module: dist/core/InteractionField.js. This makes the “field helper is inert until explicitly wired” claim enforceable in local checks, Bazel bundle-size checks, and CI.

[Jesssullivan]

Truthing pass on PR #39 at becf93d:

• Thread-aware GitHub review read shows 0 unresolved active review threads; earlier flat Greptile comments are stale/resolved by later commits.
• GitHub Actions package validation is green on the latest head; Greptile’s latest review is still pending.
• The repo-managed Vite dev harness is serving from /Users/jess/git/tinyvectors at http://127.0.0.1:5175/ for live feel checks.
• InteractionField remains inert and is explicitly guarded out of the { TinyVectors } consumer bundle by check:bundle-size.

[Jesssullivan]

Implemented and pushed 93d20a7 fix(motion): neutralize stale device IO on PR #39.

What changed:

• DeviceOrientation now has an idle watchdog (idleResetMs, default 2000) that emits neutral motion when sensor events stop.
• Visibility changes to hidden also neutralize motion so stale gravity cannot keep steering the blobs.
• TinyVectors exposes deviceMotionIdleResetMs for host tuning and the dev harness supports ?motionIdleReset=.
• Pointer physics now has explicit pointer/touch/mouse capability detection before attaching listeners.
• Browser harness now verifies synthetic orientation, CDP orientation, idle reset to neutral, and listener lifecycle.

Validation on this head:

• pnpm run check
• pnpm run test (161 tests)
• pnpm run build
• pnpm run check:release-metadata
• pnpm run check:package
• pnpm run check:bundle-size (10.48 KiB gzip, 0.52 KiB target headroom)
• pnpm run test:browser:motion
• 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

[Jesssullivan]

Implemented and pushed 176d666 fix(pointer): reset stale pointer IO on PR #39.

What changed:

• Pointer controller now listens for pointerout/mouseout and blur in addition to pointer movement.
• If pointer IO leaves the viewport or the window blurs, pending pointer rAF work is canceled and the sampled pointer position resets to the physics center.
• Internal transitions with a relatedTarget are ignored, so normal document movement does not falsely reset.
• Browser harness now asserts pointer move, pointer exit, and blur listeners are attached and fully cleaned up when pointer physics is toggled off.

Validation for this slice:

• pnpm vitest run tests/unit/pointer-physics-controller.test.ts (13 tests)
• pnpm run check
• pnpm run test (164 tests)
• pnpm run build
• pnpm run check:package
• pnpm run check:bundle-size (10.60 KiB gzip, 0.40 KiB target headroom)
• pnpm run check:release-metadata
• pnpm run test:browser:motion
• pnpm run check:package-consumer
• nix develop . --command bazel build //:pkg //:package_consumer_check //:bundle_size_check //:typecheck //:test --verbose_failures

[Jesssullivan]

Implemented and pushed b35e989 feat(motion): expose device motion status on PR #39.

What changed:

• TinyVectors handle now exposes getDeviceMotionStatus().
• Status reports enabled, supported, requiresPermission, permissionState, and active.
• Dev harness exposes the status for browser probes.
• Browser probe now asserts Chrome reports enabled/supported/granted/active for auto-started DeviceOrientation.
• Svelte package types export TinyVectorsDeviceMotionStatus; package consumer type check covers it.

Validation on this head before push:

• pnpm run check
• pnpm run test (164 tests)
• pnpm run build
• pnpm run check:release-metadata
• pnpm run check:package
• pnpm run check:bundle-size (10.72 KiB gzip, 0.28 KiB target headroom)
• pnpm run test:browser:motion
• 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

[Jesssullivan]

Pushed 9357969 refactor(motion): share device capability checks to PR #39.\n\nWhat changed:\n- Moved DeviceOrientation capability and permission detection into shared DeviceMotion helpers.\n- TinyVectors status reporting now uses the same checks as the runtime listener setup.\n- Added unit coverage for capability and permission detection without creating a listener.\n\nValidation on this head:\n- pnpm run check\n- pnpm run test (166 tests)\n- pnpm run build\n- pnpm run check:release-metadata\n- pnpm run check:package\n- pnpm run check:bundle-size (10.71 KiB gzip, 0.29 KiB target headroom)\n- pnpm run test:browser:motion\n- nix develop . --command bazel build //:pkg //:package_consumer_check //:bundle_size_check //:typecheck //:test --verbose_failures\n- pnpm run check:package-consumer\n- npm pack --dry-run ./bazel-bin/pkg\n- npm publish --dry-run --ignore-scripts --access public ./bazel-bin/pkg

[Jesssullivan]

Pushed d0a0ffd fix(physics): remove smoothing order bias to PR #39.\n\nWhat changed:\n- smoothControlPoints() now reads all neighboring radii from a pre-pass snapshot instead of mutating and re-reading the same ring during traversal.\n- The fallback smoothing pass no longer depends on which control point happens to be index 0.\n- Added a rotation-equivariance regression test so a rotated blob produces the same rotated result.\n\nValidation on this head:\n- pnpm vitest run tests/unit/core.test.ts (50 tests)\n- pnpm run check\n- pnpm run test (167 tests)\n- pnpm run build\n- pnpm run check:release-metadata\n- pnpm run check:package\n- pnpm run check:bundle-size (10.70 KiB gzip, 0.30 KiB target headroom)\n- pnpm run test:browser:motion\n- nix develop . --command bazel build //:pkg //:package_consumer_check //:bundle_size_check //:typecheck //:test --verbose_failures\n- pnpm run check:package-consumer\n- npm pack --dry-run ./bazel-bin/pkg\n- npm publish --dry-run --ignore-scripts --access public ./bazel-bin/pkg

[Jesssullivan]

Field contract test follow-up pushed: fe958b4 test(field): harden interaction invariants.

Added pure InteractionField invariants for neutral field combination, clamped directional bias preserving direction, and bounded point falloff. This strengthens the future gravity/pointer/scroll field contract without importing the helper into runtime physics or changing the restored demo feel.

Validation refreshed locally: pnpm run test (176 tests), pnpm run test:pbt, and pnpm run check.