kuinetic 0.1.2 → 0.1.3

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.3",
   "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",