react-theme-tide 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alawonn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# React Theme Tide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Change your site's theme with a water fill that rises from the bottom of the screen. It stops at 60% for one second while the waves keep moving, then fills the rest of the screen.
+
+What shows under the water is your real page in its new theme: text, backgrounds, borders and controls. It isn't a colored overlay. The reveal uses the browser's View Transitions API and a CSS mask, so it needs no screenshot library, no copy of your DOM and no React re-render on each frame.
+
+React Theme Tide doesn't store your theme. You keep your own theme state and storage, and the library animates around the function that applies it.
+
+> Status: first release (0.1). The API may still change before 1.0.
+
+## Install
+
+```bash
+npm install react-theme-tide
+```
+
+React 18 or newer is a peer dependency. There's no stylesheet to import. While a tide runs, the library adds a small `<style>` element to `<head>` and removes it when the tide ends.
+
+## Quick start
+
+Pass the function that changes your theme. It must update the DOM before it returns (or before its promise resolves), because the browser captures the new page right after it.
+
+```tsx
+"use client";
+import { useThemeTide } from "react-theme-tide";
+
+export function ThemeToggle() {
+  const tide = useThemeTide();
+  const toggle = () =>
+    tide.run(() => {
+      const dark = document.documentElement.classList.toggle("dark");
+      localStorage.setItem("theme", dark ? "dark" : "light");
+    });
+  return (
+    <button type="button" onClick={toggle} aria-label="Toggle theme">
+      Toggle theme
+    </button>
+  );
+}
+```
+
+Without React, call `themeTide` directly:
+
+```ts
+import { themeTide } from "react-theme-tide";
+
+themeTide(() => document.documentElement.classList.toggle("dark"));
+```
+
+## Wrap a theme setter you already have
+
+If your site already has a function that applies and saves the theme, pass it in unchanged:
+
+```tsx
+"use client";
+import { useThemeTide } from "react-theme-tide";
+import { setAppearance } from "@/lib/appearance"; // your existing setter
+
+export function AppearanceButtons() {
+  const tide = useThemeTide();
+  return (
+    <>
+      <button type="button" onClick={() => tide.run(() => setAppearance("light"))}>Light</button>
+      <button type="button" onClick={() => tide.run(() => setAppearance("dark"))}>Dark</button>
+    </>
+  );
+}
+```
+
+Your storage key, your pre-paint script and your other controls keep working as before. Every control can use its own `useThemeTide()`; they all see the same `running` state.
+
+### Theme held in React state
+
+React state updates are asynchronous, so wrap them in `flushSync`. That way the DOM has the new theme when the callback returns:
+
+```tsx
+import { flushSync } from "react-dom";
+
+tide.run(() => flushSync(() => setTheme("dark")));
+```
+
+This applies to theme libraries that keep state in React context, too.
+
+## Next.js App Router
+
+Use the hook in a Client Component (a file that starts with `"use client"`). Only the hook's module is marked `"use client"`. The rest of the package doesn't touch `window` or `document` when it's imported, so Server Components can import the defaults and helpers. On the server, `supportsThemeTide()` returns `false`.
+
+```tsx
+// app/theme-toggle.tsx
+"use client";
+import { useThemeTide } from "react-theme-tide";
+
+export function ThemeToggle() {
+  const { run, running } = useThemeTide();
+  return (
+    <button
+      type="button"
+      disabled={running}
+      onClick={() => run(() => document.documentElement.classList.toggle("dark"))}
+    >
+      Switch theme
+    </button>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx (a Server Component)
+import { ThemeToggle } from "./theme-toggle";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ThemeToggle />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+Apply the saved theme before paint the way you do now, for example with an inline script in `<head>`. The tide only runs when someone changes the theme, never on first load or during hydration.
+
+## Options
+
+All options are optional. Pass them to `useThemeTide(options)`, to `run(commit, options)` (which overrides the hook's options) or to `themeTide(commit, options)`.
+
+| Option | Default | Range | What it does |
+| --- | --- | --- | --- |
+| `riseDuration` | `900` | 0 to 10000 ms | Time to rise from the bottom edge to the hold level. |
+| `holdDuration` | `1000` | 0 to 10000 ms | Time the water stays at the hold level. The waves keep moving. |
+| `finishDuration` | `700` | 0 to 10000 ms | Time to rise from the hold level past the top edge. |
+| `holdLevel` | `0.6` | 0 to 1 | How full the screen is during the hold. `0.6` puts the mean waterline 40% down from the top. |
+| `waveAmplitude` | `12` | 0 to 80 px | Height of a crest above the mean waterline. `0` gives a flat line. |
+| `waveLength` | `240` | 40 to 4000 px | Distance between crests. |
+| `waveSpeed` | `1` | 0 to 5 | Crests that pass a fixed point each second. |
+| `respectReducedMotion` | `true` | boolean | Change the theme instantly when the user's system asks for reduced motion. |
+| `nonce` | none | string | Nonce for the temporary `<style>` element, for pages with a Content Security Policy. |
+
+A value outside its range, or of the wrong type, makes the call reject with a `RangeError` or `TypeError`. The theme still changes, instantly, so a bad option never breaks the toggle. To check options ahead of time, call `resolveThemeTideOptions(options)`, which throws the same errors.
+
+## How it behaves
+
+- **Coordinates.** The water is measured against the visible screen, not the document. It always starts at the bottom edge of the screen, however long the page is or however far it's scrolled. Scroll position and focus stay as they were.
+- **Both directions.** Light to dark and dark to light both fill upward.
+- **Completion.** At the end, the troughs pass above the top edge and the fill reaches past both sides, so none of the old theme is left showing.
+- **Your commit runs once.** Every call runs your function exactly once, whether the tide animates, falls back, finishes early or fails.
+- **Another change during a tide.** The running tide jumps to its end, then the new theme applies instantly. Changes always apply in the order they were made.
+- **Scrolling during a tide.** The water rushes to the top in about 0.2 s, with the waves still moving, and the page ends up where you scrolled. The old theme is a still snapshot, so it can't scroll along with the page.
+- **Resizing during a tide.** The tide ends right away, because the snapshot no longer fits the window.
+- **Input.** Keyboard input reaches the focused control during a tide. A mouse or touch press makes the water rush to the top, the same as scrolling. In Firefox the press also reaches the control under it. In Chromium it doesn't, because the browser sends pointer events to the root element during any View Transition, so the next press works as usual.
+- **Instant fallback.** The theme changes with no animation when the browser lacks View Transitions or CSS masks, when reduced motion applies, when the tab is hidden, when every duration is `0`, or when another View Transition is already running (in browsers that report `document.activeViewTransition`).
+- **Errors.** If your function throws or rejects, the returned promise rejects with that error. The animation and its temporary style are removed either way.
+- **Unmounting.** Unmounting a component that started a tide doesn't stop the tide. Nothing stays behind once it ends.
+
+The returned promise resolves to `{ animated: true }`, or to `{ animated: false, reason }`, where `reason` is one of `"reduced-motion"`, `"unsupported"`, `"hidden"`, `"zero-duration"`, `"busy"` or `"interrupted"`.
+
+## API
+
+```ts
+themeTide(commit: () => void | Promise<void>, options?: ThemeTideOptions): Promise<ThemeTideResult>
+useThemeTide(options?: ThemeTideOptions): { run, running, skip }
+skipThemeTide(): void              // jump a running tide to its end
+isThemeTideRunning(): boolean
+subscribeThemeTide(listener: () => void): () => void
+supportsThemeTide(): boolean       // false on the server
+resolveThemeTideOptions(options?): ResolvedThemeTideOptions
+themeTideDefaults, themeTideRanges
+```
+
+## Working with other View Transitions
+
+The tide animates the page's root snapshot (`::view-transition-new(root)`). If your page gives other elements their own `view-transition-name`, those elements cross-fade on their own during a tide and aren't covered by the water. Starting another View Transition while a tide runs ends the tide early; the theme still changes.
+
+## Browser support
+
+The animation needs `document.startViewTransition`, `Element.animate` and CSS `mask-image`. Other browsers get the instant fallback.
+
+Tested so far, through Playwright automation on Linux:
+
+- **Chromium 156:** animation checked frame by frame from screenshots, at 1280 × 800 and in Pixel 7 emulation (412 × 839, device pixel ratio 2.625).
+- **Firefox 157:** animation timing and mask geometry checked through computed styles, at 1280 × 800 and 390 × 844. Firefox screenshots taken through Playwright don't include the transition layer, so frames haven't been checked by eye in automation yet.
+- **Safari and WebKit:** not tested yet.
+
+Known limitation: on screens with a fractional device pixel ratio, Chromium sometimes leaves the top-right corner device pixel in the old theme during the last frames.
+
+## Demo
+
+```bash
+npm install
+npm run demo
+```
+
+Then open http://localhost:5179. The demo has light and dark controls, sliders for every option, long scrolling content and fixed elements.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { themeTide, skipThemeTide, isThemeTideRunning, subscribeThemeTide, supportsThemeTide, type ThemeTideCommit, type ThemeTideResult, type ThemeTideInstantReason, } from "./tide.js";
+export { resolveThemeTideOptions, themeTideDefaults, themeTideRanges, type ThemeTideOptions, type ResolvedThemeTideOptions, } from "./options.js";
+export { useThemeTide, type UseThemeTide } from "./use-theme-tide.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { themeTide, skipThemeTide, isThemeTideRunning, subscribeThemeTide, supportsThemeTide, } from "./tide.js";
+export { resolveThemeTideOptions, themeTideDefaults, themeTideRanges, } from "./options.js";
+export { useThemeTide } from "./use-theme-tide.js";

package/dist/options.d.ts

@@ -0,0 +1,38 @@
+export interface ThemeTideOptions {
+    /** Time for the water to rise from the bottom edge to the hold level, in ms. */
+    riseDuration?: number;
+    /** Time the mean waterline stays at the hold level, in ms. Waves keep moving. */
+    holdDuration?: number;
+    /** Time for the water to rise from the hold level past the top edge, in ms. */
+    finishDuration?: number;
+    /** How full the viewport is during the hold, from 0 (empty) to 1 (full). */
+    holdLevel?: number;
+    /** Height of a wave crest above the mean waterline, in CSS pixels. */
+    waveAmplitude?: number;
+    /** Distance between two crests, in CSS pixels. */
+    waveLength?: number;
+    /** Crests that pass a fixed point each second. */
+    waveSpeed?: number;
+    /** Change the theme instantly when the user prefers reduced motion. */
+    respectReducedMotion?: boolean;
+    /** Nonce for the temporary style element, for pages with a strict CSP. */
+    nonce?: string;
+}
+export interface ResolvedThemeTideOptions {
+    riseDuration: number;
+    holdDuration: number;
+    finishDuration: number;
+    holdLevel: number;
+    waveAmplitude: number;
+    waveLength: number;
+    waveSpeed: number;
+    respectReducedMotion: boolean;
+    nonce: string | undefined;
+}
+type NumericKey = Exclude<keyof ResolvedThemeTideOptions, "respectReducedMotion" | "nonce">;
+export declare const themeTideDefaults: Readonly<ResolvedThemeTideOptions>;
+export declare const themeTideRanges: Readonly<Record<NumericKey, readonly [min: number, max: number]>>;
+/** Fills in defaults and throws a RangeError or TypeError for bad values. */
+export declare function resolveThemeTideOptions(options?: ThemeTideOptions): ResolvedThemeTideOptions;
+export declare function totalDuration(options: ResolvedThemeTideOptions): number;
+export {};

package/dist/options.js

@@ -0,0 +1,53 @@
+export const themeTideDefaults = Object.freeze({
+    riseDuration: 900,
+    holdDuration: 1000,
+    finishDuration: 700,
+    holdLevel: 0.6,
+    waveAmplitude: 12,
+    waveLength: 240,
+    waveSpeed: 1,
+    respectReducedMotion: true,
+    nonce: undefined,
+});
+export const themeTideRanges = Object.freeze({
+    riseDuration: [0, 10000],
+    holdDuration: [0, 10000],
+    finishDuration: [0, 10000],
+    holdLevel: [0, 1],
+    waveAmplitude: [0, 80],
+    waveLength: [40, 4000],
+    waveSpeed: [0, 5],
+});
+/** Fills in defaults and throws a RangeError or TypeError for bad values. */
+export function resolveThemeTideOptions(options = {}) {
+    const resolved = { ...themeTideDefaults };
+    for (const key of Object.keys(themeTideRanges)) {
+        const value = options[key];
+        if (value === undefined)
+            continue;
+        const [min, max] = themeTideRanges[key];
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new TypeError(`themeTide: ${key} must be a finite number.`);
+        }
+        if (value < min || value > max) {
+            throw new RangeError(`themeTide: ${key} must be between ${min} and ${max}, got ${value}.`);
+        }
+        resolved[key] = value;
+    }
+    if (options.respectReducedMotion !== undefined) {
+        if (typeof options.respectReducedMotion !== "boolean") {
+            throw new TypeError("themeTide: respectReducedMotion must be a boolean.");
+        }
+        resolved.respectReducedMotion = options.respectReducedMotion;
+    }
+    if (options.nonce !== undefined) {
+        if (typeof options.nonce !== "string") {
+            throw new TypeError("themeTide: nonce must be a string.");
+        }
+        resolved.nonce = options.nonce;
+    }
+    return resolved;
+}
+export function totalDuration(options) {
+    return options.riseDuration + options.holdDuration + options.finishDuration;
+}

package/dist/tide.d.ts

@@ -0,0 +1,27 @@
+import { type ThemeTideOptions } from "./options.js";
+/** Applies the new theme to the DOM. Called exactly once per themeTide call. */
+export type ThemeTideCommit = () => void | Promise<void>;
+export type ThemeTideInstantReason = "reduced-motion" | "unsupported" | "hidden" | "zero-duration" | "busy" | "interrupted";
+export type ThemeTideResult = {
+    animated: true;
+} | {
+    animated: false;
+    reason: ThemeTideInstantReason;
+};
+/** True while a tide animation is on screen. */
+export declare function isThemeTideRunning(): boolean;
+/** Calls `listener` when a tide starts or ends. Returns an unsubscribe function. */
+export declare function subscribeThemeTide(listener: () => void): () => void;
+/** Jumps a running tide to its end. The theme commit still happens once. */
+export declare function skipThemeTide(): void;
+/** True when this browser can animate a tide. Always false on the server. */
+export declare function supportsThemeTide(): boolean;
+/**
+ * Runs `commit` to change the theme and reveals the new theme with a rising
+ * water fill. Falls back to an instant change when the browser can't animate
+ * it, the user prefers reduced motion, or another tide is running.
+ *
+ * `commit` must update the DOM before it returns or before its promise
+ * resolves. With React state, wrap the update in `flushSync`.
+ */
+export declare function themeTide(commit: ThemeTideCommit, options?: ThemeTideOptions): Promise<ThemeTideResult>;

package/dist/tide.js

@@ -0,0 +1,195 @@
+import { resolveThemeTideOptions, totalDuration, } from "./options.js";
+import { maskDeclarations, maskKeyframes, rushKeyframes, } from "./wave.js";
+const attribute = "data-theme-tide";
+const pseudo = "::view-transition-new(root)";
+/** How long the water takes to reach the top after a scroll or pointer press. */
+const rushDuration = 200;
+let active = null;
+// Commits run one after another, in call order, even when they are async.
+let commitChain = Promise.resolve();
+const listeners = new Set();
+function setActive(next) {
+    active = next;
+    for (const listener of listeners)
+        listener();
+}
+/** True while a tide animation is on screen. */
+export function isThemeTideRunning() {
+    return active !== null;
+}
+/** Calls `listener` when a tide starts or ends. Returns an unsubscribe function. */
+export function subscribeThemeTide(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** Jumps a running tide to its end. The theme commit still happens once. */
+export function skipThemeTide() {
+    active?.transition.skipTransition();
+}
+/** True when this browser can animate a tide. Always false on the server. */
+export function supportsThemeTide() {
+    return (typeof document !== "undefined" &&
+        typeof document.startViewTransition === "function" &&
+        typeof Element.prototype.animate === "function" &&
+        typeof CSS !== "undefined" &&
+        CSS.supports("mask-image", "linear-gradient(#000, #000)"));
+}
+function prefersReducedMotion() {
+    return (typeof matchMedia === "function" &&
+        matchMedia("(prefers-reduced-motion: reduce)").matches);
+}
+function once(commit) {
+    let result;
+    return () => {
+        if (!result) {
+            const run = commitChain.then(() => commit());
+            commitChain = run.catch(() => undefined);
+            result = run;
+        }
+        return result;
+    };
+}
+function instant(commit, reason) {
+    return commit().then(() => ({ animated: false, reason }));
+}
+/**
+ * Runs `commit` to change the theme and reveals the new theme with a rising
+ * water fill. Falls back to an instant change when the browser can't animate
+ * it, the user prefers reduced motion, or another tide is running.
+ *
+ * `commit` must update the DOM before it returns or before its promise
+ * resolves. With React state, wrap the update in `flushSync`.
+ */
+export function themeTide(commit, options) {
+    const run = once(commit);
+    let resolved;
+    try {
+        resolved = resolveThemeTideOptions(options);
+    }
+    catch (error) {
+        // A bad option never blocks the theme change.
+        return run().then(() => Promise.reject(error));
+    }
+    if (!supportsThemeTide())
+        return instant(run, "unsupported");
+    if (active) {
+        // A second change during a tide finishes the first one, then applies
+        // the new theme without animation once the first commit has run.
+        const previous = active.transition.updateCallbackDone.catch(() => undefined);
+        skipThemeTide();
+        return previous.then(() => instant(run, "interrupted"));
+    }
+    if (document.activeViewTransition)
+        return instant(run, "busy");
+    if (resolved.respectReducedMotion && prefersReducedMotion()) {
+        return instant(run, "reduced-motion");
+    }
+    if (document.visibilityState === "hidden")
+        return instant(run, "hidden");
+    if (totalDuration(resolved) === 0)
+        return instant(run, "zero-duration");
+    return animate(run, resolved);
+}
+function viewportSize() {
+    return { width: window.innerWidth, height: window.innerHeight };
+}
+/** Size of the new-page snapshot, which can differ from innerHeight on mobile. */
+function snapshotSize(fallback) {
+    const style = getComputedStyle(document.documentElement, pseudo);
+    const width = parseFloat(style.width);
+    const height = parseFloat(style.height);
+    return width > 0 && height > 0 ? { width, height } : fallback;
+}
+function rules(options, viewport) {
+    const root = `:root[${attribute}]`;
+    return [
+        `${root}::view-transition { pointer-events: none; }`,
+        `${root}::view-transition-old(root), ${root}${pseudo} { animation: none; mix-blend-mode: normal; }`,
+        `${root}${pseudo} { ${maskDeclarations(options, viewport)}; }`,
+    ].join("\n");
+}
+async function animate(run, options) {
+    const root = document.documentElement;
+    const style = document.createElement("style");
+    if (options.nonce)
+        style.nonce = options.nonce;
+    style.textContent = rules(options, viewportSize());
+    document.head.appendChild(style);
+    root.setAttribute(attribute, "");
+    let transition;
+    try {
+        transition = document.startViewTransition(run);
+    }
+    catch {
+        style.remove();
+        root.removeAttribute(attribute);
+        return instant(run, "unsupported");
+    }
+    setActive({ transition });
+    let animation;
+    let viewport = viewportSize();
+    let interrupted = false;
+    const interrupt = () => {
+        interrupted = true;
+        transition.skipTransition();
+    };
+    // The old page is a still snapshot, so it can't scroll. On a scroll or a
+    // pointer press the water rushes to the top in rushDuration instead.
+    // Chromium sends pointer events to the root element during a transition,
+    // so controls can't receive them until the tide ends.
+    const rush = () => {
+        if (interrupted || !animation)
+            return;
+        const from = Number(animation.currentTime ?? 0);
+        if (totalDuration(options) - from <= rushDuration)
+            return;
+        interrupted = true;
+        const next = root.animate(rushKeyframes(options, viewport, from, rushDuration), {
+            duration: rushDuration,
+            easing: "linear",
+            fill: "forwards",
+            pseudoElement: pseudo,
+        });
+        animation.cancel();
+        animation = next;
+    };
+    const ready = transition.ready.then(() => {
+        viewport = snapshotSize(viewport);
+        animation = root.animate(maskKeyframes(options, viewport), {
+            duration: totalDuration(options),
+            easing: "linear",
+            fill: "forwards",
+            pseudoElement: pseudo,
+        });
+        window.addEventListener("scroll", rush, { passive: true });
+        window.addEventListener("pointerdown", rush, { capture: true });
+        // A resize changes the snapshot's size, so end the tide right away.
+        window.addEventListener("resize", interrupt);
+    }, () => undefined);
+    let failure;
+    try {
+        await transition.updateCallbackDone;
+    }
+    catch (error) {
+        failure = { error };
+    }
+    await ready;
+    await transition.finished.catch(() => undefined);
+    // A skipped transition still calls its update callback; `run` keeps this
+    // safe if a browser ever doesn't.
+    if (!failure)
+        await run().catch((error) => (failure = { error }));
+    const completed = !interrupted && animation?.playState === "finished";
+    window.removeEventListener("scroll", rush);
+    window.removeEventListener("pointerdown", rush, { capture: true });
+    window.removeEventListener("resize", interrupt);
+    animation?.cancel();
+    style.remove();
+    root.removeAttribute(attribute);
+    setActive(null);
+    if (failure)
+        throw failure.error;
+    return completed ? { animated: true } : { animated: false, reason: "interrupted" };
+}

package/dist/use-theme-tide.d.ts

@@ -0,0 +1,16 @@
+import type { ThemeTideOptions } from "./options.js";
+import { type ThemeTideCommit, type ThemeTideResult } from "./tide.js";
+export interface UseThemeTide {
+    /** Runs a tide around `commit`. Per-call options override the hook's options. */
+    run: (commit: ThemeTideCommit, options?: ThemeTideOptions) => Promise<ThemeTideResult>;
+    /** True while any tide on the page is animating. */
+    running: boolean;
+    /** Jumps a running tide to its end. */
+    skip: () => void;
+}
+/**
+ * React access to themeTide. The hook keeps no theme state of its own: your
+ * commit callback decides the theme and where it's saved. Unmounting doesn't
+ * stop a tide that's already running, since the transition belongs to the page.
+ */
+export declare function useThemeTide(options?: ThemeTideOptions): UseThemeTide;

package/dist/use-theme-tide.js

@@ -0,0 +1,18 @@
+"use client";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { isThemeTideRunning, skipThemeTide, subscribeThemeTide, themeTide, } from "./tide.js";
+const serverRunning = () => false;
+/**
+ * React access to themeTide. The hook keeps no theme state of its own: your
+ * commit callback decides the theme and where it's saved. Unmounting doesn't
+ * stop a tide that's already running, since the transition belongs to the page.
+ */
+export function useThemeTide(options) {
+    const running = useSyncExternalStore(subscribeThemeTide, isThemeTideRunning, serverRunning);
+    const optionsRef = useRef(options);
+    useEffect(() => {
+        optionsRef.current = options;
+    });
+    const run = useCallback((commit, overrides) => themeTide(commit, { ...optionsRef.current, ...overrides }), []);
+    return { run, running, skip: skipThemeTide };
+}

package/dist/wave.d.ts

@@ -0,0 +1,24 @@
+import { type ResolvedThemeTideOptions } from "./options.js";
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface WaveTile {
+    /** A CSS url() holding an SVG tile filled below one wavelength of the wave. */
+    image: string;
+    width: number;
+    height: number;
+}
+export declare function waveTile(amplitude: number, length: number): WaveTile;
+/** Mean waterline, in pixels from the top, at `time` ms into the tide. */
+export declare function waterlineAt(time: number, options: ResolvedThemeTideOptions, viewportHeight: number): number;
+/** Horizontal offset of the wave tile at `time` ms. Grows without wrapping. */
+export declare function wavePhaseAt(time: number, options: ResolvedThemeTideOptions): number;
+/** Static mask properties. The starting position hides the whole new page. */
+export declare function maskDeclarations(options: ResolvedThemeTideOptions, viewport: Viewport): string;
+export declare function maskKeyframes(options: ResolvedThemeTideOptions, viewport: Viewport): Keyframe[];
+/**
+ * Keyframes that take the water from where it is at `from` ms to the end of
+ * the tide in `duration` ms. The waves keep their normal speed.
+ */
+export declare function rushKeyframes(options: ResolvedThemeTideOptions, viewport: Viewport, from: number, duration: number): Keyframe[];

package/dist/wave.js

@@ -0,0 +1,124 @@
+import { totalDuration } from "./options.js";
+// All geometry is in CSS pixels of the viewport, with y measured down from
+// the top edge. The waterline is the mean height of the wave; the wave phase
+// only moves the crests sideways, so the level can hold while the water moves.
+/** Keyframes per second. Positions between keyframes are interpolated linearly. */
+const sampleRate = 60;
+/** Points per wavelength in the SVG tile outline. */
+const tileSegments = 32;
+/**
+ * Transparent rows at the top and bottom of the tile. Chromium can wrap the
+ * tile vertically when it resamples at fractional device-pixel ratios; empty
+ * rows on both edges keep that from drawing a hairline above the crests.
+ */
+const tilePadding = 2;
+function tileHeight(amplitude) {
+    return 2 * amplitude + 2 * tilePadding;
+}
+export function waveTile(amplitude, length) {
+    const height = tileHeight(amplitude);
+    const middle = amplitude + tilePadding;
+    const bottom = height - tilePadding;
+    let d = `M0 ${bottom}`;
+    for (let i = 0; i <= tileSegments; i++) {
+        const x = (i * length) / tileSegments;
+        const y = middle - amplitude * Math.sin((2 * Math.PI * x) / length);
+        d += ` L${round(x)} ${round(y)}`;
+    }
+    d += ` L${length} ${bottom} Z`;
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${length}" height="${height}"><path d="${d}"/></svg>`;
+    return {
+        image: `url("data:image/svg+xml,${encodeURIComponent(svg)}")`,
+        width: length,
+        height,
+    };
+}
+function easeInOut(t) {
+    return -(Math.cos(Math.PI * t) - 1) / 2;
+}
+/** Mean waterline, in pixels from the top, at `time` ms into the tide. */
+export function waterlineAt(time, options, viewportHeight) {
+    const { riseDuration, holdDuration, finishDuration, waveAmplitude } = options;
+    // Starts with the whole tile below the bottom edge and ends with every
+    // trough above the top edge. The extra 3 px at the end keep the corners
+    // covered on screens with fractional device pixels.
+    const start = viewportHeight + waveAmplitude + tilePadding;
+    const hold = viewportHeight * (1 - options.holdLevel);
+    const end = -(waveAmplitude + 3);
+    if (time <= 0)
+        return start;
+    if (time < riseDuration) {
+        return start + (hold - start) * easeInOut(time / riseDuration);
+    }
+    if (time <= riseDuration + holdDuration)
+        return hold;
+    const finishTime = time - riseDuration - holdDuration;
+    if (finishTime >= finishDuration)
+        return end;
+    return hold + (end - hold) * easeInOut(finishTime / finishDuration);
+}
+/** Horizontal offset of the wave tile at `time` ms. Grows without wrapping. */
+export function wavePhaseAt(time, options) {
+    return (options.waveSpeed * options.waveLength * time) / 1000;
+}
+/** Height of the solid layer under the wave. Taller than any viewport position needs. */
+function bodyHeight(options, viewport) {
+    return 2 * viewport.height + 4 * options.waveAmplitude + 8;
+}
+function maskPosition(time, options, viewport) {
+    return positionFor(waterlineAt(time, options, viewport.height), wavePhaseAt(time, options), options.waveAmplitude);
+}
+function positionFor(line, phase, amplitude) {
+    // The solid layer starts one pixel above the bottom of the tile's filled
+    // area and spills one pixel past each side, so no seam shows at fractional
+    // device pixels.
+    return `${round(phase)}px ${round(line - amplitude - tilePadding)}px, -1px ${round(line + amplitude - 1)}px`;
+}
+/** Static mask properties. The starting position hides the whole new page. */
+export function maskDeclarations(options, viewport) {
+    const tile = waveTile(options.waveAmplitude, options.waveLength);
+    return [
+        `mask-image: ${tile.image}, linear-gradient(#000, #000)`,
+        "mask-repeat: repeat-x, no-repeat",
+        `mask-size: ${tile.width}px ${tile.height}px, calc(100% + 2px) ${bodyHeight(options, viewport)}px`,
+        `mask-position: ${maskPosition(0, options, viewport)}`,
+        "mask-mode: alpha",
+        "mask-clip: no-clip",
+    ].join("; ");
+}
+export function maskKeyframes(options, viewport) {
+    const duration = totalDuration(options);
+    const steps = Math.max(1, Math.ceil((duration / 1000) * sampleRate));
+    // Phase boundaries are sampled exactly so the hold starts and ends on time.
+    const times = new Set([
+        options.riseDuration,
+        options.riseDuration + options.holdDuration,
+    ]);
+    for (let i = 0; i <= steps; i++)
+        times.add((i / steps) * duration);
+    return [...times]
+        .sort((a, b) => a - b)
+        .map((time) => ({
+        offset: duration === 0 ? 0 : time / duration,
+        maskPosition: maskPosition(time, options, viewport),
+    }));
+}
+/**
+ * Keyframes that take the water from where it is at `from` ms to the end of
+ * the tide in `duration` ms. The waves keep their normal speed.
+ */
+export function rushKeyframes(options, viewport, from, duration) {
+    const start = waterlineAt(from, options, viewport.height);
+    const end = waterlineAt(totalDuration(options), options, viewport.height);
+    const steps = Math.max(1, Math.ceil((duration / 1000) * sampleRate));
+    return Array.from({ length: steps + 1 }, (_, i) => {
+        const t = i / steps;
+        return {
+            offset: t,
+            maskPosition: positionFor(start + (end - start) * easeInOut(t), wavePhaseAt(from + t * duration, options), options.waveAmplitude),
+        };
+    });
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "react-theme-tide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Theme changes that rise up the page like water, using native View Transitions.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alawonn/react-theme-tide.git"
+  },
+  "homepage": "https://github.com/alawonn/react-theme-tide#readme",
+  "bugs": {
+    "url": "https://github.com/alawonn/react-theme-tide/issues"
+  },
+  "keywords": [
+    "react",
+    "theme",
+    "dark-mode",
+    "view-transitions",
+    "animation"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p demo/tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "demo": "vite --config demo/vite.config.ts",
+    "demo:build": "vite build --config demo/vite.config.ts",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^24.19.2",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.2.1",
+    "eslint": "^10.14.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "jsdom": "^30.1.3",
+    "pngjs": "^7.0.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  }
+}