@mkbabb/glass-ui 4.0.1 → 4.2.0

package/dist/composables/motion/useMorphField.d.ts

@@ -0,0 +1,157 @@
+import { type MaybeRef, type Ref } from "vue";
+/** The five motion VECTORS a signature selects (geometry/motion, never an app name). */
+export type MorphVector = "lateral" | "radial" | "inward" | "axial" | "directed";
+/** The render TIER a morph resolves to (the caps ladder). */
+export type MorphTier = "css" | "svg-goo" | "gpu";
+/** The silhouette a body presents. `capture` = sample its clip-path → SDF (Tier-G, the
+ *  arbitrary-outline element→element morph — HARD-gated on useElementBloom). */
+export type MorphSilhouette = "circle" | "squircle" | "capture";
+/** A measured rectangle (the body endpoints; left/top/width/height in host-local px). */
+export interface MorphFieldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The motion SIGNATURE — DATA, the only thing that distinguishes the morphs. `vector`
+ * picks the geometry; `kRest`/`kPeak` are gap-FRACTIONS (not px) the threshold band
+ * scales by; `neckHold` is how long the neck holds before it pinches; `maxStretch` the
+ * LOW squish cap (the anti-taffy fence).
+ */
+export interface MorphSignature {
+    vector: MorphVector;
+    /** The neck-gap fraction at REST (bodies apart) — the threshold band floor. */
+    kRest: number;
+    /** The neck-gap fraction at the PEAK (bodies near, the gooey waist) — the band ceiling. */
+    kPeak: number;
+    /** How long (0..1 of t) the neck HOLDS its girth before it pinches (the tense pop). */
+    neckHold: number;
+    /** The LOW on-axis squish cap (≤~1.14 — the loud register lives in NECK girth, not body taffy). */
+    maxStretch: number;
+}
+/**
+ * The canonical, motion-named SIGNATURE map (DATA — F3, the FLOOR). Every consumer
+ * passes a `MorphSignatureName`; one weld reads the row; one recipe paints it. NO app
+ * names, NO three code paths.
+ */
+export declare const MORPH_SIGNATURES: {
+    /** carousel / deck / pager goo: two equal beads bud apart, a concave neck wells, the
+     *  filter merges them into one barbell with a thin pinched waist, then they coalesce. */
+    readonly lateralNeck: {
+        readonly vector: "lateral";
+        readonly kRest: 0.92;
+        readonly kPeak: 0.34;
+        readonly neckHold: 0.5;
+        readonly maxStretch: 1.12;
+    };
+    /** dock fission media: the now-playing anchor stays; flanking transport PEELS along
+     *  the cross axis with a long tapering neck tail. */
+    readonly lateralPeel: {
+        readonly vector: "lateral";
+        readonly kRest: 0.88;
+        readonly kPeak: 0.4;
+        readonly neckHold: 0.4;
+        readonly maxStretch: 1.08;
+    };
+    /** dock fission search: controls fly outward like a bloom; the neck NECKS LATE (the
+     *  tense radial pop), innermost-first — an outward ripple, not a simultaneous scatter. */
+    readonly radialBurst: {
+        readonly vector: "radial";
+        readonly kRest: 0.85;
+        readonly kPeak: 0.3;
+        readonly neckHold: 0.55;
+        readonly maxStretch: 1.08;
+    };
+    /** dock fission nav: the negative radial — N masses collapse INWARD to ONE; the bridge
+     *  runs backward; --stretch peaks at coalescence. */
+    readonly inwardMerge: {
+        readonly vector: "inward";
+        readonly kRest: 0.8;
+        readonly kPeak: 0.28;
+        readonly neckHold: 0.35;
+        readonly maxStretch: 1.1;
+    };
+    /** dock V↔H: column-mass + row-mass are two distributions in ONE topology-free field;
+     *  a gooey teardrop LOBS column→row through the midpoint (no crossfade dodge). */
+    readonly axialNeck: {
+        readonly vector: "axial";
+        readonly kRest: 0.9;
+        readonly kPeak: 0.36;
+        readonly neckHold: 0.5;
+        readonly maxStretch: 1.14;
+    };
+    /** dock collapse: the DEGENERATE 1-body field — a single mass squishes between two
+     *  footprints (no waist, Tier-C). The ratio-free convex blend. */
+    readonly collapse: {
+        readonly vector: "axial";
+        readonly kRest: 1;
+        readonly kPeak: 1;
+        readonly neckHold: 0;
+        readonly maxStretch: 1.14;
+    };
+    /** drag morph: a grabbed rect → drop rect, an optional directed neck. */
+    readonly directed: {
+        readonly vector: "directed";
+        readonly kRest: 0.9;
+        readonly kPeak: 0.42;
+        readonly neckHold: 0.45;
+        readonly maxStretch: 1.1;
+    };
+};
+export type MorphSignatureName = keyof typeof MORPH_SIGNATURES;
+/** A warm "body" the field welds — a measured endpoint pair + an optional silhouette. */
+export interface BodySpec {
+    /** The DOM node this body IS (the weld writes its transform). */
+    el: Ref<HTMLElement | null>;
+    /** The body's REST rect (t=0), measured ONCE (dock-core: no per-frame measure). */
+    at0: () => MorphFieldRect;
+    /** The body's TARGET rect (t=1), measured ONCE. */
+    at1: () => MorphFieldRect;
+    /** The body diameter (px). Default `min(width,height)/φ` — a golden-minor BLOB. */
+    radius?: () => number;
+    /** circle (default) / squircle / capture (arbitrary outline → Tier-G, HARD-gated). */
+    silhouette?: MorphSilhouette;
+}
+export interface MorphFieldOptions {
+    /** 1..N warm masses. 1 body = collapse (no weld); 2 = a neck; (1+N) = fission. */
+    bodies: MaybeRef<BodySpec[]>;
+    /** The motion signature NAME (DATA). The weld reads its row from MORPH_SIGNATURES. */
+    signature: MorphSignatureName;
+    /**
+     * The EXISTING drive scalar this weld READS off the host (NO rename). Default
+     * `--goo-t`; dock passes `--dock-morph-t`, fission `--neck-t`. The consumer's
+     * spring/rAF writes it; the weld only samples + projects.
+     */
+    driveVar?: string;
+    /** The host the drive scalar + the dedicated squish channel are read/written on. */
+    hostRef: Ref<HTMLElement | null>;
+    /** The cartoon-weight scalar source. Read live off the host `--motion-weight` if absent. */
+    weight?: MaybeRef<number>;
+    /** The render tier. `auto` (default) resolves from caps + body count + signature. */
+    tier?: MorphTier | "auto";
+    /** Travel axis for the neck span. `false` (default) horizontal, `true` vertical. */
+    vertical?: MaybeRef<boolean>;
+}
+export interface MorphFieldHandle {
+    /** Mirror of the consumer's drive scalar (last sampled). Read-only. */
+    readonly t: Readonly<Ref<number>>;
+    /** The neck waist FRACTION (waist/body) at the current frame — for π readback. */
+    readonly waist: Readonly<Ref<number>>;
+    /** The resolved render tier. */
+    readonly tier: Readonly<Ref<MorphTier>>;
+    /**
+     * PROJECT the field for an explicit drive value `t` (0..1). Reads the masses'
+     * measured endpoints + the signature, writes each body's transform + the welling
+     * neck + the dedicated squish channel + the live waist. The consumer calls this from
+     * its OWN rAF/spring callback (the weld owns no clock).
+     */
+    project(t: number): void;
+    /**
+     * SEAT the endpoint silhouette at `t` with ZERO neck frames (the PRM cut / first
+     * paint). One resting mass at the endpoint, neck hidden, --stretch 1. The consumer's
+     * PRM branch calls this.
+     */
+    seat(t: number): void;
+}
+export declare function useMorphField(opts: MorphFieldOptions): MorphFieldHandle;

