@liquiddom/react 0.2.0-rc.0 → 0.3.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @liquiddom/react
 
+## 0.3.0-alpha.1
+
+### Minor Changes
+
+- 3bf4a9e: A stopped instance is reported. The new option `onError(err)` is called once when an instance stops for good (a frame that throws, a failed grid allocation for a growth or the first area hint, a failed Canvas2D rebuild after a lost WebGPU device), after its `console.error`; it is never called for a `create()` rejection, a fallback or after `destroy()`. The React and Vue providers (and the Vue plugin) now destroy a stopped instance and expose the reason through the new `useLiquidError()` (Vue also exports `LiquidErrorKey`); a `create()` rejection sets it too, and `config.onError` is still called. `<LiquidElement drag={false}>` and `useLiquidRef({ drag: false })` pass the drag opt-out to `observe()`. An app that observes its elements after `create()` (every adapter app, or `autoObserve: false`) now gets the same grid resolution as `autoObserve`: the first observed elements set the area hint once. A Vue example joins the React one, and both are smoke-tested from the published packages.
+- 1a68179: **liquiddom 0.3 (alpha): the soft-body engine is retired and replaced by an MLS-MPM fluid engine.** This first alpha ships the liquid _at rest_: each observed element is drawn as crisp liquid behind its real DOM text, with reduced motion and print handled. Splash, shake and the pointer field arrive in the next alpha. This is a breaking release; 0.2 code does not run unchanged. The 0.2 engine is preserved at the git tag `softbody-final`.
+
+  ### Old → new
+
+  | 0.2                                                                                                                                          | 0.3                                                                                                                                                                     |
+  | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | option `capacity`                                                                                                                            | `maxElements` (fixed; `observe()` beyond it throws `RangeError`)                                                                                                        |
+  | option `physics` (`LiquidPhysicsConfig`)                                                                                                     | `material: { viscosity, cohesion, recovery }`                                                                                                                           |
+  | export `presets` (goo/jelly/firm)                                                                                                            | removed; material presets `water`/`honey`/`jelly` arrive in the next alpha                                                                                              |
+  | options `colorDefault`, `colorHover`, `colorSource`, `theme`, `refraction`, `preserveBackgrounds`, `snapDurationMs`, `canvasZIndex`, `maxDt` | removed; `create()` throws a `TypeError` naming the replacement                                                                                                         |
+  | `observe(el, liquidType)`                                                                                                                    | `observe(el, { viscosity?, recovery? })`                                                                                                                                |
+  | `grow()`, `tween()`, `getBuffer()`, `spawnDroplet()`, `despawnDroplet()`, `setBackgroundTexture()`                                           | removed                                                                                                                                                                 |
+  | `impulse()`                                                                                                                                  | removed; `splash(el, opts)` arrives in the next alpha                                                                                                                   |
+  | `setPhysicsConfig()`, `getPhysicsConfig()`, `validatePhysicsConfig`                                                                          | removed; `setMaterial()` / `getMaterial()` arrive in the next alpha; `validateMaterial` (@internal)                                                                     |
+  | `refreshTheme()`, `refreshShadow()`                                                                                                          | `refresh(el)`                                                                                                                                                           |
+  | instance property `capacity`                                                                                                                 | `elementCapacity`, plus the new `particleCapacity`                                                                                                                      |
+  | `isReducedMotion`, `isScrolling`, `pointerActive`, `pointerX`, `pointerY`, `preserveBackgrounds`, `isScrollSnapping`                         | removed                                                                                                                                                                 |
+  | `LiquidInstancePanicDetail`, the `liquiddom:instance-panic` event, `SpawnDropletOptions`                                                     | removed (WASM init is single-flight; there is nothing to recover from)                                                                                                  |
+  | React/Vue `useLiquidRef({ liquidType })`, `<LiquidElement liquidType>`                                                                       | `useLiquidRef({ viscosity?, recovery? })`, `<LiquidElement viscosity recovery>` (type names `UseLiquidRefOptions` / `LiquidElementProps` are kept, their shape changed) |
+
+  ### `SplashOptions` changed shape
+
+  In 0.2, `SplashOptions` was `{ threshold, count, jitter?, speedScale?, lifetimeMs?, radius? }` and configured droplet spawning inside `impulse()`. That type is gone in this alpha. The next alpha adds a **different** `SplashOptions`, `{ strength?: number /* 0–2, default 1 */, at?: { x: number; y: number } /* client px */ }`, for `instance.splash(el, opts)`. Code that imports `SplashOptions` must be rewritten, not just recompiled.
+
+  ### Known regression: colours no longer auto-refresh
+
+  0.2 watched every observed element with a MutationObserver and re-read its background colour and box-shadow on `style`/`class` changes. 0.3 snapshots `background-color` and `color` once at `observe()`. Until the extended MutationObserver lands (slice 4), call `instance.refresh(el)` after you change an element's colours (theme switch, class toggle, inline style).
+
+  ### Other behaviour changes
+
+  - `LiquidDOM.create()` rejects with `LiquidWasmLoadError` when the WASM fails to load. The silent mock mode is gone.
+  - Observed elements get `class="liquid-element"` (and `data-liquid-stack` when they need stacking). One `<style id="liquiddom-styles">` is injected per document. `unobserve()` restores the element exactly. Borders and box-shadows of observed elements are not drawn.
+  - The canvas is `aria-hidden="true"`, sits below the observed elements (focus rings stay visible), and is hidden in print and forced-colors.
+  - `renderer: 'auto'` uses Canvas2D until the WebGPU fluid renderer lands. `renderer: 'webgpu'` initialises WebGPU but draws nothing yet (one `console.warn`).
+  - `gravity` is accepted and validated but has no effect yet.
+  - `pause()` is no longer undone when a hidden tab becomes visible again.
+
 ## 0.2.0-rc.0
 
 ### Minor Changes
