@mkbabb/glass-ui 4.1.0 → 5.0.0

package/dist/components/header-ribbon/types.d.ts

@@ -0,0 +1,7 @@
+export type HeaderRibbonPlacement = "left" | "right";
+export interface HeaderRibbonProps {
+    /** Side of the viewport the ribbon anchors against. Defaults to `"left"`. */
+    placement?: HeaderRibbonPlacement;
+    /** Milliseconds after the pointer leaves the ribbon before items collapse. Defaults to `2000`. */
+    hideTimeoutMs?: number;
+}

package/dist/components/icon-chip/types.d.ts

@@ -0,0 +1,92 @@
+import type { Component, FunctionalComponent, HTMLAttributes } from "vue";
+/**
+ * Permissive icon type — Vue's `Component` ships across multiple structurally
+ * incompatible shapes (the @lucide/vue v1 functional-component form is one), so
+ * we accept the union a `<component :is>` render expression handles. Mirrors the
+ * `MetricCell` `IconLike` precedent (the AZ `isComponent` allowance).
+ */
+export type IconChipIcon = Component | FunctionalComponent | object;
+/** A 0..12 index into the `--section-color-N` 13-stop ramp. */
+export type IconChipSection = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * A complete token colour for the chip event (e.g. `var(--chart-download)`,
+ * `var(--tier-featured)`) — the MetricCell-`iconColor` reconcile path. NEVER a
+ * demo-local literal hue (ppmycota purple stays out of the library — the chip
+ * `tone` arm takes a token).
+ */
+export type IconChipTone = string;
+export interface IconChipProps {
+    /**
+     * The lucide glyph (functional-component form per the AZ `isComponent`
+     * precedent). Rendered via `<component :is>`.
+     */
+    icon: IconChipIcon;
+    /**
+     * The `--section-color-N` ramp index (0..12) — the section arm. XOR `tone`.
+     * When both are set, `tone` wins (the explicit complete-token override).
+     * Typed `number` for data-driven consumers (a `v-for` over a descriptor list
+     * with a `section: number` field); the 0..12 canonical range is the
+     * `IconChipSection` union the discovery layer publishes.
+     */
+    section?: number;
+    /**
+     * A complete token colour (the tone arm — the MetricCell-`iconColor`
+     * reconcile). XOR `section`.
+     */
+    tone?: IconChipTone;
+    /**
+     * The chip diameter in px — the FLOOR is `glyphSize × --icon-chip-glyph-ratio`
+     * so the plate can never paint under the glyph (the d2 proportion, structural).
+     * Default `48` (the reference register, 48/22 ≈ 2.18).
+     */
+    size?: number;
+    /** The lucide glyph pixel size. Default `22` (the reference register). */
+    glyphSize?: number;
+    /** The lucide glyph stroke width. Default `1.75` (the reference register). */
+    strokeWidth?: number;
+    /**
+     * The NO-PLATE register — render the full-chroma glyph with NO backplate
+     * (the MetricCell leading-glyph tint). The chip≤glyph floor is moot (no plate).
+     */
+    bare?: boolean;
+    /**
+     * Duotone fill — a low-alpha fill of the same hue UNDER the full-chroma
+     * stroke (the iOS/Material "filled-tonal" move). Mono-hue (proportion-safe,
+     * never a second hue). Default `false`.
+     */
+    duotone?: boolean;
+    /**
+     * The chip's own smooth-glass hover register (the backplate mix lifts, a soft
+     * glow ring appears, the stroke firms) — on the §6 easing doctrine (the GROW
+     * rides --spring-smooth, the color cross-fade the bezier), PRM-gated,
+     * disco-FREE. Default `false`.
+     */
+    bloom?: boolean;
+    /**
+     * The louder focal-pop vibrancy axis (BB.W-SUFFUSE3) — re-points the
+     * backplate `color-mix` strength off the 25% reference stop to ~40% (more
+     * chroma) via `--icon-chip-plate-strength`. STILL the ONE color event per
+     * surface (the same event, louder — proof:suffuse d3 counts the event family,
+     * not the saturation); the `in srgb` space + the chip≤glyph ratio are
+     * untouched. Default `false` (byte-identical to the reference register).
+     */
+    saturated?: boolean;
+    /**
+     * The QUIET glass register (BD.W-GLASS-ATOM-REGISTER cross-link). The DEFAULT
+     * chip keeps its loud `in srgb` brand-overlay plate (AW.W26 fence); this opt-in
+     * routes the chip through the shared `.glass-atom` warm-glass capsule instead —
+     * a transmissive lozenge with the warm floor + the `--glass-blur-quiet` backdrop
+     * + the keyed rim, tinted by `--glass-fill-tint` toward the event hue. Two
+     * registers, exactly like Badge: loud brand pop (default) vs quiet glass lens
+     * (opt-in). Default `false`.
+     */
+    glass?: boolean;
+    /**
+     * Entrance choreography — composes the shipped `vReveal` directive. A numeric
+     * value is the `--d` stagger index; `true` is index 0. PRM-gated by `vReveal`'s
+     * construction. Default `false`.
+     */
+    reveal?: boolean | number;
+    /** Pass-through class on the chip root. */
+    class?: HTMLAttributes["class"];
+}

package/dist/components/index.d.ts

@@ -0,0 +1,36 @@
+export * from "./accordion";
+export * from "./alert";
+export * from "./avatar";
+export * from "./badge";
+export * from "./button";
+export * from "./card";
+export * from "./carousel";
+export * from "./checkbox";
+export * from "./collapsible";
+export * from "./combobox";
+export * from "./command";
+export * from "./data-table";
+export * from "./dialog";
+export * from "./drawer";
+export * from "./dropdown-menu";
+export * from "./focus-scope";
+export * from "./input";
+export * from "./label";
+export * from "./notification";
+export * from "./number-field";
+export * from "./popover";
+export * from "./progress";
+export * from "./radio-group";
+export * from "./section";
+export * from "./select";
+export * from "./separator";
+export * from "./skeleton";
+export * from "./slider";
+export * from "./switch";
+export * from "./table";
+export * from "./tags-input";
+export * from "./textarea";
+export * from "./toast";
+export * from "./toggle";
+export * from "./toggle-group";
+export * from "./tooltip";

package/dist/components/liquid-grid/LiquidGrid.vue.d.ts