package/dist/composables/motion/useScrollChrome.d.ts

@@ -0,0 +1,58 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+export interface UseScrollChromeOptions {
+    /** Opt-in: collapse on scroll. DEFAULT FALSE — persistent-by-default (the iOS-27 lesson). */
+    collapseOnScroll?: boolean;
+    /** The flip-delta debounce (px) before a direction flip commits. Default 8 (the reader's). */
+    flipDeltaPx?: number;
+    /**
+     * Optional velocity gate (px/s): a flick over this collapses/expands IMMEDIATELY,
+     * a slow drag respects the threshold. Default off (undefined).
+     */
+    velocityGate?: number;
+    /** Snap-to-nearest commits past this fraction of the collapse range on scroll-STOP. Default 0.5. */
+    snapMidpoint?: number;
+    /**
+     * The scroll distance over which the chrome travels 0→1 collapsed (px). Default 116
+     * (the citymall headerHeight×2 reference) — the trigger-point span.
+     */
+    collapseRangePx?: number;
+    /**
+     * The chrome element (a dock, a header). When provided, the composable WRITES
+     * `--chrome-collapse-t` onto it directly (the JS leg of the dual-path single-writer)
+     * so the `.scroll-chrome` recipe reads it with no consumer `:style` plumbing. When
+     * absent, the consumer reads the `collapseT` ref and applies it itself.
+     */
+    chromeRef?: MaybeRefOrGetter<HTMLElement | null>;
+    /** Honor `prefers-reduced-motion: reduce` (drop the ramp to a discrete snap). Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * The scroll-STOP debounce window (ms) — the no-tick window after which the snap
+     * commits (the `onMomentumScrollEnd` analogue). Default 140 (a calm post-scroll beat).
+     */
+    scrollStopMs?: number;
+}
+export interface UseScrollChromeReturn {
+    /** 0..1 collapse fraction (drives the consumer's transform/opacity ramp). */
+    collapseT: Ref<number>;
+    /** True once collapseT past snapMidpoint (the discrete state). */
+    collapsed: Ref<boolean>;
+    /** Committed scroll direction (from the reader). */
+    direction: Ref<"down" | "up" | null>;
+    /** Force a re-read + re-evaluate (post-resize). */
+    recalculate: () => void;
+}
+/**
+ * The floating-chrome collapse-state machine. COMPOSES `useScrollTrigger` (the ONE
+ * scroll reader); ramps `collapseT` on direction + `collapseRangePx`; the optional
+ * `velocityGate` short-circuits on a flick; snaps to the nearest endpoint on scroll-stop.
+ * Writes `--chrome-collapse-t` onto `chromeRef` (when given). PERSISTENT by default
+ * (`collapseOnScroll: false`).
+ *
+ * @example
+ * ```ts
+ * const header = ref<HTMLElement | null>(null)
+ * useScrollChrome(() => window, { collapseOnScroll: true, chromeRef: header })
+ * // header.style sets --chrome-collapse-t; the .scroll-chrome recipe reads it.
+ * ```
+ */
+export declare function useScrollChrome(scrollContainer: MaybeRefOrGetter<HTMLElement | Window | null>, opts?: UseScrollChromeOptions): UseScrollChromeReturn;

