kuinetic 0.1.2 → 0.1.3

package/dist/types/core/instances.d.ts

@@ -23,7 +23,7 @@ import type { Cleanup, EffectInstance } from './types.js';
  * @complexity O(a) per call in the number of running animations; O(1) space.
  * @overallScore 100
  */
-export declare function createCssInstance(el: Element, ledger: StyleLedger, animationNames: readonly string[]): EffectInstance;
+export declare function createCssInstance(el: Element, ledger: StyleLedger, animationNames: readonly string[], scrubbed?: boolean): EffectInstance;
 /**
  * What a *finite* JS primitive's setup returns instead of a bare teardown.
  *
@@ -43,8 +43,34 @@ export interface TimedSetup {
     /** Jump to the end state, for `EffectInstance.finish()`. */
     finish?: () => void;
 }
-/** A deferred setup's return: a teardown, or a teardown plus the effect's own completion. */
-export type SetupResult = Cleanup | TimedSetup;
+/**
+ * What a setup returns when its effect genuinely never ends — a pin, a scroll progress track, a
+ * media scrub, a drag handler.
+ *
+ * This exists because a bare `Cleanup` is ambiguous, and the ambiguity matters. Ten setups in the
+ * catalog return one meaning *"there was nothing to do"* — no words to cycle, no fine pointer to
+ * follow, a stage that could not be built — and for those, "no completion pending" is the honest
+ * report. A pin returns the same shape meaning *"this will still be running an hour from now"*.
+ * Reading the two as one thing is what made the fix for D9 regress the other ten; saying which you
+ * are is cheap and the only thing that actually distinguishes them.
+ */
+export interface ContinuousSetup {
+    cleanup: Cleanup;
+    continuous: true;
+}
+/**
+ * Mark a teardown as belonging to an effect that never ends.
+ *
+ * Wrap only the return that means the effect actually started something perpetual — leave an early
+ * "nothing to do" bail-out as a bare `Cleanup`, which is what keeps the two distinguishable.
+ *
+ * @param cleanup - The effect's own teardown.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function continuousSetup(cleanup: Cleanup): ContinuousSetup;
+/** A deferred setup's return: a teardown, optionally with a completion or a never-ends marker. */
+export type SetupResult = Cleanup | TimedSetup | ContinuousSetup;
 /**
  * Turn setup-that-also-starts into a properly gated instance.
  *
@@ -85,6 +111,11 @@ export interface JsInstanceHooks {
      * `finished` after `activate()`, never before.
      */
     finished?(): Promise<void>;
+    /**
+     * Whether this effect never ends. Read on every access, for the same reason as `finished`: a
+     * deferred setup only learns which kind it is once it has run. See `EffectInstance.continuous`.
+     */
+    continuous?(): boolean;
 }
 /**
  * Build a JS-rendered instance from a primitive's hooks, filling in the optional operations.

package/dist/types/core/path-morph.d.ts

@@ -21,8 +21,27 @@ export interface Cubic {
     c2: Point;
     to: Point;
 }
+/**
+ * One subpath: a run of segments, plus whether the author closed it.
+ *
+ * A `d` string is not one contour — `M ... Z M ... Z` is a shape with a hole, and an icon with a
+ * counter (the inside of an `o`, `a`, `e`) is the common case. Flattening the runs together turns
+ * a hole into a detour line across the glyph, so the boundary has to survive parsing.
+ */
+export interface Subpath {
+    segments: Cubic[];
+    /**
+     * True when the author wrote an explicit `Z`/`z`. Kept separate from the geometry because
+     * `closeSubpath` already materialises the closing side as a real segment — this flag is what
+     * decides whether `Z` is re-emitted, which is what `fill-rule` needs to punch the hole.
+     */
+    closed: boolean;
+}
 export interface ParseResult {
+    /** Every segment in document order, with subpath boundaries flattened away. */
     segments: Cubic[];
+    /** The same segments grouped by subpath. This is the form morphing needs. */
+    subpaths: Subpath[];
     /** Present when the path could not be normalised; the caller should warn and not morph. */
     reason?: string;
 }