@@ -7,12 +49,14 @@
 Initial public release. React 18+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom).
 
 **Exports:**
+
 - `<LiquidProvider config?>` — owns a `LiquidDOMInstance` via React Context
 - `useLiquid()` — read the instance (returns `null` before init / outside provider)
 - `useLiquidRef<T>(opts?)` — callback ref that auto-observes/unobserves
 - `<LiquidElement as? liquidType? ...rest>` — drop-in tag wrapping `useLiquidRef`
 
 **Behavior:**
+
 - Strict-mode safe (idempotent observe — React 18 double-mount in dev does not double-register)
 - SSR-safe (provider effect gated on `typeof window`)
 - `liquiddom` is a peer dependency (single WASM instance shared across the app)

package/README.md

@@ -1,96 +1,73 @@
 # @liquiddom/react
 
-React 18+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom) — WASM-driven soft-body physics on real DOM elements.
+React 18+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom): WASM-driven fluid dynamics on real DOM elements.
 
 ## Install
 
 ```bash
-npm install liquiddom @liquiddom/react react react-dom
+npm install liquiddom@alpha @liquiddom/react@alpha
 ```
 
-`liquiddom` is a peer dependency so a single WASM instance is shared across your app.
-
 ## Quickstart
 
 ```tsx
 import { LiquidProvider, LiquidElement } from "@liquiddom/react";
 
-export default function App() {
+export function App() {
   return (
-    <LiquidProvider config={{ capacity: 16, theme: { fusionRadius: 50 } }}>
-      <LiquidElement as="button">Click me</LiquidElement>
-      <LiquidElement as="a" href="#">Also liquid</LiquidElement>
+    <LiquidProvider config={{ material: { viscosity: 0.6, cohesion: 0.85, recovery: 0.4 } }}>
+      <LiquidElement as="button" viscosity={0.3}>Splash</LiquidElement>
     </LiquidProvider>
   );
 }
 ```
 
-## Three usage patterns
+## API
 