package/dist/composables/motion/useScrollPin.d.ts

@@ -0,0 +1,49 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import type { ComponentPublicInstance } from "vue";
+import type { ScrollSource } from "./scrollReader";
+export interface UseScrollPinOptions {
+    /**
+     * The tall `.scroll-pin` container (a templateRef to the element or a component). Its
+     * `getBoundingClientRect` gives the pin-slice ratio; `--pin-t` is written onto it (it
+     * `inherits: true` so the sticky stage + phase children read it).
+     */
+    container: MaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null>;
+    /**
+     * The scroll source the pin tracks — the demo passes `main.demo-main-scroller`. Passed
+     * EXPLICITLY (the reader does not auto-discover). Default: the window/document.
+     */
+    source?: MaybeRefOrGetter<ScrollSource>;
+    /**
+     * The pin scrub ∈ [0, 1] — the pin drifts HEAVIER than a control (a scene, not a knob).
+     * Defaults to 1/φ² ≈ 0.382 (the golden heavier-drift rest). PRM → 0.
+     */
+    scrub?: number;
+    /** The spring damping ratio ζ for the felt reveal. < 1 overshoots. Default 0.85. */
+    dampingFraction?: number;
+    /** Honor `prefers-reduced-motion: reduce`. Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseScrollPinReturn {
+    /** The spring-damped 0..1 pin progress (reactive — mirrors `--pin-t`). */
+    pinT: Readonly<Ref<number>>;
+    /** Force a re-read (post-resize). */
+    recalculate: () => void;
+    /** Detach. */
+    dispose: () => void;
+}
+/**
+ * Drive `--pin-t` ∈ [0, 1] onto a sticky `.scroll-pin` stage off the real scroll port,
+ * spring-damped so the pinned reveal arrives with inertia, overshoots, then settles. The
+ * phase recipes (`.scroll-pin-phase-reveal` / `-settle`) read `--pin-t` — no
+ * `animation-timeline`, every engine.
+ *
+ * @example
+ * ```ts
+ * const pinContainer = ref<HTMLElement | null>(null)
+ * useScrollPin({
+ *   container: pinContainer,
+ *   source: () => document.querySelector<HTMLElement>("main.demo-main-scroller"),
+ * })
+ * ```
+ */
+export declare function useScrollPin(options: UseScrollPinOptions): UseScrollPinReturn;