package/dist/types/core/style-plan.d.ts

@@ -7,10 +7,15 @@ import type { Activation } from './types.js';
  * How the animation is started.
  *
  * - `native-timeline` — a scroll/view timeline drives progress; nothing to start.
+ * - `scrubbed` — `timeline: pin`. Held paused forever and seeked by `--kui-progress` through the
+ *   compiled `animation-delay`. Distinct from `deferred`, which is also paused but is waiting to
+ *   be *released* by an activation: a scrubbed animation must never be released, because
+ *   `animation-play-state: running` hands it back to the document timeline and it would play
+ *   forward in real time instead of tracking scroll.
  * - `immediate` — runs as soon as it is applied.
  * - `deferred` — held at its from-state until an activation fires.
  */
-export type Gate = 'native-timeline' | 'immediate' | 'deferred';
+export type Gate = 'native-timeline' | 'scrubbed' | 'immediate' | 'deferred';
 export interface StylePlan {
     /** Custom properties and animation longhands to write, in application order. */
     properties: Record<string, string>;

package/dist/types/core/types.d.ts

@@ -29,6 +29,17 @@ export declare const CHANNEL: {
     readonly color: "color";
     readonly stroke: "stroke";
     readonly text: "text";
+    /**
+     * Skew is the one transform CSS never gave an independent property to — there is no `skew:`
+     * beside `translate:`/`rotate:`/`scale:`, so it can only be written through the `transform`
+     * shorthand. That makes it its own channel: anything writing `transform` clobbers the whole
+     * shorthand, so every primitive that does is on this channel, whatever the transform is for.
+     * `scroll-skew` is one member; `flip-face` (`effects/three-d`) and `flip-3d`
+     * (`effects/catalog/core`, the `flip-in-*`/`flip-out-*` family) are the other two — both need
+     * the `perspective()` transform *function* for an element to have depth on itself, which
+     * likewise only exists inside `transform`.
+     */
+    readonly skew: "skew";
 };
 /**
  * A CSS property group an effect writes to. Two effects may only be composed in one `data-kui`
@@ -51,7 +62,18 @@ export type Activation = 'load' | 'enter' | 'hover' | 'focus' | 'click' | 'manua
  * *reverse when the user scrolls back*, which a time-based reveal does not. These are different
  * animation models, not fallbacks for each other. See docs/design.md §5.
  */
-export type Timeline = 'time' | 'view' | 'scroll' | 'pointer';
+/**
+ * `pin` is the odd one out and deliberately so. `view`/`scroll` map to a native CSS
+ * `animation-timeline`; `pin` has no native equivalent because CSS has no way to say "drive this
+ * from another element's published progress". A pinned element's `view()` timeline *stalls* — it
+ * stops travelling through the viewport, so its progress freezes for the whole hold, which is
+ * exactly the span an author wants to animate across. `pin` fills that hole: the animation is
+ * held paused and seeked with a negative `animation-delay` proportional to `--kui-progress`,
+ * which the scroll-mechanics primitives already publish every frame. Verified in Chrome:
+ * progress 0/0.25/0.5/0.75/1 renders -180/-135/-90/-45/0deg on a half-turn keyframe, re-seeks
+ * live on every variable change, and composes with `--kui-stagger`.
+ */
+export type Timeline = 'time' | 'view' | 'scroll' | 'pointer' | 'pin';
 export type Renderer = 'css-keyframes' | 'waapi' | 'javascript';
 /** Governs the performance budget a primitive is held to in tests. */
 export type PerfClass = 'compositor' | 'paint' | 'layout' | 'continuous' | 'dom-transform';
@@ -106,6 +128,20 @@ export interface EffectInstance {
     finish(): void;
     /** Resolves when the effect completes. Resolves — never rejects — on cancel. */
     readonly finished: Promise<void>;
+    /**
+     * Whether this effect has no end — a pin, a scroll progress track, a media scrub.
+     *
+     * Such an effect keeps an already-resolved `finished` on purpose, so that composing it with a
+     * one-shot on the same element does not stop the one-shot ever reporting complete. That is
+     * right for composition and wrong for the element's own reported state: an element whose *only*
+     * effects are continuous would otherwise read `data-kui-state="finished"` from the first
+     * microtask onwards and never say anything else, which is a lie an author cannot style around.
+     *
+     * The animator therefore reads this to decide whether there is any completion to wait for at
+     * all. Read after `activate()`, never before — a deferred setup only learns which kind it is
+     * once it has actually run.
+     */
+    readonly continuous?: boolean;
     /** Release every listener, observer, subscription, and inserted node. */
     destroy(): void;
 }
@@ -182,6 +218,43 @@ export interface Primitive {
     defaultActivation?: Activation;
     perfClass: PerfClass;
     reducedMotion: ReducedMotionPolicy;
+    /**
+     * Whether this primitive, left alone to finish with nobody calling `reset()`/`destroy()`, ends
+     * with the element's markup indistinguishable from what the author wrote.
+     *
+     * There are two separate teardown contracts, and `test/browser/teardown-sweep.test.mjs` used to
+     * conflate them into one check:
+     *
+     * - **Interruption restores.** Calling `reset()` mid-effect puts the markup back byte-for-byte.
+     *   This is unconditional and every primitive owes it — it is not gated by this field at all, and
+     *   never will be, because a caller can `reset()` anything at any moment.
+     * - **Natural finish restores** (this field). The effect, left alone to run to completion, ends
+     *   with the markup back as authored. This is `slat-assemble`'s whole point: it disassembles a
+     *   picture into slats and reassembles it, and the slats are scaffolding that must be gone once
+     *   the illusion lands — not just when someone happens to call `reset()`.
+     *
+     * **Defaults to `false` — a primitive has to opt in.** The tempting default is `true` ("assume it
+     * restores unless told otherwise"), on the theory that a forgotten declaration should never
+     * silently skip a check. That is the wrong default in this codebase specifically: the majority of
+     * the catalog is JS/CSS-driven effects that either never resolve `finished` at all (ambient
+     * loops, hover/pointer effects, anything `reducedMotion: 'disable'` marks as unboundable) or
+     * finish *by design* in a state that differs from authored markup — `data-kui-state="finished"`
+     * and the `--kui-*` custom properties `createCssInstance` leaves in place are the point, not a
+     * bug, and every `css-keyframes` primitive in the catalog would need an explicit opt-out under a
+     * `true` default. Defaulting to `true` would have meant "almost every primitive needs a
+     * non-default declaration," which is the sign from the design notes above that a default is
+     * wrong. `false` means "no claim is being made" for the ordinary case, and only the small set of
+     * primitives that build their own temporary DOM as scaffolding — `slat-assemble` today — assert
+     * this explicitly. The unconditional interruption check above is what actually closes the "a new
+     * scaffold-building primitive forgets to opt in" gap: `reset()` is still guaranteed to restore it
+     * even if nobody ever wrote `restoresOnFinish: true` for it.
+     *
+     * `test/browser/teardown-sweep.test.mjs` reads this to decide whether a primitive owes a
+     * natural-finish check at all, and its failure messages name which law was broken instead of the
+     * generic "leaves synthetic nodes behind" that previously misdescribed a `style=""` leak as extra
+     * DOM nodes for a whole debugging session.
+     */
+    restoresOnFinish?: boolean;
     /**
      * JS-side setup. Returns a lifecycle handle, **not** a teardown function.
      *
@@ -202,6 +275,25 @@ export interface Preset {
     params?: Record<string, string>;
     /** CSS `@keyframes` name this preset animates, when renderer is `css-keyframes`. */
     keyframes?: string;
+    /**
+     * This effect begins from a state the visitor must not see — invisible, displaced, unsplit, or
+     * un-assembled — so painting the element at its rest state before the runtime installs that
+     * from-state is a visible flash. `scripts/generate-preset-css.mjs` emits a pre-JS cloak rule for
+     * every preset that declares it; see the `kui.cloak` layer in `src/css/base.css`.
+     *
+     * **This has to be declared, not derived.** Both plausible signals were measured and both are
+     * wrong. Keying on "owns the opacity channel" cloaks `hamburger-to-x`, `checkbox-draw` and
+     * `dropdown-open` — stateful controls with no entrance — while missing `blur-in` and `bounce-in`.
+     * Keying on "supports the entrance timelines" cloaks `pin-section`, `scroll-spy` and
+     * `horizontal-scroll`, and hiding a pinned section at opacity 0 is precisely the failure the
+     * opt-in rule in `base.css` was written to avoid. Whether a name is an entrance with a
+     * from-state worth hiding is a fact only its author knows, which is why it sits here beside
+     * `params` rather than being inferred from either.
+     *
+     * Exits are deliberately excluded: `fade-out` starts at the rest state, so there is nothing to
+     * hide and cloaking it would blank an element that should be visible until it leaves.
+     */
+    cloak?: boolean;
 }
 export type ResolvedParams = Record<string, string>;
 /** One effect segment parsed out of a `data-kui` value. */

package/dist/types/effects/catalog/index.d.ts

@@ -1,10 +1,4 @@
 import type { Registry } from '../../core/registry.js';
-export { AMBIENT_PRESETS, AMBIENT_PRIMITIVES } from './ambient.js';
-export { FEEDBACK_PRESETS, FEEDBACK_PRIMITIVES } from './feedback.js';
-export { INTERACTION_PRESETS, INTERACTION_PRIMITIVES } from './interaction.js';
-export { MEDIA_PRESETS, MEDIA_PRIMITIVES } from './media.js';
-export { NUMBERS_PRESETS, NUMBERS_PRIMITIVES } from './numbers.js';
-export { TEXT_PRESETS, TEXT_PRIMITIVES } from './text.js';
 /**
  * Register the CSS-oriented catalog sections.
  *

package/dist/types/effects/catalog/media-shared.d.ts

@@ -0,0 +1,124 @@
+import type { Cleanup, EffectParams } from '../../core/types.js';
+/**
+ * DOM-surgery helpers behind `slat-assemble` (catalog section G).
+ *
+ * `text-shared.ts` is the template this follows: build a synthetic child tree once at activation,
+ * index each child with a plain custom property, and let CSS (`media.css`) own every frame from
+ * there — this module never animates anything itself, it only builds the tree and computes the
+ * per-child numbers CSS reads.
+ */
+/** Which way the image is cut into strips. `angle:` generalises this to any degree. */
+export type SlatAxis = 'vertical' | 'horizontal';
+/** How the per-slat stagger order relates to a slat's geometric position. */
+export type SlatFrom = 'alternate' | 'start' | 'end' | 'edges' | 'random-ish';
+/**
+ * Map a slat's geometric position to its stagger rank.
+ *
+ * The rank is what `--kui-i` carries into `media.css`'s `animation-delay: calc(delay + i *
+ * stagger)` — the same formula `text.css` already uses for `.kui-split-item` — so `from:` only
+ * ever changes which number lands in that one slot, never the delay formula itself. Ties are
+ * fine: two slats sharing a rank simply animate on the same beat, which is a legitimate look
+ * (`edges`'s two starting slats are meant to move together), not a bug.
+ *
+ * - `start` — geometric order, left-to-right or top-to-bottom.
+ * - `end` — the reverse.
+ * - `edges` — outside-in: both ends rank 0, the middle ranks highest, so the seam closes last.
+ * - `alternate` (default) — a zig-zag across the whole run (0, N-1, 1, N-2, 2, …), so slats land
+ *   from alternating ends instead of sweeping one direction.
+ * - `random-ish` — a deterministic scatter (see `GOLDEN_RATIO_CONJUGATE`), not real randomness.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function slatOrder(index: number, count: number, from: SlatFrom): number;
+/**
+ * Resolve the authored `angle:` to degrees, falling back to whatever `axis:` names.
+ *
+ * `angle:` is the general parameter and `axis:` the two-keyword shorthand that predates it, so an
+ * authored angle wins and an absent one reads the axis. Both `45` and `45deg` are accepted, as are
+ * `turn` and `rad`, because an author who writes an angle should not have to remember which of the
+ * three this particular parameter takes.
+ *
+ * Normalised to `[0, 180)`: a band at 200° is the same set of bands as one at 20°, only numbered
+ * from the other end, and collapsing that here means the geometry below never has to think about
+ * sign or wrap.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function slatAngleDegrees(authored: string, axis: SlatAxis): number;
+/**
+ * The unit vector each slat travels along in its from-state: the band's own long axis.
+ *
+ * At 0° this is `(0, 1)` — vertical columns sliding up and down, which is exactly what the two
+ * hand-written axis keyframes did before this generalised them. At 90° it is `(-1, 0)`, horizontal
+ * rows sliding sideways. Perpendicular travel is deliberately not offered: a band moving across its
+ * own width exposes the gap it left, and the point of the effect is strips that are *out of line*,
+ * not strips that are missing.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function slatTravelVector(angleDegrees: number): {
+    x: number;
+    y: number;
+};
+/**
+ * The `clip-path` for one band of an angled slice, in pixels against the stage's measured box.
+ *
+ * Pixels, not percentages, on purpose. A percentage polygon is resolved against each axis
+ * separately, so "45°" on a 3:4 card would paint at some other angle entirely — the author asked
+ * for a diagonal and would get a diagonal that changes as the card resizes. Measuring means the
+ * angle is the angle, at any aspect ratio, and the caller re-runs this whenever the box changes.
+ *
+ * The band is the region between two parallel lines perpendicular to `angleDegrees`, extended far
+ * enough sideways to cover the stage from any rotation; `overflow: clip` on the stage trims the
+ * overhang. Each boundary is pushed out by {@link BAND_OVERLAP_PX} for the same reason the axis
+ * version added a pixel to its width: `span / count` almost never lands on a whole pixel, and the
+ * remainder renders as a hairline of backdrop between neighbours once they have landed.
+ *
+ * @param index - Band number, `0` to `count - 1`, in geometric order along the cut normal.
+ * @param box - The stage's measured pixel size, re-read by the caller on every layout change.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function slatBandClip(index: number, count: number, angleDegrees: number, box: {
+    width: number;
+    height: number;
+}): string;
+export interface SlatStage {
+    /** The `aria-hidden` wrapper holding every slat, positioned over the source `<img>`. */
+    stage: HTMLElement;
+    /** One element per slat, in geometric order. */
+    slats: HTMLElement[];
+    /** Remove every generated node and stop watching the image's box. The source `<img>` was never modified, so nothing to restore on it. */
+    restore: Cleanup;
+}
+/** Validated build options for {@link installSlatStage}, grouped to keep its own signature small. */
+export interface SlatBuildOptions {
+    count: number;
+    /** Resolved cut angle in degrees, `[0, 180)`. See {@link slatAngleDegrees}. */
+    angleDegrees: number;
+    from: SlatFrom;
+    fold: boolean;
+}
+export declare function installSlatStage(el: Element, doc: Document, win: Window, options: SlatBuildOptions): SlatStage | null;
+/**
+ * Forward validated timing params onto the stage, so `media.css`'s `--kui-i * --kui-stagger`
+ * delay formula (the same shape `text-shared.ts`'s `applyStaggerVars` writes for split-text) can
+ * read them by inheritance into every `.kui-slat-item`.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function applySlatTimingVars(stage: HTMLElement, params: EffectParams): void;
+/**
+ * Total time before every staggered slat has finished landing: the last slat's `--kui-i *
+ * --kui-stagger` delay, plus its own duration — `splitRevealFinishMs`'s reasoning, over slat
+ * count instead of grapheme/word/line count.
+ *
+ * @param count - Slat count; zero means nothing was ever built, so nothing is animating.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function slatAssembleFinishMs(params: EffectParams, count: number): number;

package/dist/types/effects/catalog/media.d.ts

@@ -1,5 +1,9 @@
 import type { Preset, Primitive } from '../../core/types.js';
 import type { Registry } from '../../core/registry.js';
+export declare const MEDIA_CSS_PRIMITIVES: Primitive[];
+export declare const MEDIA_CSS_PRESETS: Preset[];
+export declare const MEDIA_JS_PRIMITIVES: Primitive[];
+export declare const MEDIA_JS_PRESETS: Preset[];
 export declare const MEDIA_PRIMITIVES: Primitive[];
 export declare const MEDIA_PRESETS: Preset[];
 /**

package/dist/types/effects/catalog/numbers-shared.d.ts

@@ -14,7 +14,11 @@ export interface CountLayers {
      * mid-tick — so a screen reader is told the final value and nothing in between.
      */
     srOnly: HTMLElement;
