kuinetic 0.2.2 → 0.2.4

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

@@ -53,6 +53,42 @@ export declare const CHANNEL: {
  * the union documents the built-ins without closing the set.
  */
 export type Channel = (typeof CHANNEL)[keyof typeof CHANNEL] | (string & {});
+/**
+ * The channel for an effect whose output is an attribute it writes on its own element.
+ *
+ * Named by the attribute, not by the kind of output. These primitives used to share one bucket
+ * channel, `'state'`, and since a channel is exclusive, any two of them in one comma list were
+ * refused: `swipe-y, carousel` compiled to `swipe-y` alone, with the deck dropped, though
+ * `data-kui-swipe` and `data-kui-step` never touch. What two attribute writers can actually fight
+ * over is one attribute, so that is what the claim says — `swipe-x, swipe-y` still collide on
+ * `data-kui-swipe`, and `carousel, step-progress` on `data-kui-step`.
+ *
+ * Claim every attribute the effect writes on its host; attributes written on other elements (a
+ * deck's slides, a spy's links) are not this element's to contend for.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function attributeChannel(attribute: string): string;
+/**
+ * The channel for a widget that owns its host's children: it inserts elements of its own into the
+ * host (a slideshow's controls, a compare's range and handle, hotspot markers, the slow-mo toggle),
+ * its stylesheet lays the host's children out by where they sit (`scroll-story`'s sticky
+ * `:first-child` beside a scrolling `:last-child`, `compare`'s stacked layers), or it takes the
+ * host's children as its items (a step deck's slides when no `target:` names them).
+ *
+ * This is the one thing two such widgets genuinely fight over, so it is exclusive like any channel:
+ * `slow-mo`'s toggle prepended into a `scroll-story` becomes the sticky first child, and a
+ * `compare` range appended into `hotspots` sits under the markers it places in percent of the host,
+ * and the same toggle inside a `carousel` becomes one of its slides.
+ * It replaces the bucket the showcase used to share, `'widget'`, which refused every pair of
+ * widgets — `lightbox` beside a slideshow included, though the lightbox only listens on the links
+ * already there. Attributes a widget writes on its host are claimed separately, with
+ * {@link attributeChannel}.
+ *
+ * Local to the showcase rather than a row of `CHANNEL`: it names a subtree, not a CSS property.
+ */
+export declare const SUBTREE_CHANNEL = "subtree";
 /**
  * The activations the library gives a name of its own, because the DOM has no event for them or
  * because the name bundles more than one event. See `core/activation.ts` for what each
@@ -215,6 +251,29 @@ interface ParamSpecBase {
     maximum?: number;
     /** Require a numeric parameter to have no fractional part. */
     integer?: boolean;
+    /**
+     * Plain-words documentation for a reader, surfaced by `describeEffect` — never read at runtime.
+     *
+     * Optional, and absent on every built-in primitive on purpose: the catalog's notes live in
+     * `src/notes/`, a separate entry only documentation pages load, so the prose does not ship in
+     * the core bundle. This field is the inline route for a third-party primitive, whose notes have
+     * nowhere else to live. Where both exist, this one wins.
+     */
+    note?: ParamNote;
+}
+/**
+ * What a reader needs to know about one parameter that its type and default cannot say.
+ *
+ * A bare string is shorthand for `{ why }`.
+ */
+export type ParamNote = string | ParamNoteDetail;
+export interface ParamNoteDetail {
+    /** One short sentence, for a non-specialist: why would you set this? */
+    why: string;
+    /** What happens when the author leaves it out, where the default value alone does not say. */
+    whenOmitted?: string;
+    /** The effect does nothing useful without it. Documentation only; nothing enforces it. */
+    required?: boolean;
 }
 /**
  * A parameter with a keyword half: either nothing but words (`'keyword'`), or words beside a

package/dist/types/effects/auto-motion.d.ts

@@ -0,0 +1,169 @@
+import type { PrepareContext } from '../core/effect-context.js';
+import type { Cleanup, EffectParams, ParamSpec } from '../core/types.js';
+import type { ControlGroup } from './step-index.js';
+/**
+ * A deck that moves on its own: continuous `spin:` and stepped `autoplay:`.
+ *
+ * Shared by every deck in the library — the spatial ones (`carousel/deck.ts`) and the flat
+ * `carousel`/`step-progress` index (`forms/primitives.ts`). It lived in `carousel/` while only the
+ * spatial decks had motion; it moved here, beside `step-index.ts` and `swipe-event.ts`, when the
+ * flat deck gained `autoplay:`, because a second copy of the pause rules below is exactly the drift
+ * this module exists to prevent. Nothing in it knows about positions or shapes: the deck hands in
+ * how to `step` (and, for a spatial deck, how to `advance` by a fraction).
+ *
+ * Both are the same question asked at two grains — "when nobody is touching the deck, where does it
+ * go next?" — and both have to answer the same four follow-ups identically, which is why they share
+ * one scheduler rather than each growing its own: when to stop (hover, keyboard focus, a hidden tab,
+ * offscreen, reduced motion, the author's pause control), how to yield to a person (a drag or a
+ * control press takes over, then the motion resumes from wherever the deck was left), how to hand
+ * the transition back and forth (a frame-driven spin must not also be eased), and how to tear down.
+ *
+ * ## Why `requestAnimationFrame` writing the deck's own position, and not a CSS animation
+ *
+ * The obvious CSS answer — register `--kui-step-position` with `@property` and run an infinite
+ * linear `@keyframes` over it — fails the one requirement that matters most here: a drag, a click
+ * and the spin must all move *one* number. A CSS animation owns its value; the drag would have to
+ * read the animated position back out of `getComputedStyle` at `pointerdown`, cancel the animation,
+ * drive the deck from JavaScript, and then restart the keyframe at a negative `animation-delay`
+ * computed to land on wherever the release settled. That is two sources of truth reconciled by
+ * arithmetic on every hand-off, and the "no snap-back when spin resumes" requirement is precisely
+ * the bug that reconciliation produces when it is off by one frame.
+ *
+ * Writing the continuous `position` the deck already has (the same number the drag moves and the
+ * controls set) makes the hand-off free: pausing is "stop adding to it", resuming is "start adding
+ * to it again", and a drag in between simply moved it. It costs nothing the CSS route would have
+ * saved — an animated custom property is recomputed on the main thread either way, because the
+ * geometry reading it is a `calc()` the compositor cannot run.
+ *
+ * `autoplay:` does not need frames at all: it is a timer that presses "next", and the stylesheet's
+ * own transition does the travel, exactly as it does for a click. Same model as
+ * `showcase/slideshow.ts`'s `autoplay:`, whose pause rules this mirrors.
+ */
+/**
+ * The shortest period either kind of motion may be set to, in milliseconds.
+ *
+ * The same floor `slideshow`'s `autoplay:` has and for the same reason: below it, content moves
+ * faster than it can be read, and a whole ring turning in under two seconds is a strobe rather than
+ * a carousel. Clamped with a warning rather than refused, so a typo still produces a working deck.
+ */
+export declare const MIN_PERIOD_MS = 2000;
+/**
+ * The longest frame a spin will integrate over, in milliseconds.
+ *
+ * A dropped frame or a debugger pause otherwise arrives as one enormous `dt` and the ring leaps.
+ * Capping it turns a hitch into a brief slow-down, which is the less surprising failure. Resuming
+ * from a pause never relies on this — the first frame after a resume only records its timestamp.
+ */
+export declare const MAX_FRAME_MS = 100;
+/**
+ * An authored signed period, floored to {@link MIN_PERIOD_MS} in magnitude.
+ *
+ * Pure and exported so the clamp and the sign rule are assertable without a clock. `0` means off
+ * and stays `0`; the sign is the direction and survives the clamp.
+ *
+ * @param ms - Authored period in milliseconds; negative runs backwards.
+ * @returns The period to run at, or `0` for off.
+ * @complexity O(1) time and space.
+ */
+export declare function clampPeriod(ms: number): number;
+/**
+ * How far one frame advances the deck, in whole cycles of it.
+ *
+ * A cycle is every slide passing once — one revolution of a full ring. Expressed in cycles rather
+ * than places so the rate an author writes (`spin:40s`) is independent of how many slides there
+ * are: adding a card to a 40-second ring keeps it a 40-second ring rather than slowing each card.
+ *
+ * @param dtMs - Milliseconds since the previous frame, before capping.
+ * @param periodMs - Signed milliseconds per cycle; non-zero.
+ * @complexity O(1) time and space.
+ */
+export declare function cyclesFor(dtMs: number, periodMs: number): number;
+export interface AutoMotionRequest {
+    el: Element;
+    ctx: PrepareContext;
+    /** Signed milliseconds per full cycle of continuous spin, already clamped; `0` is off. */
+    spinMs: number;
+    /** Signed milliseconds between autoplay steps, already clamped; `0` is off. */
+    autoplayMs: number;
+    /** How long a manual move takes to settle, so the motion does not resume mid-transition. */
+    settleMs: number;
+    /** Whether the pointer resting on the deck pauses it. Omitted, it does. See `HOVER_PARAM`. */
+    pauseOnHover?: boolean;
+    /**
+     * Move the deck on by a (signed) fraction of a full cycle. Absent on a deck that cannot spin; such
+     * a deck always has `spinMs` 0 (`motionPeriods`), so nothing ever calls it.
+     */
+    advance?(cycles: number): void;
+    /** Step the deck one place. */
+    step(direction: 1 | -1): void;
+    /**
+     * Publish whether frames, rather than the stylesheet's transition, are driving the deck. Absent,
+     * and never called, on a deck that cannot spin — see `advance`.
+     */
+    setSpinning?(spinning: boolean): void;
+    /** Called whenever the author-facing paused state changes, to mirror it onto pause controls. */
+    onPausedChange(paused: boolean): void;
+}
+export interface AutoMotion {
+    /** Whether any motion was configured at all. */
+    readonly enabled: boolean;
+    /** A person moved the deck: hand the transition back and hold off for one settle period. */
+    interrupt(): void;
+    /** A gesture is (or is no longer) in progress; nothing moves on its own while one is. */
+    hold(holding: boolean): void;
+    /** The author's pause control was pressed. */
+    toggle(): void;
+    release: Cleanup;
+}
+/**
+ * Start the deck's own motion and return the handle its manual inputs talk to.
+ *
+ * @returns A controller; `enabled` is false (and every method inert) when neither motion was set.
+ * @complexity O(1) per event and per frame; O(1) space.
+ */
+export declare function createAutoMotion(request: AutoMotionRequest): AutoMotion;
+export declare const AUTOPLAY_PARAM: ParamSpec;
+export declare const PAUSE_PARAM: ParamSpec;
+export declare const HOVER_PARAM: ParamSpec;
+/** What {@link createDeckMotion} needs from a deck. */
+export interface DeckMotionRequest {
+    el: Element;
+    ctx: PrepareContext;
+    params: EffectParams;
+    /** Prefix for warnings, the word an author would recognise. */
+    label: string;
+    /** How long a manual move takes to settle, so the motion does not resume mid-transition. */
+    settleMs: number;
+    /** Step the deck one place. */
+    step(direction: 1 | -1): void;
+    /**
+     * The continuous half, for a deck that has a continuous position to spin (`spin:`). Omitted, the
+     * deck has no `spin:` parameter and only `autoplay:` is read.
+     */
+    spin?: Pick<AutoMotionRequest, 'advance' | 'setSpinning'>;
+}
+/** What {@link createDeckMotion} returns. */
+export interface DeckMotion {
+    /** The motion handle the deck's manual inputs talk to (`interrupt`, `hold`). */
+    motion: AutoMotion;
+    /**
+     * The `pause:` control as a group for the deck's own delegated listener, or `null` when none was
+     * named or there is nothing to pause. Bound by the deck, so a press on it goes through the same
+     * one listener — and the same inside-first search (`core/target.ts`'s `queryControls`) — as its
+     * arrows and dots. A pause button in a band header outside the ring needs no `scope:`.
+     */
+    pause: ControlGroup | null;
+    release: Cleanup;
+}
+/**
+ * A deck's `autoplay:` (and, for a spatial deck, `spin:`) with its `pause:` control: the periods,
+ * the floor and its warning, the scheduler, and the `aria-pressed` the control carries.
+ *
+ * The deck-facing half of {@link createAutoMotion}, so the spatial decks and the flat `carousel`
+ * read the same parameters, warn the same way and reflect pause the same way — the only things a
+ * deck supplies are how it steps and, if it spins, how it advances.
+ *
+ * @complexity O(1) at setup plus one scoped query for a named `pause:`; O(m) per pause toggle in the
+ *   matched controls.
+ */
+export declare function createDeckMotion(request: DeckMotionRequest): DeckMotion;