package/dist/composables/motion/useScrollScene.d.ts

@@ -0,0 +1,67 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import { type ScrollReader, type ScrollSource } from "./scrollReader";
+/** The smoother register — a pure-lag low-pass (`SmoothProgress`) or an overshooting
+ *  spring (`SpringProgress`). The FELT reveal wants the spring (it overshoots, then
+ *  settles — the cartoon slam); the pure-lag legs (a progress number) want the smooth. */
+export type ScrollSceneRegister = "smooth" | "spring";
+export interface UseScrollSceneOptions {
+    /**
+     * The scroll source — an element with its own scroll port (the demo passes
+     * `main.demo-main-scroller`), the Window, or null. Resolved by `createScrollReader`:
+     * an HTMLElement listens on itself, else the document/window. Passed EXPLICITLY (the
+     * reader does NOT auto-discover a scroller).
+     */
+    source: MaybeRefOrGetter<ScrollSource>;
+    /**
+     * Map a fresh reader read to the raw 0..1 target this scene tracks. Default: the
+     * reader's own `position()/extent()` extent-relative progress. A pin passes a custom
+     * mapper keyed off a per-tick `getBoundingClientRect` (the pin-slice ratio).
+     */
+    map?: (reader: ScrollReader) => number;
+    /**
+     * The liquid-weight scrub ∈ [0, 1] — how much lag the scroll carries. 0 = a 1:1 snap
+     * (no weight); higher = heavier drift. Defaults to 1/φ ≈ 0.618 (the golden
+     * liquid-weight rest); a call site overrides per scene. PRM → 0. Mapped to the engine
+     * damping by `scrubToDamping` (a STATED function, no magic affine constants).
+     */
+    scrub?: number;
+    /** The smoother register (default `smooth` — the pure-lag low-pass). */
+    register?: ScrollSceneRegister;
+    /**
+     * For the `spring` register: the damping ratio ζ. < 1 overshoots (the felt slam),
+     * 0.85 ≈ the `--spring-gentle` identity. Default 0.85. Ignored for `smooth`.
+     */
+    dampingFraction?: number;
+    /** The element the damped value is written onto as a custom property (when bound). */
+    bindEl?: MaybeRefOrGetter<HTMLElement | null>;
+    /** The custom property name to write the damped 0..1 onto (e.g. `--pin-t`). */
+    property?: string;
+    /** Honor `prefers-reduced-motion: reduce` (scrub → 0, snap 1:1). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseScrollSceneReturn {
+    /** The spring-damped 0..1 progress (reactive). The single writer of every felt axis. */
+    progress: Readonly<Ref<number>>;
+    /** Force a coalesced re-read + re-target now (post-resize / layout shift). */
+    recalculate: () => void;
+    /** Detach the reader + stop the smoother. */
+    dispose: () => void;
+}
+/**
+ * The liquid-weight scroll spine. Composes the ONE `createScrollReader` + a keyframes.js
+ * smoother (`SmoothProgress` / `SpringProgress`); on each coalesced scroll tick it sets the
+ * smoother target to the mapped raw progress; the smoother converges with inertia and keeps
+ * moving after scroll stops (the liquid weight). Writes the damped 0..1 to `progress` + the
+ * optional `property` on `bindEl`.
+ *
+ * @example
+ * ```ts
+ * const { progress } = useScrollScene({
+ *   source: () => document.querySelector<HTMLElement>("main.demo-main-scroller"),
+ *   scrub: 0.618,
+ *   bindEl: stageRef,
+ *   property: "--scroll-t",
+ * })
+ * ```
+ */
+export declare function useScrollScene(options: UseScrollSceneOptions): UseScrollSceneReturn;

