@mkbabb/glass-ui 3.13.0 → 4.0.0

package/dist/components/custom/fading-scroll/FadingScroll.vue.d.ts

@@ -0,0 +1,25 @@
+type __VLS_Props = {
+    /** Scroll axis. `"x"` is the horizontal strip, `"y"` the vertical column. Default `"x"`. */
+    axis?: "x" | "y";
+    /** Feather the start edge once scrolled past the start. Default `true`. */
+    fadeStart?: boolean;
+    /** Feather the end edge while trailing overflow remains. Default `true`. */
+    fadeEnd?: boolean;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    axis: "x" | "y";
+    fadeStart: boolean;
+    fadeEnd: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/custom/fading-scroll/composables/useFadingScroll.d.ts

@@ -0,0 +1,31 @@
+import type { MaybeRef, Ref } from "vue";
+export interface UseFadingScrollOptions {
+    /** Scroll axis. `"x"` reads scrollLeft/Width; `"y"` reads scrollTop/Height. Default `"x"`. */
+    axis?: "x" | "y";
+    /** Feather the start edge once scrolled past the start. Default `true`. */
+    fadeStart?: boolean;
+    /** Feather the end edge while trailing overflow remains. Default `true`. */
+    fadeEnd?: boolean;
+}
+export interface UseFadingScrollControls {
+    /** True when this composable is the ACTIVE writer (the native timeline is absent). */
+    readonly active: Readonly<Ref<boolean>>;
+    /** Re-measure the scroll state and rewrite the customs. Safe to call manually. */
+    measure: () => void;
+    /** Detach all listeners/observers. Auto-called on unmount in a component scope. */
+    stop: () => void;
+}
+/**
+ * Drive the per-edge `--fade-start` / `--fade-end` mask-width customs off an
+ * element's live scroll state, the JS fallback for the native `scroll(self)`
+ * timeline. On a supporting engine this attaches NOTHING (the CSS recipe is the
+ * sole writer); on a non-supporting engine it measures `scrollLeft/Top`,
+ * `scrollWidth/Height − clientWidth/Height`, a `ResizeObserver` (the shared
+ * `useResizeObserver` substrate) + a rAF-coalesced `scroll` listener, writing
+ * `--fade-start = --fade-scroll-width` only past `scroll > 0` and `--fade-end`
+ * only while trailing overflow remains. The customs default to `0px` (no
+ * feather) so the at-rest no-overflow edge is SHARP.
+ *
+ * @param target the scroll-port element (the same element the CSS customs apply to)
+ */
+export declare function useFadingScroll(target: MaybeRef<HTMLElement | null>, options?: UseFadingScrollOptions): UseFadingScrollControls;

package/dist/components/custom/fading-scroll/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The module-scope constants for the FadingScroll family — the colocation home
+ * (`proof:colocation`) the dir owes once it carries a complex composable. Both
+ * were promoted out of `composables/useFadingScroll.ts` verbatim.
+ */
+/**
+ * True when the engine genuinely supports a `scroll()` timeline — the CSS recipe
+ * in `utilities/base.css` then owns the visual axis on the compositor and the
+ * `useFadingScroll` composable becomes the inert (non-attaching) path. Module-level
+ * so the feature gate is computed once. (Mirrors `useScrollProgress`'s twin.)
+ */
+export declare const NATIVE_SCROLL_TIMELINE: boolean;
+/**
+ * Tolerance (CSS px) absorbing scroll-snap jitter — `snap-mandatory` parks the
+ * active card a few px off the true start, so the start edge reads as sharp until
+ * the user genuinely scrolls past the first child. Promoted verbatim from the
+ * bespoke `PresetPickerRow` SNAP_TOLERANCE.
+ */
+export declare const SNAP_TOLERANCE = 12;

package/dist/components/custom/fading-scroll/index.d.ts

@@ -0,0 +1,2 @@
+export { default as FadingScroll } from "./FadingScroll.vue";
+export { useFadingScroll, type UseFadingScrollOptions, type UseFadingScrollControls, } from "./composables/useFadingScroll";

package/dist/components/custom/fourier-field/FourierField.vue.d.ts

@@ -38,6 +38,13 @@ type __VLS_Props = {
      *  loudness); clamped [0, 2] — the field's ~2 upper bound lets a hero push
      *  brighter than the recessed default without runaway. */
     intensity?: number;
+    /** OPTIONAL injected clock — a getter returning the loop parameter `t ∈ [0,1)`.
+     *  When BOUND, the render reads `clock()` (a controllable studio clock: pause,
+     *  scrub, speed); when ABSENT (the ambient face), the autonomous
+     *  `(now / durationMs) % 1` frame-time loop is the DEFAULT. `freeze` /
+     *  `prefers-reduced-motion` still short-circuit to `frozenT` regardless — the
+     *  ambient bundle is unchanged. The SOLE additive seam (BA.W-FOURIER-STUDIO). */
+    clock?: () => number;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;

package/dist/components/custom/fourier-field/index.d.ts

@@ -1,6 +1,6 @@
 import type { ColorResolver } from "../../../composables/color";
 export { default as FourierField } from "./FourierField.vue";
-export { comp, positionsAt, dftFromPoints, makeEllipticSpectrum, type BasisComponent, type EllipticSpectrumOptions, } from "./math";
+export { comp, positionsAt, partialSumAt, dftFromPoints, makeEllipticSpectrum, type BasisComponent, type EllipticSpectrumOptions, } from "./math";
 /** The configuration-BUNDLE axis — `hero` (epicycles on, fewer harmonics) vs
  *  `final` (epicycles off, denser). Not a recolour of one curve; one engine,
  *  two presets. */

package/dist/components/custom/fourier-field/math.d.ts

@@ -23,6 +23,23 @@ export declare function comp(index: number, re: number, im: number): BasisCompon
  * carries).
  */
 export declare function positionsAt(components: BasisComponent[], t: number, maxCircles?: number): [number, number][];
