react-theme-tide 0.0.0-stage → 0.2.5

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,96 @@
-# 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.
+Switch your site between light and dark with a wave of water. The new theme rises from the bottom of the screen, pauses for a second with the waves still moving, then fills the page.
+
+<p>
+  <a href="https://github.com/alawonn/react-theme-tide/blob/main/docs/images/tide-1-rise.png"><img src="https://raw.githubusercontent.com/alawonn/react-theme-tide/main/docs/images/tide-1-rise.png" width="260" alt="The dark theme rising from the bottom of the demo page"></a>
+  <a href="https://github.com/alawonn/react-theme-tide/blob/main/docs/images/tide-2-pause.png"><img src="https://raw.githubusercontent.com/alawonn/react-theme-tide/main/docs/images/tide-2-pause.png" width="260" alt="The water pausing at 60% of the screen"></a>
+  <a href="https://github.com/alawonn/react-theme-tide/blob/main/docs/images/tide-3-fill.png"><img src="https://raw.githubusercontent.com/alawonn/react-theme-tide/main/docs/images/tide-3-fill.png" width="260" alt="The water about to fill the page"></a>
+</p>
+
+**[Try the demo](https://alawonn.github.io/react-theme-tide/)**
+
+You keep your own theme code. React Theme Tide only animates the change.
+
+## Install
+
+```bash
+npm install react-theme-tide
+```
+
+```bash
+pnpm add react-theme-tide
+```
+
+```bash
+yarn add react-theme-tide
+```
+
+```bash
+bun add react-theme-tide
+```
+
+```bash
+deno add npm:react-theme-tide
+```
+
+You need React 18 or newer. There's no CSS to import.
+
+## Use it
+
+Wrap the code that changes your theme in `run`:
+
+```tsx
+"use client";
+import { useThemeTide } from "react-theme-tide";
+
+export function ThemeToggle() {
+  const tide = useThemeTide();
+  return (
+    <button
+      type="button"
+      onClick={() => tide.run(() => document.documentElement.classList.toggle("dark"))}
+    >
+      Switch theme
+    </button>
+  );
+}
+```
+
+Already have a function that sets and saves the theme? Pass it in as it is:
+
+```tsx
+tide.run(() => setTheme("dark"));
+```
+
+If your theme lives in React state, wrap the update in `flushSync` so the page changes before the water starts:
+
+```tsx
+import { flushSync } from "react-dom";
+
+tide.run(() => flushSync(() => setTheme("dark")));
+```
+
+It works in Next.js too. Use the hook in a Client Component.
+
+People who prefer reduced motion get an instant change. So do browsers without View Transitions.
+
+## Sites using it
+
+| Mid-tide | Site |
+| --- | --- |
+| <a href="https://vertexx.fit"><img src="https://raw.githubusercontent.com/alawonn/react-theme-tide/main/docs/images/site-vertexx.png" width="320" alt="Vertexx switching from dark to light, paused partway up"></a> | [Vertexx](https://vertexx.fit) |
+| <a href="https://meau.me"><img src="https://raw.githubusercontent.com/alawonn/react-theme-tide/main/docs/images/site-meau-me.png" width="320" alt="meau.me switching from light to dark, with long, slow waves"></a> | [meau.me](https://meau.me) |
+| <a href="https://alawonn.com"><img src="https://raw.githubusercontent.com/alawonn/react-theme-tide/main/docs/images/site-alawonn.png" width="320" alt="alawonn.com switching from light to dark, with short, quick waves"></a> | [alawonn.com](https://alawonn.com) |
+
+Using it on your site? [Open an issue](https://github.com/alawonn/react-theme-tide/issues/new?title=Add%20my%20site%20to%20the%20README&body=Site%20name%3A%0ASite%20URL%3A%0A) with the name and link, or send a pull request that adds it to this table.
+
+## More
+
+- [Usage and options](https://github.com/alawonn/react-theme-tide/blob/main/docs/usage.md): timing, waves, the API and Next.js setup.
+- [How it works](https://github.com/alawonn/react-theme-tide/blob/main/docs/how-it-works.md): what happens on screen, edge cases and tested browsers.
+- [Contributing](https://github.com/alawonn/react-theme-tide/blob/main/CONTRIBUTING.md)
+
+## 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.5",
+  "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"
+  }
+}