package/dist/composables/motion/useScrollTrigger.d.ts

@@ -0,0 +1,67 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+/**
+ * A declared trigger-point on the scroll source: a pixel offset, a 0..1 progress
+ * fraction (resolved against the source's scrollable extent), or a named element
+ * whose top crosses the source.
+ */
+export interface TriggerPoint {
+    /**
+     * A pixel offset on the scroll source, OR a 0..1 progress fraction (resolved
+     * against the source's scrollable extent), OR a named element whose top crosses
+     * the source.
+     */
+    at: number | {
+        fraction: number;
+    } | {
+        element: MaybeRefOrGetter<HTMLElement | null>;
+    };
+    /** Fire on which crossing direction. Default "both". */
+    direction?: "down" | "up" | "both";
+    /** Stable id for the event payload + de-dup. */
+    id?: string;
+}
+export interface UseScrollTriggerOptions {
+    triggers?: TriggerPoint[];
+    /**
+     * The flip-delta debounce (px) before a DIRECTION flip commits — the anti-thrash,
+     * mirroring the dock's HOVER_INTENT_MS=60ms hysteresis. Default 8 (the RN
+     * reference).
+     */
+    flipDeltaPx?: number;
+    /** Resolve the continuous `progress` ref against the source (0..1). Default true. */
+    trackProgress?: boolean;
+    /** Honor `prefers-reduced-motion: reduce` (snap `progress` to discrete endpoints). Default true. */
+    respectReducedMotion?: boolean;
+    /** Crossed a trigger in the committed direction (fires ONCE per crossing). */
+    onCross?: (id: string, dir: "down" | "up", scrollPos: number) => void;
+    /** Crossed a trigger scrolling INTO its region (past it, in `down`). */
+    onEnter?: (id: string) => void;
+    /** Crossed OUT of a trigger's region (back before it, in `up`). */
+    onLeave?: (id: string) => void;
+}
+export interface UseScrollTriggerReturn {
+    /** Continuous 0..1 scroll progress off the SAME rAF read (native-timeline-gated). */
+    progress: Ref<number>;
+    /** Current scroll direction (committed past flipDeltaPx). */
+    direction: Ref<"down" | "up" | null>;
+    /** Current scroll velocity (px/s, framerate-independent — Δpos / Δt). */
+    velocity: Ref<number>;
+    /** Force a re-read + re-evaluate every trigger (post-resize/layout). */
+    recalculate: () => void;
+}
+/**
+ * The ONE scroll reader. Composes `createScrollReader` (the shared rAF-coalesced
+ * core); resolves triggers to px; emits direction/velocity/crossing; native-timeline-
+ * gated continuous ramp.
+ *
+ * @example
+ * ```ts
+ * const { progress, direction, velocity } = useScrollTrigger(() => window, {
+ *   triggers: [{ at: 120, id: "shrink", direction: "down" }],
+ *   onCross(id, dir, pos) {  // fires once when crossing 120px scrolling down
+ *     if (id === "shrink" && dir === "down") collapseChrome()
+ *   },
+ * })
+ * ```
+ */
+export declare function useScrollTrigger(scrollSource: MaybeRefOrGetter<HTMLElement | Window | null>, opts?: UseScrollTriggerOptions): UseScrollTriggerReturn;

package/dist/composables/motion/useSpringPress.d.ts

@@ -1,14 +1,14 @@
 import { type UseSpringOptions, type SpringRef } from "./useSpring";
 export interface UseSpringPressOptions extends UseSpringOptions {
     /**
-     * Spring `response`. Default 0.25s (iOS tap-press canonical; faster
-     * than the default `useSpring` 0.5s to keep press feedback under the
-     * 100ms perception threshold).
+     * Spring `response`. Default `0.15s` — the `press` SPRING_PRESETS row (the
+     * Apple `interactiveSpring`): the sub-100ms iOS tap-press window, faster than
+     * the generic `useSpring` 0.5s so the feedback lands under the 100ms threshold.
      */
     response?: number;
     /**
-     * Spring `dampingFraction`. Default 0.7 (overshoots ~5% — feels
-     * springy but doesn't ring).
+     * Spring `dampingFraction`. Default `0.86` — the `press` row's ζ: a tiny
+     * sub-perceptual rebound (springy/alive) that does NOT ring.
      */
     dampingFraction?: number;
 }

