kuinetic 0.1.2 → 0.1.4

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. */
@@ -235,5 +327,11 @@ export interface InstanceState {
     attributes: AttributeLedger;
     /** Aborted on release, detaching bindings and primitive listeners. */
     controller: AbortController;
+    /**
+     * Releases a one-shot `enter` binding, set only for that activation and cleared once spent.
+     * Present so `Animator.activate` can disarm an observer a programmatic activation just made
+     * redundant; a toggle activation (`hover`/`focus`/`click`) deliberately leaves this undefined.
+     */
+    releaseActivation?: Cleanup;
     status: 'pending' | 'ready' | 'running' | 'finished' | 'failed';
 }

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

@@ -0,0 +1,152 @@
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { Cleanup } from '../../core/types.js';
+/**
+ * Whether an authored `src` names a video platform's web page instead of a media file.
+ *
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function isVideoPageUrl(value: string): boolean;
+/**
+ * Named focal points, as `object-position` percentage pairs.
+ *
+ * A `cover` fit crops, and which part it crops away is the whole editorial decision — the classic
+ * failure is a portrait cropped through the subject's chin. Percentages rather than the equivalent
+ * CSS keywords (`top`, `left top`) because the pair is written into one property from two halves,
+ * and `50% 0%` composes where `center top` would need its own keyword-order rules.
+ */
+declare const FOCAL_POINTS: {
+    readonly center: "50% 50%";
+    readonly top: "50% 0%";
+    readonly bottom: "50% 100%";
+    readonly left: "0% 50%";
+    readonly right: "100% 50%";
+    readonly 'top-left': "0% 0%";
+    readonly 'top-right': "100% 0%";
+    readonly 'bottom-left': "0% 100%";
+    readonly 'bottom-right': "100% 100%";
+};
+export type FocalPoint = keyof typeof FOCAL_POINTS;
+/** The nine named focal points, in the order the parameter schema declares them. */
+export declare const FOCAL_POINT_NAMES: FocalPoint[];
+/**
+ * Resolve a focal point name to an `object-position` value.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function focalPosition(focus: string): string;
+/** How a background clip decides when to run. */
+export type AutoplayMode = 'in-view' | 'always' | 'never';
+export interface BackgroundMediaOptions {
+    /** URL or path to the image or video, already screened by `mediaSource`. */
+    src: string;
+    /** Still shown before a video's first frame; `''` for none. */
+    poster: string;
+    /** `object-fit` for the layer. */
+    fit: 'cover' | 'contain';
+    /** `object-position` for the layer, already resolved from a named focal point. */
+    position: string;
+    /** Scrim colour painted over the media and under the author's children. */
+    overlay: string;
+    /** Scrim opacity, `0`–`1`. */
+    overlayOpacity: number;
+    /** When a clip plays. Ignored for an image. */
+    autoplay: AutoplayMode;
+    /** `playbackRate` for a clip. Ignored for an image. */
+    rate: number;
+    /** Whether a clip restarts when it ends. Ignored for an image. */
+    loop: boolean;
+    /** Suppresses autoplay, leaving the poster frame standing. */
+    reducedMotion: boolean;
+}
+export interface BackgroundLayer {
+    /** Stop observing and delete every node this effect added, leaving the author's own as written. */
+    remove: Cleanup;
+}
+/**
+ * Whether a scrim colour is actually asking for a scrim.
+ *
+ * `transparent` is the default so that the parameter stays a real `type: 'color'` — validated by
+ * the same screen every other colour goes through — rather than an empty string that no colour
+ * grammar accepts. It also happens to be the honest spelling of "no scrim", so an author who
+ * writes it explicitly gets exactly what the default gives them.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function paintsOverlay(options: BackgroundMediaOptions): boolean;
+/**
+ * Whether an authored `src` names a video rather than an image.
+ *
+ * @param src - Author-supplied path, already accepted as same-origin.
+ * @returns `true` when the path's final extension is a known video container.
+ * @complexity O(n) time in path length; O(1) space.
+ * @overallScore 100
+ */
+export declare function isVideoSource(src: string): boolean;
+/**
+ * Screen an authored media URL before it can reach `src`/`poster`.
+ *
+ * **Cross-origin URLs are allowed here, unlike `media-scrub`'s frame pattern, and that is a
+ * deliberate divergence rather than an oversight.** `isSameOriginPath` (`core/params.ts`) refuses
+ * every absolute URL on the grounds that `data-kui` is not always written by the site owner — a CMS
+ * field, a comment — so an unconstrained `src` turns the visitor's browser into an
+ * attacker-directed request tool. That reasoning still stands, and it is why the scheme allowlist
+ * above is kept tight.
+ *
+ * It is not the right trade for *this* parameter, though. A background is the one media case where
+ * the file routinely does not live on the page's own origin — an S3 bucket, a CDN, an asset host —
+ * and `media-scrub`'s `src:` is materially more dangerous than this one for a second reason: it is
+ * a `{i}` *template* that fires one request per frame, so a two-hundred-frame sequence is a
+ * two-hundred-request channel where this is a single fixed fetch. A site that does accept untrusted
+ * `data-kui` should set a `Content-Security-Policy` with `img-src`/`media-src`, which is the
+ * control actually designed for this and the one thing a library cannot do on the consumer's
+ * behalf.
+ *
+ * @param authored - Author-supplied value; `''` when none was written.
+ * @param name - Parameter name, for the diagnostic.
+ * @returns The URL, or `''` when it was rejected or absent.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function mediaSource(authored: string, name: string, ctx: PrepareContext): string;
+/**
+ * Apply the authored playback policy to a clip.
+ *
+ * `autoplay:` is the opt-out the three real cases need. `in-view` (default) pairs the clip with the
+ * viewport. `always` is for a short hero clip that must never be caught mid-stall by a visibility
+ * heuristic. `never` installs the clip and leaves it on its poster, which is also what any mode
+ * degrades to under a reduced-motion preference.
+ *
+ * @returns A teardown that stops any observer and leaves the clip paused.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function startPlayback(video: HTMLVideoElement, win: Window, options: BackgroundMediaOptions): Cleanup;
+/**
+ * Play a background clip while any part of it is on screen, and pause it the rest of the time.
+ *
+ * This is the primitive's own observer rather than the animator's `on:enter` gate, because the two
+ * answer different questions: `on:enter` fires once and stays fired, which is right for a reveal
+ * and wrong for a clip that should stop costing decode budget the moment it scrolls away.
+ *
+ * `threshold: 0` — any intersection at all — rather than the `0.25` a card-sized video wants.
+ * `intersectionRatio` is measured against the *target*, and this target is usually a full section:
+ * one taller than four viewports can never reach a ratio of 0.25 no matter where it is scrolled,
+ * so a fractional threshold is a clip that silently never plays.
+ *
+ * @returns A teardown that disconnects the observer and leaves the clip paused.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function autoplayInView(video: HTMLVideoElement, win: Window): Cleanup;
+/**
+ * Create the backdrop layer and hand back the handle that deletes it again.
+ *
+ * @param el - The host element, which keeps every child the author wrote.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function installBackgroundMedia(el: Element, ctx: PrepareContext, options: BackgroundMediaOptions): BackgroundLayer;
+export {};

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';
+/** Re-exported for same-directory catalog siblings; the canonical definitions live in `effects/shared.ts` — neutral ground for every effect category, not just `catalog/`. */
+export { cssPrimitive, TIMELINE_AGNOSTIC, TRIGGER_DELAY_PARAM } 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;
 }
 /**
@@ -114,6 +117,12 @@ export declare function createStepRunner(win: Window, options: StepRunOptions):
  * wrapping the space itself, the same way `appendWordSpans` already leaves inter-word whitespace
  * unwrapped.
  *
+ * Per the CSS Text line-breaking spec, browsers insert a line-break opportunity between any two
+ * adjacent atomic inline-level boxes, even without whitespace between them — so a bare run of
+ * `.kui-split-item` spans could wrap mid-word. Each word's char-spans are nested inside a shared
+ * `.kui-split-word` wrapper (itself `display: inline-block`) so the only break opportunities left
+ * are between words, same as the source text.
+ *
  * @complexity O(n) time and space in grapheme count.
  * @overallScore 100
  */

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.
  *