package/dist/types/effects/carousel/deck.d.ts

@@ -0,0 +1,170 @@
+import type { Cleanup, EffectParams, ParameterSchema } from '../../core/types.js';
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { StyleLedger } from '../../core/owned-styles.js';
+/**
+ * The spatial deck: the index, the continuous position, the controls, the grab and the auto-motion
+ * that every carousel in this folder shares, whatever shape it lays its slides out in.
+ *
+ * Extracted from what was `prepareSpatialRing` when a second shape arrived. The ring (`index.ts`)
+ * and the depth stack (`stack.ts`) differ in exactly two things — the stylesheet that turns
+ * `--kui-offset` and `--kui-step-position` into places, and which slots count as presented to the
+ * viewer — and agree on everything else: one real-valued position both a drag and a click move,
+ * the integer step derived from it, the marking, `next:`/`prev:`/`jump:`/`pause:`, the keyboard,
+ * `spin:` and `autoplay:`. Two primitives each owning a copy of that would be two answers to "where
+ * is the deck" that could drift apart, which is the bug this file's single `position` exists to
+ * make impossible. So the shape is a {@link DeckLayout} handed in, and the rest lives here once.
+ */
+/** Attribute this module owns on the host while a pointer is dragging the deck. */
+export declare const DRAGGING_ATTR = "data-kui-ring-dragging";
+/**
+ * The composition channels for what {@link prepareSpatialDeck} writes on the host, whichever
+ * layout it is handed: the children it takes as cards, the step index, the drag flag, and the
+ * `tabindex` the drag grants a host that had none. Each spatial primitive spreads this beside its
+ * own geometry's channels, so a second writer of any of them is refused rather than overwritten.
+ */
+export declare const SPATIAL_DECK_CHANNELS: readonly string[];
+/**
+ * Attribute this module owns on the host while frames — not the stylesheet — are moving the deck.
+ *
+ * The CSS transition that eases a click from one place to the next is exactly wrong under a spin:
+ * each frame retargets it, so the deck trails its own position by the transition's length and
+ * visibly accelerates out of every pause. Same reason, same fix, as {@link DRAGGING_ATTR}: while it
+ * is `true` the stylesheet suspends the transition, and the moment a person takes over it comes
+ * back, so their click still travels.
+ */
+export declare const SPINNING_ATTR = "data-kui-ring-spinning";
+/**
+ * Attribute this module owns on each slot: whether the layout currently presents it to the viewer.
+ *
+ * A published fact rather than a CSS derivation, because it is a branch on the sign or magnitude of
+ * a `calc()`, which CSS cannot take. The ring answers it with "is this slot's plane turned more
+ * than a quarter turn away" (`faceAt`); the stack with "has it left the visible depth". The
+ * stylesheet hangs `pointer-events` on it for every shape, and `visibility` where a hidden slot
+ * must also leave the tab order.
+ *
+ * That matters for more than tidiness. A card turned away from the viewer still occupies its
+ * projected screen rectangle for hit-testing purposes — `backface-visibility: hidden` stops it
+ * *painting* but is not reliably a hit-testing rule, WebKit in particular — so the back of a ring
+ * swallows clicks meant for the front of it. Publishing the fact is what lets one stylesheet rule
+ * fix that at any deck size.
+ */
+export declare const FACE_ATTR = "data-kui-ring-face";
+export type Face = 'front' | 'back';
+/**
+ * Attribute this module sets on a slot for exactly one style resolution, when its offset wrapped.
+ *
+ * `--kui-offset` is circular, so on every step one slot is re-numbered from one end of the deck to
+ * the other: on a full ring its angle jumps by a whole turn (`-180deg` to `+180deg`) while its place
+ * on screen does not move at all. A transition interpolates the number, not the place, so that card
+ * would sweep the long way round, across the front of every other card, on every click. The flag
+ * suspends its transition (`carousel.css`), the style is resolved once with it present so the jump
+ * is committed without a transition, and the flag is removed in the same task — nothing ever sees
+ * it, and the next change to that slot transitions normally.
+ */
+export declare const WRAP_ATTR = "data-kui-ring-wrap";
+/**
+ * Which way a deck's cards travel across the screen as its position grows, as the sign a drag's
+ * pixels are multiplied by: `1` when the next card sits to the right of the live one (so advancing
+ * pulls the cards left, and a leftward drag advances), `-1` when it sits to the left.
+ *
+ * Read off the rendered geometry rather than off a name or a parameter, because no one parameter
+ * owns it. Outside a ring (`translateZ(+r)`) the next card is on the right; from the centre of one
+ * (`carousel-3d-inside`, `translateZ(-r)`) the same angle puts it on the left, and a drag that
+ * ignored that moved the cards against the finger. A flat ring's next card is clockwise of twelve,
+ * so right; a stack's is wherever `shift:` steps it. The one rule that is right for all of them is
+ * "the card under the pointer follows the pointer", and that is a question about where the cards
+ * are on screen.
+ *
+ * Pure and exported so the rule is assertable without a layout engine. `null` for a side that has
+ * no card (a one-card deck) and a tie (a realm with no layout, where every box is at 0) both answer
+ * `1`, the outside ring's long-standing direction.
+ *
+ * @param liveX - Screen x of the live card's centre.
+ * @param nextX - Screen x of the next card's centre, or `null` if there is none.
+ * @param previousX - Screen x of the previous card's centre, consulted only without a next card.
+ * @complexity O(1) time and space.
+ */
+export declare function travelSign(liveX: number, nextX: number | null, previousX: number | null): 1 | -1;
+/**
+ * Whether a slot's offset moved further than any real step can: it wrapped round the deck.
+ *
+ * A step moves every offset by one place (a jump by at most half the deck, because offsets are
+ * circular); only a re-numbering from one end to the other moves one by more than half. Pure and
+ * exported so the threshold is assertable without a DOM.
+ *
+ * @complexity O(1) time and space.
+ */
+export declare function offsetWrapped(previous: number, next: number, count: number): boolean;
+/**
+ * Where the deck's continuous position rounds to, and how far past it the deck currently sits.
+ *
+ * The pair the stylesheet needs and the reason both tokens are published rather than one: the
+ * integer decides which slot is *live* (and therefore what `--kui-offset` means for every other
+ * slot), and the remainder is the sub-step motion on top of it. Re-snapping the integer whenever
+ * the remainder passes a half step is what keeps the remainder inside ±0.5, so the deck never has
+ * to travel back across the whole strip to wrap from the last slide to the first — the same
+ * property `circularOffset` gives the discrete case.
+ *
+ * @param position - Continuous position, in places. May be negative or beyond the count.
+ * @param total - How many places the deck has.
+ * @returns The live integer step, wrapped into range, and the signed remainder in `[-0.5, 0.5)`.
+ * @complexity O(1) time and space.
+ */
+export declare function snapPosition(position: number, total: number): {
+    step: number;
+    drift: number;
+};
+/**
+ * The parameters every spatial deck takes, whatever its shape.
+ *
+ * Spread into each primitive's schema so the controls, the grab and the motion are spelled — and
+ * documented — once.
+ */
+export declare const DECK_PARAMETERS: ParameterSchema;
+/** What a deck's shape contributes; everything else is shared. */
+export interface DeckLayout {
+    /** The primitive's id: names the mirrored timing properties (`--kui-<id>-duration`). */
+    id: string;
+    /** Prefix for warnings, the word an author would recognise. */
+    label: string;
+    /** Whether a slot at this place is presented to the viewer. `place` is `offset - drift`. */
+    faceOf(place: number, offset: number, count: number): Face;
+    /**
+     * The shape's own reading of a circular offset, when it is not the offset itself.
+     *
+     * Only used to spot a wrap ({@link WRAP_ATTR}): a slot wraps where *its shape's* numbering jumps,
+     * which for a ring is at the circular seam and for a stack is between "just left" and "at the
+     * back". Omitted means the circular offset is the shape's numbering.
+     */
+    placeOf?(offset: number, count: number): number;
+    /** Whether to publish the first slot's measured size for a stylesheet that derives from it. */
+    measure: boolean;
+    /** Attributes the shape publishes on the host, so its selectors can branch on parameters. */
+    hostAttributes?: Record<string, string>;
+    /**
+     * Anything else the shape keeps current on the host, handed the deck's own host style ledger.
+     *
+     * The ledger rather than a second one of the shape's own: a second ledger over the host would
+     * snapshot the deck's writes as the author's and "restore" to them (`LedgerSet` in
+     * `core/owned-styles.ts`). `render` runs after every full render — never per spin frame — with
+     * the slides it rendered; `release` runs before the host's styles are given back.
+     */
+    attach?(styles: StyleLedger): DeckAttachment;
+}
+/** What {@link DeckLayout.attach} returns. */
+export interface DeckAttachment {
+    render(nodes: readonly Element[], count: number): void;
+    release: Cleanup;
+}
+/**
+ * Drive a deck of slides from one continuous position.
+ *
+ * Reuses `step-progress`'s marking, counting and control delegation wholesale — the index half of a
+ * carousel is the same problem whether the slides sit in a row, on a ring or in a stack, and
+ * `createStepMarker` was extracted precisely so a second consumer would not re-derive it. What is
+ * new here is the continuous position, the measurement, the face marking, the grab and the motion.
+ *
+ * @complexity O(n) per flip and per drag frame in the slot count; O(n) per spin frame for the face
+ *   marks only; O(n) space in slots ever touched.
+ */
+export declare function prepareSpatialDeck(el: Element, params: EffectParams, ctx: PrepareContext, layout: DeckLayout): Cleanup;

