@mkbabb/glass-ui 3.12.0 → 4.0.0

package/dist/components/custom/expandable-container/ExpandableContainer.vue.d.ts

@@ -1,3 +1,4 @@
+import { type Surface } from "../../ui/_shared/useSurfaceAxis";
 declare const _default: typeof __VLS_export;
 export default _default;
 declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
@@ -6,20 +7,10 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     expandLabel?: string;
     /** Accessible name for the collapse (exit fullscreen) button. */
     collapseLabel?: string;
-    /**
-     * Opt into the `gl-expand` plate → fullscreen MORPH (D6.c M7). When set,
-     * the inline anchor and the teleported fullscreen surface share ONE
-     * `view-transition-name` (this prop, suffixed by an app-unique `useId()`
-     * so two ExpandableContainers on a page never collide their groups — the
-     * proof:vt-names mandate), and the open/close toggle is wrapped in
-     * `startViewTransition` so the plate's rect MORPHS to the fullscreen rect
-     * (and back) instead of jump-cutting. A passed string namespaces the pair
-     * (e.g. `"chart"`); pass an empty string for a bare `useId()` name.
-     * Omitted (default) ⇒ NO view-transition-name, the legacy instant toggle —
-     * byte-identical to the pre-M7 behaviour. PRM + unsupported engines take
-     * `startViewTransition`'s instant fallback (the open/close still runs).
-     */
-    viewTransitionName?: string;
+    /** Surface decoration register for the fullscreen overlay
+     *  (BA.W-SURFACE-AXIS) — `glass` (default) frosts over the page;
+     *  `opaque` is the solid-wall opt-out; `veil` the borderless plate. */
+    surface?: Surface;
 } & {
     /**
      * Two-way `open` model so consumers can drive fullscreen externally
@@ -27,13 +18,7 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
      * buttons continue to operate without parent wiring.
      */
     open?: boolean;
-}, {
-    anchorEl: Readonly<import("vue").ShallowRef<HTMLElement | null>>;
-    surfaceEl: Readonly<import("vue").ShallowRef<HTMLElement | null>>;
-    expand: () => void;
-    collapse: () => void;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    settle: (fullscreen: boolean) => any;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:open": (value: boolean) => any;
 }, string, import("vue").PublicProps, Readonly<{
     buttonPosition?: "left" | "right";
@@ -41,20 +26,10 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     expandLabel?: string;
     /** Accessible name for the collapse (exit fullscreen) button. */
     collapseLabel?: string;
-    /**
-     * Opt into the `gl-expand` plate → fullscreen MORPH (D6.c M7). When set,
-     * the inline anchor and the teleported fullscreen surface share ONE
-     * `view-transition-name` (this prop, suffixed by an app-unique `useId()`
-     * so two ExpandableContainers on a page never collide their groups — the
-     * proof:vt-names mandate), and the open/close toggle is wrapped in
-     * `startViewTransition` so the plate's rect MORPHS to the fullscreen rect
-     * (and back) instead of jump-cutting. A passed string namespaces the pair
-     * (e.g. `"chart"`); pass an empty string for a bare `useId()` name.
-     * Omitted (default) ⇒ NO view-transition-name, the legacy instant toggle —
-     * byte-identical to the pre-M7 behaviour. PRM + unsupported engines take
-     * `startViewTransition`'s instant fallback (the open/close still runs).
-     */
-    viewTransitionName?: string;
+    /** Surface decoration register for the fullscreen overlay
+     *  (BA.W-SURFACE-AXIS) — `glass` (default) frosts over the page;
+     *  `opaque` is the solid-wall opt-out; `veil` the borderless plate. */
+    surface?: Surface;
 } & {
     /**
      * Two-way `open` model so consumers can drive fullscreen externally
@@ -63,10 +38,9 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
      */
     open?: boolean;
 }> & Readonly<{
-    onSettle?: ((fullscreen: boolean) => any) | undefined;
     "onUpdate:open"?: ((value: boolean) => any) | undefined;
 }>, {
-    viewTransitionName: string;
+    surface: Surface;
     buttonPosition: "left" | "right";
     expandLabel: string;
     collapseLabel: string;
@@ -74,6 +48,10 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     default?: (props: {
         fullscreen: boolean;
     }) => any;
+} & {
+    default?: (props: {
+        fullscreen: boolean;
+    }) => any;
 }>;
 type __VLS_WithSlots<T, S> = T & {
     new (): {

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, 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,40 @@ 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`,
+ * uniformly spaced in the parameter `t ∈ [0, 1)`) and returns the
+ * {@link BasisComponent} spectrum that {@link positionsAt} reconstructs.
+ *
+ * Frequencies run symmetrically around 0 — `0, +1, -1, +2, -2, …` up to the
+ * Nyquist limit — which is the index ordering the epicycle chain wants (the big
+ * low-order phasors first). The DC term (`index 0`) is the curve's centroid; the
+ * caller can subtract it (draw the chain centered) or keep it (draw at the
+ * sampled position).
+ *
+ * General: any point set drives it (a glyph outline, a hand-traced path, a
+ * digitized signature). It is NOT a special case — it is the literal forward
+ * transform whose inverse already ships as `positionsAt`.
+ */
+export declare function dftFromPoints(points: [number, number][]): BasisComponent[];
 /** Tuning for {@link makeEllipticSpectrum}. */
 export interface EllipticSpectrumOptions {
     /**

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

@@ -0,0 +1,54 @@
+export interface VariantPreset {
+    /** Higher-order harmonics layered over the dominant counter-rotating pair. */
+    harmonics: number;
+    /** Peak magnitude of those harmonics relative to the dominant phasor. */
+    harmonicScale: number;
+    /** Draw the nested epicycle circles + arms underneath the curve. */
+    epicycles: boolean;
+    /** Comet-trail capacity (frames of head history). ~1/3 of the period so the
+     *  comet reads as a substantial arc, not a stub (the fourier-analysis bar). */
+    trailLength: number;
+    /** Hue offset (degrees) of the epicycle second hue away from the outline hue. */
+    epicycleHueShift: number;
+    /** Forward-clock period for one full curve traversal, in ms. */
+    durationMs: number;
+    /** A constant per-variant seed used under `freeze` so a capture is deterministic. */
+    frozenSeed: string;
+    /** The parameter `t` of the static best-frame painted under `freeze`. */
+    frozenT: number;
+    /** Comet-trail PEAK alpha (the head segment). The reference trail rides ~0.9
+     *  near-opaque — present, not the prior 0.45 hairline whisper. */
+    peakAlpha: number;
+    /** Trail stroke weight in CSS px (the reference is a BOLD 3.5px stroke, not
+     *  the prior 1.6 hairline). The single biggest faintness lever. */
+    trailWidth: number;
+    /** Head-glow alpha — the STRONGEST layer (head-forward: > peakAlpha). */
+    headGlowAlpha: number;
+    /** Head-glow `shadowBlur` bloom radius, in px. */
+    headGlowBlur: number;
+    /** The comet HEAD DOT radius in CSS px (the reference's glowing tip — a
+     *  saturated core + white highlight + soft halo). 0 disables it. */
+    headDotRadius: number;
+    /** Epicycle scaffolding alphas ÷ peak (hero only; {0,0} disables the scaffold).
+     *  The reference circles/arms are PRESENT (≈0.5/0.75), not the prior 0.18 ghost. */
+    epicycleRatios: {
+        circle: number;
+        arm: number;
+    };
+    /** Epicycle circle / arm stroke weights in CSS px (the reference uses a bold
+     *  ≈2.5/2 chain, the joints carry filled dots). */
+    epicycleWidths: {
+        circle: number;
+        arm: number;
+    };
+    /** Paint the epicycle chain as a rainbow across the spectrum (the
+     *  fourier-analysis signature) vs one analogous second hue. Hero only. */
+    epicycleRainbow: boolean;
+    /** Trail persistence exponent — SOFT (1..2), never the quadratic that kills the body. */
+    trailFadeExp: number;
+    /** Min trail alpha ÷ peak — the body survives, never decays to 0. The
+     *  reference body reads near-uniform; the floor sits HIGH (≈0.35) so the
+     *  comet body has real presence on cream too (the light-mode floor fork). */
+    trailFloor: number;
+}
+export declare const PRESETS: Record<"hero" | "final", VariantPreset>;

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/buildMetaballProgram.d.ts

@@ -0,0 +1,18 @@
+import { type MetaballUniformLocations } from "./uploadBlobUniforms";
+/** The compiled-program handles the renderer closes over + tears down. */
+export interface MetaballProgram {
+    prog: WebGLProgram;
+    vs: WebGLShader;
+    fs: WebGLShader;
+    vao: WebGLVertexArrayObject;
+    buf: WebGLBuffer;
+    locs: MetaballUniformLocations;
+}
+/**
+ * Compile the metaball shader, build the full-quad VAO, and resolve the uniform
+ * location cache on a fresh context. Leaves `BLEND` enabled with the
+ * premultiplied-alpha `(ONE, ONE_MINUS_SRC_ALPHA)` blend func (the source's
+ * setup), `prog` in use, and the VAO bound — the caller's `resize`/`drawFrame`
+ * re-bind as needed.
+ */
+export declare function buildMetaballProgram(gl: WebGL2RenderingContext): MetaballProgram;

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

@@ -0,0 +1,41 @@
+import type { BlobConfig, MoodParams } from "../types";
+import type { BlobPointer } from "./useBlobPointer";
+import type { BlobSatelliteSystem } from "./useBlobSatellites";
+import { MAX_SATS, TRAIL_N, MAX_BLOB_STOPS, POS_SCALE, UNIFORM_NAMES } from "../constants";
+import type { UniformName } from "../constants";
+export { MAX_SATS, TRAIL_N, MAX_BLOB_STOPS, POS_SCALE, UNIFORM_NAMES };
+export type { UniformName };
+/** The cached uniform-location set the GL setup builds once per context. */
+export interface MetaballUniformLocations {
+    U: Record<UniformName, WebGLUniformLocation | null>;
+    satPosLocs: (WebGLUniformLocation | null)[];
+    satRadLocs: (WebGLUniformLocation | null)[];
+    satOpLocs: (WebGLUniformLocation | null)[];
+    trailPosLocs: (WebGLUniformLocation | null)[];
+    trailRadLocs: (WebGLUniformLocation | null)[];
+    paletteLocs: (WebGLUniformLocation | null)[];
+}
+/** The per-frame state the renderer resolves and hands to the upload leaf. */
+export interface BlobFrameState {
+    /** The mood params for this frame (`mood.params.value`). */
+    params: MoodParams;
+    /** The resolved base-color gamma-sRGB triple. */
+    rgb: [number, number, number];
+    /** The tempo-integrated motion clock (ms). */
+    simTimeMs: number;
+    /** The substrate's seconds clock for this frame (the pulse-phase axis). */
+    timeSec: number;
+    /** A CONCRETE → gamma-sRGB triple resolver (the renderer's memoised `/color` leaf). */
+    resolveColor: (css: string) => [number, number, number];
+    /** The Fresnel rim color (CONCRETE — the SFC un-wrapped any var()-token). */
+    rimColor: string;
+    /** The multi-stop palette (CONCRETE strings; EMPTY → falls back to base). */
+    paletteStops: string[];
+}
+/**
+ * Write the resolved frame state into the metaball program's uniforms and issue
+ * the draw call. Pure: it mutates GL state only (the bound program/VAO + the
+ * uniform values) and never reads the renderer's closure. The body is the
+ * byte-identical lift of the prior inline `drawFrame` uniform-upload section.
+ */
+export declare function uploadBlobUniforms(gl: WebGL2RenderingContext, prog: WebGLProgram, vao: WebGLVertexArrayObject, locs: MetaballUniformLocations, canvas: HTMLCanvasElement, config: BlobConfig, pointer: BlobPointer, satellites: BlobSatelliteSystem, frame: BlobFrameState): void;

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

@@ -1,6 +1,7 @@
 import { type Ref } from "vue";
-/** Compile-time trail length — mirrors `TRAIL_N` in metaball.frag.ts. */
-export declare const TRAIL_N = 15;
+import { TRAIL_N } from "../constants";
+/** Compile-time trail length — re-exported from the co-located shape budget (`../constants`). */
+export { TRAIL_N };
 /** A single trail sample — a decaying-radius metaball source the shader smin-merges. */
 export interface TrailSample {
     x: number;
@@ -13,7 +14,7 @@ export interface TrailSample {
  * FRAME-RATE-INDEPENDENT critically-damped spring fed the renderer's per-frame
  * `dtMs` (NOT a fixed-α lerp — the prior `SMOOTH_FACTOR = 0.12` was framerate
  * dependent). The spring is `@mkbabb/keyframes.js` `SpringProgress` driven through
- * its `tick(dt)` seam by the SUBSTRATE's single rAF — it does NOT call
+ * its `tickDt(dtMs)` seam by the SUBSTRATE's single rAF — it does NOT call
  * `SpringProgress.play()` (that would start a parallel rAF, the
  * single-substrate-loop violation `proof:blob-interaction-prm` forbids).
  *

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

@@ -24,14 +24,30 @@ export interface UseMetaballRendererOptions {
     satellites: BlobSatelliteSystem;
     config: BlobConfig;
 }
+/** 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).
  *
  * This module owns ONLY the metaball-specific concerns: compiling the shader,
- * building the quad + uniform cache, and uploading the per-frame uniforms derived
- * from the mood / pointer / satellite systems and the resolved base color. The
- * generic WebGL2 lifecycle — context creation, the suspend/resume model, the
- * demand-driven rAF loop, the tab-visibility owner, the ResizeObserver, and the
+ * building the quad + uniform cache (the `buildMetaballProgram` leaf), and
+ * uploading the per-frame uniforms (the `uploadBlobUniforms` leaf) derived from the
+ * mood / pointer / satellite systems and the resolved base color. The generic
+ * WebGL2 lifecycle — context creation, the suspend/resume model, the demand-driven
+ * rAF loop, the tab-visibility owner, the ResizeObserver, and the
  * webglcontextlost/restored robustness — lives in the substrate; this renderer
  * threads its behaviour through the substrate's
  * `setup`/`frame`/`shouldContinue`/`resize`/`teardown` callbacks. It does NOT call
@@ -43,7 +59,4 @@ export interface UseMetaballRendererOptions {
  * a `var(--token)` — the SFC's `resolveTokenColor` leaf does that BEFORE handing
  * concrete strings here (inv-K-3 seam); the value.js 1×1-canvas DOM probe is gone.
  */
-export declare function useMetaballRenderer(options: UseMetaballRendererOptions): {
-    pause: () => void;
-    resume: () => void;
-};
+export declare function useMetaballRenderer(options: UseMetaballRendererOptions): UseMetaballRendererReturn;

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

@@ -0,0 +1,57 @@
+import type { BlobMood, MoodParams } from "./types";
+/** Compile-time satellite cap — mirrors `uSat*[N]` in metaball.frag.ts. */
+export declare const MAX_SATS = 4;
+/** Compile-time trail length — mirrors the `uTrail*[N]` arrays in metaball.frag.ts. */
+export declare const TRAIL_N = 15;
+/** Compile-time palette cap — mirrors `#define MAX_BLOB_STOPS` in metaball-uniforms.glsl.ts. */
+export declare const MAX_BLOB_STOPS = 4;
+/**
+ * Canvas is CSS-sized 1.6x its layout wrapper (see GooBlob.vue). Positions are in
+ * [-0.5, 0.5] normalized space mapped to canvas UVs. To make the layout footprint
+ * represent the "visible blob region" and have the extra 60% of canvas serve as
+ * overflow margin for satellite orbits, scale all length-like uniforms by
+ * 1/1.6 = 0.625.
+ */
+export declare const POS_SCALE: number;
+/** The full ordered scalar/vector uniform-name list the program builder caches a location per. */
+/** A point in the 2-axis circumplex affect space. */
+export interface AffectPoint {
+    /** Pleasantness, -1 (unpleasant) .. +1 (pleasant). */
+    valence: number;
+    /** Activation, 0 (calm/sleepy) .. 1 (energized/excited). */
+    arousal: number;
+}
+/** The five named moods as POINTS in the {valence, arousal} circumplex. */
+export declare const MOOD_AVA: Record<BlobMood, AffectPoint>;
+/**
+ * Derive the full MoodParams from a {valence, arousal} point. Arousal drives the
+ * motion energy (orbit speed, wobble, pulse rate/amp, noise, the iridescence/SSS
+ * sheen); valence warms the palette (hue range, chroma, brightness) and the
+ * pointer lean. ONE principled surface — the five named moods are samples of it.
+ */
+export declare function paramsFor({ valence, arousal }: AffectPoint): MoodParams;
+/** The resolved per-mood target params (samples of the `paramsFor` surface). */
+export declare const MOOD_TARGETS: Record<BlobMood, MoodParams>;
+/** The per-mood cross-fade duration (ms). */
+export declare const TRANSITION_MS: Record<BlobMood, number>;
+/** Idle timeout (ms of no pointer) after which the blob drifts to `sleepy`. */
+export declare const IDLE_SLEEP_MS = 6000;
+/** Click-impulse spring ring frequency (rad/s). */
+export declare const PULSE_OMEGA = 18;
+/** Click-impulse spring damping (< 1 = underdamped, overshoot-then-settle). */
+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;
+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;
+/** Minimum spacing (ms) between satellite merge events. */
+export declare const MERGE_STAGGER_MS = 3000;
+export declare const UNIFORM_NAMES: readonly ["uResolution", "uTime", "uBaseColor", "uPointer", "uPointerActive", "uPointerAttraction", "uPointerStrength", "uBodyRadius", "uPulsePhase", "uPulseAmp", "uNoiseAmp", "uNoiseFreq", "uNoiseSpeed", "uWarpAmp", "uSmoothK", "uMerge", "uMaxReach", "uLit", "uRimColor", "uLightDir", "uSpecStrength", "uSpecShininess", "uRimPower", "uRimStrength", "uIridescence", "uIridHue", "uIridSpeed", "uSssScale", "uSssPower", "uCoreGlow", "uHueRange", "uSatShift", "uBrightnessShift", "uColorNoiseFreq", "uColorNoiseSpeed", "uStopCount", "uSatCount", "uTrailCount", "uVelocity", "uStretch"];
+export type UniformName = (typeof UNIFORM_NAMES)[number];

package/dist/components/custom/goo-blob/shaders/metaball-uniforms.glsl.d.ts

@@ -0,0 +1 @@
+export declare const METABALL_UNIFORMS_GLSL = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nout vec4 fragColor;\n\nuniform vec2 uResolution;\nuniform float uTime;\nuniform vec3 uBaseColor;\n\n// Multi-stop palette (W11.b) \u2014 2-4 in-family OKLCh stops (uploaded GAMMA sRGB, like\n// uBaseColor). uStopCount <= 1 falls back to uBaseColor (the single-color default,\n// zero regression). MAX_BLOB_STOPS is a compile-time #define.\n#define MAX_BLOB_STOPS 4\nuniform int uStopCount;\nuniform vec3 uPalette[MAX_BLOB_STOPS];\n\n// Pointer\nuniform vec2 uPointer;\nuniform float uPointerActive;\nuniform float uPointerAttraction;\nuniform float uPointerStrength;\n\n// Main body\nuniform float uBodyRadius;\n\n// Pulsation\nuniform float uPulsePhase;\nuniform float uPulseAmp;\n\n// Surface noise\nuniform float uNoiseAmp;\nuniform float uNoiseFreq;\nuniform float uNoiseSpeed;\n\n// Gooey\nuniform float uSmoothK;\nuniform float uMerge;   // 0 = quadratic smin, 1 = circular smin (rounder menisci)\n\n// AX.W16 (arm 5) \u2014 the PRE-FBM bounding-discard radius (UV space). main() early-outs\n// to a transparent write for any fragment OUTSIDE this radius BEFORE the two 3-octave\n// FBM calls + the OKLCh round-trip. The renderer uploads it PADDED by every\n// outward-expanding term (body + eccentric orbit + sat radius + smin band + FBM edge\n// amplitude + click-pulse + a lean/squash safety pad) so it NEVER clips the wet\n// meniscus (IQ: inflate the bound to match any outward op).\nuniform float uMaxReach;\n\n// Membrane \u2014 domain-warp strength on the FBM edge displacement (0 = plain fbm).\nuniform float uWarpAmp;\n\n// Lit glass surface (W9.b) \u2014 gated behind uLit so the flat fill stays default.\nuniform float uLit;             // 0 = flat fill (default), 1 = lit droplet\nuniform vec3 uRimColor;         // Fresnel rim tint (GAMMA sRGB, via the /color leaf)\nuniform vec3 uLightDir;         // normalized light direction (x, y, z)\nuniform float uSpecStrength;    // Blinn-Phong specular weight\nuniform float uSpecShininess;   // specular exponent (16-64, tight glint)\nuniform float uRimPower;        // Fresnel/Schlick exponent (~2-3)\nuniform float uRimStrength;     // Fresnel rim weight\n\n// Iridescence + fake subsurface (W11.a) \u2014 translucent-gel read.\nuniform float uIridescence;     // warm-pearl rim sheen weight (0 = off)\nuniform float uIridHue;         // base hue (radians) the cosine palette biases toward (warm)\nuniform float uIridSpeed;       // animated-thickness scroll for the iridescent t\nuniform float uSssScale;        // fast-SSS back-light weight\nuniform float uSssPower;        // fast-SSS exponent\nuniform float uCoreGlow;        // thickness-driven inner-luminosity lift\n\n// Color perturbation (perceptually uniform \u2014 OKLCh L/C/h)\nuniform float uHueRange;        // degrees of hue swing (converted to radians)\nuniform float uSatShift;        // OKLCh chroma swing\nuniform float uBrightnessShift; // OKLCh lightness bias\nuniform float uColorNoiseFreq;\nuniform float uColorNoiseSpeed;\n\n// Satellites (max 4)\n#define MAX_SATS 4\nuniform int uSatCount;\nuniform vec2 uSatPos[MAX_SATS];\nuniform float uSatRadius[MAX_SATS];\nuniform float uSatOpacity[MAX_SATS];\n\n// Pointer trail (W10) \u2014 a decaying-radius pseudopod toward the cursor. uTrail is a\n// COMPILE-TIME-SIZED array (GLSL ES 3.00 forbids a uniform-sized array) with a\n// DYNAMIC break on uTrailCount, mirroring the satellite loop. Later samples paint\n// smaller metaballs (r *= 1 - i/N) so the trail tapers into a tail.\n#define TRAIL_N 15\nuniform int uTrailCount;\nuniform vec2 uTrailPos[TRAIL_N];\nuniform float uTrailRadius[TRAIL_N];\n\n// Velocity-driven volume-preserving squash-and-stretch (W10).\nuniform vec2 uVelocity;   // smoothed pointer velocity (motion direction + speed)\nuniform float uStretch;   // squash-stretch magnitude (0 = off)\n\nconst float PI = 3.141592653589793;\n";

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

@@ -13,8 +13,10 @@
  * 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 `ribbon:'hull'` perfect-freehand width-variance upgrade
- * is wired but unconsumed — a later field-delta, never a code branch).
+ * `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 {
@@ -82,6 +84,8 @@ export interface InkPath {
     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).
@@ -112,6 +116,29 @@ export declare const BRUSHES: {
         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;
@@ -209,11 +236,11 @@ export declare const BRUSHES: {
         readonly weightJitter: 0.05;
         readonly thinning: 0;
         readonly taper: {
-            readonly start: 0;
-            readonly end: 0;
-            readonly ease: "linear";
+            readonly start: 6;
+            readonly end: 10;
+            readonly ease: "out-cubic";
         };
-        readonly ribbon: "stroke";
+        readonly ribbon: "hull";
         readonly opacity: 0.38;
         readonly blend: "multiply";
         readonly passes: 1;

package/dist/components/custom/handmark/{useHandMark.d.ts → composables/useHandMark.d.ts}

@@ -18,7 +18,7 @@
  * (`useLineBoil.start()` early-returns under reduced motion).
  */
 import { type Ref } from "vue";
-import { type Brush, type BrushName } from "./brush";
+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
@@ -30,9 +30,9 @@ export interface BoilClock {
     start: () => void;
     stop: () => void;
 }
-import { type ShapeGeom } from "./geometry";
-import { type SVGFragment } from "./ink";
-import type { HandAnimation, HandMarkProps, HandShape, MarkBox } from "./types";
+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;
@@ -45,6 +45,8 @@ export interface UseHandMarkInput {
     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;