package/dist/composables/motion/useStaggerReveal.d.ts

@@ -25,4 +25,28 @@ export declare function useStaggerReveal(options?: StaggerRevealConfig): {
     register: (el: HTMLElement | null, index?: number) => void;
     revealed: Record<number, boolean>;
 };
+/**
+ * The `[data-scroll-reveal-once]` latch — BC.W-MOTION-PRESETS.
+ *
+ * The `scroll-driven.css` `[data-scroll-reveal]` recipe rides a native `view()`
+ * timeline that RE-FIRES its entrance every time a child re-enters the entry range
+ * — wrong for a virtualized/teleporting list (a row scrolls out + back and re-plays
+ * the fade-lift). A `view()` timeline cannot latch "play once" (the CSS limit), so
+ * the `[data-scroll-reveal-once]` opt-in plays the entrance ONCE: this directive
+ * adds `data-revealed=""` to each child on its FIRST cross and `unobserve`s it (the
+ * SAME `once: true` discipline `useStaggerReveal` runs above — `if (once)
+ * observer?.unobserve(el)`); the CSS plays the one-shot `gl-reveal-once` keyframe
+ * keyed off `[data-revealed]`, NOT the live `view()` range. NO second observer
+ * engine — the same `IntersectionObserver` the composable speaks for the `once`
+ * case, packaged as a Vue directive a consumer binds on the scroller.
+ *
+ * On an engine without `IntersectionObserver` (SSR/old) it reveals immediately so
+ * the terminal state is correct (the CSS animation simply never plays). Under PRM
+ * the scroll-driven.css `@media` outer gate drops the entrance and the row paints
+ * in-place (a flourish — the reveal carve, not a legibility cue).
+ */
+export declare const vScrollRevealOnce: {
+    mounted(scroller: HTMLElement): void;
+    unmounted(scroller: HTMLElement): void;
+};
 export {};

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

@@ -4,4 +4,7 @@ export type { SidebarFollowOptions } from "./useSidebarFollow";
 export { useSidebarState } from "./useSidebarState";
 export type { UseSidebarStateOptions, GenericSidebarState } from "./useSidebarState";
 export { useTreeIndex, buildTreeIndex, isActive, isInActiveChain } from "./useTreeIndex";
-export type { TreeNode, TreeIndexEntry, SidebarSection, SidebarIndexEntry, SidebarState, ScrollTrackerOptions, } from "./types";
+export { useScrollTo } from "./useScrollTo";
+export { useClickDelegate } from "./useClickDelegate";
+export { useLazyLoader } from "./useLazyLoader";
+export type { TreeNode, TreeIndexEntry, SidebarSection, SidebarIndexEntry, SidebarState, ScrollTrackerOptions, ScrollToOptions, ClickDelegateOptions, LazyLoaderOptions, } from "./types";

package/dist/composables/sidebar/types.d.ts

@@ -4,9 +4,13 @@ export interface TreeNode {
     id: string;
     children?: TreeNode[];
 }