-### 1. `<LiquidElement>` — drop-in tag
+| Export | Purpose |
+|---|---|
+| `<LiquidProvider config?>` | Owns one `LiquidDOMInstance`; `config` is read once on mount |
+| `LiquidContext` | The raw context (instance or `null`) |
+| `useLiquid()` | The instance, or `null` before init, outside a provider and after it stopped |
+| `useLiquidError()` | Why there is no instance: the stop's error or the `create()` rejection; `null` otherwise |
+| `useLiquidRef<T>({ viscosity?, recovery?, drag? }?)` | Callback ref that observes on attach and unobserves on detach; options are captured on first render |
+| `<LiquidElement as? viscosity? recovery? drag? …rest>` | Convenience tag around `useLiquidRef`; every other prop is forwarded |
 
-Easiest. Wraps `useLiquidRef` and observes on mount.
+StrictMode-safe (single-flight WASM init plus idempotent `observe`). SSR-safe (the provider effect only runs in the browser).
 
-```tsx
-<LiquidElement as="button" liquidType={4 /* Shake */}>
-  Shaky
-</LiquidElement>
-```
+## When the liquid stops
 
-### 2. `useLiquidRef` — ref on your own element
-
-When you need full control over the element (custom components, third-party libs).
+If the instance stops for good (a frame that throws, for example), the provider destroys it: the elements are restored, `useLiquid()` returns `null` and `useLiquidError()` returns the error. A `create()` that rejects (no WebGPU with `renderer: 'webgpu'`, a WASM load failure) sets the same error. There is no automatic retry; remount the provider (a new `key`) to try again. Your own `config.onError` is still called. Under `createRoot` (React 18's default, React 19's only root) a stop is one render; under the legacy `ReactDOM.render` root `useLiquid()` and `useLiquidError()` can both read `null` for one render.
 
 ```tsx
-import { useLiquidRef } from "@liquiddom/react";
-
-function Card() {
-  const ref = useLiquidRef<HTMLDivElement>({ liquidType: 3 /* Dragged */ });
-  return <div ref={ref} className="my-card">Drag me</div>;
+function Status() {
+  const error = useLiquidError();
+  return error ? <p role="alert">Liquid stopped: {String(error)}</p> : null;
 }
 ```
 
-### 3. `useLiquid` — imperative access
+`<LiquidElement drag={false}>` (or `useLiquidRef({ drag: false })`) opts an element out of every drag; like `viscosity`, it is read once.
+
+## Material
 
-For one-off actions like `impulse()`, `tween()`, `spawnDroplet()`.
+`config` is read once on mount, so changing `config.material` later does nothing. Change the material live through the instance, for example with one of the core's `presets` (`water`, `honey`, `jelly`):
 
 ```tsx
-import { useLiquid, useLiquidRef } from "@liquiddom/react";
+import { presets } from "liquiddom";
+import { useLiquid } from "@liquiddom/react";
 
-function Button() {
+function HoneyButton() {
   const liquid = useLiquid();
-  const ref = useLiquidRef<HTMLButtonElement>();
-
-  return (
-    <button
-      ref={ref}
-      onClick={() => liquid?.impulse(ref.current!, { magnitude: 20 })}
-    >
-      Splash me
-    </button>
-  );
+  return <button onClick={() => liquid?.setMaterial(presets.honey)}>Honey</button>;
 }
 ```
 
-## API
-
-| Export | Description |
-|--------|-------------|
-| `<LiquidProvider config?>` | Owns a `LiquidDOMInstance` via React Context. `config` is captured once on mount — re-renders don't re-create the instance. |
-| `useLiquid()` | Returns the active instance, or `null` before init / outside a provider. |
-| `useLiquidRef<T>(opts?)` | Callback ref that auto-observes on mount, unobserves on unmount. `opts.liquidType` captured at first attach. |
-| `<LiquidElement as? liquidType? ...rest>` | Convenience tag — internally uses `useLiquidRef`. Forwards all other props to the underlying element. |
-
-## Notes
-
-- **Strict-mode safe** — `useLiquidRef` observes idempotently, so React 18's double-mount in dev doesn't double-register.
-- **SSR-safe** — the provider effect is gated on `typeof window`, so server rendering is a no-op.
-- **Single instance per provider** — nested providers each spin up their own WASM instance. For most apps, one provider at the root is correct.
+`getMaterial()` returns the resolved material. A preset also works at create time: `<LiquidProvider config={{ material: presets.jelly }}>`.
 