-    /** Remove both layers, restoring the element to plain text of whatever the SR layer last held. */
+    /**
+     * Remove both layers, putting the authored children back as they were. Not the value the
+     * counter reached: that number is the library's, and teardown gives the element back to the
+     * author — including the `42` that was there as a no-JS fallback.
+     */
     restore: Cleanup;
 }
 /**

package/dist/types/effects/catalog/shared.d.ts

@@ -1,3 +1,2 @@
 /** Re-exported for same-directory catalog siblings; the canonical definition lives in `effects/shared.ts` — neutral ground for every CSS-keyframe category, not just `catalog/`. */
 export { cssPrimitive } from '../shared.js';
-export type { CssPrimitiveOptions } from '../shared.js';

package/dist/types/effects/catalog/subtree-capture.d.ts

@@ -0,0 +1,23 @@
+import type { Cleanup } from '../../core/types.js';
+/**
+ * Snapshot an element's children so teardown can put back exactly what the author wrote.
+ *
+ * Every DOM-rewriting primitive in this folder used to restore by assigning `textContent`, which
+ * is faithful only when the authored content was plain text — the one case every restore test
+ * happened to author. Given `<p><strong>one</strong> two</p>` it flattened the `<strong>`; given
+ * `<span>42</span>` a counter wrote back the value it had counted to instead of the author's own
+ * content. Both are invisible on a page that never tears down, and both destroy author markup in
+ * any app that unmounts.
+ *
+ * The captured nodes are the live originals, merely detached by the caller's own overwrite.
+ * Restoring re-inserts those same node objects, so nested structure, attributes, and any listeners
+ * bound to them survive — none of which would come back from re-parsing a string.
+ *
+ * Capture before overwriting: this reads the children as they stand when it is called.
+ *
+ * @param el - Element whose children are about to be replaced.
+ * @returns A cleanup that discards whatever is there now and reinstates the captured children.
+ * @complexity O(n) time and space in child-node count.
+ * @overallScore 100
+ */
+export declare function captureChildren(el: Element): Cleanup;