+/**
+ * The PARTIAL-SUM curve point at parameter `t` over the FIRST `maxTerms` phasors
+ * — the inverse-DFT truncated summation `Σ_{k<maxTerms} c_k * exp(2*pi*i*k*t)`.
+ * It is {@link positionsAt} truncated at `maxTerms` and read at the FINAL tip:
+ * the single curve POINT (not the whole chain). The truncation axis is the SAME
+ * one `positionsAt`'s `maxCircles` arg drives — `maxCircles` reads the whole
+ * chain truncated, `partialSumAt` reads only its endpoint — so the studio's
+ * N-harmonics slider can draw the assembling chain (`positionsAt(.., N)`) AND the
+ * resolving curve point (`partialSumAt(.., t, N)`) off the ONE axis. Sweeping `t`
+ * over `[0,1)` and joining the points traces the partial-sum CURVE: at `maxTerms`
+ * = 1 a single ellipse, growing toward the full reconstruction as `maxTerms`
+ * climbs to `components.length` (the reference's "watch it sum" beauty).
+ *
+ * `maxTerms` omitted (or ≥ `components.length`) is the full reconstruction — the
+ * same point `positionsAt(components, t)` returns at its final tip.
+ */
+export declare function partialSumAt(components: BasisComponent[], t: number, maxTerms?: number): [number, number];
 /**
  * The forward DFT — the inverse of {@link positionsAt}. Takes a closed sequence
  * of `[x, y]` samples around a curve (treated as the complex signal `x + i·y`,

package/dist/components/custom/glass-panel/GlassPanel.vue.d.ts

@@ -1,4 +1,5 @@
 import { type GlassTier } from "../../../composables/glass/useGlassRenderer";
+import { type Surface } from "../../ui/_shared/useSurfaceAxis";
 /**
  * Surface-tier vocabulary for the CSS rendering branch. Mirrors the v0.8
  * five-rung ladder declared in `tokens.css §8` and consumed by the
@@ -18,6 +19,12 @@ export interface GlassPanelProps {
     chromaticAberration?: boolean;
     /** Glass surface tier for the CSS rendering branch (v0.8 5-rung ladder). */
     variant?: GlassPanelVariant;
+    /** Surface decoration register (BA.W-SURFACE-AXIS) — the SHARED
+     *  {glass·veil·opaque} axis. `glass` (default) renders the variant's plain
+     *  glass rung; `veil` overlays the borderless/rimless text-legibility plate;
+     *  `opaque` sets `--glass-level:0` (the solid-card escape). Orthogonal to
+     *  `variant`/`tier`, exactly as `surface` is on `<Card>`. */
+    surface?: Surface;
     /** Additional classes */
     class?: string;
 }
