kuinetic 0.1.2 → 0.1.4

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.

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

@@ -1,4 +1,44 @@
 import type { Activation, ParameterSchema, Primitive, ReducedMotionPolicy, Timeline } from '../core/types.js';
+/**
+ * The one `delay` declaration, spread by every primitive that waits for a trigger before playing.
+ *
+ * Two spellings of an authored delay exist and they arrive by different routes. The positional
+ * one (`count-up 320ms 300ms`) rides alongside the parameter record as `params.timing` — see the
+ * design note in `core/js-effect-preparer.ts` for why timing is deliberately *not* merged into
+ * that record — while the named one (`count-up delay:300ms`) reaches a primitive only if its
+ * schema declares `delay`, and is otherwise dropped by `resolveParams` as an unknown parameter.
+ * So every primitive whose start moment is a trigger has to declare this, and declaring it is
+ * safe precisely because `0ms` is a true no-op: `readEffectParams` pre-fills every declared
+ * parameter, so a non-zero default would be indistinguishable from an authored value.
+ *
+ * Spread (`...TRIGGER_DELAY_PARAM`) rather than retyped so that rationale has one home.
+ * `test/js-effect-timing.test.ts` asserts every `defaultActivation: 'enter'` primitive ends up
+ * with this entry, whichever route it took to get there.
+ */
+export declare const TRIGGER_DELAY_PARAM: ParameterSchema;
+/**
+ * "Accepts every timeline, is driven by none of them."
+ *
+ * A few primitives have no relationship to progress at all: `background-media` paints a backdrop,
+ * and the scroll-mechanics drivers read the scroll position themselves rather than being driven by
+ * an `animation-timeline`. None of them ever reads `Timeline`.
+ *
+ * They still have to *accept* one, because `compile.ts`'s `intersect` narrows a composed element's
+ * timeline support to what every primitive on it supports. Declaring the honest answer — `['time']`,
+ * or nothing — empties that intersection for `data-kui="background-media src:/hero.mp4, parallax"`
+ * with `timeline:view`, `style-plan.ts` then refuses the timeline, and the neighbour's scrub
+ * silently degrades to a one-shot. Nothing is wrong with either effect; the intersection is simply
+ * the wrong question to ask of a primitive that has no opinion.
+ *
+ * So the list stays exhaustive and this name is what makes it truthful. Written out inline it reads
+ * as a claim to support all four — the same lie in four places, each needing its own paragraph to
+ * walk back. Written as `supportedTimelines: TIMELINE_AGNOSTIC` it reads as what it is: an
+ * abstention, not a claim.
+ *
+ * One shared array instance, like `ENTRANCE_TIMELINES` in `catalog/core.ts`. Every consumer
+ * (`intersect`, `warnUnsupportedTimeline`) only reads it.
+ */
+export declare const TIMELINE_AGNOSTIC: Timeline[];
 export interface CssPrimitiveOptions {
     parameters?: ParameterSchema;
     timelines?: Timeline[];

package/dist/types/effects/step-marking.d.ts

@@ -0,0 +1,99 @@
+import type { PrepareContext } from '../core/effect-context.js';
+import type { Cleanup } from '../core/types.js';
+/**
+ * Marking the children of a stepped effect, shared by every primitive that has an index.
+ *
+ * Two primitives publish `data-kui-step` — `scroll-progress` (scroll-driven, backs
+ * `scrollytelling-step`) and `step-progress` (click-driven, forms) — and the attribute alone puts
+ * all the work on the author. Selecting "the child matching the current index" is the one thing CSS
+ * cannot express, so a page had to enumerate it:
+ *
+ * ```css
+ * [data-kui-step='0'] li:nth-child(1),
+ * [data-kui-step='1'] li:nth-child(2),
+ * [data-kui-step='2'] li:nth-child(3),
+ * [data-kui-step='3'] li:nth-child(4) { ... }
+ * ```
+ *
+ * Four selectors for four steps, doubled for every property group, and every one of them wrong the
+ * moment a fifth step is added or an element is inserted above the list. `demo/scroll.html` carried
+ * eight such selectors for one demo.
+ *
+ * Marking the children instead collapses that to `li[data-kui-step-state='active']`, which does not
+ * change when the step count does. Three values rather than a boolean, because a stepper wants
+ * "everything up to here" (`:not([data-kui-step-state='after'])`) as often as it wants the live one.
+ */
+/** The attribute this module owns. Never write it from anywhere else. */
+export declare const STEP_STATE_ATTR = "data-kui-step-state";
+export type StepState = 'before' | 'active' | 'after';
+/**
+ * Classify a selector as unusable, dangerously broad, or fine.
+ *
+ * `matches` against the two roots catches every selector that reaches the whole document — `*`,
+ * `html`, `body` and compounds like `*, a` with one rule and no bespoke parser — while leaving a
+ * deliberately scoped wildcard such as `.spy-nav > *` working, which a syntactic ban on `*` would
+ * not. `matches` throws on invalid syntax exactly as `querySelectorAll` does, so the same call
+ * still answers the validity question.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function selectorBreadth(selector: string, doc: Document): 'invalid' | 'document-wide' | 'ok';
+/**
+ * Resolve a `target:` selector once at setup, rejecting both the unusable and the over-broad.
+ *
+ * Two distinct failures, one warning channel. An invalid selector thrown from inside the shared
+ * scheduler's frame callback would skip every other subscriber on that root, not just this one. An
+ * over-broad one is worse for being silent: `target:*` is perfectly valid syntax, so a syntax-only
+ * check passed it straight through to stamp an attribute onto every element in the document, on
+ * every frame.
+ *
+ * Rejecting rather than silently narrowing is the honest response, because there is no narrower
+ * selector that could be meant. A selector reaching `<html>` or `<body>` is not naming a set of
+ * steps or a nav link, it is naming the page, and guessing which of its thousands of descendants
+ * the author meant would be worse than saying so.
+ *
+ * @param selector - The authored `target:` value; empty is the no-op default, not an error.
+ * @param ctx - Prepare context, for `doc` and the warning channel.
+ * @param effect - Effect name, so the warning says which attribute to go and fix.
+ * @returns The selector, or `''` when it must be ignored.
+ * @complexity O(1) time and space; `matches` walks the selector, not the document.
+ * @overallScore 100
+ */
+export declare function resolveTarget(selector: string, ctx: PrepareContext, effect: string): string;
+/**
+ * A set of step elements plus the ledgers that let their original attributes survive teardown.
+ *
+ * One ledger per element ever written, rather than a bare Set of touched nodes: a Set records
+ * *which* elements were stamped but not *what they held first*, so teardown would remove a
+ * `data-kui-step-state` the consumer had authored themselves. Same reasoning as `scroll-spy`'s
+ * link ledgers and the inline-style ledger they were both modelled on.
+ */
+export interface StepMarker {
+    /** Stamp `before`/`active`/`after` across the tracked elements. Cheap enough to call per flip. */
+    mark(index: number): void;
+    /** Give every touched element back the attribute value it had before this instance existed. */
+    restore: Cleanup;
+}
+/**
+ * Build a marker over the elements a stepped effect drives.
+ *
+ * `resolve` is called per flip rather than once at setup, so a list rendered or reordered after
+ * this element was prepared is still picked up. Flips are rare — the caller is expected to guard on
+ * the index actually changing — while frames are not.
+ *
+ * @param resolve - Produces the current step elements, in document order.
+ * @returns A marker; call `restore` from the primitive's teardown.
+ * @complexity O(n) per `mark` in the number of step elements; O(n) space in elements ever touched.
+ * @overallScore 100
+ */
+export declare function createStepMarker(resolve: () => Iterable<Element>): StepMarker;
+/**
+ * Where one step sits relative to the live one.
+ *
+ * Pure, so the three-way split is assertable without a DOM.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function stepStateFor(position: number, index: number): StepState;

package/dist/types/effects/three-d/index.d.ts

@@ -1,12 +1,5 @@
 import type { Preset, Primitive } from '../../core/types.js';
 import type { Registry } from '../../core/registry.js';
-/**
- * 3D, perspective, and page-transition effects — all CSS-rendered.
- *
- * Nothing here needs JavaScript: the browser interpolates `rotate`, `clip-path`, and `opacity`
- * natively, so these cost a keyframe block and a registry row each. That ratio is the whole
- * architecture, and it is why tripling the catalog does not triple the payload.
- */
 export declare const THREE_D_PRIMITIVES: Primitive[];
 export declare const THREE_D_PRESETS: Preset[];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kuinetic",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Declarative web animation from HTML attributes. Native CSS where possible, JS only where necessary.",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "lint": "eslint src test scripts",
     "lint:deps": "depcruise src --config .dependency-cruiser.cjs",
     "lint:dead": "knip",
+    "ci": "npm run build:dist && npm run typecheck && npm run lint && npm run lint:deps && npm run lint:dead && npm run check:css-coverage && npm run test:coverage && npm run test:browser",
     "size": "npm run build:dist && size-limit",
     "build": "npm run generate:css && esbuild src/index.ts --bundle --format=iife --global-name=kuinetic --outfile=demo/kuinetic.js && esbuild src/css/index.css --bundle --outfile=demo/kuinetic.css && npx @tailwindcss/cli -i demo/tailwind-entry.css -o demo/tailwind.css && node scripts/build-standalone.mjs demo",
     "build:dist": "npm run clean:dist && npm run generate:css && esbuild src/index.ts src/core/index.ts src/effects/index.ts --bundle --format=esm --splitting --outdir=dist/esm --out-extension:.js=.mjs && esbuild src/index.ts --bundle --format=iife --global-name=kuinetic --outfile=dist/kuinetic.js && esbuild src/css/index.css --bundle --outfile=dist/kuinetic.css && tsc -p tsconfig.build.json && node scripts/build-standalone.mjs",
@@ -50,9 +51,13 @@
     "dev": "npm run build && node scripts/dev-server.mjs",
     "verify:browser": "npm run build && node scripts/verify-browser.mjs",
     "test:browser": "npm run build && node scripts/run-browser-tests.mjs",
+    "test:visual": "npm run build && node scripts/visual-regression.mjs",
+    "test:visual:update": "npm run build && node scripts/visual-regression.mjs --update",
     "generate:css": "node scripts/generate-preset-css.mjs",
+    "generate:nav": "node scripts/generate-nav-header.mjs",
     "record": "npm run build && node scripts/verify-browser.mjs --record",
-    "check:showcase": "npm run build && node scripts/check-showcase.mjs"
+    "check:showcase": "npm run build && node scripts/check-showcase.mjs",
+    "check:css-coverage": "npm run build && node scripts/check-css-coverage.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
@@ -68,7 +73,9 @@
     "globals": "^14.0.0",
     "jsdom": "^25.0.1",
     "knip": "^6.32.2",
+    "pixelmatch": "^7.2.0",
     "playwright-core": "^1.61.1",
+    "pngjs": "^7.0.0",
     "size-limit": "^13.0.3",
     "tailwindcss": "^4.3.3",
     "typescript": "^5.9.3",