-## Full options + imperative API
+## Migrating from 0.2
 
-All options and methods exposed via `config` and `useLiquid()` come straight from [`liquiddom`'s core API](https://www.npmjs.com/package/liquiddom).
+`useLiquidRef({ liquidType })` and `<LiquidElement liquidType>` are gone; use `{ viscosity?, recovery? }`. See the core package's changelog for the full old → new table.
 
 ## License
 
-[MIT](./LICENSE) © Dennis Schmock
+MIT

package/dist/index.d.ts

@@ -2,8 +2,8 @@
  * @liquiddom/react — React 18+ bindings.
  */
 import { type ReactNode, type RefCallback, type HTMLAttributes } from "react";
-import { type LiquidDOMInstance, type LiquidOptions } from "liquiddom";
-/** Context value: the live instance, or null before init / after destroy. */
+import { type ElementOptions, type LiquidDOMInstance, type LiquidOptions } from "liquiddom";
+/** Context value: the live instance, or null before init, after destroy and once it stopped (W85). */
 export declare const LiquidContext: import("react").Context<LiquidDOMInstance | null>;
 /** Provider props. `config` is read ONCE on mount; subsequent changes are ignored. */
 export interface LiquidProviderProps {
@@ -11,36 +11,37 @@ export interface LiquidProviderProps {
     children: ReactNode;
 }
 export declare function LiquidProvider({ config, children }: LiquidProviderProps): JSX.Element;
-/** Read the live instance from context. Null before init / outside a provider. */
+/** Read the live instance from context. Null before init, outside a provider and once it stopped. */
 export declare function useLiquid(): LiquidDOMInstance | null;
-export interface UseLiquidRefOptions {
-    liquidType?: number;
-}
 /**
- * Callback ref that auto-observes the attached element. Safe to use before
- * the provider's instance is ready — observation deferred via state-trigger
- * pattern (effect re-runs when `instance` becomes available).
- *
- * Strict-mode safe: cleanup unobserves, remount re-observes; `observe` is
- * idempotent (W14 invariant).
+ * W85 (D85-2): the error that left the provider without an instance: a stop's error (a frame that
+ * threw, a failed grid growth or rebuild; the provider has destroyed the instance) or the create()
+ * rejection. Null otherwise and outside a provider. No retry: remount the provider (a new `key`)
+ * to create a new instance.
+ */
+export declare function useLiquidError(): unknown;
+/** Element options (viscosity, recovery, drag), captured at first attach (D66-4). */
+export type UseLiquidRefOptions = ElementOptions;
+/**
+ * Callback ref that auto-observes the attached element. Safe before the
+ * provider's instance is ready (the effect re-runs when it arrives). Options
+ * are captured once, on first render (D66-4).
  *
- * Closure-capture: the effect cleanup captures `el` and `instance` at the
- * time the effect ran. A later `setEl(null)` does NOT change which element
- * the captured cleanup unobserves.
+ * Strict-mode safe: cleanup unobserves, remount re-observes; observe is idempotent.
  */
 export declare function useLiquidRef<T extends HTMLElement>(opts?: UseLiquidRefOptions): RefCallback<T>;
 export interface LiquidElementProps {
     as?: keyof JSX.IntrinsicElements;
-    liquidType?: number;
+    /** [0, 1]; captured at first attach. */
+    viscosity?: number;
+    /** Seconds in [0.2, 3]; captured at first attach. */
+    recovery?: number;
+    /** W85 (D85-3): `false` opts the element out of every drag (mouse, pen, touch); captured at first attach. */
+    drag?: boolean;
     children?: ReactNode;
 }
 /**
- * Convenience component: renders the chosen tag (default `div`) and auto-
- * observes it via `useLiquidRef`. All HTML attributes are forwarded via spread.
- *
- * Polymorphic typing is intentionally loose for v1 — props are typed as
- * `HTMLAttributes<HTMLElement>` so most common attributes typecheck across
- * tags. Tag-specific attributes (`type` on input, `disabled` on button) may
- * require a cast. Full polymorphic typing deferred to a follow-up ward.
+ * Renders the chosen tag (default `div`) and auto-observes it. `viscosity`,
+ * `recovery` and `drag` are consumed (not forwarded to the DOM); every other prop is spread.
  */
 export declare function LiquidElement(props: LiquidElementProps & HTMLAttributes<HTMLElement>): JSX.Element;

package/dist/index.js

@@ -4,20 +4,59 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import { createContext, useContext, useEffect, useRef, useState, } from "react";
 import { LiquidDOM, } from "liquiddom";
-/** Context value: the live instance, or null before init / after destroy. */
+/** Context value: the live instance, or null before init, after destroy and once it stopped (W85). */
 export const LiquidContext = createContext(null);
+/** W85 (D85-2, design resolution 10): why the provider has no instance; null otherwise. Private: read it with useLiquidError(). */
+const LiquidErrorContext = createContext(null);
+/**
+ * Kept identical to withOnError in packages/vue/src/index.ts.
+ * W85 (D85-2): `config` with the provider's handler chained in front of `config.onError`, which is
+ * still called, after it. An `onError` that is not a function is passed on unchanged, so create()
+ * rejects with core's TypeError (design resolution 9).
+ */
+function withOnError(config, own) {
+    const theirs = config?.onError;
+    if (theirs !== undefined && typeof theirs !== "function")
+        return { ...config };
+    const chained = theirs;
+    return {
+        ...config,
+        onError: (err) => {
+            own(err);
+            chained?.(err);
+        },
+    };
+}
 export function LiquidProvider({ config, children }) {
     const [instance, setInstance] = useState(null);
+    const [error, setError] = useState(null);
     const configRef = useRef(config);
     useEffect(() => {
         if (typeof window === "undefined")
             return; // SSR guard — never runs server-side
         let cancelled = false;
         let created = null;
-        LiquidDOM.create(configRef.current)
+        // W85 (D85-2): set by the instance's onError. A stop can arrive before create() resolves (design
+        // resolution 11); the instance is then destroyed on arrival.
+        let stopped = false;
+        // W85 (design resolution 2): synchronous, from inside core's onError, which runs last in the stop
+        // (design resolution 1). useLiquid() never hands out a stopped instance; React 18 batches a
+        // setState from a RAF or event callback.
+        const onStop = (err) => {
+            if (cancelled || stopped)
+                return;
+            stopped = true;
+            const inst = created;
+            created = null;
+            inst?.destroy();
+            setInstance(null);
+            setError(() => err); // an updater: the error itself may be a function
+        };
+        LiquidDOM.create(withOnError(configRef.current, onStop))
             .then((inst) => {
-            if (cancelled) {
-                // Provider unmounted (or strict-mode cleanup) before create resolved.
+            if (cancelled || stopped) {
+                // Provider unmounted (or strict-mode cleanup) before create resolved, or the instance
+                // stopped while create() still ran.
                 inst.destroy();
                 return;
             }
@@ -26,59 +65,76 @@ export function LiquidProvider({ config, children }) {
         })
             .catch((err) => {
             console.error("[liquiddom/react] LiquidProvider failed to create instance:", err);
+            // W85 (D85-2): no retry; a remount creates a new instance.
+            if (!cancelled)
+                setError(() => err);
         });
         return () => {
             cancelled = true;
             if (created)
                 created.destroy();
-            // No setInstance(null) on unmount — context is going away regardless,
-            // and post-unmount state updates generate noise in test output.
+            created = null;
+            // Ward-fix M1: the context must never hand out a destroyed instance
+            // ("null after destroy"), e.g. when React re-runs this effect on a kept
+            // component (Fast Refresh, strict-mode reconnects). React 18 ignores the
+            // update after a real unmount.
+            setInstance(null);
+            setError(null); // W85: a re-run effect starts without an error
         };
     }, []); // empty deps — config captured by ref, ignored after mount
-    return _jsx(LiquidContext.Provider, { value: instance, children: children });
+    return (_jsx(LiquidErrorContext.Provider, { value: error, children: _jsx(LiquidContext.Provider, { value: instance, children: children }) }));
 }
-/** Read the live instance from context. Null before init / outside a provider. */
+/** Read the live instance from context. Null before init, outside a provider and once it stopped. */
 export function useLiquid() {
     return useContext(LiquidContext);
 }
 /**
- * Callback ref that auto-observes the attached element. Safe to use before
- * the provider's instance is ready — observation deferred via state-trigger
- * pattern (effect re-runs when `instance` becomes available).
- *
- * Strict-mode safe: cleanup unobserves, remount re-observes; `observe` is
- * idempotent (W14 invariant).
+ * W85 (D85-2): the error that left the provider without an instance: a stop's error (a frame that
+ * threw, a failed grid growth or rebuild; the provider has destroyed the instance) or the create()
+ * rejection. Null otherwise and outside a provider. No retry: remount the provider (a new `key`)
+ * to create a new instance.
+ */
+export function useLiquidError() {
+    return useContext(LiquidErrorContext);
+}
+/** Kept identical to pickElementOptions in packages/vue/src/index.ts. W85 (D85-3, design resolution 8): every own key whose value is defined; none → undefined. */
+function pickElementOptions(opts) {
+    if (!opts)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(opts))
+        if (value !== undefined)
+            out[key] = value;
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/**
+ * Callback ref that auto-observes the attached element. Safe before the
+ * provider's instance is ready (the effect re-runs when it arrives). Options
+ * are captured once, on first render (D66-4).
  *
- * Closure-capture: the effect cleanup captures `el` and `instance` at the
- * time the effect ran. A later `setEl(null)` does NOT change which element
- * the captured cleanup unobserves.
+ * Strict-mode safe: cleanup unobserves, remount re-observes; observe is idempotent.
  */
 export function useLiquidRef(opts) {
     const instance = useLiquid();
     const [el, setEl] = useState(null);
-    const liquidType = opts?.liquidType;
+    const optsRef = useRef(pickElementOptions(opts));
     useEffect(() => {
         if (!el || !instance)
             return;
-        instance.observe(el, liquidType);
+        instance.observe(el, optsRef.current);
         return () => {
             instance.unobserve(el);
         };
-    }, [el, instance, liquidType]);
+    }, [el, instance]);
     return setEl;
 }
 /**
- * Convenience component: renders the chosen tag (default `div`) and auto-
- * observes it via `useLiquidRef`. All HTML attributes are forwarded via spread.
- *
- * Polymorphic typing is intentionally loose for v1 — props are typed as
- * `HTMLAttributes<HTMLElement>` so most common attributes typecheck across
- * tags. Tag-specific attributes (`type` on input, `disabled` on button) may
- * require a cast. Full polymorphic typing deferred to a follow-up ward.
+ * Renders the chosen tag (default `div`) and auto-observes it. `viscosity`,
+ * `recovery` and `drag` are consumed (not forwarded to the DOM); every other prop is spread.
  */
 export function LiquidElement(props) {
-    const { as, liquidType, children, ...rest } = props;
-    const ref = useLiquidRef({ liquidType });
+    const { as, viscosity, recovery, drag, children, ...rest } = props;
+    const ref = useLiquidRef({ viscosity, recovery, drag });
     const Tag = (as ?? "div");
     return (_jsx(Tag, { ref: ref, ...rest, children: children }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquiddom/react",
-  "version": "0.2.0-rc.0",
+  "version": "0.3.0-alpha.1",
   "description": "React bindings for liquiddom",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "liquiddom": "^0.2.0-rc.0",
+    "liquiddom": "^0.3.0-alpha.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "author": "Dennis Schmock",