package/dist/types/effects/catalog/text-shared.d.ts

@@ -4,9 +4,12 @@ export type SplitUnit = 'chars' | 'words' | 'lines';
 export interface SplitLayers {
     /** `aria-hidden` container the caller populates with decorative markup or text. */
     decorative: HTMLElement;
-    /** The element's text at the moment splitting began. */
+    /** The element's text at the moment splitting began, trimmed for display. */
     originalText: string;
-    /** Remove both layers and put the original text back, selectable and unabridged. */
+    /**
+     * Remove both layers and put the authored children back exactly as they were — element nodes
+     * and untrimmed whitespace included, not the trimmed text `originalText` renders.
+     */
     restore: Cleanup;
 }
 /**

package/dist/types/effects/gestures/index.d.ts

@@ -1,6 +1,5 @@
 import type { Preset } from '../../core/types.js';
 import type { Registry } from '../../core/registry.js';
-export { GESTURE_PRIMITIVES } from './primitives.js';
 /**
  * Gesture names. Twelve names over four primitives.
  *

package/dist/types/effects/layout/index.d.ts

@@ -1,6 +1,4 @@
 import type { Registry } from '../../core/registry.js';
-export { LAYOUT_PRIMITIVES } from './primitives.js';
-export { LAYOUT_PRESETS } from './presets.js';
 /**
  * Register the layout/FLIP catalog.
  *

package/dist/types/effects/scroll-mechanics/index.d.ts

@@ -1,8 +1,4 @@
 import type { Registry } from '../../core/registry.js';
-export { SCROLL_PRIMITIVES } from './primitives.js';
-export { SCROLL_PRESETS } from './presets.js';
-export { domGeometry, progressFrom, trackProgress } from './tracker.js';
-export type { ElementGeometry, Measurer, TrackOptions } from './tracker.js';
 /**
  * Register the scroll-mechanics catalog.
  *

package/dist/types/effects/scroll-mechanics/scroll-spy.d.ts

@@ -0,0 +1,26 @@
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { EffectParams } from '../../core/types.js';
+import type { ContinuousSetup } from '../../core/instances.js';
+/**
+ * `scroll-spy`'s two authoring shapes.
+ *
+ * Split out of `primitives.ts` once the container form pushed that file over its own line cap —
+ * same reason `stacking-cards` and `scroll-snap` got their own *test* files in commit 69253cf, one
+ * level up: a category that outgrows one file gets a file of its own rather than a bigger one.
+ *
+ * `prepareScrollSpy` is the only export `primitives.ts` needs; everything else here is either mode
+ * is private to how it marks `data-kui-active`.
+ */
+/**
+ * Mark the navigation link pointing at the most recently entered section.
+ *
+ * Two authoring shapes share this primitive. `sections:` selects the container form — one
+ * instance on the element that has both the nav and the sections as descendants, which measures
+ * every section itself instead of taking an authored `distance:` per section. Its absence keeps
+ * the original per-section form running exactly as shipped, `distance:` and all: that form is
+ * public API and this dispatch is the whole of what changes for it, nothing inside it does.
+ *
+ * @complexity Dispatch only; see whichever form runs.
+ * @overallScore 100
+ */
+export declare function prepareScrollSpy(el: Element, params: EffectParams, ctx: PrepareContext): ContinuousSetup;

