@mkbabb/glass-ui 4.0.1 → 4.2.0

package/dist/components/ui/hover-card/HoverCardContent.vue.d.ts

@@ -1,13 +1,16 @@
 import { type HTMLAttributes } from 'vue';
 import { type HoverCardContentProps } from 'reka-ui';
+import { type Surface } from '../_shared/useSurfaceAxis';
 type __VLS_Props = HoverCardContentProps & {
     class?: HTMLAttributes['class'];
+    surface?: Surface;
 };
 declare var __VLS_14: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_14) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    surface: Surface;
     sideOffset: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/components/ui/input/Input.vue.d.ts

@@ -1,10 +1,12 @@
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import { type ControlSize } from '../_shared/useControlSize';
 declare const _default: typeof __VLS_export;
 export default _default;
 declare const __VLS_export: import("vue").DefineComponent<{
     defaultValue?: string | number;
     modelValue?: string | number;
     class?: HTMLAttributes["class"];
+    size?: ControlSize;
     type?: InputHTMLAttributes["type"];
     placeholder?: InputHTMLAttributes["placeholder"];
     disabled?: InputHTMLAttributes["disabled"];
@@ -20,6 +22,7 @@ declare const __VLS_export: import("vue").DefineComponent<{
     defaultValue?: string | number;
     modelValue?: string | number;
     class?: HTMLAttributes["class"];
+    size?: ControlSize;
     type?: InputHTMLAttributes["type"];
     placeholder?: InputHTMLAttributes["placeholder"];
     disabled?: InputHTMLAttributes["disabled"];

package/dist/components/ui/number-field/NumberFieldInput.vue.d.ts

@@ -1,3 +1,8 @@
+import { type ControlSize } from '../_shared/useControlSize';
 declare const _default: typeof __VLS_export;
 export default _default;
-declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: import("vue").DefineComponent<{
+    size?: ControlSize;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
+    size?: ControlSize;
+}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/components/ui/select/SelectContent.vue.d.ts

@@ -1,7 +1,18 @@
 import { type HTMLAttributes } from 'vue';
 import { type SelectContentProps } from 'reka-ui';
+import { type Surface } from '../_shared/useSurfaceAxis';
 type __VLS_Props = SelectContentProps & {
     class?: HTMLAttributes['class'];
+    surface?: Surface;
+    /**
+     * BD.W-SELECT-WELL — the route's warm-field HUE re-emitted onto the portalled
+     * menu so it transmits its route identity even though it escapes to <body>
+     * (the page field stops at the route root; the portal does not). The menu-local
+     * `.glass-field-portal` spine reads this `--field-h`. A forms route resolves 48
+     * (terracotta); a feedback route a different warm hue — so each dropdown reads as
+     * different warm glass, none gray. Unset → the select.css `--field-h: 48` floor.
+     */
+    fieldHue?: number;
 };
 declare var __VLS_25: {};
 type __VLS_Slots = {} & {
@@ -18,6 +29,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
 }>, {
     position: "item-aligned" | "popper";
     align: "start" | "center" | "end";
+    surface: Surface;
     collisionPadding: number | Partial<Record<"bottom" | "left" | "right" | "top", number>>;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/components/ui/slider/Slider.vue.d.ts

@@ -14,6 +14,14 @@ type __VLS_Props = SliderRootProps & {
      * `data-held` on its root, intensifying the thumb halo. Default: true.
      */
     keepDockOpen?: boolean;
+    /**
+     * BD.W-GLASS-ATOM-REGISTER — the liquid weight-train on the fill: anticipation
+     * dip on grab → BOUNDED saturating smear while pulling (the cel cast lagging by
+     * `--motion-weight × velocity`) → follow-through overshoot on release. Composes
+     * the `useDragVelocity` bridge (writes `--atom-drag-v`, no-idle-rAF teardown).
+     * PRM collapses it to the plain squish floor. Default: true.
+     */
+    liquidDrag?: boolean;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (payload: number[] | undefined) => any;
@@ -23,6 +31,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
     onValueCommit?: ((payload: number[]) => any) | undefined;
 }>, {
     keepDockOpen: boolean;
+    liquidDrag: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/components/ui/switch/Switch.vue.d.ts

@@ -1,7 +1,9 @@
 import { type HTMLAttributes } from 'vue';
 import { type SwitchRootProps } from 'reka-ui';
+import { type ControlSize } from '../_shared/useControlSize';
 type __VLS_Props = SwitchRootProps & {
     class?: HTMLAttributes['class'];
+    size?: ControlSize;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (payload: boolean) => any;

package/dist/components/ui/textarea/Textarea.vue.d.ts

@@ -1,10 +1,12 @@
 import type { HTMLAttributes, TextareaHTMLAttributes } from 'vue';
+import { type ControlSize } from '../_shared/useControlSize';
 declare const _default: typeof __VLS_export;
 export default _default;
 declare const __VLS_export: import("vue").DefineComponent<{
     class?: HTMLAttributes["class"];
     defaultValue?: string | number;
     modelValue?: string | number;
+    size?: ControlSize;
     placeholder?: TextareaHTMLAttributes["placeholder"];
     disabled?: TextareaHTMLAttributes["disabled"];
     /**
@@ -29,6 +31,7 @@ declare const __VLS_export: import("vue").DefineComponent<{
     class?: HTMLAttributes["class"];
     defaultValue?: string | number;
     modelValue?: string | number;
+    size?: ControlSize;
     placeholder?: TextareaHTMLAttributes["placeholder"];
     disabled?: TextareaHTMLAttributes["disabled"];
     /**

package/dist/components/ui/tooltip/TooltipContent.vue.d.ts

@@ -1,7 +1,9 @@
 import { type HTMLAttributes } from 'vue';
 import { type TooltipContentProps } from 'reka-ui';
+import { type Surface } from '../_shared/useSurfaceAxis';
 type __VLS_Props = TooltipContentProps & {
     class?: HTMLAttributes['class'];
+    surface?: Surface;
 };
 declare var __VLS_14: {};
 type __VLS_Slots = {} & {
@@ -14,6 +16,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     onEscapeKeyDown?: ((event: KeyboardEvent) => any) | undefined;
     onPointerDownOutside?: ((event: Event) => any) | undefined;
 }>, {
+    surface: Surface;
     sideOffset: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/composables/color/index.d.ts

@@ -133,3 +133,5 @@ export interface DeriveBlobPaletteOptions {
  * @param options stop count, harmony, spreads.
  */
 export declare function deriveBlobPalette(seed: string | OklchStop, options?: DeriveBlobPaletteOptions): OklchStop[];
+export { useAccentTone } from "./useAccentTone";
+export type { UseAccentToneOptions, UseAccentToneReturn } from "./useAccentTone";

package/dist/composables/color/useAccentTone.d.ts

@@ -0,0 +1,34 @@
+import { type ComputedRef, type MaybeRefOrGetter } from "vue";
+export interface UseAccentToneOptions {
+    /** Idle fill strength (0..1). Default 0.08. The CSS `--accent-fill-strength`
+     *  twin — passed here so the JS ink-solve composites the matching band. */
+    fillStrength?: number;
+    /** Active band strength (0..1). Default 0.18 (the CSS `--accent-band-strength`). */
+    bandStrength?: number;
+    /** Target ink-over-band contrast. Default 4.5 (AA). */
+    inkContrast?: number;
+    /** The surface the accent paints ON (a CSS `<color>`). Default the warm-cream
+     *  `--card`. A consumer on a dark/other plate passes its concrete surface so
+     *  the ink solves against the right band lightness. */
+    surface?: string;
+}
+export interface UseAccentToneReturn {
+    /** The element-level custom-property style object — bind via `:style`. Carries
+     *  `--tone` (so the CSS channels resolve) + `--accent-ink-resolved` (the
+     *  contrast-safe label colour over the active band). */
+    toneStyle: ComputedRef<Record<string, string>>;
+    /** The resolved contrast-safe ink as a CSS `oklch(...)` string (for a non-CSS
+     *  reader — a canvas label, a test). */
+    ink: ComputedRef<string>;
+}
+/**
+ * `useAccentTone(tone, opts)` — resolve the contrast-safe label ink for the tonal
+ * register. The ink RESOLVES `safeAccentColor(toneColor, bandLightness, …)`:
+ * value.js shifts the tone's OKLCh lightness AWAY from the active-band fill until
+ * it clears the AA bar, so the label reads ON the fill in either mode (a dark band
+ * gets a light ink, a light band a dark ink). The darken/lighten-until-it-passes
+ * math is value.js's — glass-ui re-implements none of it.
+ *
+ * PRM-irrelevant (a colour, not an animation). DOM-free + deterministic.
+ */
+export declare function useAccentTone(tone: MaybeRefOrGetter<string>, opts?: UseAccentToneOptions): UseAccentToneReturn;

package/dist/composables/dom/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./useResizeObserver";
 export * from "./useTouchGate";
+export * from "./useDragVelocity";
 export * from "./useTokenColor";
 export * from "./useResolveTokenColor";
 export * from "./useClipboard";

package/dist/composables/dom/useDragVelocity.d.ts

@@ -0,0 +1,46 @@
+import { type Ref } from "vue";
+export interface UseDragVelocityParams {
+    /**
+     * The host element resolver — a getter (NOT a ref Slider populates in a sibling
+     * `onMounted`) so it sidesteps the onMounted-ordering trap the slider's
+     * `useDockHold` already documents. The `--atom-drag-v` var is written on THIS
+     * element; descendants inherit it (the fill + the cast read it).
+     */
+    host: () => HTMLElement | null;
+    /**
+     * The pointer axis the velocity is measured on. Default `"x"` (the horizontal
+     * slider). A getter re-reads on an orientation flip.
+     */
+    axis?: "x" | "y" | (() => "x" | "y");
+    /**
+     * The saturating-smear gain (the `tanh` steepness over px/frame). Higher = the
+     * smear reaches its ceiling at a slower drag. Default `0.06`.
+     */
+    gain?: number;
+    /**
+     * The smear CEILING (the clamp the saturated value floors under). Default `0.7`
+     * (challenge #3 R3 — mass wins, the pull never rubber-bands past this).
+     */
+    clamp?: number;
+    /** Honor `prefers-reduced-motion: reduce` (no rAF, value pinned 0). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseDragVelocityReturn {
+    /** True while a drag gesture is live (between `pointerdown` and `pointerup`). */
+    dragging: Readonly<Ref<boolean>>;
+    /** Detach all listeners + tear down any live rAF. Idempotent. */
+    detach: () => void;
+}
+/**
+ * The drag-window-gated velocity bridge — writes `--atom-drag-v` (0..1, bounded by a
+ * saturating `tanh`) on the host while a pointer drag is live, and tears the rAF DOWN
+ * on release (the no-idle-cost contract). The slider weight-train is its first
+ * consumer; any pull-to-smear atom reads the same var.
+ *
+ * @example
+ * ```ts
+ * const { dragging, detach } = useDragVelocity({ host: getRootEl })
+ * // CSS: .slider-range { transform: scaleX(calc(1 + 0.08 * var(--atom-drag-v))) }
+ * ```
+ */
+export declare function useDragVelocity(params: UseDragVelocityParams): UseDragVelocityReturn;

package/dist/composables/glass/useVizChoreography.d.ts

@@ -0,0 +1,123 @@
+import { type Easing } from "@mkbabb/keyframes.js";
+import { type Ref } from "vue";
+import { type SpringPresetName } from "../motion/springPresets";
+/**
+ * The reveal spring register. `bouncy` is the playful bloom (the dots spring out, the
+ * aurora blooms — the largest overshoot), `smooth` the calm settle, `snappy` the crisp
+ * control build, `gentle`/`dock` the patient/control ends. A named SPRING_PRESETS row —
+ * never a hand (response, ζ).
+ */
+export type VizChoreographyPreset = SpringPresetName;
+export interface UseVizChoreographyOptions {
+    /**
+     * The ENTER spring register (default `bouncy` — the playful liquid bloom the user
+     * named). The per-viz wave picks: `smooth` for a calm field settle, `bouncy` for the
+     * dot-scatter bloom.
+     */
+    preset?: VizChoreographyPreset;
+    /**
+     * The config-TRANSITION lerp duration in seconds. Default the ENTER preset's response
+     * (the spring-timed glide — never a hand wall clock). The cross-fade timing is the
+     * `springTimingFunction` of the SAME preset row.
+     */
+    transitionResponse?: number;
+    /**
+     * Honor `prefers-reduced-motion: reduce` → snap the reveal (zero spring frames, the
+     * fade survives, the scatter/transform leg is the viz's to drop). Default true. (A
+     * deterministic viz capture that ACCEPTS the live build-in opts out.)
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Start ALREADY revealed (revealT = 1) — for a viz mounted on a route that is already
+     * the active page (no enter beat owed). Default false (the page-enter starts collapsed
+     * and blooms). `enter()` always re-seats from the current value, so this is only the
+     * INITIAL seed.
+     */
+    initiallyRevealed?: boolean;
+}
+export interface UseVizChoreographyReturn {
+    /**
+     * The coupled reveal scalar ∈ [0,1] (may briefly overshoot >1 on a bouncy enter — the
+     * iOS bloom). The viz reads this for BOTH legs: the build-in uniform (settle-from-
+     * scatter) AND the canvas opacity (clamped via `opacity`). 0 = collapsed/scattered,
+     * 1 = fully materialized.
+     */
+    readonly revealT: Readonly<Ref<number>>;
+    /**
+     * The canvas opacity ∈ [0,1] — the coupled fade leg, `revealT` clamped to [0,1] (the
+     * fade does not overshoot; only the spatial build-in overshoots). The viz binds this
+     * to its canvas `style.opacity`.
+     */
+    readonly opacity: Readonly<Ref<number>>;
+    /**
+     * The config-transition progress ∈ [0,1] — the SmoothProgress glide a preset/variant
+     * morph reads to lerp its config uniforms (0 = the outgoing config, 1 = the incoming).
+     * Idle (settled at 1) when no transition is in flight.
+     */
+    readonly transitionT: Readonly<Ref<number>>;
+    /**
+     * True while the spatial build-in (the settle-from-scatter / the bloom transform) is
+     * ACTIVE — false under PRM (the viz drops the scatter, keeps the fade) and false once
+     * settled. The viz gates its scatter/transform leg on this (the P6 keeps-fade-drops-
+     * transform split).
+     */
+    readonly transformActive: Readonly<Ref<boolean>>;
+    /** True once the reveal has fully settled at its target (the loop can quiesce). */
+    readonly settled: Readonly<Ref<boolean>>;
+    /**
+     * A — START: bloom the viz in (revealT → 1) on the page-enter, on the ENTER spring
+     * register. Idempotent; a re-call mid-build re-seats velocity-continuously (the
+     * restart contract). PRM snaps to revealed (the fade survives, the scatter drops).
+     */
+    enter: () => void;
+    /**
+     * C — END: settle the viz out (revealT → 0) on the no-overshoot exit register, then
+     * the loop parks (the viz reads `settled`/`revealT === 0` to stop). PRM snaps to
+     * collapsed. A closing surface must not overshoot past gone (P2).
+     */
+    leave: () => void;
+    /**
+     * B — TRANSITION: glide a config/variant morph. Re-seats `transitionT` 0→1 on the
+     * SmoothProgress lerp; the viz reads `transitionT` to lerp its config uniforms each
+     * frame. `onComplete` (optional) fires once the glide settles. PRM snaps the glide.
+     */
+    transitionTo: (onComplete?: () => void) => void;
+    /**
+     * D — RESTART: re-seat the reveal from the CURRENT (value, velocity) so a restart mid-
+     * build inherits the live trajectory (the iOS interruptible contract — never a jump-
+     * to-zero). Snaps revealT back to 0 then blooms 1 velocity-continuously.
+     */
+    restart: () => void;
+    /**
+     * Advance the choreography ONE renderer frame. The viz calls this from INSIDE its
+     * existing `createCanvasLifecycle` frame callback with the frame `dtMs` (milliseconds).
+     * NO own rAF — the renderer owns the loop. Steps the reveal spring + the transition
+     * lerp analytically (O(1), zero allocation). Returns the live `revealT` (so a renderer
+     * can read inline). A zero/negative `dtMs` is a no-op step (a paused/first frame).
+     */
+    tick: (dtMs: number) => number;
+    /** The transition cross-fade easing (the typed {fn,css} pair) — for a viz that wants
+     *  the spring curve directly (e.g. to time a CSS-side companion). */
+    readonly transitionEasing: Easing;
+}
+/**
+ * The procedural-viz choreography clock. Composes the published-4.3.0 kf
+ * `SpringProgress` (the reveal scalar) + `SmoothProgress` (the config lerp) +
+ * `springTimingFunction` (the cross-fade timing), FED `tick(dt)` from the consuming
+ * viz's frame callback. Owns NO rAF (the one-loop discipline; the viz feed it). See the
+ * module header for the four beats, the coupled-fade drive, the one-loop fence, and the
+ * Oscillator book.
+ *
+ * @example
+ * ```ts
+ * const choreo = useVizChoreography({ preset: "bouncy" });
+ * // inside createCanvasLifecycle's frame(timeSec):
+ * const dtMs = (timeSec - lastSec) * 1000;
+ * choreo.tick(dtMs);
+ * canvas.style.opacity = String(choreo.opacity.value);
+ * gl.uniform1f(uReveal, choreo.revealT.value); // the settle-from-scatter build-in
+ * // page-enter / route-leave:
+ * watch(active, (on) => (on ? choreo.enter() : choreo.leave()));
+ * ```
+ */
+export declare function useVizChoreography(options?: UseVizChoreographyOptions): UseVizChoreographyReturn;

package/dist/composables/glass/wave/index.d.ts

@@ -0,0 +1,4 @@
+export type { Vec2, CellDriver } from "./waveField";
+export { travelingEnvelope, curlScalar, cellTwist, cellDriver, cellHeight, faceRelief, facePlateau, waveFlow, cursorSwirl, heightField, waveSwell, cellWarpBeforeHeight, } from "./waveField";
+export { WAVE_FIELD_GLSL } from "./waveField.glsl";
+export { WAVE_FIELD_WGSL } from "./waveField.wgsl";

package/dist/composables/glass/wave/waveField.d.ts

@@ -0,0 +1,115 @@
+/** A 2-vector. */
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+/**
+ * The directed-twist magnitude FLOOR (the visibility cure — shared across JS↔GLSL↔WGSL).
+ * The curl scalar alone sits ~|0.3|, damping the crest twist to a whisper; a cell in the
+ * crest band always rotates at least this fraction of `twistMax` so the wave READS.
+ */
+export declare const TWIST_FLOOR = 0.62;
+/**
+ * A moving Gaussian crest band sweeping along `waveDir` at angular speed `waveOmega`.
+ * Returns the envelope in [0,1]: ~0 where the wave has NOT reached, ~1 at the crest,
+ * relaxing back to ~0 behind it. `coord` is the wave phase at a point; `crest` wraps it
+ * to a single 0..1 cycle and `env` is the Gaussian about the cycle midpoint. The crest
+ * "passes OVER and THROUGH" the field — the cells are calm ahead, twist HARD at the
+ * crest, relax behind.
+ */
+export declare function travelingEnvelope(pivot: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number): number;
+/**
+ * The curl-noise vorticity read at the cell center — a smooth low-frequency scalar in
+ * roughly [-1,1] that DIRECTS the per-cell twist so adjacent cells lean TOGETHER (a
+ * flowing read, never per-cell noise). The host supplies `curlFn(p) -> Vec2` (the shared
+ * divergence-free curl of its own noise basis); this takes the x-component as the signed
+ * director and folds a slow time drift so the flow itself evolves. Basis-agnostic.
+ */
+export declare function curlScalar(curlFn: (p: Vec2) => Vec2, cc: Vec2, t: number): number;
+/** The cell pivot `cc` + the spring-eased crest envelope `env` a cell rides. */
+export interface CellDriver {
+    /** The PRE-twist cell center (the per-cell pivot the twist rotates about). */
+    cc: Vec2;
+    /** The traveling-Gaussian crest envelope × amp at that pivot ([0,1] · amp). */
+    env: number;
+}
+/**
+ * The pre-twist driver for the grid coordinate `g`: floor `g` to its cell, return that cell's
+ * center `cc` + the traveling-wave crest envelope `env` evaluated AT that center (= `cellHeight`,
+ * so there is provably ONE envelope). FOLD A: the face must sample its height/relief at THIS
+ * pre-twist `cc`, NOT at `floor(twisted_g)` (the crest twist crosses the cell boundary → the
+ * face would light a NEIGHBOUR cell). `cellTwist` rides the SAME driver, so twist and face fuse.
+ */
+export declare function cellDriver(g: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, amp: number): CellDriver;
+/**
+ * Twist the grid coordinate `g` about its OWN cell center, gated by the traveling wave
+ * and directed by the curl flow. The pivot is the cell center (a per-cell constant) so the
+ * box rotates about its middle — the cell stays in place but TWISTS (a windmill of warped
+ * boxes where the crest passes; calm square cells elsewhere). `amp` is the spring-eased
+ * envelope amplitude the JS host drives (the liquid-weight inertia). Returns the twisted
+ * coordinate (still in grid space; the host evaluates its extraction at it).
+ *
+ * FOLD C — the `TWIST_FLOOR` is CREST-GATED: the floor is multiplied by the crest envelope so
+ * OFF-crest cells relax to near-flat (calm paper) and only the crest band crinkles. Without
+ * this every cell crinkles regardless of the wave (static foil, no traveling read).
+ */
+export declare function cellTwist(curlFn: (p: Vec2) => Vec2, g: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, shearMax: number, amp: number): Vec2;
+/**
+ * The sheet displacement at a cell center `cc` — the EXACT traveling-wave scalar the twist
+ * rides (`travelingEnvelope · amp`), surfaced as a named leaf fn so the face reads ONE
+ * envelope. Range [0,1]·amp: ~0 ahead of / behind the crest, ~amp at the crest. `cellTwist`
+ * (via `cellDriver`) calls this, so a sign drift reds the numeric parity gate everywhere.
+ */
+export declare function cellHeight(cc: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, amp: number): number;
+/**
+ * The central-difference slope of `cellHeight` across a cell (`ε = 0.5·cellSize`) — the lit-fold
+ * normal source. Pure, derivative-FREE (NO `dFdx` on the height) → Safari WebGL2-safe by
+ * construction (only the Golus AA uses `fwidth`). Returns ∇H = (∂H/∂x, ∂H/∂y) at `cc`.
+ */
+export declare function faceRelief(cc: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, amp: number): Vec2;
+/**
+ * Soft inset-square coverage inside a (warped) cell — the filled FACE plateau. `d` is the
+ * distance into the cell from the nearest gutter (per axis, on the triangle-wave the Golus
+ * grid already uses); `smoothstep(inset, inset+2·aa, d)` floors the face to a soft-edged tile
+ * that retreats as `inset` grows (the squash). The shaders pass `aa = fwidth(g)` (crisp at any
+ * DPR — the Golus precedent); the JS round-trip passes a fixed `uvDeriv` (reproducible).
+ * Returns face coverage [0..1].
+ */
+export declare function facePlateau(g: Vec2, inset: number, uvDeriv: Vec2): number;
+/**
+ * A LOCAL Gaussian-gated rotation about the cursor — the finger twists the cells around
+ * it (the re-aimed `cursorBulge`: a swirl, not a radial push). `strength` is the peak
+ * twist angle at the cursor; `radius` the Gaussian falloff (grid units). Returns the
+ * swirled coordinate.
+ */
+export declare function cursorSwirl(g: Vec2, cursor: Vec2, strength: number, radius: number): Vec2;
+/**
+ * A CONTINUOUS divergence-free flow warp gated by the traveling wave — the SMOOTH twin of
+ * `cellTwist` for surfaces that need an unbroken coordinate (the level-set contours shatter
+ * into a mesh under the per-cell discontinuity; they need this continuous warp). The curl
+ * flow direction is read at `g` itself (no per-cell pivot → no seam), its magnitude gated by
+ * the SAME traveling Gaussian crest sweeping along `waveDir`. So the contours flow + twist as
+ * the wave passes OVER and THROUGH them, with NO cell-boundary discontinuity. Returns the
+ * warped coordinate.
+ */
+export declare function waveFlow(curlFn: (p: Vec2) => Vec2, g: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, amp: number): Vec2;
+/**
+ * A LOW-octave value-noise topography H(p) — the scalar field concentric extracts level-set
+ * contours of. `octaves` LOW (3) keeps the nested loops CLEAN (not high-freq speckle — the
+ * legibility floor). The host supplies its `noiseFn(x,y)` (the SAME value-noise basis its
+ * `potentialFBM` uses, basis-agnostic). Returns the un-normalized height.
+ */
+export declare function heightField(noiseFn: (x: number, y: number) => number, p: Vec2, octaves: number, seed: number): number;
+/**
+ * The ω=√(g·k) breathing swell — a slow global rise/fall the topography rides so basins
+ * inflate/deflate with weight (the deep-water dispersion the suite shares). A pure
+ * f(t) the host adds onto H. `phase` lets a host offset its own swell.
+ */
+export declare function waveSwell(t: number, phase: number): number;
+/**
+ * The cell-warp applied BEFORE the height eval (concentric's `cellWarpBeforeHeight`). It
+ * is the SAME `cellTwist` paper-grid runs — concentric warps the SAMPLING coordinate so
+ * the contours twist/flow as the traveling wave crosses (kinship with paper-grid). A thin
+ * alias for the gate's by-name assert + the host's call-site clarity.
+ */
+export declare function cellWarpBeforeHeight(curlFn: (p: Vec2) => Vec2, g: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, shearMax: number, amp: number): Vec2;

package/dist/composables/glass/wave/waveField.glsl.d.ts

@@ -0,0 +1 @@
+export declare const WAVE_FIELD_GLSL = "\n#ifndef WAVE_FIELD_TAU\n#define WAVE_FIELD_TAU 6.283185307179586\n#endif\n\n// The traveling-wave envelope \u2014 a moving Gaussian crest band sweeping along waveDir.\nfloat travelingEnvelope(vec2 pivot, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma) {\n  float coord = dot(pivot, waveDir) * waveK - t * waveOmega;\n  float crest = fract(coord / WAVE_FIELD_TAU);\n  float z = (crest - 0.5) * 2.0;\n  return exp(-(z * z) / max(waveSigma, 1e-3));\n}\n\n// The curl-direction scalar \u2014 the smooth low-freq director the per-cell twist follows.\nfloat curlScalar(vec2 cc, float t) {\n  vec2 f = curlFBM(vec2(cc.x * 0.5 + t * 0.08, cc.y * 0.5 - t * 0.06));\n  return clamp(f.x, -1.0, 1.0);\n}\n\n// The directed-twist FLOOR (the visibility cure): keep the curl SIGN (adjacent cells lean\n// together) but floor the magnitude so a crest-band cell ALWAYS rotates decisively.\n#ifndef WAVE_FIELD_TWIST_FLOOR\n#define WAVE_FIELD_TWIST_FLOOR 0.62\n#endif\nfloat directedTwist(float s, float floorMag) {\n  float mag = max(floorMag, abs(s));\n  float sgn = tanh(s * 6.0);\n  return sgn * mag;\n}\n\n// \u2500\u2500 The FACE leaf (the structurally-absent RE-INVENT \u2014 height-lit filled cell interior) \u2500\u2500\n// Defined ABOVE cellTwist: cellTwist rides cellHeight via the driver so twist + face read ONE\n// envelope.\n\n// The sheet displacement at a cell center = the EXACT traveling-wave scalar the twist rides.\nfloat cellHeight(vec2 cc, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma, float amp) {\n  return travelingEnvelope(cc, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n}\n\n// The pre-twist driver (FOLD A): the cell pivot cc + the crest envelope env the twist AND the\n// face both ride. The face samples height/relief at THIS pre-twist cc (floor(twisted_g) at the\n// crest lights a NEIGHBOUR cell). cc in .xy, env in .z.\nvec3 cellDriver(vec2 g, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n                float waveSigma, float amp) {\n  float cs = max(cellSize, 1e-3);\n  vec2 cc = (floor(g / cs) + 0.5) * cs;\n  float env = cellHeight(cc, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec3(cc, env);\n}\n\n// The central-difference slope of cellHeight across a cell (eps = 0.5\u00B7cellSize) \u2014 derivative-\n// FREE (NO dFdx on the height) \u2192 Safari WebGL2-safe. Returns \u2207H.\nvec2 faceRelief(vec2 cc, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n                float waveSigma, float amp) {\n  float eps = max(cellSize, 1e-3) * 0.5;\n  float hxp = cellHeight(cc + vec2(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hxm = cellHeight(cc - vec2(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hyp = cellHeight(cc + vec2(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hym = cellHeight(cc - vec2(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec2((hxp - hxm) / (2.0 * eps), (hyp - hym) / (2.0 * eps));\n}\n\n// Soft inset-square coverage inside a (warped) cell \u2014 the filled FACE plateau. d is the distance\n// into the cell from the nearest gutter (the Golus triangle-wave); the inset retreats as it grows\n// (the squash). aa = the shader's fwidth(g) (JS passes a fixed uvDeriv).\nfloat facePlateau(vec2 g, float inset, vec2 uvDeriv) {\n  vec2 tri = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  float d = min(tri.x, tri.y);\n  float aa = max(uvDeriv.x, uvDeriv.y) * 1.5;\n  return smoothstep(inset, inset + 2.0 * aa, d);\n}\n\n// The cell-local twist about each cell's own center, gated by the traveling wave + directed\n// by the curl flow. amp is the spring-eased envelope amplitude the JS host drives. FOLD C: the\n// TWIST_FLOOR is crest-gated by env so OFF-crest cells relax to flat calm paper (the traveling\n// read, not static foil).\nvec2 cellTwist(vec2 g, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n               float waveSigma, float twistMax, float shearMax, float amp) {\n  vec3 drv = cellDriver(g, cellSize, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  vec2 cc = drv.xy;\n  float env = drv.z;\n  float floorMag = WAVE_FIELD_TWIST_FLOOR * env;   // FOLD C: crest-gated floor\n  float theta = twistMax * env * directedTwist(curlScalar(cc, t), floorMag);\n  float shear = shearMax * env * directedTwist(curlScalar(cc + vec2(17.3, 9.1), t), floorMag);\n  vec2 local = g - cc;\n  float ct = cos(theta);\n  float st = sin(theta);\n  vec2 rot = vec2(ct * local.x - st * local.y, st * local.x + ct * local.y);\n  rot.x += shear * rot.y;   // a small skew so the box MORPHS, not just rotates\n  return cc + rot;\n}\n\n// The CONTINUOUS traveling-wave FLOW warp \u2014 the SMOOTH twin of cellTwist (no per-cell seam;\n// for the level-set contours that shatter into a mesh under the cell discontinuity).\nvec2 waveFlow(vec2 g, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma,\n              float twistMax, float amp) {\n  float env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  vec2 f = curlFBM(vec2(g.x * 0.6 + t * 0.05, g.y * 0.6 - t * 0.04));\n  vec2 f2 = curlFBM(vec2(g.x * 1.1 - t * 0.03, g.y * 1.1 + t * 0.035));\n  float k = twistMax * env;\n  return g + (f + f2 * 0.5) * k;\n}\n\n// The local cursor swirl \u2014 the finger twists the cells around it (re-aimed cursorBulge).\nvec2 cursorSwirl(vec2 g, vec2 cursor, float strength, float radius) {\n  vec2 to = g - cursor;\n  float d2 = dot(to, to);\n  float r = max(radius, 1e-4);\n  float theta = strength * exp(-d2 / (2.0 * r * r));\n  float ct = cos(theta);\n  float st = sin(theta);\n  return cursor + vec2(ct * to.x - st * to.y, st * to.x + ct * to.y);\n}\n\n// The LOW-octave value-noise topography \u2014 the scalar field concentric extracts contours of.\nfloat heightField(vec2 p, float octavesF, float seed) {\n  float v = 0.0;\n  float amp = 0.5;\n  float freq = 1.0;\n  float px = p.x + seed;\n  float py = p.y - seed;\n  int n = int(clamp(octavesF, 1.0, 6.0));\n  for (int i = 0; i < 6; i++) {\n    if (i >= n) break;\n    v += amp * valueNoise(px * freq, py * freq);\n    float rx = 0.8 * px - 0.6 * py;\n    float ry = 0.6 * px + 0.8 * py;\n    px = rx;\n    py = ry;\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return v;\n}\n\n// The \u03C9=\u221A(g\u00B7k) breathing swell \u2014 basins inflate/deflate with weight.\nfloat waveSwell(float t, float phase) {\n  return sin(t * 0.35 + phase) * 0.5 + sin(t * 0.21 + phase * 1.7) * 0.5;\n}\n";

package/dist/composables/glass/wave/waveField.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const WAVE_FIELD_WGSL = "\nconst WAVE_FIELD_TAU: f32 = 6.283185307179586;\n\n// The traveling-wave envelope \u2014 a moving Gaussian crest band sweeping along waveDir.\nfn travelingEnvelope(pivot: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32) -> f32 {\n  let coord = dot(pivot, waveDir) * waveK - t * waveOmega;\n  let crest = fract(coord / WAVE_FIELD_TAU);\n  let z = (crest - 0.5) * 2.0;\n  return exp(-(z * z) / max(waveSigma, 1e-3));\n}\n\n// The curl-direction scalar \u2014 the smooth low-freq director the per-cell twist follows.\nfn curlScalar(cc: vec2f, t: f32) -> f32 {\n  let f = curlFBM(vec2f(cc.x * 0.5 + t * 0.08, cc.y * 0.5 - t * 0.06));\n  return clamp(f.x, -1.0, 1.0);\n}\n\n// The directed-twist FLOOR (the visibility cure): keep the curl SIGN (adjacent cells lean\n// together) but floor the magnitude so a crest-band cell ALWAYS rotates decisively.\nconst WAVE_FIELD_TWIST_FLOOR: f32 = 0.62;\nfn directedTwist(s: f32, floorMag: f32) -> f32 {\n  let mag = max(floorMag, abs(s));\n  let sgn = tanh(s * 6.0);\n  return sgn * mag;\n}\n\n// \u2500\u2500 The FACE leaf (the structurally-absent RE-INVENT \u2014 height-lit filled cell interior) \u2500\u2500\n// DECLARED ABOVE cellTwist (no WGSL forward declaration): cellTwist rides cellHeight via the\n// driver so twist + face read ONE envelope.\n\n// The sheet displacement at a cell center = the EXACT traveling-wave scalar the twist rides.\nfn cellHeight(cc: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32, amp: f32) -> f32 {\n  return travelingEnvelope(cc, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n}\n\n// The pre-twist driver (FOLD A): the cell pivot cc + the crest envelope env the twist AND the\n// face both ride. The face samples height/relief at THIS pre-twist cc (the crest twist crosses\n// the cell boundary \u2192 floor(twisted_g) would light a NEIGHBOUR cell). cc in .xy, env in .z.\nfn cellDriver(g: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n              waveSigma: f32, amp: f32) -> vec3f {\n  let cs = max(cellSize, 1e-3);\n  let cc = (floor(g / cs) + 0.5) * cs;\n  let env = cellHeight(cc, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec3f(cc, env);\n}\n\n// The central-difference slope of cellHeight across a cell (eps = 0.5\u00B7cellSize) \u2014 derivative-\n// FREE (NO dFdx on the height) \u2192 Safari WebGL2-safe. Returns \u2207H.\nfn faceRelief(cc: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n              waveSigma: f32, amp: f32) -> vec2f {\n  let eps = max(cellSize, 1e-3) * 0.5;\n  let hxp = cellHeight(cc + vec2f(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hxm = cellHeight(cc - vec2f(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hyp = cellHeight(cc + vec2f(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hym = cellHeight(cc - vec2f(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec2f((hxp - hxm) / (2.0 * eps), (hyp - hym) / (2.0 * eps));\n}\n\n// Soft inset-square coverage inside a (warped) cell \u2014 the filled FACE plateau. d is the\n// distance into the cell from the nearest gutter (the Golus triangle-wave); the inset retreats\n// as it grows (the squash). aa = the shader's fwidth(g) (JS passes a fixed uvDeriv).\nfn facePlateau(g: vec2f, inset: f32, uvDeriv: vec2f) -> f32 {\n  let tri = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  let d = min(tri.x, tri.y);\n  let aa = max(uvDeriv.x, uvDeriv.y) * 1.5;\n  return smoothstep(inset, inset + 2.0 * aa, d);\n}\n\n// The cell-local twist about each cell's own center, gated by the traveling wave + directed\n// by the curl flow. amp is the spring-eased envelope amplitude the JS host drives. FOLD C: the\n// TWIST_FLOOR is crest-gated by env so OFF-crest cells relax to flat calm paper (the traveling\n// read, not static foil).\nfn cellTwist(g: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n             waveSigma: f32, twistMax: f32, shearMax: f32, amp: f32) -> vec2f {\n  let drv = cellDriver(g, cellSize, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let cc = drv.xy;\n  let env = drv.z;\n  let floorMag = WAVE_FIELD_TWIST_FLOOR * env;   // FOLD C: crest-gated floor\n  let theta = twistMax * env * directedTwist(curlScalar(cc, t), floorMag);\n  let shear = shearMax * env * directedTwist(curlScalar(cc + vec2f(17.3, 9.1), t), floorMag);\n  let local = g - cc;\n  let ct = cos(theta);\n  let st = sin(theta);\n  var rot = vec2f(ct * local.x - st * local.y, st * local.x + ct * local.y);\n  rot.x = rot.x + shear * rot.y;   // a small skew so the box MORPHS, not just rotates\n  return cc + rot;\n}\n\n// The CONTINUOUS traveling-wave FLOW warp \u2014 the SMOOTH twin of cellTwist (no per-cell seam;\n// for the level-set contours that shatter into a mesh under the cell discontinuity).\nfn waveFlow(g: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32,\n            twistMax: f32, amp: f32) -> vec2f {\n  let env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  let f = curlFBM(vec2f(g.x * 0.6 + t * 0.05, g.y * 0.6 - t * 0.04));\n  let f2 = curlFBM(vec2f(g.x * 1.1 - t * 0.03, g.y * 1.1 + t * 0.035));\n  let k = twistMax * env;\n  return g + (f + f2 * 0.5) * k;\n}\n\n// The local cursor swirl \u2014 the finger twists the cells around it (re-aimed cursorBulge).\nfn cursorSwirl(g: vec2f, cursor: vec2f, strength: f32, radius: f32) -> vec2f {\n  let to = g - cursor;\n  let d2 = dot(to, to);\n  let r = max(radius, 1e-4);\n  let theta = strength * exp(-d2 / (2.0 * r * r));\n  let ct = cos(theta);\n  let st = sin(theta);\n  return cursor + vec2f(ct * to.x - st * to.y, st * to.x + ct * to.y);\n}\n\n// The LOW-octave value-noise topography \u2014 the scalar field concentric extracts contours of.\nfn heightField(p: vec2f, octavesF: f32, seed: f32) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var freq = 1.0;\n  var px = p.x + seed;\n  var py = p.y - seed;\n  let n = i32(clamp(octavesF, 1.0, 6.0));\n  for (var i = 0; i < 6; i = i + 1) {\n    if (i >= n) { break; }\n    v = v + amp * valueNoise(px * freq, py * freq);\n    let rx = 0.8 * px - 0.6 * py;\n    let ry = 0.6 * px + 0.8 * py;\n    px = rx;\n    py = ry;\n    freq = freq * 2.0;\n    amp = amp * 0.5;\n  }\n  return v;\n}\n\n// The \u03C9=\u221A(g\u00B7k) breathing swell \u2014 basins inflate/deflate with weight.\nfn waveSwell(t: f32, phase: f32) -> f32 {\n  return sin(t * 0.35 + phase) * 0.5 + sin(t * 0.21 + phase * 1.7) * 0.5;\n}\n";