@@ -0,0 +1,42 @@
+import type { LiquidGridConfig } from "./constants";
+/**
+ * LiquidGrid — a liquid AA-grid: evenly-spaced LARGER lines on a slowly breathing
+ * curl-flow sheet.
+ *
+ * A calm engineering-graph-liquid grid (evenly-spaced, LARGE cells, a crisp fine rule with
+ * a bolder major rule every 5 cells) drawn on a slowly breathing liquid sheet — adjacent
+ * lines bow and flow TOGETHER as if the grid is ruled on a gently rippling pond, never a
+ * per-line jitter. WebGPU-FIRST: a pure fullscreen fragment pass (the aurora/concentric
+ * shape-class) computes the grid at a curl-warped coordinate per pixel via the Ben Golus
+ * derivative-AA distance function (constant device-pixel-crisp lines, the CSS-blur kill),
+ * the Iñigo Quílez domain warp (the "liquid"), and the Bridson divergence-free curl flow
+ * (WHY it's liquid not noise). It composes `useLiquidGrid` → the `createGpuSubstrate` picker
+ * over the ONE canvas lifecycle leaf (offscreen-pause, live-PRM freeze, consumer-owned DPR)
+ * — it never bootstraps its own context.
+ *
+ * The DEFAULT line ink is the warm-cream `--foreground` library identity (resolved live at
+ * mount); the demo themes it through a PRESET (presets-in-consumers — never a library
+ * token). The grid suffuses over the page (transparent ground) — teal-on-navy is gone.
+ */
+type __VLS_Props = {
+    /** The full author schema (the studio's `useConfiguratorState` model). */
+    config?: LiquidGridConfig;
+    /**
+     * The declarative WCAG-2.2.2 pause seam. `v-model:paused` parks the render loop
+     * (the substrate's `manual` suspend) when `true`. Wire `<DockBackgroundToggle>`'s
+     * `@update:paused` to this `v-model`.
+     */
+    paused?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    pause: () => void;
+    resume: () => void;
+    wake: () => void;
+    renderAt: (timeSec: number) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:paused": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:paused"?: ((value: boolean) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/liquid-grid/composables/liquidGrid.d.ts

@@ -0,0 +1,113 @@
+/** A 2-vector. */
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+/** The curl central-difference epsilon (matches `flow.glsl.ts` / `flow.wgsl.ts`). */
+export declare const CURL_EPS = 0.012;
+/**
+ * BG.W-GRID-AFFINE — the liquid-grid curl-sampling spatial frequency (in CELL units).
+ * `g0 = uv · gridScale` is CELL-scale (span ~14–40 cells), so the warp must sample the curl
+ * potential at a frequency an ORDER OF MAGNITUDE below the grid frequency for the warp to be
+ * locally affine at the cell scale — the sheet bows as ONE smooth curve (base wavelength 1/0.03 ≈
+ * 33 cells), never the sub-cell crackle a cell-scale `~1` frequency produced. Concentric's own
+ * `waveFlow` call passes the unit-scale `0.6` (its `p` is unit-scale). The shaders carry the same
+ * `0.03` literal (the round-trip fence). NOT a config tunable — the affine-frequency FLOOR.
+ */
+export declare const LIQUID_GRID_WARP_FREQ = 0.03;
+/** A 3-octave scalar fbm potential (the host noise basis the curl operator wraps). */
+export declare function potentialFBM(p: Vec2): number;
+/** The 2D curl of the scalar fbm potential (the JS twin of `curlFBM`). */
+export declare function curlFBM(p: Vec2): Vec2;
+/**
+ * The Ben Golus derivative-AA grid line coverage at `g` (grid space). `targetWidth` is the
+ * desired line half-width in GRID UNITS (the caller passes `lineWidthPx / minorPitchPx` so
+ * the line is N device-pixels wide); `uvDeriv` is the per-axis screen-space derivative of
+ * `g` (in the shaders `length(vec2(dFdx(g), dFdy(g)))`; in JS the caller passes it
+ * analytically so the path is reproducible). Returns line coverage [0..1].
+ *
+ * The Golus pipeline (transcribed by the WGSL/GLSL EXACTLY):
+ *   gridUV   = 1 − |fract(g)·2 − 1|                 (triangle wave: 0 at line, 1 at center)
+ *   drawW    = clamp(targetWidth, uvDeriv, 0.5)
+ *   lineAA   = uvDeriv·1.5
+ *   grid2    = smoothstep(drawW+lineAA, drawW−lineAA, gridUV)
+ *   grid2   *= clamp(targetWidth/drawW, 0, 1)        (preserve thin-line intensity)
+ *   grid2    = mix(grid2, targetWidth, clamp(uvDeriv·2−1, 0, 1))   (Moiré suppression)
+ *   line     = max(grid2.x, grid2.y)
+ */
+export declare function gridCoverage(g: Vec2, targetWidth: number, uvDeriv: Vec2): number;
+/**
+ * The complete liquid-grid sample at a domain `uv` (the round-trip anchor). Composes the
+ * warp + the bulge + the two-tier Golus coverage EXACTLY as the WGSL/GLSL `fs_main` does,
+ * returning the premultiplied-alpha (the page reads through the troughs). `uvDeriv` is the
+ * FIXED analytic per-axis derivative (JS has no fragment derivatives); the shaders compute
+ * it from `dpdx`/`dpdy`. Returns `{ line, alpha }` — the line coverage + the global alpha.
+ */
+export interface LiquidGridSampleParams {
+    /** The grid scale (view / minorPitch → LARGER cells = smaller scale). */
+    gridScale: number;
+    /** The traveling-wave front direction. */
+    waveDir: Vec2;
+    /** The crest-band spatial frequency. */
+    waveK: number;
+    /** The front speed (ω). */
+    waveOmega: number;
+    /** The crest-band width. */
+    waveSigma: number;
+    /** The affine sheet-warp displacement magnitude at the crest (grid units). */
+    twistMax: number;
+    /** The spring-eased envelope amplitude (0..1; PRM snaps to 0). */
+    amp: number;
+    /** The cursor in GRID space. */
+    cursor: Vec2;
+    /** The cursor-swirl peak twist (rad). */
+    bulgeStrength: number;
+    bulgeRadius: number;
+    /** +1 repel, −1 attract (signs the swirl). */
+    bulgeMode: number;
+    /** 1 = cursor swirl on. */
+    interactive: number;
+    /** Golus target half-widths in grid units (minor + major). */
+    targetWidth: number;
+    targetWidthMajor: number;
+    /** How many minor cells per major rule. */
+    majorEvery: number;
+    minorAlpha: number;
+    majorAlpha: number;
+    /** The GLOBAL subtlety knob (suffusion → tiny). */
+    fieldAlpha: number;
+    /** The FIXED per-axis derivative (the JS round-trip; shaders use dpdx/dpdy). */
+    uvDeriv: Vec2;
+    /** The filled-FACE opacity (0 → the face evaporates → byte-identical to HEAD). */
+    faceAlpha?: number;
+    /** The slope-shade ∇H Lambert gain. */
+    faceReliefGain?: number;
+    /** The volume-preserving squash (the inset retreats at the crest). */
+    squashK?: number;
+    /** The base inset-square coverage. */
+    baseInset?: number;
+    /** The fixed cel key-light direction. */
+    lightDir?: Vec2;
+}
+/** The face-shade scalars the FACE composite reads (the numeric-parity witness — FOLD B/C/D). */
+export interface LiquidGridFace {
+    /** The crest envelope at the pre-twist driver cc (FOLD A). */
+    env: number;
+    /** The sheet height at the driver cc (= env; the named leaf scalar). */
+    h: number;
+    /** The Lambert slope-shade [0,1] against the fixed key-light. */
+    shade: number;
+    /** The squashed inset-square face coverage [0,1]. */
+    faceCov: number;
+    /** The composited face alpha (FOLD D — face·faceAlpha·fieldAlpha, NO h-term). */
+    faceA: number;
+    /** The ramp parameter mix(shade, h) keying the multi-stop warm-divergent ink (FOLD B). */
+    rampT: number;
+}
+export declare function sampleLiquidGrid(uv: Vec2, t: number, p: LiquidGridSampleParams): {
+    line: number;
+    alpha: number;
+    face: LiquidGridFace;
+};
+/** The grid scale from the view + minor pitch (LARGER cells = smaller scale). */
+export declare function gridScaleFor(viewExtentPx: number, minorPitchPx: number): number;

package/dist/components/liquid-grid/composables/liquidGridGLSetup.d.ts

@@ -0,0 +1,18 @@
+import type { WebGLCanvasFrame } from "../../../composables/glass/webgl/useWebGLCanvas";
+import type { LiquidGridConfig } from "../constants";
+import { type Vec2 } from "./liquidGrid";
+export interface LiquidGridGLSetupDeps {
+    canvas: HTMLCanvasElement;
+    config: LiquidGridConfig;
+    getCursor: () => Vec2;
+    /** The spring-eased traveling-wave envelope amplitude (0..1; PRM → 0). */
+    getAmp: () => number;
+    shouldContinue: () => boolean;
+    /**
+     * The per-frame pointer hook — useLiquidGrid advances the shared pointer field + derives
+     * the transient cursor here (the no-own-rAF discipline). ZERO own rAF.
+     */
+    onFrame?: (timeSec: number) => void;
+}
+/** Build the `setupGL(gl)` callback the `createGpuSubstrate` WebGL2 path invokes. */
+export declare function createLiquidGridGLSetup(deps: LiquidGridGLSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

package/dist/components/liquid-grid/composables/liquidGridWGPUSetup.d.ts

@@ -0,0 +1,21 @@
+import type { WebGPUCanvasFrame } from "../../../composables/glass/webgpu/useWebGPUCanvas";
+import type { LiquidGridConfig } from "../constants";
+import type { Vec2 } from "./liquidGrid";
+export interface LiquidGridWGPUSetupDeps {
+    canvas: HTMLCanvasElement;
+    config: LiquidGridConfig;
+    /** The transient pointer cursor in GRID space — re-read each frame (the cursor swirl). */
+    getCursor: () => Vec2;
+    /** The spring-eased traveling-wave envelope amplitude (0..1; PRM → 0). */
+    getAmp: () => number;
+    /** Demand-gate (the renderer's quiescence layer — substrate-agnostic). */
+    shouldContinue: () => boolean;
+    /**
+     * The per-frame pointer hook — useLiquidGrid advances the shared `usePointerVelocityField`
+     * here (the no-own-rAF discipline: the renderer's frame loop FEEDS `tick(delta)`) and
+     * derives the transient cursor. ZERO own rAF.
+     */
+    onFrame?: (timeSec: number) => void;
+}
+/** Build the liquid-grid `setupWGPU(device, context, format)` callback. */
+export declare function createLiquidGridWGPUSetup(deps: LiquidGridWGPUSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;

package/dist/components/liquid-grid/composables/uniformBridgeWGPU.d.ts

@@ -0,0 +1,16 @@
+import type { LiquidGridConfig } from "../constants";
+import type { Vec2 } from "./liquidGrid";
+export declare const LIQUID_GRID_UNIFORM_BYTES = 224;
+export interface LiquidGridUniformScratch {
+    buffer: ArrayBuffer;
+    f32: Float32Array;
+}
+export declare function createLiquidGridScratch(): LiquidGridUniformScratch;
+/**
+ * Pack the liquid-grid uniforms in place. `viewExtentPx` is the canvas backing-store extent
+ * the grid scale derives from (so the cell pitch is honest in device px); `cursor` is the
+ * transient pointer in GRID space (the renderer derives it from `usePointerVelocityField`);
+ * `aspect` corrects the domain x. The line ink resolves the warm `--foreground` identity
+ * (the demo themes it via a preset, never a token edit).
+ */
+export declare function packLiquidGridUniforms(scratch: LiquidGridUniformScratch, config: LiquidGridConfig, timeSec: number, aspect: number, viewExtentPx: number, cursor: Vec2, amp: number): LiquidGridUniformScratch;

package/dist/components/liquid-grid/composables/useLiquidGrid.d.ts

@@ -0,0 +1,31 @@
+import { type Ref } from "vue";
+import { type GpuBackend } from "../../../composables/glass/webgpu/useGpuSubstrate";
+import type { LiquidGridConfig } from "../constants";
+export interface UseLiquidGridOptions {
+    config: LiquidGridConfig;
+    /** `"capture"` → renderAt-only (the deterministic π capture path). Default `"live"`. */
+    mode?: "live" | "capture";
+}
+/** The uniform handle a consumer wires its lifecycle against (backend-agnostic). */
+export interface LiquidGridHandle {
+    /** The resolved backend (`"webgpu"` where supported, else the WebGL2 GLSL fallback). */
+    readonly backend: GpuBackend;
+    /** Park the loop (the WCAG-2.2.2 pause seam — `DockBackgroundToggle` wires this). */
+    pause: () => void;
+    /** Re-arm the loop. */
+    resume: () => void;
+    /** Re-arm a parked loop on demand (a pointer that re-introduced motion). */
+    wake: () => void;
+    /** Draw one frame out-of-loop (capture / thumbnail). */
+    renderAt: (timeSec: number) => void;
+    /** The live `prefers-reduced-motion: reduce` state. */
+    readonly reducedMotion: boolean;
+    /** Tear down the renderer + release GPU/GL resources. */
+    dispose: () => void;
+}
+/**
+ * Mount the liquid-grid renderer on `canvasRef`. The WebGPU primary + the WebGL2 fallback are
+ * BOTH pure fullscreen fragment passes evaluating the SAME liquid grid (the ONE math source
+ * `liquidGrid.ts`), so the picker is the only seam. Returns the uniform lifecycle handle.
+ */
+export declare function useLiquidGrid(canvasRef: Ref<HTMLCanvasElement | null>, options: UseLiquidGridOptions): LiquidGridHandle;

package/dist/components/liquid-grid/constants.d.ts

@@ -0,0 +1,93 @@
+import type { OklchStop } from "../../composables/color";
+/** The WGSL `#define` cap mirror (the grid is a fullscreen fragment — no array caps needed). */
+export declare const LIQUID_GRID_MAX_MAJOR_EVERY = 16;
+/**
+ * The full author schema — the studio's `useConfiguratorState` model (commit-on-write — a
+ * single surface). Every field is a tunable the demo configurator drives; the SFC resolves
+ * it into the uniform table.
+ */
+export interface LiquidGridConfig {
+    /** The grid cell pitch in CSS px — LARGER = bigger cells (the user's "LARGER"). */
+    cellSize: number;
+    /** How many minor cells per major rule (the kf `--graph-major` 5rem/1rem ratio). */
+    majorEvery: number;
+    /** Minor line alpha — the calm hairline (≈ kf 3%). */
+    minorAlpha: number;
+    /** Major rule alpha — the bolder tier (kf 11%, above the 10% floor). */
+    majorAlpha: number;
+    /** Line width in device-px — one crisp pixel via Golus AA. */
+    lineWidth: number;
+    /** The affine sheet-warp depth at the crest (grid units — how far the sheet bows/shears). */
+    twistMax: number;
+    /** The traveling-wave front direction (a gentle diagonal). */
+    waveDir: [number, number];
+    /** The crest-band spatial frequency (LOW — cells per crest). */
+    waveK: number;
+    /** The front speed (slow — inertia). */
+    waveOmega: number;
+    /** The crest-band width (a localized front, not a global pulse). */
+    waveSigma: number;
+    /** The GLOBAL subtlety knob — 1 demo, ~0.12 suffusion (the site-wide background). */
+    fieldAlpha: number;
+    /** How far the cursor pushes the grid (the local bulge). */
+    bulgeStrength: number;
+    /** The Gaussian falloff radius in CELL units. */
+    bulgeRadius: number;
+    /** Push grid away (repel) or toward (attract) the cursor. */
+    bulgeMode: "repel" | "attract";
+    /** The line ink (the warm `--foreground` identity by default — NEVER teal-on-navy). */
+    lineColor: OklchStop;
+    /**
+     * The filled-FACE opacity — **default `0`** so the face EVAPORATES → byte-identical to the
+     * line-only HEAD render (every `proof:viz-papergrid` cage clause + the warm-identity fence
+     * stay GREEN). The demo `LIQUID_GRID_PRESET_RIPPLE` lifts it (presets-in-consumers).
+     */
+    faceAlpha: number;
+    /** The slope-shade gain (the ∇H Lambert relief — higher = steeper crest/trough contrast). */
+    faceRelief: number;
+    /** The volume-preserving SQUASH: the plateau inset retreats at the crest so the face inflates. */
+    squashK: number;
+    /** The base inset-square coverage (the soft tile inside the warped cell, 0..0.5 grid units). */
+    baseInset: number;
+    /**
+     * The 3-stop warm-DIVERGENT face ramp (FOLD B — height-keyed, NOT a 2-point mid-park `mix`):
+     * trough → mid → crest. ALL hues ∈ [20,90] (rose-umber → ember/amber → warm-wheat) so the
+     * teal-navy purge is clear by construction. `proof:viz-papergrid` clause reds a hue ∈ [180,280].
+     */
+    faceWarmLo: OklchStop;
+    faceWarmMid: OklchStop;
+    faceWarmHi: OklchStop;
+    /** The fixed cel key-light direction (upper-right) the slope-shade Lamberts against. */
+    lightDir: [number, number];
+    /** The ground (default transparent so it suffuses over the page). */
+    background: OklchStop | "transparent";
+    /** Pointer bulge (§4/§8) — on (demo) / off (suffusion). */
+    interactive: boolean;
+    /** ONE static frame then park under `prefers-reduced-motion: reduce`. */
+    respectReducedMotion: boolean;
+}
+/**
+ * The warm-cream identity line ink (the library default — NOT a themed hue). A warm-amber
+ * ink in the `--foreground` family (OKLab hue ~62, the BA.W-NO-GRAY warm identity) so the
+ * grid reads as warm ink over the page; the SFC resolves the live `--foreground` token at
+ * mount, this stop is the SSR/no-token fallback identity. A consumer (the demo) themes it
+ * through a PRESET, never a token edit. NEVER teal/navy (h in [180,280] reds P5).
+ */
+export declare const WARM_IDENTITY_INK: OklchStop;
+/**
+ * The library-default FACE ramp stops — a CALM warm-divergent fold the face would paint IF lit
+ * (the `faceAlpha:0` default keeps the face evaporated, so these never paint at HEAD; they are
+ * the warm-identity SSR fallback the vivid demo preset overrides). ALL hues ∈ [20,90] — the
+ * teal-navy purge clear by construction (`proof:viz-papergrid` reds a hue ∈ [180,280] here).
+ *   trough → rose-umber, mid → ember-amber, crest → warm-wheat.
+ */
+export declare const FACE_WARM_LO: OklchStop;
+export declare const FACE_WARM_MID: OklchStop;
+export declare const FACE_WARM_HI: OklchStop;
+/**
+ * The shipped warm-identity default config — evenly-spaced, LARGE 64px cells, a crisp fine
+ * rule with a bolder major rule every 5 cells, on a slowly breathing liquid curl-flow sheet
+ * (research/viz/paper-grid.md §6). SUBTLE + LARGE + evenly-spaced — the user's binding
+ * aesthetic. `fieldAlpha: 1` is the demo lead; the suffusion preset drops it to ~0.12.
+ */
+export declare const DEFAULT_LIQUID_GRID_CONFIG: LiquidGridConfig;

package/dist/components/liquid-grid/index.d.ts

@@ -0,0 +1,5 @@
+export { default as LiquidGrid } from "./LiquidGrid.vue";
+export { useLiquidGrid, type LiquidGridHandle, type UseLiquidGridOptions, } from "./composables/useLiquidGrid";
+export { type LiquidGridConfig, DEFAULT_LIQUID_GRID_CONFIG, WARM_IDENTITY_INK, FACE_WARM_LO, FACE_WARM_MID, FACE_WARM_HI, LIQUID_GRID_MAX_MAJOR_EVERY, } from "./constants";
+export { type Vec2, type LiquidGridSampleParams, type LiquidGridFace, potentialFBM, curlFBM, gridCoverage, sampleLiquidGrid, gridScaleFor, CURL_EPS, } from "./composables/liquidGrid";
+export type { OklchStop } from "../../composables/color";

package/dist/components/liquid-grid/shaders/liquid-grid.glsl.d.ts

@@ -0,0 +1,4 @@
+/** The full-screen-triangle vertex shader (the substrate's standard fullscreen pass). */
+export declare const LIQUID_GRID_VERT_GLSL = "#version 300 es\nprecision highp float;\nin vec2 aPosition;\nout vec2 vUv;\nvoid main() {\n  vUv = aPosition;            // [-1,1]\u00B2 domain\n  gl_Position = vec4(aPosition, 0.0, 1.0);\n}";
+/** The liquid-grid fragment source — the liquid AA-grid (the same field as the WGSL primary). */
+export declare const LIQUID_GRID_FRAG_GLSL = "#version 300 es\nprecision highp float;\n\n#define TAU 6.283185307179586\n\nin vec2 vUv;\nout vec4 fragColor;\n\nuniform float uTime;\nuniform float uGridScale;\nuniform float uMajorEvery;\nuniform float uAspect;\nuniform vec4  uWarp;          // (warpScale, warpSpeed, warpScale2, warpSpeed2)\nuniform float uAmplitude;\nuniform vec4  uGrid;          // (targetWidth, targetWidthMajor, minorAlpha, majorAlpha)\nuniform float uFieldAlpha;\nuniform float uHasBackground;\nuniform vec4  uCursor;        // (cursorX, cursorY, swirlStrength, swirlRadius)\nuniform float uBulgeMode;     // +1 repel / \u22121 attract (signs the swirl)\nuniform float uInteractive;   // 1 = cursor swirl on\nuniform vec4  uWave;          // (waveDirX, waveDirY, waveK, waveOmega)\nuniform vec4  uWave2;         // (waveSigma, twistMax, _pad, amp) \u2014 affine sheet-warp envelope\nuniform vec3  uLineColor;     // linear-sRGB ink\nuniform vec3  uBg;            // linear-sRGB themed bg\n// \u2500\u2500 The FACE (BD.W-PAPERGRID-FACE) \u2014 the height-lit filled cell interior \u2500\u2500\nuniform vec4  uFace;          // (faceAlpha, faceRelief, squashK, baseInset)\nuniform vec2  uLightDir;      // the cel key-light direction\nuniform vec3  uFaceLo;        // linear-sRGB rose-umber trough (FOLD B, 3-stop)\nuniform vec3  uFaceMid;       // linear-sRGB ember-amber mid\nuniform vec3  uFaceHi;        // linear-sRGB warm-wheat crest\n\n\nfloat srgbToLinearCh(float c) {\n    return c <= 0.04045 ? c / 12.92 : pow((c + 0.055) / 1.055, 2.4);\n}\nvec3 srgbToLinear(vec3 c) {\n    return vec3(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfloat linearToSrgbCh(float c) {\n    return c <= 0.0031308 ? c * 12.92 : 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nvec3 linearToSrgb(vec3 c) {\n    return vec3(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// The 3-stop warm-divergent FACE ramp (FOLD B \u2014 height-keyed, NOT a 2-point mid-park). All stops\n// warm hue \u2208 [20,90]; linear-space (the OETF runs in main, FOLD E).\nvec3 faceRamp(float rampT) {\n  float s = clamp(rampT, 0.0, 1.0);\n  if (s < 0.5) {\n    return mix(uFaceLo, uFaceMid, s * 2.0);\n  }\n  return mix(uFaceMid, uFaceHi, (s - 0.5) * 2.0);\n}\n\n// The shared divergence-free 2D-curl operator (flow.glsl.ts) \u2014 the prototype declares\n// potentialFBM; the host defines its BODY below the splice (GLSL forward-declaration).\n\nconst float CURL_EPS = 0.012;\n\n// Scalar fbm potential psi \u2014 the host's noise basis, wrapped so the curl operator is\n// basis-agnostic. A host carrying its own fbm defines this as: return fbm(p);\nfloat potentialFBM(vec2 p);\n\n// \u2207\u00D7\u03C8 in 2D \u2014 the divergence-free flow direction. Central finite differences of the\n// scalar potential give the partials; the cross-pairing (\u2202y, \u2212\u2202x) is the 2D curl.\nvec2 curlFBM(vec2 p) {\n  float dx = potentialFBM(p + vec2(CURL_EPS, 0.0)) - potentialFBM(p - vec2(CURL_EPS, 0.0));\n  float dy = potentialFBM(p + vec2(0.0, CURL_EPS)) - potentialFBM(p - vec2(0.0, CURL_EPS));\n  // \u03C8-gradient is (dx, dy)/(2\u00B7eps); the curl rotates it 90\u00B0: (\u2202\u03C8/\u2202y, \u2212\u2202\u03C8/\u2202x).\n  vec2 g = vec2(dx, dy) / (2.0 * CURL_EPS);\n  return vec2(g.y, -g.x);\n}\n\n\n// \u2500\u2500 The host noise basis (transcribes liquidGrid.ts hash21/valueNoise/potentialFBM) \u2500\u2500\nfloat hash21(float x, float y) {\n  float px = fract(x * 0.1031);\n  float py = fract(y * 0.1031);\n  float pz = fract(x * 0.1031);\n  float d = px * (py + 33.33) + py * (pz + 33.33) + pz * (px + 33.33);\n  px += d;\n  py += d;\n  pz += d;\n  return fract((px + py) * pz);\n}\n\nfloat valueNoise(float x, float y) {\n  float ix = floor(x);\n  float iy = floor(y);\n  float fx = x - ix;\n  float fy = y - iy;\n  float ux = fx * fx * fx * (fx * (fx * 6.0 - 15.0) + 10.0);\n  float uy = fy * fy * fy * (fy * (fy * 6.0 - 15.0) + 10.0);\n  float a = hash21(ix, iy);\n  float b = hash21(ix + 1.0, iy);\n  float c = hash21(ix, iy + 1.0);\n  float d2 = hash21(ix + 1.0, iy + 1.0);\n  return mix(mix(a, b, ux), mix(c, d2, ux), uy);\n}\n\n// The 3-octave scalar fbm potential \u2014 the curl chunk's forward-declared potentialFBM body.\nfloat potentialFBM(vec2 p) {\n  float v = 0.0;\n  float amp = 0.5;\n  float freq = 1.0;\n  float px = p.x;\n  float py = p.y;\n  for (int i = 0; i < 3; i++) {\n    v += amp * valueNoise(px * freq, py * freq);\n    // FBM_ROT mat2(0.8, 0.6, -0.6, 0.8) \u2014 same rotation as the shared chunk.\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 shared traveling-wave WARP chunk (waveField.glsl.ts \u2014 waveFlow/cursorSwirl/\n// travelingEnvelope + the FACE leaf; spliced AFTER valueNoise + potentialFBM bodies + the curlFBM\n// chunk). liquid-grid + concentric read the SAME waveFlow continuous affine sheet-warp (the DRY\n// coupling \u2014 a leaf tune moves both, never the retired per-cell twist / LINE-warp).\n\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).\n// BG.W-GRID-AFFINE \u2014 warpFreq is the HOST-supplied curl-sampling spatial frequency (the caller's\n// own coordinate units): an order of magnitude BELOW its grid frequency so the warp is locally\n// affine (major lines bow as ONE smooth curve, no sub-cell crackle). liquid-grid (cell-scale g0)\n// passes ~0.03; concentric (unit-scale p) passes 0.6. The 1.833333 second-flow ratio transcribes\n// WAVE_FLOW_SECOND_RATIO. Amplitude unchanged \u2014 curl magnitude is the intrinsic gradient at the\n// fixed CURL_EPS, independent of warpFreq; the t-drift is host-agnostic.\nvec2 waveFlow(vec2 g, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma,\n              float twistMax, float amp, float warpFreq) {\n  float env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  vec2 f = curlFBM(vec2(g.x * warpFreq + t * 0.05, g.y * warpFreq - t * 0.04));\n  float wf2 = warpFreq * 1.833333;\n  vec2 f2 = curlFBM(vec2(g.x * wf2 - t * 0.03, g.y * wf2 + 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\n\n// \u2500\u2500 \u00A71 The Ben Golus derivative-AA grid coverage (transcribes liquidGrid.ts gridCoverage) \u2500\u2500\nfloat gridCoverage(vec2 g, float targetWidth, vec2 uvDeriv) {\n  vec2 gridUV = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  vec2 drawWidth = clamp(vec2(targetWidth), uvDeriv, vec2(0.5));\n  vec2 lineAA = uvDeriv * 1.5;\n  vec2 grid2 = smoothstep(drawWidth + lineAA, drawWidth - lineAA, gridUV);\n  grid2 *= clamp(vec2(targetWidth) / max(drawWidth, vec2(1e-6)), vec2(0.0), vec2(1.0));\n  grid2 = mix(grid2, vec2(targetWidth), clamp(uvDeriv * 2.0 - 1.0, vec2(0.0), vec2(1.0)));\n  return max(grid2.x, grid2.y);\n}\n\nvoid main() {\n  float aspect = max(uAspect, 1e-4);\n  vec2 uv = vec2(vUv.x * aspect, vUv.y);\n\n  // \u00A75 the per-pixel kernel: AFFINE sheet-warp + cursor-swirl the grid coordinate, then two-tier\n  // Golus. waveFlow is the SMOOTH continuous domain transform (the SAME warp concentric reads) \u2014\n  // a low-order curl-flow displacement gated by the traveling wave, locally affine at the cell\n  // scale, so the sheet bows/shears as ONE coherent transform (major lines a single smooth curve,\n  // no per-cell seam); cursorSwirl twists the cells about the finger. The Golus dv reads the FINAL\n  // warped coord (the crisp-line fence survives).\n  vec2 g0 = uv * uGridScale;\n  // BG.W-GRID-AFFINE \u2014 g0 is CELL-scale, so pass the tiny 0.03 curl-sampling frequency (== the JS\n  // LIQUID_GRID_WARP_FREQ) so the warp is locally affine at the cell scale (major lines bow as ONE\n  // smooth curve, no sub-cell crackle). Concentric passes 0.6 (its p is unit-scale).\n  vec2 g = waveFlow(g0, uTime, uWave.xy, uWave.z, uWave.w, uWave2.x, uWave2.y, uWave2.w, 0.03);\n  if (uInteractive > 0.5) {\n    g = cursorSwirl(g, uCursor.xy, uCursor.z * uBulgeMode, uCursor.w);\n  }\n\n  // The screen-space derivative of g (Golus): length(vec2(dFdx, dFdy)) per axis (the actual\n  // backing-store pixel \u2014 NOT a CSS sub-pixel, the blur-kill).\n  vec2 dv = vec2(\n    length(vec2(dFdx(g.x), dFdy(g.x))),\n    length(vec2(dFdx(g.y), dFdy(g.y)))\n  );\n\n  float minor = gridCoverage(g, uGrid.x, dv);\n  float me = max(uMajorEvery, 1.0);\n  float major = gridCoverage(g / me, uGrid.y, dv / me);\n  float line = max(minor * uGrid.z, major * uGrid.w);\n\n  // \u2500\u2500 The FACE (BD.W-PAPERGRID-FACE) \u2014 height-lit filled cell interior \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // Sample height/relief at the WARPED-space cell center (floor(g)+0.5, the cell the fragment\n  // lands in under the affine warp); Lambert the \u2207H slope against the fixed cel key-light; squash\n  // the inset so the crest face inflates; multi-stop warm-divergent ramp keyed on mix(shade, h)\n  // (FOLD B); the ink through the production OETF (FOLD E).\n  vec2  cc     = floor(g) + 0.5;\n  float h      = cellHeight(cc, uTime, uWave.xy, uWave.z, uWave.w, uWave2.x, uWave2.w);\n  vec2  grad   = faceRelief(cc, 1.0, uTime, uWave.xy, uWave.z, uWave.w, uWave2.x, uWave2.w);\n  vec3  n      = normalize(vec3(-grad * uFace.y, 1.0));\n  float shade  = clamp(0.5 + dot(n, normalize(vec3(uLightDir, 1.0))) * 0.5, 0.0, 1.0);\n  float inset  = uFace.w * (1.0 - uFace.z * h);            // squash & stretch\n  float face   = facePlateau(g, inset, dv);\n  float rampT  = clamp(shade * 0.5 + h * 0.5, 0.0, 1.0);   // FOLD B \u2014 height-keyed crest\n  vec3  faceInk = clamp(linearToSrgb(faceRamp(rampT)), vec3(0.0), vec3(1.0));\n  float faceA  = face * uFace.x * uFieldAlpha;             // FOLD D \u2014 one field-blend scalar\n\n  vec3 col = clamp(linearToSrgb(uLineColor), vec3(0.0), vec3(1.0));\n  if (uHasBackground > 0.5) {\n    vec3 bg = clamp(linearToSrgb(uBg), vec3(0.0), vec3(1.0));\n    vec3 base = mix(bg, faceInk, faceA);\n    float a = line * uFieldAlpha;\n    fragColor = vec4(mix(base, col, a), 1.0);\n    return;\n  }\n  // transparent ground: the FACE composites UNDER the line, the SOURCE-OVER operator in\n  // PREMULTIPLIED space. faceAlpha:0 \u2192 faceA=0 \u2192 the face term vanishes \u2192 vec4(col\u00B7line, line) =\n  // byte-identical to the HEAD line-only render.\n  vec3 linePremult = (col * line) * uFieldAlpha;          // line layer (the FieldAlpha subtlety)\n  float lineA = line * uFieldAlpha;\n  vec3 facePremult = faceInk * faceA;                     // face layer premultiplied (faceA folds field)\n  vec3 outPremult = linePremult + facePremult * (1.0 - lineA);\n  float a = lineA + faceA * (1.0 - lineA);\n  fragColor = vec4(outPremult, a);  // premultiplied over transparent\n}";

package/dist/components/liquid-grid/shaders/liquid-grid.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const LIQUID_GRID_WGSL = "\nconst TAU: f32 = 6.283185307179586;\n\n// \u2500\u2500 Paper-grid uniforms (the typed-struct source-of-truth \u2014 see uniformBridgeWGPU.ts) \u2500\u2500\nstruct LiquidGridUniforms {\n  // u0: (uTime, uGridScale, uMinorPitch, uMajorEvery)\n  u0: vec4<f32>,\n  // face: (uFaceAlpha, uFaceRelief, uSquashK, uBaseInset) \u2014 the height-lit FACE (re-points the retired warp lane)\n  face: vec4<f32>,\n  // warp2: (uAmplitude, uAspect, uLightDirX, uLightDirY) \u2014 aspect + the cel key-light\n  warp2: vec4<f32>,\n  // grid: (uTargetWidth, uTargetWidthMajor, uMinorAlpha, uMajorAlpha)\n  grid: vec4<f32>,\n  // field: (uFieldAlpha, uHasBackground, _pad, _pad)\n  field: vec4<f32>,\n  // cursor: (uCursorX, uCursorY, uSwirlStrength, uSwirlRadius)\n  cursor: vec4<f32>,\n  // cursor2: (uBulgeMode, uInteractive, _pad, _pad)\n  cursor2: vec4<f32>,\n  // line: (uLineColor.rgb (linear), _pad)\n  line: vec4<f32>,\n  // bg: (uBg.rgb (linear), _pad)\n  bg: vec4<f32>,\n  // wave: (waveDirX, waveDirY, waveK, waveOmega) \u2014 the traveling-wave crest\n  wave: vec4<f32>,\n  // wave2: (waveSigma, twistMax, _pad, amp) \u2014 the affine sheet-warp envelope (amp: spring-eased)\n  wave2: vec4<f32>,\n  // faceLo: (rose-umber trough .rgb (linear), _pad) \u2014 the warm-divergent ramp (FOLD B, 3-stop)\n  faceLo: vec4<f32>,\n  // faceMid: (ember-amber mid .rgb (linear), _pad)\n  faceMid: vec4<f32>,\n  // faceHi: (warm-wheat crest .rgb (linear), _pad)\n  faceHi: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u: LiquidGridUniforms;\n\n\nfn srgbToLinearCh(c: f32) -> f32 {\n  if (c <= 0.04045) { return c / 12.92; }\n  return pow((c + 0.055) / 1.055, 2.4);\n}\nfn srgbToLinear(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfn linearToSrgbCh(c: f32) -> f32 {\n  if (c <= 0.0031308) { return c * 12.92; }\n  return 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nfn linearToSrgb(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// \u2500\u2500 The host noise basis (transcribes liquidGrid.ts hash21/valueNoise/potentialFBM) \u2500\u2500\n// A quintic-faded 2D value-noise fbm potential \u2014 the SAME basis the dot-flow-field carries\n// (so the suite speaks ONE noise basis). DECLARED ABOVE the curl splice (WGSL has no forward\n// declaration \u2014 a function may only call one declared earlier).\nfn hash21(x: f32, y: f32) -> f32 {\n  var px = fract(x * 0.1031);\n  var py = fract(y * 0.1031);\n  var pz = fract(x * 0.1031);\n  let d = px * (py + 33.33) + py * (pz + 33.33) + pz * (px + 33.33);\n  px = px + d;\n  py = py + d;\n  pz = pz + d;\n  return fract((px + py) * pz);\n}\n\nfn valueNoise(x: f32, y: f32) -> f32 {\n  let ix = floor(x);\n  let iy = floor(y);\n  let fx = x - ix;\n  let fy = y - iy;\n  let ux = fx * fx * fx * (fx * (fx * 6.0 - 15.0) + 10.0);\n  let uy = fy * fy * fy * (fy * (fy * 6.0 - 15.0) + 10.0);\n  let a = hash21(ix, iy);\n  let b = hash21(ix + 1.0, iy);\n  let c = hash21(ix, iy + 1.0);\n  let d2 = hash21(ix + 1.0, iy + 1.0);\n  return mix(mix(a, b, ux), mix(c, d2, ux), uy);\n}\n\n// The 3-octave scalar fbm potential \u2014 the host noise basis the curl operator wraps.\nfn potentialFBM(p: vec2f) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var freq = 1.0;\n  var px = p.x;\n  var py = p.y;\n  for (var i = 0; i < 3; i = i + 1) {\n    v = v + amp * valueNoise(px * freq, py * freq);\n    // FBM_ROT mat2(0.8, 0.6, -0.6, 0.8) \u2014 same rotation as the shared chunk.\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 shared divergence-free 2D-curl operator (flow.wgsl.ts \u2014 the FIRST WGSL curl consumer).\n\nconst CURL_EPS: f32 = 0.012;\n\n// \u2207\u00D7\u03C8 in 2D \u2014 the divergence-free flow direction. Central finite differences of the\n// scalar potential give the partials; the cross-pairing (\u2202y, \u2212\u2202x) is the 2D curl.\nfn curlFBM(p: vec2f) -> vec2f {\n  let dx = potentialFBM(p + vec2f(CURL_EPS, 0.0)) - potentialFBM(p - vec2f(CURL_EPS, 0.0));\n  let dy = potentialFBM(p + vec2f(0.0, CURL_EPS)) - potentialFBM(p - vec2f(0.0, CURL_EPS));\n  // \u03C8-gradient is (dx, dy)/(2\u00B7eps); the curl rotates it 90\u00B0: (\u2202\u03C8/\u2202y, \u2212\u2202\u03C8/\u2202x).\n  let g = vec2f(dx, dy) / (2.0 * CURL_EPS);\n  return vec2f(g.y, -g.x);\n}\n\n\n// The shared traveling-wave WARP chunk (waveField.wgsl.ts \u2014 waveFlow/cursorSwirl/\n// travelingEnvelope + the FACE leaf; splices AFTER valueNoise + curlFBM are declared). liquid-grid\n// + concentric read the SAME waveFlow continuous affine sheet-warp (the DRY coupling \u2014 a leaf\n// tune moves both).\n\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).\n// BG.W-GRID-AFFINE \u2014 warpFreq is the HOST-supplied curl-sampling spatial frequency (the caller's\n// own coordinate units): an order of magnitude BELOW its grid frequency so the warp is locally\n// affine (major lines bow as ONE smooth curve, no sub-cell crackle). liquid-grid (cell-scale g0)\n// passes ~0.03; concentric (unit-scale p) passes 0.6. The 1.833333 second-flow ratio transcribes\n// WAVE_FLOW_SECOND_RATIO. Amplitude unchanged \u2014 curl magnitude is the intrinsic gradient at the\n// fixed CURL_EPS, independent of warpFreq; the t-drift is host-agnostic.\nfn waveFlow(g: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32,\n            twistMax: f32, amp: f32, warpFreq: f32) -> vec2f {\n  let env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  let f = curlFBM(vec2f(g.x * warpFreq + t * 0.05, g.y * warpFreq - t * 0.04));\n  let wf2 = warpFreq * 1.833333;\n  let f2 = curlFBM(vec2f(g.x * wf2 - t * 0.03, g.y * wf2 + 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\n\n// \u2500\u2500 \u00A71 The crisp line: Ben Golus derivative-AA grid coverage (transcribes gridCoverage) \u2500\u2500\n// targetWidth is the line half-width in GRID UNITS (lineWidthPx / minorPitchPx); uvDeriv is\n// the per-axis screen-space derivative of g (length(vec2(dpdx, dpdy)) per axis). Returns\n// line coverage [0..1] \u2014 exactly N device-pixels wide at ANY DPR/zoom (the blur-kill).\nfn gridCoverage(g: vec2f, targetWidth: f32, uvDeriv: vec2f) -> f32 {\n  // triangle wave per axis: 0 at a line, 1 at the cell center.\n  let gridUV = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  let drawWidth = clamp(vec2f(targetWidth), uvDeriv, vec2f(0.5));\n  let lineAA = uvDeriv * 1.5;\n  // smoothstep with edge0 > edge1 (Golus) \u2192 a falling edge.\n  var grid2 = smoothstep(drawWidth + lineAA, drawWidth - lineAA, gridUV);\n  // preserve thin-line intensity where the line is sub-drawWidth.\n  grid2 = grid2 * clamp(vec2f(targetWidth) / max(drawWidth, vec2f(1e-6)), vec2f(0.0), vec2f(1.0));\n  // Moir\u00E9 suppression: fade toward the average where the cell packs tighter than a pixel.\n  grid2 = mix(grid2, vec2f(targetWidth), clamp(uvDeriv * 2.0 - 1.0, vec2f(0.0), vec2f(1.0)));\n  return max(grid2.x, grid2.y);\n}\n\n// \u2500\u2500 The 3-stop warm-divergent FACE ramp (FOLD B \u2014 height-keyed, NOT a 2-point mid-park) \u2500\u2500\n// trough (faceLo) \u2192 mid (faceMid) \u2192 crest (faceHi), keyed on rampT = mix(shade, h). All stops\n// are warm hue \u2208 [20,90] (the teal-navy purge clear by construction). Linear-space stops; the\n// fs_main routes the result through the production OETF (FOLD E).\nfn faceRamp(rampT: f32) -> vec3f {\n  let s = clamp(rampT, 0.0, 1.0);\n  if (s < 0.5) {\n    return mix(u.faceLo.rgb, u.faceMid.rgb, s * 2.0);\n  }\n  return mix(u.faceMid.rgb, u.faceHi.rgb, (s - 0.5) * 2.0);\n}\n\n// Full-screen-triangle (the pilot idiom): NDC corners (-1,-1),(3,-1),(-1,3) cover the\n// viewport from a single 3-vertex draw \u2014 no vertex buffer.\nstruct VSOut {\n  @builtin(position) pos: vec4f,\n  @location(0) uv: vec2f,  // domain [-1,1]\u00B2, aspect-corrected x\n};\n\n@vertex\nfn vs_main(@builtin(vertex_index) vi: u32) -> VSOut {\n  var corners = array<vec2f, 3>(\n    vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0),\n  );\n  let c = corners[vi];\n  var out: VSOut;\n  out.pos = vec4f(c, 0.0, 1.0);\n  out.uv = vec2f(c.x, c.y);\n  return out;\n}\n\n@fragment\nfn fs_main(in: VSOut) -> @location(0) vec4f {\n  let aspect = max(u.warp2.y, 1e-4);\n  // aspect-correct the domain x so the cells read square.\n  let uv = vec2f(in.uv.x * aspect, in.uv.y);\n  let t = u.u0.x;\n  let gridScale = u.u0.y;\n\n  // \u00A75 the per-pixel kernel: AFFINE sheet-warp + cursor-swirl the grid coordinate, then two-tier\n  // Golus. waveFlow is the SMOOTH continuous domain transform (the SAME warp concentric reads) \u2014\n  // a low-order curl-flow displacement gated by the traveling wave, locally affine at the cell\n  // scale, so the sheet bows/shears as ONE coherent transform (major lines a single smooth curve,\n  // no per-cell seam); cursorSwirl twists the cells about the finger. The Golus dv reads the FINAL\n  // warped coord (the crisp-line fence survives).\n  let g0 = uv * gridScale;\n  // BG.W-GRID-AFFINE \u2014 g0 is CELL-scale, so pass the tiny 0.03 curl-sampling frequency (== the JS\n  // LIQUID_GRID_WARP_FREQ) so the warp is locally affine at the cell scale (major lines bow as ONE\n  // smooth curve, no sub-cell crackle). Concentric passes 0.6 (its p is unit-scale).\n  var g = waveFlow(g0, t, u.wave.xy, u.wave.z, u.wave.w, u.wave2.x, u.wave2.y, u.wave2.w, 0.03);\n  if (u.cursor2.y > 0.5) {\n    // bulgeMode (cursor2.x: +repel / \u2212attract) signs the swirl direction.\n    g = cursorSwirl(g, u.cursor.xy, u.cursor.z * u.cursor2.x, u.cursor.w);\n  }\n\n  // The screen-space derivative of g (Golus): length(vec2(dpdx, dpdy)) per axis. fwidth-class\n  // derivative reads the ACTUAL backing-store pixel (NOT fwidthFine \u2014 Compatibility-Mode safe).\n  let dv = vec2f(\n    length(vec2f(dpdx(g.x), dpdy(g.x))),\n    length(vec2f(dpdx(g.y), dpdy(g.y))),\n  );\n\n  let minor = gridCoverage(g, u.grid.x, dv);\n  // The major tier evals at g / majorEvery with its own derivative scaling.\n  let me = max(u.u0.w, 1.0);\n  let major = gridCoverage(g / me, u.grid.y, dv / me);\n  let line = max(minor * u.grid.z, major * u.grid.w);\n\n  // \u2500\u2500 The FACE (BD.W-PAPERGRID-FACE) \u2014 height-lit filled cell interior \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // Sample height/relief at the WARPED-space cell center (floor(g)+0.5, the cell the fragment\n  // lands in under the affine warp); Lambert the \u2207H slope against the fixed cel key-light; squash\n  // the inset so the crest face inflates; multi-stop warm-divergent ramp keyed on mix(shade, h)\n  // (FOLD B); the ink through the production OETF (FOLD E).\n  let cc    = floor(g) + vec2f(0.5);\n  let h     = cellHeight(cc, t, u.wave.xy, u.wave.z, u.wave.w, u.wave2.x, u.wave2.w);\n  let grad  = faceRelief(cc, 1.0, t, u.wave.xy, u.wave.z, u.wave.w, u.wave2.x, u.wave2.w);\n  let n     = normalize(vec3f(-grad * u.face.y, 1.0));\n  let shade = clamp(0.5 + dot(n, normalize(vec3f(u.warp2.zw, 1.0))) * 0.5, 0.0, 1.0);\n  let inset = u.face.w * (1.0 - u.face.z * h);            // squash & stretch\n  let face  = facePlateau(g, inset, dv);\n  let rampT = clamp(shade * 0.5 + h * 0.5, 0.0, 1.0);     // FOLD B \u2014 height-keyed crest\n  let faceInk = clamp(linearToSrgb(faceRamp(rampT)), vec3f(0.0), vec3f(1.0));\n  let faceA = face * u.face.x * u.field.x;                // FOLD D \u2014 one field-blend scalar\n\n  let col = clamp(linearToSrgb(u.line.rgb), vec3f(0.0), vec3f(1.0));\n  let hasBg = u.field.y;\n  if (hasBg > 0.5) {\n    // opaque ground: the face fills the cell, the ink over the themed bg, the line on top.\n    let bg = clamp(linearToSrgb(u.bg.rgb), vec3f(0.0), vec3f(1.0));\n    let base = mix(bg, faceInk, faceA);\n    let a = line * u.field.x;\n    let outRgb = mix(base, col, a);\n    return vec4f(outRgb, 1.0);\n  }\n  // transparent ground: the FACE composites UNDER the line, the SOURCE-OVER operator in\n  // PREMULTIPLIED space (the page reads through the gutters). faceAlpha:0 \u2192 faceA=0 \u2192 the face\n  // term vanishes \u2192 vec4f(col\u00B7line, line) = byte-identical to the HEAD line-only render.\n  let linePremult = (col * line) * u.field.x;            // line layer (the FieldAlpha global subtlety)\n  let lineA = line * u.field.x;\n  let facePremult = faceInk * faceA;                     // face layer premultiplied (faceA folds field.x)\n  let outPremult = linePremult + facePremult * (1.0 - lineA);\n  let a = lineA + faceA * (1.0 - lineA);\n  return vec4f(outPremult, a);                           // premultiplied over transparent\n}\n";

package/dist/components/metric-badge/MetricBadge.vue.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes } from 'vue';
+import { type MetricValue } from "../metric/coalesce-metric";
+export type MetricBadgeSize = 'sm' | 'md' | 'lg' | 'xl';
+export type MetricBadgeLabelPosition = 'inline' | 'stacked';
+export interface MetricBadgeProps {
+    /** The primary metric. A valid `0` renders `"0"`, never the placeholder. */
+    value: MetricValue;
+    unit?: string;
+    /** Full annotation slot, rendered as a sibling `<span>` with classnames
+     *  `metric-badge__label metric-badge__label--full`. Tracked uppercase,
+     *  muted. */
+    label?: string;
+    /** Compact form of `label`, rendered as a SIBLING `<span>` with
+     *  classnames `metric-badge__label metric-badge__label--abbr`. When both
+     *  `label` and `abbreviation` are set the library renders BOTH siblings;
+     *  consumer container-query CSS toggles which is visible (default:
+     *  `--full` shown, `--abbr` hidden — see utilities.css). The library
+     *  itself never branches on viewport. R2-spec. */
+    abbreviation?: string;
+    /** When set, renders the label slot in `inline` (single row, baseline-
+     *  aligned) or `stacked` (column, items flex-start) mode. When unset,
+     *  the label slot does not render even if `label`/`abbreviation` carry
+     *  values. */
+    labelPosition?: MetricBadgeLabelPosition;
+    /** Color applied to the value when it's non-empty. */
+    color?: string;
+    /** Substitute glyph when value is empty (null / undefined / ""). */
+    placeholder?: string;
+    /** Typographic scale. Defaults to `md`. The ladder reads
+     *  sm 11px / md 12px / lg 14px / xl 18px; `xl` is the audacious-poster
+     *  rung (`text-mono-prose` value, `text-prose` unit) for hero
+     *  placements that need to read at chassis distance. */
+    size?: MetricBadgeSize;
+    class?: HTMLAttributes['class'];
+}
+declare const __VLS_export: import("vue").DefineComponent<MetricBadgeProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<MetricBadgeProps> & Readonly<{}>, {
+    size: MetricBadgeSize;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;