package/dist/types/effects/scroll-mechanics/tracker.d.ts

@@ -18,6 +18,19 @@ export interface ElementGeometry {
 }
 export type Measurer = (el: Element) => ElementGeometry;
 export declare const domGeometry: Measurer;
+/** Resolved `position` for one element. Injected for the same reason `Measurer` is. */
+export type PositionReader = (el: Element) => string;
+export declare const domPosition: PositionReader;
+/**
+ * Resolved `top`, in pixels, for whichever element is actually `position: sticky`. Injected for
+ * the same reason `Measurer` and `PositionReader` are, and for an extra one of its own: the value
+ * is routinely an unresolved CSS expression — `demo/system.css` sets `--kui-pin-offset: 5.5rem`
+ * and every pin's `offset-top` defaults to `var(--kui-pin-offset, 0px)` — so a static parse of the
+ * authored string cannot recover it. `getComputedStyle` can, because the browser has already
+ * resolved the `var()`, the `calc()`, and any `vh` in it.
+ */
+export type OffsetReader = (el: Element) => number;
+export declare const domOffsetTop: OffsetReader;
 export interface TrackOptions {
     /**
      * Scroll distance the effect spans, as an authored CSS length. Defaults to the element's own
@@ -25,14 +38,59 @@ export interface TrackOptions {
      */
     distance?: string;
     measure?: Measurer;
+    positionOf?: PositionReader;
+    /**
+     * A spacer the caller inserted immediately after `el`, used instead of `geometrySource` to say
+     * where `el` really sits in the content.
+     *
+     * `geometrySource` escapes a sticky subtree by taking its parent, which is only honest when the
+     * parent is a tight box around the effect. Pages used to guarantee that by hand-writing a
+     * wrapper — `demo/scroll.html` carried a `.scrub-stage` whose entire job was `height: 260vh`.
+     * Delete the wrapper and the parent becomes whatever section happens to contain the scrub:
+     * measured there, the parent started 926px above it against a 1817px distance, so progress read
+     * 51% before the element had even stuck and half the sequence played off screen.
+     *
+     * The spacer has neither problem. The library inserts it, it is exactly `distance` tall, it is
+     * never sticky, and it moves with the content — so it describes the scroll the effect spans
+     * without depending on how the author nested anything.
+     *
+     * It sits *after* `el`, so its top is `el`'s bottom; subtracting `el`'s own height recovers the
+     * flow position sticky is hiding. That assumes no margin between the two, which holds because
+     * both boxes are the library's own.
+     */
+    contentAnchor?: Element;
+    /**
+     * The element that is actually `position: sticky`, so its resolved `top` can be read back and
+     * subtracted from progress.
+     *
+     * Every caller above computes "the flow position sticky is hiding" — `sourceTop` or
+     * `contentAnchor` — but that flow position is where the element's top reaches the *viewport's*
+     * top edge, y = 0. Sticky does not wait for that: it engages the instant the flow top reaches
+     * `top: <offset>`, `offset` pixels earlier. Without this, progress read 0 for the first `offset`
+     * pixels the element was visibly stuck (an author with `--kui-pin-offset: 5.5rem` set — the
+     * showcase default — got 88px of dead pin at the start of every `pin-*` and managed
+     * `media-scrub`/`horizontal-scroll` effect, and 88px of dead pin at the end, since the same
+     * untouched flow top also gated when progress reached 1). Measured on `demo/scroll.html`'s
+     * `pin-spacer` card: 71 of those 88px, the rest eaten by an unrelated layout shift in the probe
+     * — see `docs/live-testing-backlog.md` D8.
+     *
+     * Left undefined for primitives that never call `installSticky` themselves (`scroll-progress`,
+     * `scroll-spy`, the bare `horizontal-scroll` form, `video-scrub`) — a page-authored sticky
+     * ancestor is still escaped by `geometrySource`, but its offset is unknowable from here, so
+     * progress there is unchanged: 0 at the sticky ancestor's untouched flow top, same as before.
+     */
+    stickyEl?: Element;
+    /** Injected for the same reason `measure`/`positionOf` are; see `OffsetReader`. */
+    offsetOf?: OffsetReader;
 }
 export type ProgressHandler = (progress: number, frame: ScrollFrame) => void;
 /**
  * Drive `onProgress` with the element's scroll progress in [0, 1].
  *
- * Progress is 0 when the element's top reaches the top of the scrollport and 1 once the scroll has
- * advanced by `distance`. Measurements are cached against the scheduler's epoch, so a frame costs
- * arithmetic rather than a layout flush.
+ * Progress is 0 when the tracked flow position reaches `options.stickyEl`'s sticky offset (the
+ * scrollport's top edge, y = 0, when there is no `stickyEl`) and 1 once the scroll has advanced by
+ * `distance`. Measurements are cached against the scheduler's epoch, so a frame costs arithmetic
+ * rather than a layout flush.
  *
  * @param el - Element whose position drives progress.
  * @param ctx - Prepare context supplying the scheduler and root resolver.