kuinetic 0.1.0

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

@@ -0,0 +1,55 @@
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { ScrollFrame } from '../../core/scroll-scheduler.js';
+import type { Cleanup } from '../../core/types.js';
+/**
+ * Progress tracking — the single mechanism every scroll-mechanics effect is built on.
+ *
+ * Pinning, scrollytelling, horizontal scroll, and media scrubbing differ only in what they *do*
+ * with a number between 0 and 1. Computing that number once, in one place, is what keeps the whole
+ * category to one listener, one rAF, and one measurement per resize.
+ *
+ * Geometry is read through an injected measurer: jsdom reports zeroes for every rect, so a tracker
+ * that called `getBoundingClientRect` directly could not be tested at all.
+ */
+export interface ElementGeometry {
+    /** Distance from the scrollport's top edge to the element's top edge. Negative once past it. */
+    top: number;
+    height: number;
+}
+export type Measurer = (el: Element) => ElementGeometry;
+export declare const domGeometry: Measurer;
+export interface TrackOptions {
+    /**
+     * Scroll distance the effect spans, as an authored CSS length. Defaults to the element's own
+     * height, which is what makes `pin-section` behave sensibly with no configuration.
+     */
+    distance?: string;
+    measure?: Measurer;
+}
+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.
+ *
+ * @param el - Element whose position drives progress.
+ * @param ctx - Prepare context supplying the scheduler and root resolver.
+ * @param options - Distance and an optional injected measurer.
+ * @param onProgress - Called once per scheduled frame.
+ * @returns Teardown that unsubscribes from the scheduler.
+ * @complexity O(1) per frame after the first measurement of each epoch; O(1) space.
+ * @overallScore 100
+ */
+export declare function trackProgress(el: Element, ctx: PrepareContext, options: TrackOptions, onProgress: ProgressHandler): Cleanup;
+/**
+ * Progress from the element's offset and the span it travels.
+ *
+ * @param top - Element top relative to the scrollport; negative once scrolled past.
+ * @param span - Pixels of scrolling the effect covers.
+ * @returns Progress in [0, 1]; 0 for a non-positive span.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function progressFrom(top: number, span: number): number;

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

@@ -0,0 +1,26 @@
+import type { Activation, ParameterSchema, Primitive, ReducedMotionPolicy, Timeline } from '../core/types.js';
+export interface CssPrimitiveOptions {
+    parameters?: ParameterSchema;
+    timelines?: Timeline[];
+    activations?: Activation[];
+    defaultActivation?: Activation;
+    reducedMotion?: ReducedMotionPolicy;
+    perfClass?: Primitive['perfClass'];
+}
+/**
+ * Build the metadata shared by every CSS-keyframe-rendered primitive.
+ *
+ * The one factory for "a CSS-keyframes `Primitive` with the shared timing defaults
+ * (`duration`/`delay`/`ease`/`stagger`), `renderer: 'css-keyframes'`, and a default
+ * activation/perfClass/reducedMotion policy" — every category under `effects/` that renders
+ * with CSS keyframes builds its primitives through this, so a change to a shared default only
+ * has one call site to update.
+ *
+ * @param id - Stable primitive identifier.
+ * @param channels - CSS property groups owned by the primitive.
+ * @param options - Optional schema and lifecycle overrides.
+ * @returns A CSS-keyframe primitive ready for registry registration.
+ * @complexity O(p) time and space in parameter count.
+ * @overallScore 100
+ */
+export declare function cssPrimitive(id: string, channels: string[], options?: CssPrimitiveOptions): Primitive;

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

@@ -0,0 +1,13 @@
+import type { Registry } from '../../core/registry.js';
+import type { Preset, Primitive } from '../../core/types.js';
+export declare const SVG_PRIMITIVES: Primitive[];
+export declare const SVG_PRESETS: Preset[];
+/**
+ * Register the SVG morph catalog.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in the number of primitives and presets.
+ * @overallScore 100
+ */
+export declare function registerSvg(registry: Registry): Registry;

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

@@ -0,0 +1,20 @@
+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[];
+/**
+ * Register the 3D and page-transition catalog.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in the number of primitives and presets.
+ * @overallScore 100
+ */
+export declare function registerThreeD(registry: Registry): Registry;

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+import { Animator } from './core/animator.js';
+import type { AnimatorOptions } from './core/animator.js';
+export * from './core/index.js';
+export { COMBOS, PRESETS, PRIMITIVES, createRegistry } from './effects/index.js';
+/**
+ * Create an animator with the bundled effect catalog registered.
+ *
+ * Importing this module has no side effects — nothing is scanned and the document is not
+ * touched until `.start()` is called. That keeps SSR, hydration, and tests deterministic.
+ *
+ *   import { kuinetic } from 'kuinetic'
+ *   import 'kuinetic/css'
+ *   kuinetic({ observe: true }).start()
+ */
+export declare function kuinetic(options?: AnimatorOptions): Animator;
+export default kuinetic;

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "kuinetic",
+  "version": "0.1.0",
+  "description": "Declarative web animation from HTML attributes. Native CSS where possible, JS only where necessary.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/esm/index.mjs",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "dist/kuinetic.js",
+  "jsdelivr": "dist/kuinetic.js",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/esm/index.mjs"
+    },
+    "./core": {
+      "types": "./dist/types/core/index.d.ts",
+      "default": "./dist/esm/core/index.mjs"
+    },
+    "./effects": {
+      "types": "./dist/types/effects/index.d.ts",
+      "default": "./dist/esm/effects/index.mjs"
+    },
+    "./css": "./dist/kuinetic.css",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test scripts",
+    "lint:deps": "depcruise src --config .dependency-cruiser.cjs",
+    "lint:dead": "knip",
+    "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",
+    "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",
+    "verify:standalone": "npm run build:dist && node scripts/verify-standalone.mjs",
+    "verify:pack": "npm run build:dist && node scripts/verify-pack.mjs",
+    "clean:dist": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepack": "npm run build:dist",
+    "prepublishOnly": "node -e \"if (require('./package.json').version === '0.0.0') { console.error('Refusing to publish placeholder version 0.0.0 — bump package.json first.'); process.exit(1) }\"",
+    "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",
+    "generate:css": "node scripts/generate-preset-css.mjs",
+    "record": "npm run build && node scripts/verify-browser.mjs --record",
+    "check:showcase": "npm run build && node scripts/check-showcase.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@size-limit/file": "^13.0.3",
+    "@tailwindcss/cli": "^4.3.3",
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "^2.1.9",
+    "daisyui": "^5.7.16",
+    "dependency-cruiser": "^18.2.0",
+    "esbuild": "^0.21.5",
+    "eslint": "^9.39.5",
+    "eslint-plugin-sonarjs": "^3.0.7",
+    "globals": "^14.0.0",
+    "jsdom": "^25.0.1",
+    "knip": "^6.32.2",
+    "playwright-core": "^1.61.1",
+    "size-limit": "^13.0.3",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.66.0",
+    "vitest": "^2.1.9"
+  }
+}