-/** Generic flat index entry for a tree node. */
-export interface TreeIndexEntry<T extends TreeNode = TreeNode> {
-    node: T;
+/**
+ * The flat-hierarchy fields shared by every flattened tree row. Both the
+ * sidebar's `TreeIndexEntry` and the virtual-windowing `FlatSection`
+ * (`composables/virtual`) extend this — the four fields are declared ONCE,
+ * not redeclared independently (BC.W-VIRTUAL-WINDOW type-reconcile).
+ */
+export interface SectionHierarchy {
     depth: number;
     /** ID of the root-level ancestor (self.id when depth === 0). */
     rootId: string;
@@ -15,6 +19,10 @@ export interface TreeIndexEntry<T extends TreeNode = TreeNode> {
     /** Index within root-level nodes. */
     rootIndex: number;
 }
+/** Generic flat index entry for a tree node. */
+export interface TreeIndexEntry<T extends TreeNode = TreeNode> extends SectionHierarchy {
+    node: T;
+}
 /** A section in the sidebar tree. */
 export interface SidebarSection extends TreeNode {
     title: string;
@@ -29,6 +37,63 @@ export interface ScrollTrackerOptions {
     rootMargin?: string;
     threshold?: number;
 }
+/**
+ * Options for `useScrollTo` — the rAF-retry scroll-to-id + treeIndex-aware
+ * partial-load (the ToC-click → virtual-window warm bridge).
+ *
+ * GENERIC-count-sourced: `totalCount`/`visibleCount` are plain params, NEVER a
+ * consumer type. When a `treeIndex` is passed, `ensureTargetLoaded` loads only
+ * up to the target section's `rootIndex + 2` (the partial-load) instead of
+ * force-loading everything.
+ */
+export interface ScrollToOptions {
+    /** The scroll container element to scroll within. */
+    scrollContainer: Ref<HTMLElement | null>;
+    /** Total number of items/sections (the generic count ceiling). */
+    totalCount: number;
+    /** The progressively-rendered count this leaf writes the partial-load into. */
+    visibleCount: Ref<number>;
+    /** Pixel offset from the container top. Default: 16 */
+    scrollOffset?: number;
+    /** Max rAF retry attempts before bailing. Default: 60 */
+    maxAttempts?: number;
+    /**
+     * Tree index for resolving a target id to its root section index. When
+     * provided, `scrollTo` loads only up to the target's root section + buffer
+     * (`rootIndex + 2`) instead of all content. Shares the same `TreeIndexEntry`
+     * the windowing `FlatSection` hierarchy fields reconcile with.
+     */
+    treeIndex?: Map<string, TreeIndexEntry>;
+}
+/**
+ * Options for `useClickDelegate` — the ONE delegated `[data-scroll-target]`
+ * click→scroll handler for an entire ToC (not N per-link listeners).
+ */
+export interface ClickDelegateOptions {
+    /** Container element to attach the single delegated listener to. */
+    container: Ref<HTMLElement | null>;
+    /** CSS selector for clickable elements. Default: "[data-scroll-target]" */
+    selector?: string;
+    /** Attribute to read the target id from. Default: "data-scroll-target" */
+    attribute?: string;
+    /** Maps the attribute value to a scroll-target id. Return null to skip. */
+    resolve: (value: string) => string | null;
+    /** Called with the resolved id (typically `useScrollTo`'s `scrollTo`). */
+    scrollTo: (id: string) => void;
+}
+/**
+ * Options for `useLazyLoader` — the progressive batch-render count. Distinct
+ * from `useInfiniteScroll` (which fires a data-fetch `onLoadMore` trigger):
+ * the lazy-loader grows a RENDER-MOUNT count over an already-loaded list.
+ */
+export interface LazyLoaderOptions {
+    /** Sections rendered per batch. Default: 2 */
+    batchSize?: number;
+    /** IntersectionObserver rootMargin for the bottom sentinel. Default: "0px 0px 600px 0px" */
+    rootMargin?: string;
+    /** Scroll container for the fast-drag scroll fallback. Falls back to document. */
+    scrollContainer?: Ref<HTMLElement | null>;
+}
 /** Reactive state returned by `useSidebarState`. */
 export interface SidebarState {
     sections: SidebarSection[];

package/dist/composables/sidebar/useClickDelegate.d.ts

@@ -0,0 +1,4 @@
+import type { ClickDelegateOptions } from "./types";
+export declare function useClickDelegate(options: ClickDelegateOptions): {
+    handleClick: (e: MouseEvent) => void;
+};

package/dist/composables/sidebar/useLazyLoader.d.ts

@@ -0,0 +1,5 @@
+import type { LazyLoaderOptions } from "./types";
+export declare function useLazyLoader(totalCount: number, options?: LazyLoaderOptions): {
+    visibleCount: import("vue").Ref<number, number>;
+    loadSentinel: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+};

package/dist/composables/sidebar/useScrollTo.d.ts

@@ -0,0 +1,5 @@
+import type { ScrollToOptions } from "./types";
+export declare function useScrollTo(options: ScrollToOptions): {
+    scrollTo: (id: string) => void;
+    cancel: () => void;
+};

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

@@ -0,0 +1,4 @@
+export { useVirtualSectionWindow, clearSessionHeightCache, } from "./useVirtualSectionWindow";
+export { useWindowedStore } from "./useWindowedStore";
+export { buildSectionLayout, findSectionOffset, resolveActiveSection, resolveSectionWindow, } from "./virtualSectionLayout";
+export type { FlatSection, SectionLayout, SectionWindowRange, ForcedSectionWindowRange, } from "./virtualSectionLayout";

package/dist/composables/virtual/useVirtualSectionWindow.d.ts

@@ -0,0 +1,72 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import type { FlatSection } from "./virtualSectionLayout";
+/**
+ * Lineage: a glass-ui primitive at v0.9.4, retired at v1.0 (MIGRATION.md §3.2),
+ * carried on as a verbatim transposed copy in the words app, and HOME again at
+ * BC (the live words consumer + the dock-search results list overturn the
+ * no-consumer retirement verdict). Byte-faithful to the proven words copy save
+ * the recorded refinements: the container/content ResizeObservers route through
+ * the house `useResizeObserver` leaf (cleanup discipline) instead of raw
+ * `new ResizeObserver`, and `findSectionOffset` is the binary-search variant.
+ */
+interface VirtualWindowConfig<T extends FlatSection = FlatSection> {
+    /** The flat list of section items to virtualize. */
+    items: MaybeRefOrGetter<readonly T[]>;
+    /**
+     * The element whose scroll position drives the window.
+     * `null` = use `window` / document scroll.
+     */
+    scrollContainer: Ref<HTMLElement | null>;
+    /**
+     * The wrapper element around the virtualized content.
+     * When provided, scroll offset is computed relative to this element's
+     * position in the page, so content above it (headers, images, etc.)
+     * is correctly excluded from the layout calculation.
+     */
+    contentEl?: Ref<HTMLElement | null>;
+    /** Overscan before the viewport in pixels. Default: viewport height. */
+    overscanBeforePx?: number;
+    /** Overscan after the viewport in pixels. Default: 2x viewport height. */
+    overscanAfterPx?: number;
+    /** Number of items to warm before a target when using `ensureTargetWindow`. Default: 2. */
+    warmTargetBefore?: number;
+    /** Number of items to warm after a target when using `ensureTargetWindow`. Default: 3. */
+    warmTargetAfter?: number;
+}
+/**
+ * Evict every cached measured section height. The documented escape for a
+ * consumer that wants to drop the module-global `SESSION_HEIGHT_CACHE` (a
+ * font-size change, a layout reflow that invalidates prior measurements).
+ */
+export declare function clearSessionHeightCache(): void;
+/**
+ * Scroll-based virtual windowing composable for section lists.
+ *
+ * Renders only the items visible in (or near) the scroll viewport,
+ * using spacer divs to maintain correct scroll height. Supports:
+ *
+ * - Measured heights: call `measureSection(id, el)` from a template ref
+ *   to replace estimated heights with real DOM measurements.
+ * - Warm targeting: call `ensureTargetWindow(id)` to force an item into
+ *   the render window before scrolling to it (auto-releases after 320ms).
+ * - Active tracking: `activeId` / `activeRootId` report which section
+ *   is currently at the 20% viewport mark. NOTE — this is the windowing-LOCAL
+ *   render-active reader; a ToC/sidebar consumer reads `useScrollTracker`'s
+ *   `activeId` (the deepest-visible reader) for the binding highlight. The two
+ *   serve distinct concerns and are deliberately NOT one function
+ *   (BC.W-VIRTUAL-WINDOW active-section reconcile).
+ * - Content offset: provide `contentEl` to correctly handle non-virtualized
+ *   content (headers, banners) above the virtual list.
+ */
+export declare function useVirtualSectionWindow<T extends FlatSection>(options: VirtualWindowConfig<T>): {
+    visibleItems: import("vue").ComputedRef<T[]>;
+    topSpacerPx: import("vue").ComputedRef<number>;
+    bottomSpacerPx: import("vue").ComputedRef<number>;
+    measureSection: (id: string, el: HTMLElement | null) => void;
+    ensureTargetWindow: (id: string) => void;
+    getOffsetFor: (id: string) => number | null;
+    activeId: import("vue").ComputedRef<any>;
+    activeRootId: import("vue").ComputedRef<any>;
+    recalculate: () => void;
+};
+export {};