package/dist/types/effects/carousel/drag.d.ts

@@ -11,6 +11,12 @@ export interface RingDragRequest {
     total(): number;
     /** The ring's current continuous position, in places. */
     positionOf(): number;
+    /**
+     * Which way the cards travel on screen as the position grows (`deck.ts`'s `travelSign`): `1` when
+     * a leftward drag advances, `-1` when a rightward one does. Asked once per drag, at its start, so
+     * the card under the pointer follows it whatever the shape.
+     */
+    travelSign(): 1 | -1;
     /** Move the ring to a continuous position and re-render. */
     moveTo(position: number): void;
     /** Publish or clear the dragging state the stylesheet suspends its transition on. */

package/dist/types/effects/carousel/fit.d.ts

@@ -0,0 +1,130 @@
+import type { Cleanup } from '../../core/types.js';
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { StyleLedger } from '../../core/owned-styles.js';
+/**
+ * The largest radius at which a depth ring still fits the page it is on.
+ *
+ * A depth ring's radius is derived from its cards (or authored) and knows nothing about the width
+ * it got, so on a phone its edge cards project hundreds of pixels past the screen and push the page
+ * sideways. This file finds the radius at which that stops happening, and `carousel.css` uses
+ * `min(wanted, fit)`: a ring that already fits — every desktop ring — is untouched to the pixel,
+ * and only a ring that would overflow is pulled in, exactly as far as it has to be.
+ *
+ * ## Why a solver in JavaScript and not a formula in the stylesheet
+ *
+ * The first attempt was CSS: a size container on the host and one closed-form bound,
+ * `R = D * cos(atan2(D, P))`, with `D` the host's half-width less half a card. It was correct and
+ * far too cautious, because a closed form has to assume the worst case: a card at *any* angle, seen
+ * from the side, at full width. Real rings reach much less than that. A 180-degree inside slice
+ * never shows a card past a quarter turn; a card at the silhouette is turned nearly edge-on; the
+ * tilt, the facing and the perspective all move where a card's corners land. The bound shrank the
+ * showcase's rows at 1440px from radius 805 to 500 — rings that were not overflowing anything.
+ *
+ * The exact answer is a maximum over the angles the ring can actually reach, of where each card's
+ * *corners* project under the ring's own perspective, tilt and facing — and a stylesheet cannot
+ * take a maximum over a continuous range. It also needs two facts CSS cannot see at all: where the
+ * host sits on the page (a ring off-centre has less room on one side), and whether anything
+ * between it and the page already clips it. So the geometry is solved here, once per resize, and
+ * published as one length (`--kui-ring-fit`) the stylesheet spends.
+ *
+ * The size container went with the formula. It had a side effect the solver does not: a host sized
+ * by its content (a flex or grid item with no width) took its container's width instead. Nothing
+ * here changes how any host is sized — the solver measures the page and writes one custom property.
+ *
+ * ## What counts as "the page"
+ *
+ * The nearest ancestor that contains horizontal overflow decides, walking up to (not including)
+ * `<body>`:
+ *
+ * - `overflow-x: clip` or `hidden` — the author has already decided what happens past that edge:
+ *   the ring bleeds and is cut, which is a composition (the showcase's rows run off both sides of
+ *   their band on purpose). Nothing is fitted; the ring keeps the radius it asked for.
+ * - `auto` or `scroll` — overflow would scroll that box sideways, so the ring fits its padding box.
+ * - none — the ring fits the page's own width, `0..clientWidth` in document coordinates.
+ *
+ * `<html>` and `<body>` are skipped because a page-level `overflow-x: hidden` is on a large fraction of all sites as a blanket guard, not a
+ * statement that this ring should be cut off at the screen edge.
+ *
+ * ## Which cards count
+ *
+ * Every card on the reachable arc, as it moves: a card sits within half a place of its offset
+ * while it is dragged or spun, so the reachable angles are the offsets' range widened by half a
+ * spacing each side — the whole circle for a full ring. On an *inside* ring a card at or past a
+ * quarter turn is `visibility: hidden` (`carousel.css`), so only the front half counts. On an
+ * outside ring every angle counts: the far half is content there, and its cards sit further from
+ * the camera than the near half's, so they never set the width anyway.
+ */
+/** Custom property this module owns on the ring host. */
+export declare const RING_FIT_PROPERTY = "--kui-ring-fit";
+/** Everything the projection needs, in pixels and degrees. */
+export interface RingFitGeometry {
+    /** A card's laid-out size. */
+    width: number;
+    height: number;
+    /** The host's `perspective`; `Infinity` for `none`. */
+    perspective: number;
+    /** The `rotateX` every slot is placed under — the stylesheet's `--kui-ring-tilt`, not the param. */
+    tiltDeg: number;
+    /** Whether cards sit behind the host's plane (`carousel-3d-inside`). */
+    inside: boolean;
+    /** Whether each card is counter-rotated to face the viewer. */
+    facing: 'radial' | 'camera';
+    /** The reachable ring angles (see {@link reachableAngles}). */
+    fromDeg: number;
+    toDeg: number;
+    /** The slot centre's horizontal distance from the perspective origin. */
+    originOffset: number;
+    /** The page's edges, as horizontal distances from the perspective origin (min < 0 < max). */
+    minX: number;
+    maxX: number;
+}
+/**
+ * The ring angles a card can occupy, in the stylesheet's own terms.
+ *
+ * `carousel.css` places a slot at `(offset - drift) * arc / count`. Offsets are circular, from
+ * `floor(count/2) - count + 1` to `floor(count/2)` (`circularOffset`), and the drift stays within
+ * half a place either way (`snapPosition`), so the union over every card and every moment is that
+ * range widened by half a spacing each side. A full ring reaches the whole circle.
+ *
+ * @complexity O(1) time and space.
+ */
+export declare function reachableAngles(arcDeg: number, count: number): {
+    fromDeg: number;
+    toDeg: number;
+};
+/**
+ * The largest radius at which the ring fits, or `Infinity` when every radius does.
+ *
+ * Bisection, because the extent grows with the radius: every card moves outward along its own
+ * direction, and the perspective only magnifies that on the near side and shrinks it less than
+ * linearly on the far side. Floored to a hundredth of a pixel so rounding never lands outside.
+ *
+ * @complexity O(s * k) — samples of the arc times {@link SEARCH_STEPS}; runs on resize, never per
+ *   frame.
+ */
+export declare function solveRingFit(g: RingFitGeometry): number;
+/** The box a ring has to fit, in viewport coordinates, or `null` when an ancestor clips it. */
+export declare function fitBounds(el: Element, win: Window): {
+    left: number;
+    right: number;
+} | null;
+/** What the ring tells the fit that the page cannot: its parameters. */
+export interface RingFitOptions {
+    el: Element;
+    ctx: PrepareContext;
+    styles: StyleLedger;
+    arcDeg: number;
+    /** The `tilt:` parameter in degrees, before the stylesheet's negation and clamp. */
+    tiltParamDeg: number;
+    facing: 'radial' | 'camera';
+}
+/**
+ * Keep a depth ring's `--kui-ring-fit` current: at every full render whose cards changed, and on
+ * every resize of the host or the page (coalesced to one solve per frame).
+ *
+ * @complexity O(s * k) per solve (see {@link solveRingFit}); O(1) space.
+ */
+export declare function createRingFit(options: RingFitOptions): {
+    render(nodes: readonly Element[], count: number): void;
+    release: Cleanup;
+};

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

@@ -1,5 +1,6 @@
 import type { Preset, Primitive } from '../../core/types.js';
 import type { Registry } from '../../core/registry.js';
+export { snapPosition } from './deck.js';
 /**
  * Whether a slot at this ring angle has its own plane turned away from the camera.
  *
@@ -24,25 +25,6 @@ export declare function faceAt(angleDeg: number): 'front' | 'back';
  * @complexity O(1) time and space.
  */
 export declare function normaliseDegrees(angleDeg: number): number;
-/**
- * Where the ring's continuous position rounds to, and how far past it the ring currently sits.
- *
- * The pair the stylesheet needs and the reason both tokens are published rather than one: the
- * integer decides which slot is *live* (and therefore what `--kui-offset` means for every other
- * slot), and the remainder is the sub-step rotation on top of it. Re-snapping the integer whenever
- * the remainder passes a half step is what keeps the remainder inside ±0.5, so the ring never has
- * to travel back across the whole strip to wrap from the last slide to the first — the same
- * property `circularOffset` gives the discrete case.
- *
- * @param position - Continuous ring position, in places. May be negative or beyond the count.
- * @param total - How many places the ring has.
- * @returns The live integer step, wrapped into range, and the signed remainder in `[-0.5, 0.5)`.
- * @complexity O(1) time and space.
- */
-export declare function snapPosition(position: number, total: number): {
-    step: number;
-    drift: number;
-};
 /**
  * An authored `<angle>` as a number of degrees.
  *
@@ -65,8 +47,9 @@ export declare function degreesOf(value: string, fallbackDeg: number): number;
 /**
  * The ring primitive.
  *
- * `renderer: 'javascript'` and two channels together are the honest declaration: this file paints
- * nothing itself — it publishes numbers — but `carousel.css` does, and both of the things it writes
+ * `renderer: 'javascript'` and its channels together are the honest declaration: this file paints
+ * nothing itself — it publishes numbers (and the `data-kui-step` index, its third channel) — but
+ * `carousel.css` does, and both of the things that stylesheet writes
  * have to be declared or the conflict detector waves through a composition that silently loses one
  * effect's output.
  *
@@ -116,7 +99,7 @@ export declare const CAROUSEL_PRIMITIVES: Primitive[];
  *
  * `phase: 'idle'` on all of them too, and for the same reason `target` does not change the answer:
  * `channelsFor`/`findConflicts` (`core/channels.ts`) reason about the channels *this preset
- * declares* on the host it is authored on (`CHANNEL.skew` and `'discrete'`, from
+ * declares* on the host it is authored on (`CHANNEL.skew`, `'discrete'` and `data-kui-step`, from
  * `SPATIAL_RING_PRIMITIVE`), not about which element in the subtree physically paints them — the
  * compiler has no notion of "the primitive's own target moved the real work three nodes down," and
  * does not need one here, because `requiresOwnSubtree` already keeps this preset off of anything
@@ -135,8 +118,15 @@ export declare const CAROUSEL_PRIMITIVES: Primitive[];
  * over the `transform` shorthand (`CHANNEL.skew`) for the ring's whole lifetime, and there is no
  * turn-taking to model. It replaces "nothing is known" with the actual, checked fact.
  *
- * None of the four declares `transitions`: nothing here renders through a CSS `transition:` on the
+ * None of them declares `transitions`: nothing here renders through a CSS `transition:` on the
  * host box for `phaseOf` to derive `state` from — the ring is `renderer: 'javascript'` throughout.
+ *
+ * All of them are `cloak: true`. Before the script runs, a ring is its cards laid out flat in the
+ * page's flow, and the first frame after start snaps them onto the ring: a flash of the wrong
+ * layout on every load (the showcase hero showed it). Under `<html data-kui-cloak>` the host and its
+ * cards stay hidden until the host's `data-kui-state` lands, which happens in the same task that
+ * places the cards (no frame or timer in between), and the CSS-only two-second release still shows
+ * them if the script never runs.
  */
 export declare const CAROUSEL_PRESETS: Preset[];
 /**