@@ -27,6 +34,7 @@ type __VLS_Slots = {} & {
 };
 declare const __VLS_base: import("vue").DefineComponent<GlassPanelProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<GlassPanelProps> & Readonly<{}>, {
     variant: GlassPanelVariant;
+    surface: Surface;
     blur: number;
     refraction: number;
     chromaticAberration: boolean;

package/dist/components/custom/goo-blob/composables/useMetaballRenderer.d.ts

@@ -24,10 +24,20 @@ export interface UseMetaballRendererOptions {
     satellites: BlobSatelliteSystem;
     config: BlobConfig;
 }
-/** The renderer's public control surface — pause/resume the demand loop. */
+/** The renderer's public control surface — pause/resume + wake the demand loop. */
 export interface UseMetaballRendererReturn {
     pause: () => void;
     resume: () => void;
+    /**
+     * BA.W-GOO-REDRESS — re-arm the demand-parked loop on demand (the public twin
+     * of the internal `color`/`paletteStops` wake watchers). The SFC's pointer-wake
+     * wire calls this so a first hover over a fully-parked blob (all satellites
+     * orbiting → the AX.W16 quiescence gate has parked the rAF) repaints on the
+     * SAME frame instead of waiting up to an orbit horizon for the next scheduled
+     * satellite wake (root cause 2 / BA-goo-3). It is the EXISTING substrate wake
+     * handle — NO new rAF, NO second wake path (the single-substrate-loop invariant).
+     */
+    wake: () => void;
 }
 /**
  * The GooBlob WebGL renderer — composes the `useWebGLCanvas` substrate (AU.W6).

package/dist/components/custom/goo-blob/constants.d.ts

@@ -42,7 +42,12 @@ export declare const PULSE_OMEGA = 18;
 export declare const PULSE_ZETA = 0.35;
 /** The at-rest epsilon — velocity/position below this is "settled" (the park gate). */
 export declare const REST_EPS = 0.001;
-/** Base satellite opacity. */
+export declare const ORBIT_RANDOM_BASE = 0.85;
+export declare const ORBIT_RANDOM_SPAN = 0.2;
+export declare const SAT_WOBBLE1_BASE = 0.015;
+export declare const SAT_WOBBLE1_SPAN = 0.02;
+export declare const SAT_WOBBLE2_BASE = 0.01;
+export declare const SAT_WOBBLE2_SPAN = 0.015;
 export declare const BASE_OPACITY = 0.75;
 /** Duration (ms) to blend from emerge endpoint into live orbit — eliminates snap. */
 export declare const ORBIT_BLEND_MS = 2000;

package/dist/components/custom/handmark/HandMark.vue.d.ts

@@ -0,0 +1,29 @@
+import type { HandMarkProps } from "./types";
+declare function play(): void;
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<HandMarkProps, {
+    play: typeof play;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<HandMarkProps> & Readonly<{}>, {
+    color: string;
+    seed: number;
+    shape: import("./types").HandShape;
+    animation: import("./types").HandAnimation;
+    appear: "mount" | "visible" | "manual";
+    jagged: boolean;
+    brush: import("./brush").BrushName | Partial<import("./brush").Brush>;
+    drawMs: number;
+    drawDelayMs: number;
+    boilFps: number;
+    boilFrames: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/custom/handmark/brush.d.ts

@@ -0,0 +1,269 @@
+/**
+ * brush.ts — the flat Brush DATA model (the keystone; SPEC §2). Pure data, 0 deps.
+ * ─────────────────────────────────────────────────────────────────────────────
+ * A `Brush` is a plain JSON-serialisable record — twelve scalars, four enums, and
+ * one optional `stamp` function. Every built-in medium is a frozen literal: a
+ * POINT in one continuous parameter space, NOT a class in a taxonomy. The renderer
+ * (`ink.ts`) reads fields — it NEVER branches on instrument name (SPEC §12 acc-1).
+ * Adding a medium = adding one row here; an in-between medium = a spread/lerp.
+ *
+ * Field-count discipline (SPEC §2): resist a 13th scalar per new instrument —
+ * `blend` earned its place only because highlighter genuinely needed `multiply`.
+ *
+ * The shipped register: PEN is the default (clean ink, grain:0 ⇒ no filter); the
+ * CRAYON ships as the proven STROKE-crayon (constant-width offset passes + the
+ * seeded static feTurbulence grain — `ds-crayon-handmark` verdict), i.e.
+ * `ribbon:'stroke'`. The HIGHLIGHTER (BA.W-HANDMARK C-1) ENGAGES `ribbon:'hull'`
+ * — the perfect-freehand variable-width slab the atlas's field delta names — so the
+ * vendored pf body ships whenever the highlighter does (the budget note in the cut
+ * + a `profile:budget` rebaseline).
+ */
+export type BlendMode = "source-over" | "multiply" | "darken" | "screen";
+export interface TaperSpec {
+    /** px the width ramps 0→full at the start (lift-on). */
+    start: number;
+    /** px the width ramps full→0 at the end (lift-off / dry run-out). */
+    end: number;
+    /** out-cubic = the lazy pencil run-out. */
+    ease: "linear" | "out-cubic";
+}
+export interface Brush {
+    /** base stroke diameter, in viewBox units. */
+    weight: number;
+    /** 0..1.4 seeded ±width variance along arc-length. */
+    weightJitter: number;
+    /** -1..1 pressure→width gain (pf `thinning`). */
+    thinning: number;
+    /** lift-on / lift-off ramp. */
+    taper: TaperSpec;
+    /** L2 body strategy: plain stroked <path> | pf filled hull. DEFAULT 'stroke'. */
+    ribbon: "stroke" | "hull";
+    /** 0..1 base alpha. */
+    opacity: number;
+    /** 'source-over' ink | 'multiply' highlighter-behind-text. */
+    blend: BlendMode;
+    /** overdraw count (pen 1 · crayon 2-3). */
+    passes: number;
+    /** 0..1 per-pass alpha falloff (heavy core, light fringe). */
+    passOpacity: number;
+    /** 0..1 paper-through depth — THE master pen↔crayon knob. 0 ⇒ NO filter. */
+    grain: number;
+    /** feTurbulence baseFrequency (high=pencil tooth · low=crayon wax). */
+    grainFreq: number;
+    /** feDisplacementMap edge-fray scale, px. */
+    grainScale: number;
+    /** feTurbulence numOctaves (grain richness). */
+    octaves: number;
+    /** macro tremor → wobbleLinePoints({ roughness }). */
+    roughness: number;
+    /** micro displacement scale (boil amplitude + warp filter). */
+    wobble: number;
+    /** wobble centerline resolution. */
+    segments: number;
+    cap: "round" | "square" | "butt";
+    /** when present, OVERRIDES the built-in ink stage only. */
+    stamp?: StampFn;
+}
+/** SPEC §5 — the arbitrary-brush escape hatch (one optional field, not a framework). */
+export type StampFn = (ctx: {
+    centerline: [number, number][];
+    brush: Brush;
+    rng: () => number;
+    seed: number;
+    length: number;
+    color: string;
+}) => {
+    paths: InkPath[];
+    filterId?: string | null;
+    defs?: string[];
+};
+/** One ink path the renderer emits (shared with ink.ts; declared here to avoid a cycle). */
+export interface InkPath {
+    d: string;
+    fill?: string;
+    stroke?: string;
+    opacity: number;
+    blend: BlendMode;
+    /** geometry finish — bound to the SVG `stroke-linecap` on the path (C-1(d)). */
+    cap?: "round" | "square" | "butt";
+}
+/**
+ * The named points in the continuum. `pen` is the DEFAULT (clean ink, grain:0).
+ * `crayon` is the SHIPPED stroke-crayon (ribbon:'stroke', the static grain filter);
+ * `pencil`/`marker`/`highlighter` round out the spanning set.
+ */
+export declare const BRUSHES: {
+    readonly pen: {
+        readonly weight: 6;
+        readonly weightJitter: 0.1;
+        readonly thinning: 0.15;
+        readonly taper: {
+            readonly start: 14;
+            readonly end: 14;
+            readonly ease: "out-cubic";
+        };
+        readonly ribbon: "stroke";
+        readonly opacity: 1;
+        readonly blend: "source-over";
+        readonly passes: 1;
+        readonly passOpacity: 0;
+        readonly grain: 0;
+        readonly grainFreq: 0.1;
+        readonly grainScale: 0;
+        readonly octaves: 2;
+        readonly roughness: 0.7;
+        readonly wobble: 1.2;
+        readonly segments: 9;
+        readonly cap: "round";
+    };
+    readonly boil: {
+        readonly weight: 5;
+        readonly weightJitter: 0.12;
+        readonly thinning: 0.2;
+        readonly taper: {
+            readonly start: 12;
+            readonly end: 12;
+            readonly ease: "out-cubic";
+        };
+        readonly ribbon: "stroke";
+        readonly opacity: 1;
+        readonly blend: "source-over";
+        readonly passes: 1;
+        readonly passOpacity: 0;
+        readonly grain: 0;
+        readonly grainFreq: 0.1;
+        readonly grainScale: 0;
+        readonly octaves: 2;
+        readonly roughness: 0.9;
+        readonly wobble: 1.4;
+        readonly segments: 14;
+        readonly cap: "round";
+    };
+    readonly pencil: {
+        readonly weight: 3;
+        readonly weightJitter: 0.3;
+        readonly thinning: 0.4;
+        readonly taper: {
+            readonly start: 8;
+            readonly end: 18;
+            readonly ease: "out-cubic";
+        };
+        readonly ribbon: "stroke";
+        readonly opacity: 0.6;
+        readonly blend: "source-over";
+        readonly passes: 1;
+        readonly passOpacity: 0;
+        readonly grain: 0.5;
+        readonly grainFreq: 0.42;
+        readonly grainScale: 1.5;
+        readonly octaves: 3;
+        readonly roughness: 1;
+        readonly wobble: 1.6;
+        readonly segments: 11;
+        readonly cap: "round";
+    };
+    readonly crayon: {
+        readonly weight: 16;
+        readonly weightJitter: 1;
+        readonly thinning: 0.25;
+        readonly taper: {
+            readonly start: 6;
+            readonly end: 6;
+            readonly ease: "linear";
+        };
+        readonly ribbon: "stroke";
+        readonly opacity: 0.8;
+        readonly blend: "source-over";
+        readonly passes: 2;
+        readonly passOpacity: 0.18;
+        readonly grain: 0.85;
+        readonly grainFreq: 0.16;
+        readonly grainScale: 2.6;
+        readonly octaves: 4;
+        readonly roughness: 1.5;
+        readonly wobble: 3;
+        readonly segments: 13;
+        readonly cap: "round";
+    };
+    readonly ring: {
+        readonly weight: 5;
+        readonly weightJitter: 0.6;
+        readonly thinning: 0.3;
+        readonly taper: {
+            readonly start: 8;
+            readonly end: 12;
+            readonly ease: "out-cubic";
+        };
+        readonly ribbon: "stroke";
+        readonly opacity: 0.55;
+        readonly blend: "source-over";
+        readonly passes: 1;
+        readonly passOpacity: 0;
+        readonly grain: 0.7;
+        readonly grainFreq: 0.18;
+        readonly grainScale: 1.8;
+        readonly octaves: 4;
+        readonly roughness: 1.4;
+        readonly wobble: 2.6;
+        readonly segments: 13;
+        readonly cap: "round";
+    };
+    readonly marker: {
+        readonly weight: 12;
+        readonly weightJitter: 0.2;
+        readonly thinning: 0.1;
+        readonly taper: {
+            readonly start: 4;
+            readonly end: 10;
+            readonly ease: "out-cubic";
+        };
+        readonly ribbon: "stroke";
+        readonly opacity: 0.92;
+        readonly blend: "source-over";
+        readonly passes: 1;
+        readonly passOpacity: 0;
+        readonly grain: 0.22;
+        readonly grainFreq: 0.09;
+        readonly grainScale: 1;
+        readonly octaves: 3;
+        readonly roughness: 1;
+        readonly wobble: 2.2;
+        readonly segments: 9;
+        readonly cap: "square";
+    };
+    readonly highlighter: {
+        readonly weight: 26;
+        readonly weightJitter: 0.05;
+        readonly thinning: 0;
+        readonly taper: {
+            readonly start: 6;
+            readonly end: 10;
+            readonly ease: "out-cubic";
+        };
+        readonly ribbon: "hull";
+        readonly opacity: 0.38;
+        readonly blend: "multiply";
+        readonly passes: 1;
+        readonly passOpacity: 0;
+        readonly grain: 0.12;
+        readonly grainFreq: 0.2;
+        readonly grainScale: 1.5;
+        readonly octaves: 2;
+        readonly roughness: 0.5;
+        readonly wobble: 1.4;
+        readonly segments: 9;
+        readonly cap: "square";
+    };
+};
+export type BrushName = keyof typeof BRUSHES;
+/**
+ * Resolution order (KISS, deterministic): preset → object overrides → extra `o`.
+ * A string selects a preset; an object spreads over `pen`. Later wins.
+ */
+export declare const resolveBrush: (b: BrushName | Partial<Brush>, o?: Partial<Brush>) => Brush;
+/**
+ * lerpBrush — the continuum proof (SPEC §12 acc-2). Linearly interpolate the
+ * scalar fields of two brushes; enums/taper/ribbon snap from `a` below 0.5, `b`
+ * at/above. Yields a sensible in-between ("inky crayon"), no NaN.
+ */
+export declare const lerpBrush: (a: Brush, b: Brush, t: number) => Brush;

package/dist/components/custom/handmark/composables/useHandMark.d.ts

@@ -0,0 +1,89 @@
+/**
+ * useHandMark.ts — the headless reactive core (L2/L3/L4; SPEC §9).
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Sits between the props and the SFC template so a future React/web-component skin
+ * reuses L1–L4. It orchestrates: resolve brush → shapeGeom → ink → animation. It
+ * owns NO DOM (the SFC anchors/measures/mounts the filter); it owns the reactive
+ * pipeline + the draw-on / boil state machine.
+ *
+ * Two draw-on mechanisms, picked by a FIELD (never an instrument `if`):
+ *   - clean ink (no grain): `stroke-dashoffset` on `pathLength="1"` — the slides
+ *     recipe, geometry-agnostic, compositor-cheap, no filter to re-raster.
+ *   - grained ink (crayon): a `clip-path: inset()` WIPE — the filter rasters ONCE
+ *     and the reveal mutates only the clip (`ds-crayon-handmark §5.1`). NEVER
+ *     dashoffset under a filter (it would re-raster the graph per frame — the Δ4
+ *     gate).
+ *
+ * PRM: every draw-on collapses to instant (finished static state); boil no-ops
+ * (`useLineBoil.start()` early-returns under reduced motion).
+ */
+import { type Ref } from "vue";
+import { type Brush, type BrushName } from "../brush";
+/**
+ * The boil clock surface the SFC binds — the `useLineBoil` return shape, declared
+ * structurally over glass-ui's OWN `Ref` (pencil-boil ships a nested `@vue`, so its
+ * `Ref` symbol differs; the no-op stub is built with this `ref`, hence the surface
+ * is named here rather than `ReturnType<typeof useLineBoil>`).
+ */
+export interface BoilClock {
+    currentFrame: Ref<number>;
+    start: () => void;
+    stop: () => void;
+}
+import { type ShapeGeom } from "../geometry";
+import { type SVGFragment } from "../ink";
+import type { HandAnimation, HandMarkProps, HandShape, MarkBox } from "../types";
+export interface UseHandMarkInput {
+    brush: BrushName | Partial<Brush>;
+    shape: HandShape;
+    color: string;
+    seed: number;
+    overrides?: Partial<Brush>;
+    animation: HandAnimation;
+    boilFps: number;
+    boilFrames: number;
+    roughness: number | null;
+    segments: number | null;
+    jagged: boolean;
+    /** NATURAL underline morphology (C-2) — procedural off the house-seeded engine. */
+    natural: boolean;
+    box: MarkBox | null;
+    path: string | null;
+    filterId: string;
+    /**
+     * The MEASURED text baseline as a fraction of the `.hm` box height (text-mode
+     * underline anchor). `null` until the SFC measures it (ResizeObserver +
+     * `document.fonts.ready`) — geometry falls back to the legacy constant for that
+     * one pre-measure frame. Ignored in positioned (`box`) mode.
+     */
+    baselineFrac: number | null;
+}
+/**
+ * Normalise raw HandMarkProps (with their defaults applied) into the core input.
+ * `baselineFrac` is the SFC's MEASURED text baseline (text-mode underline anchor) —
+ * passed in (not a prop) because it is a runtime measurement, `null` until measured.
+ */
+export declare function normalizeProps(props: HandMarkProps, filterId: string, baselineFrac?: number | null): UseHandMarkInput;
+export interface HandMarkCore {
+    /** the resolved effective brush vector. */
+    brush: Ref<Brush>;
+    /** the static base geometry (boil re-perturbs THIS). */
+    baseGeom: Ref<ShapeGeom>;
+    /** the live SVG fragment (paths + filter defs). */
+    fragment: Ref<SVGFragment>;
+    /** the live `d` (escape-hatch path > boiled geometry > static base). */
+    pathD: Ref<string>;
+    /** does the brush emit a grain filter? (drives the draw-on mechanism). */
+    grained: Ref<boolean>;
+    /** the draw-on mechanism for this mark: dashoffset (pen) | clip (crayon). */
+    drawKind: Ref<"dashoffset" | "clip">;
+    /** does this animation draw on at all? */
+    draws: Ref<boolean>;
+    /** does this animation boil? */
+    boils: Ref<boolean>;
+    /** the boil clock (a real `useLineBoil` only when the mark boils; else a no-op stub). */
+    boil: BoilClock;
+    /** arm/disarm boil (draw-then-boil holds it until the draw finishes). */
+    boilArmed: Ref<boolean>;
+}
+export declare function useHandMark(input: Ref<UseHandMarkInput>): HandMarkCore;

package/dist/components/custom/handmark/constants.d.ts

@@ -0,0 +1,39 @@
+/**
+ * constants.ts — the marking-space geometry constants (the colocation home).
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The hand-mark family's named geometry constants live here (the AY.W-COLOCATE
+ * convention's `constants.ts` home). geometry.ts + the SFC re-read them by name.
+ */
+/** Marking-space width (the 0..100 × 0..40 viewBox; `preserveAspectRatio="none"`). */
+export declare const VB_W = 100;
+/** Marking-space height. */
+export declare const VB_H = 40;
+/**
+ * The hairline gap, as a fraction of the `.hm` box, between the MEASURED text
+ * baseline and the underline centerline. The underline rides just under the real
+ * glyph bottoms — a hand mark sits a few % of cap-height below the baseline, never
+ * through it (the E1 occlusion root: a constant `y=32` strikethroughs tight-leading
+ * display type because 80% of a `line-height:1.02` box IS the baseline).
+ */
+export declare const UNDERLINE_GAP = 0.06;
+/**
+ * The highlighter LOW-SEAT band (BA.W-HANDMARK C-1(a)). A real highlighter rides
+ * the low two-thirds of the line — the ink sits on the baseline and rises to
+ * ~x-height — NOT the box vertical center the fork shipped. The band centerline
+ * seats at `baselineFrac − HIGHLIGHT_RISE` (raised off the baseline by ~half a
+ * lowercase x-height) so the wide slab (weight 26) covers x-height down to the
+ * baseline. Expressed as a fraction of the `.hm` box, parallel to UNDERLINE_GAP.
+ */
+export declare const HIGHLIGHT_RISE = 0.22;
+/** Pre-measure fallback for the highlight band's low seat (null baselineFrac). */
+export declare const HIGHLIGHT_FALLBACK_FRAC = 0.66;
+/**
+ * Natural-underline morphology (BA.W-HANDMARK C-2). The procedural wobble is
+ * SCALE-RELATIVE: the amplitude is a fraction of the rendered word width (a long
+ * word and a short word wobble in proportion, not the viewBox-stretched-constant
+ * the fork's GlassUnderline shipped). The period count is IRREGULAR — a seeded
+ * pick in [PERIODS_MIN, PERIODS_MAX] — so two seeds differ in hump count, never
+ * identical twins.
+ */
+export declare const PERIODS_MIN = 2;
+export declare const PERIODS_MAX = 4;